> ## 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.

# Working with HelixDB Cloud

export const workflowDiagram = ["┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐", "                 Deploying              ", "│                                     │", "          ┌─────────────┐              ", "│         │  Helix CLI  │─────────┐   │", "          └─────────────┘         │    ", "│               ▲          Store  │   │", "                │                 │    ", "│   ╔════════════════════╗        │   │", "    ║      Queries       ║        │    ", "│   ║    (Rust DSL)      ║        │   │       ╔════════════════════════════════╗", "    ╚════════════════════╝        │           ║           Helix Cloud          ║", "│                                 │   │       ║                                ║", "                                  │           ║                                ║", "└ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┼ ─ ┘       ║   ┌────────────────────────┐   ║", "                                  └───────────╬──▶│        Queries         │   ║", "                                  ┌───────────╬──▶│  (Stored Procedures)   │   ║", "┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┼ ─ ─ ┐     ║   └────────────────────────┘   ║", "                 Querying         │           ║                ▲               ║", "│                                 │     │     ║                │               ║", "          ┌──────────────────┐    │           ║                ▼               ║", "│         │  HTTP Client of  │    │     │     ║   ┌────────────────────────┐   ║", "          │   your choice    │────┘           ║   │        Database        │   ║", "│         └──────────────────┘          │     ║   └────────────────────────┘   ║", "                   ▲                          ╚════════════════════════════════╝", "│                  │                    │", "          ╔═══════════════════╗          ", "│         ║   Query name +    ║         │", "          ║    parameters     ║          ", "│         ╚═══════════════════╝         │", "                                         ", "└ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘"].join("\n");

export const EnterpriseDiagram = ({diagram}) => {
  return <div className="enterprise-diagram not-prose">
      <pre className="enterprise-diagram__pre">
        <code className="enterprise-diagram__code">{diagram}</code>
      </pre>
    </div>;
};

> For the complete documentation index optimized for AI agents, see [llms.txt](/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

<EnterpriseDiagram diagram={workflowDiagram} />

## 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](/database/rust-project-setup),
[TypeScript](/database/typescript-project-setup), or [Python](/database/python-project-setup) 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:

```json theme={"languages":{"custom":["languages/helixql.json"]}}
{
  "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):

<CodeGroup>
  ```ts TypeScript theme={"languages":{"custom":["languages/helixql.json"]}}
  await client.query().warmOnly().dynamic(request).send();
  ```

  ```rust Rust theme={"languages":{"custom":["languages/helixql.json"]}}
  let _: serde_json::Value = client.query().warm_only().dynamic(count_users()).send().await?;
  ```

  ```go Go theme={"languages":{"custom":["languages/helixql.json"]}}
  var out map[string]any
  err := client.Exec(ctx, CountUsers(), &out, helix.WarmOnly())
  ```

  ```python Python theme={"languages":{"custom":["languages/helixql.json"]}}
  client.query().warm_only().dynamic(request).send()
  ```
</CodeGroup>

* 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

| Responsibility   | Deploy-time    | Runtime                     |
| ---------------- | -------------- | --------------------------- |
| Query authoring  | `queries.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](/database/local-development) for in-memory and on-disk setups.

## Next Steps

<CardGroup cols={2}>
  <Card title="Querying" icon="magnifying-glass" href="/database/querying">
    Traversal DSL, dynamic queries, and transactions.
  </Card>

  <Card title="Architecture" icon="sitemap" href="/database/architecture">
    Gateway, writer, readers, object storage, and the cache hierarchy.
  </Card>

  <Card title="Data Model" icon="diagram-project" href="/database/data-model">
    Nodes, edges, properties, and the labeled multigraph model.
  </Card>

  <Card title="Developing Locally" icon="laptop-code" href="/database/local-development">
    Run the `enterprise-dev` image in-memory or against MinIO.
  </Card>
</CardGroup>