Limits

Understand Helix Cloud request rate limits and database constraints

Reference

For the complete documentation index optimized for AI agents, see 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/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/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