ingest

ingest loads JSONL data the same way load does, but creates (or reuses) a named branch for the load rather than writing to the caller's current branch. The result is a reviewable batch. Inspect the branch, validate it, and merge when ready.

Usage

omnigraph ingest <path> --data <file> --branch <name> [--from <base>] [options]

Arguments

Argument	Required	Description
`path`	yes	Graph URI (local path or `s3://`); required unless resolved from `--target` / `--config`

Options

Option	Required	Default	Description
`--data`	yes	—	Path to a `.jsonl` file containing node and edge records
`--branch`	no	inferred	Name of the branch to create or reuse for the ingest
`--from`	no	`main`	Base branch the new branch forks from
`--mode`	no	`merge`	Load mode: `overwrite`, `append`, or `merge`
`--target`	no	—	Named graph from `omnigraph.yaml`
`--config`	no	—	Path to an `omnigraph.yaml`
`--json`	no	—	Output a structured ingest summary

When to use ingest vs load

Command	Branch behavior	Default mode	Typical use
`load`	Writes to the caller's branch (`--branch` or `main`)	`overwrite`	Bootstrapping a graph; replacing a known table
`ingest`	Creates / writes a dedicated branch	`merge`	Reviewable agent batches; periodic data syncs that need approval before landing

Examples

Stage a daily import on a review branch and merge after validation:

omnigraph ingest ./graph.omni \
    --data ./batch-2026-05-27.jsonl \
    --branch review/import-2026-05-27

# Inspect the new branch
omnigraph snapshot ./graph.omni --branch review/import-2026-05-27
omnigraph read --uri ./graph.omni --query validation.gq --branch review/import-2026-05-27

# Merge when satisfied
omnigraph branch merge --uri ./graph.omni review/import-2026-05-27 --into main

Fork a review branch from a non-main base:

omnigraph ingest ./graph.omni \
    --data ./enrichment.jsonl \
    --branch enrichment-run-042 \
    --from feature-x