Skip to content

query.md

Latest commit

 

History

History
211 lines (159 loc) · 7.05 KB

query.md

File metadata and controls

211 lines (159 loc) · 7.05 KB
Raw

fluree query

Query a ledger.

Usage

fluree query [LEDGER] [QUERY] [OPTIONS]

Arguments

Arguments Behavior
(none) Active ledger; provide query via -e, -f, or stdin
<arg> Auto-detected: if it looks like a query, uses it inline with the active ledger; if it's an existing file, reads from it; otherwise treats it as a ledger name
<ledger> <query> Specified ledger + inline query

The ledger may also be given explicitly with -l/--ledger, which bypasses the positional auto-detection (e.g. fluree query --ledger mydb:main 'SELECT …').

Options

Option Description
-l, --ledger <LEDGER> Ledger name (defaults to active ledger); explicit alternative to the positional ledger argument
-e, --expr <EXPR> Inline query expression (alternative to positional)
-f, --file <FILE> Read query from a file
--format <FORMAT> Output format: json, jsonld, typed-json, cypher-json, table, csv, tsv, or ndjson (default: table; Cypher defaults to cypher-json)
--envelope With --format ndjson, emit the full streaming record protocol verbatim instead of bare binding objects
--sparql Force SPARQL query format
--jsonld Force JSON-LD query format
--cypher Force openCypher query format (local ledgers only)
--at <TIME> Query at a specific point in time
--normalize-arrays Always wrap multi-value properties in arrays (graph-crawl JSON-LD queries only)
--bench Benchmark mode: time execution only and print the first 5 rows as a table (no full-result JSON formatting)
--explain Print the query plan without executing it
--remote <NAME> Execute against a remote server (by remote name, e.g., origin)

Description

Executes a query against a ledger. Supports SPARQL, JSON-LD, and openCypher query formats.

Query Formats

SPARQL

fluree query 'SELECT ?name WHERE { ?s <http://example.org/name> ?name }'

JSON-LD Query

fluree query '{"select": ["?name"], "where": {"http://example.org/name": "?name"}}'

Cypher

openCypher reads run on local ledgers only (the HTTP Cypher route is not yet wired through --remote). Results default to cypher-json (a Neo4j-compatible envelope); pass --format jsonld for the RDF JSON-LD form.

fluree query mydb:main -e 'MATCH (p:Person) RETURN p.name' --cypher
fluree query mydb:main -f find-people.cypher

Format is auto-detected if not specified:

  • Force with --sparql, --jsonld, or --cypher; a .cypher/.cyp/.cql file extension also forces Cypher.
  • Leading MATCH/MERGE/UNWIND/OPTIONAL/DETACH/CREATE, or a {"cypher": "..."} envelope → Cypher
  • Contains SELECT, CONSTRUCT, ASK, or DESCRIBE → SPARQL
  • Otherwise → JSON-LD

For Cypher writes (CREATE/MERGE/SET/DELETE), use fluree update with --format cypher (or a .cypher file).

Output Formats

JSON (default)

fluree query 'SELECT ?name WHERE { ?s <http://example.org/name> ?name }'
{
  "head": {"vars": ["name"]},
  "results": {"bindings": [{"name": {"type": "literal", "value": "Alice"}}]}
}

Table

fluree query --format table 'SELECT ?name WHERE { ?s <http://example.org/name> ?name }'
┌───────┐
│ name  │
├───────┤
│ Alice │
│ Bob   │
└───────┘

CSV

fluree query --format csv 'SELECT ?name WHERE { ?s <http://example.org/name> ?name }'
name
Alice
Bob

Note: --format csv (and --format tsv) are only supported for local ledgers. Tracked/remote ledgers support json and table output.

NDJSON (streaming)

--format ndjson streams SELECT results incrementally as newline-delimited JSON instead of buffering the whole result set — use it for large result sets and unix pipelines (| jq, | while read, etc.). Rows are flushed as the query produces them, so the CLI never holds the full result in memory.

By default each line is a bare SPARQL-JSON binding object (the same term shapes as the json format's results.bindings entries), one per result row:

fluree query --format ndjson 'SELECT ?name WHERE { ?s <http://example.org/name> ?name }'
{"name":{"type":"literal","value":"Alice"}}
{"name":{"type":"literal","value":"Bob"}}

Add --envelope to emit the full streaming record protocol verbatim — the same bytes the server's streaming query endpoint produces (head / row / heartbeat / end / error). This is useful for debugging and for detecting truncation (a stream that ends without a terminal record):

fluree query --format ndjson --envelope 'SELECT ?name WHERE { ?s <http://example.org/name> ?name }'
{"type":"head","vars":["name"]}
{"type":"row","row":{"name":{"type":"literal","value":"Alice"}}}
{"type":"row","row":{"name":{"type":"literal","value":"Bob"}}}
{"type":"end","rows":2}

In bare mode the CLI consumes the terminal record internally and exits non-zero if the stream carried an error or ended without a terminal (truncated / dropped connection). A closed downstream pipe (e.g. | head) ends the stream cleanly with exit 0.

Scope (mirrors the server streaming endpoint): NDJSON streaming applies to SELECT queries only. ASK, CONSTRUCT/DESCRIBE, selectOne, hydration, and history-range queries are rejected — use a buffered --format. On local ledgers, --at (time travel) and per-request --policy are not supported with --format ndjson; use --remote (where they route through the server's dataset path) or a buffered format instead. --bench and --explain are not compatible with --format ndjson.

Time Travel

Query historical states with --at:

# Query at transaction 5
fluree query --at 5 'SELECT * WHERE { ?s ?p ?o }'

# Query at specific commit
fluree query --at abc123def 'SELECT * WHERE { ?s ?p ?o }'

# Query at ISO-8601 timestamp
fluree query --at 2024-01-15T10:30:00Z 'SELECT * WHERE { ?s ?p ?o }'

Tracked/remote ledgers also support --at. The CLI will translate --at into the appropriate dataset/time-travel form when forwarding the query to the remote server.

SPARQL note (remote): if your SPARQL already includes FROM / FROM NAMED, the CLI will not rewrite it for --at. In that case, encode time travel directly in the FROM IRI (e.g., FROM <myledger:main@t:5>).

Examples

# Inline SPARQL query (most common)
fluree query 'SELECT ?name WHERE { ?s <http://example.org/name> ?name }'

# JSON-LD query inline
fluree query '{"select": {"?s": ["*"]}, "where": {"@id": "?s"}}'

# Query specific ledger with CSV output
fluree query production --format csv 'SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10'

# SPARQL query from file
fluree query -f query.rq

# Time travel query
fluree query --at 3 'SELECT * WHERE { ?s ?p ?o }'

# Pipe from stdin
cat query.rq | fluree query

See Also