Fluree DB

A semantic graph database with time travel, branching, and verifiable data — built on W3C standards.

Fluree DB is a single binary that stores your data as an RDF knowledge graph, queryable with SPARQL or JSON-LD Query, with every commit immutably recorded so you can travel back to any prior state. It supports git-style branching and merging, signed and policy-gated transactions, SHACL validation, OWL/RDFS reasoning, and full-text and vector search — over local files, S3, or IPFS — without bolting on external services.

What you get

• Semantic by default. Your data is RDF. IRIs, JSON-LD @context, named graphs, and typed values are first-class. Queries are SPARQL 1.1 or the equivalent JSON-LD Query, both compiling to the same execution engine.
• Time travel. Every transaction is a commit on an immutable chain. Query the state of the graph at any past moment with a single t parameter — no snapshots to restore, no separate audit log to consult.
• Branching and merging. Create a branch off any commit, transact against it in isolation, then merge it back. Useful for staging changes, running what-if analyses, or maintaining environment-specific overlays.
• Verifiable data. Transactions and commits can be signed (JWS / W3C Verifiable Credentials). The commit chain is content-addressed, so any tampering is detectable. Pair it with policy enforcement to prove who changed what and when they were allowed to.
• Policy-based access control. Policies are written as graph data, evaluated per query and per transaction, and travel with the ledger — not bolted on at the API layer.
• Storage your way. Local filesystem for development, S3 + DynamoDB for production, IPFS for content-addressed distribution. The same ledger format works across all of them.
• Search built in. BM25 full-text indexing and HNSW vector search live alongside SPARQL — no separate search service to operate.
• Reasoning. OWL/RDFS inference and Datalog rules run inside the query engine, so derived facts are queryable without a materialization step.
• Embeddable. The same engine that powers the server runs as a Rust library, generic over storage and nameservice. Use it directly in your application or run it standalone over HTTP.

Start here

• New to Fluree? → Getting started
• Run the server → Quickstart: run the server
• Create a ledger and write data → Quickstart: create a ledger → Quickstart: write data
• Query data → Quickstart: query (JSON-LD + SPARQL)
• End-to-end walkthrough → Tutorial: search, time travel, branching, policies
• Coming from SQL? → Fluree for SQL developers
• Embedding in Rust? → Using Fluree as a Rust library

Explore the docs

• Concepts — ledgers, graph sources, IRIs, time travel, policy, verifiable data, reasoning
• Guides (cookbooks) — search, time travel, branching, policies, SHACL — task-oriented recipes
• CLI reference — every fluree command, flag by flag
• HTTP API — endpoints, headers, signed requests, error model
• Query — JSON-LD Query, SPARQL, output formats, CONSTRUCT, explain plans, reasoning
• Transactions — insert, upsert, update, conditional updates, signed transactions
• Security and policy — authentication, encryption, commit signing, policy model
• Indexing and search — background indexing, BM25, vector search, geospatial
• Graph sources and integrations — Iceberg/Parquet, R2RML, BM25 graph source
• Operations — configuration, Docker, storage modes, telemetry, archive/restore
• Design — internals: query execution, storage traits, index format, nameservice
• Reference — glossary, vocabulary, OWL/RDFS support, crate map
• Troubleshooting — common errors, debugging queries, performance tracing
• Contributing — dev setup, tests, SPARQL compliance, releasing

The full table of contents is in SUMMARY.md.

Fluree Memory

Fluree Memory is persistent, searchable memory for AI coding assistants — built on Fluree DB and shipped in the same fluree binary. If you’re here for the memory tooling, jump straight to the Memory docs.

Fluree CLI

The fluree command-line interface provides a convenient way to manage ledgers, run queries, and perform transactions without running a server.

Installation

Build from source:

cargo build --release -p fluree-db-cli

The binary will be at target/release/fluree.

Quick Start

# Initialize a project directory
fluree init

# Create a ledger
fluree create myledger

# Insert data
fluree insert '@prefix ex: <http://example.org/> .
ex:alice a ex:Person ; ex:name "Alice" .'

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

Global Options

Commands

Core Commands

Remote Sync

Clone and pull transfer commits and, by default, binary index data from the remote (pack protocol), so the local ledger is query-ready without a separate reindex. Use --no-indexes to skip index transfer and reduce download size; run fluree reindex afterward if you need the index. Large transfers may prompt for confirmation before streaming.

Server Management

Start a server directly from a project directory — it inherits the same .fluree/ context (config, storage) as the CLI. See server for details.

Implementers

If you’re building a custom server that must support the CLI end-to-end (for example, integrating into another app), see:

• server-integration - endpoints and auth contract required by the CLI

Authentication

Configuration

Developer Memory

For background, IDE setup, team workflows, and the mem: schema, see the Memory section of the docs.

Project Structure

When you run fluree init, a .fluree/ directory is created with:

.fluree/
├── active          # Currently active ledger name
├── config.toml     # Configuration settings
├── prefixes.json   # IRI prefix mappings
└── storage/        # Ledger data storage

Input Resolution

Commands that accept data input (insert, upsert, update, query) use flexible argument resolution:

Input is resolved in this priority order: -e flag > positional inline > -f flag > positional file > stdin.

Data Format Detection

The CLI auto-detects data format based on content:

• Lines starting with @prefix or @base → Turtle
• Content starting with { or [ → JSON-LD
• Files with .ttl extension → Turtle
• Files with .json or .jsonld extension → JSON-LD

You can override with --format turtle or --format jsonld.

fluree init

Initialize a new Fluree project directory.

Usage

fluree init [OPTIONS]

Options

Description

Creates a .fluree/ directory in the current working directory (or global directories with --global). This directory stores:

• active - The currently active ledger name
• config.toml - Configuration settings
• prefixes.json - IRI prefix mappings for compact IRIs
• storage/ - Ledger data

Running init is idempotent - it won’t overwrite existing configuration.

Examples

# Initialize in current directory
fluree init

# Initialize global config
fluree init --global

Global Directory

With --global, the directories are determined by:

1. $FLUREE_HOME environment variable (if set) — both config and data go in this single directory.
2. Platform directories (when $FLUREE_HOME is not set):

On macOS and Windows both resolve to the same directory (unified); on Linux config and data are separated per XDG conventions.

The generated config.toml will contain an absolute storage_path pointing to the data directory when the directories are split.

See Also

• create - Create a new ledger after initialization

fluree create

Create a new ledger.

Usage

fluree create <LEDGER> [OPTIONS]

Arguments

Options

Global flags that affect bulk import when using --from (see CLI README):

• --memory-budget-mb <MB> — Memory budget in MB (0 = auto: 75% of system RAM). Drives chunk size, concurrency, and indexer run budget.
• --parallelism <N> — Number of parallel parse threads (0 = auto: system cores, cap 6).

Description

Creates a new empty ledger with the given name and sets it as the active ledger. The ledger is stored in .fluree/storage/.

Use --from to create a ledger pre-populated with data from a Turtle or JSON-LD file. For large Turtle files, the CLI splits work into chunks and runs parallel parse threads; tune with --memory-budget-mb and --parallelism if needed.

Use --memory to import your project’s developer memory history into a time-travel-capable Fluree ledger. Each git commit that touched .fluree-memory/repo.ttl (and .local/user.ttl unless --no-user is set) becomes a Fluree transaction. The git commit message, SHA, and author date are stored as transaction metadata, so you can correlate Fluree t values with git history.

Examples

# Create an empty ledger
fluree create mydb

# Create with initial data
fluree create mydb --from seed-data.ttl

# Create from JSON-LD
fluree create mydb --from initial.jsonld

# Create with explicit memory and parallelism for a large Turtle file
fluree create mydb --from large.ttl --memory-budget-mb 4096 --parallelism 8

# Import memory history from the current repo
fluree create memories --memory

# Import memory history from another repo, excluding user memories
fluree create memories --memory /path/to/other/repo --no-user

Output

Created ledger 'mydb'
Set 'mydb' as active ledger

With --from:

Created ledger 'mydb'
Committed t=1 (42 flakes)
Set 'mydb' as active ledger

With --memory:

Created ledger 'memories' with 42 commits (t=1..43)
  Earliest: bf803255 — initial memory store
  Latest:   9865e5cd — prevent overrides of fluree txn-meta

Query with time travel:
  fluree query memories 'SELECT ?id ?content WHERE { ?id a mem:Fact ; mem:content ?content } LIMIT 5'
  fluree query memories --at-t 2 'SELECT ...'   # state at first commit

See Also

• list - List all ledgers
• use - Switch active ledger
• drop - Delete a ledger

fluree use

Set the active ledger.

Usage

fluree use <LEDGER>

Arguments

Description

Sets the specified ledger as the active ledger. Subsequent commands that don’t specify a ledger will use this one.

Examples

# Switch to a different ledger
fluree use production

# Verify with info
fluree info

Output

Active ledger set to 'production'

Errors

If the ledger doesn’t exist:

error: ledger 'nonexistent' not found

See Also

• list - List all ledgers
• create - Create a new ledger

fluree list

List all ledgers and graph sources.

Usage

fluree list

Description

Lists all ledgers and graph sources (Iceberg, R2RML, BM25, Vector, etc.) in the current Fluree directory. The active ledger is marked with an asterisk (*).

When graph sources are present, a TYPE column is shown to distinguish ledgers from graph sources.

Examples

fluree list

Output

When only ledgers exist:

   LEDGER      BRANCH  T
 * mydb        main    5
   production  main    12

When graph sources are also present:

   NAME              BRANCH  TYPE     T
 * mydb              main    Ledger   5
   production        main    Ledger   12
   warehouse-orders  main    Iceberg  -
   my-search         main    BM25     5

If nothing exists:

No ledgers found. Run 'fluree create <name>' to create one.

See Also

• create - Create a new ledger
• iceberg - Map Iceberg tables as graph sources
• info - Show detailed ledger or graph source information
• use - Switch active ledger

fluree info

Show detailed information about a ledger or graph source.

Usage

fluree info [NAME] [--remote <name>] [--graph <name|IRI>]

Arguments

Options

Description

Displays detailed information about a ledger or graph source. The command first checks for a matching ledger; if none is found, it checks for a graph source with the same name.

For ledgers, displays:

• Ledger ID, branch, and type
• Current transaction number (t)
• Commit and index details

For graph sources (Iceberg, R2RML, BM25, etc.), displays:

• Name, branch, and type
• Graph source ID
• Index status
• Dependencies
• Configuration (catalog URI, table, mapping, etc.)

Examples

# Info for active ledger
fluree info

# Info for specific ledger
fluree info production

# Info for a graph source
fluree info warehouse-orders

# Query a remote server
fluree info production --remote origin

# Scope stats to the default graph
fluree info mydb --graph default

# Scope stats to the transaction-metadata graph
fluree info mydb --graph txn-meta

# Scope stats to a specific named graph by IRI
fluree info mydb --graph https://example.org/graphs/inventory

When --graph is set, the command prints the full ledger-info JSON response with the stats block scoped to the selected graph (properties, classes, flakes, size).

Output

Ledger:

Ledger:         mydb
Branch:         main
Type:           Ledger
Ledger ID:      mydb:main
Commit t:       5
Commit ID:      bafybeig...
Index t:        5
Index ID:       bafybeig...

Graph source (Iceberg):

Name:           warehouse-orders
Branch:         main
Type:           Iceberg
ID:             warehouse-orders:main
Retracted:      false
Index t:        0
Index ID:       (none)

Configuration:
{
  "catalog": {
    "type": "rest",
    "uri": "https://polaris.example.com/api/catalog"
  },
  "table": "sales.orders",
  ...
}

See Also

• list - List all ledgers and graph sources
• iceberg - Map Iceberg tables as graph sources
• log - Show commit history

fluree branch

Manage branches for a ledger.

Subcommands

fluree branch create

Create a new branch.

Usage:

fluree branch create <NAME> [OPTIONS]

Arguments:

Options:

Description:

Creates a new branch for a ledger. By default the branch starts at the source branch’s current HEAD, and is fully isolated — subsequent transactions on either branch are invisible to the other.

Pass --at to branch from a historical commit on the source branch instead of its HEAD. The commit must be reachable from the source HEAD; the new branch starts with no index and replays from genesis on first query. t:N and hex-prefix resolution require the source branch to be indexed (full CIDs work unconditionally).

Branches can be nested: you can create a branch from any existing branch, not just “main”.

Examples:

# Create a branch from main (default)
fluree branch create dev

# Create a branch for a specific ledger
fluree branch create dev --ledger mydb

# Create a branch from another branch
fluree branch create feature-x --from dev

# Branch at a historical point on main (transaction number)
fluree branch create rewind --at t:5

# Branch at a historical commit by hex-digest prefix
fluree branch create rewind --at 3dd028a7

# Create a branch on a remote server
fluree branch create staging --ledger mydb --remote origin

Output:

Created branch 'dev' from 'main' at t=5
Ledger ID: mydb:dev

fluree branch list

List all branches for a ledger.

Usage:

fluree branch list [LEDGER] [OPTIONS]

Arguments:

Options:

Examples:

# List branches for the active ledger
fluree branch list

# List branches for a specific ledger
fluree branch list mydb

# List branches on a remote server
fluree branch list mydb --remote origin

Output:

 BRANCH     T   SOURCE
 main       5   -
 dev        7   main
 feature-x  8   dev

fluree branch drop

Drop a branch from a ledger.

Usage:

fluree branch drop <NAME> [OPTIONS]

Arguments:

Options:

Description:

Drops a branch from a ledger. The main branch cannot be dropped.

• Leaf branches (no children) are fully deleted — storage artifacts are removed and the NsRecord is purged.
• Branches with children are retracted (hidden from listings, reject new transactions) but storage is preserved so that child branches continue to work. When the last child is eventually dropped, the retracted parent is automatically cascade-purged.

Examples:

# Drop a branch
fluree branch drop dev

# Drop a branch for a specific ledger
fluree branch drop dev --ledger mydb

# Drop a branch on a remote server
fluree branch drop staging --ledger mydb --remote origin

Output (leaf branch):

Dropped branch 'dev'.
  Artifacts deleted: 5

Output (branch with children):

Branch 'dev' retracted (has children, storage preserved).

Output (cascade):

Dropped branch 'feature'.
  Artifacts deleted: 3
  Cascaded drops: mydb:dev

fluree branch rebase

Rebase a branch onto its source branch’s current HEAD.

Usage:

fluree branch rebase <NAME> [OPTIONS]

Arguments:

Options:

Description:

Replays a branch’s unique commits on top of the source branch’s current HEAD. This brings the branch up to date with upstream changes. The main branch cannot be rebased.

If the branch has no unique commits, a fast-forward rebase is performed — the branch point is simply updated to the source’s current HEAD.

Conflicts occur when both the branch and source have modified the same (subject, predicate, graph) tuples. See conflict strategies for details.

Examples:

# Rebase with default strategy
fluree branch rebase dev

# Rebase with abort-on-conflict strategy
fluree branch rebase dev --strategy abort

# Rebase for a specific ledger
fluree branch rebase feature-x --ledger mydb --strategy take-source

# Rebase on a remote server
fluree branch rebase dev --ledger mydb --remote origin

Output (fast-forward):

Fast-forward rebase of 'dev' to t=5.

Output (with replay):

Rebased 'dev': 3 commits replayed, 0 skipped, 1 conflicts, 0 failures.
  New branch point: t=8

fluree branch diff

Show a read-only merge preview between two branches.

Usage:

fluree branch diff <SOURCE> [OPTIONS]

Arguments:

Options:

Description:

branch diff reports ahead/behind commits, fast-forward eligibility, and conflicting (subject, predicate, graph) keys without mutating state. With --conflict-details, the preview also shows the source and target values for the returned conflict keys and annotates what the selected strategy would do.

Examples:

# Preview merging dev into its parent
fluree branch diff dev

# Preview a specific target
fluree branch diff dev --target main

# Show value details and source-winning labels
fluree branch diff dev --target main --conflict-details --strategy take-source

# Emit raw JSON for UI tooling
fluree branch diff dev --conflict-details --json

fluree branch merge

Merge a source branch into a target branch.

Usage:

fluree branch merge <SOURCE> [OPTIONS]

Arguments:

Options:

Description:

Merges a source branch into a target branch. When the target hasn’t advanced since the source branched, this is a fast-forward; otherwise --strategy controls how conflicting edits are resolved (mirroring branch rebase).

When --target is omitted, the merge target is inferred from the source branch’s parent (the branch it was created from).

After a successful merge, the source branch remains intact and can continue to receive new transactions and be merged again. Only the new commits since the last merge (or branch creation) are copied.

Examples:

# Merge dev into main (inferred from branch point)
fluree branch merge dev

# Merge feature-x into dev (explicit target)
fluree branch merge feature-x --target dev

# Merge for a specific ledger
fluree branch merge dev --ledger mydb

# Merge with source-winning conflict resolution
fluree branch merge dev --target main --strategy take-source

# Merge on a remote server
fluree branch merge dev --ledger mydb --remote origin

Output:

Merged 'dev' into 'main' (fast-forward to t=8, 3 commits copied).

Output (non-fast-forward):

Merged 'dev' into 'main' (t=9, 3 commits copied, 1 conflicts).

See Also

• create - Create a new ledger
• list - List all ledgers
• info - Show ledger details
• use - Switch active ledger

fluree drop

Drop (delete) a ledger or graph source.

Usage

fluree drop <NAME> --force

Arguments

Options

Description

Permanently deletes a ledger or graph source. The --force flag is required to prevent accidental deletion.

The command first tries to drop the name as a ledger. If no ledger is found, it tries to drop it as a graph source. This means fluree drop works uniformly for both ledgers and graph sources like Iceberg mappings.

Examples

# Delete a ledger
fluree drop oldledger --force

# Delete a graph source (Iceberg mapping)
fluree drop warehouse-orders --force

Output

Ledger:

Dropped ledger 'oldledger'

Graph source:

Dropped graph source 'warehouse-orders:main'

Errors

Without --force:

error: use --force to confirm deletion of 'oldledger'

See Also

• create - Create a new ledger
• iceberg - Map Iceberg tables as graph sources
• list - List all ledgers and graph sources

fluree insert

Insert data into a ledger.

Usage

fluree insert [LEDGER] [DATA] [OPTIONS]

Arguments

Options

Description

Inserts RDF data into a ledger. Supports both Turtle and JSON-LD formats. Data can come from:

• A positional argument (inline data)
• -e flag (inline expression)
• -f flag (file)
• Standard input (pipe)

Examples

# Insert inline Turtle
fluree insert '@prefix ex: <http://example.org/> .
ex:alice a ex:Person ; ex:name "Alice" .'

# Insert inline JSON-LD
fluree insert '{"@id": "ex:bob", "ex:name": "Bob"}'

# Insert from file
fluree insert -f data.ttl

# Insert with commit message
fluree insert -f data.ttl -m "Added initial users"

# Insert into specific ledger
fluree insert production '<http://example.org/x> a <http://example.org/Thing> .'

# Pipe from stdin
cat data.ttl | fluree insert

Output

Committed t=1 (42 flakes)

With verbose mode:

Committed t=1 (42 flakes)
Commit ID: bafybeig...

Data Format Detection

The format is auto-detected:

• @prefix or @base at line start → Turtle
• Starts with { or [ → JSON-LD
• .ttl file extension → Turtle
• .json or .jsonld extension → JSON-LD

Override with --format turtle or --format jsonld.

See Also

• upsert - Insert or update existing data
• update - Full WHERE/DELETE/INSERT updates
• query - Query the inserted data
• export - Export all data

fluree upsert

Upsert data into a ledger (insert or update existing).

Usage

fluree upsert [LEDGER] [DATA] [OPTIONS]

Arguments

Options

Description

Upserts RDF data into a ledger. Unlike insert, upsert will:

• Insert new entities
• Replace existing values for entities that already exist (matched by @id)

This is useful for updating data without needing to know whether it exists.

Examples

# Update or insert a user
fluree upsert '@prefix ex: <http://example.org/> .
ex:alice ex:name "Alice Smith" ; ex:age 31 .'

# Upsert from file
fluree upsert -f updates.ttl

# Upsert with commit message
fluree upsert '{"@id": "ex:alice", "ex:status": "active"}' -m "Updated Alice status"

Output

Committed t=2 (3 flakes)

Difference from Insert

See Also

• insert - Insert without replacement
• update - Full WHERE/DELETE/INSERT updates
• query - Query data
• history - View change history

fluree update

Update data with full WHERE/DELETE/INSERT semantics.

Usage

fluree update [LEDGER] [DATA] [OPTIONS]

Arguments

Options

Description

Executes a WHERE/DELETE/INSERT transaction against a ledger. Unlike insert (which only adds data) and upsert (which replaces by subject+predicate), update supports the full WHERE/DELETE/INSERT pattern, enabling:

• Conditional deletes: delete triples matching a WHERE pattern
• Conditional updates: delete old values and insert new ones based on WHERE matches
• Computed updates: use variables from WHERE to derive new values via bind
• Delete-only operations: WHERE + DELETE without INSERT
• Insert-only operations: equivalent to insert but using the update command

Supported Formats

• JSON-LD (default): transaction body with where, delete, and/or insert keys
• SPARQL UPDATE: standard INSERT DATA, DELETE DATA, DELETE/INSERT WHERE syntax

SPARQL UPDATE Note

SPARQL UPDATE requires the server’s parsing pipeline. It works automatically when:

• A local server is running (the CLI auto-routes through it by default)
• Using --remote to target a remote server

For direct local mode (--direct), use JSON-LD format instead.

Examples

Conditional Property Update (JSON-LD)

# Update Alice's age: find old value, delete it, insert new one
fluree update '{
  "@context": {"ex": "http://example.org/"},
  "where": [{"@id": "ex:alice", "ex:age": "?oldAge"}],
  "delete": [{"@id": "ex:alice", "ex:age": "?oldAge"}],
  "insert": [{"@id": "ex:alice", "ex:age": 31}]
}'

Delete-Only

# Remove all email addresses for alice
fluree update '{
  "@context": {"ex": "http://example.org/"},
  "where": [{"@id": "ex:alice", "ex:email": "?email"}],
  "delete": [{"@id": "ex:alice", "ex:email": "?email"}]
}'

Bulk Conditional Update

# Set all "pending" users to "active"
fluree update '{
  "@context": {"ex": "http://example.org/"},
  "where": [{"@id": "?person", "ex:status": "pending"}],
  "delete": [{"@id": "?person", "ex:status": "pending"}],
  "insert": [{"@id": "?person", "ex:status": "active"}]
}'

From File

fluree update -f update.json
fluree update -f update.json -m "Updated user statuses"

SPARQL UPDATE (via server)

# Requires a running server (fluree server start)
fluree update -e 'PREFIX ex: <http://example.org/>
DELETE { ex:alice ex:age ?oldAge }
INSERT { ex:alice ex:age 31 }
WHERE { ex:alice ex:age ?oldAge }'

Pipe from stdin

cat update.json | fluree update

Target a specific ledger

fluree update production -f migration.json

Output

Committed t=3, 4 flakes

With remote mode, the full server response is printed as JSON.

Format Detection

The format is auto-detected using this priority:

1. Explicit flag (--format) — always wins
2. File extension (when using -f or a positional file path):
   • .json, .jsonld → JSON-LD
   • .rq, .ru, .sparql → SPARQL UPDATE
3. Content sniffing:
   • Valid JSON (full parse, not just first character) → JSON-LD
   • Starts with INSERT, DELETE, PREFIX, or BASE → SPARQL UPDATE

Override with --format jsonld or --format sparql.

Comparison with Insert and Upsert

See Also

• insert - Insert new data
• upsert - Insert or replace existing data
• Update (WHERE/DELETE/INSERT) - Full transaction syntax guide
• query - Query data

fluree query

Query a ledger.

Usage

fluree query [LEDGER] [QUERY] [OPTIONS]

Arguments

Options

Description

Executes a query against a ledger. Supports both SPARQL and JSON-LD 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"}}'

Format is auto-detected if not specified:

• Contains SELECT, CONSTRUCT, ASK, or DESCRIBE → SPARQL
• Otherwise → JSON-LD

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.

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

• history - View entity change history
• export - Export all data

fluree history

Show change history for an entity.

Usage

fluree history <ENTITY> [OPTIONS]

Arguments

Options

Description

Shows the change history for a specific entity across transactions. Each change shows:

• t - Transaction number
• op - Operation: + (assert) or - (retract)
• predicate - The property that changed (if not filtered)
• value - The value asserted or retracted

Prefix Expansion

Entity IRIs can use stored prefixes:

# First, add a prefix
fluree prefix add ex http://example.org/

# Then use compact IRI
fluree history ex:alice

Or use the full IRI:

fluree history http://example.org/alice

Examples

# Show all changes to an entity
fluree history ex:alice

# Show changes in JSON format
fluree history ex:alice --format json

# Filter to specific predicate
fluree history ex:alice -p ex:name

# Show changes in a time range
fluree history ex:alice --from 1 --to 5

# Query specific ledger
fluree history ex:alice --ledger production

Output

Table (default)

┌───┬────┬─────────────────────────────────┬─────────────┐
│ t │ op │ predicate                       │ value       │
├───┼────┼─────────────────────────────────┼─────────────┤
│ 1 │ +  │ http://example.org/name         │ Alice       │
│ 1 │ +  │ http://example.org/age          │ 30          │
│ 2 │ -  │ http://example.org/name         │ Alice       │
│ 2 │ +  │ http://example.org/name         │ Alice Smith │
└───┴────┴─────────────────────────────────┴─────────────┘

JSON

[
  {"?t": 1, "?op": true, "?p": "http://example.org/name", "?v": "Alice"},
  {"?t": 1, "?op": true, "?p": "http://example.org/age", "?v": 30},
  {"?t": 2, "?op": false, "?p": "http://example.org/name", "?v": "Alice"},
  {"?t": 2, "?op": true, "?p": "http://example.org/name", "?v": "Alice Smith"}
]

CSV

t,op,predicate,value
1,+,http://example.org/name,Alice
1,+,http://example.org/age,30
2,-,http://example.org/name,Alice
2,+,http://example.org/name,Alice Smith

See Also

• prefix - Manage prefix mappings
• log - Show commit history
• query - Run custom queries

fluree export

Export ledger data as Turtle, N-Triples, N-Quads, TriG, or JSON-LD.

Usage

fluree export [LEDGER] [OPTIONS]

Arguments

Options

Formats

turtle / jsonld (data snapshot)

Exports a point-in-time snapshot of all triples in the ledger. Output goes to stdout.

ledger (native pack)

Exports the full native ledger — all commits, transaction blobs, indexes, and dictionaries — as a .flpack file. This format preserves the complete history and can be imported into a new Fluree instance via fluree create <name> --from <file>.flpack.

The .flpack format uses the fluree-pack-v1 binary wire protocol (the same format used by fluree clone and fluree pull for network transfers).

All formats (Turtle, N-Triples, N-Quads, TriG, JSON-LD) read directly from the binary SPOT index with a novelty overlay, so export always includes the latest committed transactions — even those not yet persisted to index. Memory usage stays constant regardless of dataset size. JSON-LD streams one subject at a time, so memory is O(largest subject), not O(dataset).

Prefixes / Context

Turtle, TriG, and JSON-LD output use prefix compaction to produce compact, readable output. The prefix map is resolved in this order:

1. --context or --context-file (explicit override)
2. The ledger’s default context (set via fluree context set)
3. No prefixes (falls back to full IRIs)

The context format is a JSON object mapping prefixes to namespace IRIs:

{"ex": "http://example.org/", "schema": "http://schema.org/"}

Prerequisites

All export formats require a binary index. Ledgers that have only been created and inserted into (without an index build) cannot be exported. Run the server to trigger index building first.

Examples

# Export as Turtle (default) — uses ledger's default context for prefixes
fluree export > backup.ttl

# Export as Turtle with custom prefixes
fluree export --context '{"ex": "http://example.org/"}' > backup.ttl

# Export as Turtle with prefixes from a file
fluree export --context-file prefixes.json > backup.ttl

# Export as N-Triples (no prefixes, one triple per line)
fluree export --format ntriples > backup.nt

# Export as JSON-LD
fluree export --format jsonld > backup.jsonld

# Export all graphs as TriG
fluree export --all-graphs --format trig > backup.trig

# Export all graphs as N-Quads
fluree export --all-graphs --format nquads > backup.nq

# Export a specific named graph
fluree export --graph "http://example.org/g1" --format turtle > g1.ttl

# Export data as of a specific transaction number
fluree export --at 5 > snapshot-at-t5.ttl

# Export data as of an ISO-8601 datetime
fluree export --at "2024-06-15T12:00:00Z" > snapshot.ttl

# Export data as of a specific commit
fluree export --at abc123def456 > at-commit.ttl

# Export specific ledger
fluree export production > prod-backup.ttl

# Pipe to other tools
fluree export | grep "example.org"

Output

Turtle (default)

@prefix ex: <http://example.org/> .

ex:alice
    a ex:Person ;
    ex:name "Alice" .
ex:bob
    a ex:Person ;
    ex:name "Bob" .

N-Triples

<http://example.org/alice> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://example.org/Person> .
<http://example.org/alice> <http://example.org/name> "Alice" .

TriG (all graphs)

@prefix ex: <http://example.org/> .

ex:alice
    ex:name "Alice" .

GRAPH ex:g1 {
ex:bob
    ex:name "Bob" .
}

N-Quads (all graphs)

<http://example.org/alice> <http://example.org/name> "Alice" .
<http://example.org/bob> <http://example.org/name> "Bob" <http://example.org/g1> .

JSON-LD

{
  "@context": {
    "ex": "http://example.org/"
  },
  "@graph": [
    {"@id": "ex:alice", "@type": "ex:Person", "ex:name": "Alice"},
    {"@id": "ex:bob", "@type": "ex:Person", "ex:name": "Bob", "ex:age": {"@value": 25, "@type": "http://www.w3.org/2001/XMLSchema#long"}}
  ]
}

JSON-LD output uses prefix compaction from the context. Value encoding rules:

• Plain strings (xsd:string) → JSON string (no @type)
• Booleans → native JSON true/false
• Integers/longs → {"@value": 42, "@type": "xsd:long"} (explicit datatype)
• Decimals → {"@value": "3.14", "@type": "xsd:decimal"}
• Doubles → {"@value": 3.14, "@type": "xsd:double"}
• Language-tagged strings → {"@value": "Bonjour", "@language": "fr"}
• References → {"@id": "ex:other"}
• Single-cardinality properties are unwrapped (not in [])
• Multi-cardinality properties use arrays

API Usage

The export feature is available at the API level for upstream applications:

#![allow(unused)]
fn main() {
use fluree_db_api::export::ExportFormat;

// Turtle with default context
let stats = fluree.export("mydb")
    .format(ExportFormat::Turtle)
    .write_to(&mut writer)
    .await?;

// N-Quads with all graphs
let stats = fluree.export("mydb")
    .format(ExportFormat::NQuads)
    .all_graphs()
    .write_to(&mut writer)
    .await?;

// Turtle with custom prefixes
let stats = fluree.export("mydb")
    .format(ExportFormat::Turtle)
    .context(&json!({"ex": "http://example.org/"}))
    .write_to(&mut writer)
    .await?;

// JSON-LD with prefix compaction
let stats = fluree.export("mydb")
    .format(ExportFormat::JsonLd)
    .context(&json!({"ex": "http://example.org/"}))
    .write_to(&mut writer)
    .await?;

// Export a specific named graph
let stats = fluree.export("mydb")
    .format(ExportFormat::Turtle)
    .graph("http://example.org/g1")
    .write_to(&mut writer)
    .await?;

// Time-travel: export as of transaction t=5
let stats = fluree.export("mydb")
    .format(ExportFormat::Turtle)
    .as_of(TimeSpec::at_t(5))
    .write_to(&mut writer)
    .await?;

// Time-travel: export as of an ISO-8601 datetime
let stats = fluree.export("mydb")
    .format(ExportFormat::Turtle)
    .as_of(TimeSpec::at_time("2024-06-15T12:00:00Z"))
    .write_to(&mut writer)
    .await?;

// Convenience: write directly to stdout
let stats = fluree.export("mydb")
    .format(ExportFormat::Turtle)
    .to_stdout()
    .await?;
}

See Also

• context - Manage default JSON-LD context (prefix map)
• query - Run custom queries

fluree context

Manage the default JSON-LD context for a ledger.

Usage

fluree context <COMMAND>

Subcommands

Description

Each ledger can have a default context — a JSON object mapping prefixes to IRIs (e.g., {"ex": "http://example.org/"}). When a JSON-LD query is sent via the CLI and omits its own @context, the ledger’s default context is injected automatically. The HTTP API requires ?default-context=true to opt in per request, and fluree-db-api requires explicit opt-in via its default-context view builders.

Default context is populated automatically during bulk import (from Turtle @prefix declarations). This command allows reading or replacing it after the fact.

The context is stored in content-addressed storage (CAS) and referenced from the nameservice config. Updates use compare-and-set semantics, so concurrent writers are safely handled.

context get

Show the current default context.

fluree context get [LEDGER]

Examples

# Show context for active ledger
fluree context get

# Show context for a specific ledger
fluree context get mydb

Output (pretty-printed JSON):

{
  "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
  "rdfs": "http://www.w3.org/2000/01/rdf-schema#",
  "xsd": "http://www.w3.org/2001/XMLSchema#",
  "owl": "http://www.w3.org/2002/07/owl#",
  "ex": "http://example.org/"
}

If no default context has been set, a message is printed to stderr.

context set

Replace the default context with a new JSON object.

fluree context set [LEDGER] [OPTIONS]

If neither -e nor -f is provided, context is read from stdin.

The body can be either a bare JSON object or wrapped in {"@context": {...}} — both forms are accepted.

Examples

# Set inline
fluree context set mydb -e '{"ex": "http://example.org/", "foaf": "http://xmlns.com/foaf/0.1/"}'

# Set from file
fluree context set mydb -f context.json

# Pipe from stdin
cat context.json | fluree context set mydb

# Wrapped form also accepted
fluree context set mydb -e '{"@context": {"ex": "http://example.org/"}}'

See Also

• prefix — Manage CLI-local prefix mappings (stored in project config, not the ledger)
• export — Export ledger data (the default context drives prefix output)
• IRIs, namespaces, and JSON-LD @context — Conceptual overview

fluree log

Show commit log for a ledger.

Usage

fluree log [LEDGER] [OPTIONS]

Arguments

Options

Description

Displays the commit history for a ledger, similar to git log. Shows transaction numbers, timestamps, and commit details.

Examples

# Show full commit log
fluree log

# Show last 5 commits
fluree log -n 5

# One-line format
fluree log --oneline

# Specific ledger
fluree log production --oneline -n 10

Output

Full Format (default)

commit bafybeig2k5...
t: 3
Date: 2024-01-15T10:30:00Z

    Added new users

commit bafybeig7x3...
t: 2
Date: 2024-01-14T09:15:00Z

commit bafybeig9m1...
t: 1
Date: 2024-01-13T08:00:00Z

    Initial data load

One-line Format

bafybeig2k5 t=3 Added new users
bafybeig7x3 t=2
bafybeig9m1 t=1 Initial data load

See Also

• show - Show decoded contents of a specific commit
• info - Show ledger details
• history - Show entity change history

fluree show

Show the decoded contents of a commit — assertions and retractions with resolved IRIs.

Usage

fluree show <COMMIT> [OPTIONS]

Arguments

Options

Description

Displays the full decoded contents of a single commit, similar to git show. Each flake (assertion or retraction) is rendered with IRIs compacted using the ledger’s namespace prefix table.

The commit identifier can be:

• A transaction number prefixed with t: (e.g., t:5) as shown in fluree log output
• An abbreviated hex digest (minimum 6 characters) as shown in the storage directory or obtained from the txn-meta graph
• A full CID string (e.g., bagaybqabciq...)

Policy Filtering

When executed against a remote server (--remote), the returned flakes are filtered by the server’s data-auth policy. The identity is derived from the Bearer token and the policy class from the server’s default_policy_class configuration. Flakes the caller is not permitted to read are silently omitted, and the asserts/retracts counts reflect only the visible flakes.

Unlike the query endpoints, show does not support per-request policy overrides via headers or request body — it uses only the Bearer token identity and server-configured default policy class.

When executed locally (no --remote, or with --direct), fluree show operates with full local-admin access and no policy filtering is applied. This is consistent with other local CLI operations that read directly from storage.

Output Format

The output is a JSON object containing:

Each flake is a tuple: [subject, predicate, object, datatype, operation]

• operation: true = assert (added), false = retract (removed)
• Ref objects use "@id" as the datatype
• When metadata is present (language tag, list index, or named graph), a 6th element is appended: {"lang": "en", "i": 0, "graph": "ex:myGraph"}

Examples

# Show a commit by transaction number
fluree show t:5

# Show a commit by hex prefix
fluree show 3dd028

# Show a commit from a specific ledger
fluree show 0303b7 --ledger _system

# Show a commit on a remote server
fluree show t:5 --remote origin

# Show by hex prefix on remote with explicit ledger
fluree show 3dd028 --remote origin --ledger mydb

# Pipe to jq for filtering
fluree show 3dd028 | jq '.flakes[] | select(.[4] == true)'

Example Output

{
  "id": "bagaybqabciqd3ubikmk2zh6gjxngpgjja3vi5myleidf46htiybpswyy2665zra",
  "t": 40,
  "time": "2026-03-12T16:58:18.395474217+00:00",
  "size": 327,
  "previous": "bagaybqabciqc64dbbv46vrueddgqfrafgmo27u4fibkrvwdmr2g6ze4cbaeg23a",
  "asserts": 1,
  "retracts": 1,
  "@context": {
    "xsd": "http://www.w3.org/2001/XMLSchema#",
    "schema": "http://schema.org/",
    "f": "https://ns.flur.ee/db#"
  },
  "flakes": [
    ["urn:fsys:dataset:zoho3", "schema:dateModified", "2026-03-12T14:15:30Z", "xsd:string", false],
    ["urn:fsys:dataset:zoho3", "schema:dateModified", "2026-03-12T16:58:16Z", "xsd:string", true]
  ]
}

In this example, one property (dateModified) was updated: the old value was retracted (false) and the new value asserted (true).

See Also

• log - Show commit log (list of commits)
• history - Show change history for a specific entity
• info - Show ledger details

fluree index

Build or update the binary index for a ledger.

Usage

fluree index [LEDGER]

Arguments

Description

Performs incremental indexing when possible — merges only new commits into the existing index. Falls back to a full rebuild if incremental indexing isn’t possible (e.g., no prior index exists).

Run this after transactions to clear the novelty layer and speed up queries. For routine use this is preferred over reindex, which always rebuilds from scratch.

Examples

# Index the active ledger
fluree index

# Index a specific ledger
fluree index mydb

Output

Indexed mydb to t=15 (root: bafyreig...)

When to Use

• After bulk transactions — clears accumulated novelty so queries hit the optimized binary index instead of scanning in-memory flakes.
• Routine maintenance — keeps query performance consistent as data grows.
• After clone --no-indexes or pull --no-indexes — builds the local index that was skipped during transfer.

For a clean rebuild from commit history (e.g., suspected corruption), use reindex instead.

See Also

• reindex - Full rebuild from commit history
• Background indexing - Automatic indexing in the server
• Reindex API - Rust API reference

fluree reindex

Full reindex from commit history.

Usage

fluree reindex [LEDGER]

Arguments

Description

Rebuilds the binary index from scratch by replaying all commits in order. This is a heavier operation than index — use it when the index is corrupted, missing, or you want a guaranteed clean rebuild.

For routine indexing after transactions, prefer index.

Examples

# Reindex the active ledger
fluree reindex

# Reindex a specific ledger
fluree reindex mydb

Output

Reindexed mydb to t=15 (root: bafyreig...)

When to Use

• Suspected index corruption — query results seem wrong or incomplete.
• After schema or configuration changes that affect index structure.
• Clean slate — you want to guarantee the index matches the commit history exactly.

For incremental indexing (faster, merges only new commits), use index instead.

See Also

• index - Incremental index build
• Background indexing - Automatic indexing in the server
• Reindex API - Rust API reference

fluree config

Manage configuration settings.

Usage

fluree config <COMMAND>

Subcommands

Description

Manages configuration stored in .fluree/config.toml. Configuration uses dotted keys for nested values (e.g., storage.path).

Examples

Get a value

fluree config get storage.path

Output:

/custom/storage/path

Set a value

fluree config set storage.path /custom/storage/path

Output:

Set 'storage.path' = "/custom/storage/path"

List all values

fluree config list

Output:

storage.path = "/custom/storage/path"
storage.encryption = "aes256"

If no configuration is set:

(no configuration set)

Configuration File

Configuration is stored in .fluree/config.toml:

[storage]
path = "/custom/storage/path"
encryption = "aes256"

Errors

Getting a key that doesn’t exist:

error: configuration key 'nonexistent' is not set

See Also

• init - Initialize project directory
• prefix - Manage IRI prefixes

fluree config set-origins

Store a LedgerConfig blob in local CAS and update the ledger’s nameservice record to point to it via config_id.

This enables origin-based fluree pull (when no upstream remote is configured) and improves fluree clone --origin by allowing the remote to advertise multiple fallback origins.

Usage

fluree config set-origins <LEDGER> --file <PATH>

Arguments

Options

LedgerConfig File Format

The file is canonical JSON using compact f: keys (not JSON-LD):

{
  "f:origins": [
    { "f:priority": 10, "f:enabled": true, "f:transport": "http://localhost:8090", "f:auth": { "f:mode": "none" } }
  ],
  "f:replication": { "f:preferPack": true, "f:maxPackMiB": 64 }
}

Notes:

• f:transport is an origin base URL. The CLI normalizes it the same way as remotes: it will append /fluree if missing and will use GET /.well-known/fluree.json discovery when available.
• Auth requirements are declarative. Credentials are not stored in the LedgerConfig.

Current Limitations

• fluree pull via origins currently does not attach a Bearer token from any credential store, so only origins with f:auth.f:mode = "none" are usable for pull today.
• fluree clone --origin ... --token ... can use a Bearer token for origin fetch.

fluree prefix

Manage IRI prefix mappings.

Usage

fluree prefix <COMMAND>

Subcommands

Description

Manages IRI prefix mappings stored in .fluree/prefixes.json. These prefixes are used to expand compact IRIs in commands like history.

Examples

Add a prefix

fluree prefix add ex http://example.org/
fluree prefix add foaf http://xmlns.com/foaf/0.1/
fluree prefix add schema https://schema.org/

Output:

Added prefix: ex = <http://example.org/>

List prefixes

fluree prefix list

Output:

ex: <http://example.org/>
foaf: <http://xmlns.com/foaf/0.1/>
schema: <https://schema.org/>

If no prefixes are defined:

(no prefixes defined)

Add prefixes with: fluree prefix add <prefix> <iri>
Example: fluree prefix add ex http://example.org/

Remove a prefix

fluree prefix remove foaf

Output:

Removed prefix: foaf

Usage with History

Once prefixes are defined, you can use compact IRIs:

# Instead of:
fluree history http://example.org/alice

# Use:
fluree history ex:alice

IRI Best Practices

IRI namespaces should end with / or #:

# Good
fluree prefix add ex http://example.org/
fluree prefix add foaf http://xmlns.com/foaf/0.1/

# Warning (will still work but may cause issues)
fluree prefix add bad http://example.org

Storage

Prefixes are stored in .fluree/prefixes.json:

{
  "ex": "http://example.org/",
  "foaf": "http://xmlns.com/foaf/0.1/"
}

See Also

• history - Uses prefix expansion
• config - Manage other configuration

fluree token

Manage JWS tokens for authentication with Fluree servers.

Subcommands

fluree token create

Create a new JWS token for authenticating with Fluree servers.

Usage

fluree token create --private-key <KEY> [OPTIONS]

Options

Private Key Formats

Examples

# Create a token with full access
fluree token create --private-key 0x1234...abcd --all

# Create a token for specific ledgers (events/storage)
fluree token create --private-key @~/.fluree/key \
  --events-ledger mydb --storage-ledger mydb

# Create a token with data API read+write for specific ledgers
fluree token create --private-key @~/.fluree/key \
  --read-ledger mydb:main --write-ledger mydb:main

# Create a token with identity and audience
fluree token create --private-key @- \
  --identity did:example:alice \
  --audience https://api.example.com \
  --expires-in 7d

# Output as curl command
fluree token create --private-key 0x... --all --output curl

# View claims while creating
fluree token create --private-key 0x... --all --print-claims

fluree token keygen

Generate a new Ed25519 keypair for signing tokens.

Usage

fluree token keygen [OPTIONS]

Options

Examples

# Generate keypair in hex format
fluree token keygen

# Generate in JSON format with all representations
fluree token keygen --format json

# Save private key to file
fluree token keygen --output ~/.fluree/key

# Generate base58 format
fluree token keygen --format base58

Output

Hex format:

Private key: 0x1234567890abcdef...
Public key:  0xabcdef1234567890...
DID:         did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK

JSON format:

{
  "private_key": {
    "hex": "0x1234...",
    "base58": "z..."
  },
  "public_key": {
    "hex": "0xabcd...",
    "base58": "z..."
  },
  "did": "did:key:z6Mk..."
}

fluree token inspect

Decode and optionally verify a JWS token.

Usage

fluree token inspect <TOKEN> [OPTIONS]

Arguments

Options

Examples

# Inspect and verify a token
fluree token inspect eyJhbGciOiJFZERTQSI...

# Inspect without verification
fluree token inspect eyJ... --no-verify

# Output as JSON
fluree token inspect eyJ... --output json

# Read token from file
fluree token inspect @token.txt

Output

Pretty format:

Token Information
─────────────────────────────────────────────────────
Issuer:   did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK
Subject:  test@example.com
Issued:   2024-01-15 10:30:00 UTC
Expires:  2024-01-15 11:30:00 UTC

Permissions:
  Events:  all ledgers
  Storage: all ledgers

Signature: ✓ Valid

Token Scopes

Tokens can carry different permission scopes that control access to different server features:

The --all flag sets events, storage, read, and write access for all ledgers.

Back-compat: fluree.storage.* claims also grant data API read access for the same ledgers.

See Also

• auth - Store/manage tokens on remotes
• remote - Configure remote servers
• Authentication - Auth model, modes, and token claims
• fetch - Fetch from remotes (requires auth token)
• push - Push to remotes (requires auth token)

fluree auth

Manage authentication tokens for remote servers. Tokens are stored in .fluree/config.toml as part of the remote configuration.

Token values are never printed to stdout. The status command shows token presence, expiry, and identity only.

Subcommands

fluree auth status

Show the current authentication state for a remote, including token presence, expiry time, identity, and issuer.

Usage

fluree auth status [OPTIONS]

Options

Examples

# Show auth status (single remote)
fluree auth status

# Show auth status for a specific remote
fluree auth status --remote origin

Output

When a token is configured:

Auth Status:
  Remote: origin
  Token:  configured
  Expiry: 2026-02-15 12:00 UTC
  Identity: did:example:alice
  Issuer: did:key:z6Mk...
  Subject: alice@example.com

When no token is configured:

Auth Status:
  Remote: origin
  Token:  not configured
  hint: fluree auth login --remote origin

fluree auth login

Store a bearer token for a remote. The token is saved in .fluree/config.toml and will be sent as a Authorization: Bearer header on subsequent remote operations (fetch, pull, push, query --remote, etc.).

Usage

fluree auth login [OPTIONS]

Options

If --token is omitted, you will be prompted to paste the token interactively.

Token Input Methods

Examples

# Store a token (prompted interactively)
fluree auth login

# Store a token from a value
fluree auth login --token eyJhbGciOiJFZERTQSI...

# Store a token from a file
fluree auth login --token @~/.fluree/my-token.jwt

# Pipe a token from another command
fluree token create --private-key @~/.fluree/key --all | fluree auth login --token @-

# Login to a specific remote
fluree auth login --remote staging --token @token.jwt

Output

Token stored for remote 'origin'
  Expiry: 2026-02-15 12:00 UTC
  Identity: did:example:alice

fluree auth logout

Clear the stored token for a remote.

Usage

fluree auth logout [OPTIONS]

Options

Examples

# Clear token for the default remote
fluree auth logout

# Clear token for a specific remote
fluree auth logout --remote staging

Output

Token cleared for remote 'origin'

Token Types

The auth command stores bearer tokens that are sent in the Authorization header. Fluree supports two types of bearer tokens:

Ed25519 JWS Tokens (did:key)

Created locally with fluree token create. These contain an embedded JWK (JSON Web Key) in the token header and are verified against the embedded public key. The issuer is a did:key identifier derived from the signing key.

# Create and store a token in one step
fluree token create --private-key @~/.fluree/key --all | fluree auth login --token @-

OIDC/JWKS Tokens (RS256)

Issued by external identity providers (OIDC). These contain a kid (Key ID) in the token header and are verified by the server against the provider’s JWKS (JSON Web Key Set) endpoint. The issuer is the provider’s URL.

The server must be configured with --jwks-issuer to trust these tokens. See Configuration.

Remote Resolution

When --remote is omitted:

• If exactly one remote is configured, it is used automatically.
• If no remotes are configured, an error is shown with a hint to use fluree remote add.
• If multiple remotes are configured, an error asks you to specify --remote <name>.

Security Notes

• Tokens are stored in plaintext in .fluree/config.toml. Protect this file with appropriate filesystem permissions.
• The status command never displays the raw token value.
• On 401 errors from remote operations, the CLI checks token expiry and suggests fluree auth login if the token appears expired.

OIDC login flow

When a remote is configured with auth.type = "oidc_device" (auto-discovered from the server’s /.well-known/fluree.json), fluree auth login runs an OIDC interactive login flow and then exchanges the IdP token for a Fluree-scoped Bearer token:

1. Discovers OIDC endpoints from the configured issuer
2. Chooses the flow based on IdP support:
   • If the IdP discovery document includes device_authorization_endpoint: use OAuth device-code (prints a URL + code and polls).
   • Otherwise, if it includes authorization_endpoint: use OAuth authorization-code + PKCE (opens a browser and receives a localhost callback).
3. Exchanges the IdP token for a Fluree-scoped Bearer token via the server’s exchange_url
4. Stores the token (and optional refresh token) in the remote config

Cognito note (Authorization Code + PKCE)

AWS Cognito does not publish device_authorization_endpoint, so the CLI will use authorization-code + PKCE.

Cognito requires the callback URL to be pre-allowlisted (no wildcard ports). Allowlist:

• http://127.0.0.1:8400/callback
• http://127.0.0.1:8401/callback
• http://127.0.0.1:8402/callback
• http://127.0.0.1:8403/callback
• http://127.0.0.1:8404/callback
• http://127.0.0.1:8405/callback

If your app only allowlists one callback URL, configure a fixed port with redirect_port in /.well-known/fluree.json (or set FLUREE_AUTH_PORT locally) and allowlist that single callback URL.

On subsequent 401 errors, the CLI automatically attempts a silent refresh using the stored refresh token before prompting for re-login.

See Auth contract (CLI ↔ Server) for the full protocol specification.

See Also

• token - Create and inspect JWS tokens
• remote - Manage remote servers
• Authentication - Auth model, modes, and token claims
• Auth contract (CLI ↔ Server) - Discovery, exchange, and refresh protocol
• Configuration - Server authentication configuration

fluree remote

Manage remote servers for syncing ledgers.

Subcommands

fluree remote add

Add a remote server configuration.

Usage

fluree remote add <NAME> <URL> [OPTIONS]

Arguments

Options

Examples

# Add a remote without authentication
fluree remote add origin http://localhost:8090

# Add a remote with inline token
fluree remote add prod https://api.example.com --token eyJ...

# Add a remote with token from file
fluree remote add staging https://staging.example.com --token @~/.fluree/staging-token

fluree remote remove

Remove a remote configuration.

Usage

fluree remote remove <NAME>

Arguments

Examples

fluree remote remove origin

fluree remote list

List all configured remotes.

Usage

fluree remote list

Output

┌─────────┬─────────────────────────────┬───────┐
│ Name    │ URL                         │ Auth  │
├─────────┼─────────────────────────────┼───────┤
│ origin  │ http://localhost:8090       │ none  │
│ prod    │ https://api.example.com     │ token │
└─────────┴─────────────────────────────┴───────┘

fluree remote show

Show detailed information about a remote.

Usage

fluree remote show <NAME>

Arguments

Output

Remote:
  Name: origin
  Type: HTTP
  URL:  http://localhost:8090
  Auth: token configured

See Also

• upstream - Configure upstream tracking
• clone - Clone a ledger from a remote
• fetch - Fetch refs from a remote
• token - Create authentication tokens

fluree upstream

Manage upstream tracking configuration for ledgers.

Upstream configuration links a local ledger to a remote ledger, enabling pull and push operations.

Subcommands

fluree upstream set

Configure a local ledger to track a remote ledger.

Usage

fluree upstream set <LOCAL> <REMOTE> [OPTIONS]

Arguments

Options

Examples

# Track remote ledger with same name
fluree upstream set mydb origin

# Track a differently-named remote ledger
fluree upstream set mydb origin --remote-alias production-db

# Enable auto-pull on fetch
fluree upstream set mydb origin --auto-pull

fluree upstream remove

Remove upstream tracking for a ledger.

Usage

fluree upstream remove <LOCAL>

Arguments

Examples

fluree upstream remove mydb

fluree upstream list

List all configured upstream tracking relationships.

Usage

fluree upstream list

Output

┌────────────┬─────────┬────────────────┬───────────┐
│ Local      │ Remote  │ Remote Alias   │ Auto-Pull │
├────────────┼─────────┼────────────────┼───────────┤
│ mydb:main  │ origin  │ mydb           │ no        │
│ test:main  │ staging │ test-ledger    │ yes       │
└────────────┴─────────┴────────────────┴───────────┘

See Also

• remote - Configure remote servers
• clone - Clone a ledger from a remote
• pull - Pull from upstream
• push - Push to upstream

fluree fetch

Fetch refs from a remote server (similar to git fetch).

Usage

fluree fetch <REMOTE>

Arguments

Description

Fetches ledger references from a remote server and updates local tracking data. This does not modify your local ledgers - it only updates what the CLI knows about the remote’s state.

This is a replication operation. It requires a Bearer token with root / storage-proxy permissions (fluree.storage.*). If you only have permissioned/query access to a ledger, you should use fluree track (or --remote) and run queries/transactions against the remote instead.

After fetching, you can use pull to download and apply new commits to your local ledger.

Examples

# Fetch from origin
fluree fetch origin

# Typical workflow
fluree fetch origin
fluree pull mydb

Output

Fetching from 'origin'...
Updated:
  mydb -> t=42
  testdb -> t=15
Already up to date: 2 ledger(s) unchanged

If no ledgers are found:

Fetching from 'origin'...
No ledgers found on remote.

See Also

• remote - Configure remote servers
• clone - Clone a ledger from a remote
• pull - Pull commits from upstream
• push - Push to upstream

fluree pull

Pull commits from upstream and apply them to the local ledger, similar to git pull.

Usage

fluree pull [OPTIONS] [LEDGER]

Arguments

Description

Downloads new commits from the configured upstream and applies them to the local ledger:

1. Queries the remote for its current head (t and commit ContentId)
2. Compares with the local head; exits early if already up to date
3. Attempts bulk download of missing commits (and by default index artifacts) via the pack protocol (single streaming request)
4. Falls back to paginated JSON export if the server does not support pack
5. Stores all commit and transaction blobs to local CAS
6. When index data is requested and transferred, advances the local index head to match the remote
7. Advances the local commit head to the remote head

Index transfer

As with clone, pull uses the pack protocol to request index artifacts by default when the remote has an index. Use --no-indexes to transfer only new commits and txn blobs. For large estimated transfers (~1 GiB or more), the CLI prompts for confirmation before streaming.

Transport

Pull uses the same pack protocol as clone – see clone: Transport for details.

Origin-based pull

When no upstream remote is configured, pull falls back to origin-based fetching if a LedgerConfig with origins is set on the ledger (see fluree config set-origins). This uses the same pack-first / CID-walk-fallback transport as fluree clone --origin.

This is a replication operation. It requires a Bearer token with root / storage-proxy permissions (fluree.storage.*). If you only have permissioned/query access to a ledger, you should use fluree track (or --remote) and run queries/transactions against the remote instead.

The ledger must have an upstream configured (see fluree upstream set), or a LedgerConfig with origins (see fluree config set-origins).

Restart safety: If interrupted, the local head reflects the last successful import. The next pull resumes from the local head automatically.

Examples

# Pull changes for active ledger
fluree pull

# Pull changes for specific ledger
fluree pull mydb

# Pull commits only (skip index transfer)
fluree pull --no-indexes mydb

Output

Successful pull (with index data when remote has an index):

Pulling 'mydb:main' from 'origin' (local t=10, remote t=42)...
✓ 'mydb:main' pulled 32 commit(s) via pack (new head t=42)

With --no-indexes, only commits (and referenced txn blobs) are transferred; the message does not include index artifact counts.

Already up to date:

✓ 'mydb:main' is already up to date

No upstream configured:

error: no upstream configured for 'mydb:main'
  hint: fluree upstream set mydb:main <remote>

Errors

Limitations

• Index head vs commit head: When you use --no-indexes, the local index head is not updated. Queries still work but may replay more novelty; run fluree reindex to bring the index up to the current commit head.
• Graph source indexes not replicated: Graph source snapshots (BM25/vector/geo, etc.) are not replicated by fluree pull yet. Rebuild graph source indexes in the target environment as needed.

See Also

• clone - Clone a ledger from a remote server
• upstream - Configure upstream tracking
• fetch - Fetch refs without modifying local ledger
• push - Push local changes to upstream

fluree push

Push local ledger changes to upstream remote, similar to git push.

Usage

fluree push [LEDGER]

Arguments

Description

Pushes local commits to the configured upstream remote by uploading the commit v2 bytes to the server.

The ledger must have an upstream configured (see fluree upstream set).

The push uses strict sequencing + CAS semantics:

• The server rejects the push if the remote head is not in your local history (diverged) or if the remote is ahead.
• The server also rejects the push if the first commit’s t does not match the server’s next-t.

Unlike fetch/pull, this is not a storage-proxy replication operation. It requires write permissions for the ledger (Bearer token with fluree.ledger.write.* claims) and the server validates the pushed commits like normal transactions.

If a pushed commit contains retractions, the server enforces a strict invariant: each retraction must target a fact that is currently asserted at that point in the push batch. (List retractions require exact list-index metadata match.)

Examples

# Push active ledger
fluree push

# Push specific ledger
fluree push mydb

Output

Successful push:

Pushing 'mydb:main' to 'origin'...
✓ 'mydb:main' pushed 3 commit(s) (new head t=42)

Push rejected (remote is ahead):

Pushing 'mydb:main' to 'origin'...
error: push rejected; remote is ahead (local t=10, remote t=42). Pull first.

No upstream configured:

error: no upstream configured for 'mydb:main'
  hint: fluree upstream set mydb:main <remote>

Errors

Workflow

Typical sync workflow:

# Configure remote and upstream (one time)
fluree remote add origin https://api.example.com --token @~/.fluree/token
fluree upstream set mydb origin

# Daily workflow
fluree pull mydb        # Get latest changes
# ... make local changes ...
fluree push mydb        # Push your changes

See Also

• clone - Clone a ledger from a remote
• upstream - Configure upstream tracking
• pull - Pull changes from upstream
• fetch - Fetch refs without modifying local ledger

fluree publish

Publish a local ledger to a remote server. Creates the ledger on the remote if it doesn’t exist, pushes all local commits, and configures upstream tracking for subsequent push/pull.

Usage

fluree publish <REMOTE> [LEDGER] [OPTIONS]

Arguments

Options

Description

fluree publish is the reverse of fluree clone. It takes a locally-created ledger and pushes it to a remote server in a single operation:

1. Checks if the ledger exists on the remote (GET /exists)
2. Creates it if not (POST /create)
3. Pushes all local commits (POST /push)
4. Configures upstream tracking so subsequent fluree push and fluree pull work

This is intended for the “create locally, deploy to server” workflow. If the remote ledger already has data (t > 0), the command will fail — use fluree push instead for incremental updates.

Examples

# Publish active ledger to origin
fluree publish origin

# Publish a specific ledger
fluree publish origin mydb

# Publish with a different name on the remote
fluree publish origin mydb --remote-name production-db

# Typical workflow: create locally, develop, then publish
fluree create mydb
fluree insert mydb -e '{"@id": "ex:test", "ex:name": "Test"}'
fluree publish origin mydb

Prerequisites

• A remote must be configured: fluree remote add origin <url>
• The remote must support the Fluree HTTP API (see Server implementation guide)
• A valid auth token if the remote requires authentication: fluree auth login --remote origin

After Publishing

Once published, the ledger has upstream tracking configured. Use standard sync commands:

# Push new local commits to remote
fluree push

# Pull remote changes
fluree pull

See Also

• push - Push incremental commits to upstream
• pull - Pull changes from upstream
• clone - Clone a remote ledger locally (reverse of publish)
• remote - Manage remote server configuration
• upstream - Manage upstream tracking
• export - Export ledger as .flpack for file-based transfer

fluree clone

Clone a ledger from a remote server, similar to git clone.

Usage

# Named-remote clone
fluree clone [OPTIONS] <REMOTE> <LEDGER>

# Origin-based clone (no pre-configured remote)
fluree clone --origin <URI> [--token <TOKEN>] [OPTIONS] <LEDGER>

Arguments

Description

Downloads all commits from a remote ledger and creates a local copy:

1. Verifies the remote ledger exists and has commits
2. Creates a local ledger with the same name as on the remote
3. Attempts bulk download via the pack protocol (single streaming request)
4. Falls back to paginated JSON export if the server does not support pack
5. Stores all commit and transaction blobs to local CAS
6. By default, also transfers binary index artifacts when the remote has an index (see Index transfer)
7. Sets the local commit head (and index head when index data was transferred) to match the remote
8. Configures the remote as upstream for future pull/push (named-remote only)

Index transfer

When using the pack protocol, the CLI requests index artifacts by default so the local ledger is query-ready without a full reindex. The server sends missing commit blobs, txn blobs, and binary index artifacts (dictionaries, branches, leaves) in one stream.

• Use --no-indexes to transfer only commits and txn blobs. This reduces transfer size and time; afterward, run fluree reindex to build the index locally if needed.
• For large transfers (estimated size above ~1 GiB), the CLI prompts: “Estimated transfer size: ~X. This may take several minutes. Continue? [Y/n]”. Answer n to abort or to re-request without index data (commits-only).
• If the remote has no index yet (e.g. a fresh ledger), only commits and txns are transferred regardless of the flag.

Transaction transfer

Every commit references an original transaction blob — the raw request (JSON-LD insert/update or SPARQL Update) that produced the commit. By default, fluree clone downloads these so the local ledger has a complete audit trail of the original payloads.

• Use --no-txns to skip transaction blobs entirely. The commit chain is still cloned and remains valid and verifiable; only the original request payloads are missing.
• The materialized ledger state (what queries return) is reconstructable from commits + indexes alone — transactions are not needed for query answering.
• With --no-txns, operations that need the original request payload (e.g., fluree show --flakes for transaction-level inspection, or re-running a transaction against a branch) will fail locally for those transactions. Anything that only reads materialized state is unaffected.
• Combine with --no-indexes for the smallest possible clone (fluree clone --no-indexes --no-txns origin mydb), useful for minimal verification / auditing of the commit chain only.

Transport

The CLI uses the pack protocol (fluree-pack-v1) as the primary transport for clone and pull. Pack transfers all missing CAS objects (commits + txn blobs, and by default index artifacts) in a single streaming HTTP request, avoiding per-object round-trips.

If the remote server does not support the pack endpoint (returns 404, 405, 406, or 501), the CLI automatically falls back to:

• Named-remote mode: paginated JSON export via GET /commits/{ledger} (500 commits per page)
• Origin mode: CID chain walk via GET /storage/objects/{cid} (one round-trip per commit)

This fallback is transparent – no user action is required.

Origin-based clone

The --origin flag enables CID-based clone from a server URL without pre-configuring a named remote:

fluree clone --origin http://localhost:8090 mydb
fluree clone --origin https://api.example.com --token @~/.fluree/token mydb

This mode:

1. Fetches the NsRecord from the origin to discover the head commit CID
2. Optionally upgrades to a multi-origin fetcher if a LedgerConfig is advertised
3. Downloads commits via pack (or CID chain walk as fallback)
4. Stores the LedgerConfig locally for future origin-based pull
5. Does not configure upstream tracking (use fluree upstream set manually)

This is a replication operation. It requires a Bearer token with root / storage-proxy permissions (fluree.storage.*). If you only have permissioned/query access to a ledger, you should use fluree track (or --remote) and run queries/transactions against the remote instead.

Idempotent CAS writes: If interrupted mid-clone, CAS blob writes are idempotent. Re-running the clone command will re-fetch all pages (duplicate writes are harmless). The local head is only set after all data is downloaded.

Examples

# Clone a ledger from a configured remote
fluree clone origin mydb

# Full workflow: add remote, then clone
fluree remote add production https://api.example.com --token @~/.fluree/token
fluree clone production customers

# Origin-based clone (no remote setup needed)
fluree clone --origin http://localhost:8090 mydb

# Origin-based clone with auth
fluree clone --origin https://api.example.com --token @~/.fluree/token mydb

# Clone without index data (faster; run fluree reindex afterward if needed)
fluree clone --no-indexes origin mydb

# Clone commits + indexes but skip original transaction payloads
fluree clone --no-txns origin mydb

# Smallest possible clone — commits only (no indexes, no transactions)
fluree clone --no-indexes --no-txns origin mydb

Output

Successful clone (via pack, with index data):

Cloning 'mydb:main' from 'origin' (remote t=1042)...
  fetched 2084 object(s) via pack
✓ Cloned 'mydb:main' (1042 commits, head t=1042)
  → upstream set to 'origin/mydb:main'

With --no-indexes (commits and txns only), the object count will be lower and the local index head is not set until you run fluree reindex.

Successful clone (fallback to paginated export):

Cloning 'mydb:main' from 'origin' (remote t=1042)...
  fetched 500 commits...
  fetched 1000 commits...
  fetched 1042 commits...
✓ Cloned 'mydb:main' (1042 commits, head t=1042)
  → upstream set to 'origin/mydb:main'

Origin-based clone:

Cloning 'mydb:main' from 'http://localhost:8090' (remote t=50)...
  fetched 100 object(s) via pack
✓ Cloned 'mydb:main' (50 commit(s), head t=50)

Remote ledger has no commits:

Remote ledger 'mydb:main' has no commits (t=0), nothing to clone.

Errors

Limitations

• Post-clone indexing: If you used --no-indexes, run fluree reindex to build a binary index locally. Without an index, queries replay from commits and can be slow for large ledgers. When index data is transferred by default (no --no-indexes), the local index head is set and no reindex is needed for the core ledger.
• Missing transactions: If you used --no-txns, the original transaction payloads for historical commits are permanently unavailable on the local clone (re-pull will not fetch them unless you explicitly re-clone without the flag). The ledger state remains queryable; only transaction-level inspection and replay are affected.
• Graph source indexes not replicated: Graph source snapshots (BM25/vector/geo, etc.) are not replicated by fluree clone yet. After cloning, rebuild graph source indexes in the target environment as needed.

See Also

• pull - Pull new commits from upstream
• push - Push local commits to upstream
• remote - Configure remote servers
• upstream - Configure upstream tracking

fluree track

Track a remote ledger without storing local data. Tracked ledgers route reads and writes to the configured remote server while keeping a lightweight record locally so you can use short aliases and the active-ledger shortcut.

Usage

fluree track <SUBCOMMAND>

Subcommands

fluree track add

Start tracking a remote ledger under a local alias.

Usage:

fluree track add <LEDGER> [--remote <NAME>] [--remote-alias <NAME>]

Arguments:

Options:

Examples:

# Track a remote ledger using the same name locally
fluree track add production --remote origin

# Use a different local alias
fluree track add prod --remote origin --remote-alias production

fluree track remove

Stop tracking a remote ledger. Local data is not affected (tracked ledgers have none).

Usage:

fluree track remove <LEDGER>

fluree track list

List all currently tracked ledgers and the remote each resolves to.

Usage:

fluree track list

fluree track status

Show status of tracked ledger(s) by querying the configured remote for each — commit t, index t, and head IDs.

Usage:

fluree track status [LEDGER]

Examples:

# Status of all tracked ledgers
fluree track status

# Status for a single tracked ledger
fluree track status production

Description

A tracked ledger is a local pointer to a remote ledger. Queries, transactions, and most administrative commands against a tracked alias are transparently forwarded to the remote. This lets you work against a hosted ledger using the same CLI flow as a local ledger — including the active-ledger shortcut (fluree use), without syncing commit/index data to disk.

Use fluree clone instead when you need a full local copy of a remote ledger’s data.

See Also

• remote - Manage named remote servers
• clone - Clone a remote ledger locally (with data)
• use - Switch active ledger
• list - List local and tracked ledgers

server

Manage the Fluree HTTP server from the CLI. The server inherits the same .fluree/ context (config file, storage path) as the CLI — one directory, two modes of interaction.

Subcommands

Common Options

These options are available on run, start, and restart:

--storage-path and --connection-config are mutually exclusive. Use --storage-path for local file storage or --connection-config for remote backends (S3, DynamoDB, split storage). See Configuration for details.

When no flags are provided, the server discovers its configuration using the same search as the CLI: it walks up from the current working directory looking for a .fluree/config.toml (or config.jsonld), then falls back to the global Fluree config directory ($FLUREE_HOME, or the platform config directory — see Configuration). Server settings live under the [server] section. The CLI’s --config flag is also honored.

run

Run the server in the foreground. Logs go to stderr. Press Ctrl-C for graceful shutdown.

# Start with defaults from config.toml
fluree server run

# Override listen address
fluree server run --listen-addr 127.0.0.1:9090

# S3 + DynamoDB backend
fluree server run --connection-config /etc/fluree/connection.jsonld

# Pass through advanced server flags
fluree server run -- --cors-enabled --indexing-enabled

start

Start the server as a background daemon. Writes PID and metadata to .fluree/ and redirects output to .fluree/server.log.

# Start in background
fluree server start

# Preview resolved config without starting
fluree server start --dry-run

# Start with overrides
fluree server start --listen-addr 0.0.0.0:8090 --log-level debug

The --dry-run flag prints the fully resolved configuration (config file + env + flag overrides merged) without actually starting the server. Useful for debugging “why is it using port X?”.

stop

Stop a backgrounded server by sending SIGTERM and waiting for graceful shutdown (up to 10 seconds).

fluree server stop

# Force kill after timeout
fluree server stop --force

status

Check whether the server is running. Shows PID, listen address, uptime, storage path, and performs an HTTP health check.

fluree server status

Example output:

ok: Server is running
  pid:          12345
  listen_addr:  0.0.0.0:8090
  storage_path: /path/to/.fluree/storage
  started_at:   2026-02-16T10:30:00Z
  uptime:       2h 15m 30s
  health:       ok
  log:          /path/to/.fluree/server.log

When using --connection-config, the status shows the connection config path instead of the storage path:

ok: Server is running
  pid:          12345
  listen_addr:  0.0.0.0:8090
  connection:   /etc/fluree/connection.jsonld
  started_at:   2026-02-16T10:30:00Z
  uptime:       2h 15m 30s
  health:       ok

restart

Stop and restart a backgrounded server. Recovers the original arguments from .fluree/server.meta.json. New flag overrides can be applied on restart.

fluree server restart

# Restart with a different log level
fluree server restart --log-level debug

logs

View server log output from .fluree/server.log.

# Last 50 lines (default)
fluree server logs

# Last 100 lines
fluree server logs -n 100

# Follow (like tail -f)
fluree server logs -f

Auto-Routing

When a local server is running (started via fluree server start), CLI commands that support remote execution are automatically routed through the server’s HTTP API. This applies to:

• fluree query
• fluree insert
• fluree upsert
• fluree list
• fluree info

The CLI detects the running server by checking .fluree/server.meta.json and verifying the PID is alive. When auto-routing is active, you’ll see a hint on stderr:

  server: routing through local server at 0.0.0.0:8090 (use --direct to bypass)

Opting out

Use the --direct global flag to bypass auto-routing and execute directly via the CLI’s file-based path:

# Route through server (default when server is running)
fluree query 'SELECT * WHERE { ?s ?p ?o } LIMIT 10'

# Bypass server, execute directly
fluree query --direct 'SELECT * WHERE { ?s ?p ?o } LIMIT 10'

Crash detection

If the server has crashed or been killed, the CLI detects the stale PID and falls back to direct execution with a notice:

  notice: local server (pid 12345) is no longer running; executing directly

Use fluree server status to check server health, or fluree server logs to view crash output.

Runtime Files

When a background server is running, these files are created in the .fluree/ data directory:

These files are cleaned up automatically by fluree server stop.

Configuration

The server uses the same config file as the CLI (discovered via walk-up or global fallback — see above). Server-specific settings live under the [server] section:

[server]
listen_addr = "0.0.0.0:8090"
storage_path = "/var/lib/fluree"
log_level = "info"
cors_enabled = true
# cache_max_mb = 4096  # global cache budget (MB); default: tiered fraction of RAM (30% <4GB, 40% 4-8GB, 50% ≥8GB)

[server.indexing]
enabled = true
reindex_min_bytes = 100_000
# reindex_max_bytes defaults to 20% of system RAM; uncomment to override
# reindex_max_bytes = 536_870_912  # 512 MB

For S3/DynamoDB backends, use connection_config instead of storage_path:

[server]
connection_config = "/etc/fluree/connection.jsonld"
cache_max_mb = 4096

[server.indexing]
enabled = true

Indexing settings live under the [server.indexing] subsection, not directly on [server]. Authentication settings similarly use [server.auth.events], [server.auth.data], etc.

See Configuration for the full list of server options.

Feature Flags

The server subcommand requires the server Cargo feature (enabled by default). If compiled without it:

fluree server run
# error: server support not compiled. Rebuild with `--features server`.

For S3/DynamoDB support via --connection-config, the aws feature must be enabled:

cargo build -p fluree-db-cli --features aws

Without this feature, S3 storage configs in the connection config will produce a clear error at startup.

fluree memory

Developer memory — store and recall facts, decisions, and constraints.

This page is the CLI command reference. For conceptual background, IDE setup, team workflows, and the full schema, see the Memory section of the docs.

Usage

fluree memory <COMMAND>

Subcommands

Description

The memory system stores project knowledge as RDF triples in a dedicated __memory Fluree ledger. Memories persist across sessions and are searchable by keyword-scored recall.

Run fluree memory init before using other memory commands. The MCP server auto-initializes on first tool call.

fluree memory init

Initialize the memory store and optionally configure MCP for detected AI coding tools. Idempotent — safe to run multiple times.

fluree memory init [OPTIONS]

Options

What init does

1. Creates the __memory ledger and transacts the memory schema.
2. Creates .fluree-memory/ at the project root with repo.ttl, .gitignore, and .local/user.ttl.
3. Migrates existing memories — if the ledger already has memories (e.g., from a pre-TTL version), they are exported to the appropriate .ttl files.
4. Detects AI coding tools (Claude Code, Cursor, VS Code, Windsurf, Zed) and offers to install MCP config for each.

Example

$ fluree memory init

Memory store initialized at /path/to/project/.fluree-memory

Repo memories are stored in .fluree-memory/repo.ttl (git-tracked).
Commit this directory to share project knowledge with your team.

Detected AI coding tools:
  - Claude Code (already configured)
  - Cursor
  - VS Code (Copilot) (already configured)

Install MCP config for Cursor? [Y/n] Y
  Installed: .cursor/mcp.json
  Installed: .cursor/rules/fluree_rules.md

Configured 1 tool.

With --yes: auto-confirms all installations without prompting. In a non-interactive shell (piped stdin) without --yes, MCP installation is skipped with a message.

fluree memory add

Store a new memory.

fluree memory add [OPTIONS]

Options

Examples

# Store a fact
fluree memory add --kind fact --text "Tests use cargo nextest" --tags testing,cargo

# Store a constraint with severity
fluree memory add --kind constraint --text "Never suppress dead code with underscore prefix" \
  --tags code-style --severity must

# Store from stdin
echo "The index format uses postcard encoding" | fluree memory add --kind fact --tags indexer

# Store a decision with rationale and alternatives
fluree memory add --kind decision --text "Use postcard for compact index encoding" \
  --rationale "no_std compatible, smaller output than bincode" \
  --alternatives "bincode, CBOR, MessagePack" --refs fluree-db-indexer/

# Store a fact with rationale
fluree memory add --kind fact --text "PSOT queries return supersets — post-filter required" \
  --rationale "B-tree range scan can't filter on non-key predicates" --tags query,index

Output (text):

Stored memory: mem:fact-01JDXYZ5A2B3C4D5E6F7G8H9J0

Secret detection

If the content contains secrets (API keys, passwords, tokens, connection strings), they are automatically redacted and a warning is printed:

  warning: secrets detected in content — storing redacted version.
  Original content contained sensitive data that was replaced with [REDACTED].
Stored memory: mem:fact-01JDXYZ...

fluree memory recall

Search and retrieve relevant memories ranked by score.

fluree memory recall <QUERY> [OPTIONS]

Arguments

Options

Examples

# Basic recall (returns top 3)
fluree memory recall "how to run tests"

# Get the next page
fluree memory recall "how to run tests" --offset 3

# Return up to 10 results
fluree memory recall "error handling" -n 10

# Filter by kind and tags
fluree memory recall "error handling" --kind constraint --tags errors

# Output as XML context (for LLM injection)
fluree memory recall "testing patterns" --format context

Output (text):

Recall: "how to run tests" (2 matches)

1. [score: 13.0] mem:fact-01JDXYZ...
   Tests use cargo nextest
   Tags: testing, cargo

2. [score: 8.0] mem:fact-01JDABC...
   Integration tests use assert_cmd + predicates
   Tags: testing

  (showing results 1–3; use --offset 3 for more)

Output (context):

<memory-context>
  <memory id="mem:fact-01JDXYZ..." kind="fact" score="13.0">
    <content>Tests use cargo nextest</content>
    <tags>testing, cargo</tags>
  </memory>
  <pagination shown="1" offset="0" total_in_store="13" />
</memory-context>

When results are cut off, the pagination element includes a hint:

  <pagination shown="3" offset="0" limit="3" total_in_store="13">Results 1–3. Use offset=3 to retrieve more.</pagination>

fluree memory update

Update a memory in place. Only the fields you provide are changed — the ID stays the same. History is tracked via git.

fluree memory update <ID> [OPTIONS]

Options

Example

fluree memory update mem:fact-01JDXYZ... --text "Tests use cargo nextest with --no-fail-fast"

Output:

Updated: mem:fact-01JDXYZ...

fluree memory forget

Delete a memory by retracting all its triples.

fluree memory forget <ID>

Output:

Forgotten: mem:fact-01JDXYZ...

fluree memory status

Show a summary of the memory store.

fluree memory status

Output:

Memory Store Status
  Total memories: 12
  Total tags:     25
  By kind:
    fact: 7
    decision: 2
    constraint: 3

fluree memory export / import

Export all current (non-superseded) memories as JSON, or import from a file.

fluree memory export > memories.json
fluree memory import memories.json

fluree memory mcp-install

Install MCP configuration for an IDE so agents can use memory tools.

fluree memory mcp-install [--ide <IDE>]

Options

Supported IDE values:

Legacy aliases: claude-vscode and github-copilot map to vscode.

When --ide is omitted, the first unconfigured detected tool is used; defaults to claude-code if none detected.

Example

fluree memory mcp-install --ide cursor

Output:

  Installed: .cursor/mcp.json
  Installed: .cursor/rules/fluree_rules.md

Cursor notes (recommended config)

Cursor’s MCP configuration supports stdio servers with a type field and config interpolation like ${workspaceFolder}. A portable repo-scoped setup looks like:

{
  "mcpServers": {
    "fluree-memory": {
      "type": "stdio",
      "command": "fluree",
      "args": ["mcp", "serve", "--transport", "stdio"],
      "env": {
        "FLUREE_HOME": "${workspaceFolder}/.fluree"
      }
    }
  }
}

Setting FLUREE_HOME ensures the MCP server uses the current workspace’s .fluree/ directory even if Cursor spawns the process from a different working directory. That keeps repo memory/logs under <repo>/.fluree-memory/ instead of a global location.

Troubleshooting: repo vs global memory

• Repo-scoped expected:
  • Memories: <repo>/.fluree-memory/repo.ttl
  • MCP log: <repo>/.fluree-memory/.local/mcp.log (should show client initialized after a full Cursor restart)
• If it’s using global dirs on macOS:
  • Memories/log: ~/Library/Application Support/.fluree-memory/...
  • Fix: ensure your Cursor config sets env.FLUREE_HOME = "${workspaceFolder}/.fluree" and restart Cursor fully.

See Also

• Memory overview — what it is, when to use it, how it fits into your workflow
• Memory getting started — install, quickstart, and per-IDE setup guides
• Memory concepts — repo vs user memory, supersession, recall ranking, secrets
• Memory guides — team workflows, rules-file customization, migrating from plain markdown
• Memory reference — IDE support matrix, mem: schema, TTL file format
• mcp — MCP server for IDE agent integration

fluree mcp

Model Context Protocol (MCP) server for IDE agent integration.

Usage

fluree mcp <COMMAND>

Subcommands

fluree mcp serve

Start an MCP server that exposes developer memory tools to IDE agents.

fluree mcp serve [--transport <TRANSPORT>]

Options

The stdio transport reads JSON-RPC requests from stdin and writes responses to stdout. This is the standard transport for IDE integration — the IDE spawns the process and communicates over pipes.

Available tools

The MCP server exposes 6 tools:

The server auto-initializes the memory store on first tool call. No separate fluree memory init is needed.

IDE configuration

The easiest way to configure your IDE is with fluree memory mcp-install:

fluree memory mcp-install --ide cursor

Or manually add to your IDE’s MCP config:

{
  "mcpServers": {
    "fluree-memory": {
      "type": "stdio",
      "command": "/path/to/fluree",
      "args": ["mcp", "serve", "--transport", "stdio"],
      "env": {
        "FLUREE_HOME": "${workspaceFolder}/.fluree"
      }
    }
  }
}

Testing with JSON-RPC

To test the server directly, pipe JSON-RPC to stdin:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0.0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  | fluree mcp serve --transport stdio

Tracing

CLI tracing is disabled when running fluree mcp serve to avoid any log output on stderr that could interfere with the JSON-RPC protocol.

See Also

• memory — CLI commands for memory management
• Memory: MCP server — what the MCP server exposes and how agents use it
• Memory getting started — per-IDE setup (Claude Code, Cursor, VS Code, Windsurf, Zed)
• Memory IDE support matrix — config paths and supported features per IDE

fluree iceberg

Manage Apache Iceberg table connections.

Subcommands

fluree iceberg map

Map an Iceberg table as a queryable graph source.

Usage

fluree iceberg map <NAME> [OPTIONS]

Arguments

Options

Catalog mode:

REST catalog mode options:

Direct S3 mode options:

R2RML mapping:

Authentication:

S3 overrides:

Other:

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.

Two 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.

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

# 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 info warehouse-orders

# Query via SPARQL GRAPH pattern
fluree query mydb 'SELECT ?id ?total FROM <mydb:main> WHERE { GRAPH <warehouse-orders:main> { ?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`.

See Also

• Iceberg / Parquet - Iceberg integration details
• R2RML - R2RML mapping reference
• list - List ledgers and graph sources
• info - Show graph source details
• drop - Remove a graph source

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 completions

Generate shell completions.

Usage

fluree completions <SHELL>

Arguments

Supported Shells

• bash
• zsh
• fish
• powershell
• elvish

Description

Generates shell completion scripts that enable tab-completion for fluree commands, options, and arguments.

Installation

Bash

# Add to ~/.bashrc
eval "$(fluree completions bash)"

# Or save to a file
fluree completions bash > /etc/bash_completion.d/fluree

Zsh

# Add to ~/.zshrc
eval "$(fluree completions zsh)"

# Or save to completions directory
fluree completions zsh > ~/.zfunc/_fluree
# Then add to ~/.zshrc: fpath=(~/.zfunc $fpath)

Fish

fluree completions fish > ~/.config/fish/completions/fluree.fish

PowerShell

# Add to your PowerShell profile
fluree completions powershell | Out-String | Invoke-Expression

Examples

# Generate bash completions
fluree completions bash

# Generate zsh completions and save
fluree completions zsh > ~/.zfunc/_fluree

Usage After Installation

After installing completions, you can use tab to complete:

fluree <TAB>        # Shows all commands
fluree que<TAB>     # Completes to "query"
fluree query --<TAB> # Shows available options

Getting Started

Welcome to Fluree! This section will guide you through the essential steps to start using Fluree for your graph database needs.

Quick Navigation

Fluree for SQL Developers

Coming from PostgreSQL, MySQL, or SQL Server? This guide maps SQL concepts to Fluree equivalents, shows the same operations in both languages, and highlights where Fluree gives you capabilities that relational databases don’t have.

Quickstart: Run the Server

Get Fluree up and running in minutes. Learn how to:

• Install and run the Fluree server
• Configure basic settings
• Verify the server is running
• Access the HTTP API

Quickstart: Create a Ledger

Create your first ledger to store data. Learn how to:

• Create a new ledger using the API
• Understand ledger IDs and branching
• Set up initial configuration
• Verify ledger creation

Quickstart: Write Data

Start writing data to your ledger. Learn how to:

• Insert new entities (basic inserts)
• Upsert data (idempotent transactions; predicate-level replacement for supplied predicates)
• Update existing data (WHERE/DELETE/INSERT pattern)
• Understand JSON-LD transaction format

Quickstart: Query Data

Query your data using Fluree’s powerful query languages. Learn how to:

• Write basic JSON-LD queries
• Write basic SPARQL queries
• Filter and select data
• Understand query results

Tutorial: End-to-End

Build a knowledge base that combines Fluree’s differentiating features in one workflow:

• Full-text search with BM25 relevance ranking
• Time travel to compare current and historical state
• Branching to experiment safely
• Policies for role-based access control

Using Fluree as a Rust Library

Embed Fluree directly in your Rust applications. Learn how to:

• Add Fluree as a dependency in Cargo.toml
• Use the Rust API programmatically
• Implement common patterns (insert, query, update)
• Integrate BM25 and vector search
• Handle errors and configuration
• Write tests with Fluree

What is Fluree?

Fluree is a temporal graph database that stores data as RDF triples with built-in support for:

• Time Travel: Query data as it existed at any point in time
• Full-Text Search: Integrated BM25 indexing for powerful text search
• Vector Search: Approximate nearest neighbor (ANN) queries
• Policy Enforcement: Fine-grained, data-level access control
• Verifiable Data: Cryptographically signed transactions
• Graph Sources: Integration with external data sources (Iceberg, R2RML)

Learning Path

For HTTP API users (server-based):

1. Bridge the gap: Fluree for SQL Developers if coming from relational databases
2. Start with the Server: Run the Server to get Fluree running
3. Create Your First Ledger: Create a Ledger to set up your database
4. Add Data: Write Data to insert your first entities
5. Query Your Data: Query Data to retrieve and explore
6. See it all together: End-to-End Tutorial — search, time travel, branching, and policies in one workflow
7. Core Concepts: Read Concepts to understand Fluree’s architecture
8. Practical Guides: Explore Cookbooks for search, time travel, branching, policies, and SHACL validation
9. Deep Dive: Explore Query, Transactions, and Security
10. Production Ready: Review Operations for deployment guidance

For Rust developers (embedded library):

1. Rust API Guide: Using Fluree as a Rust Library for embedding Fluree in your application
2. Core Concepts: Concepts to understand how Fluree works
3. Practical Guides: Cookbooks for search, time travel, branching, policies, and validation
4. Advanced Queries: Query for complex query patterns
5. Transactions: Transactions for data modification patterns
6. Production Ready: Operations and Dev Setup

Prerequisites

• Familiarity with JSON format
• HTTP client (curl, Postman, or your programming language’s HTTP library)
• No graph database or RDF experience required — Fluree for SQL Developers bridges the gap from relational databases

Support and Resources

• Documentation: This documentation provides comprehensive coverage
• API Reference: See HTTP API for endpoint details
• Troubleshooting: Check Troubleshooting for common issues

Let’s get started!

Fluree for SQL Developers

If you’ve spent years with PostgreSQL, MySQL, or SQL Server and are encountering a graph database for the first time, this guide bridges the gap. It maps SQL concepts you already know to their Fluree equivalents, shows you the same operations in both languages, and highlights where Fluree gives you capabilities that relational databases simply don’t have.

The mental model shift

In SQL, you design tables with fixed columns, then insert rows. In Fluree, you make statements about things — and those statements can describe anything, with any properties, at any time.

The flake: Fluree’s atomic unit

Every fact in Fluree is stored as a flake — an extended triple that adds provenance. At its core, a flake is a statement: subject → predicate → object, plus metadata about when it was asserted, which graph it belongs to, and whether it’s an assertion or retraction.

ex:alice  schema:name  "Alice"       (graph: default, t: 1, op: assert)
ex:alice  schema:age   30            (graph: default, t: 1, op: assert)
ex:alice  schema:knows ex:bob        (graph: default, t: 1, op: assert)

Think of it as: “Alice’s name is Alice (added in transaction 1).” The provenance is what makes time travel and immutability possible — every change is a new flake, and retractions are recorded alongside assertions.

In SQL terms, imagine a universal table with columns entity_id, attribute, value, graph, transaction, operation — that can represent any data structure without DDL and preserves complete history.

Terminology note: In RDF standards, the core unit is called a “triple” (subject-predicate-object). Fluree’s “flake” extends the triple with temporal and provenance metadata. You’ll see both terms in the documentation — “triple” when discussing the RDF data model, “flake” when discussing Fluree’s storage and history.

Side by side: common operations

Creating structure

SQL — Define a table:

CREATE TABLE employees (
  id SERIAL PRIMARY KEY,
  name VARCHAR(255) NOT NULL,
  email VARCHAR(255) UNIQUE,
  department VARCHAR(100),
  salary DECIMAL(10,2),
  manager_id INTEGER REFERENCES employees(id)
);

Fluree — Just insert data:

fluree insert '
@prefix schema: <http://schema.org/> .
@prefix ex:     <http://example.org/> .

ex:alice  a schema:Person ;
  schema:name        "Alice Smith" ;
  schema:email       "alice@example.com" ;
  ex:department      "Engineering" ;
  ex:salary          125000 ;
  ex:reportsTo       ex:bob .

ex:bob  a schema:Person ;
  schema:name        "Bob Jones" ;
  schema:email       "bob@example.com" ;
  ex:department      "Engineering" .
'

There’s no CREATE TABLE. Types and properties emerge from the data itself. You can add new properties to any entity at any time without migrations.

Inserting data

SQL:

INSERT INTO employees (name, email, department, salary)
VALUES ('Carol Davis', 'carol@example.com', 'Marketing', 95000);

Fluree (CLI):

fluree insert '
@prefix schema: <http://schema.org/> .
@prefix ex:     <http://example.org/> .

ex:carol  a schema:Person ;
  schema:name        "Carol Davis" ;
  schema:email       "carol@example.com" ;
  ex:department      "Marketing" ;
  ex:salary          95000 .
'

Fluree (HTTP API):

curl -X POST http://localhost:8090/v1/fluree/insert?ledger=mydb:main \
  -H "Content-Type: application/ld+json" \
  -d '{
    "@context": {
      "schema": "http://schema.org/",
      "ex": "http://example.org/"
    },
    "@id": "ex:carol",
    "@type": "schema:Person",
    "schema:name": "Carol Davis",
    "schema:email": "carol@example.com",
    "ex:department": "Marketing",
    "ex:salary": 95000
  }'

Basic queries

SQL:

SELECT name, email FROM employees WHERE department = 'Engineering';

Fluree (SPARQL):

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

SELECT ?name ?email
WHERE {
  ?person a schema:Person ;
          schema:name ?name ;
          schema:email ?email ;
          ex:department "Engineering" .
}

Fluree (JSON-LD Query):

{
  "@context": {"schema": "http://schema.org/", "ex": "http://example.org/"},
  "select": ["?name", "?email"],
  "where": [
    {
      "@id": "?person", "@type": "schema:Person",
      "schema:name": "?name",
      "schema:email": "?email",
      "ex:department": "Engineering"
    }
  ]
}

Joins

In SQL, joins are explicit operations. In Fluree, relationships are just triples — “joining” is following a link.

SQL — Find employees and their managers:

SELECT e.name AS employee, m.name AS manager
FROM employees e
JOIN employees m ON e.manager_id = m.id;

Fluree (SPARQL):

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

SELECT ?employee ?manager
WHERE {
  ?e schema:name ?employee ;
     ex:reportsTo ?m .
  ?m schema:name ?manager .
}

No JOIN keyword — you just follow the ex:reportsTo link from one entity to another. The database traverses relationships natively.

Multi-hop relationships

This is where graphs shine. “Find everyone in Alice’s reporting chain” requires recursive CTEs in SQL but is natural in a graph.

SQL (recursive CTE):

WITH RECURSIVE chain AS (
  SELECT id, name, manager_id FROM employees WHERE name = 'Alice Smith'
  UNION ALL
  SELECT e.id, e.name, e.manager_id
  FROM employees e JOIN chain c ON e.id = c.manager_id
)
SELECT name FROM chain;

Fluree (SPARQL — property path):

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

SELECT ?name
WHERE {
  ex:alice ex:reportsTo+ ?manager .
  ?manager schema:name ?name .
}

The + after ex:reportsTo means “follow this relationship one or more times.” No recursion needed.

Aggregation

SQL:

SELECT department, COUNT(*) as count, AVG(salary) as avg_salary
FROM employees
GROUP BY department
ORDER BY avg_salary DESC;

Fluree (SPARQL):

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

SELECT ?dept (COUNT(?person) AS ?count) (AVG(?salary) AS ?avg_salary)
WHERE {
  ?person ex:department ?dept ;
          ex:salary ?salary .
}
GROUP BY ?dept
ORDER BY DESC(?avg_salary)

Updates

SQL:

UPDATE employees SET salary = 130000 WHERE name = 'Alice Smith';

Fluree (SPARQL UPDATE):

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

DELETE { ?person ex:salary ?oldSalary }
INSERT { ?person ex:salary 130000 }
WHERE  { ?person schema:name "Alice Smith" ; ex:salary ?oldSalary }

The WHERE finds Alice, DELETE removes the old salary, and INSERT adds the new one. This is atomic.

Fluree (CLI — upsert for simpler cases):

fluree upsert '{
  "@context": {"schema": "http://schema.org/", "ex": "http://example.org/"},
  "@id": "ex:alice",
  "ex:salary": 130000
}'

Upsert replaces the salary value if Alice already exists, or creates the entity if she doesn’t.

Deletes

SQL:

DELETE FROM employees WHERE name = 'Carol Davis';

Fluree (SPARQL UPDATE):

PREFIX schema: <http://schema.org/>

DELETE { ?person ?p ?o }
WHERE  { ?person schema:name "Carol Davis" ; ?p ?o }

But here’s the key difference: in SQL, the row is gone. In Fluree, the retraction is recorded — you can still query Carol’s data at any previous point in time.

What SQL can’t do

These features have no relational equivalent:

Time travel

Query data as it existed at any point in the past:

# What was Alice's salary before the raise?
fluree query --at 1 'PREFIX schema: <http://schema.org/>
PREFIX ex: <http://example.org/>

SELECT ?salary WHERE {
  ?person schema:name "Alice Smith" ; ex:salary ?salary .
}'

# Show the full history of salary changes
fluree history 'PREFIX schema: <http://schema.org/>
PREFIX ex: <http://example.org/>

SELECT ?salary ?t ?op WHERE {
  ?person schema:name "Alice Smith" ; ex:salary ?salary .
}'

In SQL, you’d need audit tables, temporal extensions, or trigger-based logging. In Fluree, every change is automatically preserved.

Schema flexibility

Add new properties to any entity without ALTER TABLE:

# Alice now has a phone number — no migration needed
fluree insert '
@prefix schema: <http://schema.org/> .
@prefix ex:     <http://example.org/> .

ex:alice schema:telephone "+1-555-0100" .
'

Different entities of the same “type” can have different properties. There’s no fixed set of columns.

Branching

Fork your data to experiment without affecting production:

fluree branch create experiment
fluree use mydb:experiment

# Try risky changes on the branch
fluree update 'PREFIX ex: <http://example.org/>
DELETE { ?p ex:salary ?s }
INSERT { ?p ex:salary 200000 }
WHERE  { ?p ex:salary ?s }'

# Main branch is untouched
fluree query --ledger mydb:main 'SELECT ?name ?salary WHERE {
  ?p <http://schema.org/name> ?name ; <http://example.org/salary> ?salary
}'

Triple-level access control

SQL databases give you table-level or row-level security. Fluree policies control access to individual facts:

{
  "@id": "ex:hide-salary",
  "f:action": "query",
  "f:resource": { "f:predicate": "ex:salary" },
  "f:allow": false
}

This hides salary data from everyone unless another policy explicitly grants access. The same query returns different results for different users, automatically.

Integrated full-text search

No need for Elasticsearch or Solr alongside your database:

fluree insert '{
  "@context": {"ex": "http://example.org/"},
  "@id": "ex:doc1",
  "ex:content": {
    "@value": "Fluree is a graph database with time travel and integrated search",
    "@type": "@fulltext"
  }
}'

fluree query '{
  "@context": {"ex": "http://example.org/"},
  "select": ["?id", "?score"],
  "where": [
    {"@id": "?id", "ex:content": "?text"},
    ["bind", "?score", "(fulltext ?text \"graph database search\")"],
    ["filter", "(> ?score 0)"]
  ],
  "orderBy": [["desc", "?score"]]
}'

Common “but in SQL I would…” questions

“How do I enforce NOT NULL?” Use SHACL shapes to define constraints like required properties, value types, and cardinality.

“How do I enforce UNIQUE?” Fluree supports unique constraints in the ledger configuration.

“How do I do transactions?” Every Fluree transaction is atomic. Multiple operations in a single request either all succeed or all fail.

“How do I create indexes?” Fluree automatically maintains four indexes (SPOT, POST, OPST, PSOT) that cover all query patterns. You don’t need to create indexes manually.

“How do I paginate?” Use LIMIT and OFFSET, just like SQL:

SELECT ?name WHERE { ?p schema:name ?name }
ORDER BY ?name LIMIT 20 OFFSET 40

“How do I do subqueries?” SPARQL supports subqueries natively:

SELECT ?name ?avgSalary WHERE {
  ?person schema:name ?name ; ex:department ?dept .
  { SELECT ?dept (AVG(?s) AS ?avgSalary) WHERE { ?p ex:department ?dept ; ex:salary ?s } GROUP BY ?dept }
}

Next steps

• Quickstart: Write Data — Start writing data with the HTTP API
• SPARQL Reference — Full SPARQL 1.1 query reference
• JSON-LD Query — Fluree’s JSON-native query language
• Concepts — Deeper understanding of Fluree’s architecture
• Time Travel — Full guide to temporal queries

Quickstart: Run the Server

This guide will get the Fluree server running on your machine in minutes.

Installation

Option 1: Shell Installer (macOS / Linux)

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/fluree/db/releases/latest/download/fluree-db-cli-installer.sh | sh

Option 2: Homebrew (macOS / Linux)

brew install fluree/tap/fluree

Option 3: PowerShell (Windows)

Open PowerShell and run:

irm https://github.com/fluree/db/releases/latest/download/fluree-db-cli-installer.ps1 | iex

Then open a new PowerShell session and verify fluree --version. The installer adds %USERPROFILE%\bin to your PATH. The binary is unsigned, so Windows SmartScreen may prompt on first run — click More info → Run anyway.

Option 4: Download Pre-built Binary

Download the latest release for your platform from GitHub Releases:

# Linux (x86_64)
curl -L https://github.com/fluree/db/releases/latest/download/fluree-db-cli-x86_64-unknown-linux-gnu.tar.xz | tar xJ
chmod +x fluree-db-cli-x86_64-unknown-linux-gnu/fluree

# macOS (Apple Silicon)
curl -L https://github.com/fluree/db/releases/latest/download/fluree-db-cli-aarch64-apple-darwin.tar.xz | tar xJ
chmod +x fluree-db-cli-aarch64-apple-darwin/fluree

Option 5: Build from Source

If you have Rust installed:

# Clone the repository
git clone https://github.com/fluree/db.git
cd db

# Build the CLI (includes embedded server)
cargo build --release -p fluree-db-cli

# Binary will be at target/release/fluree

Option 6: Docker

# Pull the image
docker pull fluree/server:latest

# Run the container
docker run -p 8090:8090 fluree/server:latest

For configuration (mounted JSON-LD/TOML config files, env vars, persistent volumes, S3+DynamoDB, query peers, full Compose example), see Running with Docker.

Start the Server

Memory Storage (Development)

Start the server with in-memory storage (data is lost on restart):

fluree server run

You should see output like:

INFO fluree_db_server: Starting Fluree server
INFO fluree_db_server: Storage mode: memory
INFO fluree_db_server: Server listening on 0.0.0.0:8090

File Storage (Persistent)

For persistent storage, specify a storage path:

fluree server run --storage-path /var/lib/fluree

Custom Port

fluree server run --listen-addr 0.0.0.0:9090

Debug Logging

fluree server run --log-level debug

Verify Installation

Check Server Health

curl http://localhost:8090/health

Expected response:

{
  "status": "ok",
  "version": "4.0.3"
}

Create a Ledger

curl -X POST http://localhost:8090/v1/fluree/create \
  -H "Content-Type: application/json" \
  -d '{"ledger": "test:main"}'

Insert Data

curl -X POST "http://localhost:8090/v1/fluree/insert" \
  -H "Content-Type: application/json" \
  -H "fluree-ledger: test:main" \
  -d '{
    "@context": {"ex": "http://example.org/"},
    "@id": "ex:alice",
    "ex:name": "Alice"
  }'

Query Data

curl -X POST "http://localhost:8090/v1/fluree/query" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "test:main",
    "select": {"?s": ["*"]},
    "where": [["?s", "ex:name", "?name"]]
  }'

Understanding the Server

Endpoints

Default server endpoints:

See the API Reference for complete endpoint documentation.

Storage Modes

Memory (default):

• Fast, in-process storage
• Data lost on restart
• Best for development and testing

File (with --storage-path):

• Persistent local file storage
• Data survives restarts
• Best for single-server deployments

Configuration

All options can be set via CLI flags or environment variables:

# CLI flag
fluree server run --storage-path /data --log-level debug

# Environment variables
export FLUREE_STORAGE_PATH=/data
export FLUREE_LOG_LEVEL=debug
fluree server run

See Configuration for all options.

Common Configurations

Development

fluree server run --log-level debug

Production (Single Server)

fluree server run \
  --storage-path /var/lib/fluree \
  --indexing-enabled \
  --events-auth-mode required \
  --events-auth-trusted-issuers did:key:z6Mk...

With Background Indexing

fluree server run \
  --storage-path /var/lib/fluree \
  --indexing-enabled

Docker Deployment

For the full Docker guide — image internals, configuration via env vars vs mounted JSON-LD/TOML config files, persistent volumes, LRU cache and indexing tuning, S3+DynamoDB connection configs, query peers, and a production-ready Compose example — see Running with Docker.

Minimal persistent run:

docker run -d --name fluree \
  -p 8090:8090 \
  -v fluree-data:/var/lib/fluree \
  fluree/server:latest

Troubleshooting

Port Already in Use

# Use a different port
fluree server run --listen-addr 0.0.0.0:9090

Permission Denied (File Storage)

sudo chown -R $USER:$USER /var/lib/fluree
chmod -R 755 /var/lib/fluree

Server Won’t Start

Check logs with debug level:

fluree server run --log-level debug

Connection Refused

Verify the server is running and check the listen address:

# Listen on all interfaces (not just localhost)
fluree server run --listen-addr 0.0.0.0:8090

Next Steps

Now that your server is running:

1. Create a Ledger - Set up your first database
2. Write Data - Insert your first records
3. Query Data - Retrieve and explore your data

For production deployments:

• Configuration - All server options
• Query Peers - Horizontal scaling
• Admin Authentication - Protect admin endpoints

Quickstart: Create a Ledger

Ledgers are Fluree’s fundamental unit of data organization—similar to databases in traditional systems. This guide shows you how to create your first ledger.

Understanding Ledger IDs

Ledgers are identified by ledger IDs with the format ledger-name:branch:

• mydb:main - Primary branch of the “mydb” ledger
• customers:dev - Development branch of the “customers” ledger
• inventory:prod - Production branch

The default branch is main, so mydb is equivalent to mydb:main.

Creating a Ledger

Rust API (Library Usage)

When using Fluree as a Rust library, create ledgers explicitly with create_ledger:

#![allow(unused)]
fn main() {
let fluree = FlureeBuilder::memory().build_memory();

// Create a new ledger (returns LedgerState at t=0)
let ledger = fluree.create_ledger("mydb").await?;

// Now insert data
let result = fluree.graph("mydb:main")
    .transact()
    .insert(&data)
    .commit()
    .await?;
}

create_ledger registers the ledger in the nameservice and returns a genesis LedgerState ready for transactions. It returns ApiError::LedgerExists (HTTP 409) if the ledger already exists.

To load an existing ledger, use ledger:

#![allow(unused)]
fn main() {
let ledger = fluree.ledger("mydb:main").await?;
}

HTTP API (Server Usage)

Via the HTTP API, create a ledger explicitly with POST /v1/fluree/create, then write data with POST /v1/fluree/insert.

Step 1: Create the Ledger

curl -X POST http://localhost:8090/v1/fluree/create \
  -H "Content-Type: application/json" \
  -d '{"ledger": "mydb:main"}'

Response:

{
  "ledger_id": "mydb:main",
  "t": 0,
  "tx-id": "fluree:tx:sha256:...",
  "commit": {"hash": ""}
}

Step 2: Insert Data

curl -X POST http://localhost:8090/v1/fluree/insert \
  -H "Content-Type: application/json" \
  -H "fluree-ledger: mydb:main" \
  -d '{
    "@context": {
      "ex": "http://example.org/ns/",
      "schema": "http://schema.org/"
    },
    "@graph": [
      {
        "@id": "ex:alice",
        "@type": "schema:Person",
        "schema:name": "Alice",
        "schema:email": "alice@example.org"
      }
    ]
  }'

Response:

{
  "ledger_id": "mydb:main",
  "t": 1,
  "tx-id": "fluree:tx:sha256:...",
  "commit": {"hash": "bagaybqab..."}
}

The ledger mydb:main now has data!

Verifying Ledger Creation

Check Ledger Exists

curl http://localhost:8090/v1/fluree/exists/mydb:main

Response:

{
  "ledger_id": "mydb:main",
  "exists": true
}

Query the Ledger

Verify you can query the new ledger:

curl -X POST http://localhost:8090/v1/fluree/query \
  -H "Content-Type: application/json" \
  -d '{
    "@context": {
      "schema": "http://schema.org/"
    },
    "from": "mydb:main",
    "select": ["?name"],
    "where": [
      { "@id": "?person", "schema:name": "?name" }
    ]
  }'

Response:

[
  { "name": "Alice" }
]

Ledger Naming Best Practices

Descriptive Names

Choose names that clearly indicate purpose:

Good examples:

• customers:main
• inventory:prod
• analytics:warehouse

Bad examples:

• db1:main
• test:main
• data:main

Hierarchical Organization

Use slashes for logical grouping:

tenant/app:main
tenant/app:dev
department/project:feature-x

Branch Naming

Establish consistent branch naming conventions:

mydb:main              - Production branch
mydb:dev               - Development branch
mydb:staging           - Staging branch
mydb:feature-auth      - Feature branch
mydb:bugfix-login      - Bug fix branch

Working with Branches

Creating a New Branch

Branches are independent ledgers. First create the branch, then transact data into it:

# Create the branch
curl -X POST http://localhost:8090/v1/fluree/create \
  -H "Content-Type: application/json" \
  -d '{"ledger": "mydb:dev"}'

# Insert data into the branch
curl -X POST http://localhost:8090/v1/fluree/insert?ledger=mydb:dev \
  -H "Content-Type: application/json" \
  -d '{
    "@context": {
      "ex": "http://example.org/ns/",
      "schema": "http://schema.org/"
    },
    "@graph": [
      {
        "@id": "ex:bob",
        "@type": "schema:Person",
          "schema:name": "Bob"
      }
    ]
  }'

Now you have two independent ledgers:

• mydb:main (with Alice)
• mydb:dev (with Bob)

Understanding Branch Independence

Branches are completely independent—changes in one don’t affect the other:

# Query main branch
curl -X POST http://localhost:8090/v1/fluree/query \
  -d '{"from": "mydb:main", "select": ["?name"], "where": [{"@id": "?person", "schema:name": "?name"}]}'
# Returns: [{"name": "Alice"}]

# Query dev branch
curl -X POST http://localhost:8090/v1/fluree/query \
  -d '{"from": "mydb:dev", "select": ["?name"], "where": [{"@id": "?person", "schema:name": "?name"}]}'
# Returns: [{"name": "Bob"}]

Ledger Metadata

Each ledger maintains metadata accessible via the nameservice:

• commit_t: Latest transaction time
• index_t: Latest indexed transaction time
• commit_id: ContentId (CID) of the latest commit
• index_id: ContentId (CID) of the latest index
• default_context: Default JSON-LD @context for the ledger

Checking Ledger Status

curl http://localhost:8090/v1/fluree/info/mydb:main

Response:

{
  "ledger_id": "mydb:main",
  "branch": "main",
  "commit_t": 1,
  "index_t": 1,
  "commit_id": "bafybeig...commitT1",
  "index_id": "bafybeig...indexT1",
  "created": "2024-01-22T10:30:00.000Z",
  "last_updated": "2024-01-22T10:30:05.000Z"
}

Understanding Commit vs Index

• commit_t: Most recent transaction (always up-to-date)
• index_t: Most recent indexed snapshot (may lag behind commits)
• Gap: If commit_t > index_t, there’s a “novelty layer” being indexed

See Ledgers and Nameservice for details.

Multi-Tenant Scenarios

For multi-tenant applications, use hierarchical naming:

tenant1/app:main
tenant1/app:dev
tenant2/app:main
tenant2/app:dev

Or use separate ledgers per tenant:

tenant1-customers:main
tenant1-orders:main
tenant2-customers:main
tenant2-orders:main

Setting Default Context

A ledger may have a stored default JSON-LD @context that the CLI and HTTP server can auto-inject into queries that omit @context / PREFIX. Two ways to set it:

1. At import time: fluree create --from data.ttl captures @prefix declarations from the Turtle source and stores them as the default.
2. Explicitly: fluree context set <ledger> <ctx.json>, or PUT /v1/fluree/context/{ledger...} over HTTP.

Regular JSON-LD transactions (insert/update) do not update the default context — only the two paths above do.

// One-time setup via the CLI:
// fluree context set mydb context.json
{
  "@context": {
    "ex": "http://example.org/ns/",
    "schema": "http://schema.org/",
    "xsd": "http://www.w3.org/2001/XMLSchema#"
  }
}

After this, the CLI (fluree query) and the HTTP server query endpoint will inject the stored context into queries that don’t supply their own @context / PREFIX. Direct fluree-db-api consumers do not get auto-injection — they must opt in via Fluree::db_with_default_context(...) or include @context in each query. See docs/concepts/iri-and-context.md for the full opt-in story.

Common Patterns

Development Workflow

1. Create main branch: mydb:main
2. Create dev branch: mydb:dev
3. Develop and test in dev
4. Copy desired state to main (application logic)
5. Repeat

Feature Branching

1. Create feature branch: mydb:feature-x
2. Develop feature in isolation
3. Test thoroughly
4. Merge to main (via application logic)
5. Optionally retract feature branch

Environment Separation

mydb:dev      - Development environment
mydb:staging  - Staging environment
mydb:prod     - Production environment

Troubleshooting

Ledger Already Exists

If you try to query a ledger before it exists:

Error: Ledger not found: mydb:main

Solution: Create the ledger with a transaction first.

Permission Issues (File Storage)

If using file storage, ensure the server has write permissions:

# Check data directory permissions
ls -la /path/to/data

# Fix permissions if needed
sudo chown -R fluree:fluree /path/to/data
chmod -R 755 /path/to/data

AWS Storage Issues

For AWS storage, verify credentials and bucket access:

# Test S3 access
aws s3 ls s3://your-fluree-bucket/

# Test DynamoDB access
aws dynamodb describe-table --table-name fluree-nameservice

Next Steps

Now that you have a ledger:

1. Write Data - Learn how to insert, upsert, and update data
2. Query Data - Explore your data with queries
3. Concepts: Ledgers - Deep dive into ledger architecture

Related Documentation

• Ledgers and Nameservice - Architectural details
• Transactions - Writing data to ledgers
• Storage Modes - Storage backend options

Quickstart: Write Data

This guide shows you how to write data to Fluree using three main patterns: insert, upsert, and update.

Prerequisites

• Fluree server running (see Run the Server)
• A ledger created (see Create a Ledger)

Understanding Fluree Transactions

Fluree stores data as RDF triples (subject-predicate-object). Transactions are submitted as JSON-LD documents that get converted to triples internally.

Basic Transaction Structure

{
  "@context": {
    "ex": "http://example.org/ns/",
    "schema": "http://schema.org/"
  },
  "@graph": [
    {
      "@id": "ex:alice",
      "@type": "schema:Person",
      "schema:name": "Alice"
    }
  ]
}

This creates triples like:

ex:alice  rdf:type        schema:Person
ex:alice  schema:name     "Alice"

Insert: Adding New Data

The simplest operation is inserting new entities.

Insert a Single Entity

curl -X POST http://localhost:8090/v1/fluree/insert?ledger=mydb:main \
  -H "Content-Type: application/json" \
  -d '{
    "@context": {
      "ex": "http://example.org/ns/",
      "schema": "http://schema.org/"
    },
    "@graph": [
      {
        "@id": "ex:alice",
        "@type": "schema:Person",
        "schema:name": "Alice",
        "schema:email": "alice@example.org",
        "schema:age": 30
      }
    ]
  }'

Response:

{
  "t": 1,
  "timestamp": "2024-01-22T10:30:00.000Z",
  "commit_id": "bafybeig...commitT1",
  "flakes_added": 4,
  "flakes_retracted": 0
}

Insert Multiple Entities

curl -X POST http://localhost:8090/v1/fluree/insert?ledger=mydb:main \
  -H "Content-Type: application/json" \
  -d '{
    "@context": {
      "ex": "http://example.org/ns/",
      "schema": "http://schema.org/"
    },
    "@graph": [
      {
        "@id": "ex:bob",
        "@type": "schema:Person",
        "schema:name": "Bob",
        "schema:email": "bob@example.org"
      },
      {
        "@id": "ex:carol",
        "@type": "schema:Person",
        "schema:name": "Carol",
        "schema:email": "carol@example.org"
      }
    ]
  }'

Insert with Relationships

curl -X POST http://localhost:8090/v1/fluree/insert?ledger=mydb:main \
  -H "Content-Type: application/json" \
  -d '{
    "@context": {
      "ex": "http://example.org/ns/",
      "schema": "http://schema.org/"
    },
    "@graph": [
      {
        "@id": "ex:company-a",
        "@type": "schema:Organization",
        "schema:name": "Acme Corp"
      },
      {
        "@id": "ex:alice",
        "@type": "schema:Person",
        "schema:name": "Alice",
        "schema:worksFor": {"@id": "ex:company-a"}
      }
    ]
  }'

Upsert: Idempotent Transactions

Upsert (update/insert) replaces values for the predicates you supply on an entity. If the entity doesn’t exist, it’s created.

Basic Upsert

Use the dedicated /upsert endpoint:

curl -X POST "http://localhost:8090/v1/fluree/upsert?ledger=mydb:main" \
  -H "Content-Type: application/json" \
  -d '{
    "@context": {
      "ex": "http://example.org/ns/",
      "schema": "http://schema.org/"
    },
    "@graph": [
      {
        "@id": "ex:alice",
        "@type": "schema:Person",
        "schema:name": "Alice Smith",
        "schema:email": "alice.smith@example.org",
        "schema:age": 31
      }
    ]
  }'

This replaces existing values for the predicates included in the payload (for ex:alice, those are @type, schema:name, schema:email, schema:age).

Upsert Behavior

First transaction (entity doesn’t exist):

• Creates the entity with all specified properties

Subsequent transactions (entity exists):

• Retracts existing values for the supplied predicates
• Asserts new values for those predicates
• Leaves other predicates unchanged

Use Cases for Upsert

Good for:

• Idempotent transactions (can retry safely)
• Syncing from external systems
• Replacing values for the predicates you supply
• Avoiding duplicate checks

Not good for:

• Conditional/targeted changes (use UPDATE instead)

Update: Targeted Changes (WHERE/DELETE/INSERT)

For targeted changes to existing data, use the UPDATE pattern with WHERE/DELETE/INSERT.

Basic Update

curl -X POST http://localhost:8090/v1/fluree/update?ledger=mydb:main \
  -H "Content-Type: application/json" \
  -d '{
    "@context": {
      "ex": "http://example.org/ns/",
      "schema": "http://schema.org/"
    },
    "where": [
      { "@id": "ex:alice", "schema:age": "?oldAge" }
    ],
    "delete": [
      { "@id": "ex:alice", "schema:age": "?oldAge" }
    ],
    "insert": [
      { "@id": "ex:alice", "schema:age": 32 }
    ]
  }'

This pattern:

1. WHERE: Finds matching data
2. DELETE: Retracts specific triples
3. INSERT: Asserts new triples

Update Multiple Properties

curl -X POST http://localhost:8090/v1/fluree/update?ledger=mydb:main \
  -H "Content-Type: application/json" \
  -d '{
    "@context": {
      "ex": "http://example.org/ns/",
      "schema": "http://schema.org/"
    },
    "where": [
      { "@id": "ex:alice", "schema:name": "?name", "schema:email": "?email" }
    ],
    "delete": [
      { "@id": "ex:alice", "schema:name": "?name", "schema:email": "?email" }
    ],
    "insert": [
      { "@id": "ex:alice", "schema:name": "Alice Johnson", "schema:email": "alice.j@example.org" }
    ]
  }'

Conditional Update

Only update if condition is met:

curl -X POST http://localhost:8090/v1/fluree/update?ledger=mydb:main \
  -H "Content-Type: application/json" \
  -d '{
    "@context": {
      "ex": "http://example.org/ns/",
      "schema": "http://schema.org/"
    },
    "where": [
      { "@id": "ex:alice", "schema:age": "?age" },
      { "@id": "?age", "@type": "xsd:integer" }
    ],
    "delete": [
      { "@id": "ex:alice", "schema:age": "?age" }
    ],
    "insert": [
      { "@id": "ex:alice", "schema:age": { "@value": "32", "@type": "xsd:integer" } }
    ]
  }'

Adding Properties (Not Replacing)

To add a property without removing existing ones, use INSERT only:

curl -X POST http://localhost:8090/v1/fluree/update?ledger=mydb:main \
  -H "Content-Type: application/json" \
  -d '{
    "@context": {
      "ex": "http://example.org/ns/",
      "schema": "http://schema.org/"
    },
    "insert": [
      { "@id": "ex:alice", "schema:telephone": "+1-555-0100" }
    ]
  }'

This adds the telephone property without affecting other properties.

Data Types

Fluree supports various data types through JSON-LD typing:

Strings (Default)

{
  "@id": "ex:alice",
  "schema:name": "Alice"
}

Numbers

{
  "@id": "ex:alice",
  "schema:age": 30,
  "schema:height": 1.68
}

Booleans

{
  "@id": "ex:alice",
  "schema:active": true
}

Dates

{
  "@id": "ex:alice",
  "schema:birthDate": {
    "@value": "1994-05-15",
    "@type": "xsd:date"
  }
}

Timestamps

{
  "@id": "ex:alice",
  "schema:lastLogin": {
    "@value": "2024-01-22T10:30:00Z",
    "@type": "xsd:dateTime"
  }
}

References (Links to Other Entities)

{
  "@id": "ex:alice",
  "schema:worksFor": { "@id": "ex:company-a" }
}

Transaction Receipts

Every successful transaction returns a receipt with metadata:

{
  "t": 5,
  "timestamp": "2024-01-22T10:30:00.000Z",
  "commit_id": "bafybeig...commitT5",
  "flakes_added": 3,
  "flakes_retracted": 2,
  "previous_commit_id": "bafybeig...commitT4"
}

Key fields:

• t: Transaction time (monotonically increasing)
• timestamp: ISO 8601 timestamp
• commit_id: Content-addressed identifier (CID) for the commit
• flakes_added: Number of triples added
• flakes_retracted: Number of triples removed
• previous_commit_id: ContentId of the previous commit (present when t > 1)

See Commit Receipts for details.

Error Handling

Transaction Errors

If a transaction fails, you’ll receive an error response:

{
  "error": "TransactionError",
  "message": "Invalid IRI: not a valid URI",
  "code": "INVALID_IRI"
}

Common errors:

• INVALID_IRI: Malformed IRIs
• PARSE_ERROR: Invalid JSON-LD syntax
• TYPE_ERROR: Type mismatch
• CONSTRAINT_VIOLATION: Data constraint violated

Validation

Transactions are validated before being applied:

• JSON-LD syntax must be valid
• IRIs must be well-formed
• Types must be compatible
• References must resolve (optional)

Best Practices

1. Use Appropriate Transaction Pattern

• Insert: New entities, no duplication concerns
• Upsert: Idempotent transactions, predicate-level replacement for supplied predicates
• Update: Targeted changes, preserve other properties

2. Choose Meaningful IRIs

Good:

{"@id": "ex:user-12345"}
{"@id": "ex:product-widget-2024"}

Bad:

{"@id": "ex:1"}
{"@id": "ex:thing"}

3. Use Consistent Namespaces

Define a clear namespace strategy:

{
  "@context": {
    "app": "https://myapp.com/ns/",
    "schema": "http://schema.org/",
    "xsd": "http://www.w3.org/2001/XMLSchema#"
  }
}

4. Batch Related Changes

Include related entities in a single transaction:

{
  "@graph": [
    {"@id": "ex:order-123", "ex:customer": {"@id": "ex:alice"}},
    {"@id": "ex:order-123", "ex:product": {"@id": "ex:widget"}},
    {"@id": "ex:order-123", "ex:quantity": 5}
  ]
}

5. Use Typed Literals

Be explicit about types for dates, numbers, etc.:

{
  "@id": "ex:alice",
  "ex:birthDate": {
    "@value": "1994-05-15",
    "@type": "xsd:date"
  }
}

Transaction Size Limits

Be aware of transaction size constraints:

• Recommended: < 1000 triples per transaction
• Maximum: Configurable (default: 10,000 triples)
• Large imports: Use batch processing

See Indexing Side-Effects for performance considerations.

Next Steps

Now that you can write data:

1. Query Data - Learn how to retrieve your data
2. Transactions Overview - Detailed transaction documentation
3. JSON-LD Context - Understanding @context

Related Documentation

• Insert - Detailed insert documentation
• Upsert - Detailed upsert documentation
• Update - Detailed update documentation
• Data Types - Comprehensive type system guide

Quickstart: Query Data

This guide introduces you to querying data in Fluree using both JSON-LD Query and SPARQL.

Prerequisites

• Fluree server running with data (complete previous quickstarts)
• Sample data from Write Data guide

Query Languages

Fluree supports two query languages:

• JSON-LD Query: Fluree’s native JSON-based query language
• SPARQL: W3C standard RDF query language

Both provide access to the same data and features.

JSON-LD Query

Basic SELECT Query

Retrieve all person names:

curl -X POST http://localhost:8090/v1/fluree/query \
  -H "Content-Type: application/json" \
  -d '{
    "@context": {
      "schema": "http://schema.org/"
    },
    "from": "mydb:main",
    "select": ["?name"],
    "where": [
      { "@id": "?person", "schema:name": "?name" }
    ]
  }'

Response:

[
  { "name": "Alice" },
  { "name": "Bob" },
  { "name": "Carol" }
]

Query Multiple Properties

curl -X POST http://localhost:8090/v1/fluree/query \
  -H "Content-Type: application/json" \
  -d '{
    "@context": {
      "schema": "http://schema.org/"
    },
    "from": "mydb:main",
    "select": ["?name", "?email"],
    "where": [
      { "@id": "?person", "schema:name": "?name" },
      { "@id": "?person", "schema:email": "?email" }
    ]
  }'

Response:

[
  { "name": "Alice", "email": "alice@example.org" },
  { "name": "Bob", "email": "bob@example.org" },
  { "name": "Carol", "email": "carol@example.org" }
]

Filter Results

Query with a specific filter:

curl -X POST http://localhost:8090/v1/fluree/query \
  -H "Content-Type: application/json" \
  -d '{
    "@context": {
      "schema": "http://schema.org/"
    },
    "from": "mydb:main",
    "select": ["?name", "?age"],
    "where": [
      { "@id": "?person", "schema:name": "?name" },
      { "@id": "?person", "schema:age": "?age" }
    ],
    "filter": "?age > 25"
  }'

Query Specific Entity

Query a specific entity by IRI:

curl -X POST http://localhost:8090/v1/fluree/query \
  -H "Content-Type: application/json" \
  -d '{
    "@context": {
      "ex": "http://example.org/ns/",
      "schema": "http://schema.org/"
    },
    "from": "mydb:main",
    "select": ["?name", "?email", "?age"],
    "where": [
      { "@id": "ex:alice", "schema:name": "?name" },
      { "@id": "ex:alice", "schema:email": "?email" },
      { "@id": "ex:alice", "schema:age": "?age" }
    ]
  }'

Query with Relationships

Follow links between entities:

curl -X POST http://localhost:8090/v1/fluree/query \
  -H "Content-Type: application/json" \
  -d '{
    "@context": {
      "schema": "http://schema.org/"
    },
    "from": "mydb:main",
    "select": ["?personName", "?companyName"],
    "where": [
      { "@id": "?person", "schema:name": "?personName" },
      { "@id": "?person", "schema:worksFor": "?company" },
      { "@id": "?company", "schema:name": "?companyName" }
    ]
  }'

Response:

[
  { "personName": "Alice", "companyName": "Acme Corp" }
]

SPARQL

Basic SELECT Query

The same queries in SPARQL syntax:

curl -X POST http://localhost:8090/v1/fluree/query \
  -H "Content-Type: application/sparql-query" \
  -d '
    PREFIX schema: <http://schema.org/>
    
    SELECT ?name
    FROM <mydb:main>
    WHERE {
      ?person schema:name ?name .
    }
  '

Query Multiple Properties

curl -X POST http://localhost:8090/v1/fluree/query \
  -H "Content-Type: application/sparql-query" \
  -d '
    PREFIX schema: <http://schema.org/>
    
    SELECT ?name ?email
    FROM <mydb:main>
    WHERE {
      ?person schema:name ?name .
      ?person schema:email ?email .
    }
  '

Filter Results

curl -X POST http://localhost:8090/v1/fluree/query \
  -H "Content-Type: application/sparql-query" \
  -d '
    PREFIX schema: <http://schema.org/>
    
    SELECT ?name ?age
    FROM <mydb:main>
    WHERE {
      ?person schema:name ?name .
      ?person schema:age ?age .
      FILTER (?age > 25)
    }
  '

Query with Relationships

curl -X POST http://localhost:8090/v1/fluree/query \
  -H "Content-Type: application/sparql-query" \
  -d '
    PREFIX schema: <http://schema.org/>
    
    SELECT ?personName ?companyName
    FROM <mydb:main>
    WHERE {
      ?person schema:name ?personName .
      ?person schema:worksFor ?company .
      ?company schema:name ?companyName .
    }
  '

Time Travel Queries

Query historical data using time specifiers.

Query at Specific Transaction

curl -X POST http://localhost:8090/v1/fluree/query \
  -H "Content-Type: application/json" \
  -d '{
    "@context": {
      "schema": "http://schema.org/"
    },
    "from": "mydb:main@t:1",
    "select": ["?name"],
    "where": [
      { "@id": "?person", "schema:name": "?name" }
    ]
  }'

This shows data as it existed at transaction 1.

Query at ISO Timestamp

curl -X POST http://localhost:8090/v1/fluree/query \
  -H "Content-Type: application/json" \
  -d '{
    "@context": {
      "schema": "http://schema.org/"
    },
    "from": "mydb:main@iso:2024-01-22T10:00:00Z",
    "select": ["?name"],
    "where": [
      { "@id": "?person", "schema:name": "?name" }
    ]
  }'

Query at Commit ContentId

curl -X POST http://localhost:8090/v1/fluree/query \
  -H "Content-Type: application/json" \
  -d '{
    "@context": {
      "schema": "http://schema.org/"
    },
    "from": "mydb:main@commit:bafybeig...",
    "select": ["?name"],
    "where": [
      { "@id": "?person", "schema:name": "?name" }
    ]
  }'

See Time Travel for comprehensive details.

History Queries

Track changes to entities over time by specifying a time range in the from clause.

Entity History

curl -X POST http://localhost:8090/v1/fluree/query \
  -H "Content-Type: application/json" \
  -d '{
    "@context": {
      "ex": "http://example.org/ns/",
      "schema": "http://schema.org/"
    },
    "from": "mydb:main@t:1",
    "to": "mydb:main@t:latest",
    "select": ["?name", "?age", "?t", "?op"],
    "where": [
      { "@id": "ex:alice", "schema:name": { "@value": "?name", "@t": "?t", "@op": "?op" } },
      { "@id": "ex:alice", "schema:age": "?age" }
    ],
    "orderBy": "?t"
  }'

The @t annotation binds the transaction time, and @op binds the operation type as a boolean (true = assert, false = retract).

Response shows all changes:

[
  ["Alice", 30, 1, true],
  ["Alice", 30, 5, false],
  ["Alicia", 31, 5, true]
]

Property History

Track changes to a specific property:

curl -X POST http://localhost:8090/v1/fluree/query \
  -H "Content-Type: application/json" \
  -d '{
    "@context": {
      "ex": "http://example.org/ns/",
      "schema": "http://schema.org/"
    },
    "from": "mydb:main@t:1",
    "to": "mydb:main@t:latest",
    "select": ["?age", "?t", "?op"],
    "where": [
      { "@id": "ex:alice", "schema:age": { "@value": "?age", "@t": "?t", "@op": "?op" } }
    ],
    "orderBy": "?t"
  }'

Response:

[
  [30, 1, true],
  [30, 5, false],
  [31, 5, true]
]

Aggregations

Count Results

curl -X POST http://localhost:8090/v1/fluree/query \
  -H "Content-Type: application/sparql-query" \
  -d '
    PREFIX schema: <http://schema.org/>
    
    SELECT (COUNT(?person) AS ?count)
    FROM <mydb:main>
    WHERE {
      ?person schema:name ?name .
    }
  '

Average, Min, Max

curl -X POST http://localhost:8090/v1/fluree/query \
  -H "Content-Type: application/sparql-query" \
  -d '
    PREFIX schema: <http://schema.org/>
    
    SELECT (AVG(?age) AS ?avgAge) (MIN(?age) AS ?minAge) (MAX(?age) AS ?maxAge)
    FROM <mydb:main>
    WHERE {
      ?person schema:age ?age .
    }
  '

Limiting Results

JSON-LD Query Limit

{
  "@context": {
    "schema": "http://schema.org/"
  },
  "from": "mydb:main",
  "select": ["?name"],
  "where": [
    { "@id": "?person", "schema:name": "?name" }
  ],
  "limit": 10
}

SPARQL Limit and Offset

PREFIX schema: <http://schema.org/>

SELECT ?name
FROM <mydb:main>
WHERE {
  ?person schema:name ?name .
}
ORDER BY ?name
LIMIT 10
OFFSET 20

Ordering Results

JSON-LD Query Order

{
  "@context": {
    "schema": "http://schema.org/"
  },
  "from": "mydb:main",
  "select": ["?name", "?age"],
  "where": [
    { "@id": "?person", "schema:name": "?name" },
    { "@id": "?person", "schema:age": "?age" }
  ],
  "orderBy": ["?age"]
}

SPARQL Order

PREFIX schema: <http://schema.org/>

SELECT ?name ?age
FROM <mydb:main>
WHERE {
  ?person schema:name ?name .
  ?person schema:age ?age .
}
ORDER BY DESC(?age)

Multi-Ledger Queries

Query across multiple ledgers:

curl -X POST http://localhost:8090/v1/fluree/query \
  -H "Content-Type: application/json" \
  -d '{
    "@context": {
      "schema": "http://schema.org/"
    },
    "from": ["customers:main", "orders:main"],
    "select": ["?customerName", "?orderTotal"],
    "where": [
      { "@id": "?customer", "schema:name": "?customerName" },
      { "@id": "?order", "schema:customer": "?customer" },
      { "@id": "?order", "schema:totalPrice": "?orderTotal" }
    ]
  }'

See Datasets for comprehensive multi-graph query documentation.

Understanding Query Results

JSON-LD Query Results

Results are returned as an array of objects:

[
  { "name": "Alice", "age": 30 },
  { "name": "Bob", "age": 25 }
]

SPARQL Results

SPARQL returns results in SPARQL JSON format:

{
  "head": {
    "vars": ["name", "age"]
  },
  "results": {
    "bindings": [
      {
        "name": { "type": "literal", "value": "Alice" },
        "age": { "type": "literal", "value": "30", "datatype": "http://www.w3.org/2001/XMLSchema#integer" }
      },
      {
        "name": { "type": "literal", "value": "Bob" },
        "age": { "type": "literal", "value": "25", "datatype": "http://www.w3.org/2001/XMLSchema#integer" }
      }
    ]
  }
}

See Output Formats for format details.

Query Performance Tips

1. Use Specific Patterns

More specific patterns are faster:

Good:

{ "@id": "ex:alice", "schema:name": "?name" }

Less efficient:

{ "@id": "?person", "?predicate": "?value" }

2. Filter Early

Apply filters in WHERE clauses when possible:

"where": [
  { "@id": "?person", "schema:age": "?age" }
],
"filter": "?age > 25"

3. Limit Results

Always use LIMIT for large result sets:

"limit": 100

4. Use Indexes

Queries leverage automatic indexes. Structure queries to take advantage:

• Subject-based lookups are fast
• Predicate-based lookups are fast
• Complex graph patterns may be slower

See Explain Plans for query optimization.

Common Query Patterns

Find All Types

SELECT DISTINCT ?type
FROM <mydb:main>
WHERE {
  ?entity a ?type .
}

Find All Predicates

SELECT DISTINCT ?predicate
FROM <mydb:main>
WHERE {
  ?subject ?predicate ?object .
}

Inverse Relationships

Find what points to an entity:

SELECT ?source ?predicate
FROM <mydb:main>
WHERE {
  ?source ?predicate <http://example.org/ns/alice> .
}

Optional Properties

Query with optional values:

PREFIX schema: <http://schema.org/>

SELECT ?name ?email ?phone
FROM <mydb:main>
WHERE {
  ?person schema:name ?name .
  ?person schema:email ?email .
  OPTIONAL { ?person schema:telephone ?phone }
}

Error Handling

Query Errors

Common query errors:

{
  "error": "QueryError",
  "message": "Ledger not found: mydb:main",
  "code": "LEDGER_NOT_FOUND"
}

{
  "error": "ParseError",
  "message": "Invalid JSON-LD: unexpected token",
  "code": "PARSE_ERROR"
}

Empty Results

Empty result set (not an error):

[]

Next Steps

Now that you can query data:

1. Learn Advanced Queries: Explore JSON-LD Query and SPARQL documentation
2. Understand Time Travel: Deep dive into Time Travel
3. Optimize Queries: Read about Explain Plans
4. Multi-Graph Queries: Learn about Datasets

Related Documentation

• JSON-LD Query - Complete JSON-LD query reference
• SPARQL - Complete SPARQL reference
• Output Formats - Result format options
• Time Travel - Historical queries
• Graph Crawl - Graph traversal

Tutorial: Building a Knowledge Base with Fluree

This tutorial walks through a realistic scenario — building a team knowledge base — to show how Fluree’s differentiating features work together. You’ll use time travel, full-text search, branching, and access control in a single workflow.

Time: ~20 minutes Prerequisites: Fluree installed and running (fluree init && fluree server run)

Step 1: Create the ledger and add data

fluree create knowledge-base
fluree use knowledge-base

Insert some articles and team members:

fluree insert '
@prefix schema: <http://schema.org/> .
@prefix ex:     <http://example.org/> .
@prefix f:      <https://ns.flur.ee/db#> .

ex:alice  a schema:Person ;
  schema:name "Alice Chen" ;
  ex:role     "engineer" ;
  ex:team     "platform" .

ex:bob  a schema:Person ;
  schema:name "Bob Martinez" ;
  ex:role     "engineer" ;
  ex:team     "platform" .

ex:carol  a schema:Person ;
  schema:name "Carol White" ;
  ex:role     "manager" ;
  ex:team     "platform" .

ex:doc1  a ex:Article ;
  schema:name    "Deployment Runbook" ;
  schema:author  ex:alice ;
  ex:team        "platform" ;
  ex:visibility  "internal" ;
  ex:content     "Step 1: Check the monitoring dashboard. Step 2: Run the database migration script. Step 3: Deploy the new container image using the CI pipeline."^^f:fullText .

ex:doc2  a ex:Article ;
  schema:name    "Onboarding Guide" ;
  schema:author  ex:bob ;
  ex:team        "platform" ;
  ex:visibility  "public" ;
  ex:content     "Welcome to the platform team. This guide covers setting up your development environment, accessing the database, and deploying your first service."^^f:fullText .

ex:doc3  a ex:Article ;
  schema:name    "Incident Response Playbook" ;
  schema:author  ex:carol ;
  ex:team        "platform" ;
  ex:visibility  "confidential" ;
  ex:content     "During a production incident, the on-call engineer should check database health, review recent deployments, and escalate if the service is not recovering within 15 minutes."^^f:fullText .
'

Verify the data is there:

fluree query --format table 'PREFIX schema: <http://schema.org/>
PREFIX ex: <http://example.org/>

SELECT ?title ?author_name ?visibility
WHERE {
  ?doc a ex:Article ;
       schema:name ?title ;
       schema:author ?author ;
       ex:visibility ?visibility .
  ?author schema:name ?author_name .
}
ORDER BY ?title'

┌─────────────────────────────┬───────────────┬──────────────┐
│ title                       │ author_name   │ visibility   │
├─────────────────────────────┼───────────────┼──────────────┤
│ Deployment Runbook          │ Alice Chen    │ internal     │
│ Incident Response Playbook  │ Carol White   │ confidential │
│ Onboarding Guide            │ Bob Martinez  │ public       │
└─────────────────────────────┴───────────────┴──────────────┘

This is transaction t=1. Remember this — we’ll come back to it.

Step 2: Full-text search

The article content was inserted with the @fulltext datatype, so it’s automatically indexed for BM25 relevance scoring. Search for articles about deployments:

fluree query '{
  "@context": {"schema": "http://schema.org/", "ex": "http://example.org/"},
  "select": ["?title", "?score"],
  "where": [
    {
      "@id": "?doc", "@type": "ex:Article",
      "ex:content": "?content",
      "schema:name": "?title"
    },
    ["bind", "?score", "(fulltext ?content \"database deployment\")"],
    ["filter", "(> ?score 0)"]
  ],
  "orderBy": [["desc", "?score"]],
  "limit": 10
}'

Results are ranked by relevance — the deployment runbook and incident playbook both mention deployments and databases, while the onboarding guide has a weaker match.

You can combine search with graph filters. Find only public articles matching the search:

fluree query '{
  "@context": {"schema": "http://schema.org/", "ex": "http://example.org/"},
  "select": ["?title", "?score"],
  "where": [
    {
      "@id": "?doc", "@type": "ex:Article",
      "ex:content": "?content",
      "schema:name": "?title",
      "ex:visibility": "public"
    },
    ["bind", "?score", "(fulltext ?content \"database deployment\")"],
    ["filter", "(> ?score 0)"]
  ],
  "orderBy": [["desc", "?score"]]
}'

Search results participate in standard graph joins and filters — no separate search service needed.

Step 3: Update data and use time travel

Let’s update the deployment runbook with a new version:

fluree update 'PREFIX schema: <http://schema.org/>
PREFIX ex: <http://example.org/>
PREFIX f: <https://ns.flur.ee/db#>

DELETE { ex:doc1 ex:content ?old }
INSERT { ex:doc1 ex:content "Step 1: Check the monitoring dashboard and verify all health checks pass. Step 2: Run the database migration script with --dry-run first. Step 3: Deploy the new container image. Step 4: Verify the deployment in staging before promoting to production."^^f:fullText }
WHERE  { ex:doc1 ex:content ?old }'

Now query the current version:

fluree query 'PREFIX schema: <http://schema.org/>
PREFIX ex: <http://example.org/>

SELECT ?content WHERE { ex:doc1 ex:content ?content }'

And query the original version using time travel:

fluree query --at 1 'PREFIX schema: <http://schema.org/>
PREFIX ex: <http://example.org/>

SELECT ?content WHERE { ex:doc1 ex:content ?content }'

The --at 1 flag queries the data as it was after transaction 1 — before the update. Both versions coexist in the same ledger.

You can also see the full change history:

fluree history 'PREFIX schema: <http://schema.org/>
PREFIX ex: <http://example.org/>

SELECT ?content ?t ?op WHERE { ex:doc1 ex:content ?content }'

Each result includes ?t (the transaction number) and ?op (whether it was an assertion or retraction). You see the original content retracted and the new content asserted, with exact timestamps.

Use cases this enables:

• Audit trails — Who changed what, when?
• Rollback — See what the data looked like before a bad change
• Compliance — Prove what was known at a specific point in time
• Debugging — Compare current vs. historical state to find when a problem was introduced

Step 4: Branch to experiment safely

Suppose you want to reorganize the knowledge base — maybe split articles into categories, or restructure ownership. You don’t want to affect the production data while experimenting.

Create a branch:

fluree branch create reorganize
fluree use knowledge-base:reorganize

On the branch, add categories and reorganize:

fluree insert '
@prefix schema: <http://schema.org/> .
@prefix ex:     <http://example.org/> .

ex:doc1 ex:category "operations" .
ex:doc2 ex:category "onboarding" .
ex:doc3 ex:category "operations" .
'

fluree update 'PREFIX schema: <http://schema.org/>
PREFIX ex: <http://example.org/>

DELETE { ex:doc3 ex:visibility "confidential" }
INSERT { ex:doc3 ex:visibility "internal" }
WHERE  { ex:doc3 ex:visibility "confidential" }'

Verify the branch has the changes:

fluree query --format table 'PREFIX schema: <http://schema.org/>
PREFIX ex: <http://example.org/>

SELECT ?title ?category ?visibility
WHERE {
  ?doc a ex:Article ;
       schema:name ?title ;
       ex:category ?category ;
       ex:visibility ?visibility .
}
ORDER BY ?title'

The main branch is untouched:

fluree query --ledger knowledge-base:main 'PREFIX ex: <http://example.org/>
PREFIX schema: <http://schema.org/>

SELECT ?title ?visibility
WHERE {
  ?doc a ex:Article ; schema:name ?title ; ex:visibility ?visibility .
  OPTIONAL { ?doc ex:category ?cat }
  FILTER(!BOUND(?cat))
}
ORDER BY ?title'

No categories on main — the branch is fully isolated.

When you’re happy with the changes, merge back:

fluree branch merge reorganize
fluree use knowledge-base:main

Now main has the categories and the visibility change. The branch can continue for future experiments or be dropped:

fluree branch drop reorganize

Step 5: Add access control

Now let’s add policies so that different users see different articles based on their role and team.

Insert policies into the ledger:

fluree insert '{
  "@context": {
    "f": "https://ns.flur.ee/db#",
    "ex": "http://example.org/",
    "schema": "http://schema.org/"
  },
  "@graph": [
    {
      "@id": "ex:policy-public-read",
      "@type": "f:Policy",
      "f:action": "query",
      "f:resource": { "ex:visibility": "public" },
      "f:allow": true
    },
    {
      "@id": "ex:policy-team-internal",
      "@type": "f:Policy",
      "f:subject": "?user",
      "f:action": "query",
      "f:resource": {
        "ex:visibility": "internal",
        "ex:team": "?team"
      },
      "f:condition": [
        { "@id": "?user", "ex:team": "?team" }
      ],
      "f:allow": true
    },
    {
      "@id": "ex:policy-manager-confidential",
      "@type": "f:Policy",
      "f:subject": "?user",
      "f:action": "query",
      "f:resource": {
        "ex:visibility": "confidential",
        "ex:team": "?team"
      },
      "f:condition": [
        { "@id": "?user", "ex:team": "?team", "ex:role": "manager" }
      ],
      "f:allow": true
    }
  ]
}'

These three policies create a layered access model:

1. Public articles — visible to everyone
2. Internal articles — visible only to members of the same team
3. Confidential articles — visible only to managers on the same team

Query as Alice (engineer, platform team):

fluree query '{
  "@context": {"schema": "http://schema.org/", "ex": "http://example.org/"},
  "select": ["?title", "?visibility"],
  "where": [
    {"@id": "?doc", "@type": "ex:Article", "schema:name": "?title", "ex:visibility": "?visibility"}
  ],
  "opts": {"identity": "ex:alice"}
}'

Alice sees the public onboarding guide and the internal deployment runbook, but not the confidential incident playbook.

Query as Carol (manager, platform team):

fluree query '{
  "@context": {"schema": "http://schema.org/", "ex": "http://example.org/"},
  "select": ["?title", "?visibility"],
  "where": [
    {"@id": "?doc", "@type": "ex:Article", "schema:name": "?title", "ex:visibility": "?visibility"}
  ],
  "opts": {"identity": "ex:carol"}
}'

Carol sees all three articles, including the confidential one.

The same query, different results, based on who’s asking — enforced by the database, not application code.

Step 6: Combine everything

Now let’s use all features together. Carol (manager) searches for articles about “database” in the knowledge base, with policies applied, and compares what she sees now vs. what existed before the reorganization:

Current state, with policy:

fluree query '{
  "@context": {"schema": "http://schema.org/", "ex": "http://example.org/"},
  "select": ["?title", "?visibility", "?score"],
  "where": [
    {
      "@id": "?doc", "@type": "ex:Article",
      "ex:content": "?content",
      "schema:name": "?title",
      "ex:visibility": "?visibility"
    },
    ["bind", "?score", "(fulltext ?content \"database\")"],
    ["filter", "(> ?score 0)"]
  ],
  "orderBy": [["desc", "?score"]],
  "opts": {"identity": "ex:carol"}
}'

Historical state (before runbook was updated):

fluree query '{
  "@context": {"schema": "http://schema.org/", "ex": "http://example.org/"},
  "from": "knowledge-base:main@t:1",
  "select": ["?title", "?score"],
  "where": [
    {
      "@id": "?doc", "@type": "ex:Article",
      "ex:content": "?content",
      "schema:name": "?title"
    },
    ["bind", "?score", "(fulltext ?content \"database\")"],
    ["filter", "(> ?score 0)"]
  ],
  "orderBy": [["desc", "?score"]]
}'

In a single database, you’ve combined:

• Full-text search — ranked by relevance
• Access control — Carol sees confidential articles, others wouldn’t
• Time travel — compare current vs. historical content
• Branching — experimented with reorganization without risk

What you’ve learned

Next steps

• Search Cookbook — Deeper guide to BM25 and vector search
• Time Travel Cookbook — Practical time-travel patterns
• Branching Cookbook — Branch/merge workflows
• Policies Cookbook — Access control patterns
• SPARQL Reference — Full SPARQL 1.1 reference
• JSON-LD Query — Fluree’s native query language

Using Fluree as a Rust Library

This guide shows how to use Fluree programmatically in your Rust applications by depending on the fluree-db-api crate.

Overview

Fluree can be embedded directly in Rust applications, giving you a powerful graph database without requiring a separate server process. This is ideal for:

• Desktop applications
• Edge computing
• Embedded systems
• Library/framework integration
• Testing and development

Add Dependency

Add Fluree to your Cargo.toml:

[dependencies]
fluree-db-api = { path = "../fluree-db-api" }
tokio = { version = "1", features = ["full"] }

Note: Replace path with version when published to crates.io:

[dependencies]
fluree-db-api = "0.1"

Features

Available feature flags:

• native (default) - File storage support
• credential (default in server/CLI) - DID/JWS/VerifiableCredential support for signed queries and transactions
• shacl (default in server/CLI) - SHACL constraint validation
• iceberg (default in server/CLI) - Apache Iceberg/R2RML graph source support
• aws - AWS-backed storage support (S3, storage-backed nameservice). Enables FlureeBuilder::s3() and S3-based JSON-LD configs.
• ipfs - IPFS-backed storage via Kubo HTTP RPC
• vector - Embedded vector similarity search (HNSW indexes via usearch)
• search-remote-client - Remote search service client (HTTP client for remote BM25 and vector search services)
• aws-testcontainers - Opt-in LocalStack-backed S3/DynamoDB tests (auto-start via testcontainers)
• full - Convenience bundle: native, credential, iceberg, shacl, ipfs

Quick Start

Basic Setup

use fluree_db_api::{FlureeBuilder, Result};

#[tokio::main]
async fn main() -> Result<()> {
    // Create a memory-backed Fluree instance
    let fluree = FlureeBuilder::memory().build_memory();

    // Create a new ledger
    let ledger = fluree.create_ledger("mydb").await?;

    println!("Ledger created at t={}", ledger.t());

    Ok(())
}

With File Storage

use fluree_db_api::{FlureeBuilder, Result};

#[tokio::main]
async fn main() -> Result<()> {
    // Use file-backed storage for persistence
    let fluree = FlureeBuilder::file("./data").build()?;

    // Create a new ledger (or load an existing one)
    let ledger = fluree.create_ledger("mydb").await?;

    // Load an existing ledger by ID (`name:branch`)
    let ledger = fluree.ledger("mydb:main").await?;

    Ok(())
}

Bulk import (high throughput)

For initial ledger bootstraps (large Turtle or JSON-LD datasets), Fluree exposes a bulk import pipeline as a first-class Rust API:

use fluree_db_api::{FlureeBuilder, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let fluree = FlureeBuilder::file("./data").build()?;

    // `chunks_dir` can be:
    // - a directory containing *.ttl, *.trig, or *.jsonld files (sorted lexicographically), OR
    // - a single .ttl or .jsonld file.
    // Directories must contain a single format (no mixing Turtle and JSON-LD).
    let result = fluree
        .create("dblp:main")
        .import("./chunks_dir")
        .threads(8)          // parallel TTL parsing; commits remain serial
        .build_index(true)   // write an index root and publish it
        .publish_every(50)   // nameservice checkpoints during long imports (0 disables)
        .cleanup(true)       // delete tmp import files on success
        .execute()
        .await?;

    println!(
        "import complete: t={}, flakes={}, root={:?}",
        result.t, result.flake_count, result.root_id
    );

    // Query normally after import (loads the published V2 root from CAS).
    let view = fluree.view("dblp:main").await?;
    let qr = fluree
        .query(&view, "SELECT * WHERE { ?s ?p ?o } LIMIT 10")
        .await?;
    println!("rows={}", qr.batches.iter().map(|b| b.len()).sum::<usize>());

    Ok(())
}

Temporary files: the bulk import pipeline uses a session-scoped tmp_import/ directory and removes it only on full success (unless .cleanup(false) is set). On failure, it keeps the session directory and logs its path for debugging.

With S3 Storage

Requires fluree-db-api feature aws and standard AWS credential/region configuration.

use fluree_db_api::{FlureeBuilder, Result};

#[tokio::main]
async fn main() -> Result<()> {
    // LocalStack/MinIO: endpoint is required
    let fluree = FlureeBuilder::s3("my-bucket", "http://localhost:4566")
        .build_client()
        .await?;

    let ledger = fluree.create_ledger("mydb").await?;
    println!("Ledger created at t={}", ledger.t());
    Ok(())
}

S3 Express One Zone note: for directory buckets (--x-s3 suffix), omit s3Endpoint in JSON-LD config and let the SDK handle it.

Connection Configuration (JSON-LD)

For advanced configuration (tiered storage, address identifier routing, DynamoDB nameservice, environment variable indirection), use FlureeBuilder::from_json_ld() to parse a JSON-LD config and build from it. The typed builder methods (build(), build_memory(), build_s3()) and the type-erased build_client() all share the same underlying construction logic.

See also: JSON-LD connection configuration reference.

use fluree_db_api::{FlureeBuilder, Result};
use serde_json::json;

#[tokio::main]
async fn main() -> Result<()> {
    let cfg = json!({
        "@context": {"@base": "https://ns.flur.ee/config/connection/", "@vocab": "https://ns.flur.ee/system#"},
        "@graph": [
            {"@id": "s3Index", "@type": "Storage", "s3Bucket": {"envVar": "INDEX_BUCKET"}, "s3Endpoint": {"envVar": "S3_ENDPOINT"}},
            {"@id": "conn", "@type": "Connection", "indexStorage": {"@id": "s3Index"}}
        ]
    });
    // from_json_ld parses the config into builder settings; build_client() constructs
    // a type-erased FlureeClient suitable for runtime-determined backends.
    let fluree = FlureeBuilder::from_json_ld(&cfg)?.build_client().await?;
    Ok(())
}

Environment variables (ConfigurationValue)

Any string/number config value can be specified directly or via a ConfigurationValue object:

{
  "s3Bucket": { "envVar": "FLUREE_S3_BUCKET", "defaultVal": "my-bucket" },
  "cacheMaxMb": { "envVar": "FLUREE_CACHE_MAX_MB", "defaultVal": "1024" }
}

Supported JSON-LD fields (Rust)

Connection node:

• parallelism
• cacheMaxMb
• indexStorage, commitStorage
• primaryPublisher (publisher node)

Storage node:

• File: filePath, AES256Key
• S3: s3Bucket, s3Prefix, s3Endpoint, s3ReadTimeoutMs, s3WriteTimeoutMs, s3ListTimeoutMs, s3MaxRetries, s3RetryBaseDelayMs, s3RetryMaxDelayMs

Publisher node:

• DynamoDB nameservice: dynamodbTable, dynamodbRegion, dynamodbEndpoint, dynamodbTimeoutMs
• Storage-backed nameservice: storage (reference to a Storage node)

Core Patterns

The Graph API

The primary API revolves around fluree.graph(graph_ref), which returns a lazy Graph handle. No I/O occurs until a terminal method (.execute(), .commit(), .load()) is called.

Use graph(...).query() when the target may be a mapped graph source as well as a native ledger. If the query body itself carries "from" / FROM, use query_from(). The lower-level fluree.db(...) + fluree.query(&view, ...) path is for materialized native ledger snapshots, not graph source aliases.

When I/O happens:

• .execute() / .execute_formatted() / .execute_tracked() — loads the graph from storage, then runs the query (each call reloads)
• .commit() — loads the cached ledger handle, stages, and commits
• .stage() — loads the ledger and stages without committing
• .load() — loads the graph once, returning a GraphSnapshot for repeated queries without reloading

#![allow(unused)]
fn main() {
// Lazy query — loads graph and executes in one step
let result = fluree.graph("mydb:main")
    .query()
    .sparql("SELECT ?name WHERE { ?s <http://schema.org/name> ?name }")
    .execute()
    .await?;

// Lazy transact + commit
let out = fluree.graph("mydb:main")
    .transact()
    .insert(&data)
    .commit()
    .await?;

// Materialize for reuse (avoids reloading on each query)
let db = fluree.graph("mydb:main").load().await?;
let r1 = db.query().sparql("SELECT ...").execute().await?;
let r2 = db.query().jsonld(&q).execute().await?;

// Time travel
let result = fluree.graph_at("mydb:main", TimeSpec::AtT(42))
    .query()
    .jsonld(&q)
    .execute()
    .await?;
}

Insert Data

use fluree_db_api::{FlureeBuilder, Result};
use serde_json::json;

#[tokio::main]
async fn main() -> Result<()> {
    let fluree = FlureeBuilder::memory().build_memory();
    let ledger = fluree.create_ledger("mydb").await?;

    // Insert JSON-LD data using the Graph API
    let data = json!({
        "@context": {
            "schema": "http://schema.org/",
            "ex": "http://example.org/ns/"
        },
        "@graph": [
            {
                "@id": "ex:alice",
                "@type": "schema:Person",
                "schema:name": "Alice",
                "schema:email": "alice@example.org",
                "schema:age": 30
            },
            {
                "@id": "ex:bob",
                "@type": "schema:Person",
                "schema:name": "Bob",
                "schema:email": "bob@example.org",
                "schema:age": 25
            }
        ]
    });

    let result = fluree.graph("mydb:main")
        .transact()
        .insert(&data)
        .commit()
        .await?;

    println!("Transaction committed");

    Ok(())
}

Query Data with JSON-LD Query

use fluree_db_api::{FlureeBuilder, Result};
use serde_json::json;

#[tokio::main]
async fn main() -> Result<()> {
    let fluree = FlureeBuilder::memory().build_memory();
    let ledger = fluree.create_ledger("mydb").await?;

    // Insert test data first (see Insert Data above)
    // ...

    // Query with JSON-LD using the lazy Graph API
    let query = json!({
        "select": ["?name", "?email"],
        "where": [
            { "@id": "?person", "@type": "schema:Person" },
            { "@id": "?person", "schema:name": "?name" },
            { "@id": "?person", "schema:email": "?email" },
            { "@id": "?person", "schema:age": "?age" }
        ],
        "filter": "?age > 25"
    });

    let result = fluree.graph("mydb:main")
        .query()
        .jsonld(&query)
        .execute_formatted()
        .await?;

    println!("Query results: {}",
        serde_json::to_string_pretty(&result)?);

    Ok(())
}

Query Data with SPARQL

use fluree_db_api::{FlureeBuilder, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let fluree = FlureeBuilder::memory().build_memory();
    let ledger = fluree.create_ledger("mydb").await?;

    // Insert test data first (see Insert Data above)
    // ...

    // Query with SPARQL using the lazy Graph API
    let sparql = r#"
        PREFIX schema: <http://schema.org/>

        SELECT ?name ?email
        WHERE {
            ?person a schema:Person .
            ?person schema:name ?name .
            ?person schema:email ?email .
            ?person schema:age ?age .
            FILTER (?age > 25)
        }
        ORDER BY ?name
    "#;

    let result = fluree.graph("mydb:main")
        .query()
        .sparql(sparql)
        .execute_formatted()
        .await?;

    println!("Results: {}",
        serde_json::to_string_pretty(&result)?);

    Ok(())
}

Update Data

use fluree_db_api::{FlureeBuilder, Result};
use serde_json::json;

#[tokio::main]
async fn main() -> Result<()> {
    let fluree = FlureeBuilder::memory().build_memory();
    let ledger = fluree.create_ledger("mydb").await?;

    // Update using WHERE/DELETE/INSERT pattern
    let update = json!({
        "@context": { "schema": "http://schema.org/" },
        "where": [
            { "@id": "?person", "schema:name": "Alice" },
            { "@id": "?person", "schema:age": "?oldAge" }
        ],
        "delete": [
            { "@id": "?person", "schema:age": "?oldAge" }
        ],
        "insert": [
            { "@id": "?person", "schema:age": 31 }
        ]
    });

    let result = fluree.graph("mydb:main")
        .transact()
        .update(&update)
        .commit()
        .await?;

    println!("Updated successfully");

    Ok(())
}

SPARQL UPDATE

Use SPARQL UPDATE syntax for transactions:

use fluree_db_api::{
    FlureeBuilder, Result,
    parse_sparql, lower_sparql_update, NamespaceRegistry, TxnOpts,
    SparqlQueryBody,
};

#[tokio::main]
async fn main() -> Result<()> {
    let fluree = FlureeBuilder::file("./data").build()?;

    // Get a cached ledger handle
    let handle = fluree.ledger_cached("mydb:main").await?;

    // SPARQL UPDATE string
    let sparql = r#"
        PREFIX ex: <http://example.org/ns/>

        DELETE {
            ?person ex:age ?oldAge .
        }
        INSERT {
            ?person ex:age 31 .
        }
        WHERE {
            ?person ex:name "Alice" .
            ?person ex:age ?oldAge .
        }
    "#;

    // Parse SPARQL
    let parse_output = parse_sparql(sparql);
    if parse_output.has_errors() {
        // Handle parse errors
        for diag in parse_output.diagnostics.iter().filter(|d| d.is_error()) {
            eprintln!("Parse error: {}", diag.message);
        }
        return Err(fluree_db_api::ApiError::Internal("SPARQL parse error".into()));
    }

    let ast = parse_output.ast.unwrap();

    // Extract the UPDATE operation
    let update_op = match &ast.body {
        SparqlQueryBody::Update(op) => op,
        _ => return Err(fluree_db_api::ApiError::Internal("Expected SPARQL UPDATE".into())),
    };

    // Get namespace registry from the ledger
    let snapshot = handle.snapshot().await;
    let mut ns = NamespaceRegistry::from_db(&snapshot.snapshot);

    // Lower SPARQL UPDATE to Txn IR
    let txn = lower_sparql_update(update_op, &ast.prologue, &mut ns, TxnOpts::default())?;

    // Execute the transaction
    let result = fluree.stage(&handle)
        .txn(txn)
        .execute()
        .await?;

    println!("SPARQL UPDATE committed at t={}", result.receipt.t);

    Ok(())
}

Supported SPARQL UPDATE operations:

• INSERT DATA - Insert ground triples
• DELETE DATA - Delete specific triples
• DELETE WHERE - Delete matching patterns
• DELETE/INSERT WHERE - Full update with patterns

See SPARQL UPDATE for syntax details.

Stage and Preview Changes

use fluree_db_api::{FlureeBuilder, Result};
use serde_json::json;

#[tokio::main]
async fn main() -> Result<()> {
    let fluree = FlureeBuilder::memory().build_memory();
    let ledger = fluree.create_ledger("mydb").await?;

    let data = json!({
        "@context": {"ex": "http://example.org/ns/"},
        "@graph": [{"@id": "ex:alice", "ex:name": "Alice"}]
    });

    // Stage without committing
    let staged = fluree.graph("mydb:main")
        .transact()
        .insert(&data)
        .stage()
        .await?;

    // Query the staged state to preview changes
    let preview_query = json!({
        "select": ["?name"],
        "where": [{"@id": "ex:alice", "ex:name": "?name"}]
    });

    let preview = staged.query()
        .jsonld(&preview_query)
        .execute()
        .await?;

    println!("Preview: {} rows", preview.row_count());

    Ok(())
}

Note: StagedGraph currently supports querying only. Staging on top of a staged transaction and committing from a StagedGraph are not yet supported.

Export Data

Stream ledger data as Turtle, N-Triples, N-Quads, TriG, or JSON-LD using the builder API:

use fluree_db_api::{FlureeBuilder, Result};
use fluree_db_api::export::ExportFormat;
use std::io::BufWriter;
use std::fs::File;

#[tokio::main]
async fn main() -> Result<()> {
    let fluree = FlureeBuilder::file("./data").build()?;

    // Export as Turtle to a file
    let file = File::create("backup.ttl").unwrap();
    let mut writer = BufWriter::new(file);
    let stats = fluree.export("mydb")
        .format(ExportFormat::Turtle)
        .write_to(&mut writer)
        .await?;
    println!("Exported {} triples", stats.triples_written);

    // Export as JSON-LD with custom prefixes
    let mut buf = Vec::new();
    let stats = fluree.export("mydb")
        .format(ExportFormat::JsonLd)
        .context(&serde_json::json!({"ex": "http://example.org/"}))
        .write_to(&mut buf)
        .await?;

    // Export all graphs as N-Quads (dataset export)
    let stats = fluree.export("mydb")
        .format(ExportFormat::NQuads)
        .all_graphs()
        .to_stdout()
        .await?;

    Ok(())
}

All formats stream directly from the binary SPOT index. Memory usage is O(leaflet size) for line-oriented formats and O(largest subject) for JSON-LD, regardless of dataset size.

Builder methods:

• .format(ExportFormat) — output format (default: Turtle)
• .all_graphs() — include all named graphs including system graphs (requires TriG or NQuads)
• .graph("iri") — export a specific named graph by IRI
• .as_of(TimeSpec) — time-travel export (transaction number, ISO-8601 datetime, or commit CID prefix)
• .context(&json) — override prefix map (default: ledger’s context from nameservice)
• .write_to(&mut writer) — stream to any Write sink
• .to_stdout() — convenience for stdout output

See also: CLI export for command-line usage.

Materialize for Reuse

When you need to run multiple queries against the same snapshot, materialize a GraphSnapshot once:

use fluree_db_api::{FlureeBuilder, Result};
use serde_json::json;

#[tokio::main]
async fn main() -> Result<()> {
    let fluree = FlureeBuilder::memory().build_memory();

    // Load once, query many times
    let db = fluree.graph("mydb:main").load().await?;

    let r1 = db.query()
        .sparql("SELECT ?name WHERE { ?s <http://schema.org/name> ?name }")
        .execute()
        .await?;

    let q2 = json!({
        "select": ["?email"],
        "where": [{"@id": "?s", "schema:email": "?email"}]
    });
    let r2 = db.query()
        .jsonld(&q2)
        .execute()
        .await?;

    // Access the underlying view if needed
    let view = db.view();

    Ok(())
}

Advanced Usage

Ledger Caching

Ledger caching is enabled by default on all FlureeBuilder constructors. When caching is active, fluree.ledger() returns a cached handle and subsequent calls avoid reloading from storage:

use fluree_db_api::{FlureeBuilder, Result};

#[tokio::main]
async fn main() -> Result<()> {
    // Caching is on by default — no extra call needed
    let fluree = FlureeBuilder::file("./data").build()?;

    // First call loads from storage
    let ledger = fluree.ledger("mydb:main").await?;

    // Subsequent calls return cached state (fast)
    let ledger2 = fluree.ledger("mydb:main").await?;

    Ok(())
}

To disable caching (e.g., for a CLI tool that runs once and exits):

#![allow(unused)]
fn main() {
let fluree = FlureeBuilder::file("./data")
    .without_ledger_caching()
    .build()?;
}

Disconnecting Ledgers

Use disconnect_ledger to release a ledger from the connection cache. This forces a fresh load on the next access:

use fluree_db_api::{FlureeBuilder, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let fluree = FlureeBuilder::file("./data").build()?;

    // Load and use ledger
    let ledger = fluree.ledger("mydb:main").await?;
    println!("Ledger at t={}", ledger.t());

    // Release cached state
    fluree.disconnect_ledger("mydb:main").await;

    // Next access will reload from storage
    let ledger = fluree.ledger("mydb:main").await?;

    Ok(())
}

When to use disconnect_ledger:

• Force fresh load: After external changes to the ledger (e.g., another process wrote data)
• Free memory: Release memory for ledgers you no longer need
• Clean shutdown: Release resources before application exit
• Testing: Reset state between test cases

Note: If caching is disabled (via without_ledger_caching() on builder), disconnect_ledger is a no-op.

Checking Ledger Existence

Use ledger_exists to check if a ledger is registered in the nameservice without loading it:

use fluree_db_api::{FlureeBuilder, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let fluree = FlureeBuilder::file("./data").build()?;

    // Check if ledger exists (lightweight nameservice lookup)
    if fluree.ledger_exists("mydb:main").await? {
        // Ledger exists - load it
        let ledger = fluree.ledger("mydb:main").await?;
        println!("Loaded ledger at t={}", ledger.t());
    } else {
        // Ledger doesn't exist - create it
        let ledger = fluree.create_ledger("mydb").await?;
        println!("Created new ledger");
    }

    Ok(())
}

When to use ledger_exists:

• Conditional create-or-load: Check before deciding whether to create or load
• Validation: Verify ledger IDs exist before operations
• Defensive programming: Avoid NotFound errors in application logic

Performance note: This is a lightweight check that only queries the nameservice - it does NOT load the ledger data, indexes, or novelty. Much faster than attempting to load and catching NotFound errors.

Dropping Ledgers

Use drop_ledger to permanently remove a ledger:

use fluree_db_api::{FlureeBuilder, DropMode, DropStatus, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let fluree = FlureeBuilder::file("./data").build()?;

    // Soft drop: retract from nameservice, preserve files
    let report = fluree.drop_ledger("mydb:main", DropMode::Soft).await?;
    match report.status {
        DropStatus::Dropped => println!("Ledger dropped"),
        DropStatus::AlreadyRetracted => println!("Already dropped"),
        DropStatus::NotFound => println!("Ledger not found"),
    }

    // Hard drop: delete all files (IRREVERSIBLE)
    let report = fluree.drop_ledger("mydb:main", DropMode::Hard).await?;
    println!("Deleted {} commit files, {} index files",
        report.commit_files_deleted,
        report.index_files_deleted);

    Ok(())
}

Drop Modes:

Drop Sequence:

1. Normalizes the ledger ID (ensures :main suffix)
2. Cancels any pending background indexing
3. Waits for in-progress indexing to complete
4. In hard mode: deletes all commit and index files
5. Retracts from nameservice
6. Disconnects from ledger cache (if caching enabled)

When to use drop_ledger:

• Cleanup: Remove test ledgers or unused data
• Data lifecycle: Permanently delete ledgers that are no longer needed
• Admin operations: Clean up after migrations or failures

Idempotency:

Safe to call multiple times:

• Returns DropStatus::AlreadyRetracted if previously dropped
• Hard mode still attempts deletion for NotFound/AlreadyRetracted (useful for admin cleanup)

Warnings:

The DropReport includes a warnings field for any non-fatal errors encountered during the operation (e.g., failed to delete a specific file). Always check this for hard drops:

#![allow(unused)]
fn main() {
let report = fluree.drop_ledger("mydb:main", DropMode::Hard).await?;
if !report.warnings.is_empty() {
    for warning in &report.warnings {
        eprintln!("Warning: {}", warning);
    }
}
}

Refreshing Cached Ledgers

Use refresh to poll-check whether a cached ledger is stale and update it if needed. refresh returns a RefreshResult containing the ledger’s t after the operation and what action was taken:

use fluree_db_api::{FlureeBuilder, NotifyResult, RefreshOpts, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let fluree = FlureeBuilder::file("./data").build()?;

    // Load ledger into cache
    let _ledger = fluree.ledger_cached("mydb:main").await?;

    // Later, check if the cached state is still fresh
    match fluree.refresh("mydb:main", Default::default()).await? {
        Some(r) => {
            println!("Ledger at t={}, action: {:?}", r.t, r.action);
            match r.action {
                NotifyResult::Current => println!("Already up to date"),
                NotifyResult::Reloaded => println!("Reloaded from storage"),
                NotifyResult::IndexUpdated => println!("Index was updated"),
                NotifyResult::CommitsApplied { count } => {
                    println!("{count} commits applied incrementally");
                }
                NotifyResult::NotLoaded => println!("Not in cache"),
            }
        }
        None => println!("Ledger not found in nameservice"),
    }

    Ok(())
}

Key behaviors:

• Does NOT cold-load: If the ledger isn’t already cached, returns NotLoaded (no-op)
• Returns None: If the ledger doesn’t exist in the nameservice
• Alias resolution: Supports short aliases (mydb resolves to mydb:main)
• No-op without caching: If caching is disabled, returns NotLoaded
• Returns t: The RefreshResult.t field always tells you the ledger’s current transaction time

When to use refresh:

• Poll-based freshness: When you can’t use SSE events but need periodic freshness checks
• Before critical reads: Ensure you have the latest state before important queries
• Peer mode: Check if the local cache is behind the transaction server

refresh vs disconnect_ledger:

Read-After-Write Consistency

Fluree’s query engine is eventually consistent: when one process writes data and another (or the same process on a warm cache) queries it, the query may not yet see the latest commit. The t value returned from a transaction is the key to bridging this gap.

Pass RefreshOpts { min_t: Some(t) } to refresh() to assert that the cached ledger has reached at least that transaction time. If it hasn’t after pulling the latest state from the nameservice, refresh returns ApiError::AwaitTNotReached with both the requested and current t values. Your code owns retry timing and timeout policy.

Basic usage:

use fluree_db_api::{FlureeBuilder, RefreshOpts, ApiError, Result};
use serde_json::json;

#[tokio::main]
async fn main() -> Result<()> {
    let fluree = FlureeBuilder::file("./data").build()?;
    let handle = fluree.ledger_cached("mydb:main").await?;

    // Transaction returns the commit's t value
    let receipt = fluree.stage(&handle)
        .insert(&json!({"@id": "ex:item", "ex:count": 42}))
        .commit()
        .await?;
    let committed_t = receipt.t;

    // Ensure the cache reflects at least this t before querying
    let opts = RefreshOpts { min_t: Some(committed_t) };
    let result = fluree.refresh("mydb:main", opts).await?;
    // result.unwrap().t >= committed_t is guaranteed here

    Ok(())
}

Serverless / Lambda pattern (retry with backoff):

In a serverless environment, the transacting process and the querying process may be different Lambda invocations. The querying invocation receives t (e.g., via an event payload or API parameter) and must wait for that commit to be visible:

#![allow(unused)]
fn main() {
use fluree_db_api::{RefreshOpts, ApiError};
use std::time::{Duration, Instant};

async fn wait_for_t(
    fluree: &Fluree<impl Storage, impl NameService>,
    ledger_id: &str,
    min_t: i64,
    timeout: Duration,
) -> Result<i64, ApiError> {
    let deadline = Instant::now() + timeout;
    let opts = RefreshOpts { min_t: Some(min_t) };

    loop {
        match fluree.refresh(ledger_id, opts.clone()).await {
            Ok(Some(r)) => return Ok(r.t),   // reached min_t
            Ok(None) => return Err(ApiError::NotFound(
                format!("ledger {ledger_id} not in nameservice"),
            )),
            Err(ApiError::AwaitTNotReached { current, .. }) => {
                if Instant::now() >= deadline {
                    return Err(ApiError::AwaitTNotReached {
                        requested: min_t,
                        current,
                    });
                }
                // Back off before retrying
                tokio::time::sleep(Duration::from_millis(50)).await;
            }
            Err(e) => return Err(e),
        }
    }
}
}

How it works internally:

1. Fast path: If the cached t already satisfies min_t, returns immediately without hitting the nameservice at all.
2. Pull: Queries the nameservice for the latest commit/index pointers and applies any new commits incrementally (or reloads if the gap is large).
3. Check: If t is still below min_t after the pull, returns ApiError::AwaitTNotReached so you can retry.

This design keeps retry/timeout policy out of the database layer. Different deployment contexts (Lambda with 100ms backoff, HTTP handler with 5s deadline, integration test with immediate assertion) each wrap the same primitive differently.

Branch Diff (Merge Preview)

Fluree::merge_preview returns the rich diff between two branches — ahead/behind commit summaries, the common ancestor, conflict keys, and fast-forward eligibility — without mutating any state. It uses the same primitives as merge_branch but skips the publish/copy steps, making it cheap enough to call on every UI render.

use fluree_db_api::{FlureeBuilder, MergePreviewOpts, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let fluree = FlureeBuilder::memory().build_memory();

    // ... create ledger, branch, transact on dev, etc.

    // Default: previewing dev → main with the spec defaults
    // (cap each commit list at 500, conflict keys at 200, run conflicts).
    let preview = fluree.merge_preview("mydb", "dev", None).await?;

    println!(
        "{} ahead, {} behind, fast-forward: {}",
        preview.ahead.count, preview.behind.count, preview.fast_forward,
    );

    if preview.fast_forward {
        println!("merge would advance {} → {}", preview.source, preview.target);
    } else {
        println!("merge has {} conflict(s)", preview.conflicts.count);
        for k in &preview.conflicts.keys {
            println!("  - s={} p={}", k.s, k.p);
        }
    }
    Ok(())
}

Tuning the preview

merge_preview_with takes a MergePreviewOpts for callers that need control over response size or want to skip the conflict computation:

use fluree_db_api::{FlureeBuilder, MergePreviewOpts, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let fluree = FlureeBuilder::memory().build_memory();

    // Cheap preview: counts only, no conflict walks.
    let counts = fluree
        .merge_preview_with(
            "mydb",
            "dev",
            Some("main"),
            MergePreviewOpts {
                max_commits: Some(0),       // counts only — no commit summaries
                max_conflict_keys: Some(0),
                include_conflicts: false,
            },
        )
        .await?;

    // Direct Rust callers can opt in to **unbounded** results — useful for
    // tooling that needs the full divergence. The HTTP layer always supplies
    // a bound, so this is a Rust-only escape hatch.
    let full = fluree
        .merge_preview_with(
            "mydb",
            "dev",
            None,
            MergePreviewOpts {
                max_commits: None,
                max_conflict_keys: None,
                include_conflicts: true,
            },
        )
        .await?;

    Ok(())
}

What the caps do (and don’t) control

max_commits and max_conflict_keys cap the size of the returned lists, not the cost of computing them:

• BranchDelta::count on each side reflects the full unbounded divergence — computed by walking every commit envelope between HEAD and the common ancestor — regardless of max_commits.
• When include_conflicts: true, both compute_delta_keys walks scan the full per-side delta regardless of max_conflict_keys.
• When include_conflict_details: true, value details are collected only for the returned conflicts.keys after the max_conflict_keys cap is applied.
• Set include_conflicts: false for a cheap preview on heavily diverged branches; you still get accurate ahead.count / behind.count.

Response shape

mergeable only reflects whether the selected strategy would abort due to detected conflicts; it is not full validation of every constraint the eventual merge commit may encounter. mergeable=true does not guarantee a subsequent merge will succeed; it only reflects the conflict/strategy interaction at preview time.

All types derive Serialize so the response is wire-stable; the HTTP endpoint at GET /v1/fluree/merge-preview/{ledger...} returns the same struct. See docs/api/endpoints.md and docs/cli/server-integration.md for the HTTP contract.

Reusable primitives in fluree-db-core

The per-commit summary types and DAG walker are factored into core for reuse outside the merge-preview flow (e.g., git-log-style commit history viewers, indexer integration). Re-exported from fluree-db-api:

• walk_commit_summaries(store, head, stop_at_t, max) -> Result<(Vec<CommitSummary>, usize)> — newest-first walk that returns both the (capped) summary list and the unbounded total count.
• commit_to_summary(commit) -> CommitSummary — pure function, no I/O.
• find_common_ancestor(store, head_a, head_b) — dual-frontier BFS.

Time Travel Queries

use fluree_db_api::{FlureeBuilder, TimeSpec, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let fluree = FlureeBuilder::memory().build_memory();

    // Query at a specific point in time
    let result = fluree.graph_at("mydb:main", TimeSpec::AtT(100))
        .query()
        .sparql("SELECT * WHERE { ?s ?p ?o } LIMIT 10")
        .execute()
        .await?;

    println!("Results at t=100: {:?}", result.row_count());

    Ok(())
}

Multi-Ledger Queries

use fluree_db_api::{FlureeBuilder, DataSetDb, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let fluree = FlureeBuilder::memory().build_memory();

    // Load views from multiple ledgers
    let customers = fluree.view("customers:main").await?;
    let orders = fluree.view("orders:main").await?;

    // Compose a dataset from multiple graphs
    let dataset = DataSetDb::new()
        .with_default(customers)
        .with_named("orders:main", orders);

    // Query across ledgers using the dataset builder
    let query = r#"
        SELECT ?customerName ?orderTotal
        WHERE {
            ?customer schema:name ?customerName .
            ?customer ex:customerId ?cid .

            GRAPH <orders:main> {
                ?order ex:customerId ?cid .
                ?order ex:total ?orderTotal .
            }
        }
    "#;

    let result = dataset.query(&fluree)
        .sparql(query)
        .execute()
        .await?;

    Ok(())
}

Remote Federation

Query ledgers on remote Fluree servers using SPARQL SERVICE with the fluree:remote: scheme. Register remote connections at build time — each maps a name to a server URL and optional bearer token:

use fluree_db_api::{FlureeBuilder, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let fluree = FlureeBuilder::file("./data")
        .remote_connection(
            "acme",
            "https://acme-fluree.example.com",
            Some("eyJhbG...".to_string()),
        )
        .build()?;

    let db = fluree.view("local-ledger:main").await?;

    // Join local data with a ledger on the remote server
    let result = fluree.query(&db, r#"
        PREFIX ex: <http://example.org/ns/>
        SELECT ?name ?email
        WHERE {
          ?person ex:name ?name .
          SERVICE <fluree:remote:acme/customers:main> {
            ?person ex:email ?email .
          }
        }
    "#).await?;

    Ok(())
}

The connection name (acme) maps to the server URL. The ledger path (customers:main) is appended to form the request URL: POST https://acme-fluree.example.com/v1/fluree/query/customers:main. The bearer token is sent as Authorization: Bearer <token> on every request.

Multiple ledgers on the same remote server use the same connection name — you register the server once and can query any ledger your token is authorized for.

See Configuration: Remote connections for details and SPARQL: Remote Fluree Federation for full query syntax.

FROM-Driven Queries (Connection Queries)

When the query body itself specifies which ledgers to target (via "from" in JSON-LD or FROM in SPARQL), use query_from():

use fluree_db_api::{FlureeBuilder, Result};
use serde_json::json;

#[tokio::main]
async fn main() -> Result<()> {
    let fluree = FlureeBuilder::memory().build_memory();

    // Query where the "from" is embedded in the query body
    let query = json!({
        "from": "mydb:main",
        "select": ["?name"],
        "where": { "@id": "?s", "schema:name": "?name" }
    });

    let result = fluree.query_from()
        .jsonld(&query)
        .execute_formatted()
        .await?;

    // SPARQL with FROM clause
    let result = fluree.query_from()
        .sparql("SELECT ?name FROM <mydb:main> WHERE { ?s <http://schema.org/name> ?name }")
        .execute_formatted()
        .await?;

    Ok(())
}

Background Indexing

use fluree_db_api::{FlureeBuilder, BackgroundIndexerWorker, Result};
use std::sync::Arc;
use tokio::time::{sleep, Duration};

#[tokio::main]
async fn main() -> Result<()> {
    let fluree = Arc::new(FlureeBuilder::file("./data").build()?);

    // Start background indexer
    let indexer = BackgroundIndexerWorker::new(
        fluree.clone(),
        Duration::from_secs(5), // Index interval
    );

    let indexer_handle = indexer.start();

    // Application logic
    let ledger = fluree.create_ledger("mydb").await?;

    // Transactions will be indexed automatically in background
    for i in 0..100 {
        let txn = json!({
            "@context": {"ex": "http://example.org/ns/"},
            "@graph": [{"@id": format!("ex:item{}", i), "ex:value": i}]
        });

        fluree.graph("mydb:main")
            .transact()
            .insert(&txn)
            .commit()
            .await?;
    }

    // Wait for indexing to complete
    sleep(Duration::from_secs(10)).await;

    // Shutdown indexer
    indexer_handle.shutdown().await?;

    Ok(())
}

BM25 Full-Text Search

use fluree_db_api::{
    FlureeBuilder, Bm25CreateConfig, Bm25FieldConfig, Result
};
use serde_json::json;

#[tokio::main]
async fn main() -> Result<()> {
    let fluree = FlureeBuilder::memory().build_memory();
    let ledger = fluree.create_ledger("mydb").await?;

    // Insert searchable data and create BM25 index
    // ...

    // Query with full-text search using JSON-LD and the f:graphSource pattern
    let search_query = json!({
        "@context": {
            "schema": "http://schema.org/",
            "f": "https://ns.flur.ee/db#"
        },
        "from": "mydb:main",
        "select": ["?product", "?score", "?name"],
        "where": [
            {
                "f:graphSource": "products-search:main",
                "f:searchText": "laptop",
                "f:searchLimit": 10,
                "f:searchResult": { "f:resultId": "?product", "f:resultScore": "?score" }
            },
            { "@id": "?product", "schema:name": "?name" }
        ],
        "orderBy": [["desc", "?score"]],
        "limit": 10
    });

    let result = fluree.query_from()
        .jsonld(&search_query)
        .execute()
        .await?;

    println!("Found {} matching products", result.row_count());

    Ok(())
}

Configuration

Builder Options

use fluree_db_api::{FlureeBuilder, ConnectionConfig, IndexConfig, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let config = ConnectionConfig {
        storage_path: "./data".into(),
        index_config: IndexConfig {
            interval_ms: 5000,
            batch_size: 10,
            memory_mb: 2048,
            threads: 4,
        },
        ..Default::default()
    };

    let fluree = FlureeBuilder::with_config(config).build()?;

    Ok(())
}

Custom Storage Backend

use fluree_db_api::{
    FlureeBuilder, Storage, StorageWrite, Result
};
use async_trait::async_trait;

// Implement custom storage
struct MyStorage;

#[async_trait]
impl Storage for MyStorage {
    async fn read(&self, address: &str) -> Result<Vec<u8>> {
        // Custom implementation
        todo!()
    }
}

#[async_trait]
impl StorageWrite for MyStorage {
    async fn write(&self, address: &str, data: &[u8]) -> Result<()> {
        // Custom implementation
        todo!()
    }
}

#[tokio::main]
async fn main() -> Result<()> {
    let storage = MyStorage;
    let fluree = FlureeBuilder::custom(storage).build()?;

    Ok(())
}

If you need full control over both storage and nameservice (e.g., for proxy mode or custom backends), use build_with():

#![allow(unused)]
fn main() {
let storage = MyStorage;
let nameservice = MyNameService;

let fluree = FlureeBuilder::memory()
    .build_with(storage, nameservice);
}

build_with() respects the builder’s caching configuration — caching is on by default, or call .without_ledger_caching() before build_with() to disable it.

Error Handling

use fluree_db_api::{FlureeBuilder, ApiError, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let fluree = FlureeBuilder::memory().build_memory();

    // Create a ledger — handles duplicates gracefully
    match fluree.create_ledger("mydb").await {
        Ok(ledger) => {
            println!("Ledger created at t={}", ledger.t());
        }
        Err(ApiError::LedgerExists(ledger_id)) => {
            println!("Ledger {} already exists, loading...", ledger_id);
            let ledger = fluree.ledger("mydb:main").await?;
            println!("Loaded at t={}", ledger.t());
        }
        Err(e) => {
            eprintln!("Error: {}", e);
            return Err(e);
        }
    }

    Ok(())
}

Testing

Unit Tests

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    use fluree_db_api::{FlureeBuilder, Result};
    use serde_json::json;

    #[tokio::test]
    async fn test_insert_and_query() -> Result<()> {
        // Use memory storage for tests
        let fluree = FlureeBuilder::memory().build_memory();
        let ledger = fluree.create_ledger("test").await?;

        // Insert data
        let data = json!({
            "@context": {"ex": "http://example.org/ns/"},
            "@graph": [{"@id": "ex:alice", "ex:name": "Alice"}]
        });

        fluree.graph("test:main")
            .transact()
            .insert(&data)
            .commit()
            .await?;

        // Query data
        let query = json!({
            "select": ["?name"],
            "where": [{"@id": "ex:alice", "ex:name": "?name"}]
        });

        let result = fluree.graph("test:main")
            .query()
            .jsonld(&query)
            .execute()
            .await?;

        assert_eq!(result.row_count(), 1);

        Ok(())
    }
}
}

Integration Tests

#![allow(unused)]
fn main() {
// tests/integration_test.rs
use fluree_db_api::{FlureeBuilder, Result};
use serde_json::json;
use tempfile::TempDir;

#[tokio::test]
async fn test_persistence() -> Result<()> {
    let temp_dir = TempDir::new()?;
    let path = temp_dir.path().to_str().unwrap();

    // Create ledger and write data
    {
        let fluree = FlureeBuilder::file(path).build()?;
        let ledger = fluree.create_ledger("test").await?;

        let data = json!({"@context": {}, "@graph": [{"@id": "ex:test"}]});
        fluree.graph("test:main")
            .transact()
            .insert(&data)
            .commit()
            .await?;
    }

    // Verify persistence by reopening
    {
        let fluree = FlureeBuilder::file(path).build()?;
        let ledger = fluree.ledger("test:main").await?;

        assert!(ledger.t() > 0);
    }

    Ok(())
}
}

Performance Tips

Batch Transactions

#![allow(unused)]
fn main() {
// Good: Batch related changes
let batch_data = json!({
    "@graph": [
        {"@id": "ex:item1", "ex:value": 1},
        {"@id": "ex:item2", "ex:value": 2},
        {"@id": "ex:item3", "ex:value": 3}
    ]
});
let result = fluree.graph("mydb:main")
    .transact()
    .insert(&batch_data)
    .commit()
    .await?;

// Bad: Individual transactions (more overhead per commit)
for i in 1..=3 {
    let txn = json!({"@graph": [{"@id": format!("ex:item{}", i), "ex:value": i}]});
    fluree.graph("mydb:main")
        .transact()
        .insert(&txn)
        .commit()
        .await?;
}
}

Use Appropriate Storage

• Memory: Fastest, no persistence (tests, temporary data)
• File: Good balance (single server, local development)
• AWS: Distributed, durable (production, multi-server)

Query Optimization

#![allow(unused)]
fn main() {
// Good: Specific patterns
let query = json!({
    "select": ["?name"],
    "where": [
        {"@id": "ex:alice", "schema:name": "?name"}
    ]
});

// Bad: Broad patterns
let query = json!({
    "select": ["?s", "?p", "?o"],
    "where": [
        {"@id": "?s", "?p": "?o"}
    ]
});
}

Enable Query Tracking

use fluree_db_api::{FlureeBuilder, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let fluree = FlureeBuilder::memory().build_memory();

    // Use execute_tracked() for fuel/time/policy tracking
    let tracked = fluree.graph("mydb:main")
        .query()
        .sparql("SELECT * WHERE { ?s ?p ?o }")
        .execute_tracked()
        .await?;

    println!("Query used {} fuel", tracked.fuel().unwrap_or(0));

    Ok(())
}

Graph API Reference

The Graph API follows a lazy-handle pattern: fluree.graph(graph_ref) returns a lightweight handle, and all I/O is deferred to terminal methods.

Getting a Graph Handle

#![allow(unused)]
fn main() {
// Lazy handle to the current (head) state
let graph = fluree.graph("mydb:main");

// Lazy handle at a specific point in time
let graph = fluree.graph_at("mydb:main", TimeSpec::AtT(100));
}

Querying

#![allow(unused)]
fn main() {
// JSON-LD query (lazy — loads graph at execution time)
let result = fluree.graph("mydb:main")
    .query()
    .jsonld(&query_json)
    .execute().await?;

// SPARQL query
let result = fluree.graph("mydb:main")
    .query()
    .sparql("SELECT ?s WHERE { ?s a <ex:Person> }")
    .execute().await?;

// Formatted output (JSON-LD or SPARQL JSON based on query type)
let json = fluree.graph("mydb:main")
    .query()
    .jsonld(&query_json)
    .execute_formatted().await?;

// Tracked query (fuel/time/policy metrics)
let tracked = fluree.graph("mydb:main")
    .query()
    .sparql("SELECT * WHERE { ?s ?p ?o }")
    .execute_tracked().await?;
}

Materializing a GraphSnapshot

#![allow(unused)]
fn main() {
// Load once, query many times (avoids reloading)
let db = fluree.graph("mydb:main").load().await?;

let r1 = db.query().sparql("...").execute().await?;
let r2 = db.query().jsonld(&q).execute().await?;

// Access the underlying GraphDb
let view = db.view();
}

Transacting

#![allow(unused)]
fn main() {
// Insert and commit
let result = fluree.graph("mydb:main")
    .transact()
    .insert(&data)
    .commit().await?;

// Upsert with options. f:identity is system-controlled (signed DID,
// opts.identity, or CommitOpts::identity). f:message and f:author are
// pure user claims — supply them in the transaction body just like any
// other txn-meta property.
let data = serde_json::json!({
    "@context": {
        "ex": "http://example.org/",
        "f": "https://ns.flur.ee/db#"
    },
    "@graph": [{ "@id": "ex:alice", "ex:name": "Alice" }],
    "f:message": "admin update",
    "f:author": "did:admin"
});

let result = fluree.graph("mydb:main")
    .transact()
    .upsert(&data)
    .commit_opts(CommitOpts::default().identity("did:admin"))
    .commit().await?;

// Stage without committing (preview changes)
let staged = fluree.graph("mydb:main")
    .transact()
    .insert(&data)
    .stage().await?;

// Query staged state
let preview = staged.query()
    .jsonld(&validation_query)
    .execute().await?;
}

Commit Inspection

Decode and display the contents of a commit — assertions and retractions with IRIs resolved to compact form. Similar to git show for individual commits.

#![allow(unused)]
fn main() {
// By exact CID
let detail = fluree.graph("mydb:main")
    .commit(&commit_id)
    .execute().await?;

// By transaction number
let detail = fluree.graph("mydb:main")
    .commit_t(5)
    .execute().await?;

// By hex-digest prefix (min 6 chars, like abbreviated git hashes)
let detail = fluree.graph("mydb:main")
    .commit_prefix("3dd028")
    .execute().await?;

// With a custom @context for IRI compaction
let detail = fluree.graph("mydb:main")
    .commit_prefix("3dd028")
    .context(my_parsed_context)
    .execute().await?;

// Access the result
println!("t={}, +{} -{}", detail.t, detail.asserts, detail.retracts);
for flake in &detail.flakes {
    let op = if flake.op { "+" } else { "-" };
    println!("{} {} {} {} [{}]", op, flake.s, flake.p, flake.o, flake.dt);
}
}

The returned CommitDetail contains:

• Metadata: id, t, time, size, previous, signer, asserts, retracts
• context: prefix → IRI map derived from the ledger’s namespace codes
• flakes: flat list in SPOT order, each with resolved compact IRIs

CommitDetail implements Serialize — flakes serialize as [s, p, o, dt, op] tuples (with an optional 6th metadata element for language tags, list indices, or named graphs).

Terminal Operations

Format Override

#![allow(unused)]
fn main() {
use fluree_db_api::FormatterConfig;

// Force JSON-LD format for a SPARQL query
let result = fluree.graph("mydb:main")
    .query()
    .sparql("SELECT ?name WHERE { ?s <schema:name> ?name }")
    .format(FormatterConfig::jsonld())
    .execute_formatted()
    .await?;
}

Multi-Ledger Queries (Dataset)

For multi-ledger queries, use GraphDb directly:

#![allow(unused)]
fn main() {
let customers = fluree.view("customers:main").await?;
let orders = fluree.view("orders:main").await?;

let dataset = DataSetDb::new()
    .with_default(customers)
    .with_named("orders:main", orders);

let result = dataset.query(&fluree)
    .sparql(query)
    .execute().await?;
}

FROM-Driven Queries (Connection Queries)

#![allow(unused)]
fn main() {
let result = fluree.query_from()
    .jsonld(&query_with_from)
    .execute().await?;
}

Transaction Builder API Reference

There are two transaction builder patterns, each suited for different use cases:

stage(&handle) — Server/Application Pattern (Recommended)

Use stage(&handle) when building servers or applications with ledger caching enabled. The handle is borrowed and updated in-place on successful commit, ensuring concurrent readers see the update.

use fluree_db_api::{FlureeBuilder, Result};
use serde_json::json;

#[tokio::main]
async fn main() -> Result<()> {
    // Caching is on by default (required for stage)
    let fluree = FlureeBuilder::file("./data").build()?;

    // Get a cached handle
    let handle = fluree.ledger_cached("mydb:main").await?;

    // Transaction via builder — handle updated in-place
    let data = json!({"@graph": [{"@id": "ex:test", "ex:name": "Test"}]});
    let result = fluree.stage(&handle)
        .insert(&data)
        .execute()
        .await?;

    println!("Committed at t={}", result.receipt.t);

    // Handle now reflects the new state
    let snapshot = handle.snapshot().await;
    assert_eq!(snapshot.t, result.receipt.t);

    Ok(())
}

Why use stage(&handle):

• Concurrent safety: Multiple requests share the same handle; updates are atomic
• No ownership dance: You don’t need to track and pass around LedgerState values
• Server-friendly: Matches how the HTTP server handles transactions internally

stage_owned(ledger) — CLI/Script/Test Pattern

Use stage_owned(ledger) when you manage your own LedgerState directly. This is typical for CLI tools, scripts, and tests where you don’t need ledger caching.

use fluree_db_api::{FlureeBuilder, Result};
use serde_json::json;

#[tokio::main]
async fn main() -> Result<()> {
    let fluree = FlureeBuilder::memory().build_memory();

    // You own the ledger state
    let ledger = fluree.create_ledger("mydb").await?;

    // Transaction consumes ledger, returns updated state
    let data = json!({"@graph": [{"@id": "ex:test", "ex:name": "Test"}]});
    let result = fluree.stage_owned(ledger)
        .insert(&data)
        .execute()
        .await?;

    // Get the updated ledger from the result
    let ledger = result.ledger;
    println!("Now at t={}", ledger.t());

    Ok(())
}

Why use stage_owned(ledger):

• Simple ownership: Good for linear workflows (load → transact → done)
• No caching required: Works even with without_ledger_caching()
• Test-friendly: Each test manages its own state

Choosing Between Them

Builder Methods (Both Patterns)

Both stage(&handle) and stage_owned(ledger) return a builder with identical methods:

#![allow(unused)]
fn main() {
let result = fluree.stage(&handle)  // or stage_owned(ledger)
    .insert(&data)                   // or .upsert(&data), .update(&data)
    .commit_opts(CommitOpts::default().identity("did:admin"))
    .execute()
    .await?;
// (Include `f:message` / `f:author` directly in `data` for user-claim provenance.)
}