HelixDB Docs

Guide

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

application
   │ POST /v2/query
   ▼
gateway
   ├── read request ──► reader
   └── write request ─► writer
                         │
                         ▼
                    object storage

Connect and send a request

let client = helix_db::Client::new(Some("https://cluster.helix-db.com"))?
    .with_api_key(Some("hx_your_api_key"));

const client = Client
  .server("https://cluster.helix-db.com")
  .withApiKey("hx_your_api_key");

client, err := helix.NewClient(
	"https://cluster.helix-db.com",
	helix.WithAPIKey("hx_your_api_key"),
)

client = Client(
    "https://cluster.helix-db.com",
    api_key="hx_your_api_key",
)

Each client sends the same operation-tree request body:

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

Architecture

Understand readers, the writer, storage, and routing.

Guarantees

Review transaction and durability behavior.

Security

Handle authentication and tenant isolation.

Cloud CLI workflow

Authenticate and connect a project.

Start Here

Operate

Connect to Helix Cloud

Request flow

Connect and send a request

Routing controls

Query warming

Next steps

Architecture

Guarantees

Security

Cloud CLI workflow

​Request flow

​Connect and send a request

​Routing controls

​Query warming

​Next steps

Architecture

Guarantees

Security

Cloud CLI workflow

Request flow

Connect and send a request

Routing controls

Query warming

Next steps