load

The load command reads a JSONL file and writes its contents into the graph. 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/edge records
`--branch`	no	`main`	Target branch for the load
`--mode`	no	`overwrite`	Load mode: `overwrite`, `append`, or `merge`
`--json`	no	—	Output load summary as JSON

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. Fail if a row with the same `@key` already exists.
`merge`	Upsert: insert new rows, update existing rows that share the same `@key`.

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

Upsert — insert new rows and update existing ones by key:

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

{
  "branch": "main",
  "tables": [
    { "table": "Person", "rows_written": 847 },
    { "table": "Company", "rows_written": 124 },
    { "table": "WorksAt", "rows_written": 912 }
  ]
}

On this page