fluree iceberg

Manage Apache Iceberg table connections.

Subcommands

Subcommand	Description
`map`	Map an Iceberg table as a graph source
`list`	List Iceberg-family graph sources (`Iceberg` and `R2RML`)
`info`	Show details for an Iceberg-family graph source
`drop`	Drop an Iceberg-family graph source

fluree iceberg map

Map an Iceberg table as a queryable graph source.

Usage

fluree iceberg map <NAME> [OPTIONS]

Arguments

Argument	Description
`<NAME>`	Graph source name (e.g., “warehouse-orders”)

Options

Catalog mode:

Option	Description
`--mode <MODE>`	Catalog mode, case-insensitive: `rest` (default), `direct`, `glue` (AWS Glue Data Catalog), or `s3tables` (AWS S3 Tables)

REST catalog mode options:

Option	Description
`--catalog-uri <URI>`	REST catalog URI (required for rest mode)
`--table <ID>`	Table identifier in `namespace.table` format (required if not specified in R2RML mapping)
`--warehouse <NAME>`	Warehouse (or catalog) name as the REST catalog knows it; the catalog’s own route prefix is looked up from it
`--no-vended-credentials`	Disable vended credentials (enabled by default)

Direct S3 mode options:

Option	Description
`--table-location <URI>`	S3 table location (required for direct mode, e.g., `s3://bucket/warehouse/ns/table`)

AWS Glue / S3 Tables mode options (native AWS SDK; reads S3 with the ambient AWS credential chain — no vended credentials):

Option	Description
`--table <ID>`	Table identifier `namespace.table`; required unless `--r2rml` is given, whose `rr:tableName` entries then name the tables. For `glue`, `namespace` is the Glue database.
`--region <REGION>`	AWS region of the Glue / S3 Tables API. Glue falls back to `--s3-region`, then the AWS SDK’s region chain; S3 Tables defaults to the table bucket ARN’s region and refuses a `--region` that contradicts it. S3 data reads use `--s3-region` when given, else this region. Must be an AWS region code (e.g. `us-east-1`).
`--catalog-id <ID>`	Glue catalog id for cross-account access (`glue` mode; defaults to the caller’s account)
`--table-bucket-arn <ARN>`	S3 Tables table-bucket ARN, `arn:aws:s3tables:<region>:<account>:bucket/<name>` (required for `s3tables` mode; any AWS partition)

R2RML mapping:

Option	Description
`--r2rml <PATH>`	R2RML mapping file (Turtle format, required). Defines how table rows become RDF triples. Table references come from the mapping’s `rr:tableName` entries.
`--r2rml-type <TYPE>`	Mapping media type (e.g., `text/turtle`); inferred from extension if omitted

Authentication:

These options, and --warehouse, configure a REST catalog: any other --mode refuses them rather than ignore them.

Option	Description
`--auth-bearer <TOKEN>`	Bearer token for REST catalog authentication. Stored with the graph source; prefer the option below
`--auth-bearer-env <VAR>`	Environment variable holding the bearer token, read by the process that reads the tables. The token is not stored. With `--remote`, the server must list the variable in `FLUREE_GRAPH_SOURCE_SECRET_ENV_VARS`
`--oauth2-token-url <URL>`	OAuth2 token URL for client credentials auth
`--oauth2-client-id <ID>`	OAuth2 client ID
`--oauth2-client-secret <SECRET>`	OAuth2 client secret. Stored with the graph source; prefer the option below
`--oauth2-client-secret-env <VAR>`	Environment variable holding the OAuth2 client secret; as `--auth-bearer-env`

S3 overrides:

Option	Description
`--s3-region <REGION>`	S3 region override, in every mode (for `glue` / `s3tables`, defaults to the catalog’s region)
`--s3-endpoint <URL>`	S3 endpoint override (e.g. MinIO, LocalStack, or `https://storage.googleapis.com` for Google Cloud Storage)
`--s3-path-style`	Use path-style S3 URLs

Other:

Option	Description
`--remote <NAME>`	Execute against a remote server (by remote name)
`--branch <NAME>`	Branch name (defaults to “main”)
`--model <LEDGER>`	Model ledger (`name:branch`) whose default graph supplies the source’s view policies and class/property hierarchy. Must exist. See Access policy
`--default-allow <BOOL>`	Fallback for governed requests that match no policy; `true` keeps the source readable under authentication without a model (unset: deny)

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.

Four 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.
AWS Glue mode (--mode glue): Looks the table up in the AWS Glue Data Catalog (Glue GetTable) and reads the metadata file its metadata_location parameter names. The Glue database is the namespace; --catalog-id reads another account’s catalog.
AWS S3 Tables mode (--mode s3tables): Resolves the table’s metadata file in an S3 Tables table bucket (--table-bucket-arn) with GetTableMetadataLocation.

Glue and S3 Tables use the ambient AWS credential chain (environment, shared config / AWS_PROFILE / SSO, container or instance role) for the catalog call and the S3 reads; vended credentials are not supported, and the CLI turns them off for these modes. map tests the connection for REST catalogs only: for Glue and S3 Tables it reports Connection: not tested, and catalog errors surface at query time. See Catalog Modes and AWS Credentials.

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

# AWS Glue Data Catalog (ambient AWS credentials; the Glue database is the namespace).
# Add --catalog-id 123456789012 to read another account's catalog.
fluree iceberg map glue-orders \
  --mode glue \
  --region us-east-1 \
  --table sales.orders \
  --r2rml mappings/orders.ttl

# 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`.

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

Fluree DB

fluree iceberg

Subcommands

fluree iceberg map

Usage

Arguments

Options

Description

Examples

Output

After Mapping

Feature Flag

See Also

fluree iceberg list

Usage

Examples

fluree iceberg info

Usage

Examples

fluree iceberg drop

Usage

Examples

Keyboard shortcuts

Fluree DB