fluree iceberg

Manage Apache Iceberg table connections.

Subcommands

fluree iceberg map

Map an Iceberg table as a queryable graph source.

Usage

fluree iceberg map <NAME> [OPTIONS]

Arguments

Options

Catalog mode:

REST catalog mode options:

Direct S3 mode options:

R2RML mapping:

Authentication:

S3 overrides:

Other:

Description

Maps an Apache Iceberg table as a graph source that can be queried using SPARQL or JSON-LD queries. The table is accessed read-only; Fluree does not modify the Iceberg table.

An R2RML mapping (--r2rml) is required to define how Iceberg table rows are transformed into RDF triples.

Two catalog modes are supported:

• REST mode (default): Connects to an Iceberg REST catalog (e.g., Apache Polaris) to discover table metadata. Supports vended credentials and warehouse selection.
• Direct S3 mode: Reads table metadata directly from S3 by resolving version-hint.text in the table’s metadata/ directory. No catalog server required. Also reads Google Cloud Storage (--s3-endpoint https://storage.googleapis.com); GCS reads are signed with AWS SigV4 using GCS HMAC interop keys (the standard AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY) — see the Iceberg guide.

Examples

# REST catalog with R2RML mapping
fluree iceberg map airlines \
  --catalog-uri https://polaris.example.com/api/catalog \
  --r2rml mappings/airlines.ttl \
  --auth-bearer $POLARIS_TOKEN

# REST catalog with explicit table and warehouse
fluree iceberg map warehouse-orders \
  --catalog-uri https://polaris.example.com/api/catalog \
  --table sales.orders \
  --r2rml mappings/orders.ttl \
  --auth-bearer $POLARIS_TOKEN \
  --warehouse my-warehouse

# Direct S3 (no catalog server)
fluree iceberg map execution-log \
  --mode direct \
  --table-location s3://my-bucket/warehouse/logs/execution_log \
  --r2rml mappings/execution_log.ttl \
  --s3-region us-east-1

# Direct mode on Google Cloud Storage.
# Set AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY to your GCS HMAC interop keys
# in the server environment (used to SigV4-sign GCS reads).
fluree iceberg map orders \
  --mode direct \
  --table-location s3://my-bucket/warehouse/sales/orders \
  --r2rml mappings/orders.ttl \
  --s3-endpoint https://storage.googleapis.com \
  --s3-region europe-west1 \
  --s3-path-style

# OAuth2 authentication
fluree iceberg map orders \
  --catalog-uri https://polaris.example.com/api/catalog \
  --table sales.orders \
  --r2rml mappings/orders.ttl \
  --oauth2-token-url https://auth.example.com/token \
  --oauth2-client-id my-client \
  --oauth2-client-secret $CLIENT_SECRET

# Create the graph source on a remote Fluree server
fluree iceberg map warehouse-orders \
  --remote origin \
  --catalog-uri https://polaris.example.com/api/catalog \
  --table sales.orders \
  --r2rml mappings/orders.ttl

Output

Mapped Iceberg table as R2RML graph source 'airlines:main'
  Table:       openflights.airlines
  Catalog:     https://polaris.example.com/api/catalog
  R2RML:       mappings/airlines.ttl
  TriplesMaps: 3
  Connection:  verified
  Mapping:     validated

After Mapping

Once mapped, the graph source appears in standard commands:

# Listed alongside ledgers
fluree list

# Inspect configuration
fluree iceberg info warehouse-orders

# Query the graph source directly (single-target): name it as the target, with
# no FROM. The CLI resolves it as a graph source and runs it through the
# R2RML/Iceberg engine. Requires the `iceberg` feature.
fluree query warehouse-orders 'SELECT ?id ?total WHERE { ?o ex:id ?id ; ex:total ?total }'

# Federate into it: a query whose FROM names the source routes to the
# connection-scoped path automatically (or force it with --connection).
fluree query --connection 'SELECT ?id ?total FROM <warehouse-orders:main> WHERE { ?o ex:id ?id ; ex:total ?total }'

# Remove the mapping
fluree drop warehouse-orders --force

Feature Flag

Requires the iceberg feature flag. Without it, the command returns:

error: Iceberg support not compiled. Rebuild with `--features iceberg`.

See Also

• Iceberg / Parquet - Iceberg integration details
• R2RML - R2RML mapping reference
• list - List ledgers and graph sources
• info - Show graph source details
• drop - Remove a graph source

fluree iceberg list

List Iceberg-family graph sources (Iceberg and R2RML types).

Usage

fluree iceberg list [--remote <NAME>]

Examples

# Local
fluree iceberg list

# Remote
fluree iceberg list --remote origin

fluree iceberg info

Show details for an Iceberg-family graph source.

Usage

fluree iceberg info <NAME> [--remote <NAME>]

Examples

# Local
fluree iceberg info warehouse-orders

# Remote
fluree iceberg info warehouse-orders --remote origin

fluree iceberg drop

Drop an Iceberg-family graph source. This command only targets Iceberg/R2RML graph sources; it does not fall back to dropping ledgers of the same name.

Usage

fluree iceberg drop <NAME> --force [--remote <NAME>]

Examples

# Local
fluree iceberg drop warehouse-orders --force

# Remote
fluree iceberg drop warehouse-orders --force --remote origin