fluree upsert
Upsert data into a ledger (insert or update existing).
Usage
fluree upsert [LEDGER] [DATA] [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 |
|---|---|
-l, --ledger <LEDGER> | Ledger name (defaults to active ledger); explicit alternative to the positional ledger argument |
-e, --expr <EXPR> | Inline data expression (alternative to positional) |
-f, --file <FILE> | Read data from a file |
-m, --message <MSG> | Commit message |
--format <FORMAT> | Data format: turtle (nt for N-Triples), trig or jsonld (auto-detected if omitted) |
--remote <NAME> | Execute against a remote server (by remote name, e.g., origin) |
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.
Supports Turtle, N-Triples, TriG and JSON-LD. In TriG, values are replaced within each GRAPH <iri> { ... } block’s named graph, and a GRAPH <#txn-meta> { ... } block becomes commit metadata. The format is detected the same way as for insert: --format, then the extension (.ttl/.nt, .trig, .json/.jsonld), then the content, and Turtle that contains graph blocks is read as TriG.
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 a TriG file: values are replaced within each named graph
fluree upsert -f updates.trig
# 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
| Operation | Existing Entity | New Entity |
|---|---|---|
insert | Adds new triples (may create duplicates) | Creates entity |
upsert | Replaces values for given predicates | Creates entity |