fluree sync

Synchronize a graph: make its contents exactly the supplied data, committing only the delta.

Usage

fluree sync [LEDGER] [DATA] [--graph <IRI>] [OPTIONS]

Arguments

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

Options

Option	Description
`-g, --graph <IRI>`	Target named graph IRI — the sync scope. The payload never widens or narrows it. Omit it to sync the default graph.
`-l, --ledger <LEDGER>`	Ledger name (defaults to active ledger)
`-e, --expr <EXPR>`	Inline data expression (Turtle, TriG or JSON-LD)
`-f, --file <FILE>`	Read data from a file
`--format <FORMAT>`	Data format: `turtle` (`nt` for N-Triples), `trig` or `jsonld` (auto-detected if omitted)
`--dry-run`	Compute and report the delta (asserted / retracted counts) without committing
`--allow-empty`	Allow an empty payload, which clears the graph (off by default so a truncated export cannot silently wipe it)
`--json`	Emit the report as JSON — the same shape as the server’s dry-run response — instead of a sentence
`--remote <NAME>`	Execute against a remote server (by remote name, e.g., `origin`)
policy flags	`--as`, `--policy-class`, `--policy`, … — same as `insert` / `upsert`

Sync is the “full replacement” verb for data whose source of truth lives outside Fluree — an ontology maintained in an editor, a reference table regenerated by a pipeline. Given the graph’s current contents A and the payload B, one commit retracts A − B and asserts B − A; unchanged facts produce no flakes, and an identical payload produces no commit. History is preserved. See Sync (graph synchronization) for the full semantics, safety rails, and blank-node behavior.

Turtle input is converted to JSON-LD client-side before submission, so a Turtle export works against any server that implements the /sync endpoint, including servers from before it accepted Turtle bodies. A .nt file is read as Turtle, of which N-Triples is a subset.

TriG is sent as TriG rather than converted. It is recognized by a .trig name or --format trig, and also when a body read as Turtle turns out to hold graph blocks, as when it is piped in. Its blocks must name the --graph target, and cannot sit beside default-graph triples (see payload formats):

fluree sync mydb --graph http://example.org/graphs/ontology -f ontology.trig

With --remote, the server must accept TriG on /sync.

Sources

The target graph is the constant of this command; the source of the desired contents is pluggable. Today the source is RDF text — a file, an inline expression, or stdin. The same command shape is where mapped sources will plug in: an R2RML mapping applied to an Iceberg table, CSV, or spreadsheet resolves to the same payload and flows through the same verb, so “sync this graph to the latest downstream data” is one flag set away rather than a new command. Running with --remote moves where that materialization happens, not what is committed.

Pipelines

--dry-run --json is the pre-flight for scheduled syncs: run it, inspect retracted (an unexpectedly large count is a cheap tripwire for a truncated export), then run for real. The real run is idempotent — re-running with the same export is a no-op.

Examples

# Sync an ontology from a Turtle export
fluree sync mydb --graph urn:example:ontology -f ontology.ttl

# Sync the default graph (no --graph)
fluree sync mydb -f data.ttl

# Pre-flight: what would change?
fluree sync mydb --graph urn:example:ontology -f ontology.ttl --dry-run

# Machine-readable, against a remote
cat export.jsonld | fluree sync --graph urn:example:ontology --remote origin --json

# Clear the graph on purpose
echo '{"@graph": []}' | fluree sync mydb --graph urn:example:ontology --allow-empty

Output

Synced graph <urn:example:ontology> in 'mydb:main': +2 asserted, -2 retracted (t=7).
Graph <urn:example:ontology> in 'mydb:main' already matches the payload — no commit produced (t=7).
Would sync graph <urn:example:ontology> in 'mydb:main': +2 asserted, -2 retracted (dry run; head t=7).

With --json:

{ "ledger": "mydb:main", "graph": "urn:example:ontology",
  "asserted": 2, "retracted": 2, "committed": true, "dryRun": false, "t": 7 }

Fluree DB