> ## 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. # Limits > Understand Helix Cloud request rate limits and database constraints
Reference
> For the complete documentation index optimized for AI agents, see [llms.txt](/llms.txt). Current constraints and practical limits. These reflect the current implementation, not fundamental architectural boundaries. ## Helix Cloud request rate limits Helix Cloud applies a distributed token bucket to `POST /v2/query`. The bucket is scoped to the authenticated Cloud database, so reads and writes from every API key, application instance, and gateway replica draw from the same allowance. | Plan | Sustained rate | Burst capacity | | ------- | ---------------------: | -------------: | | Idea | 5 requests per second | 10 requests | | Startup | 10 requests per second | 20 requests | | Growth | 20 requests per second | 40 requests | Database-specific overrides can change the sustained rate and burst capacity. The values assigned to your database take precedence over its plan limits. Each admitted query request costs one token from one shared bucket per Cloud database. ### Token-bucket behavior * A full bucket can admit requests up to its burst capacity. Tokens then refill continuously at the plan's sustained rate, up to that capacity. This is not a fixed one-second window. * One incoming request consumes one token whether it is a read, write, or cache warming request. Warming fanout and gateway retries do not consume additional tokens. * Requests rejected during authentication, gateway header validation, or outer request JSON decoding do not consume a token. Query AST and planner validation happen after admission, so those later validation failures consume one token. * The bucket is shared across API keys and gateway replicas. Rotating keys or distributing calls across connections does not create more capacity. * Burst capacity controls short-term admission, not the number of queries that can execute concurrently. Bound client concurrency separately. ### Rate-limit responses When no token is available, the gateway rejects the request before database execution: ```http theme={"languages":{"custom":["languages/helixql.json"]}} HTTP/1.1 429 Too Many Requests Content-Type: application/json Retry-After: 1 {"error":"rate_limited","msg":"rate limit exceeded"} ``` `Retry-After` is a whole number of seconds. Wait at least that long before retrying, and add jitter when many workers share the same database. The response does not currently include `RateLimit-*` or `X-RateLimit-*` limit, remaining, or reset headers. Current official SDK error objects expose the HTTP status, stable code, and diagnostic, but not response headers. Use direct HTTP or an application transport that retains headers when the exact `Retry-After` value is required; otherwise use a configured, bounded status/code-aware delay with jitter. If the gateway cannot make a safe distributed rate-limit decision, it fails closed before database execution: ```http theme={"languages":{"custom":["languages/helixql.json"]}} HTTP/1.1 503 Service Unavailable Content-Type: application/json {"error":"rate_limit_unavailable","msg":"tenant rate limit is unavailable"} ``` Retry `rate_limit_unavailable` with bounded exponential backoff and jitter. A `402` `tenant_disabled` response is an account-credit gate, and a `408` `query_timeout` response is an execution deadline; neither means the request bucket was exhausted. ### Application guidance 1. Coordinate admission across workers that target the same Cloud database. 2. Honor `Retry-After` on `rate_limited` instead of retrying immediately. 3. Use bounded exponential backoff with jitter for transient `503` responses. 4. Bound in-flight concurrency as well as request rate to avoid local queues and latency spikes. 5. Apply a separate per-user or per-workspace limiter when multiple application tenants share one Cloud database; the Helix bucket does not distinguish those application tenants. ## Data Model | Limit | Value | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Node and edge ID range | 64-bit unsigned integer (max 2^64 - 1); JSON responses encode lifecycle identifiers as decimal strings | | Property value types | boolean, integer, float, string, bytes, typed primitive arrays, generic arrays, and objects | | Nested structures | Stored object/array values are supported. Dotted-path lookup such as `metadata.externalID` works in scan-time filters, expressions, projections, `values`, filtered `valueMap`, and fallback ordering. Arrays are opaque; there is no array-index path syntax. | | Reserved property keys | `$label` (used for label-based filtering and label-scoped secondary, vector, and text indexes) | ## Vector Indexes | Limit | Value | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | | Scope | Node and edge properties | | Supported property types | Numeric array properties (`float32[]`, `float64[]`, `int64[]`) normalized to `float32` for indexing | | Tenant partitioning | Optional by configured tenant property name. Tenant-scoped searches require a tenant value. Unknown tenant partitions return no results. | | Dimension matching | Vectors must exactly match the configured index dimension | | Distance metrics | cosine, euclidean, manhattan | | Search type | Approximate nearest neighbor (ANN) | | Restricted search | Final membership is the exact current traversal stream; ranking may still use approximate index structures | ## Text Indexes | Limit | Value | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Scope | Node and edge properties | | Supported property types | Top-level `String` and `StringArray` properties. Nested object fields are not flattened for BM25. | | Unsupported values | `null` and non-string values are rejected | | Analyzer config | Preset analyzers: `standard`, `standard_stem_en`, `whitespace_lowercase` | | Term positions | Optional | | Tenant partitioning | Optional. Tenant-partitioned text indexes currently require the partition property name to be `tenant_id`, and tenant-scoped searches require a tenant value. | ## Secondary Indexes | Limit | Value | | ---------------- | ---------------------------------------------------------------------------------------------------------- | | Equality indexes | Supported on top-level node and edge properties. Nested dotted paths are scan-only in V1. | | Range indexes | Supported on top-level numeric and string properties. Nested dotted paths are scan-only in V1. | | Encoding | Range indexes use lexicographic string encoding. Values must be encoded consistently for correct ordering. | ## Queries | Limit | Value | | ----------------- | ---------------------------------------------------------------------------------- | | Query model | Dynamic queries | | Query language | SDK DSLs or dynamic JSON AST | | Transaction scope | One transaction per query invocation | | Request envelope | One `read` or `write` operation-tree batch with named entries and explicit returns | ## Index lifecycle | Limit | Value | | ---------------- | --------------------------------------------------------------------------------- | | Activation | Asynchronous and atomic after scan, catch-up, and validation | | Progress | Monotonic entity/byte/operation counters; no percentage or total-work estimate | | Controls | Poll all operations; retry blocked operations; abort eligible constructing builds | | Memory reporting | Cache and batch budgets do not constitute a hard process-RSS cap | ## Embedded runtime | Limit | Value | | ------------------- | ------------------------------------------------------- | | Storage sources | In-memory, local disk, and S3-compatible object storage | | Handle modes | Writer or read-only | | Server options | Gateway headers and routing options are rejected | | Packaging | Install the SDK and its embedded runtime package | | Cache configuration | Fixed when the handle opens |