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: 60% of system RAM). Drives chunk size, concurrency, and indexer run budget. Set this to cap how much memory the import uses; auto-detected thread count shrinks to fit it.
• --parallelism <N> — Number of parallel parse threads (0 = auto: most logical cores, capped to fit the memory budget; explicit values honored as-is, floored at 1).

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, N-Triples, N-Quads, TriG, or JSON-LD file (or a directory of same-format files). Any input may be gzip- or zstd-compressed and is decoded transparently (data.ttl.gz, dump.nq.zst, mixed directories — the underlying RDF extension classifies the file). N-Triples (.nt) is a strict subset of Turtle and is parsed by the same parser. N-Quads (.nq) and TriG (.trig) support named graphs — queryable after import via the #<graph-iri> fragment. For large Turtle/N-Triples files (including .ttl.gz/.nt.gz), the CLI splits work into chunks and runs parallel parse threads — though compressed inputs decode single-threaded; TriG/N-Quads/JSON-LD use a serial path. Tune with --memory-budget-mb and --parallelism if needed.

Directory imports (.ttl/.nt) are rechunked by bytes rather than one-chunk-per-file: large files are sub-split at statement boundaries and many small files are coalesced into ~chunk_size work items. This keeps the import fully parallel and bounds the number of commits and sorted index runs regardless of how the data is packaged — so a directory of one big file, or of hundreds of tiny shards, both import at full speed. Coalescing engages automatically once a directory holds more than 64 sub-chunk_size files; a file containing a labeled blank node (_:) or an @base directive is never coalesced (it would change RDF document scope) and is imported as its own chunk. Set FLUREE_IMPORT_COALESCE_THRESHOLD=<n> to change the gate (0 disables coalescing — every file becomes its own commit, the legacy behavior). Directories containing any .trig/.nq/.jsonld continue to use the per-file serial path.

Property-graph imports (CSV & Cypher)

Two property-graph front-ends convert to JSON-LD on the fly and load through the same chunked bulk-import pipeline (not the per-transaction write path):

• CSV (.csv, single file or a directory of them) — node/relationship files in the neo4j-admin import header convention (:ID, :LABEL, :START_ID/:END_ID, :TYPE, name:type columns).
• Cypher scripts (.cypher/.cyp/.cql, single file or a directory) — ;-separated statements in the Neo4j/Memgraph dump idiom: CREATE for nodes (and inline paths), and MATCH (n:L {key: v}), (m:L {key: v}) CREATE (n)-[:T]->(m) for edges between property-matched nodes. Anything else (MERGE, SET, reads, …) fails the import with its line number.

Cypher node identity is derived from the property sets MATCH uses per label (learned in a first pass): CREATE (:User {id: 42, …}) and MATCH (n:User {id: 42}) both resolve to the stable id User/42, so edges land on the right nodes without replaying statements transactionally. Two CREATEs with the same key values therefore merge into one node, and an edge whose endpoint was never created is skipped (with a warning count) — MATCH finds nothing, so the statement is a no-op.

By default a Cypher import emits bare names (namespace 0), the same resolution Cypher’s own read/write paths use — the imported data is queryable with zero configuration (MATCH (n:User {id: 42}) RETURN n). Pass --base-iri to mint prefixed IRIs instead (RDF-compat; pair it with a ledger default context carrying the matching @vocab). CSV always mints prefixed IRIs (--base-iri, default http://example.org/).

Edge properties follow --edge-properties in both formats. Note the Cypher read contract: a plain (property-less) edge is visible to (a)-[:T]->(b) and --> patterns, but a relationship variable ((a)-[r:T]->(b)) only binds reified (annotated) edges.

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.

Restoring from a .flpack archive

When --from points at a .flpack file (produced by fluree export <ledger> --format ledger), the ledger is restored wholesale rather than bulk-imported: every commit, transaction blob, and prebuilt index artifact is streamed straight into storage and the heads are set from the archive — the restored ledger is byte-for-byte identical and immediately queryable, under whatever name you choose.

Add --remote <name> to restore onto a server instead of locally; the archive streams to the server’s import endpoint, so no local staging instance is needed. This makes .flpack the universal way to move any data onto a server — build a ledger locally in any format, export it, then import it remotely. See pack archive & restore for the full workflow.

If the remote is size-capped (e.g. an app behind a payload-limited gateway) and advertises it in discovery, the CLI automatically switches to a negotiated upload: it uploads the archive out-of-band to object storage and the server restores from it asynchronously. No extra flags — the path is chosen from the server’s capabilities and the archive size.

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

# Bulk-load a Cypher dump (e.g. a Memgraph/Neo4j benchmark dataset)
fluree create pokec --from pokec_import.cypher

# Bulk-load neo4j-admin convention CSVs, dropping edge properties
fluree create snb --from ./csv-dir --edge-properties plain

# Restore a .flpack archive into a new local ledger (any name)
fluree create restored-db --from mydb.flpack

# Restore a .flpack archive onto a remote server
fluree create restored-db --remote origin --from mydb.flpack

# 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