load

The load command reads a JSONL file and writes its contents into a local repository. Each line in the file is either a node or an edge record, validated against the repository schema before insertion.

Usage

omnigraph load <path> --data <file> [options]

Arguments

Argument	Required	Description
`path`	yes	Path to the Omnigraph repository

Options

Option	Required	Default	Description
`--data`	yes	—	Path to a `.jsonl` file containing node and edge records
`--branch`	no	`main`	Target branch for the load
`--mode`	no	`overwrite`	Load mode: `overwrite`, `append`, or `merge`
`--json`	no	—	Output a structured load summary

JSONL format

Node records

Each node record has a type field matching a node declaration in the schema, and a data object with the property values:

{"type": "Person", "data": {"name": "Alice", "age": 32}}
{"type": "Person", "data": {"name": "Bob", "age": 28}}
{"type": "Company", "data": {"name": "Acme Corp"}}

Edge records

Each edge record has an edge field matching an edge declaration, plus from and to fields referencing the @key values of the source and target nodes:

{"edge": "WorksAt", "from": "Alice", "to": "Acme Corp"}
{"edge": "Knows", "from": "Alice", "to": "Bob", "data": {"since": "2024-01-15"}}

Edge records with properties include a data object for the edge's own fields. Edges without properties omit data.

Load modes

Mode	Behavior
`overwrite`	Replace all existing rows in each affected table with the rows from the file
`append`	Add new rows; conflicts still fail validation
`merge`	Upsert compatible rows while preserving unaffected data

Examples

Load data into the default branch (main):

omnigraph load ./repo.omni --data data.jsonl

Load into a specific branch:

omnigraph load ./repo.omni --data updates.jsonl --branch feature-x

Append new records without overwriting existing data:

omnigraph load ./repo.omni --data new-records.jsonl --mode append

Merge data into an existing branch:

omnigraph load ./repo.omni --data enriched.jsonl --mode merge --branch enrichment

Get a JSON summary of what was loaded:

omnigraph load ./repo.omni --data data.jsonl --json

{
  "uri": "./repo.omni",
  "branch": "main",
  "mode": "overwrite",
  "nodes_loaded": 847,
  "edges_loaded": 912,
  "node_types_loaded": 2,
  "edge_types_loaded": 1
}

On this page