Skip to main content
For the complete documentation index optimized for AI agents, see llms.txt.
Helix Cloud separates deployment-time operations from runtime query execution. This boundary keeps the system easier to scale, secure, and operate.

​
End-to-End Workflow

​
Authoring Workflow

Queries are authored as a single queries.json artifact — graph traversals, property filters, vector searches, text searches, and mutations all expressed as JSON. A single query can chain multiple traversals, apply filters, and combine graph, vector, and text operations within one transaction. You can build queries.json with the Rust, TypeScript, or Python DSL. Queries are the only artifact that moves from development to production. There is no schema migration step, no ORM configuration, and no SQL to manage. The data model is implicit in the queries themselves.

​
Runtime Workflow

At runtime, applications interact with Helix Cloud over HTTP.
  1. Send the query. An HTTP client POSTs a dynamic request to the gateway at POST /v1/query — the JSON query AST plus any required parameters travel in the request body, so there is nothing to deploy ahead of time.
  2. Transaction execution. The gateway routes the request to the appropriate process. The query runs inside a transaction with serializable snapshot isolation. Reads and writes within the same query see a consistent snapshot.
  3. Result delivery. Helix returns the query result as a JSON response. Reads are served by horizontally scaled readers. Writes are serialized through the single writer.

​
Dynamic Queries

Each request carries the query inline, so you never deploy a route ahead of time.
  • Send POST /v1/query.
  • Include a JSON body shaped like:
{
  "request_type": "read",
  "query_name": "user_by_username",
  "query": {
    "queries": [
      {
        "Query": {
          "name": "user",
          "steps": [
            {
              "NWhere": {
                "Eq": ["username", { "String": "Alice" }]
              }
            }
          ],
          "condition": null
        }
      }
    ],
    "returns": ["user"]
  },
  "parameters": {}
}
  • request_type must be read or write so the gateway can route the request correctly.
  • query_name is optional operational metadata for logs and query diagnostics. Use the exact top-level field query_name; missing or null falls back to __dynamic__, and blank strings are rejected.
  • query is the same JSON object that lives under read_routes.<name> or write_routes.<name> in a generated queries.json bundle.
  • parameters is optional and carries the values for the query’s named parameters.

​
Query Warming

Helix supports built-in query warming for read queries.
  • Send the normal read request to POST /v1/query with the same parameters you would use for a real read.
  • Add X-Helix-Warm: true or X-Helix-Warm: 1. The SDK clients set this for you via .warmOnly() (TypeScript), .warm_only() (Rust/Python), or helix.WarmOnly() (Go):
await client.query().warmOnly().dynamic(request).send();
  • Helix executes the query as a query warming request, discards the result body, and returns 204 No Content.
This is useful when you want to pre-populate the per-process caches that a known query touches before live traffic arrives. Important details:
  • Query warming is only supported for read queries. Warming a write query is rejected.
  • Helix sends the query warming request to all backends so every node can populate its local caches with the data fetched during query execution.
  • Query warming does not create a separate query-result cache. It warms the normal storage, vector, and text-search caches that the query touches during execution.

​
Separation of Concerns

ResponsibilityDeploy-timeRuntime
Query authoringqueries.json—
Query submission—helix query + Gateway
Query execution—Gateway + Writer/Readers
Data storage—Object storage
Caching—SSD + in-memory per process
Scaling—Auto-scaling readers

​
Local Development

For iterating locally without provisioning a full cluster, Helix ships a combined enterprise-dev image that runs a gateway and database together in a single container. See Developing with HelixDB Locally for in-memory and on-disk setups.

​
Next Steps

Querying

Traversal DSL, dynamic queries, and transactions.

Architecture

Gateway, writer, readers, object storage, and the cache hierarchy.

Data Model

Nodes, edges, properties, and the labeled multigraph model.

Developing Locally

Run the enterprise-dev image in-memory or against MinIO.