Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

fluree sql

Manage SQL graph sources — R2RML mappings over tables reached through a Trino-protocol endpoint (Trino, Starburst, PrestoDB, or a fluree-sql-bridge sidecar). See SQL graph sources.

Subcommands

SubcommandDescription
mapMap tables behind a SQL endpoint as a graph source
listList mapped graph sources (SQL, Iceberg and R2RML)
infoShow details for a mapped graph source
dropDrop a mapped graph source

list, info and drop are shared with fluree iceberg: both commands operate on the same family of mapped sources.

fluree sql map

Usage

fluree sql map <NAME> --endpoint <URL> --r2rml <PATH> [OPTIONS]

Arguments

ArgumentDescription
<NAME>Graph source name (e.g., “orders-db”)

Options

Endpoint:

OptionDescription
--endpoint <URL>Statement endpoint base URL (required), e.g. https://trino.example.com:8443 or http://localhost:8080 for a sidecar
--dialect <NAME>SQL rendering dialect: trino (default), postgres, mysql, sqlite. Use the engine behind a bridge.
--protocol <NAME>Header family: trino (default) or presto
--catalog <NAME>Default catalog for unqualified table names
--schema <NAME>Default schema for unqualified table names
--user <NAME>Protocol user (X-Trino-User); defaults to fluree
--session KEY=VALUESession property (repeatable), e.g. --session query_max_run_time=5m

R2RML mapping:

OptionDescription
--r2rml <PATH>Mapping file (required). Each rr:tableName names a table reachable through the endpoint; rr:sqlQuery is also accepted.
--r2rml-type <TYPE>Mapping media type (e.g., text/turtle); inferred from extension if omitted

Authentication:

OptionDescription
--auth-bearer <TOKEN>Static bearer token. Stored with the graph source; prefer the option below
--auth-bearer-env <VAR>Environment variable holding the bearer token, read by the process that queries the endpoint; the token is not stored. With --remote, the server must list it in FLUREE_GRAPH_SOURCE_SECRET_ENV_VARS
--oauth2-token-url <URL>OAuth2 client-credentials token endpoint
--oauth2-client-id <ID>OAuth2 client ID
--oauth2-client-secret <SECRET>OAuth2 client secret. Stored; prefer the option below
--oauth2-client-secret-env <VAR>Environment variable holding the client secret; as --auth-bearer-env
--oauth2-scope <SCOPE>OAuth2 scope
--oauth2-audience <AUD>OAuth2 audience
--auth-google-metadata, --auth-google-adc, --auth-google-service-account-env <VAR>, --auth-google-wif-config <FILE>, --auth-google-quota-project <PROJECT>, --auth-google-scopes <SCOPES>A Google identity, as for fluree iceberg map

Give one way to authenticate. A bearer token beside OAuth2, two Google sources, and OAuth2 without both --oauth2-token-url and a client secret are refused. With --remote, the CLI sends a bearer token or OAuth2 client credentials as the flat fields and a Google identity as the structured auth. A server older than the structured auth reads the literal flat fields (--auth-bearer, --oauth2-client-secret and the other OAuth2 options), but not the _env forms or a Google identity, which it ignores, registering the source with no auth.

A Google identity’s token goes to the SQL endpoint, but a host identity’s token (the metadata server’s, the host’s application-default credentials, WIF signed with the host’s own AWS identity) is sent only to Google’s APIs (https on googleapis.com) and the hosts the operator lists in FLUREE_GOOGLE_TOKEN_HOSTS. Against an ordinary Trino endpoint, then, only a service-account key (--auth-google-service-account-env) works unless the operator lists the endpoint’s host; --auth-google-metadata, --auth-google-adc and a WIF configuration signed with the host’s AWS identity are refused with 403 (err:auth/HostIdentityRefused) before a token is minted.

General:

OptionDescription
--branch <BRANCH>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)
--allow-duplicate-subjectsSkip the duplicate-subject probe: no table is refused, and queries answer with set semantics (removing repeated solutions) wherever no key declared in the mapping proves a map’s subjects unique. Without it, the pushdown lane refuses statements over tables the probe finds repeated. See Repeated rows and subject keys
--remote <NAME>Execute against a remote server

Examples

# Trino with a bearer token; tables are qualified inside hive.sales
fluree sql map orders-db \
  --endpoint https://trino.example.com:8443 \
  --catalog hive --schema sales \
  --auth-bearer "$TRINO_TOKEN" \
  --r2rml mappings/orders.ttl

# A bridge sidecar in front of Postgres
fluree sql map crm \
  --endpoint http://localhost:8080 \
  --dialect postgres --schema public \
  --r2rml mappings/crm.ttl

Output

Mapped SQL endpoint as graph source 'orders-db:main'
  Endpoint:    https://trino.example.com:8443
  R2RML:       bafy…
  TriplesMaps: 3
  Tables:      2 (sales.orders, sales.customers)
  Connection:  verified
  Mapping:     validated

Connection: not tested means the SELECT 1 probe failed; the source is still registered and the first query reports the underlying error.

A Warning: line per finding of the subject-key uniqueness probe follows (a table whose subject key repeats, or a table that could not be probed). Then an advisory: line on standard error for each triples map that neither the key the probe verified nor an f:key proves subject-unique, naming the f:key that would: the lane deduplicates such a map (see R2RML → A map with no key).

fluree sql check

fluree sql check orders-db

Re-runs the subject-key uniqueness probe against the live tables and stores the result on the source: the tables whose keys repeat, and the key verified for every other table, which the pushdown lane then trusts. Run it after the endpoint was unreachable at registration, or after the tables change. It prints the probe’s findings and the advisory: lines map prints, under the keys it verified. Local only (no --remote).

fluree sql list / info / drop

fluree sql list
fluree sql info orders-db
fluree sql drop orders-db --force

Behave exactly as the fluree iceberg equivalents; SQL sources show the type SQL.