FlureeQL Query Syntax
FlureeQL is a JSON-based query language for retrieving Fluree data. It is modeled as a JSON-representation of the W3C SPARQL standard.
Query Object
FlureeQL queries are JSON with the following keys:
| key | required? | type |
|---|---|---|
@context | no | object |
from | yes | string or array |
where | no | array or object |
select | yes* | array or object |
construct | no* | array |
values | no | array |
t | no | string or integer |
groupBy | no | array or string |
having | no | array or string |
orderBy | no | string or array |
limit | no | integer |
offset | no | integer |
NOTE: Either
selectorconstructis required, but not both.
Advanced Features
| Feature | Description |
|---|---|
| Property Paths | Traverse relationships across multiple hops |
| Subqueries | Nest queries within queries |
| Time Travel | Query historical data using @t:, @iso:, or @sha: syntax |
| Value Map Filters | Inline filters in where conditions |
| Federated Queries | Query across multiple ledgers |
| Vector Search | Similarity search with embeddings |
Examples
Basic query example
{ "from": "cookbook/base", "where": { "@id": "?s", "bestFriend": "?friend" }, "select": { "?s": [ "*", { "bestFriend": [ "*" ] } ] },}
@context
| required? | type |
|---|---|
| no | object |
Understanding the use of @context within the W3C JSON-LD standard can be important for using it properly within queries. For an explanation of how to use @context in FlureeQL, consider first reading our Guides page on Working with Context.
Examples
Example of a Query without @context
{ "from": "cookbook/base", "where": { "@id": "?s", "@type": "http://example.org/Person" }, "select": { "?s": ["http://schema.org/name"] }}
Example of a Query with @context
{ "@context": { "schema": "http://schema.org/", "ex": "http://example.org/" }, "from": "cookbook/base", "where": { "@id": "?s", "@type": "ex:Person" }, "select": { "?s": ["schema:name"] }}
from
| required? | type |
|---|---|
| yes | string |
The from clause specifies the ledger to query. It takes the same value that would have been supplied to the /create endpoint when the ledger was created.
If I named a ledger "cookbook/base" when I created it, then when I queried it, I would use "from": "cookbook/base" to identify that this query should target that particular ledger.
Examples
Querying a ledger named "cookbook/base"
{ "@context": { "schema": "http://schema.org/", "ex": "http://example.org/" }, "from": "cookbook/base", "where": { "@id": "?s", "@type": "ex:Person" }, "select": { "?s": ["schema:name"] }}
Next Steps
- Select Clauses — Control what data is returned
- Where Clauses — Filter and match data patterns
- Aggregations & Grouping — Group and aggregate results
- Modifiers — Order, limit, and paginate results
- Advanced Features — Property paths, subqueries, federated queries, and more