Query

June 30, 2026 · View on GitHub

Fluree supports three query languages over the same graph data: JSON-LD Query (Fluree's native query language), SPARQL (the W3C standard), and Cypher (openCypher). All three run against one underlying store — data written through any surface is immediately visible to the others — and each provides access to Fluree's unique features including time travel, graph sources, and policy enforcement.

Query Languages

JSON-LD Query

Fluree's native query language that uses JSON-LD syntax. JSON-LD Query provides a natural, JSON-based interface for querying graph data, making it easy to integrate with modern applications.

Key Features:

  • JSON-based syntax (no string parsing)
  • Full support for time travel (@t:, @iso:, @commit:)
  • Graph source integration
  • Policy enforcement
  • History queries

SPARQL

Industry-standard SPARQL 1.1 query language. Fluree provides full SPARQL support, enabling compatibility with existing RDF tools and knowledge graphs.

Key Features:

  • W3C SPARQL 1.1 compliant
  • FROM and FROM NAMED clauses
  • CONSTRUCT queries
  • Time travel support (planned)
  • Standard SPARQL functions

Cypher

openCypher 9 for property-graph queries and writes. Cypher relationships-with-properties map directly to Fluree's edge-annotation primitive, so the same database is queryable through JSON-LD, SPARQL, and Cypher at once.

Key Features:

  • MATCH / RETURN reads and CREATE / MERGE / SET / DELETE writes
  • Property-graph edges via edge annotations
  • Neo4j-compatible cypher-json output (or RDF JSON-LD)
  • Auto-detected by the CLI; Content-Type: application/cypher over HTTP

See the openCypher support matrix for a feature-by-feature status view.

Query Features

Output Formats

Fluree supports multiple output formats for query results:

  • JSON-LD: Compact, context-aware JSON with IRI expansion/compaction
  • SPARQL JSON: Standard SPARQL result format
  • Typed JSON: Type-preserving JSON with datatype information

Datasets and Multi-Graph Execution

Query across multiple graphs and ledgers:

  • FROM clauses: Specify default graphs
  • FROM NAMED: Query named graphs
  • Multi-ledger queries: Query across different ledgers
  • Time-aware datasets: Query graphs at different time points

CONSTRUCT Queries

Generate RDF graphs from query results:

  • Transform query results into RDF
  • Create new graph structures
  • Extract subgraphs

Graph Crawl

Traverse graph relationships:

  • Follow links between entities
  • Recursive graph traversal
  • Depth-limited crawling

Explain Plans

Understand query execution:

  • View query plans
  • Analyze index usage
  • Optimize query performance

Tracking and Fuel Limits

Monitor and control query execution:

  • Query tracking and debugging
  • Fuel limits for resource control
  • Performance monitoring

Nameservice Queries

Query metadata about all ledgers and graph sources in the system. The nameservice stores information about every database including commit state, index state, and configuration.

JSON-LD Query:

{
  "@context": {"f": "https://ns.flur.ee/db#"},
  "select": ["?ledger", "?t"],
  "where": [
    { "@id": "?ns", "@type": "f:LedgerSource", "f:ledger": "?ledger", "f:t": "?t" }
  ]
}

SPARQL:

PREFIX f: <https://ns.flur.ee/db#>
SELECT ?ledger ?t WHERE { ?ns a f:LedgerSource ; f:ledger ?ledger ; f:t ?t }

See the Ledgers and Nameservice concept documentation for details.

Time Travel in Queries

Fluree supports querying historical data using time specifiers in ledger references:

Transaction Number:

ledger:main@t:100

ISO 8601 Timestamp:

ledger:main@iso:2024-01-15T10:30:00Z

Commit ContentId:

ledger:main@commit:bafybeig...

See the Time Travel concept documentation for details.

Graph Source Queries

Query graph sources (BM25, Vector, Iceberg, R2RML) using the same syntax as regular ledgers:

{
  "@context": {
    "f": "https://ns.flur.ee/db#"
  },
  "from": "products:main",
  "select": ["?product"],
  "where": [
    {
      "f:graphSource": "products-search:main",
      "f:searchText": "laptop",
      "f:searchLimit": 20,
      "f:searchResult": { "f:resultId": "?product" }
    }
  ]
}

See the Graph Sources concept documentation for details.

Policy Enforcement

Policies are automatically enforced during query execution, ensuring users only see data they're authorized to access. No special syntax is required—policies are applied transparently.

See the Policy Enforcement concept documentation for details.

Getting Started

Basic JSON-LD Query

{
  "@context": {
    "ex": "http://example.org/ns/"
  },
  "select": ["?name"],
  "where": [
    { "@id": "?person", "ex:name": "?name" }
  ]
}

Basic SPARQL Query

PREFIX ex: <http://example.org/ns/>

SELECT ?name
WHERE {
  ?person ex:name ?name .
}

Basic Cypher Query

MATCH (person:Person)
RETURN person.name

Query with Time Travel

{
  "@context": {
    "ex": "http://example.org/ns/"
  },
  "from": "ledger:main@t:100",
  "select": ["?name"],
  "where": [
    { "@id": "?person", "ex:name": "?name" }
  ]
}

Query Performance

Fluree's query engine is optimized for:

  • Automatic Join Ordering: The planner reorders all WHERE-clause patterns (triples, UNION, OPTIONAL, MINUS, search patterns, and more) using statistics-driven cardinality estimates. When database statistics are available, it uses HLL-derived property counts; otherwise it falls back to heuristic constants. Estimates are context-aware — the planner tracks which variables are already bound and adjusts costs accordingly, so a triple whose subject is bound from an earlier pattern is scored as a cheap per-subject lookup rather than a full scan.
  • Index Selection: Automatically chooses optimal indexes (SPOT, POST, OPST, PSOT) based on which triple components are bound.
  • Filter Optimization: Filters are automatically applied as soon as their required variables are bound, regardless of where they appear in the query. Range-safe filters are pushed down to index scans, and filters are evaluated inline during joins when possible.
  • Streaming Execution: Results stream as they're computed
  • Parallel Processing: Parallel execution where possible

Best Practices

  1. Use Appropriate Indexes: Structure queries to leverage indexes
  2. Limit Result Sets: Use LIMIT clauses for large result sets
  3. Time Travel Efficiency: Use @t: when transaction numbers are known
  4. Graph Source Selection: Choose appropriate graph sources for query patterns
  5. Policy Awareness: Understand how policies affect query results

Bundling queries

When you have multiple independent queries that should all see the same data — or that you'd otherwise issue as N concurrent HTTP requests — use the Multi-query envelope. It runs N JSON-LD and/or SPARQL queries in parallel against a single resolved snapshot, with shared @context / opts defaults and per-alias result assembly.