CLI Reference

The waratah binary is the developer orchestrator. Every subcommand below is defined by clap in waratah_bin/src/main.rs; run --help on any of them for the authoritative flag list.

Global

Option Meaning

--build-info

Print compile-time build provenance (workspace semver, git describe --long --tags --dirty, commit, branch, timestamps, rustc/target) and exit. --version prints the bare semver.

waratah start

Start the S/P/O partitions, the string registry, and a compute node as child processes over gRPC. The command daemonizes itself by default: it returns once the server is up (or reports "still starting" when a first-boot index auto-rebuild is running), stdout and stderr are appended to {data_dir}/logs/output.txt and error.txt — the working directory for the memory backend, which also writes its waratah-dev.pid pidfile there — and storage children inherit the same redirected streams. --debug traces go to {data_dir}/logs/debug.txt (./debug.txt for the memory backend), freshly truncated per start. --foreground keeps the process attached to the terminal instead (stderr stays stderr). --query and --no-http imply --foreground: a one-shot query’s results and the REPL need the calling terminal. Stop a daemon with waratah stop.

The pidfile is a start’s claim on its stop handle: a start refuses to run when the pidfile already names a live cluster (the file would otherwise be overwritten and the running cluster left unstoppable), while a stale pidfile from a crashed run — a dead pid — is overwritten normally. On exit a run removes the pidfile only when it still names itself.

Option Meaning

--config PATH

Five-process address table (TOML) at an explicit path. Without it, {config-dir}/cluster.toml is used when present, otherwise the 127.0.0.1:7001-7005 defaults.

--bin-dir DIR

Directory holding waratah-partition / waratah-registry; defaults to this binary’s directory.

--foreground

Stay attached to this terminal (the historical behavior). Without it the cluster daemonizes: the command returns after reporting the pid, URLs, and log paths.

--config-dir PATH

Directory where cluster.toml, notebooks.toml, and later other config files are looked up. Defaults to the platform search path — Linux ~/.config/waratah then /etc/waratah; macOS ~/Library/Application Support/waratah then /Library/Application Support/waratah; Windows %APPDATA%\waratah then %PROGRAMDATA%\waratah. Given explicitly, ONLY that directory is searched.

--data-dir DIR

Persist partitions to RocksDB under DIR/main/{s,p,o,registry} instead of memory. Daemon log files go to DIR/logs/; the pidfile to DIR/waratah-dev.pid.

--load-demo

Load the weather/city demo dataset before serving queries.

--query SPARQL

Run one SPARQL query and exit instead of starting the HTTP server. Implies --foreground.

--http ADDR

RDF4J HTTP listen address (default 127.0.0.1:8080).

--no-http

Skip the HTTP server and use the stdin SPARQL REPL instead. Implies --foreground.

--debug

Log SPARQL query text, timings, and client-facing errors: stderr in foreground mode; when daemonized, {data_dir}/logs/debug.txt (or ./debug.txt for the memory backend).

--seat-by-total-cost

Seat inner-join arms by the total seating cost instead of the default driver_cost rule (the join-seat comparator promoted to a decision; divergent seats log as join-seat-totals at debug level).

--describe-mode star|cbd|scbd

SPARQL DESCRIBE algorithm (default star).

--default-union

SPARQL default graph is the union of all named and unnamed graphs.

--strict-sparql

Strict SPARQL 1.1 adherence: gate Waratah’s documented deviations behind spec-strict behavior (currently gYear-family ordering comparisons become type errors).

--ingest-dir DIR

Staging parent for HTTP ingest. Files live in {ingest_dir}/{repository}; repository is main. Defaults to {data_dir}/ingest, otherwise ./ingest.

--spill-dir DIR

Root for query spill files (external ORDER BY runs, Grace join partitions, parked pages, DISTINCT seen-sets). Defaults to {data_dir}/spill; without a data dir, the system temp dir is used — RAM-backed (tmpfs) on many systems, with a startup warning.

--with-notebooks

Enable the Jupyter notebook service: a jupyter-server sidecar (one per compute) reverse-proxied at /jupyter, WebSocket kernel channels included. Requires the HTTP server.

--notebooks-dir DIR

Contents root for the notebook service. Defaults to {data_dir}/notebooks, otherwise ./notebooks.

--notebooks-python PATH

Python interpreter for the sidecar; skips auto-provisioning. Default: a pinned venv auto-created at {data_dir}/notebooks-venv on first start.

--notebooks-bind ADDR

Loopback bind for the notebook sidecar (default 127.0.0.1:0, engine-assigned). Also settable as bind in {config-dir}/notebooks.toml.

--notebooks-token TOKEN

Jupyter auth token (default: minted at startup).

--notebooks-cull-idle-secs N

Kernel idle culling timeout in seconds (default 3600). Also settable as cull_idle_secs in {config-dir}/notebooks.toml.

--geo-min-level / --geo-max-level / --geo-max-cells

GeoSPARQL S2 covering parameters, defaults 0 / 24 / 40 (process-local). Changing them requires waratah geo rebuild-index afterward — see the cluster-uniform caveat in the GeoSPARQL section of ARCH.md.

waratah standalone

Open S/P/O and the registry in this process — no child processes, no gRPC — and run compute in the foreground. Takes the same flags as waratah start except the spawn-only ones: no --config (there is nothing to address), no --bin-dir (nothing to locate), and no --foreground / daemonization (always foreground). The pidfile is written when --data-dir is given. See the table above for the shared flag meanings.

waratah stop

Stop a running cluster (SIGTERM via its pidfile). Storage children and the notebook sidecar go with it.

Option Meaning

--data-dir DIR

Data dir of the cluster to stop; the pidfile is {data_dir}/waratah-dev.pid. Optional: without it the working directory’s waratah-dev.pid is used — where a memory-backend daemon writes its pidfile.

waratah import

Stream an RDF file into a RocksDB data directory (or a running cluster). Formats: Turtle, TriG, N-Triples, N-Quads, RDF/XML; .gz is fine.

Option Meaning

FILE (positional)

The RDF file to load.

--data-dir DIR

RocksDB directory to write (created if missing; existing data is kept). Required unless --connect.

--timestamp N

Commit timestamp for every imported quad (default: current unix millis).

--compact

Force a full-range compaction after flush. Online: once at the end. Offline always compacts after load so statistics land in SST properties.

--offline

In-process load: no gRPC. Exclusive with --connect.

--connect

Attach to a running cluster via --config; do not spawn or kill children.

--disable-wal

Skip the write-ahead log (offline only).

--direct-sst

Ingest via SstFileWriter (offline only; not implemented yet).

--config PATH

Static five-process address table (TOML); defaults to 127.0.0.1:7001-7005.

--bin-dir DIR

Directory holding waratah-partition / waratah-registry; defaults to this binary’s directory.

waratah explain

Print SPARQL parse / Sparopt / planned algebra — no cluster required. This is the offline twin of the HTTP explain endpoint.

Option Meaning

-q, --query SPARQL

The query to optimize (SELECT, ASK, CONSTRUCT, or DESCRIBE).

-f, --format FORMAT

sse (default; parse-only Jena SSE), optimised / optimised-sparql (aliases optimized / optimized-sparql; Sparopt + VALUES-into-UNION), planned / planned-sparql (fully lowered plan), estimate (alias estimates; planned SSE plus row estimates, domains, and broadcast annotations).

-p, --pretty

Pretty-print S-expression and *-sparql output.

--default-union

SPARQL default graph is the union of all named and unnamed graphs.

--seat-by-total-cost

Seat inner-join arms by total seating cost so EXPLAIN shows the seat a server started with --seat-by-total-cost would run.

waratah catalog rebuild

Scan SPOG and write Present for each distinct named graph (skipping the default graph) into the S-axis named-graph catalog.

Option Meaning

--data-dir DIR

RocksDB data directory ({data_dir}/main/s is opened).

waratah geo rebuild-index

Wipe and recompute every O-axis S2 posting under the CURRENT coverer config. Required after changing --geo-min-level / --geo-max-level / --geo-max-cells, or after a covering algorithm change. The O partition never runs the coverer; this is the compute/offline side.

Option Meaning

--data-dir DIR

RocksDB data directory ({data_dir}/main/o is opened; blobs come from {data_dir}/main/blobs).

waratah geo census

Read-only per-level census of the O-axis S2 posting store: posting counts by cell level, envelope coverage, and the statistics histogram’s incidence mass. Use it to diagnose geo window-estimate over-counting — it is the tool that exposed the level-8 coarse-side histogram move.

Option Meaning

--data-dir DIR

RocksDB data directory ({data_dir}/main/o is opened read-only).

--window WKT

Estimate + drain-truth decomposition for one query window given as WKT (the same literal form a geof:* conjunct carries). Builds the postings-exact histogram from the live postings, runs the same estimate ladder the planner runs over the window’s merged L11 ranges, and reports it next to what the storage scan would actually fetch (candidate postings, distinct candidate terms, postings-per-term, the estimate/candidates factor). The report is ground truth: the engine’s live estimate instead reads the rolled-up (wire-trimmed) profile histogram, so compare the printed total against EXPLAIN to attribute the gap.

--geo-min-level N
--geo-max-level N
--geo-max-cells N

Coverer configuration for the window’s query covering (defaults match waratah start). Only meaningful with --window; the postings themselves were built by the config live at ingest.

waratah temporal rebuild-index

Wipe and recompute every O-axis temporal posting (partition-side walk). Required after changing the temporal covering parameters, and the manual path for what compute startup auto-triggers when the epoch is missing.

Option Meaning

--data-dir DIR

RocksDB data directory ({data_dir}/main/o is opened in-process).

--temporal-min-level N

Minimum covering node level (temporal index). Default 0.

--temporal-max-level N

Maximum covering node level (temporal index; instants bypass the covering entirely). Default 110.

--temporal-max-nodes N

Maximum nodes per interval (temporal index). Default 32.

waratah compact

Flush and compact the targets of an existing RocksDB data directory (offline).

Option Meaning

--data-dir DIR

RocksDB data directory ({data_dir}/main/{s,p,o,registry} are opened).

TARGETS…

Targets to compact (s, p, o, registry; case-insensitive). Default: all of them, sequentially.

Runtime environment variables

These are read by the engine processes at startup. The first group is operator-facing; the rest are internal tuning knobs whose authoritative documentation lives beside their definition in the crate sources.

Variable Effect

WARATAH_STORAGE_BACKEND

Selects the storage backend at runtime: unset / rocksdb (default) → RocksDB; memory → in-memory backend (fast tests, no disk).

WARATAH_DOMAIN_SEEK_UNION

Domain scans: enable the single-iterator seek-union (= 1).

WARATAH_DOMAIN_WALKS

Domain scans: parallel worker count (= <K>, K ≥ 2).

WARATAH_REGISTRY_WALKS

Registry seek walk: enable parallel worker slices (= <K>, K ≥ 2).

WARATAH_REGISTRY_WALKS_MAX

Process-wide limit on concurrently live registry seek-walk slices across all callers (values above it are clamped).

WARATAH_BLOB_CACHE_BYTES

Overrides the blob cache byte budget.

Internal tuning knobs (see the storage, partition, and compute crate sources for semantics and defaults): WARATAH_PIN_INDEX, WARATAH_WARM_CACHE, WARATAH_SCAN_ASYNC_IO, WARATAH_ITERATOR_READAHEAD_SIZE, WARATAH_RESOLVE_MULTIGET, WARATAH_RESOLVE_CACHE_ENTRIES, and the console-artifact overrides WARATAH_CONSOLE_DIST, WARATAH_CONSOLE_STUB, WARATAH_CONSOLE_MISSING_SW.