HelixDB Docs

Reference

For the complete documentation index optimized for AI agents, see llms.txt.

Send a dynamic query to POST /v2/query on a local or Helix Cloud instance. You can supply the query as a raw JSON request (--file/--json) or write it in the TypeScript DSL (-e/--ts/--ts-file) and let the CLI build the request for you.

Usage

helix query [INSTANCE] (--file <REQUEST.json> | --json '<JSON>' | -e '<TS>' | --ts-file <QUERY.ts>) [OPTIONS]

Provide exactly one input: a JSON request (--file or --json) or a TypeScript DSL expression (-e/--ts or --ts-file). The four input flags are mutually exclusive.

Arguments

Argument	Description
`INSTANCE`	Instance name from `helix.toml`. Defaults to `dev` if omitted.

Available flags

Exactly one input flag is required (--file, --json, -e/--ts, or --ts-file).

Flag	Type	Required	Description	Default
`-f`, `--file`	Path	One input required	JSON request body file.	—
`--json`	String	One input required	Inline JSON request body.	—
`-e`, `--ts`	String	One input required	TypeScript DSL expression, evaluated locally to build the request (like `mysql -e`). See TypeScript DSL input.	—
`--ts-file`	Path	One input required	Path to a `.ts` file containing a TypeScript DSL expression.	—
`--warm`	Boolean	No	Send the read as a cache-warming call (`X-Helix-Warm: true`). Helix Cloud fans out and returns `204 No Content`; standalone local instances warm one process and may return the normal query body. Read requests only.	`false`
`--host`	String	No	Override the host for local instances.	`localhost`
`--port`	Number	No	Override the port for local instances.	`[local.<instance>] port` (default `6969`)
`--compact`	Boolean	No	Print compact JSON instead of pretty-printed JSON.	`false`

Request body

The JSON request must include:

request_type — lowercase "read" or "write". Anything else is rejected with request_type must be lowercase 'read' or 'write'.
query_name — optional top-level query name for gateway logs and query diagnostics. Use exactly query_name; name and queryName are not accepted aliases. Missing or null falls back to __dynamic__.
query — exactly one typed read or write batch containing entries and returns. Missing query is rejected with dynamic query request must include query.
parameters and parameter_types — optional typed runtime values and their schemas.

helix init local scaffolds examples/request.json with a runnable read request:

{
  "request_type": "read",
  "query_name": "node_count",
  "query": {
    "read": {
      "entries": [
        {
          "query": {
            "name": "node_count",
            "root": {
              "count": {
                "input": {
                  "nodes_where": {
                    "predicate": {
                      "eq": {
                        "left": { "property": "$label" },
                        "right": { "constant": { "string": "User" } }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      ],
      "returns": ["node_count"]
    }
  }
}

Every traversal root must contain a valid source before an operation such as count. Use --file for checked-in or reusable requests, and --json for quick one-off requests from a shell. Quote inline JSON so your shell passes it as one argument.

Query warming

--warm sends the same read body with X-Helix-Warm: true. Helix Cloud fans the request out to every eligible database backend and discards their response bodies. The command succeeds silently on 204 No Content after at least one backend succeeds; partial backend failure does not fail the warm-up. If every target fails, the gateway returns the normal deterministic error. A standalone local instance warms its single process; the v0.0.4 runtime returns 200 OK with the normal query body. A managed cluster with no eligible warming target returns 503 Service Unavailable. Warm writes are rejected with 400 Bad Request before backend execution. At the HTTP/SDK layer, combine X-Helix-Warm: true with X-Helix-Require-Writer: true when only the authoritative writer should be warmed. Authentication, read rate limits, retries, and normal query timeouts still apply.

TypeScript DSL input

Instead of hand-writing JSON, you can pass a TypeScript DSL expression and let the CLI build the request — the same way mysql -e runs SQL from the shell:

# Inline expression with -e / --ts
helix query dev -e 'readBatch().varAs("c", g().nWithLabel("User").count()).returning(["c"])'

# Or from a .ts file
helix query dev --ts-file queries/count_users.ts

How it works:

The expression must evaluate to a readBatch() or writeBatch() builder. g, readBatch, writeBatch, defineParams, and param are auto-imported and already in scope — you write only the expression, no imports.
The CLI evaluates it locally with Node using the forthcoming v3 @helix-db/helix-db SDK, calls .toQueryJson(), and posts the resulting operation-tree request to /v2/query. The builders are pure (no I/O), so no instance needs to be running to build the request — only to run it. There is no separate compile step.
request_type is inferred automatically from whether you used readBatch() or writeBatch().

Requirements:

Node.js 20+ on PATH (npm ships with it). On first use the CLI installs the SDK once into its cache directory; later runs reuse it.
For inline -e use, write a single expression with no TypeScript type annotations (it is evaluated as an expression, not compiled). Put more elaborate queries in a --ts-file.

If Node is missing, the CLI tells you to install Node 20+ or fall back to --json/--file. For the full DSL surface, see the helix-query-typescript skill.

Validation rules

Rule	Error
`request_type` is missing	`dynamic query request must include request_type`
`request_type` is not lowercase `read` or `write`	`request_type must be lowercase 'read' or 'write'`
`query_name` is blank or whitespace-only	`query_name must be non-empty when provided`
`name` or `queryName` is used instead of `query_name`	Invalid request body / unknown field
`query` is missing	`dynamic query request must include query`
`--warm` is used with a write request	`--warm is only valid for read requests`
Neither `--file` nor `--json` is provided	Clap usage error
Both `--file` and `--json` are provided	Clap conflict error

Helix Cloud targets

For a Helix Cloud instance, helix query reads [enterprise.<instance>] in helix.toml and:

Posts to <gateway_url>/v2/query.
Sends an auth header named by query_auth_header (default Authorization) with the value read from the environment variable query_auth_env (default HELIX_API_KEY). The value is read from your shell environment or from a .env file in the project root (whichever is set), so you can keep the key out of your shell history.

If gateway_url is missing, the CLI returns:

Enterprise gateway URL is not configured for '<instance>'. Run 'helix sync <instance>' or set gateway_url in helix.toml.

If the auth env var is missing, the CLI returns Environment variable <NAME> is required for Enterprise query auth.

Connection errors

If the CLI cannot reach the instance, it reports cannot reach Helix instance '<instance>' at <endpoint> with a recovery hint tailored to the instance kind:

Local — Start it with helix start <instance> and check it with helix status <instance>. If it runs on another host/port, pass --host/--port.
Enterprise — Check the gateway_url for '<instance>' in helix.toml and your network connection. helix sync <instance> refreshes the gateway metadata from Helix Cloud.

Output

A non-empty JSON response is pretty-printed by default; pass --compact to print on a single line.
204 No Content (returned by Helix Cloud after at least one warm target succeeds) produces no output and exits successfully.
A standalone local warm read can return 200 OK; its normal JSON body is printed.
Non-2xx responses produce Query failed with HTTP <status>: <body> and exit with a non-zero status.

Examples

# Send the example request to the local 'dev' instance
helix query dev --file examples/request.json

# Warm the local process; the standalone runtime prints its normal response
helix query dev --file examples/request.json --warm

# Print compact JSON suitable for piping into jq
helix query dev --file examples/request.json --compact | jq '.node_count'

# Send an inline JSON request body
helix query dev --json '{"request_type":"read","query_name":"ad_hoc_read","query":{"read":{"entries":[],"returns":[]}},"parameters":{}}'

# Build the request from a TypeScript DSL expression instead of JSON
helix query dev -e 'readBatch().varAs("c", g().nWithLabel("User").count()).returning(["c"])'

# Target a Helix Cloud instance (requires HELIX_API_KEY in env and gateway_url in helix.toml)
helix query production --file examples/request.json

helix start — start a local instance to query against
helix sync — refresh Helix Cloud gateway/auth metadata

Using the helix CLI

CLI Command Reference

helix query

Usage

Arguments

Available flags

Request body

Query warming

TypeScript DSL input

Validation rules

Helix Cloud targets

Connection errors

Output

Examples

​Usage

​Arguments

​Available flags

​Request body

​Query warming

​TypeScript DSL input

​Validation rules

​Helix Cloud targets

​Connection errors

​Output

​Examples

​Related

Usage

Arguments

Available flags

Request body

Query warming

TypeScript DSL input

Validation rules

Helix Cloud targets

Connection errors

Output

Examples

Related