Environment Variables

Relata DB 3.0
This page is the 3.0 open-build reference, generated from the repository file docs/src/end-users/environment-variables.md. For 2.x variables see the frozen version snapshots. Relata DB 3.0 is a single-machine build: the public gRPC, PostgreSQL wire, Arrow Flight, S3, Neo4j and Bolt listeners are retired, there is no clustering, no licensing and no multi-tenant mode, and RELATA_PROFILE accepts only free. Variables for those features are not documented here; the retired ones fail startup when set (see the protocol migration guide).

Defaults shown are the compiled-in values; — means the feature is disabled when the variable is absent.

Config precedence: env > file > built-in default. File search order: (1) --config <path> flag, (2) RELATA_CONFIG env var, (3) ./relata.toml, (4) ~/.relata/relata.toml. Run relata config --print-template for a commented starter, or relata config --validate to check your config before boot.

Strict parsing. Malformed values FATAL at startup. Removed or renamed variables also FATAL; run relata config --migrate when upgrading from an earlier release.

Core server

VariableDefaultDescription
RELATA_PROFILEfreeAccepts only free, which is the default, so there is nothing to set. Startup fails (FATAL) on server, cluster (retired in 3.0), lite (removed) or any other value. Auth, TLS and bind posture follow configuration - see RELATA_HTTP_BIND, RELATA_BEARER_TOKEN, RELATA_OPEN_DEV_ALLOWED and RELATA_PLAINTEXT_OK below.
RELATA_PORT9090HTTP API port.
RELATA_HOST—Advertised host name (used for the A2A Agent Card base URL when RELATA_A2A_BASE_URL is unset). Falls back to the bind address.
RELATA_HTTP_BIND127.0.0.1:<port>HTTP bind address for the data plane, including governed query, ingest, GraphQL, MCP, and Files APIs. Since #2082 this listener no longer serves /admin/* or /admin/platform/* at all — see RELATA_ADMIN_BIND below. Also the input to is_loopback_bind() (127.0.0.1/[::1] prefix, or unset), which gates RELATA_OPEN_DEV_ALLOWED and the RELATA_PLAINTEXT_OK default (#2073).
RELATA_ADMIN_BIND127.0.0.1:9091#2082 (ADR-0261 v1 — Zero-Trust control plane). Bind address for a SECOND, dedicated TcpListener that exclusively serves /admin/* and /admin/platform/*. These routes are not mounted on the data-plane listener (RELATA_HTTP_BIND) at all — a request to them there gets a plain 404 (the route doesn't exist), not 401/403, so a remote peer cannot even confirm an admin surface exists. Must resolve to a loopback address (127.0.0.0/8 or ::1) — startup fails (FATAL) otherwise; this is deliberate (ADR-0261: "Loopback is enforced by TCP, not by an HTTP header check"), not a bug — widening it would silently reintroduce a network-reachable admin token. Reach it via kubectl port-forward svc/relata 9091:9091 or an mTLS control-plane sidecar in the same pod/network namespace; never expose it directly.
RELATA_ADMIN_URLderived from RELATA_ADMIN_BIND (http://127.0.0.1:9091)(#2852) CLI-side override for the admin listener's base URL, read by relata rebuild-index vector|phash (crates/relata-cli/src/main.rs's admin_listener_base) when the operator already knows the admin listener's externally-reachable address (e.g. the local end of a kubectl port-forward/mTLS tunnel to the loopbound RELATA_ADMIN_BIND address, which is not itself reachable from outside the pod/node). When unset, falls back to http://<RELATA_ADMIN_BIND>. Server-side, this variable has no effect — only RELATA_ADMIN_BIND controls what the admin listener actually binds to.
RELATA_BEARER_TOKEN—Root bootstrap secret used to mint registry credentials. It is not itself a data-plane bearer token. Set it persistently on any node that is not a throwaway local one; data-plane HTTP/JSON, GraphQL, and MCP calls use registry-minted tokens.
RELATA_ADMIN_TOKEN—Admin-only token for the /admin/* + /admin/platform/* surface (privilege-separated from RELATA_BEARER_TOKEN per ADR-131), gated on the loopbound listener described under RELATA_ADMIN_BIND (#2082, ADR-0261). Gates: /admin/console (HTML), /admin/tokens, /admin/backup, /admin/backups, /admin/restore, /admin/compact, /admin/rotate-dek, and the /platform/* routes. When unset, the entire admin surface returns 401 — unless RELATA_OPEN_DEV_ALLOWED=true (#2073 — see below). Browser access: GET /admin/console?token=<RELATA_ADMIN_TOKEN> (the client JS reads ?token= from the URL). Env-only by design (ADR-131): this is a privileged secret and is deliberately not persisted to disk or config — it must be re-supplied on every restart. A restart without it leaves /admin/* and admin-gated features unprovisioned (a client sees this as a degraded/"stub" mode); startup logs a loud Admin surface: UNPROVISIONED warning so the state is never silent (#374). Note: #58 tracks an open gap where check_admin_auth falls back to the bearer token when RELATA_ADMIN_TOKEN is unset — set both tokens explicitly in production until #58 closes. POST /admin/tokens is the real token-creation endpoint (not POST /tokens, which is unrelated idempotency-key plumbing). Minted tokens are persisted to the token-registry path under RELATA_CONFIG_DIR (default ${RELATA_DATA_DIR}/config).
RELATA_OPEN_DEV_ALLOWEDfalse(#2073) Explicit, uniform-across-every-profile opt-in for the unauthenticated local-dev convenience that used to be a silent RELATA_PROFILE=free special case. When true, AND no RELATA_BEARER_TOKEN/RELATA_ADMIN_TOKEN/registered token is configured, AND RELATA_AUTH_MODE resolves to none (unauthenticated), AND the relevant listener is bound to loopback (data plane: RELATA_HTTP_BIND; admin surface: RELATA_ADMIN_BIND, #2082 — checked fresh per request, never by profile), every data endpoint (check_auth_with_registry), the admin surface (check_static_admin_auth), and the diagnostics surface (diagnostics_auth_ok) are open with no token. Fail-closed on every axis: unset, a configured credential, a non-None auth mode, or a non-loopback bind all keep the gate closed regardless of profile. Do not set this outside local development.
RELATA_SECURITY_MODEstrict(#4945) strict (default) or open — the master posture over the weak-security/dev-mode opt-out flag RELATA_KMS_LOCAL_DEV. Under strict, that setting fails startup. Set open only when intentionally using that development setting. The value is a strict `strict
RELATA_PLAINTEXT_OKunset (defaults to true only on a loopback bind)(#2073 — uniform across every profile, including free) Set true/false explicitly to allow/require TLS termination in front of a plaintext HTTP listener when RELATA_TLS_CERT/RELATA_TLS_KEY are not configured. If unset, the effective default is true when the bind is loopback (RELATA_HTTP_BIND unset or 127.0.0.1/[::1]) and false (TLS required, startup FATALs) otherwise — the same loopback predicate RELATA_OPEN_DEV_ALLOWED uses. There is no longer a free-only unconditional plaintext pass: a free-profile server bound to 0.0.0.0 needs RELATA_TLS_CERT/RELATA_TLS_KEY or an explicit RELATA_PLAINTEXT_OK=true exactly like server/cluster.
RELATA_DATA_DIR./data/relataRoot directory for config files and WAL state. Keep it on a persistent volume. #4623: also the source of the default admin token-registry path when RELATA_CONFIG_DIR is unset — see RELATA_CONFIG_DIR below; minted tokens (POST /admin/tokens) ride this same volume by default, no separate mount needed.
RELATA_CONFIG_DIRunset → ${RELATA_DATA_DIR}/config if RELATA_DATA_DIR is set, else ~/.relataOverride directory for TOML config files (takes priority over RELATA_DATA_DIR) and the base directory for the admin token registry (TokenRegistry::default_path(), crates/relata-cli/src/serve/admin_tokens.rs): the registry persists to ${RELATA_CONFIG_DIR}/tokens.json. #4623 fix: before this, the token-registry fallback was unconditionally ~/.relata, independent of RELATA_DATA_DIR — the volume every deployment guide already tells operators to mount — so a container that mounted only RELATA_DATA_DIR kept its row data across a restart but silently lost every minted admin token. Now, when RELATA_CONFIG_DIR is unset, the registry defaults to ${RELATA_DATA_DIR}/config/tokens.json whenever RELATA_DATA_DIR is itself set (the common case), falling back to ~/.relata/tokens.json only when NEITHER var is set — that rarer case now also logs a startup tracing::warn! (target relata::admin_auth) so the gap is never silent. Set RELATA_CONFIG_DIR explicitly if you want config/tokens on a genuinely separate volume from RELATA_DATA_DIR.
RELATA_CONFIG—Inline TOML config blob; takes priority over config files.
RELATA_PUBLIC_URL—Externally-visible base URL (used for CORS Allow-Origin and link generation).
RELATA_URLhttp://127.0.0.1:9090Base URL the CLI client uses to reach a running relata serve — covers relata import, relata status, relata query, relata ingest, relata show (#2546 — these three now talk to the live server by default; --offline/--local opts back into the disconnected local sandbox snapshot at ~/.relata/store.json), jobs subcommands, and admin calls. Falls back to http://127.0.0.1:{RELATA_PORT}.
RELATA_A2A_BASE_URL—Explicit base URL advertised in the A2A Agent Card (.well-known/agent.json). Overrides the RELATA_HOST/RELATA_PORT derivation.
RELATA_DRAIN_TIMEOUT_SECS30Graceful-shutdown drain timeout. On SIGTERM/Ctrl-C the server first waits (up to this bound) for the ingest queue to reach empty so every acknowledged row is flushed to the WAL before exit (#310). The outcome is observable: an info log ingest drain complete — N rows persisted on success, or a LOUD error ingest drain INCOMPLETE — acked rows may be unpersisted plus a non-zero exit if the timeout fires with acked rows still queued (fail-closed, so an orchestrator never treats an acked-data-loss shutdown as clean).
RELATA_DEMO_MODE—Set true (or 1/yes/on) to enable demo-mode restrictions (read-only ingest, synthetic data). Case-insensitive. Startup fails on unrecognised values.
RELATA_SHELL_PURPOSEshellDefault purpose for the relata shell interactive REPL (#967 CX-3).

lite was a silent legacy alias for free (ADR-204); it is now rejected outright — startup fails (FATAL) if RELATA_PROFILE=lite is set.


Storage

Relata selects the application object store in priority order: in-memory opt-in → configured cloud/S3 backend → local disk (default). When RELATA_IN_MEMORY=true, the object store is volatile; persistent restart recovery is a separate local authority controlled by RELATA_PERSIST and the data directory.

VariableDefaultDescription
RELATA_IN_MEMORY—Set true (or 1/yes/on) for RAM object storage (dev/CI). With persistence enabled and a writable data directory, a separate local checkpoint/WAL authority supports restart recovery while application objects stay in RAM. Use RELATA_PERSIST=false for fully volatile operation. Case-insensitive; startup fails on unrecognised values.
RELATA_LOCAL_DATA_DIR—Explicit local-disk path for the object store. When unset, falls back to RELATA_DATA_DIR/objects.
AWS_ENDPOINT_URL—S3-compatible endpoint (AWS S3, R2, GCS, self-hosted). When set, S3 takes priority over local disk.
AWS_S3_BUCKETrelataS3 bucket name.
AWS_ACCESS_KEY_ID—S3 access key.
AWS_SECRET_ACCESS_KEY—S3 secret key.
AWS_REGIONus-east-1AWS region (S3 path, KMS).
RELATA_DURABILITYs3Per-backend WAL recovery posture: s3 (strong), r2 (eventual on failure), s3compat, azure.
RELATA_ALLOW_HTTP_OBJECT_STORE—Set true to silence the plaintext-http:// object-store warning (local S3-compatible dev). Credentials/data travel unencrypted (#829).
RELATA_STORE_MAX_INDEX_MB— (adaptive #952)Cap on per-store index RAM in MiB. When unset, derived from detected RAM (index ≈11% of the ~75% pool). 0 = unbounded (#859).
RELATA_EMPTY_WAL_ORPHANED_SNAPSHOTS_ALLOWEDfalse#4831: boot-time sanity check — if wal.jsonl replay recovers zero rows (the sole durability boundary for row data; the object store's flushed Parquet segments are a downstream OLAP export, never read back into the live row store) while data_dir still has ≥1 MiB total of idx_*.snap secondary-index-shard spill files (crates/relata-storage/src/store/index_paging.rs's RAM-cap index paging, #907), that combination is strong evidence of masked data loss (a node coming up status: ready with COUNT 0 across every type/tenant) rather than a genuinely empty store, so relata serve refuses to start (std::process::exit(1)) with a clear message. Set true only for the rare deliberate case — a fresh start against a reused data_dir that still has old index-spill files lying around. See crates/relata-cli/src/serve/wal_replay.rs's empty_wal_orphaned_snapshot_check.
RELATA_TEMPORAL_INDEX_MAX_ENTRIES4000000Cap on Table's per-entity bi-temporal version-chain index (version_index), in entries per object type. Past the cap, the index stops growing and is marked incomplete — AS OF reads fall back to an exact full scan for that type rather than trusting a truncated index (#1868, ADR-0253). #3900 (AC2/AC3) also reuses this SAME value (own separate counters, one budget each) for two process-wide append-only historical secondary indexes in ObjectStore (crates/relata-storage/src/store/secondary_index.rs's HistoricalIndexes) — the door _pk version-GET fast path, and general per-(field, value) candidate generation for AS OF ts WHERE indexed_col = x — rather than adding a third/fourth env var for the same shape of RAM budget. Past either cap, that specific fast path stops firing for the rest of the process (falls back to the same full scan as before this feature existed — never a wrong answer, only slower).
RELATA_TABLE_GC_SHARDS1#3497/ADR-0288 (16th pass — real Table-partitioning live wiring): number of independent Table shards AND group-commit staging lanes per registered type (sharded_table::ShardedTable + TableGroupCommit, crates/relata-storage/src/store/), the SAME number end to end — lane i's drain leader writes directly into shard i's Table. 1 (default) is byte-identical to the pre-#3497 single-Table, single-lane design. N > 1 (capped at 256 — a row's shard membership is pinned into one tag byte of its RowId at first mint) hash-routes each brand-new row to one of N shards; every later operation on that row (update/retract) decodes the SAME pinned tag rather than re-hashing, so an entity's whole version chain always resolves to one shard. N concurrent same-type writers on N distinct shards now hold genuinely independent Table write locks — measured ~1.4–1.6× same-type 8-thread throughput vs. the pre-#3497 ~0.87–0.95× (macOS dev-host relata-bench write-concurrency, not the pinned Linux gate); cross-shard sealed-segment eviction (spill-to-disk) compares a shared per-(branch,type) seal-sequence counter to pick the globally-oldest segment across shards (see sharded_table.rs's module doc, ADR-0288's 15th-pass design D2). #4371: the same N now also partitions this type's per-object_type index locks — the secondary (equality), range and both historical (_pk + general) index maps become N independently-locked partitions routed by the same pinned row tag (store/index_shards.rs::ShardedIndex), so a row's Table shard and its index partition are the same number end to end and a single-object_type firehose no longer serialises on index_secondary's per-row field loop. Every reader unions across partitions, so N == 1 (the default) is byte-identical to the pre-#4371 single lock. Measured on B-157 at N = 8: 8-thread single-type ingest 345,339 -> 1,072,903 rows/s (0.65x -> 2.03x vs the 1-thread baseline); the curve is flat from 4 to 8 threads, so #3888's "near-linear to >=8 cores" is improved but still not met. See RELATA_TABLE_GC_SHARDS_AUTO for a cores-derived alternative to picking N by hand.
RELATA_TABLE_GC_SHARDS_AUTOfalse#3887 (epic #3879): when true AND RELATA_TABLE_GC_SHARDS is unset, every newly-registered type gets min(available_parallelism, 4) shards (table_gc::default_table_gc_shard_count, crates/relata-storage/src/store/table_gc.rs) instead of the historical fixed 1 — mirrors RELATA_FTS_SHARDS's own cores-derived default heuristic (#3410). An explicit RELATA_TABLE_GC_SHARDS=N always wins over this flag. Opt-in rather than a flip of RELATA_TABLE_GC_SHARDS's own bare default: N > 1 is a real (if narrow) behavior change — full-table scan row order is no longer insertion order, and a heterogeneous insert_batch only guarantees no-partial-batch-visibility within one shard, not across the whole batch (see ObjectStore::with_table_write_batch_sealing's doc comment) — so this is left an explicit opt-in for many-core operators until it is validated safe as the bare default via a full cargo test --workspace run.
RELATA_TABLE_GC_SHARD_DRYRUN_LANES0#3497/ADR-0288, observability-only: number of lanes to preview in group_commit_table_insert's (crates/relata-storage/src/store/mod.rs) dry-run shard-routing log. 0 (default) disables the preview entirely — zero cost, zero behavior change. N > 0 makes each group-commit drain batch compute (via table_gc_shard::shard_for_identity) and tracing::debug!-log an N-lane distribution histogram plus a dry-run HLC-stamped ticket (via table_gc_shard::TableGcShardedTicketAuthority), previewing ADR-0288 decision 2's ORIGINAL (superseded) single-global-ticket design — independent of, and does not affect, the real RELATA_TABLE_GC_SHARDS lanes above. Does not route any row into more than one lane — the real leader/follower group-commit protocol, insert order, and locking are unchanged regardless of this knob's value.
RELATA_TABLE_SCAN_PARALLELtrue#3887 round 3 (epic #3879); defaulted on in item 2's cargo-verified pass: when true, cross-shard full-table scans (ObjectStore::scan_all_arc/scan_all_for_tenant_arc) read every RELATA_TABLE_GC_SHARDS/RELATA_TABLE_GC_SHARDS_AUTO shard concurrently on rayon's global pool (ShardedTable::read_concat_parallel, crates/relata-storage/src/store/sharded_table.rs) instead of walking shards sequentially under their own read locks one at a time. Output is byte-identical either way (rayon's collect preserves shard order, matching the sequential concatenation exactly) — this is purely a lock-acquisition/materialization concurrency change, never a row-set or ordering change. Round 6 extended the same flag to the reduce-style ObjectStore::row_count/live_count stats reads (ShardedTable::read_each_parallel), same guarantee (summed result identical either way). Round 7 extended it again to ObjectStore::live_index_complete (crates/relata-storage/src/store/pending_index.rs) — the same read_each_parallel reduce shape, AND-merging each shard's Table::live_index_complete flag instead of summing a count, verdict identical either way. Provably a complete no-op at the default N == 1 shard count regardless of this flag — read_concat_parallel/read_each_parallel short-circuit to the identical sequential single-shard call with zero rayon dispatch whenever shards.len() <= 1 — so this default flip changes nothing for any deployment that has not ALSO opted into RELATA_TABLE_GC_SHARDS/_AUTO. At N > 1 the byte-identical-output guarantee above is pinned by sharded_table.rs's own read_concat_parallel_matches_read_concat_ordering_multi_shard/read_each_parallel_matches_read_each_multi_shard and this crate's table_scan_parallel_flag_does_not_change_scan_results/_row_or_live_counts/_live_index_complete (crates/relata-storage/src/store/scan.rs) — verified via a real cargo test -p relata-storage --all-features run. RELATA_TABLE_SCAN_PARALLEL=false still opts back out.
RELATA_WAL_SYNCintervalProcess-global WAL fsync mode, parsed by the one shared relata_core::validate_wal_sync_value both local-disk WAL consumers read (#3892). always/on/true/1/yes/sync (fsync on every flush boundary, RPO≈0) | interval/default (default — batched fsync every ~10 ms, RPO≈10 ms) | off/batch/os/false/0/no (page-cache only — faster, crash-but-not-power-loss-durable). Matching is case-insensitive and trimmed. Any value outside this vocabulary is a FATAL startup error. For a per-write RPO=0 knob use the X-Relata-Durability: sync request header instead of a deployment-wide switch (#309; see guarantees → durability levels).
RELATA_WAL_STRICT—Set true to escalate mid-stream WAL corruption to a hard startup error instead of dropping the corrupted suffix (#251). When unset, recovery drops the unparseable tail and increments relata_wal_records_dropped_total.
RELATA_START_EMPTY_ON_RESTORE_ALLOWED—#4668: operator opt-in restoring the OLD behaviour when durable-state restore fails at relata serve startup (run_server.rs's remote-restore match arm) — warn and boot an empty store. Dangerous: that empty store's next flush overwrites the unreadable manifest and the sealed-WAL prune deletes the local copy, destroying the data. Default (unset/false): a failed restore FATALs at startup (exit 78, recovery guidance in the message) via restore_safety::fatal_restore_failure (crates/relata-cli/src/serve/restore_safety.rs), because durable data exists but could not be loaded — booting anyway is itself the data-destroying event. A brand-new deployment is unaffected: a genuinely absent manifest is NotFound → empty catalog, which never reaches the error arm. Case-insensitive; startup fails on unrecognised values (strict bool_env, ADR-230).
RELATA_PERSISTtrueEnables persistent mutation journaling. With RELATA_IN_MEMORY=true, recovery uses a separate local checkpoint/WAL authority under the data directory while application objects remain in RAM. Set false with RELATA_IN_MEMORY=true for fully volatile dev/CI operation.
RELATA_COMPACTION_GC_GRACE_SECS—GC grace period after compaction before old segments are deleted.
RELATA_TIER_WARM_AGE_SECS2592000 (30 days)Age threshold (seconds, from a segment's partition_date) past which the background tier-transition scheduler (tier_transition_task, crates/relata-cli/src/serve/maintenance.rs, #3435) moves a hot-tier sealed segment to warm via ObjectStore::move_segment_to_warm_tier_from_snapshot (crates/relata-storage/src/store/tier_transition.rs) — physically copies the segment's Parquet bytes to a distinct tier=warm/ path within the same configured object_store and updates the manifest's key + storage_class together; pre-move bytes are deliberately left in place (orphan-tolerant, same as compaction's own merged-away inputs) until the reclaim pass (fixed 1 h grace) runs. A segment with no partition_date (legacy, pre-#209) is treated as maximally old — always eligible. Tier-transition slice only: no separate physical storage backend (a distinct NVMe/S3 object_store client — see RELATA_TIER_COLD_AGE_SECS for the warm→cold slice, same same-backend design), and no governed TTL/retention-drop path yet (tracked on #3435).
RELATA_TIER_COLD_AGE_SECS7776000 (90 days)Age threshold (seconds, from a segment's partition_date) past which the same tier-transition scheduler (tier_transition_task, #3435) moves a warm-tier sealed segment to cold via ObjectStore::move_segment_to_cold_tier_from_snapshot (crates/relata-storage/src/store/tier_transition.rs) — the warm→cold mirror of RELATA_TIER_WARM_AGE_SECS's hot→warm move: physically copies the segment's Parquet bytes to a distinct tier=cold/ path within the same configured object_store and updates the manifest's key + storage_class together; pre-move (warm-tier) bytes are left in place until the same reclaim pass runs. Defaults to 3x the warm threshold so a segment that just became warm-eligible can't also be cold-eligible on the very next tick. Each scheduler tick runs the hot→warm pass before the warm→cold pass, off eligible lists both computed up front, so a segment never skips through two tiers in one tick.
RELATA_COMPACT_STRATEGYsize-tieredCompaction segment-selection strategy (#1300). size-tiered (default) applies real Cassandra-style size-tiered bucketing (#3906): segments are grouped into buckets whose byte sizes fall within a [0.5x, 1.5x] ratio of the bucket's running average (segments below the 16 MiB SE-03 small-segment cutoff always bucket together, mirroring Cassandra's min_sstable_size escape hatch), and only the most-fragmented bucket is compacted per round — bounding compaction I/O at O(bucket), not O(type). Applied identically to the hot path (ObjectStore::compact_segments_body) and the warm/cold tiered-reclaim path (ObjectStore::compact_tiered_segments_body); see crates/relata-storage/src/store/size_tiered_bucketing.rs. leveled compacts the first level of up to 10 segments. time-window compacts only segments sharing the earliest partition_date bucket.
RELATA_VERIFY_SHALLOW_INTERVAL_SECS3600#5987: interval of the manifest-vs-object existence and size check (one HEAD per live segment). 0 disables. Malformed values fail startup (ADR-230). See Object-store request costs.
RELATA_VERIFY_DEEP_INTERVAL_SECS604800#5986: interval of the deep check that GETs and re-hashes every live segment against its manifest SHA-256. 0 disables. Reads the whole segment set each run.
RELATA_OBJECT_STORE—Object-store URL selecting a native cloud backend ahead of the S3-compatible path: gcs://bucket/prefix or azure://container/prefix (crates/relata-storage/src/remote.rs). When unset, Relata uses the AWS_ENDPOINT_URL S3-compatible path.
RELATA_SPILL_FORMATsstableOn-disk format for cold spill segments (crates/relata-storage/src/sstable.rs). sstable (default) writes LSM-style sorted blocks with a binary-searchable sparse index; json keeps the legacy newline-delimited text format (#1303).
RELATA_WAL_FORMATbinaryWAL payload encoding (crates/relata-storage/src/wal.rs). binary = compact 0xB1-magic layout (default); json = legacy/interop human-readable. Any non-json value selects binary.
RELATA_WAL_IOtokioWAL writer I/O backend (crates/relata-storage/src/async_io.rs). tokio (default) selects TokioAsyncIo/tokio::fs, but this setting is not consulted by the object_store-backed WalWriter::sync_to_segment (crates/relata-storage/src/wal.rs), which always writes via object_store::PutPayload regardless. direct (#3539) IS wired into the local-disk wal.jsonl durability path's two live writers — flush_confirmed_to_wal and wal_write_line/wal_write_lines (crates/relata-cli/src/serve.rs) — via O_DIRECT-aligned writes (async_io::DirectIoFile::open_append + AlignedBuffer) framed with a sector-padded record format (async_io::wal_framing) so variable-length JSONL rows satisfy O_DIRECT's alignment contract; replay transparently strips the framing on read. The resolved backend is process-wide and cached: it degrades to tokio (logged, not FATAL) if O_DIRECT is unsupported on the data_dir's filesystem, or if a non-empty plain-JSONL wal.jsonl from a prior tokio-mode run already exists (start a fresh/empty data_dir to switch to direct). io_uring is a real, live-wired value on Linux builds compiled with the io-uring-wal cargo feature (ADR-0284, #3542/#3677): on that one build target, it routes the fsync/durability boundary of both live local-disk WAL write paths — Store::wal_group_commit_fsync (crates/relata-storage/src/store/mod.rs) and wal_write_line_durable/wal_write_lines/flush_confirmed_to_wal/wal_sync_all (crates/relata-cli/src/serve.rs) — through a dedicated io_uring worker thread instead of File::sync_data; the buffered write(2) step that puts record bytes into the page cache is unaffected, io_uring included. On every OTHER build/config (any non-Linux host, or a Linux build without the feature), io_uring is rejected at startup with a FATAL message. Store::enable_wal/wal_group_commit_fsync (crates/relata-storage/src/store/mod.rs) is a separate, mostly test/bench-exercised local WAL API, not relata serve's live path, for the direct/tokio write step (only its fsync boundary is wired to io_uring, per above). Any genuinely unrecognised value exits the process at startup with a FATAL message; no accepted value is ever silently accepted then either failing at use time or doing nothing.
RELATA_WAL_ARCHIVE_DIR—Directory where rotated WAL segments are archived for point-in-time recovery / disaster recovery (crates/relata-storage/src/backup.rs). When unset, WAL archiving returns NotConfigured and rotated segments are recycled.

Memory and cache

Adaptive defaults (#952, ADR-219). When the budget vars below are unset, Relata derives them from detected hardware at startup — one shared ~75%-of-RAM pool split store ≈34% / index ≈11% / cache ≈11% / vectors ≈19%. The pool is never clamped by a profile. Explicit env vars always win; if the RAM probe fails the legacy flat constants apply. See capacity-planning and crates/relata-cli/src/resource.rs.

VariableDefaultDescription
RELATA_STORE_MAX_RAM_MB— (adaptive #952)Global RAM budget cap across all stores. When unset, derived from detected RAM (store ≈34% of the ~75% pool); the default is the adaptive per-host budget, and the flat legacy 1024 MB applies only when RAM detection fails (#2583). Crossing the cap no longer spills synchronously on the inserting thread (#1821): an insert only flips an in-memory pressure flag, and a supervised background task (serve::maintenance::background_spiller_task, polling every 200 ms) performs the actual disk write + fdatasync off the hot path. Caveat (#787): this caps resident row payloads only — secondary/range/agency indexes keep entries for spilled rows, so index RAM still grows with total row count; bound it separately with RELATA_STORE_MAX_INDEX_MB. Disk-resident indexes are tracked in #3441.
RELATA_SESSION_DRAFT_TTL_HOURS24How long a session write-buffer (draft) is retained before automatic eviction. Set lower in memory-constrained environments. See X-Session-Draft header (#753).
RELATA_VECTOR_RAM_BUDGET_MB64Vector index (DiskANN) RAM budget.
RELATA_GRAPH_RAM_BUDGET_MB64Graph (CSR) in-memory budget. When set, GRAPH_* ops build their adjacency into a disk-paged CSR, streaming edges block-by-block so peak build RAM is O(page budget), not O(edges) (#240).
RELATA_GRAPH_MAX_EDGES16000000Hard bound on resident named-edge link instances (current plus historical) in the in-memory graph (#5958). A write that would cross it (POST /v1/links, POST /v1/links/batch) is refused before anything is journaled with 507 graph-edge-bound-exceeded; nothing is spilled to disk. About 469 bytes resident per edge, so the default is roughly 7 GiB. 0 disables the bound. WAL replay is exempt (already-durable data is never dropped): if a restart finds more edges than the bound it logs a warning and refuses new edge writes until the bound is raised. Parsed strictly (ADR-230).
RELATA_GRAPH_RESIDENT_EDGE_WARN10000000Edge-count at which a resident (whole-RAM) graph build logs a warn! that it may OOM without paging — a nudge to set RELATA_GRAPH_RAM_BUDGET_MB (#240). 0 disables the warning. Since #3537, this is also the threshold a pre-scan edge-count estimate is checked against to auto-route a graph build to the paged leg (see RELATA_GRAPH_AUTO_PAGE_RAM_BUDGET_MB below) before the resident edge batch is materialized — not just a post-hoc warning.
RELATA_GRAPH_AUTO_PAGE_RAM_BUDGET_MB512RAM budget (MB) auto-selected when a pre-materialization edge-count estimate is at/above RELATA_GRAPH_RESIDENT_EDGE_WARN and no explicit RELATA_GRAPH_RAM_BUDGET_MB/process-global default (#990) is already configured — routes the build to the paged CSR leg automatically instead of building the whole graph resident and only warning about it afterward (#3537). Ignored once an explicit/process-global budget is set (that always wins).
RELATA_IDENTITY_RAM_BUDGET_MB64Identity index RAM budget.
RELATA_EXEC_RAM_BUDGET_MB—Query execution working-memory cap. GROUP BY/DISTINCT spill to disk above this budget (spill.rs); ORDER BY spills the same way. Window functions (OVER (...)) cannot spill yet (#3541) — above this budget they instead reject up front with WindowBudgetExceeded (REL_WINDOW_BUDGET) rather than silently materialising the full row set. On by default even when unset (#3899): GROUP BY/DISTINCT default to a 1,000,000-group budget (DEFAULT_BUDGET_GROUPS) and ORDER BY/window functions default to a 1,000,000-row budget (DEFAULT_ORDER_BUDGET_ROWS), both in spill.rs. Set a positive value to size the budget in MB. For ORDER BY/window functions specifically, an explicit 0 is a documented opt-out that disables the check entirely (unbounded) — see the WindowBudgetExceeded row in error-codes.md; GROUP BY/DISTINCT has no such opt-out today (0 and unset both resolve to the default budget).
RELATA_JOIN_STRATEGYautoJoin algorithm selection: hash (always hash join), sort-merge (always sort-merge join O((n+m) log n)), or auto (hash for small datasets, sort-merge when both sides exceed 100 000 rows). (#1290)
RELATA_DISKANN_MAX_RESIDENT— (adaptive #952)Max DiskANN pages to keep resident. When unset, derived from detected RAM (vectors ≈19% of the ~75% pool, ≈3.5 KiB/vector).
RELATA_BG_RAYON_THREADS— (adaptive, cores/2 min 1)Worker-thread count for the dedicated background rayon pool (crates/relata-storage/src/bg_pool.rs, #3416) that HNSW bulk_insert_par and IVF/Paged-ANN train_centroids k-means builds run under, isolated from rayon's global pool so a large background index build can't starve the query executor's parallel GROUP BY/window/rerank/fan-out work sharing that global pool. Parsed strictly (ADR-230) — a non-integer value fails startup.
RELATA_BLOOM_COLUMNStenant_id,object_typeComma-separated column names for which per-column Bloom filters are built at segment flush time (ADR-212, #427). Set to none to disable. Columns missing from a segment fail open (the segment is never falsely pruned). Both the segment-key bloom and per-column blooms are consulted live on the scan path (equality predicates prune disk segments pre-decode, #962 — executor.rs bloom hint → scan_as_of_arc_with_bloom in scan.rs).
RELATA_SKETCH_COLUMNStenant_id,object_type,statusComma-separated column names for which HyperLogLog (NDV) and Count-Min Sketch (value frequency) are maintained in-memory and updated on every row insert (ADR-213, #428). Used by the cost-based optimizer to replace hardcoded 0.20 selectivity constants with data-driven per-value estimates. Set to none to disable; cold-start or disabled columns fall back to the NDV-sample heuristic. Memory: ~96 KB per tracked column per type.
RELATA_VECTOR_QUANTfullVector quantization tier for HNSW node embeddings (#1333). Every node is already stored int8-quantized (~4× reduction vs. raw f32, #500) regardless of this setting. full = that int8-quantized baseline, no additional compression; binary = 1-bit per dimension packed into u64 words on top of the baseline, ~32× total reduction, used as a hamming pre-filter before exact distance re-ranking. fp16 is not an accepted value (startup fails on it, #3093) — no FP16 codec is wired into the HNSW storage/search path.
RELATA_VECTOR_COLD_RESIDENT_MAX100000Soft cap on RAM-resident vectors in an IVF cold bucket's staging area before the batch spills to the object-store-backed PagedAnnIndex (#906). Only pages when an object store is configured.
RELATA_MAX_VECTOR_K1000Hard cap on a vector query's requested k (ADR-189). 0 disables the cap.
RELATA_DECODED_SEGMENT_CACHE_MAX_BYTES536870912 (512 MiB)Byte budget for the decoded disk-segment cache, keyed on each segment's on-disk plaintext size (#3906). Primary eviction trigger — a handful of multi-hundred-MB segments and a thousand tiny ones previously counted identically toward a bare entry count (a fixed 64-entry secondary bound still applies). A single segment whose own bytes exceed the budget is still cached (the budget targets the aggregate working set, not a hard per-entry cap). ADR-0297 (#4468): when a row-store RAM budget is configured (RELATA_STORE_MAX_RAM_MB / set_disk_overflow), this value is clamped down to that budget by default — an operator who bounds the store's RAM footprint expects that number to be the total footprint, not just resident rows. Set this var explicitly to opt back into an independent decode-cache budget; an explicit value here always wins over the derived clamp, even one larger than the row-store's own budget.
RELATA_PARQUET_MAX_DECOMPRESSED_MB4096Hard cap on the decompressed size of a single Parquet segment in MiB (#583). Segments that expand beyond this limit are rejected at load time to prevent decompression-bomb OOM.
RELATA_ENRICH_MODEeagerIdentity enrichment mode (ADR-205, #363). lazy enqueues enrichment for background processing via EnrichmentQueue (lower write latency, slight graph-visibility delay). eager enriches inline before the write acks (default, preserves graph consistency). Startup fails on any other value.
RELATA_LAZY_TYPES—Per-type lazy-enrichment override (#2259, SI-4). Comma-separated list of object-type names (e.g. LogEvent,MetricSample) that are enriched lazily via EnrichmentQueue regardless of the global RELATA_ENRICH_MODE. Types not listed fall back to the global RELATA_ENRICH_MODE decision. This list only ever adds lazy behavior on top of the global default — it cannot force a listed type back to eager when RELATA_ENRICH_MODE=lazy is already set globally. See "Tuning detection latency" for the eager/lazy tradeoff and the non-durable caveat.
RELATA_MIN_FREE_DISK_MB256Minimum free disk space in MiB before Relata sheds inbound writes to protect the WAL and spill segments. 0 disables the guard entirely.
RELATA_HTTP_MAX_CONNS4096Maximum concurrent TCP connections accepted by the shared HTTP/TLS listener. Distinct from RELATA_HTTP_MAX_INFLIGHT_REQUESTS (request concurrency; one HTTP/2 connection can carry multiple requests) and per-route rate limiting (RELATA_RATE_LIMIT_RPS).
RELATA_HTTP_MAX_INFLIGHT_REQUESTS4096Maximum concurrent in-flight HTTP requests admitted by tower::limit::ConcurrencyLimitLayer, applied to the router before either the TLS or non-TLS accept loop serves connections (#3913). Requests over the limit back-pressure at the router. Before #3913 this was conflated with RELATA_HTTP_MAX_CONNS under one name with two different meanings (connection count on TLS, request concurrency on non-TLS) — they are now independently tunable, with the same default so an unconfigured deployment's effective behavior is unchanged.
RELATA_RESULT_CACHE_ENABLEDtrueEnable the 16-shard query result cache (ADR-209, #418). Set to false to disable globally (all queries hit the executor).
RELATA_RESULT_CACHE_TTL_SECS300Default TTL for cached result sets in seconds. 0 means entries never expire (relying on type-tagged invalidation only). Per-query TTL override (WITH CACHE TTL <duration>) is not yet implemented — tracked as #901.
RELATA_RESULT_CACHE_MAX_BYTES134217728Starting total byte budget across all 16 shards (default 128 MiB), shared across every tenant — there is no per-tenant partition (#5300). #2006: this is now the initial value only — the tick() feedback loop (wired into the 60 s background task) adjusts it ±5% toward a fixed 0.85 hit ratio at runtime, bounded by a RAM-derived ceiling (cgroup-aware, see that var's row). Multi-tenant sizing (#5300): the cache key includes caller_org, so the distinct-key space scales linearly with tenant count and eventually exceeds any fixed byte budget — measured with a realistic ~5 KiB average result-row payload and a 20-query-per-tenant working set (crates/relata-query/src/result_cache.rs's result_cache_hit_ratio_collapses_under_tenant_fanout test), hit ratio against the unmodified 128 MiB default was 100.0% at 1/10/100 tenants, 87.3% at 1,000 tenants, and 13.3% at 10,000 tenants. The budget needs to scale roughly with tenant_count × working_set_size × avg_result_bytes to hold a given hit ratio — e.g. ~1 GiB to keep 10,000 tenants at the same working set back near 100%. Set this explicitly for large multi-tenant deployments rather than relying on the adaptive tick() loop alone; one tenant is capped at a quarter of whatever budget you pick, so a noisy tenant cannot take it all.
RELATA_VECTOR_RESULT_CACHE_ENABLEDtrue#2005: enable the vector KNN query-result cache (KnnResultCache, crates/relata-storage/src/vector_cache.rs) — memoises (query_vector, k, filter_hash, tenant_id, model_tag) -> top-k ids/scores below the full-SQL result cache, so a repeated embedding skips the hot TurboVec scan and any cold-tier IVF paging. Set to false to disable globally.

Usage example (#2005): The KNN result-cache budget is fixed at 64 MiB and its TTL at 60 s; RELATA_VECTOR_RESULT_CACHE_ENABLED=false cargo run -p relata-cli -- serve disables the cache entirely (every KNN/HYBRID_SEARCH vector sub-query re-runs the hot scan + cold-tier paging in full).

| RELATA_CACHE_DISK_PATH | — | Directory path for the optional disk-tier segment cache (foyer HybridCache). When unset, the cache is RAM-only (RowGroupCache). Set together with RELATA_CACHE_DISK_GB to enable the disk tier (#691). Caches plaintext bytes regardless of RELATA_ENCRYPTION_AT_REST (#2688): the cached bytes are the same flushed Parquet segment bytes that are never encrypted at the object-store source (see that variable's row above), so enabling this disk tier additionally spills that plaintext onto local disk at this path — anyone with filesystem access to it can read cached row data unencrypted. File-permission posture (#4839): this directory is created owner-only (0700), and the region files foyer creates under it are tightened to owner-only (0600) right after creation — narrowing exposure from "any local user/process on the host" to "only the service account (or root)" on a shared or multi-tenant host. This is defense-in-depth, not a substitute for the plaintext caveat above: it does not encrypt the cached bytes, and the file-tightening pass is best-effort (foyer's DirectFsDeviceOptions has no file-mode option, so each region file briefly exists under the ambient umask between foyer creating it and this pass running); on non-Unix targets these permission bits don't apply and only the directory is created. | | RELATA_CACHE_DISK_GB | — | Maximum disk space (GiB) reserved for the disk-tier segment cache. Ignored when RELATA_CACHE_DISK_PATH is unset. Integer; 0 or unset disables the disk tier (#691). |

| RELATA_QUERY_ARENA | true | When true (default), the in-memory sort path arena-allocates its keyed buffer via bumpalo — one bump allocation for the whole intermediate result set instead of repeated malloc/free per row (ADR-211, #905). Set to false to fall back to standard heap allocation (useful for memory-profiling or if a bumpalo bug is suspected). |

Explicit result-cache warming

The automatic query predictor and query-pattern recorder were removed in v3.0. Ordinary SQL requests do not retain query history or schedule predicted queries. Authenticated callers can still explicitly submit a bounded cache-warm request through POST /admin/warm-cache; the worker processes one request at a time with a queue capacity of 64. The retired RELATA_PATTERN_*, RELATA_PREDICT_*, and RELATA_SPECULATE_* variables are no longer read.

Retired semantic RAG row-cache settings

RELATA_SEMANTIC_CACHE_ENABLED, RELATA_SEMANTIC_CACHE_THRESHOLD, and RELATA_SEMANTIC_CACHE_MAX_ENTRIES are obsolete in v3.0 and rejected at startup; remove them from deployment configuration. Similarity-based reuse of prior RAG rows was retired under #5738. Semantically similar but non-identical /v1/rag/query calls follow governed retrieval again; an identical validated query may still use exact query-result caching. Dense/hybrid misses still use query embeddings. Vector-result, block, and embedding caches are separate mechanisms and remain. The retired RAG cache held only process-local results, so there is no persisted cache data to migrate.


Graph index and algorithms

VariableDefaultDescription
RELATA_GRAPH_CACHE_BYTES268435456 (256 MiB)Total byte budget for the 16-shard PagedGraphCache (CSR adjacency cache, crates/relata-query/src/graph_cache.rs), used by the investigation-ops persistent paged-graph cache (crates/relata-query/src/investigation_ops.rs). Higher values keep more (object_type × tenant × orientation) adjacency graphs RAM-resident.
RELATA_GRAPH_PREWARMtrueWhether to speculatively build + cache the CSR graph after bulk ingest (crates/relata-cli/src/serve/ingest.rs). Parsed strictly (ADR-230) — a value that is not one of true/1/yes/on or false/0/no/off fails startup; unset leaves the prewarm enabled (#2935).
RELATA_GRAPH_EXACT_ALGO_MAX_NODES20000Node-count ceiling for the exact O(V²)-memory / O(V·(V+E))-time graph operators (GRAPH_DIAMETER, GRAPH_APSP) on the resident leg (#3043). A graph past this cap is rejected up front with REL_GRAPH_TOO_LARGE rather than silently materialising a V×V distance matrix or running a BFS from every node (an OOM/CPU-exhaustion vector on the default free profile). 0 disables the cap. The default GRAPH_CENTRALITY betweenness arm additionally auto-routes through betweenness_centrality_approx (above a fixed 10,000-node threshold (``) so it never runs the unbounded exact algorithm unconditionally.
RELATA_GRAPH_UNPAGED_COMMUNITY_MAX_EDGESRELATA_GRAPH_RESIDENT_EDGE_WARN's value (10000000)Edge-count cap for the two GRAPH_COMMUNITY algorithm variants with no paged/incrementally-contracting leg — ALGO => 'leiden' and ALGO => 'louvain', LEVELS => N (N > 1) (#3606, narrowed from #3534/#3438). Single-level Louvain (LEVELS <= 1, the default) already routes through the paged GraphView::louvain leg (#3534) and is unaffected by this cap. A pre-scan edge-count estimate past this cap is rejected up front with REL_GRAPH_COMMUNITY_UNPAGED rather than silently building the whole graph resident (an OOM vector). 0 disables the cap.
RELATA_GRAPH_MAX_K_SHORTEST50Hard cap on GRAPH_K_SHORTEST(..., K => n)'s K (crates/relata-query/src/parser.rs::max_k_shortest_limit). Yen's algorithm is O(k·V·(E log V)) (relata_graph::paths_advanced::yens_k_shortest), so an unbounded K let a caller pin a worker thread indefinitely with no special privileges; a request above the cap is rejected at parse time with a QueryError rather than running (#2954). The native PATHS_BETWEEN(...) MAX_HOPS keyword syntax, the paths_between(...) TVF, and Cypher quantified path patterns [*min..max] share a companion, non-overridable MAX_HOPS_LIMIT = 20 ceiling (same ticket) — that one isn't env-configurable since it's small enough not to need a deployment-time knob.

Vector index tuning

VariableDefaultDescription

Query parse cache and optimizer

VariableDefaultDescription

HTTP listener and retired client protocols

HTTP, GraphQL, and MCP share RELATA_PORT (default 9090); RELATA_HTTP_BIND controls the listener address. Client gRPC, PostgreSQL wire, the public S3 listener, Neo4j HTTP, Bolt, and Arrow Flight listeners are retired. Their old settings are rejected at startup when present, including false flags, and relata config --migrate comments them out. See the protocol migration guide for the complete retired-variable list and migration paths. Object-store settings remain for managed blobs and backups.

Door and serve scale ceilings (#5304)

These bound how much one door will hold resident (open cursors, prepared statements, materialized rows, buffered draft sessions). Each used to be a bare hard-coded constant with no override and no relationship to the hardware; each is now either resource-derived or explicitly fixed for a stated reason, and all are operator-overridable.

How the derived defaults work. The "Default" column below is the baseline — the value the ceiling has always had. A resource-derived ceiling multiplies that baseline by detected_RAM / 8 GiB, clamped to 1×…8×, where the detected RAM is the cgroup-aware figure from crates/relata-cli/src/resource.rs (#5265 — a container's memory.max, not the host's total). The multiplier floor of 1× is deliberate: a host at or below 8 GiB — and therefore every deployment sized against today's constants — sees exactly the number it saw before, and only a demonstrably larger box is allowed more. The 8× ceiling keeps the bound a bound.

Setting any of these explicitly overrides the derivation entirely. 0 is not "unlimited" — it clamps to 1. Exceeding a ceiling always produces backpressure or a typed error (429 / RESOURCE_EXHAUSTED / 400 / eviction of the caller's own oldest entry), never unbounded growth.

VariableDefault (baseline)Derived?Description
RELATA_SEARCH_MAX_BATCH_QUERIES16No — fairness boundMax subqueries in one /v1/search queries batch (#1986 T4). Deliberately not RAM-derived: it bounds how far one request may amplify itself against every other in-flight request (tail latency / fairness), not memory — the subqueries dispatch sequentially. An over-cap batch is rejected with 400.

Example — pin a small edge node's ceilings well below what its RAM would otherwise allow, and let a large analytics node keep the derived defaults:

# Edge node (2 GiB container): shrink the two biggest materializers.
  relata serve
 
# Confirm the HTTP API is serving the governed query surface:
relata query "SELECT * FROM Person LIMIT 1"

Not overridable, by design: the /v1/search batch response's row limit (BATCH_MAX_LIMIT, 10 000) mirrors relata_query::json_query::MAX_LIMIT and a door-local knob would let the two drift, admitting a batch at a limit the single-subquery path still rejects.


TLS / mTLS

VariableDefaultDescription
RELATA_TLS_CERT—Path to the TLS certificate (PEM) for in-process HTTP TLS termination. When set with RELATA_TLS_KEY, the HTTP listener binds with rustls TLS. (#2073) Required on every profile — including free — unless RELATA_PLAINTEXT_OK resolves true (see that row for the loopback default).
RELATA_TLS_KEY—Path to the TLS private key matching RELATA_TLS_CERT.
RELATA_TLS_HANDSHAKE_TIMEOUT_SECS10Seconds a TLS client gets to complete the rustls handshake on the HTTP listener before the connection is dropped and its connection permit released (#3137). Guards against slowloris-style partial-ClientHello stalls exhausting the RELATA_HTTP_MAX_CONNS accept-time semaphore. 0 falls back to the default.
RELATA_HTTP_TIMEOUT_SECS30Per-request timeout on the governed HTTP data-plane and admin listeners. A timed-out handler returns 408 Request Timeout; this is separate from the query execution deadline (RELATA_QUERY_TIMEOUT_SECS) and the SDK-side timeout= constructor argument.
RELATA_SLOW_QUERY_MS500Query wall-clock threshold (ms) above which a query is recorded in the slow_queries ring surfaced on the metrics dashboard (#1043).
RELATA_PARQUET_COMPRESSIONzstdParquet segment compression codec. Accepted: zstd (default, level 3), zstd:<level> (level 1-22), lz4, snappy, none. ZSTD level 3 gives 2-4× size reduction vs Snappy at similar decode throughput (#1302).
RELATA_MANIFEST_V2_WRITEtrueOn by default since #3905 round 2 (previously opt-in, default false). Each flush writes a ManifestIndexV2 sharded catalog (manifests/<branch>/manifest/index.json + per-epoch <epoch>.ndjson shards) alongside the existing v1 manifest.ndjson/manifest-catalog.ndjson files (#3492). Set to false to opt back out (e.g. while validating a backend without conditional-PUT support). Additive and fall-back-safe: the v1 files remain authoritative regardless of this flag, and turning it back off never strands a deployment without a readable manifest. The read side (ObjectStore::read_manifest_v2_sharded, #3433/#3472) already prefers a v2 index when present, so this is what actually populates it. An existing v1-only deployment's first post-upgrade flush automatically migrates its full pre-existing catalog into the first v2 shard (not just that flush's new segments) so no pre-existing segment goes missing behind the new default — see ObjectStore::write_manifest_v2_sharded's doc comment. #3533: once the v2 index's total entry count crosses a bounded-eager-load threshold, node startup fetches only the most-recent shards up front and defers the rest to first data-serving touch (ObjectStore::ensure_full_v2_catalog_loaded) — the catalog-load side of AC1 in #3433 ("startup must not load every segment entry into RAM"), with no separate env var to configure.
RELATA_MANIFEST_V2_REQUIRE_CHAINfalse#4332 / ADR-0290 P2. When true, a v2 manifest index (manifests/<branch>/manifest/index.json) that carries no shard-chain head is rejected instead of accepted with a warning. Every v2 index writer seals a GENESIS_HASH-rooted hash-chain head over the whole shard list before its conditional PUT, and the read path (ObjectStore::read_manifest_v2_sharded) hard-fails a head that does not match — that is what restores SPECS §4 non-negotiable #13's tamper evidence on the artefact the read path actually consults (the v1 manifest.ndjson chain has not been on that path since ADR-0290 Phases 2/3). An index written by a pre-#4332 build has no head and is accepted by default, because it is sealed in place by the very next v2 index write — normally one flush — whereas rejecting it by default would push every already-deployed branch onto the v1 fallback, which since ADR-0290 Phase 4 may lag by up to 63 flushes (the resync interval is fixed at 64). Turn this on once the fleet is fully upgraded (confirm the storage crate's MANIFEST_V2_UNCHAINED_INDEX_READS_TOTAL has stopped growing); it closes the residual "strip the head to make the index look pre-#4332" downgrade path. Violations are counted by MANIFEST_V2_CHAIN_VIOLATIONS_TOTAL — any non-zero value is an incident, not a trend.
RELATA_SEAL_MAX_BYTES67108864 (64 MiB)#3500: byte-size threshold for SealPolicy — a (branch, type)'s unflushed tail (estimated in-RAM row-value bytes) at or above this is due for a policy-driven seal via ObjectStore::flush_to_remote_policy, independent of RAM-pressure spill. 0 disables the size trigger.
RELATA_SEAL_MAX_AGE_SECS300#3500: age threshold (seconds, measured from the oldest unflushed row's system_from) for SealPolicy — a tail that has sat unflushed this long is seal-due regardless of size/row-count. 0 disables the age trigger.
RELATA_SEAL_MAX_ROWS100000#3500: row-count threshold for SealPolicy — a tail with this many or more unflushed rows is seal-due. 0 disables the row-count trigger.
RELATA_LAZY_RESTARTfalseWhen true, startup loads the manifest catalog only (O(manifest), not O(rows)) instead of eager row restoration. Faster cold starts; older segments hydrate on demand (#1265).
RELATA_HYDRATE_RECENT_SEGMENTS0With lazy restart on, hydrate only the newest N segments into RAM at startup. 0 = fully lazy (all segments hydrate on demand). Set to a small number (e.g. 3) to keep recent data hot (#1265).
RELATA_ROW_GROUP_PRUNED_HYDRATEfalse#3694 (#3432 follow-on): when true, the cold-restart on-demand hydration path (ObjectStore::hydrate_type_for_query) fetches only the Parquet row groups a Point/Range query predicate's own zone-map stats cannot rule out (#3484), instead of always decoding an admitted segment's whole file. Opt-in, default off, because a row-group-pruned fetch cannot verify a segment's whole-file sha256 the way every other hydrate path does — a segment whose row-group selection turns out to cover every row group (no pruning benefit) always falls back automatically to the sha256-verified whole-segment path, so the tamper-evidence gap is paid only when this flag is set and pruning genuinely reduces fetched bytes. See ADR-104's 2026-08-06 addendum.
RELATA_EPHEMERAL_ROW_GROUP_SCANfalse#3733 (#3721/#3432 follow-on): refines RELATA_ROW_GROUP_PRUNED_HYDRATE (checked only when that is also true) — a Point/Range cold-restart hydration whose row-group selection hits an already RAM-cache-resident segment (RowGroupCache) decodes those row groups ephemerally for this query call only (ObjectStore::ephemeral_decode_row_groups), instead of permanently inserting them into the hot table via ingest_segment_rows. Bounds resident row count across repeated queries against the same cache-resident segment (re-decodes each time — a bounded CPU cost — rather than growing RAM without bound). A cache miss falls back unchanged to the existing permanent-ingest fetch. Opt-in, default off — unset behavior (including RELATA_ROW_GROUP_PRUNED_HYDRATE alone) is byte-for-byte unchanged. See ADR-104's 2026-08-06 addendum. #3432 correctness gate: the decoded ephemeral rows are only ever consulted by the columnar aggregate fast-path (scan_as_of_column_batch's ephemeral leg); serve/query.rs only takes the ephemeral branch when relata_query::executor::dispatch::query_shape_uses_columnar_aggregate_fast_path reports the query's shape (aggregate, no JOIN/window/WITH PROVENANCE) will actually reach that fast-path — any other query shape still gets a permanent hydrate, so cold rows are never silently invisible.
RELATA_MAX_AGENCY_INDEX_BUCKET_ENTRIES0 (unbounded)Per-bucket cap on live-RowId entries in a single (type, agency) agency-index bucket (#3495). Smallest-live-set-first eviction (above) never touches the single largest bucket, so an always-growing tenant's bucket was otherwise unbounded even as its row payloads spilled to disk. When set >0, any bucket exceeding this size is evicted outright at the next prune cycle, independent of the bucket-count budget; reads stay correct via the same field-filtered fallback.
RELATA_EMBED_TIMEOUT_MS30000Query-time embedding sidecar HTTP call timeout in ms (#1101). On timeout the call fails fast.
RELATA_SEARCH_PRESETbalancedSearch relevance preset: strict (exact-match preferred, no typo tolerance — governed/production), balanced (light typo tolerance, prefix on short tokens — general-purpose), or lenient (edit-distance 2, fuzzy on — demo/evaluation). See Search presets guide (#1257).
RELATA_SEARCH_LAST_TERM_PREFIXtrueWhen true, the /v1/search handler treats the last whitespace-delimited token as a prefix and unions BM25 results with prefix_search hits — enabling search-as-you-type without explicit wildcard syntax (#1261). Set to false to disable. Can also be overridden per-request via the lastTermIsPrefix body field.
RELATA_SEARCH_LANGenISO 639-1 language code for the built-in stemmer (#669). 15 hand-rolled stemmers ship (en, fr, de, es/pt (shared stem_es), it, nl (Dutch), sv (Swedish), no (Norwegian), da (Danish), fi (Finnish), hu (Hungarian), ro (Romanian), ru (Russian Cyrillic), tr (Turkish), ar (Arabic)) — see crates/relata-storage/src/search.rs:3266-3822. Unknown codes fall back to English. none (aliases off, simple) disables stemming: tokens are lowercased and split but indexed as written, for corpora where inflection folding costs precision (#5944). CJK text (Han/Kana/Hangul) is always bigram-segmented regardless of this setting; Thai/Lao/Myanmar/Khmer and the Indic/Brahmic scripts (Devanagari, Bengali, Tamil, …) are always segmented with the real UAX #29 word-boundary algorithm (unicode_words(), via the unicode-segmentation crate) instead of the ad-hoc !is_alphanumeric() splitter, regardless of this setting too — none of the 15 stemmers above target those scripts, so this is a word-boundary fix, not a new stemmer (#4958). Read once at startup — restart required for changes to take effect.
RELATA_STOP_WORDS_LANGenStop-word language: en for built-in English list, none to disable (ADR-214 D2, #663).
RELATA_STOP_WORDS_FILE—Path to a custom stop-word file (one word per line). Overrides the built-in list when set (ADR-214 D2, #663).
RELATA_SYNONYMS_FILE—Path to a JSON synonym file for query-time expansion, e.g. {"phone": ["telephone", "mobile"]} (ADR-214 D3, #664).
RELATA_FACETS_<Type>—Comma-separated list of facetable attributes per type, e.g. RELATA_FACETS_Product=category,brand (ADR-214 D4, #665).
RELATA_RANKING_<Type>—Per-type custom ranking rules, e.g. RELATA_RANKING_Article=recency:published_at:86400,popularity:weight:0.3 (ADR-214 D5, #666).
RELATA_MTLS_CA_CERT_PATH—CA certificate (PEM) used to verify client certs. Required for RELATA_AUTH_MODE=mtls.
RELATA_MTLS_REQUIRE_CLIENT_CERT—Require client certificate on TLS handshake.
RELATA_MTLS_ALLOWED_DNS_SANS—Comma-separated list of allowed DNS SANs in client certs.

Rate limiting

VariableDefaultDescription
RELATA_RATE_LIMIT_RPS10000Request rate (requests/sec), keyed per authenticated principal or client IP. Applies to the shared HTTP API, including HTTP/JSON, GraphQL, and MCP requests; throttled requests receive HTTP 429.
RELATA_RATE_LIMIT_BURST10000Burst capacity above RELATA_RATE_LIMIT_RPS. Matches the RPS default.
RELATA_ACL_GRANT—Comma-separated ACL grants for partner types, e.g. CustomClaim:read+write. Applies to public HTTP/JSON, GraphQL, and MCP principals; http-client also gets type-ownership registration (#111). Bare type names default to read. Accepted permissions: read, write, and override; override is deny-by-default unless explicitly granted.
RELATA_ACL_GRANT_<DOOR>—Optional narrowing of global ACL grants by caller role. Supported public API roles are HTTP and MCP. See the authorization guide for the role and permission model.
RELATA_ACL_PROFILEunset on fresh foundation installsSelects legacy-v2 to restore the versioned v2 compatibility read grants, or custom to intentionally use foundation defaults plus explicit ACL env grants. Installing the legacy-v2 schema package requires one of these explicit choices. Package type presence never implies permissions. This changes explicit system/analyst/break-glass defaults; protocol-door wildcard read remains governed by tenant/cell/classification checks.
RELATA_DISKANN_DISK_RESIDENT—When true, writes a .rgph sidecar for disk-resident ANN beam-search (ADR-077/185). Requires a backing object store. As of #2562, the sidecar is built by the real Vamana graph algorithm (vamana_build, #1331) rather than derived from the in-RAM HNSW graph. The build parameters (alpha 1.2, max degree 32, L 100) are fixed. Each flush also round-trips one vector through beam_search_disk_resident as a warn-only self-check that the sidecar it just wrote is queryable. As of ADR-282/#3271, the same flag also writes the .sgph/.svec/.pqcb/.ids true-disk beam-search segments (sector-demand-paged PQ/ADC graph + sector-aligned full vectors + trained PQ codebook + node-index→row-id map) that DiskAnnIndex::beam_search_true_disk reads — its sector cache (256 MB), per-query IO budget (512 sectors, fail-open) and rerank factor (6) are fixed. This is still an opt-in, disk-resident path — the default RAM-resident HNSW search every query reaches by default is unaffected either way. The .rgph/beam_search_disk_resident path is still not wired into live query dispatch (ADR-185, tracked by #2670). The .sgph/.svec/.pqcb/.ids true-disk path IS now wired into live dispatch as of #3414 step 2: ObjectStore::merge_cold_tier (reached from vector_search_for_tenant/vector_search_with_metric_for_tenant) folds in beam_search_true_disk hits when this flag is true and the bucket has a disk-resident segment — still not covering the ACL-filtered HYBRID_SEARCH path (vector_search_filtered_for_tenant) or relata-query's EXPLAIN ANALYZE IO-stat surfacing, both tracked on #3414. As of #3898 round 4, the .ids sidecar is what lets load_and_search resolve node index → row id without downloading the (embedding-sized) .bin segment on every query; a segment flushed before round 4 has no .ids file and falls back to the legacy full-.bin scan.
RELATA_COLD_TIER_FAILopenDiskANN cold-tier page-in failure mode (crates/relata-storage/src/paged_ann.rs). open (default): a failed cold-tier read returns an empty result (observability-only — the query succeeds with fewer candidates). closed: a failed cold-tier read fails the query. Set to closed only when you need hard failure semantics on cold-tier I/O errors.
RELATA_COLD_ANNrebuildCold-tier IVF absorb strategy (#1989, T7 — crates/relata-storage/src/paged_ann.rs / ivf_builder.rs). rebuild (default): the legacy ColdIvfBucket behaviour — a full k-means rebuild of the resident overflow once it doubles. incremental: routes inserts into a centroid-incremental tier (IncrementalCentroidIndex) that appends to the nearest centroid's posting list and periodically re-centres only the centroids that changed, never rerunning k-means over the whole corpus.
RELATA_VECTOR_COLD_PQfalse(#3897, PQ re-rank wiring) When true, ColdIvfBucket::ensure_index's internal candidate-generation IVF (crates/relata-storage/src/ivf_builder.rs) is built with IvfBuilder::pq(DEFAULT_PQ_M) (Product Quantization) instead of the default Quantization::Int8. IvfBuilder::pq still gates itself on the held-out PQ_RECALL_GATE and falls back to Int8 if a trained codebook underperforms, so this never trades away recall — only the resident posting-list code size when PQ activates. Off by default: PQ codebook training is materially more CPU per rebuild than Int8's per-vector quantization, and that rebuild already runs under a write lock (#893); flipping the default needs a rebuild-cadence benchmark. Does not shrink ColdIvfBucket's resident raw-f32 staging kept for the exact cosine rerank — see the module's doc comments for the larger PQ-resident/object-store-rerank redesign this does not attempt.
RELATA_VECTOR_COLD_PQ_APPROX_RERANKfalse(#3975 round 7) When true and the internal candidate IVF actually quantized as Quantization::PQ (only happens when RELATA_VECTOR_COLD_PQ=true also cleared PQ_RECALL_GATE at build time — otherwise the index stays Int8 and this flag is a no-op), ColdIvfBucket::search (crates/relata-storage/src/ivf_builder.rs) skips fetching the exact-f32 rerank copy from raw and instead scores candidates via Asymmetric Distance Computation against the coarse quantizer's own already-resident PQ codes (IvfIndex::search_scored). Off by default: exact-cosine rerank is unchanged for every existing deployment. This is a query-time CPU-efficiency opt-in only — it does not shrink raw's resident RAM footprint (still required by spill_if_over_budget's centroid training/drain and the ADR-186 snapshot), so it is not itself a step toward the ticket's <=1/8-of-f32 resident-bytes-per-vector target; that redesign remains open follow-on scope.
RELATA_VECTOR_COLD_PQ_SEED_FROM_HOTfalse(#3975 round 12, Phase 1 of the hot-tier-seeded codebook bootstrap design) When true, the very first cold-tier overflow for a key (store/vectors.rs's route_embedding_to_tier/new_cold_bucket) trains a bootstrap PqCodebook from the sibling hot-tier TurboVecIndex bucket's own resident vectors and stores it on ColdIvfBucket::seed_codebook, via ColdIvfBucket::seed_codebook_from_hot (crates/relata-storage/src/ivf_builder.rs) — only if the trained codebook clears PQ_RECALL_GATE against its own seed sample. Off by default, and has zero effect on raw, add, or spill_if_over_budget whether true or false. As of round 15, ColdIvfBucket::build_index_if_needed is this field's one consumer — see RELATA_VECTOR_COLD_PQ_SEED_CONSUME below for the separate opt-in that gates that consumption.
RELATA_VECTOR_COLD_PQ_SEED_CONSUMEfalse(#3975 round 15, Phase 2 of the hot-tier-seeded codebook bootstrap design) When true (and RELATA_VECTOR_COLD_PQ=true), ColdIvfBucket::build_index_if_needed (crates/relata-storage/src/ivf_builder.rs) substitutes a bucket's stored seed_codebook (populated by RELATA_VECTOR_COLD_PQ_SEED_FROM_HOT, above) for a freshly trained PqCodebook, skipping train_pq's repeated per-rebuild k-means cost on the common-case success path. The seed is re-validated against the current raw resident sample via the existing PQ_RECALL_GATE gate at substitution time (not just the hot-tier sample it was originally trained against), so a seed that has drifted from the cold tier's own accruing distribution always falls back to today's unconditional train_pq path instead of degrading recall. Deliberately a separate flag from RELATA_VECTOR_COLD_PQ_SEED_FROM_HOT rather than overloading it to also mean "and consume it," so every existing seed-population test's "zero consumers" contract stays intact independent of this one. Off by default: zero behavior change for existing deployments merely from a seed existing on a bucket.
RELATA_VECTOR_COLD_RAW_COMPACTfalse(#3975 round 20, ADR-0292 Phase 2 — the resident-staging compaction itself) When true (and RELATA_VECTOR_COLD_PQ=true), a cold-tier rebuild replaces the exact f32 of every already-indexed resident slot (ColdIvfBucket::raw[..built_len], crates/relata-storage/src/ivf_builder.rs) with the m-byte PQ code the coarse quantizer just computed for that same position — no fresh encoding — so the RAM-resident staging costs m bytes/vector instead of dim * 4. This is the flag behind #3975's "cold-tier resident bytes/vector <= ~1/8 of f32" target; measure the result with ColdIvfBucket::resident_payload_bytes(). Necessary but not sufficient: compaction additionally requires that bucket's own pq_resident_compaction_conforms() to be Some(true) — the two-clause acceptance predicate (bytes <= 1/8 of f32 and measured ADC recall@10 >= PQ_RESIDENT_RECALL_GATE = 0.98, deliberately 2.5x tighter than the PQ_RECALL_GATE = 0.95 candidate-generation fallback trigger). A bucket whose data does not quantize well enough simply does not compact: it keeps today's exact rerank and today's memory, so nothing can regress for it even with this flag on. Compacted slots are reranked against their PQ reconstruction rather than exact f32, are decoded on the way into the spill/paged tier and the ADR-186 shutdown snapshot (whose on-disk shape is unchanged — no VectorSnapshot::VERSION bump), and are re-materialized to exact f32 by a re-add. A slot is quantized at most once: if a later rebuild trains a different codebook, compaction freezes for that bucket rather than stacking a second quantization (ADR-0292 Blocker B). Off by default; the recall measurement it gates on is sample-based and therefore optimistic for a large staging, so treat enabling it as an explicit, measured opt-in.
RELATA_READ_RATE_LIMIT_RPS—Read-path rate limit (separate bucket from write path).
RELATA_MEMORY_RATE_LIMIT_RPS—In-memory scan rate limit.
RELATA_RATE_LIMIT_AUTH_FAIL_RPSloopback bind: 10000; any other bind: 10Brute-force throttle after auth failure. The default follows the bind address (#5809): a non-loopback bind uses a deliberately low 10 RPS to slow credential stuffing; a loopback bind uses the same value as RELATA_RATE_LIMIT_RPS. Always ≥1 (.max(1) guard). Does not govern the escalating IP lockout below — that is a structurally separate mechanism; see RELATA_AUTH_LOCKOUT_FAILURE_THRESHOLD.
RELATA_AUTH_LOCKOUT_FAILURE_THRESHOLD5(#4950) Number of consecutive auth failures from one IP that arm the escalating lockout (#219, rate_limit_middleware's bare-IP/per-credential lockout with body "Authentication failures from this IP have triggered a temporary lockout…", 30s→60s→2min→5min backoff). This is a raw failure count, distinct from RELATA_RATE_LIMIT_AUTH_FAIL_RPS above (a requests-per-second rate governing a different, sibling token-bucket mechanism) — before #4950 this threshold had no env override at all, so raising RELATA_RATE_LIMIT_AUTH_FAIL_RPS to relax brute-force throttling for local dev/testing correctly disabled the token-bucket 429 but left this lockout still tripping at the hardcoded default. Strictly parsed (ADR-230): malformed values FATAL at startup. Clamped to ≥1 — 0 would lock an IP out on its very first failure. A request presenting a credential this node actually accepts (a registry-minted data-plane token, or the static RELATA_ADMIN_TOKEN) bypasses an active lockout rather than being collaterally rejected — see rate_limit_middleware's doc comment. #5407: the armed lockout's own response is a 401 (auth-throttled, with Retry-After), not a 429 — it stays the same status code as the pre-lockout failures, since the rejection reason (an unrecognized credential) never changes; only a Retry-After header distinguishes it.
RELATA_WEBHOOK_ALLOW_PRIVATE_NETWORKSfalseAllow notification-rule and RELATA_ALERT_WEBHOOKS targets on loopback, RFC 1918, carrier-grade NAT and IPv6 unique-local networks (and plain http:// to them). Off by default so a webhook cannot be aimed at the host's own network. Link-local and cloud-metadata addresses (for example 169.254.169.254) are refused whatever this is set to. Checked at registration and again after DNS resolution at delivery; redirects are never followed (#6002).
RELATA_WEBHOOK_MAX_INFLIGHT32Ceiling on concurrently in-flight alert-webhook deliveries (spawn_alert_webhooks, #530/#1174/#1830). Deliveries beyond the cap are dropped with a warn!; deliveries under the cap get a bounded retry with exponential backoff on 5xx/timeout before giving up. Raise for high-volume alerting pipelines; lower to bound webhook concurrency. Zero/invalid falls back to 32.
RELATA_QUERY_QUOTA0Per-principal read-cost cap (cost units, not rows). 0 = unlimited (no cap installed). A principal whose cumulative read cost exceeds a non-zero value within RELATA_QUERY_QUOTA_WINDOW_SECS receives a 429. Distinct from RELATA_MAX_RESULT_ROWS (which caps result size). #4751: this is NOT the per-tenant quota knob — it only feeds CostAccounting's server-wide fallback (crates/relata-prov/src/audit.rs), the last resort in the per-request cost-charge resolution order (per-principal quota → per-tenant override → this var's default → unlimited). The per-tenant admission gate a fresh tenant actually hits first (AdmissionController, error text "tenant quota exceeded: query cost N exceeds limit M") is cost_limit on that tenant's TenantQuota row — see PUT /v1/tenants/:id/quota (see Tenant Management) and the TenantTier preset (crates/relata-core/src/quota.rs) it's seeded from at tenant creation. Raising this var does not change that. Query cost itself (crates/relata-query/src/cost_estimate.rs) is roughly min(rows, limit) * (1 + join_count) * 10 CPU units, plus a small memory- and IO-derived component.
RELATA_STREAM_REAUTH_INTERVAL_SECS15(#2471) How often GET /v1/graph/changes / GET /changes (graph_changes_handler, crates/relata-cli/src/serve/streams.rs) re-runs check_auth_with_registry against the credential that opened the connection, for the life of the (potentially indefinite) SSE stream. The stream ends the moment a re-check fails, bounding how long a revoked or expired token keeps delivering events to at most this interval instead of "until the client disconnects". Unset falls back to 15; 0 is clamped up to 1 (never a zero-duration re-check loop).
RELATA_BULK_MAX_INFLIGHT0Cap on concurrent bulk work (GET /v1/export, /v1/rag/export, the Arrow and NDJSON stream endpoints), so exports and streams cannot occupy every worker an interactive read needs (#5695). 0 = unlimited (default). Work beyond the cap is refused with 503 (query-admission-rejected, Retry-After: 1) and counted in relata_query_class_shed_total{class="bulk"}; the cap is exported as relata_query_class_bulk_cap. Interactive reads are never counted against it. Malformed values fail startup (ADR-230).
RELATA_QUERY_TIMEOUT_SECS—Per-query execution deadline (seconds); a query past it aborts with a timeout error so it can't pin a worker (#1025). Unset/0 = no limit. Cancellation (#5695): the same cooperative checks also stop a query whose client disconnected (or whose RELATA_HTTP_TIMEOUT_SECS request timeout fired): the worker aborts with REL_CANCELLED (499, distinct from REL_TIMEOUT and never an empty success), freeing its CPU thread and its admission slot within one check interval (every 4096 rows in scan/aggregate loops); relata_query_cancelled_disconnect_total counts them, and relata_query_cancel_aborts_total counts the executor checks that actually observed the cancel and stopped. The same cancel-on-disconnect applies to every door that runs the engine: POST /v1/query, EXPLAIN ANALYZE, GraphQL (which executes through /v1/query) and the MCP query tool; each runs on a blocking worker that owns its admission permit, so the permit is released only when the worker has stopped. Spill files of a cancelled GROUP BY are removed when it unwinds. Work is accounted per class (interactive vs bulk exports/streams) in relata_query_class_{started_total,inflight,cancelled_total,busy_seconds_total}{class=...}; this is accounting only; the single limit is the optional RELATA_BULK_MAX_INFLIGHT cap on bulk work. The MCP entity, timeline, search and graph tools (get_entities, search_entities, search_knowledge, get_relationships, get_entity_profile, get_timeline, find_connections, paths_between, detect_communities, rank_key_nodes, hub_authority, predict_links, find_scc, aggregate_stats) also run on a cancellable worker, as do GET /v1/export, the /v1/rag/export scan and the Arrow/NDJSON stream producers (a dropped response body cancels the producer). The PATHS_BETWEEN DFS and the parallel SIMILAR scoring branch poll the same flag. Limits of the bound: an MCP tool or export stops at the next cooperative check inside the executor or export loop (every 4096 rows in export rendering and in /v1/query result-row JSON rendering, where a cancel answers REL_CANCELLED rather than a partial body); a single storage scan call, and graph algorithms that have no loop-level poll (find_cycle, GDS centrality/community kernels), run to the end of that call before the cancel is noticed. EXPLAIN ANALYZE also returns scan (rows, bytes read by the Scan stage) and spill (runs, bytes; a process-wide delta over the run, so it includes any concurrent query's spill). Row, memory and result budgets (REL_RESULT_CAP, REL_WINDOW_BUDGET) are unchanged.
RELATA_QUERY_MAX_INFLIGHTadaptive (#952 detected cores, min 1)CPU-query admission control (#1869, ADR-254): max POST /v1/query executions allowed to run concurrently inside the offloaded execution core. A request that can't get a slot within RELATA_QUERY_ADMISSION_WAIT_MS is shed with 503 + Retry-After instead of queueing unboundedly. /health//health/ready are exempt.
RELATA_QUERY_ADMISSION_WAIT_MS50Max time (ms) POST /v1/query waits for a CPU-query admission slot before shedding (#1869, ADR-254).
RELATA_QUERY_PRINCIPAL_MAX_INFLIGHTgeneral pool size - 1; unlimited when the general pool has fewer than 2 permits#5695: max concurrent admitted queries one authenticated principal may hold. A principal at its cap waits up to RELATA_QUERY_ADMISSION_WAIT_MS, then is shed with the same 503 query-admission-rejected problem type (detail says the principal is at its limit; relata_query_admission_principal_rejected_total counts it), so one heavy principal cannot occupy the whole pool and starve a light one. 0 disables the cap.
RELATA_SEGMENT_IO_MAX_INFLIGHT32#5694: process-wide cap on concurrent cold-vector segment searches; fan-out over many flushed segments no longer spawns one task per segment.
RELATA_SEGMENT_IO_PER_QUERY4#5694: concurrent segment searches a single query may run.
RELATA_SEGMENT_IO_MAX_INFLIGHT_MIB128#5694: cap on estimated bytes reserved by in-flight cold-vector segment searches.
RELATA_COMPACTION_MAX_INFLIGHT_MIB256#5682: cap on decode memory reserved by in-flight compaction segment reads across all types compacting at once (each segment reserves 4x its Parquet size; a segment larger than the cap still runs, alone). Fan-out is a fixed 4-way. See Compaction resource limits.
RELATA_COMPACTION_IO_MIB_PER_SEC128#5682: compaction I/O pacing in MiB/s, counting segment reads and output writes. 0 disables pacing. Pacing sleeps asynchronously so foreground requests and ingestion keep their threads.
RELATA_DELETE_MAX_ROWS_PER_STATEMENT50000#4832: max rows one DELETE FROM <type> [WHERE …] statement (HTTP /v1/query, DELETE /v1/objects/:type_name) will tombstone before returning. A predicate-less or low-selectivity delete over a large type previously snapshotted and tombstoned every matching row in one call — up to minutes of store.update() calls one at a time, all inside the single block_in_place call that also holds this request's one process-wide RELATA_QUERY_MAX_INFLIGHT CPU-query permit, starving unrelated queries with 503 CPU query pool saturated for as long as the delete ran. A call that hits this cap tombstones only the first RELATA_DELETE_MAX_ROWS_PER_STATEMENT matching rows and reports the rest via the response's remaining field; re-issue the identical statement to continue — already-tombstoned rows are excluded from the next call's snapshot, so repeated calls always make forward progress and finish. 0 disables the cap (pre-#4832 unbounded behavior). Rows the RAM-only store.update() path can't reach (disk-spilled — #4747) are resolved by ONE ObjectStore::retract_disk_batch call per statement rather than one per row (#4832 follow-up), which was the dominant real-world cost for a large disk-spilled type: each disk segment file is read + parsed exactly once per call instead of once per fallback row.
RELATA_EXPIRY_SWEEP_INTERVAL_SECS5#5781: how often the per-row expiry sweep runs. The sweep retracts rows past their own expiry (a retention policy with expiry_field, plus the built-in finished queue jobs and sequence idempotency receipts) so they stop counting against storage; compaction then reclaims the retracted versions. A row past its expiry is still returned by /v1/query until the next sweep, so this interval (plus the policy's grace_seconds) bounds how long an expired row stays visible. Values below 1 are treated as 1.
RELATA_EXPIRY_SWEEP_MAX_ROWS10000#5781: most rows one expiry sweep pass retracts. The sweep is a bounded background job: a backlog larger than this drains over consecutive passes rather than holding the retention lock for one long pass. Live (unexpired) rows are never selected.
RELATA_QUEUE_FINISHED_RETENTION_SECS604800#5768: how long a completed or dead-lettered queue job is kept (for GET /v1/queues/{name}/jobs/{id} and the dead-letter list) before the expiry sweep reclaims it. Jobs that are ready or leased never expire.
RELATA_SEQUENCE_RECEIPT_TTL_SECS604800#5783: how long a sequence allocation's idempotency receipt is kept. Within this window a retry with the same idempotencyKey returns the original range; after it the key is free again. The counter itself never expires, so a reclaimed receipt can never cause a value to be reissued.
RELATA_QUERY_CPU_THREADSadaptive (#952 detected cores × 4, min 4)Max blocking-pool threads (tokio::runtime::Builder::max_blocking_threads) on the real server runtime — the pool an offloaded /v1/query execution (block_in_place) runs on (#1869, ADR-254). Overrides tokio's flat built-in default (512).
RELATA_MAX_WATCH_SUBSCRIPTIONS1024Maximum concurrent query watches; registrations past the cap are rejected. A bounded background worker reevaluates watches after source-generation changes, outside the write/commit path. See query-watch behavior for queue, gap, and restart semantics (#1051, #5777).
RELATA_CHANGE_FEED_ENABLEfalseOpt-in change-data-capture: journals an authorized, resumable GET /v1/changes event for every write path (objects, bulk and queued ingest, SQL writes, graph links, deletes with or without If-Match, batch delete). Off: nothing is journaled and the route answers 404 change-feed-disabled. Parsed strictly (ADR-230); restart to change. See object change feed (#5716).
RELATA_CHANGE_FEED_RETENTION100000Events the object change feed (GET /v1/changes) keeps for replay, and the cap on its durable journal (older journal rows are retracted in the background); clamped to 64..5,000,000. A cursor older than the window gets an explicit 410 resynchronization outcome. See object change feed (#5716).
RELATA_DISCONNECTEDfalseDeclares a node with no route to the internet (#5705). At startup every configured outbound endpoint (RELATA_EMBED_URL, RELATA_ACCEL_ENDPOINT, RELATA_RERANK_URL, RELATA_COLBERT_ENDPOINT, RELATA_SPLADE_ENDPOINT, RELATA_OTLP_ENDPOINT, RELATA_AUDIT_OTLP_ENDPOINT, RELATA_AUDIT_ARCHIVE_ENDPOINT, RELATA_TSA_URL, REKOR_URL, AWS_ENDPOINT_URL, RELATA_ALERT_WEBHOOKS, cloud object-store URLs and cloud key management) must be inside the network boundary, or the server refuses to start and names the variable and host. Webhook URLs supplied at runtime are held to the same rule. See disconnected operation.
RELATA_DISCONNECTED_ALLOW_HOSTS—Comma-separated host names of customer-managed services inside the isolated network that RELATA_DISCONNECTED should accept. IP literals in loopback, RFC 1918 and unique-local ranges and localhost are always accepted; a name is never resolved through DNS to decide (#5705).
RELATA_MAX_RESULT_ROWS10000Maximum rows serialized in one HTTP /v1/query response. An unbounded SELECT exceeding the response cap returns truncated: true; inspect that flag even when next_cursor is null. Use bounded keyset queries (LIMIT n AFTER '<cursor>') to retrieve the complete set; the cap does not establish a snapshot across requests or bound executor materialization memory. LIMIT n OFFSET m is also checked against the planning cap and can be rejected with ResultCapExceeded (#2467). Read once per process; restart after changing it.
RELATA_RECURSIVE_CTE_MAX_ROWS100000Cumulative row cap for WITH RECURSIVE materialisation (#3181). The fixed-point loop is already bounded to 10 000 iterations, but a recursive term that self-joins its working set multiplies rows per iteration, so the iteration cap alone does not bound memory. Once the accumulated rows (or a single iteration's output) exceed this cap the query aborts with ResultCapExceeded. 0 disables the cap (unbounded).
RELATA_MAX_EXPORT_ROWS1000000Hard ceiling on GET /v1/export row-version count (#2461), mirroring RELATA_MAX_RESULT_ROWS for the /v1/query path. export_rows (crates/relata-cli/src/serve/query.rs) probes for cap + 1 rows via the bounded scan_all[_for_tenant]_with_limit storage calls and rejects with 413 Payload Too Large before rendering format when the type's row-version count (scoped to the caller's tenant, where applicable) exceeds the cap. 0 disables the cap (unbounded, matching RELATA_MAX_RESULT_ROWS=0's convention, which now means unlimited on /v1/query) — not recommended for large tables, since /v1/export still materializes its full (uncapped) result in memory rather than streaming it.
RELATA_MAX_OWL_REASONER_EDGES200000Hard ceiling on the number of live LinkStore edges handed to the OWL 2 reasoning kernel (infer_property_chains/materialise_inverses/validate_cardinality) per CHECK CONSISTENCY / INFER INVERSES / INFER CHAINS invocation (#4794). owl_edges_from_link_store (crates/relata-cli/src/serve/query/owl_statements.rs) checks the caller's tenant-scoped live edge count before the reasoning pass runs and rejects with 413 Payload Too Large past the cap, so an ordinary auth-only query-capable user cannot force an unbounded synchronous scan/reasoning pass (held under state.link_store's read lock) by registering a property_chain/transitive link type against a call-graph/CDR-scale tenant. 0 disables the cap (unbounded, matching RELATA_MAX_EXPORT_ROWS=0's convention).
RELATA_TRUSTED_PROXIES—Comma-separated trusted proxy CIDRs for real-IP extraction.
RELATA_CORS_ALLOWED_ORIGINS—Comma-separated allowed CORS origins and CSRF guard allowlist (#1383). Both layers read this single var on every profile (#2075 — Free previously had no override path at all). When unset: a non-loopback bind blocks all cross-origin requests and CSRF protection is disabled (warn); a loopback bind defaults to a localhost-only allowlist (localhost/127.0.0.1 on ports 3000/9090/5173) tuned for local frontend dev. E.g. https://app.example.com,https://admin.example.com.

Ingest and query

VariableDefaultDescription
RELATA_INGEST_QUEUE_MAX_BYTES5% of budgeted RAM (1 GiB if RAM probing fails)Shared byte budget for queued ingest payloads and batches being applied by the writer. Backpressure (HTTP 429) fires when EITHER the batch count (10,000) OR this byte budget would be exceeded — so a handful of very large batches can't admit hundreds of GB before the store-side cap sees them. 0 disables the byte check (count-only backpressure).
RELATA_FILES_UPLOAD_MAX_BYTES10737418240 (10 GiB)Largest declared size a resumable upload (POST /v1/files/uploads, #5690) may stage; larger requests are 413. Staging is on disk, so this bounds disk, not memory.
RELATA_FILES_UPLOAD_CHUNK_MAX_BYTES8388608 (8 MiB)Largest single chunk accepted by PUT /v1/files/uploads/{id}; a larger chunk is 413 and rolled back. Chunk bodies are streamed to disk frame by frame, so this is a request-size cap, not a buffer size.
RELATA_FILES_UPLOAD_TTL_SECS86400Lifetime of an upload session from creation. Expired sessions answer 410 and their staging data is reclaimed (also swept on the next session creation).
RELATA_FILES_UPLOAD_COMPLETE_TIMEOUT_SECS1800Request timeout for POST /v1/files/uploads/{id}/complete only (verify and stream the staged file to blob storage). Every other route keeps RELATA_HTTP_TIMEOUT_SECS; the larger of the two applies to this route. A timeout is 408 and the staged upload is kept so complete can be retried (#5690).
RELATA_FILES_UPLOAD_MAX_SESSIONS64Maximum live upload sessions per tenant; creating more is 429 with Retry-After.
RELATA_FILES_UPLOAD_MAX_STAGED_BYTES21474836480 (20 GiB)Maximum sum of declared sizes across live upload sessions (staging disk quota); beyond it creation is 429 with Retry-After.
RELATA_FILES_UPLOAD_TENANT_MAX_STAGED_BYTES10737418240 (10 GiB)Maximum sum of declared sizes across one tenant's live upload sessions; beyond it creation is 429 upload-quota-exceeded with Retry-After, so one tenant cannot use up the node-wide staging space (#5999).
RELATA_FILES_UPLOAD_PRINCIPAL_MAX_STAGED_BYTES10737418240 (10 GiB)Maximum sum of declared sizes across live upload sessions opened by one principal within a tenant; beyond it creation is 429 upload-quota-exceeded (#5999).
RELATA_FILES_PUT_TENANT_MAX_STORED_BYTES0 (unlimited)Maximum total stored bytes (sum of live object sizes) for one tenant through single-shot PUT /v1/files/content; a PUT that would exceed it, net of the key it overwrites, is 429 upload-quota-exceeded (#6016). Usage is read from the owner_tenant column stamped on writes, so objects stored before it existed are not counted. Checked per request, so concurrent PUTs can overshoot by at most two bodies.
RELATA_FILES_PUT_PRINCIPAL_MAX_STORED_BYTES0 (unlimited)Same bound per principal within a tenant, using the owner_principal column (#6016).
RELATA_INGEST_QUEUE_LANESDetected CPU cores, clamped 1..=64Number of independent lock domains ("lanes") the ingest queue shards into (#1871, ADR-219 adaptive sizing). Each lane owns its own deque + content-hash dedup window, so producers routed to different lanes (by a stable hash of object_type + tenant) never contend on the same mutex. capacity/RELATA_INGEST_QUEUE_MAX_BYTES and per-tenant quota stay global regardless of lane count. Parsed strictly (ADR-230) — a non-integer value fails startup.
RELATA_INGEST_IDEMPOTENCY_TTL_SECS86400How long a completed POST /v1/ingest/bulk Idempotency-Key is remembered (#5689). After expiry the same key is treated as new. Parsed strictly (ADR-230).
RELATA_INGEST_IDEMPOTENCY_MAX_ENTRIES100000Upper bound on remembered idempotency keys; the oldest are evicted first (#5689). Parsed strictly (ADR-230).
RELATA_INGEST_QUARANTINE_MAX_ENTRIES10000Per-tenant bound on quarantined records refused by ingestion contracts; the oldest are evicted and counted in the dataset's evicted_quarantine_total (#5714). Parsed strictly (ADR-230).
RELATA_INGEST_QUARANTINE_RETENTION_SECS604800 (7 days)Retention of a quarantined record before it is purged (#5714). Parsed strictly (ADR-230).
RELATA_INGEST_LATE_ARRIVALfalseMaster switch for the ingest-writer late-arrival gate (#3104, H42/H43). When true, the background writer classifies every drained batch against an event-time watermark and routes late batches per RELATA_INGEST_LATE_POLICY. When false (default) the drain path is unchanged. Opt-in because watermark-based routing is only appropriate for genuinely streaming sources, never for backfill/replay ingest.
RELATA_INGEST_LATE_POLICYdropWhat the late-arrival gate does with a batch whose event time is behind the writer's watermark (#3104): drop (discard, counted), dlq (preserve every row in the NDJSON DLQ sink), or reprocess (retroactive insert under a fresh system_from). Parsed strictly (ADR-230) — any other value fails startup. Only read when RELATA_INGEST_LATE_ARRIVAL=true.
RELATA_INGEST_WATERMARK_BOUND_NS5000000000 (5 s)Out-of-order bound (ns) of the ingest writer's watermark generator (#3104): the watermark trails the maximum observed event time by this much, so events arriving within the bound stay on-time. Parsed strictly (ADR-230) — a non-integer value fails startup.
RELATA_INGEST_LATE_WINDOW_NS—Optional window size (ns) threaded through the late-arrival classification (#3104) so the reprocess policy can log the affected window starts. Unset = no window layout is assumed. Parsed strictly (ADR-230).
RELATA_INGEST_DLQ_PATH{data_dir}/ingest-dlq.ndjsonNDJSON dead-letter sink for batches routed there by RELATA_INGEST_LATE_POLICY=dlq (#3104) — one JSON line per row, embedding the row in the WAL shape so it stays replayable. Defaults under the data directory; with no data directory and no override, dlq degrades to a counted drop.
RELATA_INGEST_WRITER_SHARDS1#3888: number of intra-object_type row shards the background ingest-writer drain's store-insert phase fans out across via rayon, ON TOP OF its existing per-distinct-type fan-out (crates/relata-cli/src/serve/ingest_writer.rs::group_and_shard_pre_batches_capped/shard_type_group_by_identity). 1 (default) is byte-identical to pre-#3888 behavior: a drain cycle dominated by ONE hot type (the SIEM/Kafka/OTLP firehose case — LogEvent/KafkaEvent) still runs fully sequentially. N > 1 hash-routes each row by its id/_pk identity (falling back to a hash of the row's own serialised WAL line for rows with neither) into up to N independent shard buckets, so that type's insert-phase work spreads across up to N rayon tasks instead of one; same-identity rows always route to the same shard (never split across two concurrently-running threads), keeping resolve_existing_for_drain's race-free supersede-lookup guarantee (#3824) intact per shard. #3888 round 12 (coupling fix): this value is CAPPED per type at that type's REAL, already-pinned Table shard count — ObjectStore::table_shard_count(object_type), driven by RELATA_TABLE_GC_SHARDS/_AUTO (#3497/ADR-0288) — never raised past it. Rounds 9-11's real --release bench runs found the two knobs are NOT independent in the way earlier docs claimed: raising this value alone, with RELATA_TABLE_GC_SHARDS/_AUTO left at its default of 1, fanned work out across N rayon tasks that all still serialized on the SAME one real Table lock — measurably WORSE than N == 1, not better. To get real intra-type parallelism, raise RELATA_TABLE_GC_SHARDS/_AUTO too; this knob then only controls how many of the store's real shards the CLI drain's rayon fan-out actually uses (capped at min(RELATA_INGEST_WRITER_SHARDS, real table shard count)). #3888 round 14: because that cap collapses ANY value of this knob back to 1 at the default configuration, setting it alone used to be a completely silent no-op — the drain now logs a one-time WARN naming both knobs whenever the cap reduces a requested fan-out (crates/relata-cli/src/serve/ingest_writer.rs::warn_once_on_shard_cap_collapse). Round 14 also found, by code reading (not yet measured), that raising both knobs together is still not sufficient for near-linear scaling: ObjectStore::insert_with_tenant takes further per-object_type-only exclusive locks per row that RELATA_TABLE_GC_SHARDS does not shard (secondary_index[type], range_index[type], historical.general[type], the pending_fts[(type, tenant)] queue guard, and — for tenant-tagged rows — tenant_live_index[type]), so a single-type firehose still serialises on those. That remaining work is tracked as #4371; until it lands, do not expect this knob (with or without RELATA_TABLE_GC_SHARDS) to deliver near-linear intra-type ingest scaling. See B-157 in docs/src/specs/benchmarks.md for the file:line list and the control experiment that confirms or refutes it. Parsed strictly (ADR-230 v1.1); clamped to [1, 64]. #4175: a panic in one shard-group's row-processing (e.g. an unbounded-arithmetic/index panic reachable from row data) is caught and dead-letters only that shard-group's rows (counted in rows_dropped) — it no longer discards the task_updates of every other, unaffected shard-group processed in the same drain cycle.
RELATA_SEQUENCE_RULE—Comma-separated spec for the sequence-correlation detection job's steps (e.g. A→B,window=300). Unset = default rule.
RELATA_GLOBAL_SCAN_ALLOWED—Set true to allow full-table scans (expensive on large datasets) and to let an un-scoped query executor see every row. Relata DB is single-tenant, so this only removes the scan guard.
RELATA_MV_MAX_ROWS—Max rows per materialized view partition.
RELATA_MV_CHANGE_LOG_ENABLEfalse#3901 round 6 (step (ii) of the incremental-refresh design documented on mv_compute in crates/relata-cli/src/serve.rs and in crates/relata-query/src/mv_refresh.rs's module doc): gates whether ObjectStore::insert/insert_batch/insert_batch_atomic/update/retract record each touched RowId into a bounded per-type change-tracking log (crates/relata-storage/src/store/mv_change_log.rs) for a future materialized-view incremental-refresh consumer. Default false — recording is pure overhead with no consumer yet (step (iii), a delta-computing refresh closure, is still open), so it stays off until that consumer lands. Parsed strictly (ADR-230).
RELATA_FACET_SCAN_LIMIT100000Row ceiling for FACETS aggregation (#1825). When a query requests facets, its LIMIT is bumped to at least this many rows so facet counts reflect the full matching set rather than just the top-k; the same value short-circuits the per-row facet-counting loop even if the caller's own LIMIT was larger. Lower it on smaller deployments to cut the bumped-scan cost; raise it for accurate facets over larger match sets.
RELATA_AUDIT_SHARDS8Number of independent hash-chain shards for the audit log (#1878), clamped to [1, 256]. Each shard has its own lock, so push throughput scales with core count. Set to 1 to reproduce the pre-#1878 single-chain behavior exactly -- the setting to use when a compliance requirement demands one global total order.
RELATA_AUDIT_LOG_WARN_MB1024Size threshold, in MB, above which the background audit verifier (every 300s) logs a WARN that data_dir/audit.jsonl is large (#2718). Rotation (RELATA_AUDIT_SEGMENT_MAX_MB/RELATA_AUDIT_SEGMENT_MAX_AGE below) is default-on on every profile (100 MB or daily, #5591), so this only fires if rotation was explicitly disabled or the threshold is set below the segment size -- it is the audit-log-specific early-warning signal -- distinct from the general disk-pressure gate (RELATA_MIN_FREE_DISK_MB), which only reacts once the whole filesystem is nearly full. The current size is always sampled into the relata_audit_log_bytes gauge (/metrics) regardless of this threshold; relata_audit_segments (rotated segment count) and relata_audit_last_verified_timestamp_seconds (last valid background verification, 0 = none yet) sit alongside it (#5591; runbook: "Audit chain invalid"). Set to 0 to disable the warning log line (the gauge keeps updating). See ADR-0302 for current segment shipping and anchored retention; ADR-0274's original manual archival procedure is historical only.
RELATA_AUDIT_SEGMENT_MAX_MB100 (every profile)Size threshold, in MB, above which the audit-drain task automatically rotates data_dir/audit.jsonl to a numbered segment (audit.jsonl.<N>) and opens a fresh live file (#2718 chain-aware rotation; default-on on every profile per #5591; an explicit value always wins). 0 disables the size trigger. Works together with RELATA_AUDIT_SEGMENT_MAX_AGE (whichever fires first). Rotated segments replay transparently on the next restart (relata_prov::discover_audit_segments/read_audit_jsonl_entries) into one continuously verified chain -- rotation never trips handle_audit_integrity_failure. Rotated segments are sealed (RELATA_AUDIT_SEGMENT_SEAL_ENABLED) and are deleted only by opt-in retention (RELATA_AUDIT_SEGMENT_RETENTION_DAYS, default 0 = never), behind a KMS-signed trust anchor. The active policy is shown in relata serve --help and the boot banner (Audit audit rotation: daily / 100 MB). See ADR-274's "Chain-aware rotation" amendment.
RELATA_AUDIT_SEGMENT_MAX_AGE86400 (daily, every profile)Age trigger, in seconds (#5591): the live audit.jsonl is rotated to a numbered segment once it has been receiving entries for this long (measured from the file's creation time where the platform reports it, else from first observation after boot) and is non-empty. 0 disables the age trigger. Combined with RELATA_AUDIT_SEGMENT_MAX_MB, whichever comes first rotates. Malformed values fail startup (ADR-230). Same chain-aware replay, sealing and retention semantics as RELATA_AUDIT_SEGMENT_MAX_MB.
RELATA_AUDIT_SEGMENT_SEAL_ENABLEDtrue (every profile)#5591 / ADR-0302: when the audit drain rotates audit.jsonl, it seals the new segment. The segment is chain-verified once, from the previous seal's per-shard tail heads, and a record is appended to data_dir/audit.seals.json (written atomically and hash-chained): file SHA-256 and length, entry count, per-shard seed and tail heads, seal time. A journal entry (principal relata-audit-seal) binds the seal into the live chain. At boot each sealed segment is checked with one SHA-256 pass over its bytes, and only the region after the newest journal-bound seal is chain-replayed (seeded from that seal's tails), so boot cost and memory track recent activity rather than total history. /v1/audit/log after a restart shows that window; relata export audit still reads every segment. A sealed segment whose bytes changed, or which is missing without a signed trust anchor, is an unrecoverable verification failure: startup preserves the artifacts and records a continuity restart in every profile; it exits 78 only if preservation or marker persistence fails. A missing or corrupt audit.seals.json falls back to the full replay. Segments rotated before this existed are sealed automatically after the next successful boot. false writes no seals and boot does a full replay from genesis every start. Malformed values fail startup (ADR-230).
RELATA_AUDIT_SEGMENT_COMPRESS_ENABLEDfalse (default build); true (open edition, #5953)#5591 / ADR-0302 §4: gzip each newly sealed audit segment to audit.jsonl.<N>.gz. The .gz is written atomically, the raw file is then removed, and the seal's SHA-256 covers the stored .gz bytes. This happens after the segment's verify-once pass. Boot, relata export audit, relata prov export and relata audit-recover read .gz segments transparently, and if a crash leaves both forms, the .gz wins. The default is off so external tooling that reads audit.jsonl.<N> keeps working. Segments sealed before you enable this stay uncompressed, because a seal's digest is immutable. Malformed values fail startup (ADR-230).
RELATA_AUDIT_SEGMENT_RETENTION_DAYS0 (never delete; default build); 365 (open edition, #5953)#5591 / ADR-0302 §4, the ADR-0280 Phase 3 deletion. After each seal, the audit drain deletes the oldest contiguous run of sealed segments whose seal is at least this many days old. The newest sealed segment is always kept. Deletion happens only after these steps: each candidate's digest still matches its seal; the run independently re-derives as covered (it replays from the run's first seed to the last seal's tail heads in every shard); a new KMS-signed AuditTrustAnchor with exactly that boundary is appended to audit.trust_anchor.json and re-verifies through the boot verifier. The deletion is then journaled in-band (principal relata-audit-retention) and counted in relata_audit_segments_deleted_total. Deletion is refused unless RELATA_KMS_KEY_ARN is set, or RELATA_KMS_LOCAL_DEV=true (dev only); an open-edition node may sign with the dev key. At boot, a sealed segment may be missing only if a cryptographically signed, verified anchor covers it. Anything else is an integrity failure. Ship sealed segments to write-once storage before they age out. Malformed values fail startup (ADR-230).
RELATA_AUDIT_DIR{data_dir}/audit#5953 (open edition): directory for the audit log (audit-local.jsonl, rotated and gzipped segments, audit-archive.manifest.json, archive/, legacy/). Created 0700, files 0600; a wider mode is tightened and logged, and if it cannot be made private startup is refused unless RELATA_AUDIT_PERMISSIONS_RELAXED=true. Mount it on its own volume so a full audit volume cannot fill the data volume and the reverse. Files from the previous layout in data_dir (audit-local.jsonl*) are moved here at boot, idempotently; a chained audit.jsonl* from another edition is moved to legacy/ and never read. The default build keeps its chain files in data_dir.
RELATA_AUDIT_PERMISSIONS_RELAXEDfalse#5953: start even if RELATA_AUDIT_DIR cannot be restricted to 0700. Logged at WARN. Malformed values fail startup (ADR-230).
RELATA_AUDIT_DIR_MAX_MB10240#5953: total size cap of the audit directory. Over the cap, the oldest archive-acknowledged segments are evicted first (overriding the reclaim grace, never the acknowledgement). If nothing is eligible a WARN is logged and nothing is deleted. 0 disables the cap.
RELATA_AUDIT_MIN_FREE_MB1024#5953: free space on the audit directory's filesystem below which a WARN is logged (checked every 5 minutes). 0 disables.
RELATA_AUDIT_MIN_FREE_CRITICAL_MB256#5953: free space below which /health/ready answers 503 audit-sink-unavailable (NIST AU-5). With RELATA_AUDIT_FAIL_CLOSED=true audited requests are refused too. 0 disables.
RELATA_AUDIT_RETENTION_HOLDfalse#5953: legal hold on the audit directory. While true, RELATA_AUDIT_SEGMENT_RETENTION_DAYS and RELATA_AUDIT_DIR_MAX_MB delete nothing (a WARN is logged once and relata_audit_retention_hold is 1); archiving and gzip continue and the directory can grow, so watch the free-space thresholds. Use it while an investigation or an erasure proof (#5697) needs the history. Malformed values fail startup (ADR-230).
RELATA_AUDIT_FAIL_CLOSEDfalse#5953: when critical free space degrades readiness, also refuse audited data-plane work with 503 audit-sink-unavailable. The live log still never drops a staged record (ADR-192).
RELATA_AUDIT_ARCHIVE_URLunset (local {audit_dir}/archive/)#5953: where sealed, gzipped segments are shipped: file:///path, s3://bucket/prefix, gcs://bucket/prefix or azure://container/prefix. Each segment is uploaded, read back and compared by SHA-256, and only then recorded in the local manifest; local copies are removed only after that acknowledgement plus RELATA_AUDIT_ARCHIVE_GRACE_SECS. Work is done on a background thread in bounded batches with exponential backoff; an outage never blocks or drops the live log and never records a false success.
RELATA_AUDIT_ARCHIVE_ENDPOINTunset#5953: S3-compatible endpoint (MinIO, Ceph RGW, R2). Independent of the data store's AWS_* variables.
RELATA_AUDIT_ARCHIVE_REGIONus-east-1#5953: S3 region for the archive.
RELATA_AUDIT_ARCHIVE_ACCESS_KEY_IDunset#5953: archive access key id (S3), or storage account (Azure). Required for s3://.
RELATA_AUDIT_ARCHIVE_SECRET_ACCESS_KEYunset#5953: archive secret key (S3) or account key (Azure). Required for s3://. Never logged.
RELATA_AUDIT_ARCHIVE_SERVICE_ACCOUNT_PATHunset#5953: GCS service-account JSON for a gcs:// archive.
RELATA_AUDIT_ARCHIVE_ALLOW_HTTPfalse#5953: allow a plaintext http:// archive endpoint (local MinIO).
RELATA_AUDIT_ARCHIVE_GRACE_SECS3600#5953: seconds a local segment is kept after the archive acknowledged it.
RELATA_AUDIT_EVENTSauthn,authz,admin,write,read-denied#5953 (open edition): comma list of event classes recorded by the best-effort audit path: authn, authz, admin, write, read-denied, read. Allowed reads (read) are off by default and counted in relata_audit_reads_not_logged_total. Required (durable-mutation) audit is never filtered. An unknown class fails startup.
RELATA_AUDIT_OTLP_ENDPOINTunset#5953 (open edition): OTLP/HTTP collector base URL (/v1/logs is appended) to which security events (never allowed reads, no statement text) are forwarded as OTel log records. Best effort: bounded queue, drop-newest, counted in relata_audit_forward_dropped_total; the local log remains the source of truth. Separate from RELATA_OTLP_ENDPOINT (traces).
RELATA_AUDIT_OTLP_HEADERSunset#5953: name=value request headers for the OTLP log exporter, comma separated (for authentication).
RELATA_AUDIT_READ_SAMPLE_RATIO0#5953 (open edition): fraction 0.0..=1.0 of allowed reads recorded while the read class of RELATA_AUDIT_EVENTS is off. Deterministic per request id, so all rows of one request are in or out together; the rest still count in relata_audit_reads_not_logged_total. Out of range fails startup.
RELATA_AUDIT_OTLP_CA_FILEunset#5953: PEM CA bundle trusted for the OTLP log collector (private CA), in addition to the system roots. Requires an https:// endpoint.
RELATA_AUDIT_OTLP_CLIENT_CERT_FILEunset#5953: PEM client certificate presented to a collector that requires mutual TLS. Must be set together with RELATA_AUDIT_OTLP_CLIENT_KEY_FILE.
RELATA_AUDIT_OTLP_CLIENT_KEY_FILEunset#5953: PEM PKCS#8 private key for RELATA_AUDIT_OTLP_CLIENT_CERT_FILE.
RELATA_AUDIT_OTLP_QUEUE1024#5953: OTLP exporter queue capacity in records.
RELATA_FTS_MAX_DOCSunboundedMax documents held in the full-text search index before the spill trigger fires (#712). Set explicitly to cap it.
RELATA_FTS_MAX_RESIDENT_BYTESadaptive (#5625): ≈9% of detected effective RAM (cgroup-clamped, #5265), no small-container floor; 512 MiB when the RAM probe failsCurrent behavior: byte-budgeted complement to RELATA_FTS_MAX_DOCS's document-count trigger. After each full-text flush, the just-written object's resident tenant cells' estimated bytes are checked against the budget; one cell is spilled when either trigger is crossed. The largest unrelated object-type cell is preferred. If that unrelated victim was spilled recently, the exact active (object type, tenant) cell is used instead. Active cells may be spilled again after a query pages them in. These estimates and flush-time spills are not a total-RSS or hard cgroup limit: queries may page cells into RAM transiently. serve installs the adaptive fallback at boot; an explicit value always wins. Strict parse_env_u64 per ADR-230; 0 disables the budget and overrides the fallback. Source 200299c012f5fd3779c727eebfd0ae9ee73908a7 implements the store-wide adaptive fallback only; explicit values retain per-type behavior, including 0 to disable. This source is independently reviewed but NOT BUILT / NOT TESTED; 14 new regressions are authored but NOT RUN (scope and limits). See the current v3 completion status and ADR-219 for qualification limits.
RELATA_FTS_MAX_TERMS5000000Max unique terms in the full-text dictionary. Past this cap, new terms are silently dropped so the dictionary stays below ~200 MB even under high-cardinality OCR/log/social-media ingest.
RELATA_FTS_RESIDENT_TEXTfalseWhether the full-text index keeps a resident copy of every indexed document's text for snippet generation (#1874). Off by default: a search hit's snippet is instead resolved lazily from the row store, for the surviving limit hits only -- the row table already holds the text, so the default path never stores it twice. Set to true to restore the pre-#1874 resident-snippet behavior (marginally faster for small corpora that query heavily). Strict bool_env parse per ADR-230.
RELATA_FTS_POSITIONStrueWhether the full-text index maintains the positional index (FullTextIndex::positions) that PHRASE search verifies token adjacency against (#3896 item 1). Positions cost roughly 8x the source-text size (one u32 offset per token occurrence, per document) and are read by nothing else -- plain search/search_fuzzy/BM25 scoring never touch them. Default stays true (unlike most opt-in memory knobs) because the fallback is conditional: with positions off, PHRASE is verified by re-tokenising each candidate document's resident text (search/phrase.rs), which is exact but needs RELATA_FTS_RESIDENT_TEXT=true -- with both off, every PHRASE query against the affected type returns zero matches (a warning is logged when positions are disabled in that combination). The fallback also trades RAM for CPU: it is O(first-term df x document length) per phrase query instead of a positional lookup. Set false per type (ObjectStore::set_fts_positions_enabled) for a type that never uses PHRASE, or alongside RELATA_FTS_RESIDENT_TEXT=true for a type that uses PHRASE rarely, to reclaim that memory. Strict bool_env_or parse per ADR-230.
RELATA_FTS_SHARDSmin(available_parallelism, 4)Number of independently-locked segments each per-type full-text index fans documents/queries out across (#1874, ADR-0256). A document routes to shard hash(id) % N; a write only takes that one shard's lock, so a reader on any other shard is never blocked by concurrent indexing, and a query is scored across all N shards in parallel. BM25 IDF and length normalization stay corpus-global regardless of N (shared n_docs/total_doc_len/per-term df), so any N (including 1, today's pre-#3410 single-lock behavior) returns identical rankings -- only the RAM layout and concurrency characteristics differ. This is the TARGET shard count a growth-aware index migrates up to (growth threshold fixed at 10,000 documents, #3557); an explicit RELATA_FTS_SHARDS override still applies immediately with no growth involved (e.g. 1 to force single-threaded fan-out for the index's whole life). Clamped to at least 1; malformed/0 values fall back to the default. Strict parse_env_u64 per ADR-230.
RELATA_FTS_COLD_TIER_COMPACT_POSTINGSfalse(#3896 round 9) Opt-in switchover of the disk-spilled/paged full-text "cold tier" (FullTextIndex::to_segment/from_segment, store/index_paging.rs) postings codec, for any one term's posting list at/above 256 entries, from the plain continuous delta+varint chain (#3558) to CompactPostingList's blocked delta+varint chain (search/compact_postings.rs). This is purely an at-rest wire-format choice -- from_segment always decodes either codec straight back into the same Vec<PostingEntry> the always-resident hot path (BM25/Block-Max WAND/WAND/TAAT) has always used, so enabling it changes nothing about query results or RAM-resident representation, only the bytes a spilled segment's codec byte (segment format v6) carries per term. Every write also decode-verifies the candidate blocked payload against the source entries before trusting it, falling back to the plain codec on any mismatch. Off by default: this is a live disk-format change this cargo-free pass could not execute end-to-end beyond unit tests, so it stays an explicit operator opt-in. Strict bool_env_or parse per ADR-230.
RELATA_PENDING_FTS_MAX1000000Cap on the main pending full-text-index backlog (documents awaiting async FTS indexing) before new entries overflow into the RELATA_PENDING_FTS_OVERFLOW_MAX second-chance queue (#943, extended by #3896). 0 (or unset) uses the default.
RELATA_PENDING_FTS_OVERFLOW_MAX1000000(#3896) Cap on the bounded second-chance queue a pending FTS doc overflows into when RELATA_PENDING_FTS_MAX is full. As the periodic drain frees room in the main queue, overflowed docs are pulled back in and indexed automatically — a transient ingest burst above the main cap recovers instead of being dropped. Only once BOTH this queue AND the main queue are simultaneously full are new docs dropped-with-count (see pending_fts_dropped); the row itself always stays stored/durable either way, only its deferred FTS indexing is affected. Strict parse_env_u64 per ADR-230; 0 disables the second-chance tier entirely (immediate drop on main-queue overflow, matching pre-#3896 behavior).
RELATA_PENDING_INDEX_WORK_MAX1000000Cap on the pending secondary/range-index + vector-embedding backlog (rows awaiting async indexing, deferred off the insert/insert_with_prov critical path, #1872). UNLIKE RELATA_PENDING_FTS_MAX, past this cap the insert is REJECTED (StoreError::IndexQueueFull) rather than silently dropped — a dropped secondary/vector entry would permanently hide a row from index-routed queries. The queue is also bounded by bytes (#5940): queued rows pin their _emb_* vector bytes, so once the queued embedding payload passes a quarter of RELATA_STORE_MAX_RAM_MB (256 MiB when no ceiling is set, floor 256 KiB) a vector write applies its embedding inline instead of queueing, and boot WAL replay drains the queue. No separate setting. Unset uses the default.
RELATA_RULE_EVAL_INTERVAL_SECS30How often the rules engine re-evaluates derived facts. Parsed strictly (ADR-230) — a non-integer value fails startup (#2935).
RELATA_SCHEDULED_DETECTION_JOBSempty (no recurring domain scans)Comma-separated allowlist of remaining generic detection jobs, currently sequence_correlation. Fresh foundation deployments schedule none. Unknown names are logged and ignored. Authenticated one-shot MCP schedule_job calls follow the names registered by the running server. Domain recipes such as C2 beacon, convoy, contradiction, transaction-ring, TBML, and formulary drug-interaction detection run from caller-owned workflows; see the migration guides. Generic lazy identity enrichment keeps its own drain task and is not selected here.
RELATA_DETECTION_JOBS_INTERVAL_SECS60Detection job sweep interval, applied only to jobs selected by RELATA_SCHEDULED_DETECTION_JOBS. Parsed strictly (ADR-230) — a non-integer value fails startup instead of silently falling back to the 60s default (#2935).
RELATA_FORGET_SCHEDULER_INTERVAL_SECS60(#2449) How often the background forget-scheduler tick runs (scans due RetentionMark rows and retracts the matching MemoryItems). Widen this on deployments with large tenant counts to reduce per-tick blocking-pool cost; the scan+retract work itself runs via tokio::task::spawn_blocking, mirroring RELATA_DETECTION_JOBS_INTERVAL_SECS/RELATA_JOBS_MAX_PARALLEL (#1824).
RELATA_RETENTION_ENFORCER_INTERVAL_SECS60(#2449) How often the background retention-enforcement tick runs (scans active RetentionPolicy rows and retires over-age rows). Widen this on deployments with large tenant/policy counts; the per-policy scan+retract work runs via tokio::task::spawn_blocking, mirroring RELATA_DETECTION_JOBS_INTERVAL_SECS (#1824).
RELATA_MEM_WATCHDOG_ENABLEDtrue(#4932) Enables the background memory-pressure watchdog (serve/memory_watchdog.rs): every RELATA_MEM_WATCHDOG_INTERVAL_SECS it samples this process's own RSS (Linux /proc/self/status VmRSS) and logs a tracing::warn! once usage crosses RELATA_MEM_WATCHDOG_WARN_THRESHOLD_PCT of the effective memory ceiling — the one in-process signal available before an OS/cgroup OOM-kill, since SIGKILL runs no handler code and the kill itself can never be logged (main.rs::install_panic_hook's doc comment is the origin of this ticket). Set false to disable (e.g. a sandboxed environment with no meaningful /proc//sys). Strict bool_env_or parse per ADR-230.
RELATA_MEM_WATCHDOG_INTERVAL_SECS1(#4932) How often the memory-pressure watchdog samples live RSS. Strict parse_env_u64_or per ADR-230.
RELATA_MEM_WATCHDOG_WARN_THRESHOLD_PCT85(#4932) Percentage of the effective memory ceiling (cgroup v2 /sys/fs/cgroup/memory.max when present and bounded, else resource.rs's detected host RAM) at/above which the watchdog warns. Strict parse_env_f64_or per ADR-230.
RELATA_MEM_WATCHDOG_REPEAT_INTERVAL_SECS300(#4932) Minimum gap between repeat memory-pressure warnings while usage stays continuously above RELATA_MEM_WATCHDOG_WARN_THRESHOLD_PCT — the watchdog warns on the rising edge immediately and then at most once per this interval, never every sample tick. A fresh drop-below-then-rise-above crossing always warns immediately regardless of this interval. Strict parse_env_u64_or per ADR-230.
RELATA_DETECT_PACKSnetwork,contact,cryptoComma-separated detector packs to activate (network, contact, crypto, financial, device, transport, payment, social, ics, telco, regulatory; or all / none). When unset, the minimal default network,contact,crypto applies on every node (#5809 removed the profile-scoped default). An explicit value always overrides it.
RELATA_DETECT_TYPE_PACKS—(#2257, SI-2) ;-separated per-type detector-pack overrides: TypeName=<spec>;TypeName=<spec>;..., e.g. Transaction=financial,contact;Vessel=transport;LogEvent=none. Each <spec> uses the same grammar as RELATA_DETECT_PACKS (comma-separated pack names, or all/none/default). Bootstraps AppState::type_detect_configs at startup; also settable at runtime via POST /v1/types/detect-config ({"type": "...", "packs": [...]}), listed via GET /v1/types/detect-config and GET /v1/system/specs. A type with no override falls back to the process-global RELATA_DETECT_PACKS config (including its profile-scoped default above) — =none (or packs: []) disables detection for that type entirely, at zero detection cost.
RELATA_DETECT_BATCH_SIZE256Chunk size for batched identity detection (SmartIngest::detect_batch_with). Inputs are detected in chunks of this many so the per-input setup and a reused hit buffer are amortised across the chunk instead of one synchronous detect_with per cell (#361). 0 or unset falls back to 256; a malformed (non-integer) value FATALs at startup (#4799 — matches the fixed token-length cap below). Detection results are identical regardless of batch size; this only tunes throughput.
RELATA_IDENTITY_MIN_CONFIDENCE1.0(#2371) Minimum DetectionHit confidence, in [0.0, 1.0], required before a detected identity is written into the authoritative IdentityIndex (the SAME_IDENTITY/RESOLVE_IDENTITY/LOOKUP_IDENTITY operators' backing store) via enrich_mvs/enrich_records_batch. Defaults to 1.0 — only checksum-verified DetectionHit::certain hits qualify, matching today's behavior for every checksum-verified canonical kind. Every DetectionHit::probable(...) heuristic hit in relata-detect (e.g. TikTokHandle/InstagramHandle at 0.6, SnapchatHandle/FacebookProfileId/FacebookPageId at 0.5, MpesaRef at 0.7) is excluded by default; lower this to admit them once an operator has accepted the false-attribution risk a purely structural match carries. Out-of-range values are clamped to [0.0, 1.0]. Does not affect the separate LinkStore carries/identifies edges, which already carry their own per-edge confidence.
RELATA_FK_EDGES—Comma-separated FK-to-edge mappings: TypeName.field=predicate,... (e.g. CdrRecord.tower_id=uses_tower,TransactionGraph.from_wallet=sends_to). At ingest time each matching FK field is materialised as a KnowledgeTriple row so PATHS_BETWEEN can traverse typed-object→graph boundaries without schema changes (#976).
RELATA_IDENTITY_LINK—Comma-separated identity-link mappings: TypeName.field=predicate,... (e.g. CdrRecord.caller_msisdn=has_msisdn). At ingest time the field value is materialised as a KnowledgeTriple with the given predicate. Use identity-semantic predicates (has_msisdn, has_email, identified_by, linked_to) to make the link visible through lookup_identity (#977).

Observability

VariableDefaultDescription
RELATA_LOG_LEVELwarnLog verbosity: error | warn | info | debug | trace. Defaults to warn (previously info) — routine per-request/operational INFO logs are high-volume enough to drown a terminal or log aggregator on any real workload; startup, degraded-state, and error conditions still surface at warn. Set RELATA_LOG_LEVEL=info (or debug/trace) to restore the old verbosity for local debugging.
RELATA_LOG_FORMATTTY-detectLog format: pretty (human-readable) | json (structured). Defaults to pretty when stderr is a TTY, json otherwise. Note: the CLI binary defaults to pretty format; containers should explicitly set RELATA_LOG_FORMAT=json for structured log ingestion.
RELATA_OBSERVE_STREAMfalseEnables the live structured observability event stream at GET /v1/observe/stream (SSE). When on, every protocol-door query's lifecycle (received → completed / failed) is published as a typed JSON event carrying door, purpose, tenant_id, trace_id, stage, sql_template, rows, latency_ms, error. Tenant-scoped server-side. Strict bool parser (on/true/1/yes; anything else, including a typo, stays off). See monitoring.
RELATA_OTLP_ENABLEDfalseSet true to enable native OTLP HTTP ingest endpoints (POST /v1/traces, /v1/metrics, /v1/logs). Disabled by default; off-the-shelf OTLP exporters (Jaeger, Tempo, Grafana Alloy) will receive 404 until enabled. Parsed strictly (ADR-230) — a value that is not one of true/1/yes/on or false/0/no/off fails startup (#2935).
RELATA_OTLP_ENDPOINT—OpenTelemetry OTLP/HTTP endpoint. Telemetry disabled when unset.
RELATA_OTLP_SAMPLE_RATIO0.01Parent-based TraceID-ratio sampler for root traces (1% default).
RELATA_METRICS_PUBLIC—Set true to serve /metrics without the bearer check (auth terminated at the network layer). Default fails closed.
RELATA_PROFILE_SAMPLE_RATE0.01Fraction ([0.0, 1.0]) of production queries that get per-operator attribution (scan/filter/join/aggregate/sort/acl/serialize timing, feeding /metrics — see the flamegraph guide). 0.0 disables sampling entirely; EXPLAIN ANALYZE always instruments regardless of this setting. Malformed or out-of-range values fail startup (ADR-230, ADR-0238).
RELATA_PPROF_ENABLEfalseEnable GET /admin/debug/pprof/profile (CPU pprof protobuf, ?seconds=1..30) and GET /admin/debug/pprof/heap. Off by default — a profiling endpoint is an attack surface (leaks workload shape + internal symbol names). When enabled, both routes additionally require RELATA_ADMIN_TOKEN to be set and a matching Authorization: Bearer on every profile, including the free profile where the general bearer check is otherwise optional — there is no dev bypass for this surface. See ADR-0238 and the flamegraph guide.

Detection-job scheduler tick metrics (#2450): /metrics also exposes relata_detection_job_tick_seconds_sum + relata_detection_job_tick_count (sum/count convention — divide for the average tick duration) and relata_detection_job_tick_overrun_total, a counter incremented whenever a tick's (job, tenant) fan-out takes longer than RELATA_DETECTION_JOBS_INTERVAL_SECS to drain. Previously there was no signal that the scheduler was falling behind its own schedule as num_jobs × num_tenants grew — a non-zero/climbing overrun rate means it is time to raise RELATA_JOBS_MAX_PARALLEL (see above).


AI inference

Relata v3 does not configure text-completion providers in the engine. Keep provider URLs, credentials, timeouts, and model selection in your application; see the natural-language migration guide. RELATA_LLM_URL no longer configures a provider. The generic MCP ingest_document path now always runs its built-in rule-based identity detection when the caller supplies no entities; use an application-owned extractor and pass its entities explicitly for model-based extraction.

VariableDefaultDescription
RELATA_EMBED_URL—Canonical embedding sidecar HTTP endpoint — the var relata_intelligence::accel::default_embedder actually reads to select the real embedder used by agent-memory recall, HYBRID_SEARCH, and SIMILAR (#2667). This is a base URL, not a full route — the client appends /v1/embed for text and /embed-{modality} for media (accel.rs), so set e.g. http://localhost:8080 (an already-/v1/embed-suffixed value double-appends to /embed/embed). Relata does not embed at ingest time (the media-worker drain was removed in #5942) — this endpoint serves query-time embedding only (see embedder sidecar). Without it, the built-in CPU embedder (128-dim, deterministic) is used for queries. (RELATA_ACCEL_ENDPOINT is a deprecated alias — see the Deprecated section.)
RELATA_EMBEDDER—noop | http | onnx (onnx is recognised but hard-rejected at startup, see ADR-224 / #1833). Advisory only (#2667): has no effect on the real embedder used by recall/HYBRID_SEARCH/SIMILAR — that dispatch (relata_intelligence::accel::default_embedder) reads only RELATA_EMBED_URL/RELATA_ACCEL_ENDPOINT, never this var. Startup still validates the value (fails fast on typos/onnx) so it is safe to set, just not sufficient on its own to select a real embedder.
RELATA_EMBED_MODEL—Embedding model name.
RELATA_QUERY_EMBED_POLICYlenientQuery-time embedding policy (ADR-0309, #5941). Nothing is embedded at ingest; this governs how a HYBRID_SEARCH/RAG_RETRIEVE text query becomes a vector. lenient: use the one endpoint in RELATA_EMBED_URL, else the built-in lexical embedder; a model mismatch is only a warning on the result. strict: no lexical fallback (503 embedding-endpoint-unavailable without an endpoint or a query_vector), endpoint failure is 502, and a query/index model mismatch is 409 query-embedding-model-mismatch. A malformed value fails startup. A caller-supplied query_vector needs no endpoint under either policy. See query-time embedding.
RELATA_EMBED_API_KEY—Optional bearer token sent as Authorization: Bearer <key> on every inference-engine call (#3261). Unset = no auth header.
RELATA_EMBED_MAX_CONCURRENCY8#3261: cap on in-flight inference-engine calls (embed + rerank combined). An ingest burst behind a slow engine queues callers at this bound instead of fanning out unboundedly. Must be ≥ 1 — startup fails on 0/malformed.
RELATA_INFERENCE_FAILURE_MODEdegrade#3261: engine-down behaviour — degrade (serve lexical/RRF results, mark degraded) or fail (typed errors for inference-requiring queries). Startup fails on unrecognised values.
RELATA_INFERENCE_BREAKER_THRESHOLD5#3261: consecutive engine failures that open the circuit breaker (calls then fail fast instead of paying the full timeout). Must be ≥ 1.
RELATA_INFERENCE_BREAKER_COOLDOWN_MS10000#3261: how long the breaker stays open before a half-open probe call.
RELATA_RERANK_URL—#3262: dedicated reranker engine base URL. Falls back to RELATA_EMBED_URL / RELATA_ACCEL_ENDPOINT when unset.
RELATA_RERANK_MODEL—#3262: reranker model tag (diagnostics).
RELATA_RERANK_TOP_N50#3262: max (query, doc) pairs re-scored per rerank call — bounds the load a large fused candidate list puts on the engine. Must be ≥ 1.
RELATA_RERANK_REQUIREDfalse#3262: true makes a RERANK request return a typed error (reranker-unconfigured / reranker-unavailable, HTTP 400) instead of silently returning the un-reranked RRF order when the engine is missing or failing.
RELATA_COLBERT_ENDPOINT—#4519: optional ColBERT (late-interaction) reranker sidecar endpoint — same wire contract (POST {endpoint}/rerank), timeout, and concurrency/breaker guard as the cross-encoder sidecar (RELATA_RERANK_URL). Second-priority tier: tried only when neither RELATA_RERANK_URL nor RELATA_EMBED_URL/RELATA_ACCEL_ENDPOINT (the cross-encoder tier) is configured. Genuinely optional — absent means this tier is silently skipped, never an error.
RELATA_SPLADE_ENDPOINT—#4519: optional SPLADE (sparse-neural) reranker sidecar endpoint — same wire contract/timeout/guard as the cross-encoder sidecar. Lowest-priority tier: tried only when neither the cross-encoder nor ColBERT tiers are configured. Genuinely optional — absent means this tier is silently skipped, never an error.

Encryption and KMS

VariableDefaultDescription
RELATA_ENCRYPTION_AT_RESTON when RELATA_KMS_KEY_ARN is set, otherwise OFFEnvelope-encrypts WAL + backups only (#910). One default rule, derived from configuration (#5809): provisioning a real KMS key turns encryption on; with no key it stays off so a zero-config local install does not encrypt under the committed dev secret. An explicit true/false always wins (an empty value is an explicit false); true without a key uses the dev-secret backend and warns. Does not cover flushed Parquet segments (#2688): once a type's rows are flushed from the WAL to a Parquet segment in the object store, that segment is plaintext regardless of this setting or deployment profile — this is the durable, long-term bulk-data artifact, so a compliance control that assumes "encryption-at-rest: ON" means all persisted data is encrypted is incorrect today. See ADR-056's amendment for the tracked gap against the original per-segment-key design. Cross-node/cross-region peer replication is covered (#2701): rows accepted from a replication peer are mirrored into the encrypted object-store WAL identically to locally-originated commits, so a receiving region's object_store_wal holds replicated rows as ciphertext whenever this variable and a remote object store are both configured. The always-plaintext local wal.jsonl (#1222, unaffected by this variable on any path) still receives every row too — that file is never the encrypted artifact, on either the direct-ingest or replication path.
RELATA_KMS_LOCAL_DEVfalseSet true to allow encryption to use the committed dev-secret KMS backend when RELATA_KMS_KEY_ARN is not set. For local Docker dev/CI only — NEVER set in production. Logs a loud warning at startup (#1358). (#4943) Whether this is currently active is also persistently queryable — not just logged once at boot — via GET /admin/platform/license's security_posture.kms_dev_mode field.
RELATA_KMS_PROVIDER—KMS backend: aws | localstack | vault.
RELATA_KMS_KEY_ARN—ARN of the KMS master key used for envelope encryption. Decrypt does not pin this value as a hard KeyId constraint (#2355) — changing it to a different CMK (master-key rotation/replacement) does not orphan previously-wrapped DEKs as long as the old CMK stays enabled and IAM-reachable; see docs/operations/kms.md §"Master key rotation / replacement" for the full procedure.
RELATA_KMS_REGIONRELATA_REGIONKMS region. Defaults to RELATA_REGION when unset.
RELATA_KMS_KEY_ARN_ROTATED—Test-only: names a second CMK (distinct from RELATA_KMS_KEY_ARN) for the #[ignore]d localstack-test-gated aws_kms_decrypt_survives_master_key_rotation regression test (#2355), which proves a DEK wrapped under the first CMK still decrypts through a backend configured against this "rotated-to" one. Not read outside that test.
RELATA_KMS_REGION_ROTATEDRELATA_KMS_REGION's valueTest-only: region for the second CMK above, used by the same #2355 rotation regression test. Not read outside that test.
RELATA_TOKENIZE_KEY—32-byte hex key for format-preserving tokenization of PII fields.
RELATA_ERASURE_SIGNING_KEY—Key used to sign erasure proofs (GDPR right-to-erasure audit trail). On the open edition, an unset value derives a key from RELATA_BEARER_TOKEN (#1389) — no config needed. The documented generation command (openssl rand -hex 32) produces a 64-char hex string; when set to a value that is not valid hex, erasure_signing_key_for_profile (crates/relata-prov/src/gdpr.rs) deliberately falls back to using the raw bytes as the key (logging a loud RELATA_ERASURE_SIGNING_KEY is not valid hex — using raw bytes warning) rather than failing closed, so a pre-existing non-hex value from an older deployment is not suddenly broken (#5350). This only affects the strength/stability of the HMAC key signing erasure receipts and the durable erasure marker — it never weakens or skips the underlying tombstone/purge operation itself (gdpr_erase_subject_rows, crates/relata-cli/src/serve/gdpr.rs), which runs identically either way.
RELATA_AUDIT_HMAC_KEY—HMAC-SHA256 signing key for audit-log entries. When unset, the server falls back to the RELATA_BEARER_TOKEN bytes. There is no committed default key (a baked-in key would allow audit-log forgery, #1387); an empty key is permitted with a loud startup warning. Also used by relata audit verify for offline chain verification (FATAL-exits if unset).
RELATA_TSA_URL—RFC 3161 Time-Stamping Authority endpoint used by CommitManifest::timestamp_head to anchor the manifest chain head to an independent, third-party-verifiable time source (#1780, ADR-249). Additive to, and independent of, KMS sign_head. Opt-in: unset means no timestamp anchor and every other manifest code path is unchanged — not a startup failure (crates/relata-prov/src/tsa.rs, HttpTsaClient::from_env).
RELATA_REKOR_PUBLIC_KEY—PEM-encoded ECDSA P-256 public key trusted to verify a Sigstore Rekor transparency log's SignedEntryTimestamp (crates/relata-prov/src/supply_chain.rs::rekor_check, #2997). Required for a private/self-hosted Rekor mirror (REKOR_URL pointed anywhere other than https://rekor.sigstore.dev) — without it, the signer-identity half of Rekor verification has no trust root and fails closed. Not needed for the public Sigstore log: that key is hardcoded.

Governance and privacy

VariableDefaultDescription
RELATA_PURPOSE_MODEopenPurpose-check enforcement: open (default, ADR-125 — any non-empty purpose token is accepted and recorded for audit) | strict (only tokens pre-registered via RELATA_PURPOSES or the domain profile are accepted; others are rejected). Startup fails on any other value.
RELATA_PURPOSES—Comma-separated allowed purpose strings for this deployment.
RELATA_DOMAIN_PROFILEenterpriseDomain preset that seeds default purposes and policies: enterprise | lea | finint | security | custom. Startup fails on any other value.
RELATA_AUTH_MODEbearerAuthentication mode: bearer | mtls. none is removed — startup FATAL if set. If unset and RELATA_BEARER_TOKEN is also unset, a random token is auto-generated and printed to stderr on first run. oidc, oidc-proxy, oidc-verify and saml were removed (#5813) and make startup fail with a pointer to X-Relata-Principal.
RELATA_AUDIT_REDACT_PII—Set true to redact sensitive field values from audit log entries.
RELATA_AUDIT_FAIL_CLOSEDfalseOpt-in (#1856): when true, a request whose audit entry could not be captured (bounded channel full AND the disk-backed spill also failed — a genuine drop, not the normal spill-absorbs-it case) is refused with 503 Service Unavailable instead of being served unaudited. Default false keeps the historical fail-open behaviour (the governed action still succeeds even if its audit record could not be captured).
RELATA_CELL_POLICIES—Comma-separated Type.column=action entries defining per-column cell-masking policies (#753), e.g. Person.national_id=mask,Person.pan=tokenize,BankAccount.iban=redact. action is one of mask | redact (both replace the cell with a redacted value) | tokenize (deterministic surrogate token; requires RELATA_TOKENIZE_KEY above) | allow (explicit pass-through no-op). Not a file path and not JSON — this is an inline CSV string, parsed by relata_acl::CellPolicies::parse. Unset/empty = no masking. A malformed entry (missing =, missing ., empty type/column, or an unrecognised action) fails startup: RELATA_CELL_POLICIES is malformed — refusing to start. A tokenize action with RELATA_TOKENIZE_KEY unset also fails startup, fail-closed.
RELATA_CEDAR_POLICY_FILE—Path to a Cedar policy document (ADR-078) installed at startup as AclEngine's secondary Cedar evaluation layer via set_cedar_policy_checked (#4707). Applied after the hand-rolled ABAC layer returns Allow and can only further restrict (deny-wins) — it cannot grant what ABAC denied. Same fail-closed discipline as RELATA_CELL_POLICIES: an unreadable file, or Cedar syntax the parser rejects, refuses to start rather than silently running unrestricted or silently deny-all. Unset (the default): no Cedar secondary filter, unchanged from prior behavior.
RELATA_CONDITIONAL_POLICIES_FILE—Optional path to a strict JSON document of conditional row denials. Example: {"policies":[{"principal":"http-client","object_type":"Person","action":"read","effect":"deny","condition":{"field":"classification","op":"eq","value":"SECRET"}}]}. Supports up to 256 rules and a 1 MiB file; operators are eq, ne, gt, lt; gt/lt use numeric comparison if both strings parse as numbers and lexicographic comparison otherwise. Conditional allow, non-read actions, wildcards, unknown keys, duplicate rules, malformed identifiers, and unreadable files refuse startup. Rules restrict but never replace/create base grants. Principal matches a role ID (not user or tenant), so each rule applies across tenants using that role. Unset/blank preserves prior behavior. Enforcement applies only on server paths that attach the source-row gate; see the security coverage note before relying on it for a specific retrieval path.
RELATA_PRIVACY_DP_EPSILON—Differential-privacy epsilon (lower = more private, less accurate). Enforced by relata-query's executor on plain (non-windowed) GROUP BY aggregate queries (#190): every numeric aggregate metric in the result is perturbed with Laplace(0, sensitivity/ε) noise, sensitivity defaulting to 1.0. See docs/operations/privacy.md.
RELATA_PRIVACY_MIN_GROUP—k-anonymity threshold: GROUP BY buckets whose true membership count is below this value are dropped from the result. 0/1 disables the check. Enforced by relata-query's executor on plain (non-windowed) GROUP BY aggregate queries (#190) — a windowed (TUMBLE) GROUP BY is not yet covered. See docs/operations/privacy.md.
RELATA_REGION—Deployment region tag (used for data-sovereignty routing and KMS).
RELATA_GDPR_DSAR_PAGE_LIMIT5000Per-page cap on full source-row records GET /v1/gdpr/dsar materialises into a single response (#2463). A subject whose IdentityMention fan-out exceeds this returns "has_more": true plus a "next_cursor" token (an opaque mention_id); pass it back as the cursor query param to fetch the next page. Bounds the OOM risk of a single DSAR call for a high-fan-out identity without ever refusing to eventually return the complete Art. 15 export. Strict parse_env_u64_or per ADR-230; clamped to at least 1.
RELATA_ATTESTATION_PLATFORM—TEE attestation platform (nitro | sgx | sev).
RELATA_QUERY_QUOTA_WINDOW_SECS—Rolling-window length (seconds) for the per-principal read-cost quota (#272). The quota now refills over this window instead of being a permanent cumulative cap that locks a principal out after 10k reads.
RELATA_PHOTODNA_HAMMING10PhotoDNA/CSAM blocklist Hamming threshold for the ingest-side quarantine match (ADR-187). Default tolerates re-encode noise without over-flagging; lower = stricter.
RELATA_NEAR_DUP_HAMMINGalgo-keyedOverride the near-duplicate Hamming threshold (ADR-187). Unset keys off the algo tag (PDQ ≤ 31 / pHash ≤ 6).

ADR-0308. Relata DB has local authentication only; SSO is handled by the application layer, which asserts an end-user principal with X-Relata-Principal from a can_assert_principal service token (see Security hardening). The OIDC/SAML modes and their variables, the trusted-proxy acknowledgement and the token-registry size cap were removed (#5813); see retired variables. The token registry has no count limit.


Backup

VariableDefaultDescription
RELATA_BACKUP_DIR—Local directory for backup snapshots.
RELATA_BACKUP_REPLICA_DIR—Secondary backup replica directory (off-host).
RELATA_BACKUP_FULL_INTERVAL_SECS—Interval between full backups.
RELATA_BACKUP_INCR_INTERVAL_SECS—Interval between incremental backups.
RELATA_BACKUP_RETENTION_DAYS—Days to retain old backups before deletion.
RELATA_BACKUP_TARGET—Default object-store target URL (s3://bucket/prefix) for scheduled backups when the --target CLI argument is not passed (crates/relata-cli/src/cmd_backup.rs). Unset = no default target; the caller must supply one.

Open Knowledge Framework (OKF)

VariableDefaultDescription
RELATA_OKF_SEED—OKF seed file path for loading initial ontology entries.
RELATA_OKF_SOURCE—OKF source identifier used in provenance tagging.

Content packs (#2585)

relata pack install --file <path> copies a local binary into ~/.relata/packs/<name>/ and chmods it executable; relata pack run <name> invokes it as a native subprocess. Both fail closed by default: install requires a <path>.sha256 signature sidecar (a bare sha256 hex digest, optionally sha256:/local-sha256:-prefixed) matching the source file, and run re-verifies the installed binary's digest against the one recorded at install time before executing it.

VariableDefaultDescription
RELATA_PACK_ALLOW_UNVERIFIEDfalseExplicit, loud opt-in to install/run a pack binary with no matching signature sidecar (local/dev use only). Never bypasses an actual digest mismatch — only a missing sidecar/marker. Every code path taken under this override prints a WARNING: UNVERIFIED PACK line before proceeding; it is never silent.

Miscellaneous

VariableDefaultDescription
RELATA_ORPHAN_SWEEP_SECS3600Interval for the background orphan-blob sweep. Values below 1 are treated as 1.
RELATA_BLOB_REFCOUNT_PERSIST_INTERVAL_MS1000Debounce interval for the blob-refcount snapshot (#1082). The decrement paths (decref / delete / sweep) write the snapshot at most once per this window instead of on every op, cutting a bulk erase/sweep from O(n) writes-per-op to O(1). Increments (put_blob) always persist synchronously and ignore this, so a still-referenced blob is never at risk. 0 disables debouncing (every decrement persists immediately — the pre-#1082 behaviour). A crash inside the window can only lose a decrement, leaving the on-disk refcount higher than reality (a leak the orphan sweeper reclaims), never lower.
RELATA_OBJECT_PUT_TIMEOUT_SECS30Timeout for every remote object-store PUT (store/remote_io.rs:1108). Covers WAL segment flush, Parquet segment flush, manifest put, and blob put. Raise when running against a high-latency object store.
RELATA_OBJECT_PUT_MIN_BYTES_PER_SEC1048576#5983: minimum acceptable PUT throughput. A segment or manifest PUT's timeout is RELATA_OBJECT_PUT_TIMEOUT_SECS plus size / this, so a large segment on a slow link is not cut off at a fixed 30 s. 0 disables size scaling.
RELATA_OBJECT_PUT_MAX_ATTEMPTS4#5983: attempts per segment, manifest (v1, v2 shard and index) and catalog PUT. Timeouts, throttling (HTTP 429 / SlowDown) and 5xx are retried with exponential backoff (250 ms base, 10 s cap); other errors fail immediately.
RELATA_S3_CONDITIONAL_PUTetag#5978: S3 conditional-write mode. etag (default) sends If-Match / If-None-Match so manifest compare-and-swap really detects a concurrent writer (AWS S3, MinIO, Cloudflare R2, Ceph RGW). off disables it for a backend that rejects those headers; Relata then falls back to unconditional overwrite, so run exactly one writer on that bucket.
RELATA_READINESS_PROBE_TIMEOUT_MS2000#5984: per-step timeout of the /health/ready object-store probe (LIST, then a PUT+DELETE of the scratch key _relata_health/readiness-probe every 30 s). Three consecutive failed probes are needed before readiness drops, and it recovers on the next success. A bucket that lists but refuses writes reports remote-backend-write-denied.
RELATA_FLUSH_FAILURE_UNREADY_THRESHOLD5#5983: consecutive failed background flushes before /health/ready returns remote-flush-failing (about five minutes at the 60 s cadence). Clears on the next successful flush. 0 disables the gate. Cumulative failures are exported as relata_flush_failures_total.
RELATA_STORE_GUARD_IO_BUDGET_SECS600#5577 (from #5517's lock graph): total wall-clock a serve-layer background task may hold a store guard across remote I/O — the 60 s flusher's flush_to_remote, the seal-policy task, the feature flush, and StoreHydrator's partition hydrate/peer-ingest. Per-op timeouts (RELATA_OBJECT_PUT_TIMEOUT_SECS, #5576) bound each PUT/GET but not the whole hold; this bounds the hold so a degraded-but-progressing remote cannot block every store writer (for a write guard, every reader) indefinitely. On expiry the guard is dropped and the task retries on its next cycle (content-addressed PUTs make the retry idempotent). Parsed strictly (ADR-230) — a non-integer value fails startup.
RELATA_LOG_TARGETS—Per-module log-level override via EnvFilter directives, e.g. relata_storage=debug,relata_query=warn. Overrides RELATA_LOG_LEVEL for the named crates (#67, ADR-136).

Deprecated / removed

Retired variables are listed on Retired environment variables.

VariableStatusReplacement
RELATA_ACCEL_ENDPOINTDeprecated alias → RELATA_EMBED_URL⚠ still read at crates/relata-intelligence/src/accel.rs:361,476,598, crates/relata-cli/src/serve.rs:19790 (SSRF guard), crates/relata-cli/src/serve.rs:20587 — removal tracked separately.
RELATA_ALERT_MIN_SEVERITYmediumMinimum severity for webhook alert delivery (low, medium, high, critical). Alerts below this are stored but not pushed.
RELATA_ALERT_WEBHOOKS—Comma-separated webhook URLs for alert delivery (PagerDuty/Slack/email gateway). System-level fallback; tenant-specific rules via NotificationRule.
RELATA_CACHE_RAM_MBNever existedThe Parquet segment cache (relata-cache) has no size-override env var — its budget is adaptively sized from detected RAM (#952, see crates/relata-cli/src/resource.rs, docs/src/guides/cache-architecture.md). RELATA_STORE_MAX_RAM_MB is a different subsystem's knob (row-store RAM budget, not this cache) — do not follow it expecting to size the segment cache.
RELATA_INGEST_QUEUE_CAPACITYRenamedUse RELATA_INGEST_QUEUE_MAX_BYTES. The old name appears in diagnostic JSON only and is not read from the environment.

The Linux memory watchdog also sets relata_memory_pressure to 1 at 90% of the effective memory limit. Shared query admission and HTTP ingestion then return retryable 503 responses; admission resumes below 80%. Existing work continues. Health checks and task polling remain available. Sampling cannot prevent every allocation spike; this is additional backpressure, not a hard RSS ceiling. Disabling the watchdog disables these automatic updates. Other platforms currently have no live memory sample.

Cgroup v2 pressure uses the working set (memory.current - inactive_file), so reclaimable file cache from sustained WAL/segment writes does not by itself latch ingestion closed.