The waratah Command

waratah is the single binary that runs everything: it starts and stops the cluster, loads data, and maintains indexes. This page explains each command by task; the exhaustive flag tables live in the CLI reference in the developer module, and any command answers --help from your terminal.

The three run modes

Mode What it is Use it when

waratah start

Spawns the storage partitions and registry as child processes and runs the query node, then daemonizes (the command returns once the server is up).

Everyday local operation; anything you want running in the background.

waratah standalone

Opens the storage engines inside the one process — no child processes, no internal gRPC — and stays in the foreground.

Quick exploration, scripted one-shots, containers.

waratah stop

Ends a running start cluster via its pidfile.

Always, to shut down cleanly.

start and standalone take the same serving options, so everything below about start applies to standalone too (minus the daemon behavior, which standalone never does).

waratah start

waratah start --load-demo --data-dir ./waratah-data

The options you will actually reach for:

Option Meaning

--data-dir DIR

Persist storage to RocksDB under this directory instead of memory.

--load-demo

Load the weather/city demo dataset before serving.

--config-dir DIR

Directory holding cluster.toml / notebooks.toml (see Configuration). Without it, the standard user then system config locations are searched.

--config PATH

Read the address table from this exact cluster.toml path.

--http ADDR

RDF4J HTTP listen address — default 127.0.0.1:8080.

--foreground

Stay attached to the terminal instead of daemonizing.

--query 'SELECT …​'

Run one SPARQL query and exit (implies --foreground; no HTTP server).

--no-http

Serve queries from an interactive terminal REPL instead of HTTP.

--debug

Log query text, timings, and client errors to debug.txt.

--with-notebooks

Enable the Jupyter service (see Jupyter Notebooks).

--default-union

Treat the default graph as the union of all graphs.

--strict-sparql

Enforce strict SPARQL 1.1 behavior (see Deviations from Spec).

The daemon, its logs, and its pidfile

Daemonized start writes its process id to {data_dir}/waratah-dev.pid (memory backend: ./waratah-dev.pid) and appends stdout/stderr to {data_dir}/logs/output.txt and error.txt (memory backend: the working directory) — storage children inherit the same redirection. --debug traces land in debug.txt, truncated fresh per start. waratah stop reads the pidfile and ends the whole tree.

waratah stop

waratah stop --data-dir ./waratah-data

--data-dir says which cluster to stop — it must match the directory the cluster was started with; without it, the working directory’s pidfile (that is, a memory-backend cluster) is used.

waratah import

waratah import data.ttl --data-dir ./waratah-data

Loads an RDF file: Turtle, TriG, N-Triples, N-Quads, or RDF/XML, plain or .gz-compressed. Existing data in the target directory is kept.

Option Meaning

--data-dir DIR

RocksDB directory to write into. Required unless --connect.

--connect

Attach to an already-running cluster instead of starting storage; load through the running compute node.

--offline

Write in-process — no child processes, no gRPC.

--compact

Force a full compaction pass after the load. Offline loads always compact (that is what lands query statistics on disk); this flag is for the online modes.

--disable-wal

Skip the write-ahead log during an offline load (faster bulk writes, no crash safety mid-load).

--timestamp MILLIS

Commit timestamp stamped on every imported quad (default: current unix milliseconds).

waratah explain

waratah explain -q 'SELECT ?s WHERE { ?s ?p ?o }' -p

Prints how a query parses and plans — parse tree or planned algebra — without needing a cluster. -q carries the query, -f picks the output format (default: S-expression), -p pretty-prints.

Maintenance commands

  • waratah catalog rebuild — rescan stored data and rebuild the named-graph catalog.

  • waratah compact --data-dir DIR [TARGET …​] — flush and compact a data directory’s storage; compact s, p, o, or registry selectively, or all of them by default.

  • waratah geo rebuild-index / waratah geo census — maintain and inspect the geospatial index (see Geospatial Data).

  • waratah temporal rebuild-index — rebuild the temporal index (see Temporal Data).

--build-info on the bare binary prints its build provenance; --version prints the version.