Session settings

A file may open with settings lines, before its declarations or its one statement. set <name> = <value>; gives one setting a value for that file: the CLI applies it to the invocation, the server to the request, and nothing is persisted, so the next file starts from the process defaults again. The same name set twice in one file takes the last value. reset <name>; restores one setting's process default; reset all; restores every setting the caller may set. show <name>; and show all; are themselves the file's one statement, run through omnigraph query or POST /query, and return one row per setting with the columns name, value, default, source and scope. source is default, env (a process default read from the environment), request (the settings field, a set query parameter or --set) or file (a set line). A file of only settings lines, set or reset, reset all; alone included, is refused: a file of only settings lines carries no statement.

set merge_lineage = verify;

query reports($who: String) {
  match { $p: Person { name: $who }  $p reportsTo{1,3} $m }
  return { $m.name }
}

reset merge_lineage;
branch merge review into main;

show all;

show is authorized as a scope-free read, the decision branch list takes: a credential scoped to one branch, or one holding only change permissions, is refused show. A graph-wide reader sees every row, process rows included, and each row's source says whether the value came from the environment.

Every setting has a scope. A request setting is set by any caller. A process setting is set only by the process that hosts the engine: the server from its environment, and a direct CLI run (--target) from its environment, its --set values and the file; a served caller's settings field, set query parameter or set line naming one is refused.

A setting reaches the engine through one of three doors:

• CLI: --set name=value, repeatable, on omnigraph query, mutate, branch merge, commit changes and changes poll, and direct --target loads; see the CLI guide.
• HTTP body: the settings object on POST /query, POST /mutate, POST /mutate/if-graph-commit and POST /branches/merge, one key per request setting ({"settings": {"merge_lineage": "verify"}}); an unknown key is refused.
• HTTP query string: set=<name>=<value>, repeatable, on GET /changes and GET /commits/{id}/changes.

A set line in the text applies after the door's value, so the file wins.

A stored query runs under the process defaults: omnigraph query <name> without -e or --query refuses --set, and POST /queries/{query_name} takes no settings field.

Each setting's environment variable is its process default: the server reads it once at startup, the CLI once per run, and the value is what every request starts from and what reset returns to. An invalid or out-of-range value refuses startup; no default is substituted.

For these statements the cap covers all traversals, including named and nested ones, and remains shared across retries. It charges consumed source rows, conservative physical edge rows before each scan, examined adjacency entries and bound-edge source replication. Exceeding the cap fails with traversal_work_limit; a result limit cannot bypass admission. This is a row-work bound, not a byte, elapsed-time or total-query CPU/I/O bound. Memory and scratch retain their existing limits. The budgeted route uses pinned Lance scans with indexed filtering where available.

Sources are admitted in fixed windows of at most 8,192 rows, independent of upstream batch boundaries. Each nonempty frontier probe charges the selected table's full physical row count before opening the scan. Multiple windows, members, directions and hops can therefore charge a table repeatedly. A directed one-hop query over selected tables totaling 1,000,000 physical rows exceeds the default cap even when its start node has only one neighbor. Index selectivity does not reduce this conservative admission charge. The cap does not bound index decoding, bytes read, or storage latency.

Internal traversal pins used by the GQT harness can force indexed execution. A forced CSR pin is refused for statements with selections; there is no public set traversal setting.

write_max_bytes applies to each existing write account: row data and Blob descriptors, logical Blob payloads, parser estimates and retained removed IDs. The accounts keep their existing per-table, per-operation or per-chunk scope. Row data and Blob payloads have separate allowances: a payload exactly at the limit can accompany a row whose metadata fits its own allowance. The value is captured once for an operation, including its retries and merge publication. A one-row keyed write costs about 1 to 3 KiB of row data from Arrow buffer rounding, so allowances below a few KiB refuse every write.

Strict inserts and overwrite writes also pass write_max_bytes to Lance as the buffer accumulation target for each data-file writer. Lance divides it across top-level columns instead of using its default 8 MiB per column. The default 32 MiB target therefore raises or lowers each column's threshold depending on the number of columns. This is a flush threshold, not a total memory cap: the incoming array can cross it, nested fields and encoding have additional working memory, and concurrent table writers each receive the target. Upserts and updates use Lance merge-insert, which does not expose this option and keeps its native buffering defaults. Row and Blob admission limits still apply to those writes.

Neither byte setting has a fixed maximum. A lower environment value is a process default, so a request may still select any value of at least 1. Raising write_max_bytes above the default admits a larger staged-write input (a JSONL load's typed batch, a CSV overwrite's reader batch), held in memory at commit; raising load_source_max_bytes admits a larger load csv source object into memory before parsing. On a server both stay bounded by workload admission (OMNIGRAPH_GLOBAL_BYTES_MAX, OMNIGRAPH_PER_ACTOR_BYTES_MAX). Embedded sessions and direct --target CLI loads can override them; a load csv statement travels on /mutate, whose settings field and set prefix apply. The JSONL HTTP load routes inherit the process default and accept no request setting; remote CLI loads of those routes refuse --set. HTTP bodies, Blob reads, compaction and external URI metadata retain their independent limits. Lower values can produce smaller merge chunks or reject a write that the default admits.

history_release_bytes is measured against the branch's buffered commit and table-change rows as stored, plus the head whole; the row layout is in storage versioning. The commit that reaches the budget records the decision in its commit id's slot, so sessions publishing to one branch under different budgets agree on where a block closes, and the publish after it releases the block whatever its own budget. A load carries the setting only from the CLI or an embedded Session: the HTTP load routes take no settings. The bound on a head's commit fields stays 256 KiB, the production budget. A lower budget means more and smaller __history files and more requests per release, never different rows.

A name outside the table, a value of the wrong type, and a value outside the declared values or range are each refused with the table's row. A process setting named in a request is refused too: the settings field has no member for one, so the key is refused as unknown, while a set line in the text and a set= parameter answer the row's message. omnigraph lint reports a settings line's refusal as ERROR line <n>, column <c>: <message>.

set merge_lineage = fast;
error: unknown value `fast` for setting `merge_lineage`; expected one of off, on, verify
set traversal = csr;                      (likewise reset traversal; and show traversal;)
error: unknown setting `traversal`; expected one of engine, rrf_plan, merge_lineage, ann_nprobes, stage_write_concurrency, traversal_work_limit, write_max_bytes, load_source_max_bytes, query_memory_bytes, history_release_bytes, explain_dump_dir
set ann_nprobes = "many";
error: setting `ann_nprobes` takes an integer of at least 0, got a string
set stage_write_concurrency = 0;
error: setting `stage_write_concurrency` takes an integer in 1..=64, got 0
set stage_write_concurrency = 64;        (in an HTTP request)
error: setting `stage_write_concurrency` is a process setting; it is read from the server's environment, not from a request

See Query language for query syntax.