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

# Connect to Helix Cloud

> Send dynamic requests through a managed gateway

<div className="flex flex-wrap gap-2"><Badge color="blue" size="sm">Guide</Badge></div>

Helix Cloud runs a dedicated writer and horizontally scalable readers behind a routing
gateway. Applications send the same dynamic operation-tree request used in local and
embedded modes.

## Request flow

```text theme={"languages":{"custom":["languages/helixql.json"]}}
application
   │ POST /v2/query
   ▼
gateway
   ├── read request ──► reader
   └── write request ─► writer
                         │
                         ▼
                    object storage
```

## Connect and send a request

<CodeGroup>
  ```rust Rust theme={"languages":{"custom":["languages/helixql.json"]}}
  let client = helix_db::Client::new(Some("https://cluster.helix-db.com"))?
      .with_api_key(Some("hx_your_api_key"));
  ```

  ```ts TypeScript theme={"languages":{"custom":["languages/helixql.json"]}}
  const client = Client
    .server("https://cluster.helix-db.com")
    .withApiKey("hx_your_api_key");
  ```

  ```go Go theme={"languages":{"custom":["languages/helixql.json"]}}
  client, err := helix.NewClient(
  	"https://cluster.helix-db.com",
  	helix.WithAPIKey("hx_your_api_key"),
  )
  ```

  ```python Python theme={"languages":{"custom":["languages/helixql.json"]}}
  client = Client(
      "https://cluster.helix-db.com",
      api_key="hx_your_api_key",
  )
  ```
</CodeGroup>

Each client sends the same operation-tree request body:

```json JSON theme={"languages":{"custom":["languages/helixql.json"]}}
{
  "request_type": "read",
  "query_name": "user_by_username",
  "query": {
    "read": {
      "entries": [
        {
          "query": {
            "name": "user",
            "root": {
              "nodes_where": {
                "predicate": {
                  "eq": {
                    "left": { "property": "username" },
                    "right": { "constant": { "string": "Alice" } }
                  }
                }
              }
            }
          }
        }
      ],
      "returns": ["user"]
    }
  }
}
```

Keep API keys in secrets management, not source control. The JSON example is the request
body sent to `POST /v2/query`.

`query_name` is optional diagnostic metadata. The query itself remains entirely inside
the request; there is no route deployment step.

## Routing controls

SDK request builders expose advanced server-only controls:

* Require execution on the writer.
* Require a warm read.
* Choose whether a write waits for durability.

Embedded clients reject these controls because they describe distributed routing.

## Query warming

Send an ordinary read request with `X-Helix-Warm: true` to execute it on every
eligible database backend without returning the query result. The gateway returns
`204 No Content` after at least one backend succeeds, including when another target
fails. If every target fails, the normal deterministic error response is returned.

Managed clusters target database pods that are ready, running, routable, and not
quarantined. Add `X-Helix-Require-Writer: true` to target only the authoritative
writer. Authentication, read rate limits, retries, and the normal query timeout still
apply before and during fanout.

Warming populates the storage, vector, and text caches touched by the read; it does
not create a separate result cache. `X-Helix-Warm: true` or `1` enables warming;
`false` or `0` leaves the request on the ordinary query path. Invalid values and
warm write requests return `400 Bad Request`; writes are rejected before backend
execution. A managed cluster with no eligible warming target returns
`503 Service Unavailable`.

## Next steps

<CardGroup cols={2}>
  <Card title="Architecture" icon="sitemap" href="/database/helix-cloud/start-here/architecture">
    Understand readers, the writer, storage, and routing.
  </Card>

  <Card title="Guarantees" icon="shield-check" href="/database/helix-cloud/operate/guarantees">
    Review transaction and durability behavior.
  </Card>

  <Card title="Security" icon="lock" href="/database/helix-cloud/operate/security">
    Handle authentication and tenant isolation.
  </Card>

  <Card title="Cloud CLI workflow" icon="terminal" href="/cli/workflows/helix_cloud">
    Authenticate and connect a project.
  </Card>
</CardGroup>