Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.helix-db.com/llms.txt

Use this file to discover all available pages before exploring further.

For the complete documentation index optimized for AI agents, see llms.txt.
Send a dynamic JSON request to POST /v1/query on a local or V2 Cloud instance.

​
Usage

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

​
Arguments

ArgumentDescription
INSTANCEInstance name from helix.toml. Defaults to dev if omitted.

​
Available flags

FlagTypeRequiredDescriptionDefault
-f, --filePathYes, unless --json is setJSON request body file.—
--jsonStringYes, unless --file is setInline JSON request body. Mutually exclusive with --file.—
--warmBooleanNoSend the request as a cache-warming call (X-Helix-Warm: true). Read requests only.false
--hostStringNoOverride the host for local instances.localhost
--portNumberNoOverride the port for local instances.[local.<instance>] port (default 8080)
--compactBooleanNoPrint 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 — the dynamic query object (same shape as read_routes.<name> / write_routes.<name> in queries.json). Missing query is rejected with dynamic query request must include query.
  • parameters — optional object of named parameters.
helix init local scaffolds examples/request.json with a runnable read request: 
{
  "request_type": "read",
  "query": {
    "queries": [
      {
        "Query": {
          "name": "node_count",
          "steps": [
            { "NWhere": { "Eq": ["$label", { "String": "User" }] } },
            "Count"
          ],
          "condition": null
        }
      }
    ],
    "returns": ["node_count"]
  },
  "parameters": {}
}
Every query must begin with a source step (for example NWhere) before any terminal aggregator like 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.

​
Validation rules

RuleError
request_type is missingdynamic query request must include request_type
request_type is not lowercase read or writerequest_type must be lowercase 'read' or 'write'
query is missingdynamic query request must include query
--warm is used with a write request--warm is only valid for read requests
Neither --file nor --json is providedClap usage error
Both --file and --json are providedClap conflict error

​
V2 Cloud targets

For a V2 Cloud instance, helix query reads [enterprise.<instance>] in helix.toml and:
  • Posts to <gateway_url>/v1/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).
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.

​
Output

  • A non-empty JSON response is pretty-printed by default; pass --compact to print on a single line.
  • 204 No Content (returned for --warm requests) produces no output and exits successfully.
  • 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

# Run the same request as a warm-up — populates per-process caches without printing output
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":{"queries":[],"returns":[]},"parameters":{}}'

# Target a V2 Cloud instance (requires HELIX_API_KEY in env and gateway_url in helix.toml)
helix query production --file examples/request.json
  • helix run — start a local instance to query against
  • helix sync — refresh V2 Cloud gateway/auth metadata