Reference

Commands &
HTTP API.

Exact arguments, fields, responses and defaults for the tools that ship in the evaluation preview.

The four tools and the launcher

Run commands from the extracted package directory. Paths beginning with ./bin/ select the supplied executable. All four tools accept --help, -h, --version and -V without opening a database or starting a service. Their application arguments are positional.

The database tools do not require Rust, Node, Docker or a cloud account. The optional launcher needs Python 3.10 or later:

python3 scripts/start-local-cluster.py ./my-lab --bin-dir ./bin

The launcher accepts four distinct ports between 1024 and 65535. It starts detached processes and records logs and observed process IDs. Closing its console leaves the nodes running. See how to start and stop your lab.

Every local CLI command

The CLI accepts UTF-8 strings as keys and values. Quote spaces and JSON in your shell. It does not parse JSON documents. Binary values are best read through the console's hex editor or the HTTP interface; CLI output converts non-UTF-8 bytes to display text.

./bin/polybase init ./workspace-db
./bin/polybase batch ./workspace-db put tasks/1 open put notes/1 'A first note'
./bin/polybase get ./workspace-db notes/1
./bin/polybase batch ./workspace-db put tasks/1 done delete notes/1
./bin/polybase events ./workspace-db 0 10
./bin/polybase snapshot ./workspace-db

For this fresh database, the two batches print committed 1 and committed 2; the last snapshot starts with snapshot 2. Commands return exit status 0 on success and 1 on an error. Only init creates a missing directory; valid commands can initialize an existing empty directory when opening it. Stop the console before running the CLI against its directory.

Local HTTP conventions

Start polybase-console and use the exact printed address, normally http://127.0.0.1:7340. These are the preview console's local endpoints, not a hosted SaaS API. They are useful for evaluation scripts; there is no separately distributed SDK.

./bin/polybase-console ./workspace-db 7340
# From a second terminal:
curl --http1.1 http://127.0.0.1:7340/api/health
curl --http1.1 -H 'Content-Type: application/json' \
  -H 'Origin: http://127.0.0.1:7340' \
  --data '{"key":"7461736b732f31"}' \
  http://127.0.0.1:7340/api/read

POST requests require exactly Content-Type: application/json and an Origin matching the console address, including its port. Use 127.0.0.1 consistently rather than substituting localhost. The HTTP/1.1 interface accepts ordinary Content-Length bodies; streamed bodies and Expect headers are unsupported. Each response closes the connection.

Unknown fields are rejected in the typed request bodies below. Always include required fields, even when their value is an empty string or null. JSON is just one possible value encoding: the server compares the encoded bytes you supply.

Complete local endpoint reference

Query fields

key_prefix is a hex-encoded byte prefix. Use 7461736b732f for tasks/, or "" for all keys. predicate is exactly any, equals or prefix. value is a hex string; supply "" with any. Equals compares the entire byte value, and prefix compares its starting bytes. Neither reads fields inside JSON.

curl --http1.1 -H 'Content-Type: application/json' \
  -H 'Origin: http://127.0.0.1:7340' \
  --data '{"key_prefix":"7461736b732f","predicate":"any","value":""}' \
  http://127.0.0.1:7340/api/query

Conditional write fields

reads is an array of expected entries, each containing key and value. Use null to expect an absent key. There must be one unique expected key for every mutated key. Extra expected reads may check another dependency. mutations is a nonempty array of {key,value}: a hex string inserts or replaces; null deletes. Mutation order is retained, including repeated keys. The local console accepts at most 128 expected reads and 128 mutations per request.

A condition checks bytes, not a revision number. If a value changes away and later returns to the same bytes before your submission, that condition can still succeed. See the condition model. Use a named request for an outcome you can inspect after a missing reply. The working Python example constructs a complete named request without placeholder tokens.

Reading responses correctly

A query response establishes the starting result. Poll responses contain complete transaction groups. Each group has a decimal position and a changes array. Each change has key, before and after. Null before means an insertion; null after means a deletion. A replacement has both values.

One transaction yields at most one net change per matching key, even if it writes that key several times. A whole-value no-op can produce no query change, while the cursor still advances. Empty commits therefore does not mean the returned token should be ignored. head is the prefix captured for that response, and floor is the oldest retained position.

These counters are observations, not one coordinated application snapshot or a promise about memory use. Use a query or validated read for record values.

Status codes and your next action

Local errors contain {code,message}. Check both the HTTP status and the structured code. A timeout or broken connection after submission may hide a successful write; keep the original named request.

Defaults exposed by the preview

The supplied command-line servers use their default options. There are no CLI flags for increasing these limits. Counts and logical bytes bound individual data structures; they are not hard process-memory or timing budgets.

The bundled GUARANTEES.md lists further engine bounds for versions, leases, pages and checkpoints. The implemented scope explains the practical limits.

The separate cluster-console API

The cluster console normally runs at http://127.0.0.1:7342. Every API call is POST and requires node as a decimal string, read_mode as quorum or local, and an optional minimum of null or {index,term} with decimal strings. The same exact Origin and JSON conventions apply.

curl --http1.1 -H 'Content-Type: application/json' \
  -H 'Origin: http://127.0.0.1:7342' \
  --data '{"node":"1","read_mode":"local","minimum":null}' \
  http://127.0.0.1:7342/api/health

The health call reports all configured nodes, their availability and roles, plus the selected context. It does not promise a quorum-confirmed record read. Select the observed leader explicitly for writes and quorum reads; do not assume node 1 is the leader. Node IDs are exactly 1, 2 and 3, with distinct IPv4 loopback addresses and one nonzero 16-byte hex partition identity in cluster.json. Keep that binding intact on restart.

/api/checkpoint-incremental and /api/compact are local-console routes and are not cluster-console routes. Replicated commits can return HTTP 200 with a durable non-write status such as conflict or capacity. A successful write has status=applied, wrote=true and durable=true; read the receipt rather than treating HTTP 200 alone as a mutation.

Additional cluster errors include 409 not_leader, 409 behind, 503 quorum_unavailable and 502 protocol. Keep the last applied result/cursor when a read cannot satisfy its chosen mode. A leader hint is a selection hint, not permission to replace a pending write's identity. See original-request reconciliation.