{"owner":"HelixDB","repo":"helix-db","hasSkills":true,"totalSkillsCount":3,"totalTokensCount":19184,"categories":["root-instruction"],"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md","docs/llms.txt","docs/llms-full.txt"],"skills":{"AGENTS.md":"### approach\n\n- ⁠Make invalid states unrepresentable using algebraic data types (e.g. enums).\n- ⁠Use code coverage tools to make sure unit test coverage covers every edge case. This should be easily doable if invalid states are unrepresentable.\n- Keep things modular.\n- Define clear contract boundaries for testability. Document them all, and make sure doc comment examples are ran as tests.\n- Use assertions for invariants when encoding within types is not feasible.\n- Use clippy and fix code smells reported.\n- Prefer iterators, monadic logic, and functional concepts. Where not possible for performance, document why.\n- Make invalid state unrepresentable.\n- Prefer importing modules over long lists of types. Using `module::Type` at call sites is fine, keeps names unambiguous, and reduces namespace-collision churn.\n- Be wary of things that don't scale. If you have reason to believe why it wont, report back to the user explaining why.\n- instead of if let { ... } use let Some(…) = … else { }\n- avoid over using helper functions where possible. duplicating a single line of code is clearer than polluting with helper functions. if a large piece of functionality is shared or repeated multiple times then it can be abstracted but you should favour inline code where possible. small pieces of functionality should be inlined instead of abstracted.\n- Do not stage, commit (including locally), push, publish artifacts, or trigger remote CI unless explicitly instructed. Keep work-session timestamps out of authored reports and documentation.\n- As you make changes, if it is small (e.g. single/couple line addition) or if it is critical to your implementation, make the change.\n- Clean up any temporary files or directories you create during your work (including in /private/tmp)\n- ⁠match { Example(_) => ExampleVariant } -> use derive macro for Variant and the conversions instead of littering our code with the extra types and functions\n⁠- ⁠instead of children structs holding an Arc, maybe just let them take in a &Db in every method that requires it.\n- when that's not feasible, evaluate whether passing in an Arc is fine, and if not make sure that holding an Arc won't leak the memory based on how the child is stored in parent.\n\n### Slice access\n⁠When accessing or creating slices, for every access or slice don't minify it to start..end constants, always keep the additions of offsets explicit.\nInstead of making `start` and `end` variables in the place of `const` values, use the `const` values directly, adding them up instead.\n\ne.g. you should do the following\n\n```rust\nconst PREFIX_LEN: usize = core::mem::size_of::();\nconst INDEX_PREFIX_LEN: usize = core::mem::size_of::();\nconst PROPERTY_HASH_MAX_LEN: usize = core::mem::size_of::();\nconst VALUE_HASH_MAX_LEN: usize = core::mem::size_of::();\n\nlet property_hash = slice[INDEX_PREFIX_LEN..INDEX_PREFIX_LEN + PROPERTY_HASH_MAX_LEN]\n .try_into()\n .expect(\"property hash slice is 4 bytes\");\n```\n\n### Clippy and formatting\n\nRun clippy and formatting to check for code smells and formatting issues.\n\n```bash\ncargo clippy --workspace -- -D warnings\nrustfmt --edition 2024 --check\n```\n\nyou should run formatting and clippy before finishing your work. Rust crates in this workspace use edition 2024 from their `Cargo.toml`; do not pass `--edition 2024` to `cargo clippy`, because Cargo does not accept that flag for Clippy. Use a current stable Rust toolchain with the matching Clippy component installed.\n\n### Database Key/Value Construction, Parsing, and Use\n\n- ALL database key construction, parsing, and serialisation should be done using the structs in crates/db/src/encoding/v2\n - There are structs here that make building invalid keys impossible and it ensures call sites remain standardised and improves testability\n- ALL database value construction, parsing, and serialisation should be done using the structs in crates/db/src/encoding/v2/values\n - There are structs here that make building invalid keys impossible and it ensures call sites remain standardised and improves testability\n - We are in the process of moving more values to this dir. If you notice inline value use, please either add it to crates/db/src/encoding/v2/values if it is small (e.g. single variant addition) or if it is a major change just note it down.\n\n","docs/llms.txt":"# HelixDB\n\n> HelixDB combines a property graph, approximate vector search, and BM25 full-text search behind one operation-tree query model. Requests run through Cloud, a local server, or the embedded runtime.\n\nQuickstart (local instance requires Docker or Podman):\n\nmacOS and Linux:\n```bash\ncurl -sSL \"https://install.helix-db.com\" | bash # install the helix CLI\n```\n\nWindows PowerShell:\n```powershell\nirm https://raw.githubusercontent.com/HelixDB/helix-db/main/crates/cli/install.ps1 | iex\n```\n\nThen:\n```bash\nhelix init local # scaffold helix.toml + examples/\nhelix start dev # start a local instance\nhelix query dev -e 'writeBatch().varAs(\"alice\", g().addN(\"User\", { username: \"alice\" })).returning([\"alice\"])'\nhelix query dev -e 'readBatch().varAs(\"users\", g().nWithLabel(\"User\")).returning([\"users\"])'\n```\n\nFull walkthrough: https://docs.helix-db.com/database/helix-db/start-here/quickstart\n\n## HelixDB developer resources\n- [HelixDB HTTP API documentation](https://docs.helix-db.com/database/helix-db/query-guides/http-api): Request contract, authentication, headers, responses, and examples for `POST /v2/query`.\n- [HelixDB OpenAPI specification](https://www.helix-db.com/openapi.json): OpenAPI 3.1 JSON for the public HelixDB HTTP API.\n- [HelixDB authentication guide for agents](https://www.helix-db.com/auth.md): Supported API-key and OAuth surfaces, with links to machine-readable discovery metadata.\n- [HelixDB unified MCP endpoint](https://docs.helix-db.com/database/helix-cloud/connect/mcp): Connect human OAuth, scoped service credentials, and agent registrations to authorized tools on one endpoint.\n- [HelixDB AI Catalog](https://www.helix-db.com/.well-known/ai-catalog.json): ARD catalog of HelixDB agent resources.\n\n## HelixDB — Start Here\n- [Introduction](https://docs.helix-db.com/database/helix-db/start-here/introduction): HelixDB is a graph database with native vector and full-text search, built on object storage — Page type: Concept\n- [Get started](https://docs.helix-db.com/database/helix-db/start-here/quickstart): Initialize HelixDB, start a local instance, run the generated query, and stop it — Page type: Tutorial\n- [Deployment options](https://docs.helix-db.com/database/helix-db/start-here/run-modes): Compare Cloud, local server, and embedded execution — Page type: Concept\n- [Local server](https://docs.helix-db.com/database/helix-db/start-here/local-development/local-server): Start HelixDB locally with memory, a persistent directory, or S3-compatible storage — Page type: Guide\n- [Embedded database](https://docs.helix-db.com/database/helix-db/start-here/local-development/embedded-database): Open HelixDB directly inside your process with explicit storage and cache settings — Page type: Guide\n- [SDK setup](https://docs.helix-db.com/database/helix-db/start-here/sdk-setup/overview): Choose a HelixDB SDK and connect it to a local or Cloud server — Page type: Guide\n- [Rust SDK](https://docs.helix-db.com/database/helix-db/start-here/sdk-setup/rust-project-setup): Build typed HelixDB queries and execute them over HTTP or an embedded engine — Page type: Guide\n- [TypeScript SDK](https://docs.helix-db.com/database/helix-db/start-here/sdk-setup/typescript-project-setup): Build typed HelixDB requests for Node.js applications — Page type: Guide\n- [Go SDK](https://docs.helix-db.com/database/helix-db/start-here/sdk-setup/go-project-setup): Build and execute HelixDB requests with ordinary Go functions — Page type: Guide\n- [Python SDK](https://docs.helix-db.com/database/helix-db/start-here/sdk-setup/python-project-setup): Build HelixDB requests with idiomatic synchronous and asynchronous Python clients — Page type: Guide\n- [Roadmap](https://docs.helix-db.com/database/helix-db/start-here/roadmap): What we're building and what's coming next — Page type: Reference\n- [Release notes](https://docs.helix-db.com/database/helix-db/start-here/release-notes): New features and changes in HelixDB, Helix Cloud, the SDKs, and the CLI — Page type: Reference\n\n## Core Concepts\n- [Data model](https://docs.helix-db.com/database/helix-db/core-concepts/data-model): Understand how HelixDB represents entities, relationships, properties, and indexes — Page type: Concept\n- [Build and run a query](https://docs.helix-db.com/database/helix-db/core-concepts/overview): Build a small write query operation by operation, then read its request and response — Page type: Tutorial\n\n## Query Guides\n- [Writing data](https://docs.helix-db.com/database/helix-db/query-guides/writing-data): Create, update, connect, and remove entities in one typed write batch — Page type: Guide\n- [Reading data](https://docs.helix-db.com/database/helix-db/query-guides/reading-data): Start a traversal from IDs, labels, properties, or previous query results — Page type: Guide\n- [Traverse relationships](https://docs.helix-db.com/database/helix-db/query-guides/traversals): Follow edges, retain row-local bindings, and control duplicate paths — Page type: Guide\n- [Filtering](https://docs.helix-db.com/database/helix-db/query-guides/filtering): Narrow traversal streams with predicates and exact search candidate sets — Page type: Guide\n- [Shape query results](https://docs.helix-db.com/database/helix-db/query-guides/projections): Return properties, computed values, aggregates, and correlated binding rows — Page type: Guide\n- [Bind typed query parameters](https://docs.helix-db.com/database/helix-db/query-guides/parameters): Keep the operation tree stable while request values change — Page type: Guide\n- [Branch, repeat, and condition queries](https://docs.helix-db.com/database/helix-db/query-guides/advanced): Compose sub-traversals and gate named entries without leaving one transaction — Page type: Guide\n- [Query HelixDB with Cypher](https://docs.helix-db.com/database/helix-db/query-guides/cypher): Run Cypher statements beside native queries, and see which parts of openCypher HelixDB supports — Page type: Guide\n- [Secondary indexes](https://docs.helix-db.com/database/helix-db/query-guides/secondary-indexes): Accelerate equality, uniqueness, and ordered property lookups — Page type: Guide\n- [Vector indexes](https://docs.helix-db.com/database/helix-db/query-guides/vector-indexes): Create vector indexes and run nearest-neighbor search — Page type: Guide\n- [Text indexes](https://docs.helix-db.com/database/helix-db/query-guides/text-indexes): Create BM25 indexes and run ranked full-text search — Page type: Guide\n- [Prefiltered search](https://docs.helix-db.com/database/helix-db/query-guides/prefiltering): Rank only the nodes or edges a traversal reaches with vector or BM25 search — Page type: Guide\n- [Search consistency](https://docs.helix-db.com/database/helix-db/query-guides/search-consistency): Choose whether vector and text searches include unpublished index work, and handle index backpressure — Page type: Guide\n- [HelixDB HTTP API and OpenAPI specification](https://docs.helix-db.com/database/helix-db/query-guides/http-api): Call the HelixDB v2 query endpoint and discover its machine-readable OpenAPI 3.1 contract — Page type: Reference\n- [Query error reference](https://docs.helix-db.com/database/helix-db/query-guides/error-handling): Branch on stable error codes, apply retry rules, and look up every HelixDB query error — Page type: Reference\n- [Troubleshoot HelixDB](https://docs.helix-db.com/database/helix-db/query-guides/troubleshooting): Diagnose query, index, vector, embedded, and local runtime failures — Page type: Troubleshooting\n\n## Helix Cloud — Start Here\n- [Get started with Helix Cloud](https://docs.helix-db.com/database/helix-cloud/start-here/using-the-cloud): Sign in, create a workspace and choose its plan, provision a database, and test the connection — Page type: Tutorial\n- [Connect to Helix Cloud](https://docs.helix-db.com/database/helix-cloud/start-here/working-with-enterprise): Connect an SDK or HTTP client to a Helix Cloud database and control request routing — Page type: Guide\n- [Architecture](https://docs.helix-db.com/database/helix-cloud/start-here/architecture): How the Helix Cloud gateway, writer, readers, caches, and object storage serve reads and writes — Page type: Concept\n\n## Connect and automate\n- [Helix Cloud MCP](https://docs.helix-db.com/database/helix-cloud/connect/mcp): Connect users and agents to the unified Helix Cloud MCP endpoint — Page type: Reference\n\n## Operate\n- [Security](https://docs.helix-db.com/database/helix-cloud/operate/security): Authenticate requests, handle API keys, and review encryption and enterprise security features — Page type: Reference\n- [Multi-tenancy](https://docs.helix-db.com/database/helix-cloud/operate/multi-tenancy): Isolate application tenants with row-level scoping and tenant-partitioned search indexes — Page type: Guide\n- [Guarantees](https://docs.helix-db.com/database/helix-cloud/operate/guarantees): Atomicity, isolation, durability, index activation, and read-after-write behavior — Page type: Reference\n- [Limits](https://docs.helix-db.com/database/helix-cloud/operate/limits): Understand Helix Cloud request rate limits and database constraints — Page type: Reference\n- [Tradeoffs](https://docs.helix-db.com/database/helix-cloud/operate/tradeoffs): What the Helix Cloud architecture is optimized for, and where another system may fit better — Page type: Concept\n- [Helix Cloud gateway errors](https://docs.helix-db.com/database/helix-cloud/operate/error-handling): Use stable Helix Cloud error codes, HTTP statuses, and SDK error metadata — Page type: Reference\n\n## Helix Foundry — Start Here\n- [What is Helix Foundry?](https://docs.helix-db.com/foundry/start-here/introduction): Helix Foundry connects your company's data, drafts an ontology across it, and loads it into a Helix database you can explore — Page type: Concept\n- [Helix Foundry quickstart](https://docs.helix-db.com/foundry/start-here/quickstart): Sign in, connect a source, generate an ontology, load it into a Helix database and explore it — Page type: Tutorial\n- [Workspaces and navigation](https://docs.helix-db.com/foundry/start-here/workspaces-and-navigation): Sign in to Helix Foundry, choose or create a workspace, and find your way with the sidebar, search and themes — Page type: Guide\n\n## Data\n- [Connect and sync data](https://docs.helix-db.com/foundry/data/connect-data): Add a source to a Helix Foundry workspace, test its credential, sync its tables and read what each table holds — Page type: Guide\n- [Connectors](https://docs.helix-db.com/foundry/data/connectors): What each Helix Foundry source needs, the permissions to give it, the tables it syncs and its limits — Page type: Reference\n\n## Ontologies\n- [Create an ontology](https://docs.helix-db.com/foundry/ontologies/create-an-ontology): Create a Helix Foundry ontology on an existing Helix database or a new one, and read its overview — Page type: Guide\n- [Generate and version an ontology](https://docs.helix-db.com/foundry/ontologies/generate-and-version): Ask Helix Foundry's agent to draft an ontology from your synced tables and documents, review each version, and choose the current one — Page type: Guide\n- [Upload documents](https://docs.helix-db.com/foundry/ontologies/documents): Upload Markdown and text files to a Helix Foundry ontology so generations and loads read the names and facts they hold — Page type: Guide\n- [Load data into a Helix database](https://docs.helix-db.com/foundry/ontologies/load-data): Write an ontology's current version, your synced tables and your documents into its Helix database, and manage its loads — Page type: Guide\n\n## Explore\n- [Explore the graph](https://docs.helix-db.com/foundry/explore/explorer): Read what a Helix Foundry load wrote as a graph: search, expand, inspect, pick a load and compare two — Page type: Guide\n- [Records and entities](https://docs.helix-db.com/foundry/explore/records-and-entities): Read a Helix Foundry load as tables by type, open a record's links and sources, and see everything about one entity — Page type: Guide\n\n## Ask\n- [Ask questions of your data](https://docs.helix-db.com/foundry/ask/ask-questions): Ask a Helix Foundry ontology questions in plain language and get answers that cite where they came from. Coming soon. — Page type: Guide; Status: Preview\n\n## Workspace\n- [Members and roles](https://docs.helix-db.com/foundry/workspace/members-and-roles): See who is in a Helix Foundry workspace, invite people, and what owners, admins and members can do — Page type: Guide\n- [Plans and billing](https://docs.helix-db.com/foundry/workspace/plans-and-billing): Compare Helix Foundry Free, Pro and Max, upgrade a workspace, switch tiers, cancel, resume and manage payment — Page type: Guide\n\n## Reference\n- [Helix Foundry limits](https://docs.helix-db.com/foundry/reference/limits): Every Helix Foundry limit in one place: syncs, generations, documents, loads, spending and reads — Page type: Reference\n- [Troubleshooting Helix Foundry](https://docs.helix-db.com/foundry/reference/troubleshooting): What Helix Foundry's sign-in, connection, sync, generation, database and load messages mean, and what to do — Page type: Troubleshooting\n\n## Using the helix CLI\n- [Getting started with HelixDB CLI](https://docs.helix-db.com/cli/getting-started): Install the CLI, run locally, or link a WorkOS-authenticated Cloud database — Page type: Tutorial\n- [Local development](https://docs.helix-db.com/cli/workflows/local): Run a local instance and iterate on dynamic JSON queries — Page type: Guide\n- [Helix Cloud CLI workflow](https://docs.helix-db.com/cli/workflows/helix_cloud): Authenticate, link, query, and manage Cloud resources — Page type: Guide\n- [CLI configuration](https://docs.helix-db.com/cli/configuration): Project linkage and WorkOS session files — Page type: Reference\n- [CLI troubleshooting](https://docs.helix-db.com/cli/troubleshooting): Recover local and WorkOS-authenticated Cloud CLI operations — Page type: Troubleshooting\n\n## CLI Command Reference\n- [CLI command reference](https://docs.helix-db.com/cli/command-reference): Every Helix CLI command, grouped by what it manages — Page type: Reference\n- [helix add](https://docs.helix-db.com/cli/command-reference/add): Add a local instance or a Helix Cloud database link to an existing project — Page type: Reference\n- [helix auth](https://docs.helix-db.com/cli/command-reference/auth): Log in to Helix Cloud, check the session, or log out — Page type: Reference\n- [helix api](https://docs.helix-db.com/cli/command-reference/api): Call a Helix Cloud API endpoint with your CLI login session — Page type: Reference\n- [helix chef](https://docs.helix-db.com/cli/command-reference/chef): Bootstrap a first HelixDB app with a coding agent — Page type: Reference\n- [helix cluster](https://docs.helix-db.com/cli/command-reference/cluster): List and inspect Helix Cloud clusters and their active indexes — Page type: Reference\n- [helix cypher](https://docs.helix-db.com/cli/command-reference/cypher): Execute or explain one Cypher statement against a local instance — Page type: Reference\n- [helix database](https://docs.helix-db.com/cli/command-reference/database): Discover and manage Helix Cloud databases and application keys — Page type: Reference\n- [helix delete](https://docs.helix-db.com/cli/command-reference/delete): Remove an instance from helix.toml and clean up its local state — Page type: Reference\n- [helix doctor](https://docs.helix-db.com/cli/command-reference/doctor): Check an instance's setup: runtime, storage, disk cache, memory, and index use — Page type: Reference\n- [helix explorer](https://docs.helix-db.com/cli/command-reference/explorer): Browse a running local instance in the graph Explorer — Page type: Reference\n- [helix feedback](https://docs.helix-db.com/cli/command-reference/feedback): Open a pre-filled feedback issue for the Helix team — Page type: Reference\n- [helix init](https://docs.helix-db.com/cli/command-reference/init): Create a local project or a WorkOS-authenticated Cloud link — Page type: Reference\n- [helix logs](https://docs.helix-db.com/cli/command-reference/logs): View local logs or recent Cloud query errors — Page type: Reference\n- [helix metrics](https://docs.helix-db.com/cli/command-reference/metrics): Configure CLI telemetry and usage metrics collection — Page type: Reference\n- [helix project](https://docs.helix-db.com/cli/command-reference/project): Discover, manage, and link Helix Cloud projects — Page type: Reference\n- [helix prune](https://docs.helix-db.com/cli/command-reference/prune): Remove Helix-owned local containers, volumes, and instance state — Page type: Reference\n- [helix query](https://docs.helix-db.com/cli/command-reference/query): Execute a direct Helix v3 query against a local instance or a Cloud database — Page type: Reference\n- [helix restart](https://docs.helix-db.com/cli/command-reference/restart): Restart a background local instance — Page type: Reference\n- [helix skills](https://docs.helix-db.com/cli/command-reference/skills): Install, refresh, and list the Helix agent skills — Page type: Reference\n- [helix start](https://docs.helix-db.com/cli/command-reference/start): Start a local instance in the background or foreground — Page type: Reference\n- [helix status](https://docs.helix-db.com/cli/command-reference/status): Inspect local runtime or current Cloud database state — Page type: Reference\n- [helix stop](https://docs.helix-db.com/cli/command-reference/stop): Stop a background local instance and remove its containers — Page type: Reference\n- [helix service-credential](https://docs.helix-db.com/cli/command-reference/service-credential): Manage workspace-owned credentials for headless HTTP API and unified MCP clients — Page type: Reference\n- [helix shell](https://docs.helix-db.com/cli/command-reference/shell): Run line-oriented Helix v3 JSON requests — Page type: Reference\n- [helix update](https://docs.helix-db.com/cli/command-reference/update): Update the Helix CLI and refresh installed agent skills — Page type: Reference\n- [helix workspace](https://docs.helix-db.com/cli/command-reference/workspace): Discover WorkOS workspace memberships — Page type: Reference\n\n## Learning center\n- [Learning center](https://docs.helix-db.com/learn/index): Plain-language answers about graph databases, vector search, full-text search, AI agent memory, and modern database architecture. — Page type: Concept\n\n## Graph databases\n- [What is a graph database?](https://docs.helix-db.com/learn/graph-databases/what-is-a-graph-database): A graph database stores things as nodes and the connections between them as edges, and answers questions by following those connections. — Page type: Concept\n- [What is the difference between a graph database and a relational database?](https://docs.helix-db.com/learn/graph-databases/graph-vs-relational-database): A relational database keeps data in tables and rebuilds connections with joins; a graph database stores connections as edges and follows them. — Page type: Concept\n- [What is a knowledge graph?](https://docs.helix-db.com/learn/graph-databases/what-is-a-knowledge-graph): A knowledge graph is a connected collection of facts about things and how they relate, organized by a schema so software can query and cite it. — Page type: Concept\n- [What is a property graph?](https://docs.helix-db.com/learn/graph-databases/what-is-a-property-graph): A property graph stores data as labeled nodes and edges with key-value properties on both, so a relationship can carry its own details. — Page type: Concept\n- [What is the difference between a property graph and RDF?](https://docs.helix-db.com/learn/graph-databases/property-graph-vs-rdf): A property graph stores nodes and edges that carry their own properties; RDF stores every fact as a three-part triple named by global IDs. — Page type: Concept\n\n## Vector search\n- [What is vector search?](https://docs.helix-db.com/learn/vector-search/what-is-vector-search): Vector search finds results by meaning instead of exact words, by comparing embeddings: lists of numbers that capture what content is about. — Page type: Concept\n- [What are vector embeddings?](https://docs.helix-db.com/learn/vector-search/what-are-vector-embeddings): A vector embedding is a list of numbers, produced by a machine learning model, that captures what a piece of content means. — Page type: Concept\n- [What is a vector database?](https://docs.helix-db.com/learn/vector-search/what-is-a-vector-database): A vector database stores embeddings, lists of numbers that capture what content means, and quickly finds the ones most similar to a query. — Page type: Concept\n- [What is HNSW?](https://docs.helix-db.com/learn/vector-search/what-is-hnsw): HNSW is a vector search index that links each vector to its nearest neighbors in layers, so a search can hop quickly to similar items. — Page type: Concept\n- [What is filtered vector search?](https://docs.helix-db.com/learn/vector-search/filtered-vector-search): Filtered vector search finds the most similar items among only those that pass a rule, such as a tenant, a date range, or a permission check. — Page type: Concept\n- [What is the difference between cosine, Euclidean, and Manhattan distance?](https://docs.helix-db.com/learn/vector-search/vector-distance-metrics): Cosine distance compares direction, Euclidean measures the straight-line gap, and Manhattan adds up the per-dimension gaps between two embeddings. — Page type: Concept\n\n## Full-text search\n- [What is full-text search?](https://docs.helix-db.com/learn/full-text-search/what-is-full-text-search): Full-text search finds documents by the words inside them and lists the best matches first, using an inverted index and a relevance score such as BM25. — Page type: Concept\n- [What is BM25?](https://docs.helix-db.com/learn/full-text-search/what-is-bm25): BM25 is a scoring formula that ranks documents for a keyword search by how rare each word is, how often it appears, and how long the document is. — Page type: Concept\n- [What is hybrid search?](https://docs.helix-db.com/learn/full-text-search/hybrid-search): Hybrid search runs a keyword search and a vector search for the same query, then merges the results so it finds both exact terms and similar meaning. — Page type: Concept\n\n## AI memory and RAG\n- [What is retrieval-augmented generation (RAG)?](https://docs.helix-db.com/learn/ai-memory/what-is-rag): RAG has an AI model answer from documents looked up at question time, so answers can use private, current data and cite their sources. — Page type: Concept\n- [What is GraphRAG?](https://docs.helix-db.com/learn/ai-memory/what-is-graphrag): GraphRAG finds context for an AI model by following links between facts in a graph, not only by matching text that is similar to the question. — Page type: Concept\n- [What is AI agent memory?](https://docs.helix-db.com/learn/ai-memory/what-is-ai-agent-memory): AI agent memory lets an AI assistant store, update, and recall what it learns across sessions, outside the model's context window. — Page type: Concept\n- [How do you build long-term memory for AI agents?](https://docs.helix-db.com/learn/ai-memory/long-term-memory-for-ai-agents): Build agent long-term memory from versioned, user-scoped facts: catch duplicates and forget on write, then search and expand on read. — Page type: Concept\n\n## Database architecture\n- [Why build a database on object storage?](https://docs.helix-db.com/learn/database-architecture/object-storage-databases): A database on object storage keeps its data in a durable object store and uses server memory and disks as cache, so storage and compute scale separately. — Page type: Concept\n- [Do you need separate graph, vector, and text databases?](https://docs.helix-db.com/learn/database-architecture/one-database-for-graph-vector-and-text): Often not. One database that stores relationships and indexes the same records for vector and keyword search avoids sync pipelines and stale copies. — Page type: Concept\n","docs/llms-full.txt":"# HelixDB\n\n> HelixDB combines a property graph, approximate vector search, and BM25 full-text search behind one operation-tree query model. Requests run through Cloud, a local server, or the embedded runtime. This file is the full markdown corpus for AI agents.\n\n\n# Introduction\n\nPage type: Concept\n\nHelixDB is a graph database with native vector and full-text search, built on object\nstorage. It stores and searches knowledge and context for applications where both\nexplicit structure and meaning matter.\n\nBecause graph, vector, and text retrieval live in one database, an application can\nwork with connected entities, semantically similar content, and exact terms without\nsynchronizing separate stores. Teams use HelixDB to build enterprise company brains,\nlarge-scale people search, and AI agent swarms.\n\nNew to these ideas? The [learning center](/learn) explains graph databases, vector and\nfull-text search, and AI agent memory from first principles.\n\n```mermaid\n%%{init: {\"themeCSS\": \".cluster-label { translate: -140px 0; }\"}}%%\nflowchart TB\n knowledge[\"Documents, conversations, events, users\"]\n\n subgraph brain[\"Company brain in HelixDB\"]\n relationships[\"Graph Data\"]\n vector[\"Vector search\"]\n text[\"Text search\"]\n context[\"Shared memory and context\"]\n\n relationships --> context\n vector --> context\n text --> context\n end\n\n knowledge --> relationships\n knowledge --> vector\n knowledge --> text\n\n context --> agents[\"AI agent swarms\"]\n context --> search[\"Enterprise search and knowledge bases\"]\n context --> apps[\"Company Brains\"]\n```\n\n## How it works\n\nEverything in HelixDB is one labeled property graph. Nodes are your entities, directed\nedges are the relationships between them, and both carry typed properties.\n\nSearch is not a second system bolted on top. A vector, text, or secondary index is an\naccess path over a property that already lives on a node or edge: the embedding on a\nchunk, the body text of a document, or the `status` field you filter by. That has\nthree consequences:\n\n- **The graph stays the source of truth.** A semantic match and the relationships\n around it are the same data, read in the same transaction.\n- **Nothing needs synchronizing.** There is no separate graph store, vector store, or\n search cluster to keep consistent.\n- **Edges are searchable too.** An index is scoped to a label and a property rather\n than a special node type, so you can search and filter relationships as well as\n entities.\n\n## What you get\n\n- **ACID transactions** across graph, vector, and text data.\n- **Vector search** with prefiltering and over 90% recall.\n- **Full-text search** for exact terms and keyword relevance.\n- **Equality and range filtering** on property values.\n- **Search and filtering on nodes and edges**, not just nodes.\n- **Object storage as the source of truth**, so storage scales independently of compute.\n- **Horizontal scaling** across multi-tenant and single-tenant deployments, with BYOC\n coming soon.\n\n## Why object storage\n\nMost graph databases keep all data on one machine's disk, and in the worst case\nentirely in memory. That caps how much data you can store and makes large graphs\nexpensive.\n\nHelixDB keeps object storage as the source of truth and uses NVMe and memory only as\ncaches. Storage scales separately from compute, so a dataset can grow far beyond the\ncapacity of the machines that serve it while latency and cost stay low.\n\n## Next steps\n\n Start a local instance and run the generated query.\n\n Learn how nodes, edges, properties, and indexes represent your data.\n\n Discuss large-scale Helix Cloud workloads with the founding team.\n\n# Get started\n\nPage type: Tutorial\n\nThis is the canonical local HelixDB quickstart. You will create a project, start\nthe generated `dev` instance, run the generated JSON request, and stop the\ninstance.\n\n## Prerequisites\n\n- Docker, or Podman configured as described below\n- A terminal on macOS or Linux, or PowerShell on Windows\n\nmacOS and Linux:\n\n```bash\ncurl -sSL \"https://install.helix-db.com\" | bash\n```\n\nWindows PowerShell:\n\n```powershell\nirm https://raw.githubusercontent.com/HelixDB/helix-db/main/crates/cli/install.ps1 | iex\n```\n\nIf the CLI is already installed, run [`helix update`](/cli/command-reference/update).\n\nCreate and enter an empty directory, then initialize it:\n\n```bash\nmkdir my-helix-app\ncd my-helix-app\nhelix init local\n```\n\n`helix init local` creates:\n\n- `helix.toml` with one local instance named `dev` on port `6969`.\n- `.helix/` for CLI-managed instance state.\n- `.gitignore` entries for `.helix/`, `.env`, `target/`, and `*.log`.\n- `AGENTS.md` with the current CLI workflow for coding agents.\n- `examples/request.json` with a runnable read request.\n\nIt does not create a Rust, TypeScript, Go, or Python project. Choose an SDK\nafter this CLI journey.\n\nIf you use Podman, set `container_runtime = \"podman\"` under `[project]` in\n`helix.toml` before you start the generated instance. New projects otherwise\ndefault to Docker.\n\n```bash\nhelix start dev\n```\n\nThe CLI starts the local container, publishes it at `http://localhost:6969`,\nand waits for the database health check before it returns.\n\nThe default storage mode is in-memory. Stopping the instance removes its data.\nUse `helix start dev --disk` when you need local persistence.\n\n```bash\nhelix query dev --file examples/request.json\n```\n\nThe generated request counts nodes with the `User` label. A new database\nreturns a `node_count` of zero. Edit the JSON file and run the same command\nagain to iterate.\n\n```bash\nhelix stop dev\n```\n\n`helix stop` is idempotent, so it also exits successfully when the instance is\nalready stopped.\n\n## Use an SDK\n\nThe SDKs build the same JSON operation tree that `helix query` sends to\n`POST /v2/query`. Initialize a normal language project and install one released\nSDK:\n\n```bash Rust\ncargo add helix-db@3.0.0 tokio serde_json\n```\n\n```bash TypeScript\nnpm install @helix-db/helix-db@3.1.0\n```\n\n```bash Go\ngo get github.com/helixdb/helix-db/sdks/go@v0.3.1\n```\n\n```bash Python\npython -m pip install helix-db==0.3.4\n```\n\nContinue with the full setup guide for your language:\n\n Build and execute typed Rust queries.\n\n Build and execute TypeScript queries.\n\n Build and execute Go queries.\n\n Build and execute synchronous or asynchronous Python queries.\n\n## Next steps\n\n Learn how SDK builders become the JSON request sent to HelixDB.\n\n Learn how nodes, edges, labels, and properties fit together.\n\n Add, update, and remove graph data.\n\n See every current CLI command and option.\n\n# Deployment options\n\nPage type: Concept\n\nEvery deployment option runs the same queries with the same SDKs, so you can develop\nagainst one and deploy to another without changing application code. Choose based on\nwhere the engine runs, where data is stored, and who operates it.\n\n| Mode | Best for | Interface | Storage | Availability |\n| --- | --- | --- | --- | --- |\n| Helix Cloud | Production services with managed operations | HTTPS | Managed object storage | Highly available |\n| Local server | Development, production-shaped testing, and self-hosting | HTTP | Memory or S3-compatible storage | Single node |\n| Embedded | In-process applications and local tools | Native SDK call | Memory, disk, or object storage | In process |\n\n## Helix Cloud\n\nHelix Cloud runs a highly available cluster that provides managed deployment, storage,\ndatabase authentication, and read scaling. It supports multi-tenant and single-tenant\ndeployments; BYOC is coming soon.\n\n## Local server\n\nThe local server runs the standalone HelixDB container on your own machine or\ninfrastructure. It exposes the same `POST /v2/query` interface as Helix Cloud, which\nmakes it the default development target: code written against it works unchanged in\nCloud.\n\n## Embedded\n\nEmbedded clients open the engine inside your process and skip HTTP entirely. Rust,\nTypeScript, and Python ship embedded runtimes; the Go SDK is currently HTTP-only.\n\n## Which should I use?\n\n- **Building a networked application?** Develop against the local server.\n- **Going to production?** Use Helix Cloud for managed operations and high\n availability.\n- **Shipping a tool or app that owns its data?** Use embedded mode when process-local\n execution simplifies your architecture and the SDK's native packaging fits how you\n distribute.\n\n## Next steps\n\n Run the server locally with memory or persistent storage.\n\n Create a managed database and connect to it.\n\n Open a writer or reader and review current SDK availability.\n\n# Local server\n\nPage type: Guide\n\nThe `ghcr.io/helixdb/helixdb:v0.0.12` image runs the standalone HelixDB server.\nIt supports Linux on amd64 and arm64.\nIt exposes the same operation-tree request contract used by Helix Cloud at\n`POST /v2/query`; gateway-only Cloud features are not included.\n\n## Choose storage\n\n| Mode | Persistence | Use when |\n| --- | --- | --- |\n| Memory | Lost when the server stops | Fast local iteration and tests |\n| Native directory (`HELIX_DATA_DIR`) | Preserved in a mounted volume or directory | Running the image directly with local persistence |\n| CLI disk (`--disk`) | Preserved in a CLI-managed SeaweedFS volume | Testing restart and persistence through the CLI |\n| Existing S3-compatible store | Owned outside Helix | Reusing SeaweedFS, Ceph, LocalStack, or AWS S3 |\n\n## Start with the CLI\n\nmacOS and Linux:\n\n```bash\ncurl -sSL \"https://install.helix-db.com\" | bash\n```\n\nWindows PowerShell:\n\n```powershell\nirm https://raw.githubusercontent.com/HelixDB/helix-db/main/crates/cli/install.ps1 | iex\n```\n\nThen, in your shell:\n\n```bash\nmkdir my-helix-app\ncd my-helix-app\nhelix init local --name dev # add --disk to make persistence the project default\nhelix start dev # add --disk to persist this instance\n```\n\nThe standalone server accepts queries at `http://localhost:6969/v2/query`.\n\nFor an existing project, set `tag = \"v0.0.12\"` in its `[local.dev]` block in\n`helix.toml` before starting it. An explicitly saved tag overrides the CLI default.\n\nThe first time v0.0.10 or later opens a persisted database, it upgrades the index storage\nversion, and v0.0.9 and earlier then refuse to open that database. Back up the data\nbefore changing the tag if you may need to roll back.\n```bash\nhelix query dev \\\n -e 'readBatch().varAs(\"count\", g().nWithLabel(\"User\").count()).returning([\"count\"])'\n```\n\nThe default mode is in-memory. `helix stop` and `helix restart` discard its data.\n\n## Use an existing object store\n\nPlace credentials in a project-root `.env` file or export them:\n\n```dotenv .env\nAWS_ACCESS_KEY_ID=your-access-key\nAWS_SECRET_ACCESS_KEY=your-secret-key\n# AWS_SESSION_TOKEN=your-session-token\n```\n\n```bash\nhelix start dev \\\n --storage-uri s3://helix-db/my-app \\\n --s3-region us-east-1 \\\n --s3-endpoint-url https://s3.example.com \\\n --persist\n```\n\nAdd `--s3-allow-http` only for a plain HTTP endpoint.\n\n```bash\nhelix start dev \\\n --storage-uri s3://my-bucket/my-app \\\n --s3-region eu-west-2 \\\n --persist\n```\n\n`--persist` stores the resolved configuration in `helix.toml`. Helix does not delete\nexternally managed object-store data during stop, restart, or prune.\n\n## Run the image directly\n\nMemory mode is selected by leaving both `HELIX_DATA_DIR` and `S3_BUCKET` unset:\n\n```bash\ndocker run --rm --name helixdb \\\n -p 6969:8080 \\\n ghcr.io/helixdb/helixdb:v0.0.12\n```\n\nThe standalone server exposes liveness and readiness checks:\n\n```bash\ncurl -fsS http://127.0.0.1:6969/healthz\ncurl -fsS http://127.0.0.1:6969/readyz\n```\n\nDo not set `S3_BUCKET=IN_MEMORY`. Every defined `S3_BUCKET` value selects\nS3-compatible storage and is interpreted as a real bucket name. Setting\n`HELIX_DATA_DIR` and `S3_BUCKET` together causes startup to fail.\n\n## Run with native directory persistence\n\nSet `HELIX_DATA_DIR` to a mounted directory inside the container:\n\n```bash\ndocker volume create helixdb-data\ndocker run --rm --name helixdb \\\n -p 6969:8080 \\\n -e HELIX_DATA_DIR=/var/lib/helix \\\n --mount type=volume,source=helixdb-data,target=/var/lib/helix \\\n ghcr.io/helixdb/helixdb:v0.0.12\n```\n\nStop the server with `docker stop helixdb`. Starting a new container with the\nsame volume preserves its database. Removing the volume deletes the data.\nThis mode needs no object store; the CLI's `--disk` mode uses SeaweedFS.\n\nThe image runs as user and group `65532:65532`. Its `/var/lib/helix` directory\nis prepared for that user, including when initializing a new Docker named volume.\nIf you use a bind mount or an existing volume, its directory must be writable by\nthat user.\n\n## Run with SeaweedFS persistence\n\nThis Compose configuration runs SeaweedFS as a single-node S3 store with a\nstatic identity, creates the `helix-db` bucket on startup, and stores HelixDB\nobjects in the `seaweedfs-data` volume. HelixDB starts once a signed request\nto the bucket succeeds:\n\n```yaml docker-compose.yaml expandable\nservices:\n seaweedfs:\n image: ghcr.io/chrislusf/seaweedfs:4.47@sha256:ce9e796f1fe6f06968f4c04bdaf8f678dad9c8acdfef3d244133d71bfa6bf882\n command:\n - mini\n - -dir=/data\n - -bucket=helix-db\n - -s3.config=/etc/seaweedfs/s3.json\n - -master.telemetry=false\n - -admin.ui=false\n - -webdav=false\n - -s3.port.iceberg=0\n - -s3.port.lance=0\n restart: unless-stopped\n configs:\n - source: seaweedfs-s3\n target: /etc/seaweedfs/s3.json\n volumes:\n - seaweedfs-data:/data\n healthcheck:\n test:\n - CMD\n - curl\n - -fsS\n - -o\n - /dev/null\n - --max-time\n - \"2\"\n - -I\n - --aws-sigv4\n - aws:amz:us-east-1:s3\n - --user\n - helix:helix-local-secret\n - http://127.0.0.1:8333/helix-db\n interval: 1s\n timeout: 5s\n retries: 120\n\n helix:\n image: ghcr.io/helixdb/helixdb:v0.0.12\n restart: unless-stopped\n depends_on:\n seaweedfs:\n condition: service_healthy\n ports:\n - \"6969:8080\"\n environment:\n S3_BUCKET: helix-db\n S3_REGION: us-east-1\n DB_PATH: db/\n AWS_ACCESS_KEY_ID: helix\n AWS_SECRET_ACCESS_KEY: helix-local-secret\n AWS_ENDPOINT: http://seaweedfs:8333\n AWS_ALLOW_HTTP: \"true\"\n\nconfigs:\n seaweedfs-s3:\n content: |\n {\n \"identities\": [\n {\n \"name\": \"helix\",\n \"credentials\": [\n {\"accessKey\": \"helix\", \"secretKey\": \"helix-local-secret\"}\n ],\n \"actions\": [\"Read:helix-db\", \"Write:helix-db\", \"List:helix-db\"]\n }\n ]\n }\n\nvolumes:\n seaweedfs-data:\n```\n\nInline `configs` content needs Docker Compose 2.23.1 or later. The SeaweedFS\ncontainer is not published to the host. Change the example credentials in all\nthree places if you expose it.\n\nRun `docker compose down` to replace the HelixDB container without deleting\nthe SeaweedFS data. `docker compose down -v` deletes the persisted database.\n\nFor an existing object store, use the same HelixDB environment variables and\nomit the SeaweedFS service. For AWS S3, omit the endpoint and HTTP override.\n\nHelixDB's storage engine needs S3 conditional writes: `If-None-Match: *` on\ncreate and `If-Match` on replace must fail with HTTP 412 when the condition\ndoes not hold. A store that ignores them can silently lose data. AWS S3 and\nSeaweedFS 4.09 or later enforce both.\n\n| Variable | Purpose |\n| --- | --- |\n| `HELIX_DATA_DIR` | Selects native disk storage and names its container directory; mount a volume there for persistence |\n| `S3_BUCKET` | Selects S3 mode and names the object-store bucket; omit both storage selectors for memory mode |\n| `S3_REGION` | Region supplied to the S3 client; falls back to `AWS_REGION`, then `AWS_DEFAULT_REGION`, then `us-east-1` |\n| `DB_PATH` | Logical database prefix inside the selected store, including under `HELIX_DATA_DIR`; defaults to `db/` |\n| `AWS_ACCESS_KEY_ID` | Access key |\n| `AWS_SECRET_ACCESS_KEY` | Secret key |\n| `AWS_SESSION_TOKEN` | Optional temporary-credential token |\n| `AWS_ENDPOINT` or `AWS_ENDPOINT_URL_S3` | Non-AWS S3 endpoint |\n| `AWS_ALLOW_HTTP` | Set to `true` or `1` to permit an HTTP endpoint |\n| `HELIX_STRONG_VECTOR_SEARCH_MAX_PENDING_BYTES` | Most unpublished vector work, in bytes, one `strong` vector search scores before it fails with `index_backpressure`; defaults to the index's retained-byte limit (1,000,000,000), which writes reach first. See [Search consistency](/database/helix-db/query-guides/search-consistency#searches-behind-unpublished-changes) |\n| `HELIX_STRONG_TEXT_SEARCH_MAX_ANALYSIS_BYTES` | Most unpublished text, in analysis bytes, one `strong` text search includes per partition before it fails with `index_backpressure`; defaults to 512 MiB (536,870,912). See [Search consistency](/database/helix-db/query-guides/search-consistency#searches-behind-unpublished-changes) |\n\nThe endpoint must be reachable from inside the container; container `localhost` is not\nthe host machine. `DB_PATH` is a logical prefix, not the storage directory. To use\nnative directory persistence, set `HELIX_DATA_DIR` and mount the directory there.\n\n## Add a local disk cache\n\nWith `S3_BUCKET`, the server always keeps recently read data on local disk, ideally\nNVMe, in `/var/cache/helix` unless `HELIX_DISK_CACHE_DIR` names another directory.\nVector indexes on S3 need it: once an index outgrows the memory cache, every graph\nhop that misses it would otherwise wait on its own S3 request. Mount a volume at\n`/var/cache/helix` so the cache survives restarts; without one, each new container\nstarts with an empty cache. With `HELIX_DATA_DIR`, set `HELIX_DISK_CACHE_DIR` to add\nthe disk cache. Memory storage rejects the cache variables.\n\nThe disk cache needs v0.0.7 or later, and the v0.0.6 image and earlier ignore the\n`HELIX_DISK_CACHE_*` variables. v0.0.7 and v0.0.8 cache S3 on disk only when\n`HELIX_DISK_CACHE_DIR` is set, so the example below sets it to the default.\n```bash\nsudo mkdir -p /data/helix-cache\nsudo chown 65532:65532 /data/helix-cache\ndocker run --rm --name helixdb \\\n -p 6969:8080 \\\n -e S3_BUCKET=my-bucket \\\n -e S3_REGION=eu-west-2 \\\n -e HELIX_DISK_CACHE_DIR=/var/cache/helix \\\n -e HELIX_DISK_CACHE_BYTES=107374182400 \\\n -v /data/helix-cache:/var/cache/helix \\\n ghcr.io/helixdb/helixdb:v0.0.12\n```\n\nIn Compose, add a volume at `/var/cache/helix` to the `helix` service. A new\nnamed volume mounted there is already writable; a bind mount must be owned by\n`65532:65532`. When running as another user or outside the image, set\n`HELIX_DISK_CACHE_DIR` to a directory that user can write. With a read-only root\nfilesystem, mount a writable volume (for example a tmpfs or `emptyDir`) at the cache\ndirectory. Use one cache directory per running server and per database; changing\n`DB_PATH` on the same directory leaves the old database's full-text cache behind.\n\n| Variable | Purpose |\n| --- | --- |\n| `HELIX_DISK_CACHE_DIR` | Disk cache directory, created if needed. Defaults to `/var/cache/helix` with `S3_BUCKET`; with `HELIX_DATA_DIR`, setting it enables the disk cache |\n| `HELIX_DISK_CACHE_BYTES` | Total disk budget in bytes, from 64 MiB to 1 TiB; defaults to 8 GiB |\n| `HELIX_DISK_CACHE_MEMORY_BYTES` | Memory tier of the block cache in bytes; defaults to 640 MiB |\n| `HELIX_DISK_CACHE_WARM` | `on` (the default) or `off`: whether the server warms the disk cache at startup |\n\nHalf of the disk budget caches object-store files, 3/8 caches database blocks,\nand the rest caches full-text search data. With `S3_BUCKET`, the object-store cache\nalso keeps the files the server writes; with `HELIX_DATA_DIR` they are already on\nlocal disk, so it keeps only the files the server reads. Changing the budget\nusually changes the block size, which discards the database-block cache at startup\nso it refills from the object store. The object-store cache keeps its files and\nevicts down to a smaller budget as it admits new data. Full-text search data is\ncached on demand, once searches have used it twice; the server downloads none of it\nat startup. At startup and on every admission the full-text cache evicts down to\nits share. Each of these trims spares data admitted or recorded as used in the\nsecond before it (use is recorded at most once a minute) and data still open in\nsearches or the 64 MiB full-text memory cache, so the cache can stay over its share\nby that data until the next admission. It never caches a split larger than its\nwhole share. After a restart, the first search to use each cached split reads and\nchecksums the whole split, up to 64 MiB, before it answers. Budget at least twice\nthe data the server reads often: the object-store cache fetches whole file parts\n(4 MiB, or smaller under a 2 GiB budget), so once that data outgrows half the\nbudget, cold reads fetch more than memory-only caches would. The budget must also\nfit on the cache's filesystem: its free space plus what the cache already uses.\nWhen `HELIX_DISK_CACHE_BYTES` is unset and the 8 GiB default does not fit, startup\nfails naming the variable; without a volume the cache would otherwise share, and\ncould fill, the filesystem of the container runtime. A budget you set that does not\nfit only logs a warning at startup.\n\nOnce storage opens, the server warms the disk cache in the background: it caches the\ndatabase blocks that index the newest files and, with `S3_BUCKET`, the rows vector\nsearches read, using at most half the object-store cache. The warm delays neither\nstartup nor readiness; queries that arrive first read from the object store as usual.\nSet `HELIX_DISK_CACHE_WARM=off` to skip it, and the caches then fill only as queries\nread.\n\nThe block cache also indexes its disk share in memory, outside\n`HELIX_DISK_CACHE_MEMORY_BYTES`. Once full, the index takes roughly 2–9 MiB of RAM\nper GiB of `HELIX_DISK_CACHE_BYTES` (about 20–70 MiB at the default, 2–9 GiB at\n1 TiB), and a restart briefly needs about twice that while it rebuilds the index.\nSize the container's memory limit for this index as well as the memory tier.\n\nThe block cache keeps up to 32,768 files open, so the server needs at least 34,792\nopen files in the worst case (26,600 at the default budget), plus one per open\nfull-text split. It raises its soft open-file limit to the hard limit at startup.\nIf the container's hard limit is below that minimum, startup fails naming\n`HELIX_DISK_CACHE_BYTES`; raise the hard limit with `--ulimit nofile=65536:65536`.\nLowering the budget is not a reliable fix above about 3 GiB, where the file count\ndoes not fall steadily with it; budgets of 1 GiB or less need about 8,200 or fewer.\nRun natively on macOS, the limit is also capped by `sysctl kern.maxfilesperproc`.\n\nStartup also fails with a message naming the variable when a size is invalid or\nout of range, a size is set with `HELIX_DATA_DIR` but without `HELIX_DISK_CACHE_DIR`,\nthe default budget does not fit, the cache directory is not writable or cannot be\nlocked (some network and FUSE filesystems do not support locks), or another running\nserver already uses it. Stop the old container before starting its replacement on\nthe same cache directory.\n\nAn S3 container that ran v0.0.8 or earlier used no local disk, so it can fail or\nuse more resources after upgrading: it needs a hard open-file limit of at least\n26,600 at the default budget (about 8,200 or fewer at 1 GiB or less), about 20–70\nMiB more RAM at the default budget, a writable cache directory (mount a volume with\na read-only root filesystem, and set `HELIX_DISK_CACHE_DIR` when running as a user\nother than `65532`), and room for the 8 GiB default unless `HELIX_DISK_CACHE_BYTES`\nis set.\n\n## Stop or inspect\n\n```bash\nhelix status\nhelix logs dev\nhelix stop dev\n```\n\n## Next steps\n\n Create a project and run your first query.\n\n Open HelixDB directly inside your process.\n\n Move the same application requests to a managed cluster.\n\n Manage instances and raw requests.\n\n# Embedded database\n\nPage type: Guide\n\nEmbedded clients execute operation-tree requests without HTTP. The process opens a\nwriter or read-only handle against memory, disk, or S3-compatible object storage.\n\n## Install\n\nInstall the SDK and its embedded runtime package.\n\n```bash Rust\ncargo add helix-db --features embedded\n```\n\n```bash TypeScript\nnpm install @helix-db/helix-db @helix-db/helix-db-embedded\n```\n\n```bash Go\ngo get github.com/helixdb/helix-db/sdks/go\n```\n\n```bash Python\npython -m pip install helix-db helix-db-embedded\n```\n\n## Open a writer\n\n```rust Rust\nuse helix_db::{Client, HelixDbSource};\n\nlet client = Client::open(HelixDbSource::Disk {\n root: \"/data/helix\".into(),\n database: \"app\".to_string(),\n})\n.await?;\n```\n\n```ts TypeScript\nconst client = await Client.embedded({\n kind: \"disk\",\n root: \"/data/helix\",\n database: \"app\",\n});\n```\n\n```go Go\nclient, err := helix.NewEmbeddedClient(\n\thelix.DiskSource{Root: \"/data/helix\", Database: \"app\"},\n)\nif err != nil {\n\treturn err\n}\n```\n\n```python Python\nfrom helixdb import Client, Disk\n\nclient = Client.embedded(Disk(\"/data/helix\", \"app\"))\n```\n\n## Choose a storage source\n\n| Source | Persistence | Use |\n| --- | --- | --- |\n| In-memory | Process-local | Tests, scratch data, and short-lived tools |\n| Disk | Filesystem path | Persistent single-host applications |\n| Object storage | Bucket and logical database path | Durable shared storage with an S3-compatible service |\n\n```ts In-memory\nconst client = await Client.embedded({\n kind: \"inMemory\",\n database: \"app\",\n});\n```\n\n```ts Disk\nconst client = await Client.embedded({\n kind: \"disk\",\n root: \"/data/helix\",\n database: \"app\",\n});\n```\n\n```ts Object storage\nconst client = await Client.embedded({\n kind: \"objectStorage\",\n database: \"app\",\n bucket: \"helix-production\",\n region: \"eu-west-2\",\n});\n```\n\n## Configure caches\n\nCache configuration is optional and fixed when the handle opens. Local defaults are\nbounded and demand-filled so a small embedded database does not reserve server-sized\ncaches:\n\n| Setting | In-memory | Disk | Object storage |\n| --- | --- | --- | --- |\n| Durable-write flush interval | 1 ms | 3 ms | 100 ms |\n| Vector memory | 64 MiB | 64 MiB | 256 MiB |\n| SlateDB block / metadata | 16 MiB / 8 MiB | 48 MiB / 16 MiB | 512 MiB / 128 MiB |\n| Full-text search | 16 MiB | 16 MiB | 64 MiB |\n| SlateDB / FTS startup warming | Off | Off | Background |\n| Disk cache | Disabled | Disabled | Disabled |\n\nThe local profiles also use a 16 MiB L0 target and a 64 MiB unflushed-data ceiling.\nThe flush interval is the batching delay before storage I/O; filesystem and device\nlatency still apply.\n\nPass an explicit cache configuration to change the vector-memory budget or enable\nbounded disk caches:\n\n| Profile | Behavior |\n| --- | --- |\n| Memory | Uses in-memory database caches |\n| Hybrid | Adds bounded disk caches with explicit paths and byte budgets |\n\n```ts Memory\nconst client = await Client.embedded(\n { kind: \"disk\", root: \"/data/helix\", database: \"app\" },\n {\n vectorMemoryBytes: 512 * 1024 * 1024,\n mode: { kind: \"memory\" },\n },\n);\n```\n\n```ts Hybrid\nconst client = await Client.embedded(\n { kind: \"disk\", root: \"/data/helix\", database: \"app\" },\n {\n vectorMemoryBytes: 512 * 1024 * 1024,\n mode: {\n kind: \"hybrid\",\n slateMemoryBytes: 256 * 1024 * 1024,\n slateDiskPath: \"/var/cache/helix/slate\",\n slateDiskBytes: 4 * 1024 * 1024 * 1024,\n objectStoreDiskPath: \"/var/cache/helix/objects\",\n objectStoreDiskBytes: 8 * 1024 * 1024 * 1024,\n },\n },\n);\n```\n\nCache byte budgets bound those caches. They are not a hard cap on total process RSS;\nrequests and index work can allocate transient memory.\n\n## Open a read-only database\n\nUse a read-only handle for processes that must never mutate the database. It opens an\nexisting disk or object-storage database, executes read requests, and rejects writes.\n\n```rust Rust\nuse helix_db::{Client, HelixDbSource};\n\nlet reader = Client::open_reader(HelixDbSource::Disk {\n root: \"/data/helix\".into(),\n database: \"app\".to_string(),\n})\n.await?;\n```\n\n```ts TypeScript\nconst reader = await Client.embeddedReader({\n kind: \"disk\",\n root: \"/data/helix\",\n database: \"app\",\n});\n```\n\n```go Go\nreader, err := helix.NewEmbeddedReaderClient(\n\thelix.DiskSource{Root: \"/data/helix\", Database: \"app\"},\n)\nif err != nil {\n\treturn err\n}\n```\n\n```python Python\nfrom helixdb import Client, Disk\n\nreader = Client.embedded_reader(Disk(\"/data/helix\", \"app\"))\n```\n\n## Embedded request rules\n\n- Use the same `QueryRequest` and response contract as server mode.\n- Writer handles can execute read and write requests.\n- Server routing options such as writer-only, warm-only, API headers, and durability\n headers are rejected because there is no gateway.\n- Reopen the same disk or object-storage source to retain canonical data across process\n lifetimes.\n\n## Next steps\n\n Run the production-shaped HTTP interface on your machine.\n\n Compare local server, embedded, and Cloud execution.\n\n# SDK setup\n\nPage type: Guide\n\nEvery HelixDB SDK builds the same operation-tree request and sends it to\n`POST /v2/query`, so the query guides apply to all four languages. Pick the SDK for\nyour application's language:\n\n| SDK | Package | HTTP client | Embedded runtime |\n| --- | --- | --- | --- |\n| Rust | `helix-db` (imported as `helix_db`) | Async | Yes, behind the `embedded` feature |\n| TypeScript | `@helix-db/helix-db` (ESM, Node.js 20+) | Async | Yes |\n| Go | `github.com/helixdb/helix-db/sdks/go` | Yes | Not yet |\n| Python | `helix-db` (imported as `helixdb`) | Sync and async | Yes, with `helix-db-embedded` |\n\n Typed DSL, `#[query]` macro, and async HTTP client.\n\n Typed DSL and async client for Node.js 20 or newer.\n\n Query builder and HTTP client.\n\n Synchronous and asynchronous clients.\n\n## Next steps\n\nAfter setup, the [query walkthrough](/database/helix-db/core-concepts/overview) builds\nand runs a first query, and the query guides cover reads, writes, traversals,\nfiltering, projections, parameters, and search in every language.\n\n# Rust SDK\n\nPage type: Guide\n\nThe published `helix-db` 3.0.0 crate provides the query DSL, request types, async\nHTTP client, native graph helpers, and a feature-gated embedded client.\n\nThe package is published as `helix-db` and imported as `helix_db`.\n\n## Install\n\n```bash\ncargo add helix-db@3.0.0\n```\n\nOr add the dependency directly:\n\n```toml Cargo.toml\n[dependencies]\nhelix-db = \"3.0.0\"\nserde = { version = \"1\", features = [\"derive\"] }\nserde_json = \"1\"\ntokio = { version = \"1\", features = [\"macros\", \"rt-multi-thread\"] }\n```\n\n## Define a query\n\n```rust\nuse helix_db::dsl::prelude::*;\n\n#[query]\nfn find_users(tenant_id: String, limit: i64) -> ReadBatch {\n read_batch()\n .var_as(\n \"users\",\n g()\n .n_with_label(\"User\")\n .where_(Predicate::eq(\"tenantId\", tenant_id))\n .limit(limit)\n .value_map(Some(vec![\"$id\", \"name\", \"tenantId\"])),\n )\n .returning([\"users\"])\n}\n```\n\n`#[query]` converts typed arguments into request parameters, sets `query_name` to\nthe function name, and returns `Result`.\n\n## Execute\n\n```rust\nuse helix_db::Client;\n\nlet client = Client::new(Some(\"http://localhost:6969\"))?;\nlet request = find_users(\"acme\".to_string(), 25)?;\nlet response: serde_json::Value = client.query(request).send().await?;\n```\n\nUse `.with_api_key(Some(\"hx_...\"))` for Helix Cloud. Request-builder options can\nrequire the writer, require a warm read, or control durability waiting.\n\n## Build without the macro\n\n```rust\nlet request = QueryRequest::read(\n read_batch()\n .var_as(\"count\", g().n_with_label(\"User\").count())\n .returning([\"count\"]),\n)\n.with_query_name(\"count_users\");\n```\n\n## Embedded runtime\n\nEnable the `embedded` feature:\n\n```bash\ncargo add helix-db --features embedded\n```\n\nSee [Embedded database](/database/helix-db/start-here/local-development/embedded-database)\nfor storage, cache, and handle configuration.\n\n## Verify\n\nRust SDK crate docs are doctests, and the public `#[query]` README journeys are\ncompile-tested as examples:\n\n```bash\ncargo test --manifest-path sdks/rust/Cargo.toml --lib\ncargo test --manifest-path sdks/rust/Cargo.toml --doc\ncargo check --manifest-path sdks/rust/Cargo.toml --example basic_query\ncargo check --manifest-path sdks/rust/Cargo.toml --example readme_sdk_query\ncargo check --manifest-path sdks/rust/Cargo.toml --example readme_macros_query\n```\n\n## Next steps\n\n Learn the batch and traversal model.\n\n Select data by ID, label, or indexed property.\n\n# TypeScript SDK\n\nPage type: Guide\n\nThe published `@helix-db/helix-db` 3.1.0 package targets Node.js 20 or newer and\nemits the same operation-tree AST as the Rust, Go, and Python SDKs.\n\nThe package is ESM and requires Node.js 20 or newer.\n\n## Install\n\n```bash\nnpm install @helix-db/helix-db@3.1.0\n```\n\nThe package is ESM. Set `\"type\": \"module\"` or compile to ESM.\n\n## Define a query\n\n```ts\nimport {\n Predicate,\n defineParams,\n g,\n param,\n readBatch,\n} from \"@helix-db/helix-db\";\n\nexport const findUsersParams = defineParams({\n tenantId: param.string(),\n limit: param.i64(),\n});\n\nexport function findUsers() {\n return readBatch()\n .varAs(\n \"users\",\n g()\n .nWithLabel(\"User\")\n .where(Predicate.eq(\"tenantId\", findUsersParams.tenantId))\n .limit(findUsersParams.limit)\n .valueMap([\"$id\", \"name\", \"tenantId\"]),\n )\n .returning([\"users\"]);\n}\n```\n\n## Execute\n\n```ts\nimport { Client } from \"@helix-db/helix-db\";\n\nconst request = findUsers().toQueryRequest(\n findUsersParams,\n { tenantId: \"acme\", limit: 25n },\n { queryName: \"find_users\" },\n);\n\nconst result = await Client.server(\"http://localhost:6969\")\n .query(request)\n .send();\n```\n\nUse `withApiKey(\"hx_...\")` for Helix Cloud.\n\n## Integer safety\n\nThe SDK preserves 64-bit integers as `bigint`. Use `stringifyJson` or the request's\nserialization methods instead of `JSON.stringify` when a value can contain `bigint`.\n\n## Embedded runtime\n\nInstall the SDK and embedded runtime with\n`npm install @helix-db/helix-db @helix-db/helix-db-embedded`. See\n[Embedded database](/database/helix-db/start-here/local-development/embedded-database)\nfor storage, cache, and handle configuration.\n\n## Verify\n\n```bash\nnpm --prefix sdks/typescript test\n```\n\n## Next steps\n\n Build reads, writes, and parameters.\n\n Open HelixDB directly inside your process.\n\n# Go SDK\n\nPage type: Guide\n\nThe Go SDK builds the shared operation-tree AST and executes requests through a\ntyped HTTP client.\n\nVersion `v0.3.1` ships the server query builder and HTTP client. It does not\ndistribute the native bindings required by embedded execution or native graph\nalgorithms.\n\nThe module path remains `github.com/helixdb/helix-db/sdks/go`; it does not add a\n`/v3` suffix because the module itself has not reached major version 2.\n\n## Install\n\n```bash\ngo get github.com/helixdb/helix-db/sdks/go@v0.3.1\n```\n\n```go\nimport helix \"github.com/helixdb/helix-db/sdks/go\"\n```\n\n## Define a query\n\n```go\nfunc FindUsers(tenantID string, limit int64) helix.Request {\n\tq := helix.ReadQuery(\"find_users\")\n\ttenant := q.ParamString(\"tenant_id\", tenantID)\n\tmaxRows := q.ParamI64(\"limit\", limit)\n\n\treturn q.\n\t\tVarAs(\n\t\t\t\"users\",\n\t\t\thelix.G().\n\t\t\t\tNWithLabel(\"User\").\n\t\t\t\tWhere(helix.PredEq(\"tenantId\", tenant)).\n\t\t\t\tLimit(maxRows).\n\t\t\t\tValueMap(\"$id\", \"name\", \"tenantId\"),\n\t\t).\n\t\tReturning(\"users\")\n}\n```\n\n## Execute\n\n```go\nclient, err := helix.NewClient(\"http://localhost:6969\")\nif err != nil {\n\treturn err\n}\n\nvar response struct {\n\tUsers []map[string]any `json:\"users\"`\n}\nif err := client.Exec(ctx, FindUsers(\"acme\", 25), &response); err != nil {\n\treturn err\n}\n```\n\nWrite requests can pass `helix.WriterOnly()` and `helix.AwaitDurability(true)` execution\noptions. The client does not retry conflicts automatically.\n\n## Release scope\n\nUse `v0.3.1` with a local or remote Helix server through `/v2/query`. Embedded\nconstructors and `Client.Graph` return native-binding-unavailable errors in a\nstandard module installation.\n\n## Verify\n\n```bash\ncd sdks/go\ngo test ./...\n```\n\n## Next steps\n\n Bind typed values and bounds.\n\n Diagnose validation, conflict, and runtime failures.\n\n# Python SDK\n\nPage type: Guide\n\nThe Python SDK is published on PyPI as `helix-db` 0.3.4 and imported as `helixdb`.\nIts builder methods use `snake_case` and produce the same operation-tree AST as\nthe other HelixDB v3 SDKs.\n\n`helix-db` includes the synchronous and asynchronous server clients. Install\n`helix-db-embedded` as well only when the application runs HelixDB in process.\n\n## Install\n\n```bash\npython -m pip install helix-db==0.3.4\n```\n\n## Define a query\n\n```python\nfrom helixdb import Predicate, define_params, g, param, read_batch\n\nfind_users_params = define_params({\n \"tenant_id\": param.string(),\n \"limit\": param.i64(),\n})\n\ndef find_users():\n return (\n read_batch()\n .var_as(\n \"users\",\n g()\n .n_with_label(\"User\")\n .where(Predicate.eq(\"tenantId\", find_users_params.tenant_id))\n .limit(find_users_params.limit)\n .value_map([\"$id\", \"name\", \"tenantId\"]),\n )\n .returning([\"users\"])\n )\n```\n\n## Execute\n\n```python\nfrom helixdb import Client\n\nrequest = find_users().to_query_request(\n find_users_params,\n {\"tenant_id\": \"acme\", \"limit\": 25},\n query_name=\"find_users\",\n)\nresult = Client(\"http://localhost:6969\").query(request)\n```\n\nThe server clients have no native runtime dependency.\n\n### Async execution\n\nReuse one async client to reuse its HTTP connection pool. HTTP requests have no\ntimeout unless you explicitly configure one.\n\n```python\nimport asyncio\n\nimport httpx\n\nfrom helixdb import AsyncClient\n\nasync def execute_queries():\n limits = httpx.Limits(max_connections=20, max_keepalive_connections=10)\n async with AsyncClient(timeout=10.0, limits=limits) as client:\n return await asyncio.gather(\n client.query(request),\n client.execute(request, writer_only=True, timeout=2.0),\n )\n\nresults = asyncio.run(execute_queries())\n```\n\nCancellation propagates as `asyncio.CancelledError`, closes the response stream,\nand leaves the client reusable. The client owns and closes an injected HTTPX\nasync transport. `await client.close()` is idempotent.\n\n## Embedded runtime\n\nInstall the SDK and embedded runtime with\n`python -m pip install helix-db helix-db-embedded`. See\n[Embedded database](/database/helix-db/start-here/local-development/embedded-database)\nfor storage, cache, and handle configuration.\n\n```python\nimport asyncio\n\nfrom helixdb import AsyncClient, Disk, InMemory\n\nasync def query_embedded():\n writer = await AsyncClient.embedded(InMemory(\"app\"))\n async with writer:\n memory_result = await writer.query(request)\n\n reader = await AsyncClient.embedded_reader(Disk(\"./data\", \"seeded-app\"))\n async with reader:\n disk_checkpoint = await reader.query(request)\n\n return memory_result, disk_checkpoint\n\nresults = asyncio.run(query_embedded())\n```\n\nAsync embedded queries await native UniFFI operations directly. Use\n`asyncio.timeout(...)` for cancellation boundaries. Async native graph loading is\nnot part of this API; use the synchronous `Client.graph(...)` API.\n\n## Verify\n\n```bash\nPYTHONDONTWRITEBYTECODE=1 \\\nPYTHONPATH=sdks/python/src \\\npython -m unittest discover sdks/python/tests\n```\n\n## Next steps\n\n Follow the shared batch and traversal model.\n\n Open an in-process writer or reader.\n\n# Roadmap\n\nPage type: Reference\n\n## In progress\n\n- **Smarter cache warming** (ongoing)\n- **Reliability and availability improvements** (ongoing)\n- **Support for non-HA clusters**\n- **Backups and point-in-time recovery**\n- **Expanded query plans for better performance**\n\n## Up next\n\n- **SSO and SAML**\n- **RBAC and fine-grained API key permissions**\n- **AWS PrivateLink**\n- **Audit logs**\n\n## Recently shipped\n\n- **Local Docker deployment**\n- **Dashboard improvements**\n\nSee the [release notes](/database/helix-db/start-here/release-notes) for everything\nthat has shipped.\n\nHave a feature request? [Let us know on Discord](https://discord.com/invite/2stgMPr5BD) or [email us](mailto:founders@helix-db.com).\n\n# Release notes\n\nPage type: Reference\n\n- **Strong text search keeps working during ingest.** A `strong` text search now has its own bound, 512 MiB of unpublished text per partition by default (it was one publication's 64 MiB), and reuses analyses of pending text across searches. Ingest bursts of 20K–40K documents that made v0.0.10's strong text searches fail with `index_backpressure` now complete with no rejections, and a strong text search behind 5,000 pending documents dropped from about 200 ms to 30 ms. Set `HELIX_STRONG_TEXT_SEARCH_MAX_ANALYSIS_BYTES` to change the bound; past it the search fails with retryable `index_backpressure` (`pending_text_analysis_bytes`).\n- **Strong searches decode pending index work once per request.** Several searches in one request share one decoded copy of the pending queue, decoding and exact scoring run off the async workers so they no longer stall other requests, and four strong vector searches in one request behind 160K pending 768-dimension changes went from about 5.0 s to 2.2 s.\n- **Strong vector searches are bounded.** A `strong` vector search decodes and scores at most the index's retained-byte limit of unpublished work by default (1 GB, so writes reach backpressure first). Set `HELIX_STRONG_VECTOR_SEARCH_MAX_PENDING_BYTES` to lower it; past it the search fails with retryable `index_backpressure` (`pending_vector_bytes`).\n- **Queue admission tracks real memory.** Each queued index operation now counts its encoded size plus 576 bytes against the 1 GB per-index limit, so a backlog of many small operations, such as deletes, can no longer use several times the limit in memory. Such backlogs reach `index_backpressure` sooner; the 250,000 pending-entity limit is unchanged.\n- **Writers reopen faster with a large backlog.** Opening a writer loads its queued index work one queue at a time instead of decoding every queue at once: a 2.26 GB backlog opened in about 5 s instead of 25 s, with peak memory bounded by the largest queue instead of the whole backlog.\n- **Publication drains in linear time.** Selecting work to publish no longer rescans the whole queue each time, which was 9.4 s of bookkeeping per 250K-operation drain and is now 0.16 s, and a queue retired by an index drop is discarded without being re-read.\n- No storage changes since v0.0.10: upgrading from v0.0.10 needs no migration. Upgrading from v0.0.9 or earlier follows the v0.0.10 notes below.\n- **CLI 3.4.4** defaults to image v0.0.11. Projects that saved a `tag` in `helix.toml` keep using it until you change it.\n\n- **Upgrading: index storage version 5.** The first time a v0.0.10 writer opens a database, it upgrades the index storage version from 4 to 5. It rewrites only the version marker and rebuilds no index. After that, v0.0.9 and earlier refuse to open the database with `unsupported_index_storage_version`:\n - Upgrade readers before the writer; v0.0.10 readers serve both versions.\n - Never start a v0.0.9-or-earlier writer against an upgraded database.\n - Take a backup before upgrading if you may need to roll back.\n- **[Vector and text indexes publish asynchronously](/database/helix-db/query-guides/search-consistency).** A write commits its graph change together with a durable queued index operation, and a background index worker publishes it into the vector or text index, so writes no longer wait on index maintenance. Steady vector insert publication went from 6.2 to 239 per second. Index builds no longer livelock under concurrent writes: on a c7i.8xlarge with 100 writes/s during the build, backfilling 100K 768-dimension vectors on disk finished in about 2,500 s, where v0.0.9 never finished.\n- **Search consistency.** Read requests set `search_consistency` to `strong` (the default) or `eventual`. `strong` searches include every committed write, published or not. `eventual` searches include a bounded amount of unpublished work and serve the rest as last published, so they can return a node or edge that has since changed tenant, label or indexed property. Write requests always search `strong`, and a write batch that searches an index fails with a retryable `transaction_conflict` if the index worker publishes into that index first. The SDK options ship in the next SDK releases; until then, send `search_consistency` in a direct HTTP request.\n- **[Index backpressure](/database/helix-db/query-guides/search-consistency#index-backpressure).** Each index retains at most 1,000,000,000 bytes or 250,000 pending entities of unpublished work. Three cases fail with `index_backpressure` (HTTP 429, `retryable: true`) before the request takes effect: a write past either limit, a whole-index `strong` search behind more than 800 unpublished changes, and a `strong` text search that would analyze more unpublished text than one publication may (64 MiB by default). Retry it unchanged with bounded backoff. A single write that stages more than 8 MiB of index work for one index fails with `index_operation_batch_too_large` (HTTP 400); split it.\n- **[Text write limits are per document](/database/helix-cloud/operate/limits#active-text-mutation-admission).** `active_text_mutation_limit_exceeded` now checks each indexed document against its own allowances, about 16,000 unique terms, instead of limiting a write to 512 text-indexed entities.\n- **A failing index entry no longer stalls its index.** An entry whose index update fails the same way every time, for example on damaged index data, is held back while the rest of the index keeps publishing. `GET /healthz` counts it under `blocked_index_entity_count`, the server logs an error naming it, and the worker retries it about once a minute. See [troubleshooting](/database/helix-db/query-guides/troubleshooting).\n- **Fixed: `missing simhash` after re-embedding and then deleting a node** (the v0.0.9 known issue). Re-embedding a node no longer loses track of the vector index (HNSW) links that point at it, so deleting it later removes them all, and a node is never linked to itself. Indexes written by v0.0.9 and earlier can still hold such links; drop and recreate the vector index to repair them.\n- **Fixed: counts over a range index with other indexed filters.** A `.count()` over `N.where(...)` or `E.where(...)` that combined a range condition with other indexed conditions counted the range alone, for example 149 rows instead of 49. Counts now apply every filter.\n- **CLI 3.4.3** defaults to image v0.0.10. Projects that saved a `tag` in `helix.toml` keep using it until you change it.\n\n- **Upgrading S3 deployments** — S3 storage now always writes a local disk cache, so an S3 container that ran v0.0.8 or earlier can fail or use more resources after the upgrade:\n - The cache directory, `/var/cache/helix` unless `HELIX_DISK_CACHE_DIR` names another, must be writable. Mount a volume there (required with a read-only root filesystem), and set `HELIX_DISK_CACHE_DIR` when running as a user other than `65532`.\n - The hard open-file limit must be at least 26,600 at the default budget (about 8,200 or fewer at 1 GiB or less). Raise it with `--ulimit nofile=65536:65536`.\n - RSS grows by the block cache's index, about 20–70 MiB at the default budget and twice that briefly after a restart.\n - Without `HELIX_DISK_CACHE_BYTES`, the 8 GiB default budget must fit the cache's filesystem, or startup fails.\n- **[S3 always uses a local disk cache](/database/helix-db/start-here/local-development/local-server#add-a-local-disk-cache)** in `/var/cache/helix` by default, with an 8 GiB default budget. Memory-only S3 is gone: once a vector index outgrew the memory cache, every graph hop waited on its own S3 request. `HELIX_DATA_DIR` and in-memory storage are unchanged.\n- **Faster first vector searches on S3.** Cold batch reads overlap their block fetches, expansions read parents concurrently, and projections prefetch the records they need. After open, the server also warms vector search rows into the disk cache in the background; readiness never waits for it. `HELIX_DISK_CACHE_WARM=off` (default `on`) turns startup warming off. On 2 CPUs, 4 GiB of memory and an 8 GiB cache over S3, the first global vector top-50 after open went from 30.8 s on v0.0.7 to 714 ms once the ~26 s warm finished.\n- **Index sets are kept across `ForEach` iterations and unrelated writes** in the same request, which removes the v0.0.8 known limitation. A set is read again only when an iteration binds a parameter it depends on, or a write creates, deletes or changes indexed properties of nodes with its label. A batch that expands, filters on an index and adds an edge per iteration runs about twice as fast.\n- **Source filters and counts always use indexes.** `N.where(...)`, `E.where(...)` and counts on indexed properties no longer scan the label, including partly indexed ORs, long `IN` lists, parameter lists, `== null`, and counts over `.as()` / `.store()`. A label scan only happens when no condition has an index. On 50k rows, counts after `.as()` went from up to 1.1 s to under 5 ms, and 200-value `IN` lists from up to 1.5 s to about 0.2 s.\n- **Upgrading** — the stored data format is unchanged. Databases written by v0.0.8 open directly with v0.0.9.\n- **Known issue** — updating a node's vector (re-embedding it) and later deleting that node can leave vector index (HNSW) links pointing at the deleted node, and searches that reach them fail with `missing simhash`. Earlier releases are affected too, and a fix is in progress. To repair an affected index, drop and recreate the vector index.\n- **CLI 3.4.2** defaults to image v0.0.9. With `--disk` or S3 storage, `helix start` mounts a per-instance `helix---cache` volume at `/var/cache/helix` for the disk cache, with a 64 MiB budget in disk mode and 1 GiB for an S3 bucket. `helix stop` keeps it and `helix prune` removes it.\n\n- **Filters after a traversal always use indexes.** A `.where(...)` on indexe"},"files":{"AGENTS.md":"### approach\n\n- ⁠Make invalid states unrepresentable using algebraic data types (e.g. enums).\n- ⁠Use code coverage tools to make sure unit test coverage covers every edge case. This should be easily doable if invalid states are unrepresentable.\n- Keep things modular.\n- Define clear contract boundaries for testability. Document them all, and make sure doc comment examples are ran as tests.\n- Use assertions for invariants when encoding within types is not feasible.\n- Use clippy and fix code smells reported.\n- Prefer iterators, monadic logic, and functional concepts. Where not possible for performance, document why.\n- Make invalid state unrepresentable.\n- Prefer importing modules over long lists of types. Using `module::Type` at call sites is fine, keeps names unambiguous, and reduces namespace-collision churn.\n- Be wary of things that don't scale. If you have reason to believe why it wont, report back to the user explaining why.\n- instead of if let { ... } use let Some(…) = … else { }\n- avoid over using helper functions where possible. duplicating a single line of code is clearer than polluting with helper functions. if a large piece of functionality is shared or repeated multiple times then it can be abstracted but you should favour inline code where possible. small pieces of functionality should be inlined instead of abstracted.\n- Do not stage, commit (including locally), push, publish artifacts, or trigger remote CI unless explicitly instructed. Keep work-session timestamps out of authored reports and documentation.\n- As you make changes, if it is small (e.g. single/couple line addition) or if it is critical to your implementation, make the change.\n- Clean up any temporary files or directories you create during your work (including in /private/tmp)\n- ⁠match { Example(_) => ExampleVariant } -> use derive macro for Variant and the conversions instead of littering our code with the extra types and functions\n⁠- ⁠instead of children structs holding an Arc, maybe just let them take in a &Db in every method that requires it.\n- when that's not feasible, evaluate whether passing in an Arc is fine, and if not make sure that holding an Arc won't leak the memory based on how the child is stored in parent.\n\n### Slice access\n⁠When accessing or creating slices, for every access or slice don't minify it to start..end constants, always keep the additions of offsets explicit.\nInstead of making `start` and `end` variables in the place of `const` values, use the `const` values directly, adding them up instead.\n\ne.g. you should do the following\n\n```rust\nconst PREFIX_LEN: usize = core::mem::size_of::();\nconst INDEX_PREFIX_LEN: usize = core::mem::size_of::();\nconst PROPERTY_HASH_MAX_LEN: usize = core::mem::size_of::();\nconst VALUE_HASH_MAX_LEN: usize = core::mem::size_of::();\n\nlet property_hash = slice[INDEX_PREFIX_LEN..INDEX_PREFIX_LEN + PROPERTY_HASH_MAX_LEN]\n .try_into()\n .expect(\"property hash slice is 4 bytes\");\n```\n\n### Clippy and formatting\n\nRun clippy and formatting to check for code smells and formatting issues.\n\n```bash\ncargo clippy --workspace -- -D warnings\nrustfmt --edition 2024 --check\n```\n\nyou should run formatting and clippy before finishing your work. Rust crates in this workspace use edition 2024 from their `Cargo.toml`; do not pass `--edition 2024` to `cargo clippy`, because Cargo does not accept that flag for Clippy. Use a current stable Rust toolchain with the matching Clippy component installed.\n\n### Database Key/Value Construction, Parsing, and Use\n\n- ALL database key construction, parsing, and serialisation should be done using the structs in crates/db/src/encoding/v2\n - There are structs here that make building invalid keys impossible and it ensures call sites remain standardised and improves testability\n- ALL database value construction, parsing, and serialisation should be done using the structs in crates/db/src/encoding/v2/values\n - There are structs here that make building invalid keys impossible and it ensures call sites remain standardised and improves testability\n - We are in the process of moving more values to this dir. If you notice inline value use, please either add it to crates/db/src/encoding/v2/values if it is small (e.g. single variant addition) or if it is a major change just note it down.\n\n","docs/llms.txt":"# HelixDB\n\n> HelixDB combines a property graph, approximate vector search, and BM25 full-text search behind one operation-tree query model. Requests run through Cloud, a local server, or the embedded runtime.\n\nQuickstart (local instance requires Docker or Podman):\n\nmacOS and Linux:\n```bash\ncurl -sSL \"https://install.helix-db.com\" | bash # install the helix CLI\n```\n\nWindows PowerShell:\n```powershell\nirm https://raw.githubusercontent.com/HelixDB/helix-db/main/crates/cli/install.ps1 | iex\n```\n\nThen:\n```bash\nhelix init local # scaffold helix.toml + examples/\nhelix start dev # start a local instance\nhelix query dev -e 'writeBatch().varAs(\"alice\", g().addN(\"User\", { username: \"alice\" })).returning([\"alice\"])'\nhelix query dev -e 'readBatch().varAs(\"users\", g().nWithLabel(\"User\")).returning([\"users\"])'\n```\n\nFull walkthrough: https://docs.helix-db.com/database/helix-db/start-here/quickstart\n\n## HelixDB developer resources\n- [HelixDB HTTP API documentation](https://docs.helix-db.com/database/helix-db/query-guides/http-api): Request contract, authentication, headers, responses, and examples for `POST /v2/query`.\n- [HelixDB OpenAPI specification](https://www.helix-db.com/openapi.json): OpenAPI 3.1 JSON for the public HelixDB HTTP API.\n- [HelixDB authentication guide for agents](https://www.helix-db.com/auth.md): Supported API-key and OAuth surfaces, with links to machine-readable discovery metadata.\n- [HelixDB unified MCP endpoint](https://docs.helix-db.com/database/helix-cloud/connect/mcp): Connect human OAuth, scoped service credentials, and agent registrations to authorized tools on one endpoint.\n- [HelixDB AI Catalog](https://www.helix-db.com/.well-known/ai-catalog.json): ARD catalog of HelixDB agent resources.\n\n## HelixDB — Start Here\n- [Introduction](https://docs.helix-db.com/database/helix-db/start-here/introduction): HelixDB is a graph database with native vector and full-text search, built on object storage — Page type: Concept\n- [Get started](https://docs.helix-db.com/database/helix-db/start-here/quickstart): Initialize HelixDB, start a local instance, run the generated query, and stop it — Page type: Tutorial\n- [Deployment options](https://docs.helix-db.com/database/helix-db/start-here/run-modes): Compare Cloud, local server, and embedded execution — Page type: Concept\n- [Local server](https://docs.helix-db.com/database/helix-db/start-here/local-development/local-server): Start HelixDB locally with memory, a persistent directory, or S3-compatible storage — Page type: Guide\n- [Embedded database](https://docs.helix-db.com/database/helix-db/start-here/local-development/embedded-database): Open HelixDB directly inside your process with explicit storage and cache settings — Page type: Guide\n- [SDK setup](https://docs.helix-db.com/database/helix-db/start-here/sdk-setup/overview): Choose a HelixDB SDK and connect it to a local or Cloud server — Page type: Guide\n- [Rust SDK](https://docs.helix-db.com/database/helix-db/start-here/sdk-setup/rust-project-setup): Build typed HelixDB queries and execute them over HTTP or an embedded engine — Page type: Guide\n- [TypeScript SDK](https://docs.helix-db.com/database/helix-db/start-here/sdk-setup/typescript-project-setup): Build typed HelixDB requests for Node.js applications — Page type: Guide\n- [Go SDK](https://docs.helix-db.com/database/helix-db/start-here/sdk-setup/go-project-setup): Build and execute HelixDB requests with ordinary Go functions — Page type: Guide\n- [Python SDK](https://docs.helix-db.com/database/helix-db/start-here/sdk-setup/python-project-setup): Build HelixDB requests with idiomatic synchronous and asynchronous Python clients — Page type: Guide\n- [Roadmap](https://docs.helix-db.com/database/helix-db/start-here/roadmap): What we're building and what's coming next — Page type: Reference\n- [Release notes](https://docs.helix-db.com/database/helix-db/start-here/release-notes): New features and changes in HelixDB, Helix Cloud, the SDKs, and the CLI — Page type: Reference\n\n## Core Concepts\n- [Data model](https://docs.helix-db.com/database/helix-db/core-concepts/data-model): Understand how HelixDB represents entities, relationships, properties, and indexes — Page type: Concept\n- [Build and run a query](https://docs.helix-db.com/database/helix-db/core-concepts/overview): Build a small write query operation by operation, then read its request and response — Page type: Tutorial\n\n## Query Guides\n- [Writing data](https://docs.helix-db.com/database/helix-db/query-guides/writing-data): Create, update, connect, and remove entities in one typed write batch — Page type: Guide\n- [Reading data](https://docs.helix-db.com/database/helix-db/query-guides/reading-data): Start a traversal from IDs, labels, properties, or previous query results — Page type: Guide\n- [Traverse relationships](https://docs.helix-db.com/database/helix-db/query-guides/traversals): Follow edges, retain row-local bindings, and control duplicate paths — Page type: Guide\n- [Filtering](https://docs.helix-db.com/database/helix-db/query-guides/filtering): Narrow traversal streams with predicates and exact search candidate sets — Page type: Guide\n- [Shape query results](https://docs.helix-db.com/database/helix-db/query-guides/projections): Return properties, computed values, aggregates, and correlated binding rows — Page type: Guide\n- [Bind typed query parameters](https://docs.helix-db.com/database/helix-db/query-guides/parameters): Keep the operation tree stable while request values change — Page type: Guide\n- [Branch, repeat, and condition queries](https://docs.helix-db.com/database/helix-db/query-guides/advanced): Compose sub-traversals and gate named entries without leaving one transaction — Page type: Guide\n- [Query HelixDB with Cypher](https://docs.helix-db.com/database/helix-db/query-guides/cypher): Run Cypher statements beside native queries, and see which parts of openCypher HelixDB supports — Page type: Guide\n- [Secondary indexes](https://docs.helix-db.com/database/helix-db/query-guides/secondary-indexes): Accelerate equality, uniqueness, and ordered property lookups — Page type: Guide\n- [Vector indexes](https://docs.helix-db.com/database/helix-db/query-guides/vector-indexes): Create vector indexes and run nearest-neighbor search — Page type: Guide\n- [Text indexes](https://docs.helix-db.com/database/helix-db/query-guides/text-indexes): Create BM25 indexes and run ranked full-text search — Page type: Guide\n- [Prefiltered search](https://docs.helix-db.com/database/helix-db/query-guides/prefiltering): Rank only the nodes or edges a traversal reaches with vector or BM25 search — Page type: Guide\n- [Search consistency](https://docs.helix-db.com/database/helix-db/query-guides/search-consistency): Choose whether vector and text searches include unpublished index work, and handle index backpressure — Page type: Guide\n- [HelixDB HTTP API and OpenAPI specification](https://docs.helix-db.com/database/helix-db/query-guides/http-api): Call the HelixDB v2 query endpoint and discover its machine-readable OpenAPI 3.1 contract — Page type: Reference\n- [Query error reference](https://docs.helix-db.com/database/helix-db/query-guides/error-handling): Branch on stable error codes, apply retry rules, and look up every HelixDB query error — Page type: Reference\n- [Troubleshoot HelixDB](https://docs.helix-db.com/database/helix-db/query-guides/troubleshooting): Diagnose query, index, vector, embedded, and local runtime failures — Page type: Troubleshooting\n\n## Helix Cloud — Start Here\n- [Get started with Helix Cloud](https://docs.helix-db.com/database/helix-cloud/start-here/using-the-cloud): Sign in, create a workspace and choose its plan, provision a database, and test the connection — Page type: Tutorial\n- [Connect to Helix Cloud](https://docs.helix-db.com/database/helix-cloud/start-here/working-with-enterprise): Connect an SDK or HTTP client to a Helix Cloud database and control request routing — Page type: Guide\n- [Architecture](https://docs.helix-db.com/database/helix-cloud/start-here/architecture): How the Helix Cloud gateway, writer, readers, caches, and object storage serve reads and writes — Page type: Concept\n\n## Connect and automate\n- [Helix Cloud MCP](https://docs.helix-db.com/database/helix-cloud/connect/mcp): Connect users and agents to the unified Helix Cloud MCP endpoint — Page type: Reference\n\n## Operate\n- [Security](https://docs.helix-db.com/database/helix-cloud/operate/security): Authenticate requests, handle API keys, and review encryption and enterprise security features — Page type: Reference\n- [Multi-tenancy](https://docs.helix-db.com/database/helix-cloud/operate/multi-tenancy): Isolate application tenants with row-level scoping and tenant-partitioned search indexes — Page type: Guide\n- [Guarantees](https://docs.helix-db.com/database/helix-cloud/operate/guarantees): Atomicity, isolation, durability, index activation, and read-after-write behavior — Page type: Reference\n- [Limits](https://docs.helix-db.com/database/helix-cloud/operate/limits): Understand Helix Cloud request rate limits and database constraints — Page type: Reference\n- [Tradeoffs](https://docs.helix-db.com/database/helix-cloud/operate/tradeoffs): What the Helix Cloud architecture is optimized for, and where another system may fit better — Page type: Concept\n- [Helix Cloud gateway errors](https://docs.helix-db.com/database/helix-cloud/operate/error-handling): Use stable Helix Cloud error codes, HTTP statuses, and SDK error metadata — Page type: Reference\n\n## Helix Foundry — Start Here\n- [What is Helix Foundry?](https://docs.helix-db.com/foundry/start-here/introduction): Helix Foundry connects your company's data, drafts an ontology across it, and loads it into a Helix database you can explore — Page type: Concept\n- [Helix Foundry quickstart](https://docs.helix-db.com/foundry/start-here/quickstart): Sign in, connect a source, generate an ontology, load it into a Helix database and explore it — Page type: Tutorial\n- [Workspaces and navigation](https://docs.helix-db.com/foundry/start-here/workspaces-and-navigation): Sign in to Helix Foundry, choose or create a workspace, and find your way with the sidebar, search and themes — Page type: Guide\n\n## Data\n- [Connect and sync data](https://docs.helix-db.com/foundry/data/connect-data): Add a source to a Helix Foundry workspace, test its credential, sync its tables and read what each table holds — Page type: Guide\n- [Connectors](https://docs.helix-db.com/foundry/data/connectors): What each Helix Foundry source needs, the permissions to give it, the tables it syncs and its limits — Page type: Reference\n\n## Ontologies\n- [Create an ontology](https://docs.helix-db.com/foundry/ontologies/create-an-ontology): Create a Helix Foundry ontology on an existing Helix database or a new one, and read its overview — Page type: Guide\n- [Generate and version an ontology](https://docs.helix-db.com/foundry/ontologies/generate-and-version): Ask Helix Foundry's agent to draft an ontology from your synced tables and documents, review each version, and choose the current one — Page type: Guide\n- [Upload documents](https://docs.helix-db.com/foundry/ontologies/documents): Upload Markdown and text files to a Helix Foundry ontology so generations and loads read the names and facts they hold — Page type: Guide\n- [Load data into a Helix database](https://docs.helix-db.com/foundry/ontologies/load-data): Write an ontology's current version, your synced tables and your documents into its Helix database, and manage its loads — Page type: Guide\n\n## Explore\n- [Explore the graph](https://docs.helix-db.com/foundry/explore/explorer): Read what a Helix Foundry load wrote as a graph: search, expand, inspect, pick a load and compare two — Page type: Guide\n- [Records and entities](https://docs.helix-db.com/foundry/explore/records-and-entities): Read a Helix Foundry load as tables by type, open a record's links and sources, and see everything about one entity — Page type: Guide\n\n## Ask\n- [Ask questions of your data](https://docs.helix-db.com/foundry/ask/ask-questions): Ask a Helix Foundry ontology questions in plain language and get answers that cite where they came from. Coming soon. — Page type: Guide; Status: Preview\n\n## Workspace\n- [Members and roles](https://docs.helix-db.com/foundry/workspace/members-and-roles): See who is in a Helix Foundry workspace, invite people, and what owners, admins and members can do — Page type: Guide\n- [Plans and billing](https://docs.helix-db.com/foundry/workspace/plans-and-billing): Compare Helix Foundry Free, Pro and Max, upgrade a workspace, switch tiers, cancel, resume and manage payment — Page type: Guide\n\n## Reference\n- [Helix Foundry limits](https://docs.helix-db.com/foundry/reference/limits): Every Helix Foundry limit in one place: syncs, generations, documents, loads, spending and reads — Page type: Reference\n- [Troubleshooting Helix Foundry](https://docs.helix-db.com/foundry/reference/troubleshooting): What Helix Foundry's sign-in, connection, sync, generation, database and load messages mean, and what to do — Page type: Troubleshooting\n\n## Using the helix CLI\n- [Getting started with HelixDB CLI](https://docs.helix-db.com/cli/getting-started): Install the CLI, run locally, or link a WorkOS-authenticated Cloud database — Page type: Tutorial\n- [Local development](https://docs.helix-db.com/cli/workflows/local): Run a local instance and iterate on dynamic JSON queries — Page type: Guide\n- [Helix Cloud CLI workflow](https://docs.helix-db.com/cli/workflows/helix_cloud): Authenticate, link, query, and manage Cloud resources — Page type: Guide\n- [CLI configuration](https://docs.helix-db.com/cli/configuration): Project linkage and WorkOS session files — Page type: Reference\n- [CLI troubleshooting](https://docs.helix-db.com/cli/troubleshooting): Recover local and WorkOS-authenticated Cloud CLI operations — Page type: Troubleshooting\n\n## CLI Command Reference\n- [CLI command reference](https://docs.helix-db.com/cli/command-reference): Every Helix CLI command, grouped by what it manages — Page type: Reference\n- [helix add](https://docs.helix-db.com/cli/command-reference/add): Add a local instance or a Helix Cloud database link to an existing project — Page type: Reference\n- [helix auth](https://docs.helix-db.com/cli/command-reference/auth): Log in to Helix Cloud, check the session, or log out — Page type: Reference\n- [helix api](https://docs.helix-db.com/cli/command-reference/api): Call a Helix Cloud API endpoint with your CLI login session — Page type: Reference\n- [helix chef](https://docs.helix-db.com/cli/command-reference/chef): Bootstrap a first HelixDB app with a coding agent — Page type: Reference\n- [helix cluster](https://docs.helix-db.com/cli/command-reference/cluster): List and inspect Helix Cloud clusters and their active indexes — Page type: Reference\n- [helix cypher](https://docs.helix-db.com/cli/command-reference/cypher): Execute or explain one Cypher statement against a local instance — Page type: Reference\n- [helix database](https://docs.helix-db.com/cli/command-reference/database): Discover and manage Helix Cloud databases and application keys — Page type: Reference\n- [helix delete](https://docs.helix-db.com/cli/command-reference/delete): Remove an instance from helix.toml and clean up its local state — Page type: Reference\n- [helix doctor](https://docs.helix-db.com/cli/command-reference/doctor): Check an instance's setup: runtime, storage, disk cache, memory, and index use — Page type: Reference\n- [helix explorer](https://docs.helix-db.com/cli/command-reference/explorer): Browse a running local instance in the graph Explorer — Page type: Reference\n- [helix feedback](https://docs.helix-db.com/cli/command-reference/feedback): Open a pre-filled feedback issue for the Helix team — Page type: Reference\n- [helix init](https://docs.helix-db.com/cli/command-reference/init): Create a local project or a WorkOS-authenticated Cloud link — Page type: Reference\n- [helix logs](https://docs.helix-db.com/cli/command-reference/logs): View local logs or recent Cloud query errors — Page type: Reference\n- [helix metrics](https://docs.helix-db.com/cli/command-reference/metrics): Configure CLI telemetry and usage metrics collection — Page type: Reference\n- [helix project](https://docs.helix-db.com/cli/command-reference/project): Discover, manage, and link Helix Cloud projects — Page type: Reference\n- [helix prune](https://docs.helix-db.com/cli/command-reference/prune): Remove Helix-owned local containers, volumes, and instance state — Page type: Reference\n- [helix query](https://docs.helix-db.com/cli/command-reference/query): Execute a direct Helix v3 query against a local instance or a Cloud database — Page type: Reference\n- [helix restart](https://docs.helix-db.com/cli/command-reference/restart): Restart a background local instance — Page type: Reference\n- [helix skills](https://docs.helix-db.com/cli/command-reference/skills): Install, refresh, and list the Helix agent skills — Page type: Reference\n- [helix start](https://docs.helix-db.com/cli/command-reference/start): Start a local instance in the background or foreground — Page type: Reference\n- [helix status](https://docs.helix-db.com/cli/command-reference/status): Inspect local runtime or current Cloud database state — Page type: Reference\n- [helix stop](https://docs.helix-db.com/cli/command-reference/stop): Stop a background local instance and remove its containers — Page type: Reference\n- [helix service-credential](https://docs.helix-db.com/cli/command-reference/service-credential): Manage workspace-owned credentials for headless HTTP API and unified MCP clients — Page type: Reference\n- [helix shell](https://docs.helix-db.com/cli/command-reference/shell): Run line-oriented Helix v3 JSON requests — Page type: Reference\n- [helix update](https://docs.helix-db.com/cli/command-reference/update): Update the Helix CLI and refresh installed agent skills — Page type: Reference\n- [helix workspace](https://docs.helix-db.com/cli/command-reference/workspace): Discover WorkOS workspace memberships — Page type: Reference\n\n## Learning center\n- [Learning center](https://docs.helix-db.com/learn/index): Plain-language answers about graph databases, vector search, full-text search, AI agent memory, and modern database architecture. — Page type: Concept\n\n## Graph databases\n- [What is a graph database?](https://docs.helix-db.com/learn/graph-databases/what-is-a-graph-database): A graph database stores things as nodes and the connections between them as edges, and answers questions by following those connections. — Page type: Concept\n- [What is the difference between a graph database and a relational database?](https://docs.helix-db.com/learn/graph-databases/graph-vs-relational-database): A relational database keeps data in tables and rebuilds connections with joins; a graph database stores connections as edges and follows them. — Page type: Concept\n- [What is a knowledge graph?](https://docs.helix-db.com/learn/graph-databases/what-is-a-knowledge-graph): A knowledge graph is a connected collection of facts about things and how they relate, organized by a schema so software can query and cite it. — Page type: Concept\n- [What is a property graph?](https://docs.helix-db.com/learn/graph-databases/what-is-a-property-graph): A property graph stores data as labeled nodes and edges with key-value properties on both, so a relationship can carry its own details. — Page type: Concept\n- [What is the difference between a property graph and RDF?](https://docs.helix-db.com/learn/graph-databases/property-graph-vs-rdf): A property graph stores nodes and edges that carry their own properties; RDF stores every fact as a three-part triple named by global IDs. — Page type: Concept\n\n## Vector search\n- [What is vector search?](https://docs.helix-db.com/learn/vector-search/what-is-vector-search): Vector search finds results by meaning instead of exact words, by comparing embeddings: lists of numbers that capture what content is about. — Page type: Concept\n- [What are vector embeddings?](https://docs.helix-db.com/learn/vector-search/what-are-vector-embeddings): A vector embedding is a list of numbers, produced by a machine learning model, that captures what a piece of content means. — Page type: Concept\n- [What is a vector database?](https://docs.helix-db.com/learn/vector-search/what-is-a-vector-database): A vector database stores embeddings, lists of numbers that capture what content means, and quickly finds the ones most similar to a query. — Page type: Concept\n- [What is HNSW?](https://docs.helix-db.com/learn/vector-search/what-is-hnsw): HNSW is a vector search index that links each vector to its nearest neighbors in layers, so a search can hop quickly to similar items. — Page type: Concept\n- [What is filtered vector search?](https://docs.helix-db.com/learn/vector-search/filtered-vector-search): Filtered vector search finds the most similar items among only those that pass a rule, such as a tenant, a date range, or a permission check. — Page type: Concept\n- [What is the difference between cosine, Euclidean, and Manhattan distance?](https://docs.helix-db.com/learn/vector-search/vector-distance-metrics): Cosine distance compares direction, Euclidean measures the straight-line gap, and Manhattan adds up the per-dimension gaps between two embeddings. — Page type: Concept\n\n## Full-text search\n- [What is full-text search?](https://docs.helix-db.com/learn/full-text-search/what-is-full-text-search): Full-text search finds documents by the words inside them and lists the best matches first, using an inverted index and a relevance score such as BM25. — Page type: Concept\n- [What is BM25?](https://docs.helix-db.com/learn/full-text-search/what-is-bm25): BM25 is a scoring formula that ranks documents for a keyword search by how rare each word is, how often it appears, and how long the document is. — Page type: Concept\n- [What is hybrid search?](https://docs.helix-db.com/learn/full-text-search/hybrid-search): Hybrid search runs a keyword search and a vector search for the same query, then merges the results so it finds both exact terms and similar meaning. — Page type: Concept\n\n## AI memory and RAG\n- [What is retrieval-augmented generation (RAG)?](https://docs.helix-db.com/learn/ai-memory/what-is-rag): RAG has an AI model answer from documents looked up at question time, so answers can use private, current data and cite their sources. — Page type: Concept\n- [What is GraphRAG?](https://docs.helix-db.com/learn/ai-memory/what-is-graphrag): GraphRAG finds context for an AI model by following links between facts in a graph, not only by matching text that is similar to the question. — Page type: Concept\n- [What is AI agent memory?](https://docs.helix-db.com/learn/ai-memory/what-is-ai-agent-memory): AI agent memory lets an AI assistant store, update, and recall what it learns across sessions, outside the model's context window. — Page type: Concept\n- [How do you build long-term memory for AI agents?](https://docs.helix-db.com/learn/ai-memory/long-term-memory-for-ai-agents): Build agent long-term memory from versioned, user-scoped facts: catch duplicates and forget on write, then search and expand on read. — Page type: Concept\n\n## Database architecture\n- [Why build a database on object storage?](https://docs.helix-db.com/learn/database-architecture/object-storage-databases): A database on object storage keeps its data in a durable object store and uses server memory and disks as cache, so storage and compute scale separately. — Page type: Concept\n- [Do you need separate graph, vector, and text databases?](https://docs.helix-db.com/learn/database-architecture/one-database-for-graph-vector-and-text): Often not. One database that stores relationships and indexes the same records for vector and keyword search avoids sync pipelines and stale copies. — Page type: Concept\n","docs/llms-full.txt":"# HelixDB\n\n> HelixDB combines a property graph, approximate vector search, and BM25 full-text search behind one operation-tree query model. Requests run through Cloud, a local server, or the embedded runtime. This file is the full markdown corpus for AI agents.\n\n\n# Introduction\n\nPage type: Concept\n\nHelixDB is a graph database with native vector and full-text search, built on object\nstorage. It stores and searches knowledge and context for applications where both\nexplicit structure and meaning matter.\n\nBecause graph, vector, and text retrieval live in one database, an application can\nwork with connected entities, semantically similar content, and exact terms without\nsynchronizing separate stores. Teams use HelixDB to build enterprise company brains,\nlarge-scale people search, and AI agent swarms.\n\nNew to these ideas? The [learning center](/learn) explains graph databases, vector and\nfull-text search, and AI agent memory from first principles.\n\n```mermaid\n%%{init: {\"themeCSS\": \".cluster-label { translate: -140px 0; }\"}}%%\nflowchart TB\n knowledge[\"Documents, conversations, events, users\"]\n\n subgraph brain[\"Company brain in HelixDB\"]\n relationships[\"Graph Data\"]\n vector[\"Vector search\"]\n text[\"Text search\"]\n context[\"Shared memory and context\"]\n\n relationships --> context\n vector --> context\n text --> context\n end\n\n knowledge --> relationships\n knowledge --> vector\n knowledge --> text\n\n context --> agents[\"AI agent swarms\"]\n context --> search[\"Enterprise search and knowledge bases\"]\n context --> apps[\"Company Brains\"]\n```\n\n## How it works\n\nEverything in HelixDB is one labeled property graph. Nodes are your entities, directed\nedges are the relationships between them, and both carry typed properties.\n\nSearch is not a second system bolted on top. A vector, text, or secondary index is an\naccess path over a property that already lives on a node or edge: the embedding on a\nchunk, the body text of a document, or the `status` field you filter by. That has\nthree consequences:\n\n- **The graph stays the source of truth.** A semantic match and the relationships\n around it are the same data, read in the same transaction.\n- **Nothing needs synchronizing.** There is no separate graph store, vector store, or\n search cluster to keep consistent.\n- **Edges are searchable too.** An index is scoped to a label and a property rather\n than a special node type, so you can search and filter relationships as well as\n entities.\n\n## What you get\n\n- **ACID transactions** across graph, vector, and text data.\n- **Vector search** with prefiltering and over 90% recall.\n- **Full-text search** for exact terms and keyword relevance.\n- **Equality and range filtering** on property values.\n- **Search and filtering on nodes and edges**, not just nodes.\n- **Object storage as the source of truth**, so storage scales independently of compute.\n- **Horizontal scaling** across multi-tenant and single-tenant deployments, with BYOC\n coming soon.\n\n## Why object storage\n\nMost graph databases keep all data on one machine's disk, and in the worst case\nentirely in memory. That caps how much data you can store and makes large graphs\nexpensive.\n\nHelixDB keeps object storage as the source of truth and uses NVMe and memory only as\ncaches. Storage scales separately from compute, so a dataset can grow far beyond the\ncapacity of the machines that serve it while latency and cost stay low.\n\n## Next steps\n\n Start a local instance and run the generated query.\n\n Learn how nodes, edges, properties, and indexes represent your data.\n\n Discuss large-scale Helix Cloud workloads with the founding team.\n\n# Get started\n\nPage type: Tutorial\n\nThis is the canonical local HelixDB quickstart. You will create a project, start\nthe generated `dev` instance, run the generated JSON request, and stop the\ninstance.\n\n## Prerequisites\n\n- Docker, or Podman configured as described below\n- A terminal on macOS or Linux, or PowerShell on Windows\n\nmacOS and Linux:\n\n```bash\ncurl -sSL \"https://install.helix-db.com\" | bash\n```\n\nWindows PowerShell:\n\n```powershell\nirm https://raw.githubusercontent.com/HelixDB/helix-db/main/crates/cli/install.ps1 | iex\n```\n\nIf the CLI is already installed, run [`helix update`](/cli/command-reference/update).\n\nCreate and enter an empty directory, then initialize it:\n\n```bash\nmkdir my-helix-app\ncd my-helix-app\nhelix init local\n```\n\n`helix init local` creates:\n\n- `helix.toml` with one local instance named `dev` on port `6969`.\n- `.helix/` for CLI-managed instance state.\n- `.gitignore` entries for `.helix/`, `.env`, `target/`, and `*.log`.\n- `AGENTS.md` with the current CLI workflow for coding agents.\n- `examples/request.json` with a runnable read request.\n\nIt does not create a Rust, TypeScript, Go, or Python project. Choose an SDK\nafter this CLI journey.\n\nIf you use Podman, set `container_runtime = \"podman\"` under `[project]` in\n`helix.toml` before you start the generated instance. New projects otherwise\ndefault to Docker.\n\n```bash\nhelix start dev\n```\n\nThe CLI starts the local container, publishes it at `http://localhost:6969`,\nand waits for the database health check before it returns.\n\nThe default storage mode is in-memory. Stopping the instance removes its data.\nUse `helix start dev --disk` when you need local persistence.\n\n```bash\nhelix query dev --file examples/request.json\n```\n\nThe generated request counts nodes with the `User` label. A new database\nreturns a `node_count` of zero. Edit the JSON file and run the same command\nagain to iterate.\n\n```bash\nhelix stop dev\n```\n\n`helix stop` is idempotent, so it also exits successfully when the instance is\nalready stopped.\n\n## Use an SDK\n\nThe SDKs build the same JSON operation tree that `helix query` sends to\n`POST /v2/query`. Initialize a normal language project and install one released\nSDK:\n\n```bash Rust\ncargo add helix-db@3.0.0 tokio serde_json\n```\n\n```bash TypeScript\nnpm install @helix-db/helix-db@3.1.0\n```\n\n```bash Go\ngo get github.com/helixdb/helix-db/sdks/go@v0.3.1\n```\n\n```bash Python\npython -m pip install helix-db==0.3.4\n```\n\nContinue with the full setup guide for your language:\n\n Build and execute typed Rust queries.\n\n Build and execute TypeScript queries.\n\n Build and execute Go queries.\n\n Build and execute synchronous or asynchronous Python queries.\n\n## Next steps\n\n Learn how SDK builders become the JSON request sent to HelixDB.\n\n Learn how nodes, edges, labels, and properties fit together.\n\n Add, update, and remove graph data.\n\n See every current CLI command and option.\n\n# Deployment options\n\nPage type: Concept\n\nEvery deployment option runs the same queries with the same SDKs, so you can develop\nagainst one and deploy to another without changing application code. Choose based on\nwhere the engine runs, where data is stored, and who operates it.\n\n| Mode | Best for | Interface | Storage | Availability |\n| --- | --- | --- | --- | --- |\n| Helix Cloud | Production services with managed operations | HTTPS | Managed object storage | Highly available |\n| Local server | Development, production-shaped testing, and self-hosting | HTTP | Memory or S3-compatible storage | Single node |\n| Embedded | In-process applications and local tools | Native SDK call | Memory, disk, or object storage | In process |\n\n## Helix Cloud\n\nHelix Cloud runs a highly available cluster that provides managed deployment, storage,\ndatabase authentication, and read scaling. It supports multi-tenant and single-tenant\ndeployments; BYOC is coming soon.\n\n## Local server\n\nThe local server runs the standalone HelixDB container on your own machine or\ninfrastructure. It exposes the same `POST /v2/query` interface as Helix Cloud, which\nmakes it the default development target: code written against it works unchanged in\nCloud.\n\n## Embedded\n\nEmbedded clients open the engine inside your process and skip HTTP entirely. Rust,\nTypeScript, and Python ship embedded runtimes; the Go SDK is currently HTTP-only.\n\n## Which should I use?\n\n- **Building a networked application?** Develop against the local server.\n- **Going to production?** Use Helix Cloud for managed operations and high\n availability.\n- **Shipping a tool or app that owns its data?** Use embedded mode when process-local\n execution simplifies your architecture and the SDK's native packaging fits how you\n distribute.\n\n## Next steps\n\n Run the server locally with memory or persistent storage.\n\n Create a managed database and connect to it.\n\n Open a writer or reader and review current SDK availability.\n\n# Local server\n\nPage type: Guide\n\nThe `ghcr.io/helixdb/helixdb:v0.0.12` image runs the standalone HelixDB server.\nIt supports Linux on amd64 and arm64.\nIt exposes the same operation-tree request contract used by Helix Cloud at\n`POST /v2/query`; gateway-only Cloud features are not included.\n\n## Choose storage\n\n| Mode | Persistence | Use when |\n| --- | --- | --- |\n| Memory | Lost when the server stops | Fast local iteration and tests |\n| Native directory (`HELIX_DATA_DIR`) | Preserved in a mounted volume or directory | Running the image directly with local persistence |\n| CLI disk (`--disk`) | Preserved in a CLI-managed SeaweedFS volume | Testing restart and persistence through the CLI |\n| Existing S3-compatible store | Owned outside Helix | Reusing SeaweedFS, Ceph, LocalStack, or AWS S3 |\n\n## Start with the CLI\n\nmacOS and Linux:\n\n```bash\ncurl -sSL \"https://install.helix-db.com\" | bash\n```\n\nWindows PowerShell:\n\n```powershell\nirm https://raw.githubusercontent.com/HelixDB/helix-db/main/crates/cli/install.ps1 | iex\n```\n\nThen, in your shell:\n\n```bash\nmkdir my-helix-app\ncd my-helix-app\nhelix init local --name dev # add --disk to make persistence the project default\nhelix start dev # add --disk to persist this instance\n```\n\nThe standalone server accepts queries at `http://localhost:6969/v2/query`.\n\nFor an existing project, set `tag = \"v0.0.12\"` in its `[local.dev]` block in\n`helix.toml` before starting it. An explicitly saved tag overrides the CLI default.\n\nThe first time v0.0.10 or later opens a persisted database, it upgrades the index storage\nversion, and v0.0.9 and earlier then refuse to open that database. Back up the data\nbefore changing the tag if you may need to roll back.\n```bash\nhelix query dev \\\n -e 'readBatch().varAs(\"count\", g().nWithLabel(\"User\").count()).returning([\"count\"])'\n```\n\nThe default mode is in-memory. `helix stop` and `helix restart` discard its data.\n\n## Use an existing object store\n\nPlace credentials in a project-root `.env` file or export them:\n\n```dotenv .env\nAWS_ACCESS_KEY_ID=your-access-key\nAWS_SECRET_ACCESS_KEY=your-secret-key\n# AWS_SESSION_TOKEN=your-session-token\n```\n\n```bash\nhelix start dev \\\n --storage-uri s3://helix-db/my-app \\\n --s3-region us-east-1 \\\n --s3-endpoint-url https://s3.example.com \\\n --persist\n```\n\nAdd `--s3-allow-http` only for a plain HTTP endpoint.\n\n```bash\nhelix start dev \\\n --storage-uri s3://my-bucket/my-app \\\n --s3-region eu-west-2 \\\n --persist\n```\n\n`--persist` stores the resolved configuration in `helix.toml`. Helix does not delete\nexternally managed object-store data during stop, restart, or prune.\n\n## Run the image directly\n\nMemory mode is selected by leaving both `HELIX_DATA_DIR` and `S3_BUCKET` unset:\n\n```bash\ndocker run --rm --name helixdb \\\n -p 6969:8080 \\\n ghcr.io/helixdb/helixdb:v0.0.12\n```\n\nThe standalone server exposes liveness and readiness checks:\n\n```bash\ncurl -fsS http://127.0.0.1:6969/healthz\ncurl -fsS http://127.0.0.1:6969/readyz\n```\n\nDo not set `S3_BUCKET=IN_MEMORY`. Every defined `S3_BUCKET` value selects\nS3-compatible storage and is interpreted as a real bucket name. Setting\n`HELIX_DATA_DIR` and `S3_BUCKET` together causes startup to fail.\n\n## Run with native directory persistence\n\nSet `HELIX_DATA_DIR` to a mounted directory inside the container:\n\n```bash\ndocker volume create helixdb-data\ndocker run --rm --name helixdb \\\n -p 6969:8080 \\\n -e HELIX_DATA_DIR=/var/lib/helix \\\n --mount type=volume,source=helixdb-data,target=/var/lib/helix \\\n ghcr.io/helixdb/helixdb:v0.0.12\n```\n\nStop the server with `docker stop helixdb`. Starting a new container with the\nsame volume preserves its database. Removing the volume deletes the data.\nThis mode needs no object store; the CLI's `--disk` mode uses SeaweedFS.\n\nThe image runs as user and group `65532:65532`. Its `/var/lib/helix` directory\nis prepared for that user, including when initializing a new Docker named volume.\nIf you use a bind mount or an existing volume, its directory must be writable by\nthat user.\n\n## Run with SeaweedFS persistence\n\nThis Compose configuration runs SeaweedFS as a single-node S3 store with a\nstatic identity, creates the `helix-db` bucket on startup, and stores HelixDB\nobjects in the `seaweedfs-data` volume. HelixDB starts once a signed request\nto the bucket succeeds:\n\n```yaml docker-compose.yaml expandable\nservices:\n seaweedfs:\n image: ghcr.io/chrislusf/seaweedfs:4.47@sha256:ce9e796f1fe6f06968f4c04bdaf8f678dad9c8acdfef3d244133d71bfa6bf882\n command:\n - mini\n - -dir=/data\n - -bucket=helix-db\n - -s3.config=/etc/seaweedfs/s3.json\n - -master.telemetry=false\n - -admin.ui=false\n - -webdav=false\n - -s3.port.iceberg=0\n - -s3.port.lance=0\n restart: unless-stopped\n configs:\n - source: seaweedfs-s3\n target: /etc/seaweedfs/s3.json\n volumes:\n - seaweedfs-data:/data\n healthcheck:\n test:\n - CMD\n - curl\n - -fsS\n - -o\n - /dev/null\n - --max-time\n - \"2\"\n - -I\n - --aws-sigv4\n - aws:amz:us-east-1:s3\n - --user\n - helix:helix-local-secret\n - http://127.0.0.1:8333/helix-db\n interval: 1s\n timeout: 5s\n retries: 120\n\n helix:\n image: ghcr.io/helixdb/helixdb:v0.0.12\n restart: unless-stopped\n depends_on:\n seaweedfs:\n condition: service_healthy\n ports:\n - \"6969:8080\"\n environment:\n S3_BUCKET: helix-db\n S3_REGION: us-east-1\n DB_PATH: db/\n AWS_ACCESS_KEY_ID: helix\n AWS_SECRET_ACCESS_KEY: helix-local-secret\n AWS_ENDPOINT: http://seaweedfs:8333\n AWS_ALLOW_HTTP: \"true\"\n\nconfigs:\n seaweedfs-s3:\n content: |\n {\n \"identities\": [\n {\n \"name\": \"helix\",\n \"credentials\": [\n {\"accessKey\": \"helix\", \"secretKey\": \"helix-local-secret\"}\n ],\n \"actions\": [\"Read:helix-db\", \"Write:helix-db\", \"List:helix-db\"]\n }\n ]\n }\n\nvolumes:\n seaweedfs-data:\n```\n\nInline `configs` content needs Docker Compose 2.23.1 or later. The SeaweedFS\ncontainer is not published to the host. Change the example credentials in all\nthree places if you expose it.\n\nRun `docker compose down` to replace the HelixDB container without deleting\nthe SeaweedFS data. `docker compose down -v` deletes the persisted database.\n\nFor an existing object store, use the same HelixDB environment variables and\nomit the SeaweedFS service. For AWS S3, omit the endpoint and HTTP override.\n\nHelixDB's storage engine needs S3 conditional writes: `If-None-Match: *` on\ncreate and `If-Match` on replace must fail with HTTP 412 when the condition\ndoes not hold. A store that ignores them can silently lose data. AWS S3 and\nSeaweedFS 4.09 or later enforce both.\n\n| Variable | Purpose |\n| --- | --- |\n| `HELIX_DATA_DIR` | Selects native disk storage and names its container directory; mount a volume there for persistence |\n| `S3_BUCKET` | Selects S3 mode and names the object-store bucket; omit both storage selectors for memory mode |\n| `S3_REGION` | Region supplied to the S3 client; falls back to `AWS_REGION`, then `AWS_DEFAULT_REGION`, then `us-east-1` |\n| `DB_PATH` | Logical database prefix inside the selected store, including under `HELIX_DATA_DIR`; defaults to `db/` |\n| `AWS_ACCESS_KEY_ID` | Access key |\n| `AWS_SECRET_ACCESS_KEY` | Secret key |\n| `AWS_SESSION_TOKEN` | Optional temporary-credential token |\n| `AWS_ENDPOINT` or `AWS_ENDPOINT_URL_S3` | Non-AWS S3 endpoint |\n| `AWS_ALLOW_HTTP` | Set to `true` or `1` to permit an HTTP endpoint |\n| `HELIX_STRONG_VECTOR_SEARCH_MAX_PENDING_BYTES` | Most unpublished vector work, in bytes, one `strong` vector search scores before it fails with `index_backpressure`; defaults to the index's retained-byte limit (1,000,000,000), which writes reach first. See [Search consistency](/database/helix-db/query-guides/search-consistency#searches-behind-unpublished-changes) |\n| `HELIX_STRONG_TEXT_SEARCH_MAX_ANALYSIS_BYTES` | Most unpublished text, in analysis bytes, one `strong` text search includes per partition before it fails with `index_backpressure`; defaults to 512 MiB (536,870,912). See [Search consistency](/database/helix-db/query-guides/search-consistency#searches-behind-unpublished-changes) |\n\nThe endpoint must be reachable from inside the container; container `localhost` is not\nthe host machine. `DB_PATH` is a logical prefix, not the storage directory. To use\nnative directory persistence, set `HELIX_DATA_DIR` and mount the directory there.\n\n## Add a local disk cache\n\nWith `S3_BUCKET`, the server always keeps recently read data on local disk, ideally\nNVMe, in `/var/cache/helix` unless `HELIX_DISK_CACHE_DIR` names another directory.\nVector indexes on S3 need it: once an index outgrows the memory cache, every graph\nhop that misses it would otherwise wait on its own S3 request. Mount a volume at\n`/var/cache/helix` so the cache survives restarts; without one, each new container\nstarts with an empty cache. With `HELIX_DATA_DIR`, set `HELIX_DISK_CACHE_DIR` to add\nthe disk cache. Memory storage rejects the cache variables.\n\nThe disk cache needs v0.0.7 or later, and the v0.0.6 image and earlier ignore the\n`HELIX_DISK_CACHE_*` variables. v0.0.7 and v0.0.8 cache S3 on disk only when\n`HELIX_DISK_CACHE_DIR` is set, so the example below sets it to the default.\n```bash\nsudo mkdir -p /data/helix-cache\nsudo chown 65532:65532 /data/helix-cache\ndocker run --rm --name helixdb \\\n -p 6969:8080 \\\n -e S3_BUCKET=my-bucket \\\n -e S3_REGION=eu-west-2 \\\n -e HELIX_DISK_CACHE_DIR=/var/cache/helix \\\n -e HELIX_DISK_CACHE_BYTES=107374182400 \\\n -v /data/helix-cache:/var/cache/helix \\\n ghcr.io/helixdb/helixdb:v0.0.12\n```\n\nIn Compose, add a volume at `/var/cache/helix` to the `helix` service. A new\nnamed volume mounted there is already writable; a bind mount must be owned by\n`65532:65532`. When running as another user or outside the image, set\n`HELIX_DISK_CACHE_DIR` to a directory that user can write. With a read-only root\nfilesystem, mount a writable volume (for example a tmpfs or `emptyDir`) at the cache\ndirectory. Use one cache directory per running server and per database; changing\n`DB_PATH` on the same directory leaves the old database's full-text cache behind.\n\n| Variable | Purpose |\n| --- | --- |\n| `HELIX_DISK_CACHE_DIR` | Disk cache directory, created if needed. Defaults to `/var/cache/helix` with `S3_BUCKET`; with `HELIX_DATA_DIR`, setting it enables the disk cache |\n| `HELIX_DISK_CACHE_BYTES` | Total disk budget in bytes, from 64 MiB to 1 TiB; defaults to 8 GiB |\n| `HELIX_DISK_CACHE_MEMORY_BYTES` | Memory tier of the block cache in bytes; defaults to 640 MiB |\n| `HELIX_DISK_CACHE_WARM` | `on` (the default) or `off`: whether the server warms the disk cache at startup |\n\nHalf of the disk budget caches object-store files, 3/8 caches database blocks,\nand the rest caches full-text search data. With `S3_BUCKET`, the object-store cache\nalso keeps the files the server writes; with `HELIX_DATA_DIR` they are already on\nlocal disk, so it keeps only the files the server reads. Changing the budget\nusually changes the block size, which discards the database-block cache at startup\nso it refills from the object store. The object-store cache keeps its files and\nevicts down to a smaller budget as it admits new data. Full-text search data is\ncached on demand, once searches have used it twice; the server downloads none of it\nat startup. At startup and on every admission the full-text cache evicts down to\nits share. Each of these trims spares data admitted or recorded as used in the\nsecond before it (use is recorded at most once a minute) and data still open in\nsearches or the 64 MiB full-text memory cache, so the cache can stay over its share\nby that data until the next admission. It never caches a split larger than its\nwhole share. After a restart, the first search to use each cached split reads and\nchecksums the whole split, up to 64 MiB, before it answers. Budget at least twice\nthe data the server reads often: the object-store cache fetches whole file parts\n(4 MiB, or smaller under a 2 GiB budget), so once that data outgrows half the\nbudget, cold reads fetch more than memory-only caches would. The budget must also\nfit on the cache's filesystem: its free space plus what the cache already uses.\nWhen `HELIX_DISK_CACHE_BYTES` is unset and the 8 GiB default does not fit, startup\nfails naming the variable; without a volume the cache would otherwise share, and\ncould fill, the filesystem of the container runtime. A budget you set that does not\nfit only logs a warning at startup.\n\nOnce storage opens, the server warms the disk cache in the background: it caches the\ndatabase blocks that index the newest files and, with `S3_BUCKET`, the rows vector\nsearches read, using at most half the object-store cache. The warm delays neither\nstartup nor readiness; queries that arrive first read from the object store as usual.\nSet `HELIX_DISK_CACHE_WARM=off` to skip it, and the caches then fill only as queries\nread.\n\nThe block cache also indexes its disk share in memory, outside\n`HELIX_DISK_CACHE_MEMORY_BYTES`. Once full, the index takes roughly 2–9 MiB of RAM\nper GiB of `HELIX_DISK_CACHE_BYTES` (about 20–70 MiB at the default, 2–9 GiB at\n1 TiB), and a restart briefly needs about twice that while it rebuilds the index.\nSize the container's memory limit for this index as well as the memory tier.\n\nThe block cache keeps up to 32,768 files open, so the server needs at least 34,792\nopen files in the worst case (26,600 at the default budget), plus one per open\nfull-text split. It raises its soft open-file limit to the hard limit at startup.\nIf the container's hard limit is below that minimum, startup fails naming\n`HELIX_DISK_CACHE_BYTES`; raise the hard limit with `--ulimit nofile=65536:65536`.\nLowering the budget is not a reliable fix above about 3 GiB, where the file count\ndoes not fall steadily with it; budgets of 1 GiB or less need about 8,200 or fewer.\nRun natively on macOS, the limit is also capped by `sysctl kern.maxfilesperproc`.\n\nStartup also fails with a message naming the variable when a size is invalid or\nout of range, a size is set with `HELIX_DATA_DIR` but without `HELIX_DISK_CACHE_DIR`,\nthe default budget does not fit, the cache directory is not writable or cannot be\nlocked (some network and FUSE filesystems do not support locks), or another running\nserver already uses it. Stop the old container before starting its replacement on\nthe same cache directory.\n\nAn S3 container that ran v0.0.8 or earlier used no local disk, so it can fail or\nuse more resources after upgrading: it needs a hard open-file limit of at least\n26,600 at the default budget (about 8,200 or fewer at 1 GiB or less), about 20–70\nMiB more RAM at the default budget, a writable cache directory (mount a volume with\na read-only root filesystem, and set `HELIX_DISK_CACHE_DIR` when running as a user\nother than `65532`), and room for the 8 GiB default unless `HELIX_DISK_CACHE_BYTES`\nis set.\n\n## Stop or inspect\n\n```bash\nhelix status\nhelix logs dev\nhelix stop dev\n```\n\n## Next steps\n\n Create a project and run your first query.\n\n Open HelixDB directly inside your process.\n\n Move the same application requests to a managed cluster.\n\n Manage instances and raw requests.\n\n# Embedded database\n\nPage type: Guide\n\nEmbedded clients execute operation-tree requests without HTTP. The process opens a\nwriter or read-only handle against memory, disk, or S3-compatible object storage.\n\n## Install\n\nInstall the SDK and its embedded runtime package.\n\n```bash Rust\ncargo add helix-db --features embedded\n```\n\n```bash TypeScript\nnpm install @helix-db/helix-db @helix-db/helix-db-embedded\n```\n\n```bash Go\ngo get github.com/helixdb/helix-db/sdks/go\n```\n\n```bash Python\npython -m pip install helix-db helix-db-embedded\n```\n\n## Open a writer\n\n```rust Rust\nuse helix_db::{Client, HelixDbSource};\n\nlet client = Client::open(HelixDbSource::Disk {\n root: \"/data/helix\".into(),\n database: \"app\".to_string(),\n})\n.await?;\n```\n\n```ts TypeScript\nconst client = await Client.embedded({\n kind: \"disk\",\n root: \"/data/helix\",\n database: \"app\",\n});\n```\n\n```go Go\nclient, err := helix.NewEmbeddedClient(\n\thelix.DiskSource{Root: \"/data/helix\", Database: \"app\"},\n)\nif err != nil {\n\treturn err\n}\n```\n\n```python Python\nfrom helixdb import Client, Disk\n\nclient = Client.embedded(Disk(\"/data/helix\", \"app\"))\n```\n\n## Choose a storage source\n\n| Source | Persistence | Use |\n| --- | --- | --- |\n| In-memory | Process-local | Tests, scratch data, and short-lived tools |\n| Disk | Filesystem path | Persistent single-host applications |\n| Object storage | Bucket and logical database path | Durable shared storage with an S3-compatible service |\n\n```ts In-memory\nconst client = await Client.embedded({\n kind: \"inMemory\",\n database: \"app\",\n});\n```\n\n```ts Disk\nconst client = await Client.embedded({\n kind: \"disk\",\n root: \"/data/helix\",\n database: \"app\",\n});\n```\n\n```ts Object storage\nconst client = await Client.embedded({\n kind: \"objectStorage\",\n database: \"app\",\n bucket: \"helix-production\",\n region: \"eu-west-2\",\n});\n```\n\n## Configure caches\n\nCache configuration is optional and fixed when the handle opens. Local defaults are\nbounded and demand-filled so a small embedded database does not reserve server-sized\ncaches:\n\n| Setting | In-memory | Disk | Object storage |\n| --- | --- | --- | --- |\n| Durable-write flush interval | 1 ms | 3 ms | 100 ms |\n| Vector memory | 64 MiB | 64 MiB | 256 MiB |\n| SlateDB block / metadata | 16 MiB / 8 MiB | 48 MiB / 16 MiB | 512 MiB / 128 MiB |\n| Full-text search | 16 MiB | 16 MiB | 64 MiB |\n| SlateDB / FTS startup warming | Off | Off | Background |\n| Disk cache | Disabled | Disabled | Disabled |\n\nThe local profiles also use a 16 MiB L0 target and a 64 MiB unflushed-data ceiling.\nThe flush interval is the batching delay before storage I/O; filesystem and device\nlatency still apply.\n\nPass an explicit cache configuration to change the vector-memory budget or enable\nbounded disk caches:\n\n| Profile | Behavior |\n| --- | --- |\n| Memory | Uses in-memory database caches |\n| Hybrid | Adds bounded disk caches with explicit paths and byte budgets |\n\n```ts Memory\nconst client = await Client.embedded(\n { kind: \"disk\", root: \"/data/helix\", database: \"app\" },\n {\n vectorMemoryBytes: 512 * 1024 * 1024,\n mode: { kind: \"memory\" },\n },\n);\n```\n\n```ts Hybrid\nconst client = await Client.embedded(\n { kind: \"disk\", root: \"/data/helix\", database: \"app\" },\n {\n vectorMemoryBytes: 512 * 1024 * 1024,\n mode: {\n kind: \"hybrid\",\n slateMemoryBytes: 256 * 1024 * 1024,\n slateDiskPath: \"/var/cache/helix/slate\",\n slateDiskBytes: 4 * 1024 * 1024 * 1024,\n objectStoreDiskPath: \"/var/cache/helix/objects\",\n objectStoreDiskBytes: 8 * 1024 * 1024 * 1024,\n },\n },\n);\n```\n\nCache byte budgets bound those caches. They are not a hard cap on total process RSS;\nrequests and index work can allocate transient memory.\n\n## Open a read-only database\n\nUse a read-only handle for processes that must never mutate the database. It opens an\nexisting disk or object-storage database, executes read requests, and rejects writes.\n\n```rust Rust\nuse helix_db::{Client, HelixDbSource};\n\nlet reader = Client::open_reader(HelixDbSource::Disk {\n root: \"/data/helix\".into(),\n database: \"app\".to_string(),\n})\n.await?;\n```\n\n```ts TypeScript\nconst reader = await Client.embeddedReader({\n kind: \"disk\",\n root: \"/data/helix\",\n database: \"app\",\n});\n```\n\n```go Go\nreader, err := helix.NewEmbeddedReaderClient(\n\thelix.DiskSource{Root: \"/data/helix\", Database: \"app\"},\n)\nif err != nil {\n\treturn err\n}\n```\n\n```python Python\nfrom helixdb import Client, Disk\n\nreader = Client.embedded_reader(Disk(\"/data/helix\", \"app\"))\n```\n\n## Embedded request rules\n\n- Use the same `QueryRequest` and response contract as server mode.\n- Writer handles can execute read and write requests.\n- Server routing options such as writer-only, warm-only, API headers, and durability\n headers are rejected because there is no gateway.\n- Reopen the same disk or object-storage source to retain canonical data across process\n lifetimes.\n\n## Next steps\n\n Run the production-shaped HTTP interface on your machine.\n\n Compare local server, embedded, and Cloud execution.\n\n# SDK setup\n\nPage type: Guide\n\nEvery HelixDB SDK builds the same operation-tree request and sends it to\n`POST /v2/query`, so the query guides apply to all four languages. Pick the SDK for\nyour application's language:\n\n| SDK | Package | HTTP client | Embedded runtime |\n| --- | --- | --- | --- |\n| Rust | `helix-db` (imported as `helix_db`) | Async | Yes, behind the `embedded` feature |\n| TypeScript | `@helix-db/helix-db` (ESM, Node.js 20+) | Async | Yes |\n| Go | `github.com/helixdb/helix-db/sdks/go` | Yes | Not yet |\n| Python | `helix-db` (imported as `helixdb`) | Sync and async | Yes, with `helix-db-embedded` |\n\n Typed DSL, `#[query]` macro, and async HTTP client.\n\n Typed DSL and async client for Node.js 20 or newer.\n\n Query builder and HTTP client.\n\n Synchronous and asynchronous clients.\n\n## Next steps\n\nAfter setup, the [query walkthrough](/database/helix-db/core-concepts/overview) builds\nand runs a first query, and the query guides cover reads, writes, traversals,\nfiltering, projections, parameters, and search in every language.\n\n# Rust SDK\n\nPage type: Guide\n\nThe published `helix-db` 3.0.0 crate provides the query DSL, request types, async\nHTTP client, native graph helpers, and a feature-gated embedded client.\n\nThe package is published as `helix-db` and imported as `helix_db`.\n\n## Install\n\n```bash\ncargo add helix-db@3.0.0\n```\n\nOr add the dependency directly:\n\n```toml Cargo.toml\n[dependencies]\nhelix-db = \"3.0.0\"\nserde = { version = \"1\", features = [\"derive\"] }\nserde_json = \"1\"\ntokio = { version = \"1\", features = [\"macros\", \"rt-multi-thread\"] }\n```\n\n## Define a query\n\n```rust\nuse helix_db::dsl::prelude::*;\n\n#[query]\nfn find_users(tenant_id: String, limit: i64) -> ReadBatch {\n read_batch()\n .var_as(\n \"users\",\n g()\n .n_with_label(\"User\")\n .where_(Predicate::eq(\"tenantId\", tenant_id))\n .limit(limit)\n .value_map(Some(vec![\"$id\", \"name\", \"tenantId\"])),\n )\n .returning([\"users\"])\n}\n```\n\n`#[query]` converts typed arguments into request parameters, sets `query_name` to\nthe function name, and returns `Result`.\n\n## Execute\n\n```rust\nuse helix_db::Client;\n\nlet client = Client::new(Some(\"http://localhost:6969\"))?;\nlet request = find_users(\"acme\".to_string(), 25)?;\nlet response: serde_json::Value = client.query(request).send().await?;\n```\n\nUse `.with_api_key(Some(\"hx_...\"))` for Helix Cloud. Request-builder options can\nrequire the writer, require a warm read, or control durability waiting.\n\n## Build without the macro\n\n```rust\nlet request = QueryRequest::read(\n read_batch()\n .var_as(\"count\", g().n_with_label(\"User\").count())\n .returning([\"count\"]),\n)\n.with_query_name(\"count_users\");\n```\n\n## Embedded runtime\n\nEnable the `embedded` feature:\n\n```bash\ncargo add helix-db --features embedded\n```\n\nSee [Embedded database](/database/helix-db/start-here/local-development/embedded-database)\nfor storage, cache, and handle configuration.\n\n## Verify\n\nRust SDK crate docs are doctests, and the public `#[query]` README journeys are\ncompile-tested as examples:\n\n```bash\ncargo test --manifest-path sdks/rust/Cargo.toml --lib\ncargo test --manifest-path sdks/rust/Cargo.toml --doc\ncargo check --manifest-path sdks/rust/Cargo.toml --example basic_query\ncargo check --manifest-path sdks/rust/Cargo.toml --example readme_sdk_query\ncargo check --manifest-path sdks/rust/Cargo.toml --example readme_macros_query\n```\n\n## Next steps\n\n Learn the batch and traversal model.\n\n Select data by ID, label, or indexed property.\n\n# TypeScript SDK\n\nPage type: Guide\n\nThe published `@helix-db/helix-db` 3.1.0 package targets Node.js 20 or newer and\nemits the same operation-tree AST as the Rust, Go, and Python SDKs.\n\nThe package is ESM and requires Node.js 20 or newer.\n\n## Install\n\n```bash\nnpm install @helix-db/helix-db@3.1.0\n```\n\nThe package is ESM. Set `\"type\": \"module\"` or compile to ESM.\n\n## Define a query\n\n```ts\nimport {\n Predicate,\n defineParams,\n g,\n param,\n readBatch,\n} from \"@helix-db/helix-db\";\n\nexport const findUsersParams = defineParams({\n tenantId: param.string(),\n limit: param.i64(),\n});\n\nexport function findUsers() {\n return readBatch()\n .varAs(\n \"users\",\n g()\n .nWithLabel(\"User\")\n .where(Predicate.eq(\"tenantId\", findUsersParams.tenantId))\n .limit(findUsersParams.limit)\n .valueMap([\"$id\", \"name\", \"tenantId\"]),\n )\n .returning([\"users\"]);\n}\n```\n\n## Execute\n\n```ts\nimport { Client } from \"@helix-db/helix-db\";\n\nconst request = findUsers().toQueryRequest(\n findUsersParams,\n { tenantId: \"acme\", limit: 25n },\n { queryName: \"find_users\" },\n);\n\nconst result = await Client.server(\"http://localhost:6969\")\n .query(request)\n .send();\n```\n\nUse `withApiKey(\"hx_...\")` for Helix Cloud.\n\n## Integer safety\n\nThe SDK preserves 64-bit integers as `bigint`. Use `stringifyJson` or the request's\nserialization methods instead of `JSON.stringify` when a value can contain `bigint`.\n\n## Embedded runtime\n\nInstall the SDK and embedded runtime with\n`npm install @helix-db/helix-db @helix-db/helix-db-embedded`. See\n[Embedded database](/database/helix-db/start-here/local-development/embedded-database)\nfor storage, cache, and handle configuration.\n\n## Verify\n\n```bash\nnpm --prefix sdks/typescript test\n```\n\n## Next steps\n\n Build reads, writes, and parameters.\n\n Open HelixDB directly inside your process.\n\n# Go SDK\n\nPage type: Guide\n\nThe Go SDK builds the shared operation-tree AST and executes requests through a\ntyped HTTP client.\n\nVersion `v0.3.1` ships the server query builder and HTTP client. It does not\ndistribute the native bindings required by embedded execution or native graph\nalgorithms.\n\nThe module path remains `github.com/helixdb/helix-db/sdks/go`; it does not add a\n`/v3` suffix because the module itself has not reached major version 2.\n\n## Install\n\n```bash\ngo get github.com/helixdb/helix-db/sdks/go@v0.3.1\n```\n\n```go\nimport helix \"github.com/helixdb/helix-db/sdks/go\"\n```\n\n## Define a query\n\n```go\nfunc FindUsers(tenantID string, limit int64) helix.Request {\n\tq := helix.ReadQuery(\"find_users\")\n\ttenant := q.ParamString(\"tenant_id\", tenantID)\n\tmaxRows := q.ParamI64(\"limit\", limit)\n\n\treturn q.\n\t\tVarAs(\n\t\t\t\"users\",\n\t\t\thelix.G().\n\t\t\t\tNWithLabel(\"User\").\n\t\t\t\tWhere(helix.PredEq(\"tenantId\", tenant)).\n\t\t\t\tLimit(maxRows).\n\t\t\t\tValueMap(\"$id\", \"name\", \"tenantId\"),\n\t\t).\n\t\tReturning(\"users\")\n}\n```\n\n## Execute\n\n```go\nclient, err := helix.NewClient(\"http://localhost:6969\")\nif err != nil {\n\treturn err\n}\n\nvar response struct {\n\tUsers []map[string]any `json:\"users\"`\n}\nif err := client.Exec(ctx, FindUsers(\"acme\", 25), &response); err != nil {\n\treturn err\n}\n```\n\nWrite requests can pass `helix.WriterOnly()` and `helix.AwaitDurability(true)` execution\noptions. The client does not retry conflicts automatically.\n\n## Release scope\n\nUse `v0.3.1` with a local or remote Helix server through `/v2/query`. Embedded\nconstructors and `Client.Graph` return native-binding-unavailable errors in a\nstandard module installation.\n\n## Verify\n\n```bash\ncd sdks/go\ngo test ./...\n```\n\n## Next steps\n\n Bind typed values and bounds.\n\n Diagnose validation, conflict, and runtime failures.\n\n# Python SDK\n\nPage type: Guide\n\nThe Python SDK is published on PyPI as `helix-db` 0.3.4 and imported as `helixdb`.\nIts builder methods use `snake_case` and produce the same operation-tree AST as\nthe other HelixDB v3 SDKs.\n\n`helix-db` includes the synchronous and asynchronous server clients. Install\n`helix-db-embedded` as well only when the application runs HelixDB in process.\n\n## Install\n\n```bash\npython -m pip install helix-db==0.3.4\n```\n\n## Define a query\n\n```python\nfrom helixdb import Predicate, define_params, g, param, read_batch\n\nfind_users_params = define_params({\n \"tenant_id\": param.string(),\n \"limit\": param.i64(),\n})\n\ndef find_users():\n return (\n read_batch()\n .var_as(\n \"users\",\n g()\n .n_with_label(\"User\")\n .where(Predicate.eq(\"tenantId\", find_users_params.tenant_id))\n .limit(find_users_params.limit)\n .value_map([\"$id\", \"name\", \"tenantId\"]),\n )\n .returning([\"users\"])\n )\n```\n\n## Execute\n\n```python\nfrom helixdb import Client\n\nrequest = find_users().to_query_request(\n find_users_params,\n {\"tenant_id\": \"acme\", \"limit\": 25},\n query_name=\"find_users\",\n)\nresult = Client(\"http://localhost:6969\").query(request)\n```\n\nThe server clients have no native runtime dependency.\n\n### Async execution\n\nReuse one async client to reuse its HTTP connection pool. HTTP requests have no\ntimeout unless you explicitly configure one.\n\n```python\nimport asyncio\n\nimport httpx\n\nfrom helixdb import AsyncClient\n\nasync def execute_queries():\n limits = httpx.Limits(max_connections=20, max_keepalive_connections=10)\n async with AsyncClient(timeout=10.0, limits=limits) as client:\n return await asyncio.gather(\n client.query(request),\n client.execute(request, writer_only=True, timeout=2.0),\n )\n\nresults = asyncio.run(execute_queries())\n```\n\nCancellation propagates as `asyncio.CancelledError`, closes the response stream,\nand leaves the client reusable. The client owns and closes an injected HTTPX\nasync transport. `await client.close()` is idempotent.\n\n## Embedded runtime\n\nInstall the SDK and embedded runtime with\n`python -m pip install helix-db helix-db-embedded`. See\n[Embedded database](/database/helix-db/start-here/local-development/embedded-database)\nfor storage, cache, and handle configuration.\n\n```python\nimport asyncio\n\nfrom helixdb import AsyncClient, Disk, InMemory\n\nasync def query_embedded():\n writer = await AsyncClient.embedded(InMemory(\"app\"))\n async with writer:\n memory_result = await writer.query(request)\n\n reader = await AsyncClient.embedded_reader(Disk(\"./data\", \"seeded-app\"))\n async with reader:\n disk_checkpoint = await reader.query(request)\n\n return memory_result, disk_checkpoint\n\nresults = asyncio.run(query_embedded())\n```\n\nAsync embedded queries await native UniFFI operations directly. Use\n`asyncio.timeout(...)` for cancellation boundaries. Async native graph loading is\nnot part of this API; use the synchronous `Client.graph(...)` API.\n\n## Verify\n\n```bash\nPYTHONDONTWRITEBYTECODE=1 \\\nPYTHONPATH=sdks/python/src \\\npython -m unittest discover sdks/python/tests\n```\n\n## Next steps\n\n Follow the shared batch and traversal model.\n\n Open an in-process writer or reader.\n\n# Roadmap\n\nPage type: Reference\n\n## In progress\n\n- **Smarter cache warming** (ongoing)\n- **Reliability and availability improvements** (ongoing)\n- **Support for non-HA clusters**\n- **Backups and point-in-time recovery**\n- **Expanded query plans for better performance**\n\n## Up next\n\n- **SSO and SAML**\n- **RBAC and fine-grained API key permissions**\n- **AWS PrivateLink**\n- **Audit logs**\n\n## Recently shipped\n\n- **Local Docker deployment**\n- **Dashboard improvements**\n\nSee the [release notes](/database/helix-db/start-here/release-notes) for everything\nthat has shipped.\n\nHave a feature request? [Let us know on Discord](https://discord.com/invite/2stgMPr5BD) or [email us](mailto:founders@helix-db.com).\n\n# Release notes\n\nPage type: Reference\n\n- **Strong text search keeps working during ingest.** A `strong` text search now has its own bound, 512 MiB of unpublished text per partition by default (it was one publication's 64 MiB), and reuses analyses of pending text across searches. Ingest bursts of 20K–40K documents that made v0.0.10's strong text searches fail with `index_backpressure` now complete with no rejections, and a strong text search behind 5,000 pending documents dropped from about 200 ms to 30 ms. Set `HELIX_STRONG_TEXT_SEARCH_MAX_ANALYSIS_BYTES` to change the bound; past it the search fails with retryable `index_backpressure` (`pending_text_analysis_bytes`).\n- **Strong searches decode pending index work once per request.** Several searches in one request share one decoded copy of the pending queue, decoding and exact scoring run off the async workers so they no longer stall other requests, and four strong vector searches in one request behind 160K pending 768-dimension changes went from about 5.0 s to 2.2 s.\n- **Strong vector searches are bounded.** A `strong` vector search decodes and scores at most the index's retained-byte limit of unpublished work by default (1 GB, so writes reach backpressure first). Set `HELIX_STRONG_VECTOR_SEARCH_MAX_PENDING_BYTES` to lower it; past it the search fails with retryable `index_backpressure` (`pending_vector_bytes`).\n- **Queue admission tracks real memory.** Each queued index operation now counts its encoded size plus 576 bytes against the 1 GB per-index limit, so a backlog of many small operations, such as deletes, can no longer use several times the limit in memory. Such backlogs reach `index_backpressure` sooner; the 250,000 pending-entity limit is unchanged.\n- **Writers reopen faster with a large backlog.** Opening a writer loads its queued index work one queue at a time instead of decoding every queue at once: a 2.26 GB backlog opened in about 5 s instead of 25 s, with peak memory bounded by the largest queue instead of the whole backlog.\n- **Publication drains in linear time.** Selecting work to publish no longer rescans the whole queue each time, which was 9.4 s of bookkeeping per 250K-operation drain and is now 0.16 s, and a queue retired by an index drop is discarded without being re-read.\n- No storage changes since v0.0.10: upgrading from v0.0.10 needs no migration. Upgrading from v0.0.9 or earlier follows the v0.0.10 notes below.\n- **CLI 3.4.4** defaults to image v0.0.11. Projects that saved a `tag` in `helix.toml` keep using it until you change it.\n\n- **Upgrading: index storage version 5.** The first time a v0.0.10 writer opens a database, it upgrades the index storage version from 4 to 5. It rewrites only the version marker and rebuilds no index. After that, v0.0.9 and earlier refuse to open the database with `unsupported_index_storage_version`:\n - Upgrade readers before the writer; v0.0.10 readers serve both versions.\n - Never start a v0.0.9-or-earlier writer against an upgraded database.\n - Take a backup before upgrading if you may need to roll back.\n- **[Vector and text indexes publish asynchronously](/database/helix-db/query-guides/search-consistency).** A write commits its graph change together with a durable queued index operation, and a background index worker publishes it into the vector or text index, so writes no longer wait on index maintenance. Steady vector insert publication went from 6.2 to 239 per second. Index builds no longer livelock under concurrent writes: on a c7i.8xlarge with 100 writes/s during the build, backfilling 100K 768-dimension vectors on disk finished in about 2,500 s, where v0.0.9 never finished.\n- **Search consistency.** Read requests set `search_consistency` to `strong` (the default) or `eventual`. `strong` searches include every committed write, published or not. `eventual` searches include a bounded amount of unpublished work and serve the rest as last published, so they can return a node or edge that has since changed tenant, label or indexed property. Write requests always search `strong`, and a write batch that searches an index fails with a retryable `transaction_conflict` if the index worker publishes into that index first. The SDK options ship in the next SDK releases; until then, send `search_consistency` in a direct HTTP request.\n- **[Index backpressure](/database/helix-db/query-guides/search-consistency#index-backpressure).** Each index retains at most 1,000,000,000 bytes or 250,000 pending entities of unpublished work. Three cases fail with `index_backpressure` (HTTP 429, `retryable: true`) before the request takes effect: a write past either limit, a whole-index `strong` search behind more than 800 unpublished changes, and a `strong` text search that would analyze more unpublished text than one publication may (64 MiB by default). Retry it unchanged with bounded backoff. A single write that stages more than 8 MiB of index work for one index fails with `index_operation_batch_too_large` (HTTP 400); split it.\n- **[Text write limits are per document](/database/helix-cloud/operate/limits#active-text-mutation-admission).** `active_text_mutation_limit_exceeded` now checks each indexed document against its own allowances, about 16,000 unique terms, instead of limiting a write to 512 text-indexed entities.\n- **A failing index entry no longer stalls its index.** An entry whose index update fails the same way every time, for example on damaged index data, is held back while the rest of the index keeps publishing. `GET /healthz` counts it under `blocked_index_entity_count`, the server logs an error naming it, and the worker retries it about once a minute. See [troubleshooting](/database/helix-db/query-guides/troubleshooting).\n- **Fixed: `missing simhash` after re-embedding and then deleting a node** (the v0.0.9 known issue). Re-embedding a node no longer loses track of the vector index (HNSW) links that point at it, so deleting it later removes them all, and a node is never linked to itself. Indexes written by v0.0.9 and earlier can still hold such links; drop and recreate the vector index to repair them.\n- **Fixed: counts over a range index with other indexed filters.** A `.count()` over `N.where(...)` or `E.where(...)` that combined a range condition with other indexed conditions counted the range alone, for example 149 rows instead of 49. Counts now apply every filter.\n- **CLI 3.4.3** defaults to image v0.0.10. Projects that saved a `tag` in `helix.toml` keep using it until you change it.\n\n- **Upgrading S3 deployments** — S3 storage now always writes a local disk cache, so an S3 container that ran v0.0.8 or earlier can fail or use more resources after the upgrade:\n - The cache directory, `/var/cache/helix` unless `HELIX_DISK_CACHE_DIR` names another, must be writable. Mount a volume there (required with a read-only root filesystem), and set `HELIX_DISK_CACHE_DIR` when running as a user other than `65532`.\n - The hard open-file limit must be at least 26,600 at the default budget (about 8,200 or fewer at 1 GiB or less). Raise it with `--ulimit nofile=65536:65536`.\n - RSS grows by the block cache's index, about 20–70 MiB at the default budget and twice that briefly after a restart.\n - Without `HELIX_DISK_CACHE_BYTES`, the 8 GiB default budget must fit the cache's filesystem, or startup fails.\n- **[S3 always uses a local disk cache](/database/helix-db/start-here/local-development/local-server#add-a-local-disk-cache)** in `/var/cache/helix` by default, with an 8 GiB default budget. Memory-only S3 is gone: once a vector index outgrew the memory cache, every graph hop waited on its own S3 request. `HELIX_DATA_DIR` and in-memory storage are unchanged.\n- **Faster first vector searches on S3.** Cold batch reads overlap their block fetches, expansions read parents concurrently, and projections prefetch the records they need. After open, the server also warms vector search rows into the disk cache in the background; readiness never waits for it. `HELIX_DISK_CACHE_WARM=off` (default `on`) turns startup warming off. On 2 CPUs, 4 GiB of memory and an 8 GiB cache over S3, the first global vector top-50 after open went from 30.8 s on v0.0.7 to 714 ms once the ~26 s warm finished.\n- **Index sets are kept across `ForEach` iterations and unrelated writes** in the same request, which removes the v0.0.8 known limitation. A set is read again only when an iteration binds a parameter it depends on, or a write creates, deletes or changes indexed properties of nodes with its label. A batch that expands, filters on an index and adds an edge per iteration runs about twice as fast.\n- **Source filters and counts always use indexes.** `N.where(...)`, `E.where(...)` and counts on indexed properties no longer scan the label, including partly indexed ORs, long `IN` lists, parameter lists, `== null`, and counts over `.as()` / `.store()`. A label scan only happens when no condition has an index. On 50k rows, counts after `.as()` went from up to 1.1 s to under 5 ms, and 200-value `IN` lists from up to 1.5 s to about 0.2 s.\n- **Upgrading** — the stored data format is unchanged. Databases written by v0.0.8 open directly with v0.0.9.\n- **Known issue** — updating a node's vector (re-embedding it) and later deleting that node can leave vector index (HNSW) links pointing at the deleted node, and searches that reach them fail with `missing simhash`. Earlier releases are affected too, and a fix is in progress. To repair an affected index, drop and recreate the vector index.\n- **CLI 3.4.2** defaults to image v0.0.9. With `--disk` or S3 storage, `helix start` mounts a per-instance `helix---cache` volume at `/var/cache/helix` for the disk cache, with a 64 MiB budget in disk mode and 1 GiB for an S3 bucket. `helix stop` keeps it and `helix prune` removes it.\n\n- **Filters after a traversal always use indexes.** A `.where(...)` on indexe"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","rawUrl":"https://raw.githubusercontent.com/HelixDB/helix-db/HEAD/AGENTS.md","title":"AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"### approach\n\n- ⁠Make invalid states unrepresentable using algebraic data types (e.g. enums).\n- ⁠Use code coverage tools to make sure unit test coverage covers every edge case. This should be easily doable if invalid states are unrepresentable.\n- Keep things modular.\n- Define clear contract boundaries for testability. Document them all, and make sure doc comment examples are ran as tests.\n- Use assertions for invariants when encoding within types is not feasible.\n- Use clippy and fix code smells reported.\n- Prefer iterators, monadic logic, and functional concepts. Where not possible for performance, document why.\n- Make invalid state unrepresentable.\n- Prefer importing modules over long lists of types. Using `module::Type` at call sites is fine, keeps names unambiguous, and reduces namespace-collision churn.\n- Be wary of things that don't scale. If you have reason to believe why it wont, report back to the user explaining why.\n- instead of if let { ... } use let Some(…) = … else { }\n- avoid over using helper functions where possible. duplicating a single line of code is clearer than polluting with helper functions. if a large piece of functionality is shared or repeated multiple times then it can be abstracted but you should favour inline code where possible. small pieces of functionality should be inlined instead of abstracted.\n- Do not stage, commit (including locally), push, publish artifacts, or trigger remote CI unless explicitly instructed. Keep work-session timestamps out of authored reports and documentation.\n- As you make changes, if it is small (e.g. single/couple line addition) or if it is critical to your implementation, make the change.\n- Clean up any temporary files or directories you create during your work (including in /private/tmp)\n- ⁠match { Example(_) => ExampleVariant } -> use derive macro for Variant and the conversions instead of littering our code with the extra types and functions\n⁠- ⁠instead of children structs holding an Arc, maybe just let them take in a &Db in every method that requires it.\n- when that's not feasible, evaluate whether passing in an Arc is fine, and if not make sure that holding an Arc won't leak the memory based on how the child is stored in parent.\n\n### Slice access\n⁠When accessing or creating slices, for every access or slice don't minify it to start..end constants, always keep the additions of offsets explicit.\nInstead of making `start` and `end` variables in the place of `const` values, use the `const` values directly, adding them up instead.\n\ne.g. you should do the following\n\n```rust\nconst PREFIX_LEN: usize = core::mem::size_of::();\nconst INDEX_PREFIX_LEN: usize = core::mem::size_of::();\nconst PROPERTY_HASH_MAX_LEN: usize = core::mem::size_of::();\nconst VALUE_HASH_MAX_LEN: usize = core::mem::size_of::();\n\nlet property_hash = slice[INDEX_PREFIX_LEN..INDEX_PREFIX_LEN + PROPERTY_HASH_MAX_LEN]\n .try_into()\n .expect(\"property hash slice is 4 bytes\");\n```\n\n### Clippy and formatting\n\nRun clippy and formatting to check for code smells and formatting issues.\n\n```bash\ncargo clippy --workspace -- -D warnings\nrustfmt --edition 2024 --check\n```\n\nyou should run formatting and clippy before finishing your work. Rust crates in this workspace use edition 2024 from their `Cargo.toml`; do not pass `--edition 2024` to `cargo clippy`, because Cargo does not accept that flag for Clippy. Use a current stable Rust toolchain with the matching Clippy component installed.\n\n### Database Key/Value Construction, Parsing, and Use\n\n- ALL database key construction, parsing, and serialisation should be done using the structs in crates/db/src/encoding/v2\n - There are structs here that make building invalid keys impossible and it ensures call sites remain standardised and improves testability\n- ALL database value construction, parsing, and serialisation should be done using the structs in crates/db/src/encoding/v2/values\n - There are structs here that make building invalid keys impossible and it ensures call sites remain standardised and improves testability\n - We are in the process of moving more values to this dir. If you notice inline value use, please either add it to crates/db/src/encoding/v2/values if it is small (e.g. single variant addition) or if it is a major change just note it down.\n\n","isInternal":false,"tokens":957,"sizeBytes":4366},{"name":"llms-full.txt","path":"docs/llms-full.txt","rawUrl":"https://raw.githubusercontent.com/HelixDB/helix-db/HEAD/docs/llms-full.txt","title":"docs - LLM Full Documentation Context","category":"root-instruction","format":"text","content":"# HelixDB\n\n> HelixDB combines a property graph, approximate vector search, and BM25 full-text search behind one operation-tree query model. Requests run through Cloud, a local server, or the embedded runtime. This file is the full markdown corpus for AI agents.\n\n\n# Introduction\n\nPage type: Concept\n\nHelixDB is a graph database with native vector and full-text search, built on object\nstorage. It stores and searches knowledge and context for applications where both\nexplicit structure and meaning matter.\n\nBecause graph, vector, and text retrieval live in one database, an application can\nwork with connected entities, semantically similar content, and exact terms without\nsynchronizing separate stores. Teams use HelixDB to build enterprise company brains,\nlarge-scale people search, and AI agent swarms.\n\nNew to these ideas? The [learning center](/learn) explains graph databases, vector and\nfull-text search, and AI agent memory from first principles.\n\n```mermaid\n%%{init: {\"themeCSS\": \".cluster-label { translate: -140px 0; }\"}}%%\nflowchart TB\n knowledge[\"Documents, conversations, events, users\"]\n\n subgraph brain[\"Company brain in HelixDB\"]\n relationships[\"Graph Data\"]\n vector[\"Vector search\"]\n text[\"Text search\"]\n context[\"Shared memory and context\"]\n\n relationships --> context\n vector --> context\n text --> context\n end\n\n knowledge --> relationships\n knowledge --> vector\n knowledge --> text\n\n context --> agents[\"AI agent swarms\"]\n context --> search[\"Enterprise search and knowledge bases\"]\n context --> apps[\"Company Brains\"]\n```\n\n## How it works\n\nEverything in HelixDB is one labeled property graph. Nodes are your entities, directed\nedges are the relationships between them, and both carry typed properties.\n\nSearch is not a second system bolted on top. A vector, text, or secondary index is an\naccess path over a property that already lives on a node or edge: the embedding on a\nchunk, the body text of a document, or the `status` field you filter by. That has\nthree consequences:\n\n- **The graph stays the source of truth.** A semantic match and the relationships\n around it are the same data, read in the same transaction.\n- **Nothing needs synchronizing.** There is no separate graph store, vector store, or\n search cluster to keep consistent.\n- **Edges are searchable too.** An index is scoped to a label and a property rather\n than a special node type, so you can search and filter relationships as well as\n entities.\n\n## What you get\n\n- **ACID transactions** across graph, vector, and text data.\n- **Vector search** with prefiltering and over 90% recall.\n- **Full-text search** for exact terms and keyword relevance.\n- **Equality and range filtering** on property values.\n- **Search and filtering on nodes and edges**, not just nodes.\n- **Object storage as the source of truth**, so storage scales independently of compute.\n- **Horizontal scaling** across multi-tenant and single-tenant deployments, with BYOC\n coming soon.\n\n## Why object storage\n\nMost graph databases keep all data on one machine's disk, and in the worst case\nentirely in memory. That caps how much data you can store and makes large graphs\nexpensive.\n\nHelixDB keeps object storage as the source of truth and uses NVMe and memory only as\ncaches. Storage scales separately from compute, so a dataset can grow far beyond the\ncapacity of the machines that serve it while latency and cost stay low.\n\n## Next steps\n\n Start a local instance and run the generated query.\n\n Learn how nodes, edges, properties, and indexes represent your data.\n\n Discuss large-scale Helix Cloud workloads with the founding team.\n\n# Get started\n\nPage type: Tutorial\n\nThis is the canonical local HelixDB quickstart. You will create a project, start\nthe generated `dev` instance, run the generated JSON request, and stop the\ninstance.\n\n## Prerequisites\n\n- Docker, or Podman configured as described below\n- A terminal on macOS or Linux, or PowerShell on Windows\n\nmacOS and Linux:\n\n```bash\ncurl -sSL \"https://install.helix-db.com\" | bash\n```\n\nWindows PowerShell:\n\n```powershell\nirm https://raw.githubusercontent.com/HelixDB/helix-db/main/crates/cli/install.ps1 | iex\n```\n\nIf the CLI is already installed, run [`helix update`](/cli/command-reference/update).\n\nCreate and enter an empty directory, then initialize it:\n\n```bash\nmkdir my-helix-app\ncd my-helix-app\nhelix init local\n```\n\n`helix init local` creates:\n\n- `helix.toml` with one local instance named `dev` on port `6969`.\n- `.helix/` for CLI-managed instance state.\n- `.gitignore` entries for `.helix/`, `.env`, `target/`, and `*.log`.\n- `AGENTS.md` with the current CLI workflow for coding agents.\n- `examples/request.json` with a runnable read request.\n\nIt does not create a Rust, TypeScript, Go, or Python project. Choose an SDK\nafter this CLI journey.\n\nIf you use Podman, set `container_runtime = \"podman\"` under `[project]` in\n`helix.toml` before you start the generated instance. New projects otherwise\ndefault to Docker.\n\n```bash\nhelix start dev\n```\n\nThe CLI starts the local container, publishes it at `http://localhost:6969`,\nand waits for the database health check before it returns.\n\nThe default storage mode is in-memory. Stopping the instance removes its data.\nUse `helix start dev --disk` when you need local persistence.\n\n```bash\nhelix query dev --file examples/request.json\n```\n\nThe generated request counts nodes with the `User` label. A new database\nreturns a `node_count` of zero. Edit the JSON file and run the same command\nagain to iterate.\n\n```bash\nhelix stop dev\n```\n\n`helix stop` is idempotent, so it also exits successfully when the instance is\nalready stopped.\n\n## Use an SDK\n\nThe SDKs build the same JSON operation tree that `helix query` sends to\n`POST /v2/query`. Initialize a normal language project and install one released\nSDK:\n\n```bash Rust\ncargo add helix-db@3.0.0 tokio serde_json\n```\n\n```bash TypeScript\nnpm install @helix-db/helix-db@3.1.0\n```\n\n```bash Go\ngo get github.com/helixdb/helix-db/sdks/go@v0.3.1\n```\n\n```bash Python\npython -m pip install helix-db==0.3.4\n```\n\nContinue with the full setup guide for your language:\n\n Build and execute typed Rust queries.\n\n Build and execute TypeScript queries.\n\n Build and execute Go queries.\n\n Build and execute synchronous or asynchronous Python queries.\n\n## Next steps\n\n Learn how SDK builders become the JSON request sent to HelixDB.\n\n Learn how nodes, edges, labels, and properties fit together.\n\n Add, update, and remove graph data.\n\n See every current CLI command and option.\n\n# Deployment options\n\nPage type: Concept\n\nEvery deployment option runs the same queries with the same SDKs, so you can develop\nagainst one and deploy to another without changing application code. Choose based on\nwhere the engine runs, where data is stored, and who operates it.\n\n| Mode | Best for | Interface | Storage | Availability |\n| --- | --- | --- | --- | --- |\n| Helix Cloud | Production services with managed operations | HTTPS | Managed object storage | Highly available |\n| Local server | Development, production-shaped testing, and self-hosting | HTTP | Memory or S3-compatible storage | Single node |\n| Embedded | In-process applications and local tools | Native SDK call | Memory, disk, or object storage | In process |\n\n## Helix Cloud\n\nHelix Cloud runs a highly available cluster that provides managed deployment, storage,\ndatabase authentication, and read scaling. It supports multi-tenant and single-tenant\ndeployments; BYOC is coming soon.\n\n## Local server\n\nThe local server runs the standalone HelixDB container on your own machine or\ninfrastructure. It exposes the same `POST /v2/query` interface as Helix Cloud, which\nmakes it the default development target: code written against it works unchanged in\nCloud.\n\n## Embedded\n\nEmbedded clients open the engine inside your process and skip HTTP entirely. Rust,\nTypeScript, and Python ship embedded runtimes; the Go SDK is currently HTTP-only.\n\n## Which should I use?\n\n- **Building a networked application?** Develop against the local server.\n- **Going to production?** Use Helix Cloud for managed operations and high\n availability.\n- **Shipping a tool or app that owns its data?** Use embedded mode when process-local\n execution simplifies your architecture and the SDK's native packaging fits how you\n distribute.\n\n## Next steps\n\n Run the server locally with memory or persistent storage.\n\n Create a managed database and connect to it.\n\n Open a writer or reader and review current SDK availability.\n\n# Local server\n\nPage type: Guide\n\nThe `ghcr.io/helixdb/helixdb:v0.0.12` image runs the standalone HelixDB server.\nIt supports Linux on amd64 and arm64.\nIt exposes the same operation-tree request contract used by Helix Cloud at\n`POST /v2/query`; gateway-only Cloud features are not included.\n\n## Choose storage\n\n| Mode | Persistence | Use when |\n| --- | --- | --- |\n| Memory | Lost when the server stops | Fast local iteration and tests |\n| Native directory (`HELIX_DATA_DIR`) | Preserved in a mounted volume or directory | Running the image directly with local persistence |\n| CLI disk (`--disk`) | Preserved in a CLI-managed SeaweedFS volume | Testing restart and persistence through the CLI |\n| Existing S3-compatible store | Owned outside Helix | Reusing SeaweedFS, Ceph, LocalStack, or AWS S3 |\n\n## Start with the CLI\n\nmacOS and Linux:\n\n```bash\ncurl -sSL \"https://install.helix-db.com\" | bash\n```\n\nWindows PowerShell:\n\n```powershell\nirm https://raw.githubusercontent.com/HelixDB/helix-db/main/crates/cli/install.ps1 | iex\n```\n\nThen, in your shell:\n\n```bash\nmkdir my-helix-app\ncd my-helix-app\nhelix init local --name dev # add --disk to make persistence the project default\nhelix start dev # add --disk to persist this instance\n```\n\nThe standalone server accepts queries at `http://localhost:6969/v2/query`.\n\nFor an existing project, set `tag = \"v0.0.12\"` in its `[local.dev]` block in\n`helix.toml` before starting it. An explicitly saved tag overrides the CLI default.\n\nThe first time v0.0.10 or later opens a persisted database, it upgrades the index storage\nversion, and v0.0.9 and earlier then refuse to open that database. Back up the data\nbefore changing the tag if you may need to roll back.\n```bash\nhelix query dev \\\n -e 'readBatch().varAs(\"count\", g().nWithLabel(\"User\").count()).returning([\"count\"])'\n```\n\nThe default mode is in-memory. `helix stop` and `helix restart` discard its data.\n\n## Use an existing object store\n\nPlace credentials in a project-root `.env` file or export them:\n\n```dotenv .env\nAWS_ACCESS_KEY_ID=your-access-key\nAWS_SECRET_ACCESS_KEY=your-secret-key\n# AWS_SESSION_TOKEN=your-session-token\n```\n\n```bash\nhelix start dev \\\n --storage-uri s3://helix-db/my-app \\\n --s3-region us-east-1 \\\n --s3-endpoint-url https://s3.example.com \\\n --persist\n```\n\nAdd `--s3-allow-http` only for a plain HTTP endpoint.\n\n```bash\nhelix start dev \\\n --storage-uri s3://my-bucket/my-app \\\n --s3-region eu-west-2 \\\n --persist\n```\n\n`--persist` stores the resolved configuration in `helix.toml`. Helix does not delete\nexternally managed object-store data during stop, restart, or prune.\n\n## Run the image directly\n\nMemory mode is selected by leaving both `HELIX_DATA_DIR` and `S3_BUCKET` unset:\n\n```bash\ndocker run --rm --name helixdb \\\n -p 6969:8080 \\\n ghcr.io/helixdb/helixdb:v0.0.12\n```\n\nThe standalone server exposes liveness and readiness checks:\n\n```bash\ncurl -fsS http://127.0.0.1:6969/healthz\ncurl -fsS http://127.0.0.1:6969/readyz\n```\n\nDo not set `S3_BUCKET=IN_MEMORY`. Every defined `S3_BUCKET` value selects\nS3-compatible storage and is interpreted as a real bucket name. Setting\n`HELIX_DATA_DIR` and `S3_BUCKET` together causes startup to fail.\n\n## Run with native directory persistence\n\nSet `HELIX_DATA_DIR` to a mounted directory inside the container:\n\n```bash\ndocker volume create helixdb-data\ndocker run --rm --name helixdb \\\n -p 6969:8080 \\\n -e HELIX_DATA_DIR=/var/lib/helix \\\n --mount type=volume,source=helixdb-data,target=/var/lib/helix \\\n ghcr.io/helixdb/helixdb:v0.0.12\n```\n\nStop the server with `docker stop helixdb`. Starting a new container with the\nsame volume preserves its database. Removing the volume deletes the data.\nThis mode needs no object store; the CLI's `--disk` mode uses SeaweedFS.\n\nThe image runs as user and group `65532:65532`. Its `/var/lib/helix` directory\nis prepared for that user, including when initializing a new Docker named volume.\nIf you use a bind mount or an existing volume, its directory must be writable by\nthat user.\n\n## Run with SeaweedFS persistence\n\nThis Compose configuration runs SeaweedFS as a single-node S3 store with a\nstatic identity, creates the `helix-db` bucket on startup, and stores HelixDB\nobjects in the `seaweedfs-data` volume. HelixDB starts once a signed request\nto the bucket succeeds:\n\n```yaml docker-compose.yaml expandable\nservices:\n seaweedfs:\n image: ghcr.io/chrislusf/seaweedfs:4.47@sha256:ce9e796f1fe6f06968f4c04bdaf8f678dad9c8acdfef3d244133d71bfa6bf882\n command:\n - mini\n - -dir=/data\n - -bucket=helix-db\n - -s3.config=/etc/seaweedfs/s3.json\n - -master.telemetry=false\n - -admin.ui=false\n - -webdav=false\n - -s3.port.iceberg=0\n - -s3.port.lance=0\n restart: unless-stopped\n configs:\n - source: seaweedfs-s3\n target: /etc/seaweedfs/s3.json\n volumes:\n - seaweedfs-data:/data\n healthcheck:\n test:\n - CMD\n - curl\n - -fsS\n - -o\n - /dev/null\n - --max-time\n - \"2\"\n - -I\n - --aws-sigv4\n - aws:amz:us-east-1:s3\n - --user\n - helix:helix-local-secret\n - http://127.0.0.1:8333/helix-db\n interval: 1s\n timeout: 5s\n retries: 120\n\n helix:\n image: ghcr.io/helixdb/helixdb:v0.0.12\n restart: unless-stopped\n depends_on:\n seaweedfs:\n condition: service_healthy\n ports:\n - \"6969:8080\"\n environment:\n S3_BUCKET: helix-db\n S3_REGION: us-east-1\n DB_PATH: db/\n AWS_ACCESS_KEY_ID: helix\n AWS_SECRET_ACCESS_KEY: helix-local-secret\n AWS_ENDPOINT: http://seaweedfs:8333\n AWS_ALLOW_HTTP: \"true\"\n\nconfigs:\n seaweedfs-s3:\n content: |\n {\n \"identities\": [\n {\n \"name\": \"helix\",\n \"credentials\": [\n {\"accessKey\": \"helix\", \"secretKey\": \"helix-local-secret\"}\n ],\n \"actions\": [\"Read:helix-db\", \"Write:helix-db\", \"List:helix-db\"]\n }\n ]\n }\n\nvolumes:\n seaweedfs-data:\n```\n\nInline `configs` content needs Docker Compose 2.23.1 or later. The SeaweedFS\ncontainer is not published to the host. Change the example credentials in all\nthree places if you expose it.\n\nRun `docker compose down` to replace the HelixDB container without deleting\nthe SeaweedFS data. `docker compose down -v` deletes the persisted database.\n\nFor an existing object store, use the same HelixDB environment variables and\nomit the SeaweedFS service. For AWS S3, omit the endpoint and HTTP override.\n\nHelixDB's storage engine needs S3 conditional writes: `If-None-Match: *` on\ncreate and `If-Match` on replace must fail with HTTP 412 when the condition\ndoes not hold. A store that ignores them can silently lose data. AWS S3 and\nSeaweedFS 4.09 or later enforce both.\n\n| Variable | Purpose |\n| --- | --- |\n| `HELIX_DATA_DIR` | Selects native disk storage and names its container directory; mount a volume there for persistence |\n| `S3_BUCKET` | Selects S3 mode and names the object-store bucket; omit both storage selectors for memory mode |\n| `S3_REGION` | Region supplied to the S3 client; falls back to `AWS_REGION`, then `AWS_DEFAULT_REGION`, then `us-east-1` |\n| `DB_PATH` | Logical database prefix inside the selected store, including under `HELIX_DATA_DIR`; defaults to `db/` |\n| `AWS_ACCESS_KEY_ID` | Access key |\n| `AWS_SECRET_ACCESS_KEY` | Secret key |\n| `AWS_SESSION_TOKEN` | Optional temporary-credential token |\n| `AWS_ENDPOINT` or `AWS_ENDPOINT_URL_S3` | Non-AWS S3 endpoint |\n| `AWS_ALLOW_HTTP` | Set to `true` or `1` to permit an HTTP endpoint |\n| `HELIX_STRONG_VECTOR_SEARCH_MAX_PENDING_BYTES` | Most unpublished vector work, in bytes, one `strong` vector search scores before it fails with `index_backpressure`; defaults to the index's retained-byte limit (1,000,000,000), which writes reach first. See [Search consistency](/database/helix-db/query-guides/search-consistency#searches-behind-unpublished-changes) |\n| `HELIX_STRONG_TEXT_SEARCH_MAX_ANALYSIS_BYTES` | Most unpublished text, in analysis bytes, one `strong` text search includes per partition before it fails with `index_backpressure`; defaults to 512 MiB (536,870,912). See [Search consistency](/database/helix-db/query-guides/search-consistency#searches-behind-unpublished-changes) |\n\nThe endpoint must be reachable from inside the container; container `localhost` is not\nthe host machine. `DB_PATH` is a logical prefix, not the storage directory. To use\nnative directory persistence, set `HELIX_DATA_DIR` and mount the directory there.\n\n## Add a local disk cache\n\nWith `S3_BUCKET`, the server always keeps recently read data on local disk, ideally\nNVMe, in `/var/cache/helix` unless `HELIX_DISK_CACHE_DIR` names another directory.\nVector indexes on S3 need it: once an index outgrows the memory cache, every graph\nhop that misses it would otherwise wait on its own S3 request. Mount a volume at\n`/var/cache/helix` so the cache survives restarts; without one, each new container\nstarts with an empty cache. With `HELIX_DATA_DIR`, set `HELIX_DISK_CACHE_DIR` to add\nthe disk cache. Memory storage rejects the cache variables.\n\nThe disk cache needs v0.0.7 or later, and the v0.0.6 image and earlier ignore the\n`HELIX_DISK_CACHE_*` variables. v0.0.7 and v0.0.8 cache S3 on disk only when\n`HELIX_DISK_CACHE_DIR` is set, so the example below sets it to the default.\n```bash\nsudo mkdir -p /data/helix-cache\nsudo chown 65532:65532 /data/helix-cache\ndocker run --rm --name helixdb \\\n -p 6969:8080 \\\n -e S3_BUCKET=my-bucket \\\n -e S3_REGION=eu-west-2 \\\n -e HELIX_DISK_CACHE_DIR=/var/cache/helix \\\n -e HELIX_DISK_CACHE_BYTES=107374182400 \\\n -v /data/helix-cache:/var/cache/helix \\\n ghcr.io/helixdb/helixdb:v0.0.12\n```\n\nIn Compose, add a volume at `/var/cache/helix` to the `helix` service. A new\nnamed volume mounted there is already writable; a bind mount must be owned by\n`65532:65532`. When running as another user or outside the image, set\n`HELIX_DISK_CACHE_DIR` to a directory that user can write. With a read-only root\nfilesystem, mount a writable volume (for example a tmpfs or `emptyDir`) at the cache\ndirectory. Use one cache directory per running server and per database; changing\n`DB_PATH` on the same directory leaves the old database's full-text cache behind.\n\n| Variable | Purpose |\n| --- | --- |\n| `HELIX_DISK_CACHE_DIR` | Disk cache directory, created if needed. Defaults to `/var/cache/helix` with `S3_BUCKET`; with `HELIX_DATA_DIR`, setting it enables the disk cache |\n| `HELIX_DISK_CACHE_BYTES` | Total disk budget in bytes, from 64 MiB to 1 TiB; defaults to 8 GiB |\n| `HELIX_DISK_CACHE_MEMORY_BYTES` | Memory tier of the block cache in bytes; defaults to 640 MiB |\n| `HELIX_DISK_CACHE_WARM` | `on` (the default) or `off`: whether the server warms the disk cache at startup |\n\nHalf of the disk budget caches object-store files, 3/8 caches database blocks,\nand the rest caches full-text search data. With `S3_BUCKET`, the object-store cache\nalso keeps the files the server writes; with `HELIX_DATA_DIR` they are already on\nlocal disk, so it keeps only the files the server reads. Changing the budget\nusually changes the block size, which discards the database-block cache at startup\nso it refills from the object store. The object-store cache keeps its files and\nevicts down to a smaller budget as it admits new data. Full-text search data is\ncached on demand, once searches have used it twice; the server downloads none of it\nat startup. At startup and on every admission the full-text cache evicts down to\nits share. Each of these trims spares data admitted or recorded as used in the\nsecond before it (use is recorded at most once a minute) and data still open in\nsearches or the 64 MiB full-text memory cache, so the cache can stay over its share\nby that data until the next admission. It never caches a split larger than its\nwhole share. After a restart, the first search to use each cached split reads and\nchecksums the whole split, up to 64 MiB, before it answers. Budget at least twice\nthe data the server reads often: the object-store cache fetches whole file parts\n(4 MiB, or smaller under a 2 GiB budget), so once that data outgrows half the\nbudget, cold reads fetch more than memory-only caches would. The budget must also\nfit on the cache's filesystem: its free space plus what the cache already uses.\nWhen `HELIX_DISK_CACHE_BYTES` is unset and the 8 GiB default does not fit, startup\nfails naming the variable; without a volume the cache would otherwise share, and\ncould fill, the filesystem of the container runtime. A budget you set that does not\nfit only logs a warning at startup.\n\nOnce storage opens, the server warms the disk cache in the background: it caches the\ndatabase blocks that index the newest files and, with `S3_BUCKET`, the rows vector\nsearches read, using at most half the object-store cache. The warm delays neither\nstartup nor readiness; queries that arrive first read from the object store as usual.\nSet `HELIX_DISK_CACHE_WARM=off` to skip it, and the caches then fill only as queries\nread.\n\nThe block cache also indexes its disk share in memory, outside\n`HELIX_DISK_CACHE_MEMORY_BYTES`. Once full, the index takes roughly 2–9 MiB of RAM\nper GiB of `HELIX_DISK_CACHE_BYTES` (about 20–70 MiB at the default, 2–9 GiB at\n1 TiB), and a restart briefly needs about twice that while it rebuilds the index.\nSize the container's memory limit for this index as well as the memory tier.\n\nThe block cache keeps up to 32,768 files open, so the server needs at least 34,792\nopen files in the worst case (26,600 at the default budget), plus one per open\nfull-text split. It raises its soft open-file limit to the hard limit at startup.\nIf the container's hard limit is below that minimum, startup fails naming\n`HELIX_DISK_CACHE_BYTES`; raise the hard limit with `--ulimit nofile=65536:65536`.\nLowering the budget is not a reliable fix above about 3 GiB, where the file count\ndoes not fall steadily with it; budgets of 1 GiB or less need about 8,200 or fewer.\nRun natively on macOS, the limit is also capped by `sysctl kern.maxfilesperproc`.\n\nStartup also fails with a message naming the variable when a size is invalid or\nout of range, a size is set with `HELIX_DATA_DIR` but without `HELIX_DISK_CACHE_DIR`,\nthe default budget does not fit, the cache directory is not writable or cannot be\nlocked (some network and FUSE filesystems do not support locks), or another running\nserver already uses it. Stop the old container before starting its replacement on\nthe same cache directory.\n\nAn S3 container that ran v0.0.8 or earlier used no local disk, so it can fail or\nuse more resources after upgrading: it needs a hard open-file limit of at least\n26,600 at the default budget (about 8,200 or fewer at 1 GiB or less), about 20–70\nMiB more RAM at the default budget, a writable cache directory (mount a volume with\na read-only root filesystem, and set `HELIX_DISK_CACHE_DIR` when running as a user\nother than `65532`), and room for the 8 GiB default unless `HELIX_DISK_CACHE_BYTES`\nis set.\n\n## Stop or inspect\n\n```bash\nhelix status\nhelix logs dev\nhelix stop dev\n```\n\n## Next steps\n\n Create a project and run your first query.\n\n Open HelixDB directly inside your process.\n\n Move the same application requests to a managed cluster.\n\n Manage instances and raw requests.\n\n# Embedded database\n\nPage type: Guide\n\nEmbedded clients execute operation-tree requests without HTTP. The process opens a\nwriter or read-only handle against memory, disk, or S3-compatible object storage.\n\n## Install\n\nInstall the SDK and its embedded runtime package.\n\n```bash Rust\ncargo add helix-db --features embedded\n```\n\n```bash TypeScript\nnpm install @helix-db/helix-db @helix-db/helix-db-embedded\n```\n\n```bash Go\ngo get github.com/helixdb/helix-db/sdks/go\n```\n\n```bash Python\npython -m pip install helix-db helix-db-embedded\n```\n\n## Open a writer\n\n```rust Rust\nuse helix_db::{Client, HelixDbSource};\n\nlet client = Client::open(HelixDbSource::Disk {\n root: \"/data/helix\".into(),\n database: \"app\".to_string(),\n})\n.await?;\n```\n\n```ts TypeScript\nconst client = await Client.embedded({\n kind: \"disk\",\n root: \"/data/helix\",\n database: \"app\",\n});\n```\n\n```go Go\nclient, err := helix.NewEmbeddedClient(\n\thelix.DiskSource{Root: \"/data/helix\", Database: \"app\"},\n)\nif err != nil {\n\treturn err\n}\n```\n\n```python Python\nfrom helixdb import Client, Disk\n\nclient = Client.embedded(Disk(\"/data/helix\", \"app\"))\n```\n\n## Choose a storage source\n\n| Source | Persistence | Use |\n| --- | --- | --- |\n| In-memory | Process-local | Tests, scratch data, and short-lived tools |\n| Disk | Filesystem path | Persistent single-host applications |\n| Object storage | Bucket and logical database path | Durable shared storage with an S3-compatible service |\n\n```ts In-memory\nconst client = await Client.embedded({\n kind: \"inMemory\",\n database: \"app\",\n});\n```\n\n```ts Disk\nconst client = await Client.embedded({\n kind: \"disk\",\n root: \"/data/helix\",\n database: \"app\",\n});\n```\n\n```ts Object storage\nconst client = await Client.embedded({\n kind: \"objectStorage\",\n database: \"app\",\n bucket: \"helix-production\",\n region: \"eu-west-2\",\n});\n```\n\n## Configure caches\n\nCache configuration is optional and fixed when the handle opens. Local defaults are\nbounded and demand-filled so a small embedded database does not reserve server-sized\ncaches:\n\n| Setting | In-memory | Disk | Object storage |\n| --- | --- | --- | --- |\n| Durable-write flush interval | 1 ms | 3 ms | 100 ms |\n| Vector memory | 64 MiB | 64 MiB | 256 MiB |\n| SlateDB block / metadata | 16 MiB / 8 MiB | 48 MiB / 16 MiB | 512 MiB / 128 MiB |\n| Full-text search | 16 MiB | 16 MiB | 64 MiB |\n| SlateDB / FTS startup warming | Off | Off | Background |\n| Disk cache | Disabled | Disabled | Disabled |\n\nThe local profiles also use a 16 MiB L0 target and a 64 MiB unflushed-data ceiling.\nThe flush interval is the batching delay before storage I/O; filesystem and device\nlatency still apply.\n\nPass an explicit cache configuration to change the vector-memory budget or enable\nbounded disk caches:\n\n| Profile | Behavior |\n| --- | --- |\n| Memory | Uses in-memory database caches |\n| Hybrid | Adds bounded disk caches with explicit paths and byte budgets |\n\n```ts Memory\nconst client = await Client.embedded(\n { kind: \"disk\", root: \"/data/helix\", database: \"app\" },\n {\n vectorMemoryBytes: 512 * 1024 * 1024,\n mode: { kind: \"memory\" },\n },\n);\n```\n\n```ts Hybrid\nconst client = await Client.embedded(\n { kind: \"disk\", root: \"/data/helix\", database: \"app\" },\n {\n vectorMemoryBytes: 512 * 1024 * 1024,\n mode: {\n kind: \"hybrid\",\n slateMemoryBytes: 256 * 1024 * 1024,\n slateDiskPath: \"/var/cache/helix/slate\",\n slateDiskBytes: 4 * 1024 * 1024 * 1024,\n objectStoreDiskPath: \"/var/cache/helix/objects\",\n objectStoreDiskBytes: 8 * 1024 * 1024 * 1024,\n },\n },\n);\n```\n\nCache byte budgets bound those caches. They are not a hard cap on total process RSS;\nrequests and index work can allocate transient memory.\n\n## Open a read-only database\n\nUse a read-only handle for processes that must never mutate the database. It opens an\nexisting disk or object-storage database, executes read requests, and rejects writes.\n\n```rust Rust\nuse helix_db::{Client, HelixDbSource};\n\nlet reader = Client::open_reader(HelixDbSource::Disk {\n root: \"/data/helix\".into(),\n database: \"app\".to_string(),\n})\n.await?;\n```\n\n```ts TypeScript\nconst reader = await Client.embeddedReader({\n kind: \"disk\",\n root: \"/data/helix\",\n database: \"app\",\n});\n```\n\n```go Go\nreader, err := helix.NewEmbeddedReaderClient(\n\thelix.DiskSource{Root: \"/data/helix\", Database: \"app\"},\n)\nif err != nil {\n\treturn err\n}\n```\n\n```python Python\nfrom helixdb import Client, Disk\n\nreader = Client.embedded_reader(Disk(\"/data/helix\", \"app\"))\n```\n\n## Embedded request rules\n\n- Use the same `QueryRequest` and response contract as server mode.\n- Writer handles can execute read and write requests.\n- Server routing options such as writer-only, warm-only, API headers, and durability\n headers are rejected because there is no gateway.\n- Reopen the same disk or object-storage source to retain canonical data across process\n lifetimes.\n\n## Next steps\n\n Run the production-shaped HTTP interface on your machine.\n\n Compare local server, embedded, and Cloud execution.\n\n# SDK setup\n\nPage type: Guide\n\nEvery HelixDB SDK builds the same operation-tree request and sends it to\n`POST /v2/query`, so the query guides apply to all four languages. Pick the SDK for\nyour application's language:\n\n| SDK | Package | HTTP client | Embedded runtime |\n| --- | --- | --- | --- |\n| Rust | `helix-db` (imported as `helix_db`) | Async | Yes, behind the `embedded` feature |\n| TypeScript | `@helix-db/helix-db` (ESM, Node.js 20+) | Async | Yes |\n| Go | `github.com/helixdb/helix-db/sdks/go` | Yes | Not yet |\n| Python | `helix-db` (imported as `helixdb`) | Sync and async | Yes, with `helix-db-embedded` |\n\n Typed DSL, `#[query]` macro, and async HTTP client.\n\n Typed DSL and async client for Node.js 20 or newer.\n\n Query builder and HTTP client.\n\n Synchronous and asynchronous clients.\n\n## Next steps\n\nAfter setup, the [query walkthrough](/database/helix-db/core-concepts/overview) builds\nand runs a first query, and the query guides cover reads, writes, traversals,\nfiltering, projections, parameters, and search in every language.\n\n# Rust SDK\n\nPage type: Guide\n\nThe published `helix-db` 3.0.0 crate provides the query DSL, request types, async\nHTTP client, native graph helpers, and a feature-gated embedded client.\n\nThe package is published as `helix-db` and imported as `helix_db`.\n\n## Install\n\n```bash\ncargo add helix-db@3.0.0\n```\n\nOr add the dependency directly:\n\n```toml Cargo.toml\n[dependencies]\nhelix-db = \"3.0.0\"\nserde = { version = \"1\", features = [\"derive\"] }\nserde_json = \"1\"\ntokio = { version = \"1\", features = [\"macros\", \"rt-multi-thread\"] }\n```\n\n## Define a query\n\n```rust\nuse helix_db::dsl::prelude::*;\n\n#[query]\nfn find_users(tenant_id: String, limit: i64) -> ReadBatch {\n read_batch()\n .var_as(\n \"users\",\n g()\n .n_with_label(\"User\")\n .where_(Predicate::eq(\"tenantId\", tenant_id))\n .limit(limit)\n .value_map(Some(vec![\"$id\", \"name\", \"tenantId\"])),\n )\n .returning([\"users\"])\n}\n```\n\n`#[query]` converts typed arguments into request parameters, sets `query_name` to\nthe function name, and returns `Result`.\n\n## Execute\n\n```rust\nuse helix_db::Client;\n\nlet client = Client::new(Some(\"http://localhost:6969\"))?;\nlet request = find_users(\"acme\".to_string(), 25)?;\nlet response: serde_json::Value = client.query(request).send().await?;\n```\n\nUse `.with_api_key(Some(\"hx_...\"))` for Helix Cloud. Request-builder options can\nrequire the writer, require a warm read, or control durability waiting.\n\n## Build without the macro\n\n```rust\nlet request = QueryRequest::read(\n read_batch()\n .var_as(\"count\", g().n_with_label(\"User\").count())\n .returning([\"count\"]),\n)\n.with_query_name(\"count_users\");\n```\n\n## Embedded runtime\n\nEnable the `embedded` feature:\n\n```bash\ncargo add helix-db --features embedded\n```\n\nSee [Embedded database](/database/helix-db/start-here/local-development/embedded-database)\nfor storage, cache, and handle configuration.\n\n## Verify\n\nRust SDK crate docs are doctests, and the public `#[query]` README journeys are\ncompile-tested as examples:\n\n```bash\ncargo test --manifest-path sdks/rust/Cargo.toml --lib\ncargo test --manifest-path sdks/rust/Cargo.toml --doc\ncargo check --manifest-path sdks/rust/Cargo.toml --example basic_query\ncargo check --manifest-path sdks/rust/Cargo.toml --example readme_sdk_query\ncargo check --manifest-path sdks/rust/Cargo.toml --example readme_macros_query\n```\n\n## Next steps\n\n Learn the batch and traversal model.\n\n Select data by ID, label, or indexed property.\n\n# TypeScript SDK\n\nPage type: Guide\n\nThe published `@helix-db/helix-db` 3.1.0 package targets Node.js 20 or newer and\nemits the same operation-tree AST as the Rust, Go, and Python SDKs.\n\nThe package is ESM and requires Node.js 20 or newer.\n\n## Install\n\n```bash\nnpm install @helix-db/helix-db@3.1.0\n```\n\nThe package is ESM. Set `\"type\": \"module\"` or compile to ESM.\n\n## Define a query\n\n```ts\nimport {\n Predicate,\n defineParams,\n g,\n param,\n readBatch,\n} from \"@helix-db/helix-db\";\n\nexport const findUsersParams = defineParams({\n tenantId: param.string(),\n limit: param.i64(),\n});\n\nexport function findUsers() {\n return readBatch()\n .varAs(\n \"users\",\n g()\n .nWithLabel(\"User\")\n .where(Predicate.eq(\"tenantId\", findUsersParams.tenantId))\n .limit(findUsersParams.limit)\n .valueMap([\"$id\", \"name\", \"tenantId\"]),\n )\n .returning([\"users\"]);\n}\n```\n\n## Execute\n\n```ts\nimport { Client } from \"@helix-db/helix-db\";\n\nconst request = findUsers().toQueryRequest(\n findUsersParams,\n { tenantId: \"acme\", limit: 25n },\n { queryName: \"find_users\" },\n);\n\nconst result = await Client.server(\"http://localhost:6969\")\n .query(request)\n .send();\n```\n\nUse `withApiKey(\"hx_...\")` for Helix Cloud.\n\n## Integer safety\n\nThe SDK preserves 64-bit integers as `bigint`. Use `stringifyJson` or the request's\nserialization methods instead of `JSON.stringify` when a value can contain `bigint`.\n\n## Embedded runtime\n\nInstall the SDK and embedded runtime with\n`npm install @helix-db/helix-db @helix-db/helix-db-embedded`. See\n[Embedded database](/database/helix-db/start-here/local-development/embedded-database)\nfor storage, cache, and handle configuration.\n\n## Verify\n\n```bash\nnpm --prefix sdks/typescript test\n```\n\n## Next steps\n\n Build reads, writes, and parameters.\n\n Open HelixDB directly inside your process.\n\n# Go SDK\n\nPage type: Guide\n\nThe Go SDK builds the shared operation-tree AST and executes requests through a\ntyped HTTP client.\n\nVersion `v0.3.1` ships the server query builder and HTTP client. It does not\ndistribute the native bindings required by embedded execution or native graph\nalgorithms.\n\nThe module path remains `github.com/helixdb/helix-db/sdks/go`; it does not add a\n`/v3` suffix because the module itself has not reached major version 2.\n\n## Install\n\n```bash\ngo get github.com/helixdb/helix-db/sdks/go@v0.3.1\n```\n\n```go\nimport helix \"github.com/helixdb/helix-db/sdks/go\"\n```\n\n## Define a query\n\n```go\nfunc FindUsers(tenantID string, limit int64) helix.Request {\n\tq := helix.ReadQuery(\"find_users\")\n\ttenant := q.ParamString(\"tenant_id\", tenantID)\n\tmaxRows := q.ParamI64(\"limit\", limit)\n\n\treturn q.\n\t\tVarAs(\n\t\t\t\"users\",\n\t\t\thelix.G().\n\t\t\t\tNWithLabel(\"User\").\n\t\t\t\tWhere(helix.PredEq(\"tenantId\", tenant)).\n\t\t\t\tLimit(maxRows).\n\t\t\t\tValueMap(\"$id\", \"name\", \"tenantId\"),\n\t\t).\n\t\tReturning(\"users\")\n}\n```\n\n## Execute\n\n```go\nclient, err := helix.NewClient(\"http://localhost:6969\")\nif err != nil {\n\treturn err\n}\n\nvar response struct {\n\tUsers []map[string]any `json:\"users\"`\n}\nif err := client.Exec(ctx, FindUsers(\"acme\", 25), &response); err != nil {\n\treturn err\n}\n```\n\nWrite requests can pass `helix.WriterOnly()` and `helix.AwaitDurability(true)` execution\noptions. The client does not retry conflicts automatically.\n\n## Release scope\n\nUse `v0.3.1` with a local or remote Helix server through `/v2/query`. Embedded\nconstructors and `Client.Graph` return native-binding-unavailable errors in a\nstandard module installation.\n\n## Verify\n\n```bash\ncd sdks/go\ngo test ./...\n```\n\n## Next steps\n\n Bind typed values and bounds.\n\n Diagnose validation, conflict, and runtime failures.\n\n# Python SDK\n\nPage type: Guide\n\nThe Python SDK is published on PyPI as `helix-db` 0.3.4 and imported as `helixdb`.\nIts builder methods use `snake_case` and produce the same operation-tree AST as\nthe other HelixDB v3 SDKs.\n\n`helix-db` includes the synchronous and asynchronous server clients. Install\n`helix-db-embedded` as well only when the application runs HelixDB in process.\n\n## Install\n\n```bash\npython -m pip install helix-db==0.3.4\n```\n\n## Define a query\n\n```python\nfrom helixdb import Predicate, define_params, g, param, read_batch\n\nfind_users_params = define_params({\n \"tenant_id\": param.string(),\n \"limit\": param.i64(),\n})\n\ndef find_users():\n return (\n read_batch()\n .var_as(\n \"users\",\n g()\n .n_with_label(\"User\")\n .where(Predicate.eq(\"tenantId\", find_users_params.tenant_id))\n .limit(find_users_params.limit)\n .value_map([\"$id\", \"name\", \"tenantId\"]),\n )\n .returning([\"users\"])\n )\n```\n\n## Execute\n\n```python\nfrom helixdb import Client\n\nrequest = find_users().to_query_request(\n find_users_params,\n {\"tenant_id\": \"acme\", \"limit\": 25},\n query_name=\"find_users\",\n)\nresult = Client(\"http://localhost:6969\").query(request)\n```\n\nThe server clients have no native runtime dependency.\n\n### Async execution\n\nReuse one async client to reuse its HTTP connection pool. HTTP requests have no\ntimeout unless you explicitly configure one.\n\n```python\nimport asyncio\n\nimport httpx\n\nfrom helixdb import AsyncClient\n\nasync def execute_queries():\n limits = httpx.Limits(max_connections=20, max_keepalive_connections=10)\n async with AsyncClient(timeout=10.0, limits=limits) as client:\n return await asyncio.gather(\n client.query(request),\n client.execute(request, writer_only=True, timeout=2.0),\n )\n\nresults = asyncio.run(execute_queries())\n```\n\nCancellation propagates as `asyncio.CancelledError`, closes the response stream,\nand leaves the client reusable. The client owns and closes an injected HTTPX\nasync transport. `await client.close()` is idempotent.\n\n## Embedded runtime\n\nInstall the SDK and embedded runtime with\n`python -m pip install helix-db helix-db-embedded`. See\n[Embedded database](/database/helix-db/start-here/local-development/embedded-database)\nfor storage, cache, and handle configuration.\n\n```python\nimport asyncio\n\nfrom helixdb import AsyncClient, Disk, InMemory\n\nasync def query_embedded():\n writer = await AsyncClient.embedded(InMemory(\"app\"))\n async with writer:\n memory_result = await writer.query(request)\n\n reader = await AsyncClient.embedded_reader(Disk(\"./data\", \"seeded-app\"))\n async with reader:\n disk_checkpoint = await reader.query(request)\n\n return memory_result, disk_checkpoint\n\nresults = asyncio.run(query_embedded())\n```\n\nAsync embedded queries await native UniFFI operations directly. Use\n`asyncio.timeout(...)` for cancellation boundaries. Async native graph loading is\nnot part of this API; use the synchronous `Client.graph(...)` API.\n\n## Verify\n\n```bash\nPYTHONDONTWRITEBYTECODE=1 \\\nPYTHONPATH=sdks/python/src \\\npython -m unittest discover sdks/python/tests\n```\n\n## Next steps\n\n Follow the shared batch and traversal model.\n\n Open an in-process writer or reader.\n\n# Roadmap\n\nPage type: Reference\n\n## In progress\n\n- **Smarter cache warming** (ongoing)\n- **Reliability and availability improvements** (ongoing)\n- **Support for non-HA clusters**\n- **Backups and point-in-time recovery**\n- **Expanded query plans for better performance**\n\n## Up next\n\n- **SSO and SAML**\n- **RBAC and fine-grained API key permissions**\n- **AWS PrivateLink**\n- **Audit logs**\n\n## Recently shipped\n\n- **Local Docker deployment**\n- **Dashboard improvements**\n\nSee the [release notes](/database/helix-db/start-here/release-notes) for everything\nthat has shipped.\n\nHave a feature request? [Let us know on Discord](https://discord.com/invite/2stgMPr5BD) or [email us](mailto:founders@helix-db.com).\n\n# Release notes\n\nPage type: Reference\n\n- **Strong text search keeps working during ingest.** A `strong` text search now has its own bound, 512 MiB of unpublished text per partition by default (it was one publication's 64 MiB), and reuses analyses of pending text across searches. Ingest bursts of 20K–40K documents that made v0.0.10's strong text searches fail with `index_backpressure` now complete with no rejections, and a strong text search behind 5,000 pending documents dropped from about 200 ms to 30 ms. Set `HELIX_STRONG_TEXT_SEARCH_MAX_ANALYSIS_BYTES` to change the bound; past it the search fails with retryable `index_backpressure` (`pending_text_analysis_bytes`).\n- **Strong searches decode pending index work once per request.** Several searches in one request share one decoded copy of the pending queue, decoding and exact scoring run off the async workers so they no longer stall other requests, and four strong vector searches in one request behind 160K pending 768-dimension changes went from about 5.0 s to 2.2 s.\n- **Strong vector searches are bounded.** A `strong` vector search decodes and scores at most the index's retained-byte limit of unpublished work by default (1 GB, so writes reach backpressure first). Set `HELIX_STRONG_VECTOR_SEARCH_MAX_PENDING_BYTES` to lower it; past it the search fails with retryable `index_backpressure` (`pending_vector_bytes`).\n- **Queue admission tracks real memory.** Each queued index operation now counts its encoded size plus 576 bytes against the 1 GB per-index limit, so a backlog of many small operations, such as deletes, can no longer use several times the limit in memory. Such backlogs reach `index_backpressure` sooner; the 250,000 pending-entity limit is unchanged.\n- **Writers reopen faster with a large backlog.** Opening a writer loads its queued index work one queue at a time instead of decoding every queue at once: a 2.26 GB backlog opened in about 5 s instead of 25 s, with peak memory bounded by the largest queue instead of the whole backlog.\n- **Publication drains in linear time.** Selecting work to publish no longer rescans the whole queue each time, which was 9.4 s of bookkeeping per 250K-operation drain and is now 0.16 s, and a queue retired by an index drop is discarded without being re-read.\n- No storage changes since v0.0.10: upgrading from v0.0.10 needs no migration. Upgrading from v0.0.9 or earlier follows the v0.0.10 notes below.\n- **CLI 3.4.4** defaults to image v0.0.11. Projects that saved a `tag` in `helix.toml` keep using it until you change it.\n\n- **Upgrading: index storage version 5.** The first time a v0.0.10 writer opens a database, it upgrades the index storage version from 4 to 5. It rewrites only the version marker and rebuilds no index. After that, v0.0.9 and earlier refuse to open the database with `unsupported_index_storage_version`:\n - Upgrade readers before the writer; v0.0.10 readers serve both versions.\n - Never start a v0.0.9-or-earlier writer against an upgraded database.\n - Take a backup before upgrading if you may need to roll back.\n- **[Vector and text indexes publish asynchronously](/database/helix-db/query-guides/search-consistency).** A write commits its graph change together with a durable queued index operation, and a background index worker publishes it into the vector or text index, so writes no longer wait on index maintenance. Steady vector insert publication went from 6.2 to 239 per second. Index builds no longer livelock under concurrent writes: on a c7i.8xlarge with 100 writes/s during the build, backfilling 100K 768-dimension vectors on disk finished in about 2,500 s, where v0.0.9 never finished.\n- **Search consistency.** Read requests set `search_consistency` to `strong` (the default) or `eventual`. `strong` searches include every committed write, published or not. `eventual` searches include a bounded amount of unpublished work and serve the rest as last published, so they can return a node or edge that has since changed tenant, label or indexed property. Write requests always search `strong`, and a write batch that searches an index fails with a retryable `transaction_conflict` if the index worker publishes into that index first. The SDK options ship in the next SDK releases; until then, send `search_consistency` in a direct HTTP request.\n- **[Index backpressure](/database/helix-db/query-guides/search-consistency#index-backpressure).** Each index retains at most 1,000,000,000 bytes or 250,000 pending entities of unpublished work. Three cases fail with `index_backpressure` (HTTP 429, `retryable: true`) before the request takes effect: a write past either limit, a whole-index `strong` search behind more than 800 unpublished changes, and a `strong` text search that would analyze more unpublished text than one publication may (64 MiB by default). Retry it unchanged with bounded backoff. A single write that stages more than 8 MiB of index work for one index fails with `index_operation_batch_too_large` (HTTP 400); split it.\n- **[Text write limits are per document](/database/helix-cloud/operate/limits#active-text-mutation-admission).** `active_text_mutation_limit_exceeded` now checks each indexed document against its own allowances, about 16,000 unique terms, instead of limiting a write to 512 text-indexed entities.\n- **A failing index entry no longer stalls its index.** An entry whose index update fails the same way every time, for example on damaged index data, is held back while the rest of the index keeps publishing. `GET /healthz` counts it under `blocked_index_entity_count`, the server logs an error naming it, and the worker retries it about once a minute. See [troubleshooting](/database/helix-db/query-guides/troubleshooting).\n- **Fixed: `missing simhash` after re-embedding and then deleting a node** (the v0.0.9 known issue). Re-embedding a node no longer loses track of the vector index (HNSW) links that point at it, so deleting it later removes them all, and a node is never linked to itself. Indexes written by v0.0.9 and earlier can still hold such links; drop and recreate the vector index to repair them.\n- **Fixed: counts over a range index with other indexed filters.** A `.count()` over `N.where(...)` or `E.where(...)` that combined a range condition with other indexed conditions counted the range alone, for example 149 rows instead of 49. Counts now apply every filter.\n- **CLI 3.4.3** defaults to image v0.0.10. Projects that saved a `tag` in `helix.toml` keep using it until you change it.\n\n- **Upgrading S3 deployments** — S3 storage now always writes a local disk cache, so an S3 container that ran v0.0.8 or earlier can fail or use more resources after the upgrade:\n - The cache directory, `/var/cache/helix` unless `HELIX_DISK_CACHE_DIR` names another, must be writable. Mount a volume there (required with a read-only root filesystem), and set `HELIX_DISK_CACHE_DIR` when running as a user other than `65532`.\n - The hard open-file limit must be at least 26,600 at the default budget (about 8,200 or fewer at 1 GiB or less). Raise it with `--ulimit nofile=65536:65536`.\n - RSS grows by the block cache's index, about 20–70 MiB at the default budget and twice that briefly after a restart.\n - Without `HELIX_DISK_CACHE_BYTES`, the 8 GiB default budget must fit the cache's filesystem, or startup fails.\n- **[S3 always uses a local disk cache](/database/helix-db/start-here/local-development/local-server#add-a-local-disk-cache)** in `/var/cache/helix` by default, with an 8 GiB default budget. Memory-only S3 is gone: once a vector index outgrew the memory cache, every graph hop waited on its own S3 request. `HELIX_DATA_DIR` and in-memory storage are unchanged.\n- **Faster first vector searches on S3.** Cold batch reads overlap their block fetches, expansions read parents concurrently, and projections prefetch the records they need. After open, the server also warms vector search rows into the disk cache in the background; readiness never waits for it. `HELIX_DISK_CACHE_WARM=off` (default `on`) turns startup warming off. On 2 CPUs, 4 GiB of memory and an 8 GiB cache over S3, the first global vector top-50 after open went from 30.8 s on v0.0.7 to 714 ms once the ~26 s warm finished.\n- **Index sets are kept across `ForEach` iterations and unrelated writes** in the same request, which removes the v0.0.8 known limitation. A set is read again only when an iteration binds a parameter it depends on, or a write creates, deletes or changes indexed properties of nodes with its label. A batch that expands, filters on an index and adds an edge per iteration runs about twice as fast.\n- **Source filters and counts always use indexes.** `N.where(...)`, `E.where(...)` and counts on indexed properties no longer scan the label, including partly indexed ORs, long `IN` lists, parameter lists, `== null`, and counts over `.as()` / `.store()`. A label scan only happens when no condition has an index. On 50k rows, counts after `.as()` went from up to 1.1 s to under 5 ms, and 200-value `IN` lists from up to 1.5 s to about 0.2 s.\n- **Upgrading** — the stored data format is unchanged. Databases written by v0.0.8 open directly with v0.0.9.\n- **Known issue** — updating a node's vector (re-embedding it) and later deleting that node can leave vector index (HNSW) links pointing at the deleted node, and searches that reach them fail with `missing simhash`. Earlier releases are affected too, and a fix is in progress. To repair an affected index, drop and recreate the vector index.\n- **CLI 3.4.2** defaults to image v0.0.9. With `--disk` or S3 storage, `helix start` mounts a per-instance `helix---cache` volume at `/var/cache/helix` for the disk cache, with a 64 MiB budget in disk mode and 1 GiB for an S3 bucket. `helix stop` keeps it and `helix prune` removes it.\n\n- **Filters after a traversal always use indexes.** A `.where(...)` on indexe","isInternal":false,"tokens":12607,"sizeBytes":50018},{"name":"llms.txt","path":"docs/llms.txt","rawUrl":"https://raw.githubusercontent.com/HelixDB/helix-db/HEAD/docs/llms.txt","title":"docs - LLM Index & Context Digest","category":"root-instruction","format":"text","content":"# HelixDB\n\n> HelixDB combines a property graph, approximate vector search, and BM25 full-text search behind one operation-tree query model. Requests run through Cloud, a local server, or the embedded runtime.\n\nQuickstart (local instance requires Docker or Podman):\n\nmacOS and Linux:\n```bash\ncurl -sSL \"https://install.helix-db.com\" | bash # install the helix CLI\n```\n\nWindows PowerShell:\n```powershell\nirm https://raw.githubusercontent.com/HelixDB/helix-db/main/crates/cli/install.ps1 | iex\n```\n\nThen:\n```bash\nhelix init local # scaffold helix.toml + examples/\nhelix start dev # start a local instance\nhelix query dev -e 'writeBatch().varAs(\"alice\", g().addN(\"User\", { username: \"alice\" })).returning([\"alice\"])'\nhelix query dev -e 'readBatch().varAs(\"users\", g().nWithLabel(\"User\")).returning([\"users\"])'\n```\n\nFull walkthrough: https://docs.helix-db.com/database/helix-db/start-here/quickstart\n\n## HelixDB developer resources\n- [HelixDB HTTP API documentation](https://docs.helix-db.com/database/helix-db/query-guides/http-api): Request contract, authentication, headers, responses, and examples for `POST /v2/query`.\n- [HelixDB OpenAPI specification](https://www.helix-db.com/openapi.json): OpenAPI 3.1 JSON for the public HelixDB HTTP API.\n- [HelixDB authentication guide for agents](https://www.helix-db.com/auth.md): Supported API-key and OAuth surfaces, with links to machine-readable discovery metadata.\n- [HelixDB unified MCP endpoint](https://docs.helix-db.com/database/helix-cloud/connect/mcp): Connect human OAuth, scoped service credentials, and agent registrations to authorized tools on one endpoint.\n- [HelixDB AI Catalog](https://www.helix-db.com/.well-known/ai-catalog.json): ARD catalog of HelixDB agent resources.\n\n## HelixDB — Start Here\n- [Introduction](https://docs.helix-db.com/database/helix-db/start-here/introduction): HelixDB is a graph database with native vector and full-text search, built on object storage — Page type: Concept\n- [Get started](https://docs.helix-db.com/database/helix-db/start-here/quickstart): Initialize HelixDB, start a local instance, run the generated query, and stop it — Page type: Tutorial\n- [Deployment options](https://docs.helix-db.com/database/helix-db/start-here/run-modes): Compare Cloud, local server, and embedded execution — Page type: Concept\n- [Local server](https://docs.helix-db.com/database/helix-db/start-here/local-development/local-server): Start HelixDB locally with memory, a persistent directory, or S3-compatible storage — Page type: Guide\n- [Embedded database](https://docs.helix-db.com/database/helix-db/start-here/local-development/embedded-database): Open HelixDB directly inside your process with explicit storage and cache settings — Page type: Guide\n- [SDK setup](https://docs.helix-db.com/database/helix-db/start-here/sdk-setup/overview): Choose a HelixDB SDK and connect it to a local or Cloud server — Page type: Guide\n- [Rust SDK](https://docs.helix-db.com/database/helix-db/start-here/sdk-setup/rust-project-setup): Build typed HelixDB queries and execute them over HTTP or an embedded engine — Page type: Guide\n- [TypeScript SDK](https://docs.helix-db.com/database/helix-db/start-here/sdk-setup/typescript-project-setup): Build typed HelixDB requests for Node.js applications — Page type: Guide\n- [Go SDK](https://docs.helix-db.com/database/helix-db/start-here/sdk-setup/go-project-setup): Build and execute HelixDB requests with ordinary Go functions — Page type: Guide\n- [Python SDK](https://docs.helix-db.com/database/helix-db/start-here/sdk-setup/python-project-setup): Build HelixDB requests with idiomatic synchronous and asynchronous Python clients — Page type: Guide\n- [Roadmap](https://docs.helix-db.com/database/helix-db/start-here/roadmap): What we're building and what's coming next — Page type: Reference\n- [Release notes](https://docs.helix-db.com/database/helix-db/start-here/release-notes): New features and changes in HelixDB, Helix Cloud, the SDKs, and the CLI — Page type: Reference\n\n## Core Concepts\n- [Data model](https://docs.helix-db.com/database/helix-db/core-concepts/data-model): Understand how HelixDB represents entities, relationships, properties, and indexes — Page type: Concept\n- [Build and run a query](https://docs.helix-db.com/database/helix-db/core-concepts/overview): Build a small write query operation by operation, then read its request and response — Page type: Tutorial\n\n## Query Guides\n- [Writing data](https://docs.helix-db.com/database/helix-db/query-guides/writing-data): Create, update, connect, and remove entities in one typed write batch — Page type: Guide\n- [Reading data](https://docs.helix-db.com/database/helix-db/query-guides/reading-data): Start a traversal from IDs, labels, properties, or previous query results — Page type: Guide\n- [Traverse relationships](https://docs.helix-db.com/database/helix-db/query-guides/traversals): Follow edges, retain row-local bindings, and control duplicate paths — Page type: Guide\n- [Filtering](https://docs.helix-db.com/database/helix-db/query-guides/filtering): Narrow traversal streams with predicates and exact search candidate sets — Page type: Guide\n- [Shape query results](https://docs.helix-db.com/database/helix-db/query-guides/projections): Return properties, computed values, aggregates, and correlated binding rows — Page type: Guide\n- [Bind typed query parameters](https://docs.helix-db.com/database/helix-db/query-guides/parameters): Keep the operation tree stable while request values change — Page type: Guide\n- [Branch, repeat, and condition queries](https://docs.helix-db.com/database/helix-db/query-guides/advanced): Compose sub-traversals and gate named entries without leaving one transaction — Page type: Guide\n- [Query HelixDB with Cypher](https://docs.helix-db.com/database/helix-db/query-guides/cypher): Run Cypher statements beside native queries, and see which parts of openCypher HelixDB supports — Page type: Guide\n- [Secondary indexes](https://docs.helix-db.com/database/helix-db/query-guides/secondary-indexes): Accelerate equality, uniqueness, and ordered property lookups — Page type: Guide\n- [Vector indexes](https://docs.helix-db.com/database/helix-db/query-guides/vector-indexes): Create vector indexes and run nearest-neighbor search — Page type: Guide\n- [Text indexes](https://docs.helix-db.com/database/helix-db/query-guides/text-indexes): Create BM25 indexes and run ranked full-text search — Page type: Guide\n- [Prefiltered search](https://docs.helix-db.com/database/helix-db/query-guides/prefiltering): Rank only the nodes or edges a traversal reaches with vector or BM25 search — Page type: Guide\n- [Search consistency](https://docs.helix-db.com/database/helix-db/query-guides/search-consistency): Choose whether vector and text searches include unpublished index work, and handle index backpressure — Page type: Guide\n- [HelixDB HTTP API and OpenAPI specification](https://docs.helix-db.com/database/helix-db/query-guides/http-api): Call the HelixDB v2 query endpoint and discover its machine-readable OpenAPI 3.1 contract — Page type: Reference\n- [Query error reference](https://docs.helix-db.com/database/helix-db/query-guides/error-handling): Branch on stable error codes, apply retry rules, and look up every HelixDB query error — Page type: Reference\n- [Troubleshoot HelixDB](https://docs.helix-db.com/database/helix-db/query-guides/troubleshooting): Diagnose query, index, vector, embedded, and local runtime failures — Page type: Troubleshooting\n\n## Helix Cloud — Start Here\n- [Get started with Helix Cloud](https://docs.helix-db.com/database/helix-cloud/start-here/using-the-cloud): Sign in, create a workspace and choose its plan, provision a database, and test the connection — Page type: Tutorial\n- [Connect to Helix Cloud](https://docs.helix-db.com/database/helix-cloud/start-here/working-with-enterprise): Connect an SDK or HTTP client to a Helix Cloud database and control request routing — Page type: Guide\n- [Architecture](https://docs.helix-db.com/database/helix-cloud/start-here/architecture): How the Helix Cloud gateway, writer, readers, caches, and object storage serve reads and writes — Page type: Concept\n\n## Connect and automate\n- [Helix Cloud MCP](https://docs.helix-db.com/database/helix-cloud/connect/mcp): Connect users and agents to the unified Helix Cloud MCP endpoint — Page type: Reference\n\n## Operate\n- [Security](https://docs.helix-db.com/database/helix-cloud/operate/security): Authenticate requests, handle API keys, and review encryption and enterprise security features — Page type: Reference\n- [Multi-tenancy](https://docs.helix-db.com/database/helix-cloud/operate/multi-tenancy): Isolate application tenants with row-level scoping and tenant-partitioned search indexes — Page type: Guide\n- [Guarantees](https://docs.helix-db.com/database/helix-cloud/operate/guarantees): Atomicity, isolation, durability, index activation, and read-after-write behavior — Page type: Reference\n- [Limits](https://docs.helix-db.com/database/helix-cloud/operate/limits): Understand Helix Cloud request rate limits and database constraints — Page type: Reference\n- [Tradeoffs](https://docs.helix-db.com/database/helix-cloud/operate/tradeoffs): What the Helix Cloud architecture is optimized for, and where another system may fit better — Page type: Concept\n- [Helix Cloud gateway errors](https://docs.helix-db.com/database/helix-cloud/operate/error-handling): Use stable Helix Cloud error codes, HTTP statuses, and SDK error metadata — Page type: Reference\n\n## Helix Foundry — Start Here\n- [What is Helix Foundry?](https://docs.helix-db.com/foundry/start-here/introduction): Helix Foundry connects your company's data, drafts an ontology across it, and loads it into a Helix database you can explore — Page type: Concept\n- [Helix Foundry quickstart](https://docs.helix-db.com/foundry/start-here/quickstart): Sign in, connect a source, generate an ontology, load it into a Helix database and explore it — Page type: Tutorial\n- [Workspaces and navigation](https://docs.helix-db.com/foundry/start-here/workspaces-and-navigation): Sign in to Helix Foundry, choose or create a workspace, and find your way with the sidebar, search and themes — Page type: Guide\n\n## Data\n- [Connect and sync data](https://docs.helix-db.com/foundry/data/connect-data): Add a source to a Helix Foundry workspace, test its credential, sync its tables and read what each table holds — Page type: Guide\n- [Connectors](https://docs.helix-db.com/foundry/data/connectors): What each Helix Foundry source needs, the permissions to give it, the tables it syncs and its limits — Page type: Reference\n\n## Ontologies\n- [Create an ontology](https://docs.helix-db.com/foundry/ontologies/create-an-ontology): Create a Helix Foundry ontology on an existing Helix database or a new one, and read its overview — Page type: Guide\n- [Generate and version an ontology](https://docs.helix-db.com/foundry/ontologies/generate-and-version): Ask Helix Foundry's agent to draft an ontology from your synced tables and documents, review each version, and choose the current one — Page type: Guide\n- [Upload documents](https://docs.helix-db.com/foundry/ontologies/documents): Upload Markdown and text files to a Helix Foundry ontology so generations and loads read the names and facts they hold — Page type: Guide\n- [Load data into a Helix database](https://docs.helix-db.com/foundry/ontologies/load-data): Write an ontology's current version, your synced tables and your documents into its Helix database, and manage its loads — Page type: Guide\n\n## Explore\n- [Explore the graph](https://docs.helix-db.com/foundry/explore/explorer): Read what a Helix Foundry load wrote as a graph: search, expand, inspect, pick a load and compare two — Page type: Guide\n- [Records and entities](https://docs.helix-db.com/foundry/explore/records-and-entities): Read a Helix Foundry load as tables by type, open a record's links and sources, and see everything about one entity — Page type: Guide\n\n## Ask\n- [Ask questions of your data](https://docs.helix-db.com/foundry/ask/ask-questions): Ask a Helix Foundry ontology questions in plain language and get answers that cite where they came from. Coming soon. — Page type: Guide; Status: Preview\n\n## Workspace\n- [Members and roles](https://docs.helix-db.com/foundry/workspace/members-and-roles): See who is in a Helix Foundry workspace, invite people, and what owners, admins and members can do — Page type: Guide\n- [Plans and billing](https://docs.helix-db.com/foundry/workspace/plans-and-billing): Compare Helix Foundry Free, Pro and Max, upgrade a workspace, switch tiers, cancel, resume and manage payment — Page type: Guide\n\n## Reference\n- [Helix Foundry limits](https://docs.helix-db.com/foundry/reference/limits): Every Helix Foundry limit in one place: syncs, generations, documents, loads, spending and reads — Page type: Reference\n- [Troubleshooting Helix Foundry](https://docs.helix-db.com/foundry/reference/troubleshooting): What Helix Foundry's sign-in, connection, sync, generation, database and load messages mean, and what to do — Page type: Troubleshooting\n\n## Using the helix CLI\n- [Getting started with HelixDB CLI](https://docs.helix-db.com/cli/getting-started): Install the CLI, run locally, or link a WorkOS-authenticated Cloud database — Page type: Tutorial\n- [Local development](https://docs.helix-db.com/cli/workflows/local): Run a local instance and iterate on dynamic JSON queries — Page type: Guide\n- [Helix Cloud CLI workflow](https://docs.helix-db.com/cli/workflows/helix_cloud): Authenticate, link, query, and manage Cloud resources — Page type: Guide\n- [CLI configuration](https://docs.helix-db.com/cli/configuration): Project linkage and WorkOS session files — Page type: Reference\n- [CLI troubleshooting](https://docs.helix-db.com/cli/troubleshooting): Recover local and WorkOS-authenticated Cloud CLI operations — Page type: Troubleshooting\n\n## CLI Command Reference\n- [CLI command reference](https://docs.helix-db.com/cli/command-reference): Every Helix CLI command, grouped by what it manages — Page type: Reference\n- [helix add](https://docs.helix-db.com/cli/command-reference/add): Add a local instance or a Helix Cloud database link to an existing project — Page type: Reference\n- [helix auth](https://docs.helix-db.com/cli/command-reference/auth): Log in to Helix Cloud, check the session, or log out — Page type: Reference\n- [helix api](https://docs.helix-db.com/cli/command-reference/api): Call a Helix Cloud API endpoint with your CLI login session — Page type: Reference\n- [helix chef](https://docs.helix-db.com/cli/command-reference/chef): Bootstrap a first HelixDB app with a coding agent — Page type: Reference\n- [helix cluster](https://docs.helix-db.com/cli/command-reference/cluster): List and inspect Helix Cloud clusters and their active indexes — Page type: Reference\n- [helix cypher](https://docs.helix-db.com/cli/command-reference/cypher): Execute or explain one Cypher statement against a local instance — Page type: Reference\n- [helix database](https://docs.helix-db.com/cli/command-reference/database): Discover and manage Helix Cloud databases and application keys — Page type: Reference\n- [helix delete](https://docs.helix-db.com/cli/command-reference/delete): Remove an instance from helix.toml and clean up its local state — Page type: Reference\n- [helix doctor](https://docs.helix-db.com/cli/command-reference/doctor): Check an instance's setup: runtime, storage, disk cache, memory, and index use — Page type: Reference\n- [helix explorer](https://docs.helix-db.com/cli/command-reference/explorer): Browse a running local instance in the graph Explorer — Page type: Reference\n- [helix feedback](https://docs.helix-db.com/cli/command-reference/feedback): Open a pre-filled feedback issue for the Helix team — Page type: Reference\n- [helix init](https://docs.helix-db.com/cli/command-reference/init): Create a local project or a WorkOS-authenticated Cloud link — Page type: Reference\n- [helix logs](https://docs.helix-db.com/cli/command-reference/logs): View local logs or recent Cloud query errors — Page type: Reference\n- [helix metrics](https://docs.helix-db.com/cli/command-reference/metrics): Configure CLI telemetry and usage metrics collection — Page type: Reference\n- [helix project](https://docs.helix-db.com/cli/command-reference/project): Discover, manage, and link Helix Cloud projects — Page type: Reference\n- [helix prune](https://docs.helix-db.com/cli/command-reference/prune): Remove Helix-owned local containers, volumes, and instance state — Page type: Reference\n- [helix query](https://docs.helix-db.com/cli/command-reference/query): Execute a direct Helix v3 query against a local instance or a Cloud database — Page type: Reference\n- [helix restart](https://docs.helix-db.com/cli/command-reference/restart): Restart a background local instance — Page type: Reference\n- [helix skills](https://docs.helix-db.com/cli/command-reference/skills): Install, refresh, and list the Helix agent skills — Page type: Reference\n- [helix start](https://docs.helix-db.com/cli/command-reference/start): Start a local instance in the background or foreground — Page type: Reference\n- [helix status](https://docs.helix-db.com/cli/command-reference/status): Inspect local runtime or current Cloud database state — Page type: Reference\n- [helix stop](https://docs.helix-db.com/cli/command-reference/stop): Stop a background local instance and remove its containers — Page type: Reference\n- [helix service-credential](https://docs.helix-db.com/cli/command-reference/service-credential): Manage workspace-owned credentials for headless HTTP API and unified MCP clients — Page type: Reference\n- [helix shell](https://docs.helix-db.com/cli/command-reference/shell): Run line-oriented Helix v3 JSON requests — Page type: Reference\n- [helix update](https://docs.helix-db.com/cli/command-reference/update): Update the Helix CLI and refresh installed agent skills — Page type: Reference\n- [helix workspace](https://docs.helix-db.com/cli/command-reference/workspace): Discover WorkOS workspace memberships — Page type: Reference\n\n## Learning center\n- [Learning center](https://docs.helix-db.com/learn/index): Plain-language answers about graph databases, vector search, full-text search, AI agent memory, and modern database architecture. — Page type: Concept\n\n## Graph databases\n- [What is a graph database?](https://docs.helix-db.com/learn/graph-databases/what-is-a-graph-database): A graph database stores things as nodes and the connections between them as edges, and answers questions by following those connections. — Page type: Concept\n- [What is the difference between a graph database and a relational database?](https://docs.helix-db.com/learn/graph-databases/graph-vs-relational-database): A relational database keeps data in tables and rebuilds connections with joins; a graph database stores connections as edges and follows them. — Page type: Concept\n- [What is a knowledge graph?](https://docs.helix-db.com/learn/graph-databases/what-is-a-knowledge-graph): A knowledge graph is a connected collection of facts about things and how they relate, organized by a schema so software can query and cite it. — Page type: Concept\n- [What is a property graph?](https://docs.helix-db.com/learn/graph-databases/what-is-a-property-graph): A property graph stores data as labeled nodes and edges with key-value properties on both, so a relationship can carry its own details. — Page type: Concept\n- [What is the difference between a property graph and RDF?](https://docs.helix-db.com/learn/graph-databases/property-graph-vs-rdf): A property graph stores nodes and edges that carry their own properties; RDF stores every fact as a three-part triple named by global IDs. — Page type: Concept\n\n## Vector search\n- [What is vector search?](https://docs.helix-db.com/learn/vector-search/what-is-vector-search): Vector search finds results by meaning instead of exact words, by comparing embeddings: lists of numbers that capture what content is about. — Page type: Concept\n- [What are vector embeddings?](https://docs.helix-db.com/learn/vector-search/what-are-vector-embeddings): A vector embedding is a list of numbers, produced by a machine learning model, that captures what a piece of content means. — Page type: Concept\n- [What is a vector database?](https://docs.helix-db.com/learn/vector-search/what-is-a-vector-database): A vector database stores embeddings, lists of numbers that capture what content means, and quickly finds the ones most similar to a query. — Page type: Concept\n- [What is HNSW?](https://docs.helix-db.com/learn/vector-search/what-is-hnsw): HNSW is a vector search index that links each vector to its nearest neighbors in layers, so a search can hop quickly to similar items. — Page type: Concept\n- [What is filtered vector search?](https://docs.helix-db.com/learn/vector-search/filtered-vector-search): Filtered vector search finds the most similar items among only those that pass a rule, such as a tenant, a date range, or a permission check. — Page type: Concept\n- [What is the difference between cosine, Euclidean, and Manhattan distance?](https://docs.helix-db.com/learn/vector-search/vector-distance-metrics): Cosine distance compares direction, Euclidean measures the straight-line gap, and Manhattan adds up the per-dimension gaps between two embeddings. — Page type: Concept\n\n## Full-text search\n- [What is full-text search?](https://docs.helix-db.com/learn/full-text-search/what-is-full-text-search): Full-text search finds documents by the words inside them and lists the best matches first, using an inverted index and a relevance score such as BM25. — Page type: Concept\n- [What is BM25?](https://docs.helix-db.com/learn/full-text-search/what-is-bm25): BM25 is a scoring formula that ranks documents for a keyword search by how rare each word is, how often it appears, and how long the document is. — Page type: Concept\n- [What is hybrid search?](https://docs.helix-db.com/learn/full-text-search/hybrid-search): Hybrid search runs a keyword search and a vector search for the same query, then merges the results so it finds both exact terms and similar meaning. — Page type: Concept\n\n## AI memory and RAG\n- [What is retrieval-augmented generation (RAG)?](https://docs.helix-db.com/learn/ai-memory/what-is-rag): RAG has an AI model answer from documents looked up at question time, so answers can use private, current data and cite their sources. — Page type: Concept\n- [What is GraphRAG?](https://docs.helix-db.com/learn/ai-memory/what-is-graphrag): GraphRAG finds context for an AI model by following links between facts in a graph, not only by matching text that is similar to the question. — Page type: Concept\n- [What is AI agent memory?](https://docs.helix-db.com/learn/ai-memory/what-is-ai-agent-memory): AI agent memory lets an AI assistant store, update, and recall what it learns across sessions, outside the model's context window. — Page type: Concept\n- [How do you build long-term memory for AI agents?](https://docs.helix-db.com/learn/ai-memory/long-term-memory-for-ai-agents): Build agent long-term memory from versioned, user-scoped facts: catch duplicates and forget on write, then search and expand on read. — Page type: Concept\n\n## Database architecture\n- [Why build a database on object storage?](https://docs.helix-db.com/learn/database-architecture/object-storage-databases): A database on object storage keeps its data in a durable object store and uses server memory and disks as cache, so storage and compute scale separately. — Page type: Concept\n- [Do you need separate graph, vector, and text databases?](https://docs.helix-db.com/learn/database-architecture/one-database-for-graph-vector-and-text): Often not. One database that stores relationships and indexes the same records for vector and keyword search avoids sync pipelines and stale copies. — Page type: Concept\n","isInternal":false,"tokens":5620,"sizeBytes":24205}],"systemPromptSnippet":"\n\n### approach\n\n- ⁠Make invalid states unrepresentable using algebraic data types (e.g. enums).\n- ⁠Use code coverage tools to make sure unit test coverage covers every edge case. This should be easily doable if invalid states are unrepresentable.\n- Keep things modular.\n- Define clear contract boundaries for testability. Document them all, and make sure doc comment examples are ran as tests.\n- Use assertions for invariants when encoding within types is not feasible.\n- Use clippy and fix code smells reported.\n- Prefer iterators, monadic logic, and functional concepts. Where not possible for performance, document why.\n- Make invalid state unrepresentable.\n- Prefer importing modules over long lists of types. Using `module::Type` at call sites is fine, keeps names unambiguous, and reduces namespace-collision churn.\n- Be wary of things that don't scale. If you have reason to believe why it wont, report back to the user explaining why.\n- instead of if let { ... } use let Some(…) = … else { }\n- avoid over using helper functions where possible. duplicating a single line of code is clearer than polluting with helper functions. if a large piece of functionality is shared or repeated multiple times then it can be abstracted but you should favour inline code where possible. small pieces of functionality should be inlined instead of abstracted.\n- Do not stage, commit (including locally), push, publish artifacts, or trigger remote CI unless explicitly instructed. Keep work-session timestamps out of authored reports and documentation.\n- As you make changes, if it is small (e.g. single/couple line addition) or if it is critical to your implementation, make the change.\n- Clean up any temporary files or directories you create during your work (including in /private/tmp)\n- ⁠match { Example(_) => ExampleVariant } -> use derive macro for Variant and the conversions instead of littering our code with the extra types and functions\n⁠- ⁠instead of children structs holding an Arc, maybe just let them take in a &Db in every method that requires it.\n- when that's not feasible, evaluate whether passing in an Arc is fine, and if not make sure that holding an Arc won't leak the memory based on how the child is stored in parent.\n\n### Slice access\n⁠When accessing or creating slices, for every access or slice don't minify it to start..end constants, always keep the additions of offsets explicit.\nInstead of making `start` and `end` variables in the place of `const` values, use the `const` values directly, adding them up instead.\n\ne.g. you should do the following\n\n```rust\nconst PREFIX_LEN: usize = core::mem::size_of::();\nconst INDEX_PREFIX_LEN: usize = core::mem::size_of::();\nconst PROPERTY_HASH_MAX_LEN: usize = core::mem::size_of::();\nconst VALUE_HASH_MAX_LEN: usize = core::mem::size_of::();\n\nlet property_hash = slice[INDEX_PREFIX_LEN..INDEX_PREFIX_LEN + PROPERTY_HASH_MAX_LEN]\n .try_into()\n .expect(\"property hash slice is 4 bytes\");\n```\n\n### Clippy and formatting\n\nRun clippy and formatting to check for code smells and formatting issues.\n\n```bash\ncargo clippy --workspace -- -D warnings\nrustfmt --edition 2024 --check\n```\n\nyou should run formatting and clippy before finishing your work. Rust crates in this workspace use edition 2024 from their `Cargo.toml`; do not pass `--edition 2024` to `cargo clippy`, because Cargo does not accept that flag for Clippy. Use a current stable Rust toolchain with the matching Clippy component installed.\n\n### Database Key/Value Construction, Parsing, and Use\n\n- ALL database key construction, parsing, and serialisation should be done using the structs in crates/db/src/encoding/v2\n - There are structs here that make building invalid keys impossible and it ensures call sites remain standardised and improves testability\n- ALL database value construction, parsing, and serialisation should be done using the structs in crates/db/src/encoding/v2/values\n - There are structs here that make building invalid keys impossible and it ensures call sites remain standardised and improves testability\n - We are in the process of moving more values to this dir. If you notice inline value use, please either add it to crates/db/src/encoding/v2/values if it is small (e.g. single variant addition) or if it is a major change just note it down.\n\n\n# HelixDB\n\n> HelixDB combines a property graph, approximate vector search, and BM25 full-text search behind one operation-tree query model. Requests run through Cloud, a local server, or the embedded runtime. This file is the full markdown corpus for AI agents.\n\n\n# Introduction\n\nPage type: Concept\n\nHelixDB is a graph database with native vector and full-text search, built on object\nstorage. It stores and searches knowledge and context for applications where both\nexplicit structure and meaning matter.\n\nBecause graph, vector, and text retrieval live in one database, an application can\nwork with connected entities, semantically similar content, and exact terms without\nsynchronizing separate stores. Teams use HelixDB to build enterprise company brains,\nlarge-scale people search, and AI agent swarms.\n\nNew to these ideas? The [learning center](/learn) explains graph databases, vector and\nfull-text search, and AI agent memory from first principles.\n\n```mermaid\n%%{init: {\"themeCSS\": \".cluster-label { translate: -140px 0; }\"}}%%\nflowchart TB\n knowledge[\"Documents, conversations, events, users\"]\n\n subgraph brain[\"Company brain in HelixDB\"]\n relationships[\"Graph Data\"]\n vector[\"Vector search\"]\n text[\"Text search\"]\n context[\"Shared memory and context\"]\n\n relationships --> context\n vector --> context\n text --> context\n end\n\n knowledge --> relationships\n knowledge --> vector\n knowledge --> text\n\n context --> agents[\"AI agent swarms\"]\n context --> search[\"Enterprise search and knowledge bases\"]\n context --> apps[\"Company Brains\"]\n```\n\n## How it works\n\nEverything in HelixDB is one labeled property graph. Nodes are your entities, directed\nedges are the relationships between them, and both carry typed properties.\n\nSearch is not a second system bolted on top. A vector, text, or secondary index is an\naccess path over a property that already lives on a node or edge: the embedding on a\nchunk, the body text of a document, or the `status` field you filter by. That has\nthree consequences:\n\n- **The graph stays the source of truth.** A semantic match and the relationships\n around it are the same data, read in the same transaction.\n- **Nothing needs synchronizing.** There is no separate graph store, vector store, or\n search cluster to keep consistent.\n- **Edges are searchable too.** An index is scoped to a label and a property rather\n than a special node type, so you can search and filter relationships as well as\n entities.\n\n## What you get\n\n- **ACID transactions** across graph, vector, and text data.\n- **Vector search** with prefiltering and over 90% recall.\n- **Full-text search** for exact terms and keyword relevance.\n- **Equality and range filtering** on property values.\n- **Search and filtering on nodes and edges**, not just nodes.\n- **Object storage as the source of truth**, so storage scales independently of compute.\n- **Horizontal scaling** across multi-tenant and single-tenant deployments, with BYOC\n coming soon.\n\n## Why object storage\n\nMost graph databases keep all data on one machine's disk, and in the worst case\nentirely in memory. That caps how much data you can store and makes large graphs\nexpensive.\n\nHelixDB keeps object storage as the source of truth and uses NVMe and memory only as\ncaches. Storage scales separately from compute, so a dataset can grow far beyond the\ncapacity of the machines that serve it while latency and cost stay low.\n\n## Next steps\n\n Start a local instance and run the generated query.\n\n Learn how nodes, edges, properties, and indexes represent your data.\n\n Discuss large-scale Helix Cloud workloads with the founding team.\n\n# Get started\n\nPage type: Tutorial\n\nThis is the canonical local HelixDB quickstart. You will create a project, start\nthe generated `dev` instance, run the generated JSON request, and stop the\ninstance.\n\n## Prerequisites\n\n- Docker, or Podman configured as described below\n- A terminal on macOS or Linux, or PowerShell on Windows\n\nmacOS and Linux:\n\n```bash\ncurl -sSL \"https://install.helix-db.com\" | bash\n```\n\nWindows PowerShell:\n\n```powershell\nirm https://raw.githubusercontent.com/HelixDB/helix-db/main/crates/cli/install.ps1 | iex\n```\n\nIf the CLI is already installed, run [`helix update`](/cli/command-reference/update).\n\nCreate and enter an empty directory, then initialize it:\n\n```bash\nmkdir my-helix-app\ncd my-helix-app\nhelix init local\n```\n\n`helix init local` creates:\n\n- `helix.toml` with one local instance named `dev` on port `6969`.\n- `.helix/` for CLI-managed instance state.\n- `.gitignore` entries for `.helix/`, `.env`, `target/`, and `*.log`.\n- `AGENTS.md` with the current CLI workflow for coding agents.\n- `examples/request.json` with a runnable read request.\n\nIt does not create a Rust, TypeScript, Go, or Python project. Choose an SDK\nafter this CLI journey.\n\nIf you use Podman, set `container_runtime = \"podman\"` under `[project]` in\n`helix.toml` before you start the generated instance. New projects otherwise\ndefault to Docker.\n\n```bash\nhelix start dev\n```\n\nThe CLI starts the local container, publishes it at `http://localhost:6969`,\nand waits for the database health check before it returns.\n\nThe default storage mode is in-memory. Stopping the instance removes its data.\nUse `helix start dev --disk` when you need local persistence.\n\n```bash\nhelix query dev --file examples/request.json\n```\n\nThe generated request counts nodes with the `User` label. A new database\nreturns a `node_count` of zero. Edit the JSON file and run the same command\nagain to iterate.\n\n```bash\nhelix stop dev\n```\n\n`helix stop` is idempotent, so it also exits successfully when the instance is\nalready stopped.\n\n## Use an SDK\n\nThe SDKs build the same JSON operation tree that `helix query` sends to\n`POST /v2/query`. Initialize a normal language project and install one released\nSDK:\n\n```bash Rust\ncargo add helix-db@3.0.0 tokio serde_json\n```\n\n```bash TypeScript\nnpm install @helix-db/helix-db@3.1.0\n```\n\n```bash Go\ngo get github.com/helixdb/helix-db/sdks/go@v0.3.1\n```\n\n```bash Python\npython -m pip install helix-db==0.3.4\n```\n\nContinue with the full setup guide for your language:\n\n Build and execute typed Rust queries.\n\n Build and execute TypeScript queries.\n\n Build and execute Go queries.\n\n Build and execute synchronous or asynchronous Python queries.\n\n## Next steps\n\n Learn how SDK builders become the JSON request sent to HelixDB.\n\n Learn how nodes, edges, labels, and properties fit together.\n\n Add, update, and remove graph data.\n\n See every current CLI command and option.\n\n# Deployment options\n\nPage type: Concept\n\nEvery deployment option runs the same queries with the same SDKs, so you can develop\nagainst one and deploy to another without changing application code. Choose based on\nwhere the engine runs, where data is stored, and who operates it.\n\n| Mode | Best for | Interface | Storage | Availability |\n| --- | --- | --- | --- | --- |\n| Helix Cloud | Production services with managed operations | HTTPS | Managed object storage | Highly available |\n| Local server | Development, production-shaped testing, and self-hosting | HTTP | Memory or S3-compatible storage | Single node |\n| Embedded | In-process applications and local tools | Native SDK call | Memory, disk, or object storage | In process |\n\n## Helix Cloud\n\nHelix Cloud runs a highly available cluster that provides managed deployment, storage,\ndatabase authentication, and read scaling. It supports multi-tenant and single-tenant\ndeployments; BYOC is coming soon.\n\n## Local server\n\nThe local server runs the standalone HelixDB container on your own machine or\ninfrastructure. It exposes the same `POST /v2/query` interface as Helix Cloud, which\nmakes it the default development target: code written against it works unchanged in\nCloud.\n\n## Embedded\n\nEmbedded clients open the engine inside your process and skip HTTP entirely. Rust,\nTypeScript, and Python ship embedded runtimes; the Go SDK is currently HTTP-only.\n\n## Which should I use?\n\n- **Building a networked application?** Develop against the local server.\n- **Going to production?** Use Helix Cloud for managed operations and high\n availability.\n- **Shipping a tool or app that owns its data?** Use embedded mode when process-local\n execution simplifies your architecture and the SDK's native packaging fits how you\n distribute.\n\n## Next steps\n\n Run the server locally with memory or persistent storage.\n\n Create a managed database and connect to it.\n\n Open a writer or reader and review current SDK availability.\n\n# Local server\n\nPage type: Guide\n\nThe `ghcr.io/helixdb/helixdb:v0.0.12` image runs the standalone HelixDB server.\nIt supports Linux on amd64 and arm64.\nIt exposes the same operation-tree request contract used by Helix Cloud at\n`POST /v2/query`; gateway-only Cloud features are not included.\n\n## Choose storage\n\n| Mode | Persistence | Use when |\n| --- | --- | --- |\n| Memory | Lost when the server stops | Fast local iteration and tests |\n| Native directory (`HELIX_DATA_DIR`) | Preserved in a mounted volume or directory | Running the image directly with local persistence |\n| CLI disk (`--disk`) | Preserved in a CLI-managed SeaweedFS volume | Testing restart and persistence through the CLI |\n| Existing S3-compatible store | Owned outside Helix | Reusing SeaweedFS, Ceph, LocalStack, or AWS S3 |\n\n## Start with the CLI\n\nmacOS and Linux:\n\n```bash\ncurl -sSL \"https://install.helix-db.com\" | bash\n```\n\nWindows PowerShell:\n\n```powershell\nirm https://raw.githubusercontent.com/HelixDB/helix-db/main/crates/cli/install.ps1 | iex\n```\n\nThen, in your shell:\n\n```bash\nmkdir my-helix-app\ncd my-helix-app\nhelix init local --name dev # add --disk to make persistence the project default\nhelix start dev # add --disk to persist this instance\n```\n\nThe standalone server accepts queries at `http://localhost:6969/v2/query`.\n\nFor an existing project, set `tag = \"v0.0.12\"` in its `[local.dev]` block in\n`helix.toml` before starting it. An explicitly saved tag overrides the CLI default.\n\nThe first time v0.0.10 or later opens a persisted database, it upgrades the index storage\nversion, and v0.0.9 and earlier then refuse to open that database. Back up the data\nbefore changing the tag if you may need to roll back.\n```bash\nhelix query dev \\\n -e 'readBatch().varAs(\"count\", g().nWithLabel(\"User\").count()).returning([\"count\"])'\n```\n\nThe default mode is in-memory. `helix stop` and `helix restart` discard its data.\n\n## Use an existing object store\n\nPlace credentials in a project-root `.env` file or export them:\n\n```dotenv .env\nAWS_ACCESS_KEY_ID=your-access-key\nAWS_SECRET_ACCESS_KEY=your-secret-key\n# AWS_SESSION_TOKEN=your-session-token\n```\n\n```bash\nhelix start dev \\\n --storage-uri s3://helix-db/my-app \\\n --s3-region us-east-1 \\\n --s3-endpoint-url https://s3.example.com \\\n --persist\n```\n\nAdd `--s3-allow-http` only for a plain HTTP endpoint.\n\n```bash\nhelix start dev \\\n --storage-uri s3://my-bucket/my-app \\\n --s3-region eu-west-2 \\\n --persist\n```\n\n`--persist` stores the resolved configuration in `helix.toml`. Helix does not delete\nexternally managed object-store data during stop, restart, or prune.\n\n## Run the image directly\n\nMemory mode is selected by leaving both `HELIX_DATA_DIR` and `S3_BUCKET` unset:\n\n```bash\ndocker run --rm --name helixdb \\\n -p 6969:8080 \\\n ghcr.io/helixdb/helixdb:v0.0.12\n```\n\nThe standalone server exposes liveness and readiness checks:\n\n```bash\ncurl -fsS http://127.0.0.1:6969/healthz\ncurl -fsS http://127.0.0.1:6969/readyz\n```\n\nDo not set `S3_BUCKET=IN_MEMORY`. Every defined `S3_BUCKET` value selects\nS3-compatible storage and is interpreted as a real bucket name. Setting\n`HELIX_DATA_DIR` and `S3_BUCKET` together causes startup to fail.\n\n## Run with native directory persistence\n\nSet `HELIX_DATA_DIR` to a mounted directory inside the container:\n\n```bash\ndocker volume create helixdb-data\ndocker run --rm --name helixdb \\\n -p 6969:8080 \\\n -e HELIX_DATA_DIR=/var/lib/helix \\\n --mount type=volume,source=helixdb-data,target=/var/lib/helix \\\n ghcr.io/helixdb/helixdb:v0.0.12\n```\n\nStop the server with `docker stop helixdb`. Starting a new container with the\nsame volume preserves its database. Removing the volume deletes the data.\nThis mode needs no object store; the CLI's `--disk` mode uses SeaweedFS.\n\nThe image runs as user and group `65532:65532`. Its `/var/lib/helix` directory\nis prepared for that user, including when initializing a new Docker named volume.\nIf you use a bind mount or an existing volume, its directory must be writable by\nthat user.\n\n## Run with SeaweedFS persistence\n\nThis Compose configuration runs SeaweedFS as a single-node S3 store with a\nstatic identity, creates the `helix-db` bucket on startup, and stores HelixDB\nobjects in the `seaweedfs-data` volume. HelixDB starts once a signed request\nto the bucket succeeds:\n\n```yaml docker-compose.yaml expandable\nservices:\n seaweedfs:\n image: ghcr.io/chrislusf/seaweedfs:4.47@sha256:ce9e796f1fe6f06968f4c04bdaf8f678dad9c8acdfef3d244133d71bfa6bf882\n command:\n - mini\n - -dir=/data\n - -bucket=helix-db\n - -s3.config=/etc/seaweedfs/s3.json\n - -master.telemetry=false\n - -admin.ui=false\n - -webdav=false\n - -s3.port.iceberg=0\n - -s3.port.lance=0\n restart: unless-stopped\n configs:\n - source: seaweedfs-s3\n target: /etc/seaweedfs/s3.json\n volumes:\n - seaweedfs-data:/data\n healthcheck:\n test:\n - CMD\n - curl\n - -fsS\n - -o\n - /dev/null\n - --max-time\n - \"2\"\n - -I\n - --aws-sigv4\n - aws:amz:us-east-1:s3\n - --user\n - helix:helix-local-secret\n - http://127.0.0.1:8333/helix-db\n interval: 1s\n timeout: 5s\n retries: 120\n\n helix:\n image: ghcr.io/helixdb/helixdb:v0.0.12\n restart: unless-stopped\n depends_on:\n seaweedfs:\n condition: service_healthy\n ports:\n - \"6969:8080\"\n environment:\n S3_BUCKET: helix-db\n S3_REGION: us-east-1\n DB_PATH: db/\n AWS_ACCESS_KEY_ID: helix\n AWS_SECRET_ACCESS_KEY: helix-local-secret\n AWS_ENDPOINT: http://seaweedfs:8333\n AWS_ALLOW_HTTP: \"true\"\n\nconfigs:\n seaweedfs-s3:\n content: |\n {\n \"identities\": [\n {\n \"name\": \"helix\",\n \"credentials\": [\n {\"accessKey\": \"helix\", \"secretKey\": \"helix-local-secret\"}\n ],\n \"actions\": [\"Read:helix-db\", \"Write:helix-db\", \"List:helix-db\"]\n }\n ]\n }\n\nvolumes:\n seaweedfs-data:\n```\n\nInline `configs` content needs Docker Compose 2.23.1 or later. The SeaweedFS\ncontainer is not published to the host. Change the example credentials in all\nthree places if you expose it.\n\nRun `docker compose down` to replace the HelixDB container without deleting\nthe SeaweedFS data. `docker compose down -v` deletes the persisted database.\n\nFor an existing object store, use the same HelixDB environment variables and\nomit the SeaweedFS service. For AWS S3, omit the endpoint and HTTP override.\n\nHelixDB's storage engine needs S3 conditional writes: `If-None-Match: *` on\ncreate and `If-Match` on replace must fail with HTTP 412 when the condition\ndoes not hold. A store that ignores them can silently lose data. AWS S3 and\nSeaweedFS 4.09 or later enforce both.\n\n| Variable | Purpose |\n| --- | --- |\n| `HELIX_DATA_DIR` | Selects native disk storage and names its container directory; mount a volume there for persistence |\n| `S3_BUCKET` | Selects S3 mode and names the object-store bucket; omit both storage selectors for memory mode |\n| `S3_REGION` | Region supplied to the S3 client; falls back to `AWS_REGION`, then `AWS_DEFAULT_REGION`, then `us-east-1` |\n| `DB_PATH` | Logical database prefix inside the selected store, including under `HELIX_DATA_DIR`; defaults to `db/` |\n| `AWS_ACCESS_KEY_ID` | Access key |\n| `AWS_SECRET_ACCESS_KEY` | Secret key |\n| `AWS_SESSION_TOKEN` | Optional temporary-credential token |\n| `AWS_ENDPOINT` or `AWS_ENDPOINT_URL_S3` | Non-AWS S3 endpoint |\n| `AWS_ALLOW_HTTP` | Set to `true` or `1` to permit an HTTP endpoint |\n| `HELIX_STRONG_VECTOR_SEARCH_MAX_PENDING_BYTES` | Most unpublished vector work, in bytes, one `strong` vector search scores before it fails with `index_backpressure`; defaults to the index's retained-byte limit (1,000,000,000), which writes reach first. See [Search consistency](/database/helix-db/query-guides/search-consistency#searches-behind-unpublished-changes) |\n| `HELIX_STRONG_TEXT_SEARCH_MAX_ANALYSIS_BYTES` | Most unpublished text, in analysis bytes, one `strong` text search includes per partition before it fails with `index_backpressure`; defaults to 512 MiB (536,870,912). See [Search consistency](/database/helix-db/query-guides/search-consistency#searches-behind-unpublished-changes) |\n\nThe endpoint must be reachable from inside the container; container `localhost` is not\nthe host machine. `DB_PATH` is a logical prefix, not the storage directory. To use\nnative directory persistence, set `HELIX_DATA_DIR` and mount the directory there.\n\n## Add a local disk cache\n\nWith `S3_BUCKET`, the server always keeps recently read data on local disk, ideally\nNVMe, in `/var/cache/helix` unless `HELIX_DISK_CACHE_DIR` names another directory.\nVector indexes on S3 need it: once an index outgrows the memory cache, every graph\nhop that misses it would otherwise wait on its own S3 request. Mount a volume at\n`/var/cache/helix` so the cache survives restarts; without one, each new container\nstarts with an empty cache. With `HELIX_DATA_DIR`, set `HELIX_DISK_CACHE_DIR` to add\nthe disk cache. Memory storage rejects the cache variables.\n\nThe disk cache needs v0.0.7 or later, and the v0.0.6 image and earlier ignore the\n`HELIX_DISK_CACHE_*` variables. v0.0.7 and v0.0.8 cache S3 on disk only when\n`HELIX_DISK_CACHE_DIR` is set, so the example below sets it to the default.\n```bash\nsudo mkdir -p /data/helix-cache\nsudo chown 65532:65532 /data/helix-cache\ndocker run --rm --name helixdb \\\n -p 6969:8080 \\\n -e S3_BUCKET=my-bucket \\\n -e S3_REGION=eu-west-2 \\\n -e HELIX_DISK_CACHE_DIR=/var/cache/helix \\\n -e HELIX_DISK_CACHE_BYTES=107374182400 \\\n -v /data/helix-cache:/var/cache/helix \\\n ghcr.io/helixdb/helixdb:v0.0.12\n```\n\nIn Compose, add a volume at `/var/cache/helix` to the `helix` service. A new\nnamed volume mounted there is already writable; a bind mount must be owned by\n`65532:65532`. When running as another user or outside the image, set\n`HELIX_DISK_CACHE_DIR` to a directory that user can write. With a read-only root\nfilesystem, mount a writable volume (for example a tmpfs or `emptyDir`) at the cache\ndirectory. Use one cache directory per running server and per database; changing\n`DB_PATH` on the same directory leaves the old database's full-text cache behind.\n\n| Variable | Purpose |\n| --- | --- |\n| `HELIX_DISK_CACHE_DIR` | Disk cache directory, created if needed. Defaults to `/var/cache/helix` with `S3_BUCKET`; with `HELIX_DATA_DIR`, setting it enables the disk cache |\n| `HELIX_DISK_CACHE_BYTES` | Total disk budget in bytes, from 64 MiB to 1 TiB; defaults to 8 GiB |\n| `HELIX_DISK_CACHE_MEMORY_BYTES` | Memory tier of the block cache in bytes; defaults to 640 MiB |\n| `HELIX_DISK_CACHE_WARM` | `on` (the default) or `off`: whether the server warms the disk cache at startup |\n\nHalf of the disk budget caches object-store files, 3/8 caches database blocks,\nand the rest caches full-text search data. With `S3_BUCKET`, the object-store cache\nalso keeps the files the server writes; with `HELIX_DATA_DIR` they are already on\nlocal disk, so it keeps only the files the server reads. Changing the budget\nusually changes the block size, which discards the database-block cache at startup\nso it refills from the object store. The object-store cache keeps its files and\nevicts down to a smaller budget as it admits new data. Full-text search data is\ncached on demand, once searches have used it twice; the server downloads none of it\nat startup. At startup and on every admission the full-text cache evicts down to\nits share. Each of these trims spares data admitted or recorded as used in the\nsecond before it (use is recorded at most once a minute) and data still open in\nsearches or the 64 MiB full-text memory cache, so the cache can stay over its share\nby that data until the next admission. It never caches a split larger than its\nwhole share. After a restart, the first search to use each cached split reads and\nchecksums the whole split, up to 64 MiB, before it answers. Budget at least twice\nthe data the server reads often: the object-store cache fetches whole file parts\n(4 MiB, or smaller under a 2 GiB budget), so once that data outgrows half the\nbudget, cold reads fetch more than memory-only caches would. The budget must also\nfit on the cache's filesystem: its free space plus what the cache already uses.\nWhen `HELIX_DISK_CACHE_BYTES` is unset and the 8 GiB default does not fit, startup\nfails naming the variable; without a volume the cache would otherwise share, and\ncould fill, the filesystem of the container runtime. A budget you set that does not\nfit only logs a warning at startup.\n\nOnce storage opens, the server warms the disk cache in the background: it caches the\ndatabase blocks that index the newest files and, with `S3_BUCKET`, the rows vector\nsearches read, using at most half the object-store cache. The warm delays neither\nstartup nor readiness; queries that arrive first read from the object store as usual.\nSet `HELIX_DISK_CACHE_WARM=off` to skip it, and the caches then fill only as queries\nread.\n\nThe block cache also indexes its disk share in memory, outside\n`HELIX_DISK_CACHE_MEMORY_BYTES`. Once full, the index takes roughly 2–9 MiB of RAM\nper GiB of `HELIX_DISK_CACHE_BYTES` (about 20–70 MiB at the default, 2–9 GiB at\n1 TiB), and a restart briefly needs about twice that while it rebuilds the index.\nSize the container's memory limit for this index as well as the memory tier.\n\nThe block cache keeps up to 32,768 files open, so the server needs at least 34,792\nopen files in the worst case (26,600 at the default budget), plus one per open\nfull-text split. It raises its soft open-file limit to the hard limit at startup.\nIf the container's hard limit is below that minimum, startup fails naming\n`HELIX_DISK_CACHE_BYTES`; raise the hard limit with `--ulimit nofile=65536:65536`.\nLowering the budget is not a reliable fix above about 3 GiB, where the file count\ndoes not fall steadily with it; budgets of 1 GiB or less need about 8,200 or fewer.\nRun natively on macOS, the limit is also capped by `sysctl kern.maxfilesperproc`.\n\nStartup also fails with a message naming the variable when a size is invalid or\nout of range, a size is set with `HELIX_DATA_DIR` but without `HELIX_DISK_CACHE_DIR`,\nthe default budget does not fit, the cache directory is not writable or cannot be\nlocked (some network and FUSE filesystems do not support locks), or another running\nserver already uses it. Stop the old container before starting its replacement on\nthe same cache directory.\n\nAn S3 container that ran v0.0.8 or earlier used no local disk, so it can fail or\nuse more resources after upgrading: it needs a hard open-file limit of at least\n26,600 at the default budget (about 8,200 or fewer at 1 GiB or less), about 20–70\nMiB more RAM at the default budget, a writable cache directory (mount a volume with\na read-only root filesystem, and set `HELIX_DISK_CACHE_DIR` when running as a user\nother than `65532`), and room for the 8 GiB default unless `HELIX_DISK_CACHE_BYTES`\nis set.\n\n## Stop or inspect\n\n```bash\nhelix status\nhelix logs dev\nhelix stop dev\n```\n\n## Next steps\n\n Create a project and run your first query.\n\n Open HelixDB directly inside your process.\n\n Move the same application requests to a managed cluster.\n\n Manage instances and raw requests.\n\n# Embedded database\n\nPage type: Guide\n\nEmbedded clients execute operation-tree requests without HTTP. The process opens a\nwriter or read-only handle against memory, disk, or S3-compatible object storage.\n\n## Install\n\nInstall the SDK and its embedded runtime package.\n\n```bash Rust\ncargo add helix-db --features embedded\n```\n\n```bash TypeScript\nnpm install @helix-db/helix-db @helix-db/helix-db-embedded\n```\n\n```bash Go\ngo get github.com/helixdb/helix-db/sdks/go\n```\n\n```bash Python\npython -m pip install helix-db helix-db-embedded\n```\n\n## Open a writer\n\n```rust Rust\nuse helix_db::{Client, HelixDbSource};\n\nlet client = Client::open(HelixDbSource::Disk {\n root: \"/data/helix\".into(),\n database: \"app\".to_string(),\n})\n.await?;\n```\n\n```ts TypeScript\nconst client = await Client.embedded({\n kind: \"disk\",\n root: \"/data/helix\",\n database: \"app\",\n});\n```\n\n```go Go\nclient, err := helix.NewEmbeddedClient(\n\thelix.DiskSource{Root: \"/data/helix\", Database: \"app\"},\n)\nif err != nil {\n\treturn err\n}\n```\n\n```python Python\nfrom helixdb import Client, Disk\n\nclient = Client.embedded(Disk(\"/data/helix\", \"app\"))\n```\n\n## Choose a storage source\n\n| Source | Persistence | Use |\n| --- | --- | --- |\n| In-memory | Process-local | Tests, scratch data, and short-lived tools |\n| Disk | Filesystem path | Persistent single-host applications |\n| Object storage | Bucket and logical database path | Durable shared storage with an S3-compatible service |\n\n```ts In-memory\nconst client = await Client.embedded({\n kind: \"inMemory\",\n database: \"app\",\n});\n```\n\n```ts Disk\nconst client = await Client.embedded({\n kind: \"disk\",\n root: \"/data/helix\",\n database: \"app\",\n});\n```\n\n```ts Object storage\nconst client = await Client.embedded({\n kind: \"objectStorage\",\n database: \"app\",\n bucket: \"helix-production\",\n region: \"eu-west-2\",\n});\n```\n\n## Configure caches\n\nCache configuration is optional and fixed when the handle opens. Local defaults are\nbounded and demand-filled so a small embedded database does not reserve server-sized\ncaches:\n\n| Setting | In-memory | Disk | Object storage |\n| --- | --- | --- | --- |\n| Durable-write flush interval | 1 ms | 3 ms | 100 ms |\n| Vector memory | 64 MiB | 64 MiB | 256 MiB |\n| SlateDB block / metadata | 16 MiB / 8 MiB | 48 MiB / 16 MiB | 512 MiB / 128 MiB |\n| Full-text search | 16 MiB | 16 MiB | 64 MiB |\n| SlateDB / FTS startup warming | Off | Off | Background |\n| Disk cache | Disabled | Disabled | Disabled |\n\nThe local profiles also use a 16 MiB L0 target and a 64 MiB unflushed-data ceiling.\nThe flush interval is the batching delay before storage I/O; filesystem and device\nlatency still apply.\n\nPass an explicit cache configuration to change the vector-memory budget or enable\nbounded disk caches:\n\n| Profile | Behavior |\n| --- | --- |\n| Memory | Uses in-memory database caches |\n| Hybrid | Adds bounded disk caches with explicit paths and byte budgets |\n\n```ts Memory\nconst client = await Client.embedded(\n { kind: \"disk\", root: \"/data/helix\", database: \"app\" },\n {\n vectorMemoryBytes: 512 * 1024 * 1024,\n mode: { kind: \"memory\" },\n },\n);\n```\n\n```ts Hybrid\nconst client = await Client.embedded(\n { kind: \"disk\", root: \"/data/helix\", database: \"app\" },\n {\n vectorMemoryBytes: 512 * 1024 * 1024,\n mode: {\n kind: \"hybrid\",\n slateMemoryBytes: 256 * 1024 * 1024,\n slateDiskPath: \"/var/cache/helix/slate\",\n slateDiskBytes: 4 * 1024 * 1024 * 1024,\n objectStoreDiskPath: \"/var/cache/helix/objects\",\n objectStoreDiskBytes: 8 * 1024 * 1024 * 1024,\n },\n },\n);\n```\n\nCache byte budgets bound those caches. They are not a hard cap on total process RSS;\nrequests and index work can allocate transient memory.\n\n## Open a read-only database\n\nUse a read-only handle for processes that must never mutate the database. It opens an\nexisting disk or object-storage database, executes read requests, and rejects writes.\n\n```rust Rust\nuse helix_db::{Client, HelixDbSource};\n\nlet reader = Client::open_reader(HelixDbSource::Disk {\n root: \"/data/helix\".into(),\n database: \"app\".to_string(),\n})\n.await?;\n```\n\n```ts TypeScript\nconst reader = await Client.embeddedReader({\n kind: \"disk\",\n root: \"/data/helix\",\n database: \"app\",\n});\n```\n\n```go Go\nreader, err := helix.NewEmbeddedReaderClient(\n\thelix.DiskSource{Root: \"/data/helix\", Database: \"app\"},\n)\nif err != nil {\n\treturn err\n}\n```\n\n```python Python\nfrom helixdb import Client, Disk\n\nreader = Client.embedded_reader(Disk(\"/data/helix\", \"app\"))\n```\n\n## Embedded request rules\n\n- Use the same `QueryRequest` and response contract as server mode.\n- Writer handles can execute read and write requests.\n- Server routing options such as writer-only, warm-only, API headers, and durability\n headers are rejected because there is no gateway.\n- Reopen the same disk or object-storage source to retain canonical data across process\n lifetimes.\n\n## Next steps\n\n Run the production-shaped HTTP interface on your machine.\n\n Compare local server, embedded, and Cloud execution.\n\n# SDK setup\n\nPage type: Guide\n\nEvery HelixDB SDK builds the same operation-tree request and sends it to\n`POST /v2/query`, so the query guides apply to all four languages. Pick the SDK for\nyour application's language:\n\n| SDK | Package | HTTP client | Embedded runtime |\n| --- | --- | --- | --- |\n| Rust | `helix-db` (imported as `helix_db`) | Async | Yes, behind the `embedded` feature |\n| TypeScript | `@helix-db/helix-db` (ESM, Node.js 20+) | Async | Yes |\n| Go | `github.com/helixdb/helix-db/sdks/go` | Yes | Not yet |\n| Python | `helix-db` (imported as `helixdb`) | Sync and async | Yes, with `helix-db-embedded` |\n\n Typed DSL, `#[query]` macro, and async HTTP client.\n\n Typed DSL and async client for Node.js 20 or newer.\n\n Query builder and HTTP client.\n\n Synchronous and asynchronous clients.\n\n## Next steps\n\nAfter setup, the [query walkthrough](/database/helix-db/core-concepts/overview) builds\nand runs a first query, and the query guides cover reads, writes, traversals,\nfiltering, projections, parameters, and search in every language.\n\n# Rust SDK\n\nPage type: Guide\n\nThe published `helix-db` 3.0.0 crate provides the query DSL, request types, async\nHTTP client, native graph helpers, and a feature-gated embedded client.\n\nThe package is published as `helix-db` and imported as `helix_db`.\n\n## Install\n\n```bash\ncargo add helix-db@3.0.0\n```\n\nOr add the dependency directly:\n\n```toml Cargo.toml\n[dependencies]\nhelix-db = \"3.0.0\"\nserde = { version = \"1\", features = [\"derive\"] }\nserde_json = \"1\"\ntokio = { version = \"1\", features = [\"macros\", \"rt-multi-thread\"] }\n```\n\n## Define a query\n\n```rust\nuse helix_db::dsl::prelude::*;\n\n#[query]\nfn find_users(tenant_id: String, limit: i64) -> ReadBatch {\n read_batch()\n .var_as(\n \"users\",\n g()\n .n_with_label(\"User\")\n .where_(Predicate::eq(\"tenantId\", tenant_id))\n .limit(limit)\n .value_map(Some(vec![\"$id\", \"name\", \"tenantId\"])),\n )\n .returning([\"users\"])\n}\n```\n\n`#[query]` converts typed arguments into request parameters, sets `query_name` to\nthe function name, and returns `Result`.\n\n## Execute\n\n```rust\nuse helix_db::Client;\n\nlet client = Client::new(Some(\"http://localhost:6969\"))?;\nlet request = find_users(\"acme\".to_string(), 25)?;\nlet response: serde_json::Value = client.query(request).send().await?;\n```\n\nUse `.with_api_key(Some(\"hx_...\"))` for Helix Cloud. Request-builder options can\nrequire the writer, require a warm read, or control durability waiting.\n\n## Build without the macro\n\n```rust\nlet request = QueryRequest::read(\n read_batch()\n .var_as(\"count\", g().n_with_label(\"User\").count())\n .returning([\"count\"]),\n)\n.with_query_name(\"count_users\");\n```\n\n## Embedded runtime\n\nEnable the `embedded` feature:\n\n```bash\ncargo add helix-db --features embedded\n```\n\nSee [Embedded database](/database/helix-db/start-here/local-development/embedded-database)\nfor storage, cache, and handle configuration.\n\n## Verify\n\nRust SDK crate docs are doctests, and the public `#[query]` README journeys are\ncompile-tested as examples:\n\n```bash\ncargo test --manifest-path sdks/rust/Cargo.toml --lib\ncargo test --manifest-path sdks/rust/Cargo.toml --doc\ncargo check --manifest-path sdks/rust/Cargo.toml --example basic_query\ncargo check --manifest-path sdks/rust/Cargo.toml --example readme_sdk_query\ncargo check --manifest-path sdks/rust/Cargo.toml --example readme_macros_query\n```\n\n## Next steps\n\n Learn the batch and traversal model.\n\n Select data by ID, label, or indexed property.\n\n# TypeScript SDK\n\nPage type: Guide\n\nThe published `@helix-db/helix-db` 3.1.0 package targets Node.js 20 or newer and\nemits the same operation-tree AST as the Rust, Go, and Python SDKs.\n\nThe package is ESM and requires Node.js 20 or newer.\n\n## Install\n\n```bash\nnpm install @helix-db/helix-db@3.1.0\n```\n\nThe package is ESM. Set `\"type\": \"module\"` or compile to ESM.\n\n## Define a query\n\n```ts\nimport {\n Predicate,\n defineParams,\n g,\n param,\n readBatch,\n} from \"@helix-db/helix-db\";\n\nexport const findUsersParams = defineParams({\n tenantId: param.string(),\n limit: param.i64(),\n});\n\nexport function findUsers() {\n return readBatch()\n .varAs(\n \"users\",\n g()\n .nWithLabel(\"User\")\n .where(Predicate.eq(\"tenantId\", findUsersParams.tenantId))\n .limit(findUsersParams.limit)\n .valueMap([\"$id\", \"name\", \"tenantId\"]),\n )\n .returning([\"users\"]);\n}\n```\n\n## Execute\n\n```ts\nimport { Client } from \"@helix-db/helix-db\";\n\nconst request = findUsers().toQueryRequest(\n findUsersParams,\n { tenantId: \"acme\", limit: 25n },\n { queryName: \"find_users\" },\n);\n\nconst result = await Client.server(\"http://localhost:6969\")\n .query(request)\n .send();\n```\n\nUse `withApiKey(\"hx_...\")` for Helix Cloud.\n\n## Integer safety\n\nThe SDK preserves 64-bit integers as `bigint`. Use `stringifyJson` or the request's\nserialization methods instead of `JSON.stringify` when a value can contain `bigint`.\n\n## Embedded runtime\n\nInstall the SDK and embedded runtime with\n`npm install @helix-db/helix-db @helix-db/helix-db-embedded`. See\n[Embedded database](/database/helix-db/start-here/local-development/embedded-database)\nfor storage, cache, and handle configuration.\n\n## Verify\n\n```bash\nnpm --prefix sdks/typescript test\n```\n\n## Next steps\n\n Build reads, writes, and parameters.\n\n Open HelixDB directly inside your process.\n\n# Go SDK\n\nPage type: Guide\n\nThe Go SDK builds the shared operation-tree AST and executes requests through a\ntyped HTTP client.\n\nVersion `v0.3.1` ships the server query builder and HTTP client. It does not\ndistribute the native bindings required by embedded execution or native graph\nalgorithms.\n\nThe module path remains `github.com/helixdb/helix-db/sdks/go`; it does not add a\n`/v3` suffix because the module itself has not reached major version 2.\n\n## Install\n\n```bash\ngo get github.com/helixdb/helix-db/sdks/go@v0.3.1\n```\n\n```go\nimport helix \"github.com/helixdb/helix-db/sdks/go\"\n```\n\n## Define a query\n\n```go\nfunc FindUsers(tenantID string, limit int64) helix.Request {\n\tq := helix.ReadQuery(\"find_users\")\n\ttenant := q.ParamString(\"tenant_id\", tenantID)\n\tmaxRows := q.ParamI64(\"limit\", limit)\n\n\treturn q.\n\t\tVarAs(\n\t\t\t\"users\",\n\t\t\thelix.G().\n\t\t\t\tNWithLabel(\"User\").\n\t\t\t\tWhere(helix.PredEq(\"tenantId\", tenant)).\n\t\t\t\tLimit(maxRows).\n\t\t\t\tValueMap(\"$id\", \"name\", \"tenantId\"),\n\t\t).\n\t\tReturning(\"users\")\n}\n```\n\n## Execute\n\n```go\nclient, err := helix.NewClient(\"http://localhost:6969\")\nif err != nil {\n\treturn err\n}\n\nvar response struct {\n\tUsers []map[string]any `json:\"users\"`\n}\nif err := client.Exec(ctx, FindUsers(\"acme\", 25), &response); err != nil {\n\treturn err\n}\n```\n\nWrite requests can pass `helix.WriterOnly()` and `helix.AwaitDurability(true)` execution\noptions. The client does not retry conflicts automatically.\n\n## Release scope\n\nUse `v0.3.1` with a local or remote Helix server through `/v2/query`. Embedded\nconstructors and `Client.Graph` return native-binding-unavailable errors in a\nstandard module installation.\n\n## Verify\n\n```bash\ncd sdks/go\ngo test ./...\n```\n\n## Next steps\n\n Bind typed values and bounds.\n\n Diagnose validation, conflict, and runtime failures.\n\n# Python SDK\n\nPage type: Guide\n\nThe Python SDK is published on PyPI as `helix-db` 0.3.4 and imported as `helixdb`.\nIts builder methods use `snake_case` and produce the same operation-tree AST as\nthe other HelixDB v3 SDKs.\n\n`helix-db` includes the synchronous and asynchronous server clients. Install\n`helix-db-embedded` as well only when the application runs HelixDB in process.\n\n## Install\n\n```bash\npython -m pip install helix-db==0.3.4\n```\n\n## Define a query\n\n```python\nfrom helixdb import Predicate, define_params, g, param, read_batch\n\nfind_users_params = define_params({\n \"tenant_id\": param.string(),\n \"limit\": param.i64(),\n})\n\ndef find_users():\n return (\n read_batch()\n .var_as(\n \"users\",\n g()\n .n_with_label(\"User\")\n .where(Predicate.eq(\"tenantId\", find_users_params.tenant_id))\n .limit(find_users_params.limit)\n .value_map([\"$id\", \"name\", \"tenantId\"]),\n )\n .returning([\"users\"])\n )\n```\n\n## Execute\n\n```python\nfrom helixdb import Client\n\nrequest = find_users().to_query_request(\n find_users_params,\n {\"tenant_id\": \"acme\", \"limit\": 25},\n query_name=\"find_users\",\n)\nresult = Client(\"http://localhost:6969\").query(request)\n```\n\nThe server clients have no native runtime dependency.\n\n### Async execution\n\nReuse one async client to reuse its HTTP connection pool. HTTP requests have no\ntimeout unless you explicitly configure one.\n\n```python\nimport asyncio\n\nimport httpx\n\nfrom helixdb import AsyncClient\n\nasync def execute_queries():\n limits = httpx.Limits(max_connections=20, max_keepalive_connections=10)\n async with AsyncClient(timeout=10.0, limits=limits) as client:\n return await asyncio.gather(\n client.query(request),\n client.execute(request, writer_only=True, timeout=2.0),\n )\n\nresults = asyncio.run(execute_queries())\n```\n\nCancellation propagates as `asyncio.CancelledError`, closes the response stream,\nand leaves the client reusable. The client owns and closes an injected HTTPX\nasync transport. `await client.close()` is idempotent.\n\n## Embedded runtime\n\nInstall the SDK and embedded runtime with\n`python -m pip install helix-db helix-db-embedded`. See\n[Embedded database](/database/helix-db/start-here/local-development/embedded-database)\nfor storage, cache, and handle configuration.\n\n```python\nimport asyncio\n\nfrom helixdb import AsyncClient, Disk, InMemory\n\nasync def query_embedded():\n writer = await AsyncClient.embedded(InMemory(\"app\"))\n async with writer:\n memory_result = await writer.query(request)\n\n reader = await AsyncClient.embedded_reader(Disk(\"./data\", \"seeded-app\"))\n async with reader:\n disk_checkpoint = await reader.query(request)\n\n return memory_result, disk_checkpoint\n\nresults = asyncio.run(query_embedded())\n```\n\nAsync embedded queries await native UniFFI operations directly. Use\n`asyncio.timeout(...)` for cancellation boundaries. Async native graph loading is\nnot part of this API; use the synchronous `Client.graph(...)` API.\n\n## Verify\n\n```bash\nPYTHONDONTWRITEBYTECODE=1 \\\nPYTHONPATH=sdks/python/src \\\npython -m unittest discover sdks/python/tests\n```\n\n## Next steps\n\n Follow the shared batch and traversal model.\n\n Open an in-process writer or reader.\n\n# Roadmap\n\nPage type: Reference\n\n## In progress\n\n- **Smarter cache warming** (ongoing)\n- **Reliability and availability improvements** (ongoing)\n- **Support for non-HA clusters**\n- **Backups and point-in-time recovery**\n- **Expanded query plans for better performance**\n\n## Up next\n\n- **SSO and SAML**\n- **RBAC and fine-grained API key permissions**\n- **AWS PrivateLink**\n- **Audit logs**\n\n## Recently shipped\n\n- **Local Docker deployment**\n- **Dashboard improvements**\n\nSee the [release notes](/database/helix-db/start-here/release-notes) for everything\nthat has shipped.\n\nHave a feature request? [Let us know on Discord](https://discord.com/invite/2stgMPr5BD) or [email us](mailto:founders@helix-db.com).\n\n# Release notes\n\nPage type: Reference\n\n- **Strong text search keeps working during ingest.** A `strong` text search now has its own bound, 512 MiB of unpublished text per partition by default (it was one publication's 64 MiB), and reuses analyses of pending text across searches. Ingest bursts of 20K–40K documents that made v0.0.10's strong text searches fail with `index_backpressure` now complete with no rejections, and a strong text search behind 5,000 pending documents dropped from about 200 ms to 30 ms. Set `HELIX_STRONG_TEXT_SEARCH_MAX_ANALYSIS_BYTES` to change the bound; past it the search fails with retryable `index_backpressure` (`pending_text_analysis_bytes`).\n- **Strong searches decode pending index work once per request.** Several searches in one request share one decoded copy of the pending queue, decoding and exact scoring run off the async workers so they no longer stall other requests, and four strong vector searches in one request behind 160K pending 768-dimension changes went from about 5.0 s to 2.2 s.\n- **Strong vector searches are bounded.** A `strong` vector search decodes and scores at most the index's retained-byte limit of unpublished work by default (1 GB, so writes reach backpressure first). Set `HELIX_STRONG_VECTOR_SEARCH_MAX_PENDING_BYTES` to lower it; past it the search fails with retryable `index_backpressure` (`pending_vector_bytes`).\n- **Queue admission tracks real memory.** Each queued index operation now counts its encoded size plus 576 bytes against the 1 GB per-index limit, so a backlog of many small operations, such as deletes, can no longer use several times the limit in memory. Such backlogs reach `index_backpressure` sooner; the 250,000 pending-entity limit is unchanged.\n- **Writers reopen faster with a large backlog.** Opening a writer loads its queued index work one queue at a time instead of decoding every queue at once: a 2.26 GB backlog opened in about 5 s instead of 25 s, with peak memory bounded by the largest queue instead of the whole backlog.\n- **Publication drains in linear time.** Selecting work to publish no longer rescans the whole queue each time, which was 9.4 s of bookkeeping per 250K-operation drain and is now 0.16 s, and a queue retired by an index drop is discarded without being re-read.\n- No storage changes since v0.0.10: upgrading from v0.0.10 needs no migration. Upgrading from v0.0.9 or earlier follows the v0.0.10 notes below.\n- **CLI 3.4.4** defaults to image v0.0.11. Projects that saved a `tag` in `helix.toml` keep using it until you change it.\n\n- **Upgrading: index storage version 5.** The first time a v0.0.10 writer opens a database, it upgrades the index storage version from 4 to 5. It rewrites only the version marker and rebuilds no index. After that, v0.0.9 and earlier refuse to open the database with `unsupported_index_storage_version`:\n - Upgrade readers before the writer; v0.0.10 readers serve both versions.\n - Never start a v0.0.9-or-earlier writer against an upgraded database.\n - Take a backup before upgrading if you may need to roll back.\n- **[Vector and text indexes publish asynchronously](/database/helix-db/query-guides/search-consistency).** A write commits its graph change together with a durable queued index operation, and a background index worker publishes it into the vector or text index, so writes no longer wait on index maintenance. Steady vector insert publication went from 6.2 to 239 per second. Index builds no longer livelock under concurrent writes: on a c7i.8xlarge with 100 writes/s during the build, backfilling 100K 768-dimension vectors on disk finished in about 2,500 s, where v0.0.9 never finished.\n- **Search consistency.** Read requests set `search_consistency` to `strong` (the default) or `eventual`. `strong` searches include every committed write, published or not. `eventual` searches include a bounded amount of unpublished work and serve the rest as last published, so they can return a node or edge that has since changed tenant, label or indexed property. Write requests always search `strong`, and a write batch that searches an index fails with a retryable `transaction_conflict` if the index worker publishes into that index first. The SDK options ship in the next SDK releases; until then, send `search_consistency` in a direct HTTP request.\n- **[Index backpressure](/database/helix-db/query-guides/search-consistency#index-backpressure).** Each index retains at most 1,000,000,000 bytes or 250,000 pending entities of unpublished work. Three cases fail with `index_backpressure` (HTTP 429, `retryable: true`) before the request takes effect: a write past either limit, a whole-index `strong` search behind more than 800 unpublished changes, and a `strong` text search that would analyze more unpublished text than one publication may (64 MiB by default). Retry it unchanged with bounded backoff. A single write that stages more than 8 MiB of index work for one index fails with `index_operation_batch_too_large` (HTTP 400); split it.\n- **[Text write limits are per document](/database/helix-cloud/operate/limits#active-text-mutation-admission).** `active_text_mutation_limit_exceeded` now checks each indexed document against its own allowances, about 16,000 unique terms, instead of limiting a write to 512 text-indexed entities.\n- **A failing index entry no longer stalls its index.** An entry whose index update fails the same way every time, for example on damaged index data, is held back while the rest of the index keeps publishing. `GET /healthz` counts it under `blocked_index_entity_count`, the server logs an error naming it, and the worker retries it about once a minute. See [troubleshooting](/database/helix-db/query-guides/troubleshooting).\n- **Fixed: `missing simhash` after re-embedding and then deleting a node** (the v0.0.9 known issue). Re-embedding a node no longer loses track of the vector index (HNSW) links that point at it, so deleting it later removes them all, and a node is never linked to itself. Indexes written by v0.0.9 and earlier can still hold such links; drop and recreate the vector index to repair them.\n- **Fixed: counts over a range index with other indexed filters.** A `.count()` over `N.where(...)` or `E.where(...)` that combined a range condition with other indexed conditions counted the range alone, for example 149 rows instead of 49. Counts now apply every filter.\n- **CLI 3.4.3** defaults to image v0.0.10. Projects that saved a `tag` in `helix.toml` keep using it until you change it.\n\n- **Upgrading S3 deployments** — S3 storage now always writes a local disk cache, so an S3 container that ran v0.0.8 or earlier can fail or use more resources after the upgrade:\n - The cache directory, `/var/cache/helix` unless `HELIX_DISK_CACHE_DIR` names another, must be writable. Mount a volume there (required with a read-only root filesystem), and set `HELIX_DISK_CACHE_DIR` when running as a user other than `65532`.\n - The hard open-file limit must be at least 26,600 at the default budget (about 8,200 or fewer at 1 GiB or less). Raise it with `--ulimit nofile=65536:65536`.\n - RSS grows by the block cache's index, about 20–70 MiB at the default budget and twice that briefly after a restart.\n - Without `HELIX_DISK_CACHE_BYTES`, the 8 GiB default budget must fit the cache's filesystem, or startup fails.\n- **[S3 always uses a local disk cache](/database/helix-db/start-here/local-development/local-server#add-a-local-disk-cache)** in `/var/cache/helix` by default, with an 8 GiB default budget. Memory-only S3 is gone: once a vector index outgrew the memory cache, every graph hop waited on its own S3 request. `HELIX_DATA_DIR` and in-memory storage are unchanged.\n- **Faster first vector searches on S3.** Cold batch reads overlap their block fetches, expansions read parents concurrently, and projections prefetch the records they need. After open, the server also warms vector search rows into the disk cache in the background; readiness never waits for it. `HELIX_DISK_CACHE_WARM=off` (default `on`) turns startup warming off. On 2 CPUs, 4 GiB of memory and an 8 GiB cache over S3, the first global vector top-50 after open went from 30.8 s on v0.0.7 to 714 ms once the ~26 s warm finished.\n- **Index sets are kept across `ForEach` iterations and unrelated writes** in the same request, which removes the v0.0.8 known limitation. A set is read again only when an iteration binds a parameter it depends on, or a write creates, deletes or changes indexed properties of nodes with its label. A batch that expands, filters on an index and adds an edge per iteration runs about twice as fast.\n- **Source filters and counts always use indexes.** `N.where(...)`, `E.where(...)` and counts on indexed properties no longer scan the label, including partly indexed ORs, long `IN` lists, parameter lists, `== null`, and counts over `.as()` / `.store()`. A label scan only happens when no condition has an index. On 50k rows, counts after `.as()` went from up to 1.1 s to under 5 ms, and 200-value `IN` lists from up to 1.5 s to about 0.2 s.\n- **Upgrading** — the stored data format is unchanged. Databases written by v0.0.8 open directly with v0.0.9.\n- **Known issue** — updating a node's vector (re-embedding it) and later deleting that node can leave vector index (HNSW) links pointing at the deleted node, and searches that reach them fail with `missing simhash`. Earlier releases are affected too, and a fix is in progress. To repair an affected index, drop and recreate the vector index.\n- **CLI 3.4.2** defaults to image v0.0.9. With `--disk` or S3 storage, `helix start` mounts a per-instance `helix---cache` volume at `/var/cache/helix` for the disk cache, with a 64 MiB budget in disk mode and 1 GiB for an S3 bucket. `helix stop` keeps it and `helix prune` removes it.\n\n- **Filters after a traversal always use indexes.** A `.where(...)` on indexe\n\n\n# HelixDB\n\n> HelixDB combines a property graph, approximate vector search, and BM25 full-text search behind one operation-tree query model. Requests run through Cloud, a local server, or the embedded runtime.\n\nQuickstart (local instance requires Docker or Podman):\n\nmacOS and Linux:\n```bash\ncurl -sSL \"https://install.helix-db.com\" | bash # install the helix CLI\n```\n\nWindows PowerShell:\n```powershell\nirm https://raw.githubusercontent.com/HelixDB/helix-db/main/crates/cli/install.ps1 | iex\n```\n\nThen:\n```bash\nhelix init local # scaffold helix.toml + examples/\nhelix start dev # start a local instance\nhelix query dev -e 'writeBatch().varAs(\"alice\", g().addN(\"User\", { username: \"alice\" })).returning([\"alice\"])'\nhelix query dev -e 'readBatch().varAs(\"users\", g().nWithLabel(\"User\")).returning([\"users\"])'\n```\n\nFull walkthrough: https://docs.helix-db.com/database/helix-db/start-here/quickstart\n\n## HelixDB developer resources\n- [HelixDB HTTP API documentation](https://docs.helix-db.com/database/helix-db/query-guides/http-api): Request contract, authentication, headers, responses, and examples for `POST /v2/query`.\n- [HelixDB OpenAPI specification](https://www.helix-db.com/openapi.json): OpenAPI 3.1 JSON for the public HelixDB HTTP API.\n- [HelixDB authentication guide for agents](https://www.helix-db.com/auth.md): Supported API-key and OAuth surfaces, with links to machine-readable discovery metadata.\n- [HelixDB unified MCP endpoint](https://docs.helix-db.com/database/helix-cloud/connect/mcp): Connect human OAuth, scoped service credentials, and agent registrations to authorized tools on one endpoint.\n- [HelixDB AI Catalog](https://www.helix-db.com/.well-known/ai-catalog.json): ARD catalog of HelixDB agent resources.\n\n## HelixDB — Start Here\n- [Introduction](https://docs.helix-db.com/database/helix-db/start-here/introduction): HelixDB is a graph database with native vector and full-text search, built on object storage — Page type: Concept\n- [Get started](https://docs.helix-db.com/database/helix-db/start-here/quickstart): Initialize HelixDB, start a local instance, run the generated query, and stop it — Page type: Tutorial\n- [Deployment options](https://docs.helix-db.com/database/helix-db/start-here/run-modes): Compare Cloud, local server, and embedded execution — Page type: Concept\n- [Local server](https://docs.helix-db.com/database/helix-db/start-here/local-development/local-server): Start HelixDB locally with memory, a persistent directory, or S3-compatible storage — Page type: Guide\n- [Embedded database](https://docs.helix-db.com/database/helix-db/start-here/local-development/embedded-database): Open HelixDB directly inside your process with explicit storage and cache settings — Page type: Guide\n- [SDK setup](https://docs.helix-db.com/database/helix-db/start-here/sdk-setup/overview): Choose a HelixDB SDK and connect it to a local or Cloud server — Page type: Guide\n- [Rust SDK](https://docs.helix-db.com/database/helix-db/start-here/sdk-setup/rust-project-setup): Build typed HelixDB queries and execute them over HTTP or an embedded engine — Page type: Guide\n- [TypeScript SDK](https://docs.helix-db.com/database/helix-db/start-here/sdk-setup/typescript-project-setup): Build typed HelixDB requests for Node.js applications — Page type: Guide\n- [Go SDK](https://docs.helix-db.com/database/helix-db/start-here/sdk-setup/go-project-setup): Build and execute HelixDB requests with ordinary Go functions — Page type: Guide\n- [Python SDK](https://docs.helix-db.com/database/helix-db/start-here/sdk-setup/python-project-setup): Build HelixDB requests with idiomatic synchronous and asynchronous Python clients — Page type: Guide\n- [Roadmap](https://docs.helix-db.com/database/helix-db/start-here/roadmap): What we're building and what's coming next — Page type: Reference\n- [Release notes](https://docs.helix-db.com/database/helix-db/start-here/release-notes): New features and changes in HelixDB, Helix Cloud, the SDKs, and the CLI — Page type: Reference\n\n## Core Concepts\n- [Data model](https://docs.helix-db.com/database/helix-db/core-concepts/data-model): Understand how HelixDB represents entities, relationships, properties, and indexes — Page type: Concept\n- [Build and run a query](https://docs.helix-db.com/database/helix-db/core-concepts/overview): Build a small write query operation by operation, then read its request and response — Page type: Tutorial\n\n## Query Guides\n- [Writing data](https://docs.helix-db.com/database/helix-db/query-guides/writing-data): Create, update, connect, and remove entities in one typed write batch — Page type: Guide\n- [Reading data](https://docs.helix-db.com/database/helix-db/query-guides/reading-data): Start a traversal from IDs, labels, properties, or previous query results — Page type: Guide\n- [Traverse relationships](https://docs.helix-db.com/database/helix-db/query-guides/traversals): Follow edges, retain row-local bindings, and control duplicate paths — Page type: Guide\n- [Filtering](https://docs.helix-db.com/database/helix-db/query-guides/filtering): Narrow traversal streams with predicates and exact search candidate sets — Page type: Guide\n- [Shape query results](https://docs.helix-db.com/database/helix-db/query-guides/projections): Return properties, computed values, aggregates, and correlated binding rows — Page type: Guide\n- [Bind typed query parameters](https://docs.helix-db.com/database/helix-db/query-guides/parameters): Keep the operation tree stable while request values change — Page type: Guide\n- [Branch, repeat, and condition queries](https://docs.helix-db.com/database/helix-db/query-guides/advanced): Compose sub-traversals and gate named entries without leaving one transaction — Page type: Guide\n- [Query HelixDB with Cypher](https://docs.helix-db.com/database/helix-db/query-guides/cypher): Run Cypher statements beside native queries, and see which parts of openCypher HelixDB supports — Page type: Guide\n- [Secondary indexes](https://docs.helix-db.com/database/helix-db/query-guides/secondary-indexes): Accelerate equality, uniqueness, and ordered property lookups — Page type: Guide\n- [Vector indexes](https://docs.helix-db.com/database/helix-db/query-guides/vector-indexes): Create vector indexes and run nearest-neighbor search — Page type: Guide\n- [Text indexes](https://docs.helix-db.com/database/helix-db/query-guides/text-indexes): Create BM25 indexes and run ranked full-text search — Page type: Guide\n- [Prefiltered search](https://docs.helix-db.com/database/helix-db/query-guides/prefiltering): Rank only the nodes or edges a traversal reaches with vector or BM25 search — Page type: Guide\n- [Search consistency](https://docs.helix-db.com/database/helix-db/query-guides/search-consistency): Choose whether vector and text searches include unpublished index work, and handle index backpressure — Page type: Guide\n- [HelixDB HTTP API and OpenAPI specification](https://docs.helix-db.com/database/helix-db/query-guides/http-api): Call the HelixDB v2 query endpoint and discover its machine-readable OpenAPI 3.1 contract — Page type: Reference\n- [Query error reference](https://docs.helix-db.com/database/helix-db/query-guides/error-handling): Branch on stable error codes, apply retry rules, and look up every HelixDB query error — Page type: Reference\n- [Troubleshoot HelixDB](https://docs.helix-db.com/database/helix-db/query-guides/troubleshooting): Diagnose query, index, vector, embedded, and local runtime failures — Page type: Troubleshooting\n\n## Helix Cloud — Start Here\n- [Get started with Helix Cloud](https://docs.helix-db.com/database/helix-cloud/start-here/using-the-cloud): Sign in, create a workspace and choose its plan, provision a database, and test the connection — Page type: Tutorial\n- [Connect to Helix Cloud](https://docs.helix-db.com/database/helix-cloud/start-here/working-with-enterprise): Connect an SDK or HTTP client to a Helix Cloud database and control request routing — Page type: Guide\n- [Architecture](https://docs.helix-db.com/database/helix-cloud/start-here/architecture): How the Helix Cloud gateway, writer, readers, caches, and object storage serve reads and writes — Page type: Concept\n\n## Connect and automate\n- [Helix Cloud MCP](https://docs.helix-db.com/database/helix-cloud/connect/mcp): Connect users and agents to the unified Helix Cloud MCP endpoint — Page type: Reference\n\n## Operate\n- [Security](https://docs.helix-db.com/database/helix-cloud/operate/security): Authenticate requests, handle API keys, and review encryption and enterprise security features — Page type: Reference\n- [Multi-tenancy](https://docs.helix-db.com/database/helix-cloud/operate/multi-tenancy): Isolate application tenants with row-level scoping and tenant-partitioned search indexes — Page type: Guide\n- [Guarantees](https://docs.helix-db.com/database/helix-cloud/operate/guarantees): Atomicity, isolation, durability, index activation, and read-after-write behavior — Page type: Reference\n- [Limits](https://docs.helix-db.com/database/helix-cloud/operate/limits): Understand Helix Cloud request rate limits and database constraints — Page type: Reference\n- [Tradeoffs](https://docs.helix-db.com/database/helix-cloud/operate/tradeoffs): What the Helix Cloud architecture is optimized for, and where another system may fit better — Page type: Concept\n- [Helix Cloud gateway errors](https://docs.helix-db.com/database/helix-cloud/operate/error-handling): Use stable Helix Cloud error codes, HTTP statuses, and SDK error metadata — Page type: Reference\n\n## Helix Foundry — Start Here\n- [What is Helix Foundry?](https://docs.helix-db.com/foundry/start-here/introduction): Helix Foundry connects your company's data, drafts an ontology across it, and loads it into a Helix database you can explore — Page type: Concept\n- [Helix Foundry quickstart](https://docs.helix-db.com/foundry/start-here/quickstart): Sign in, connect a source, generate an ontology, load it into a Helix database and explore it — Page type: Tutorial\n- [Workspaces and navigation](https://docs.helix-db.com/foundry/start-here/workspaces-and-navigation): Sign in to Helix Foundry, choose or create a workspace, and find your way with the sidebar, search and themes — Page type: Guide\n\n## Data\n- [Connect and sync data](https://docs.helix-db.com/foundry/data/connect-data): Add a source to a Helix Foundry workspace, test its credential, sync its tables and read what each table holds — Page type: Guide\n- [Connectors](https://docs.helix-db.com/foundry/data/connectors): What each Helix Foundry source needs, the permissions to give it, the tables it syncs and its limits — Page type: Reference\n\n## Ontologies\n- [Create an ontology](https://docs.helix-db.com/foundry/ontologies/create-an-ontology): Create a Helix Foundry ontology on an existing Helix database or a new one, and read its overview — Page type: Guide\n- [Generate and version an ontology](https://docs.helix-db.com/foundry/ontologies/generate-and-version): Ask Helix Foundry's agent to draft an ontology from your synced tables and documents, review each version, and choose the current one — Page type: Guide\n- [Upload documents](https://docs.helix-db.com/foundry/ontologies/documents): Upload Markdown and text files to a Helix Foundry ontology so generations and loads read the names and facts they hold — Page type: Guide\n- [Load data into a Helix database](https://docs.helix-db.com/foundry/ontologies/load-data): Write an ontology's current version, your synced tables and your documents into its Helix database, and manage its loads — Page type: Guide\n\n## Explore\n- [Explore the graph](https://docs.helix-db.com/foundry/explore/explorer): Read what a Helix Foundry load wrote as a graph: search, expand, inspect, pick a load and compare two — Page type: Guide\n- [Records and entities](https://docs.helix-db.com/foundry/explore/records-and-entities): Read a Helix Foundry load as tables by type, open a record's links and sources, and see everything about one entity — Page type: Guide\n\n## Ask\n- [Ask questions of your data](https://docs.helix-db.com/foundry/ask/ask-questions): Ask a Helix Foundry ontology questions in plain language and get answers that cite where they came from. Coming soon. — Page type: Guide; Status: Preview\n\n## Workspace\n- [Members and roles](https://docs.helix-db.com/foundry/workspace/members-and-roles): See who is in a Helix Foundry workspace, invite people, and what owners, admins and members can do — Page type: Guide\n- [Plans and billing](https://docs.helix-db.com/foundry/workspace/plans-and-billing): Compare Helix Foundry Free, Pro and Max, upgrade a workspace, switch tiers, cancel, resume and manage payment — Page type: Guide\n\n## Reference\n- [Helix Foundry limits](https://docs.helix-db.com/foundry/reference/limits): Every Helix Foundry limit in one place: syncs, generations, documents, loads, spending and reads — Page type: Reference\n- [Troubleshooting Helix Foundry](https://docs.helix-db.com/foundry/reference/troubleshooting): What Helix Foundry's sign-in, connection, sync, generation, database and load messages mean, and what to do — Page type: Troubleshooting\n\n## Using the helix CLI\n- [Getting started with HelixDB CLI](https://docs.helix-db.com/cli/getting-started): Install the CLI, run locally, or link a WorkOS-authenticated Cloud database — Page type: Tutorial\n- [Local development](https://docs.helix-db.com/cli/workflows/local): Run a local instance and iterate on dynamic JSON queries — Page type: Guide\n- [Helix Cloud CLI workflow](https://docs.helix-db.com/cli/workflows/helix_cloud): Authenticate, link, query, and manage Cloud resources — Page type: Guide\n- [CLI configuration](https://docs.helix-db.com/cli/configuration): Project linkage and WorkOS session files — Page type: Reference\n- [CLI troubleshooting](https://docs.helix-db.com/cli/troubleshooting): Recover local and WorkOS-authenticated Cloud CLI operations — Page type: Troubleshooting\n\n## CLI Command Reference\n- [CLI command reference](https://docs.helix-db.com/cli/command-reference): Every Helix CLI command, grouped by what it manages — Page type: Reference\n- [helix add](https://docs.helix-db.com/cli/command-reference/add): Add a local instance or a Helix Cloud database link to an existing project — Page type: Reference\n- [helix auth](https://docs.helix-db.com/cli/command-reference/auth): Log in to Helix Cloud, check the session, or log out — Page type: Reference\n- [helix api](https://docs.helix-db.com/cli/command-reference/api): Call a Helix Cloud API endpoint with your CLI login session — Page type: Reference\n- [helix chef](https://docs.helix-db.com/cli/command-reference/chef): Bootstrap a first HelixDB app with a coding agent — Page type: Reference\n- [helix cluster](https://docs.helix-db.com/cli/command-reference/cluster): List and inspect Helix Cloud clusters and their active indexes — Page type: Reference\n- [helix cypher](https://docs.helix-db.com/cli/command-reference/cypher): Execute or explain one Cypher statement against a local instance — Page type: Reference\n- [helix database](https://docs.helix-db.com/cli/command-reference/database): Discover and manage Helix Cloud databases and application keys — Page type: Reference\n- [helix delete](https://docs.helix-db.com/cli/command-reference/delete): Remove an instance from helix.toml and clean up its local state — Page type: Reference\n- [helix doctor](https://docs.helix-db.com/cli/command-reference/doctor): Check an instance's setup: runtime, storage, disk cache, memory, and index use — Page type: Reference\n- [helix explorer](https://docs.helix-db.com/cli/command-reference/explorer): Browse a running local instance in the graph Explorer — Page type: Reference\n- [helix feedback](https://docs.helix-db.com/cli/command-reference/feedback): Open a pre-filled feedback issue for the Helix team — Page type: Reference\n- [helix init](https://docs.helix-db.com/cli/command-reference/init): Create a local project or a WorkOS-authenticated Cloud link — Page type: Reference\n- [helix logs](https://docs.helix-db.com/cli/command-reference/logs): View local logs or recent Cloud query errors — Page type: Reference\n- [helix metrics](https://docs.helix-db.com/cli/command-reference/metrics): Configure CLI telemetry and usage metrics collection — Page type: Reference\n- [helix project](https://docs.helix-db.com/cli/command-reference/project): Discover, manage, and link Helix Cloud projects — Page type: Reference\n- [helix prune](https://docs.helix-db.com/cli/command-reference/prune): Remove Helix-owned local containers, volumes, and instance state — Page type: Reference\n- [helix query](https://docs.helix-db.com/cli/command-reference/query): Execute a direct Helix v3 query against a local instance or a Cloud database — Page type: Reference\n- [helix restart](https://docs.helix-db.com/cli/command-reference/restart): Restart a background local instance — Page type: Reference\n- [helix skills](https://docs.helix-db.com/cli/command-reference/skills): Install, refresh, and list the Helix agent skills — Page type: Reference\n- [helix start](https://docs.helix-db.com/cli/command-reference/start): Start a local instance in the background or foreground — Page type: Reference\n- [helix status](https://docs.helix-db.com/cli/command-reference/status): Inspect local runtime or current Cloud database state — Page type: Reference\n- [helix stop](https://docs.helix-db.com/cli/command-reference/stop): Stop a background local instance and remove its containers — Page type: Reference\n- [helix service-credential](https://docs.helix-db.com/cli/command-reference/service-credential): Manage workspace-owned credentials for headless HTTP API and unified MCP clients — Page type: Reference\n- [helix shell](https://docs.helix-db.com/cli/command-reference/shell): Run line-oriented Helix v3 JSON requests — Page type: Reference\n- [helix update](https://docs.helix-db.com/cli/command-reference/update): Update the Helix CLI and refresh installed agent skills — Page type: Reference\n- [helix workspace](https://docs.helix-db.com/cli/command-reference/workspace): Discover WorkOS workspace memberships — Page type: Reference\n\n## Learning center\n- [Learning center](https://docs.helix-db.com/learn/index): Plain-language answers about graph databases, vector search, full-text search, AI agent memory, and modern database architecture. — Page type: Concept\n\n## Graph databases\n- [What is a graph database?](https://docs.helix-db.com/learn/graph-databases/what-is-a-graph-database): A graph database stores things as nodes and the connections between them as edges, and answers questions by following those connections. — Page type: Concept\n- [What is the difference between a graph database and a relational database?](https://docs.helix-db.com/learn/graph-databases/graph-vs-relational-database): A relational database keeps data in tables and rebuilds connections with joins; a graph database stores connections as edges and follows them. — Page type: Concept\n- [What is a knowledge graph?](https://docs.helix-db.com/learn/graph-databases/what-is-a-knowledge-graph): A knowledge graph is a connected collection of facts about things and how they relate, organized by a schema so software can query and cite it. — Page type: Concept\n- [What is a property graph?](https://docs.helix-db.com/learn/graph-databases/what-is-a-property-graph): A property graph stores data as labeled nodes and edges with key-value properties on both, so a relationship can carry its own details. — Page type: Concept\n- [What is the difference between a property graph and RDF?](https://docs.helix-db.com/learn/graph-databases/property-graph-vs-rdf): A property graph stores nodes and edges that carry their own properties; RDF stores every fact as a three-part triple named by global IDs. — Page type: Concept\n\n## Vector search\n- [What is vector search?](https://docs.helix-db.com/learn/vector-search/what-is-vector-search): Vector search finds results by meaning instead of exact words, by comparing embeddings: lists of numbers that capture what content is about. — Page type: Concept\n- [What are vector embeddings?](https://docs.helix-db.com/learn/vector-search/what-are-vector-embeddings): A vector embedding is a list of numbers, produced by a machine learning model, that captures what a piece of content means. — Page type: Concept\n- [What is a vector database?](https://docs.helix-db.com/learn/vector-search/what-is-a-vector-database): A vector database stores embeddings, lists of numbers that capture what content means, and quickly finds the ones most similar to a query. — Page type: Concept\n- [What is HNSW?](https://docs.helix-db.com/learn/vector-search/what-is-hnsw): HNSW is a vector search index that links each vector to its nearest neighbors in layers, so a search can hop quickly to similar items. — Page type: Concept\n- [What is filtered vector search?](https://docs.helix-db.com/learn/vector-search/filtered-vector-search): Filtered vector search finds the most similar items among only those that pass a rule, such as a tenant, a date range, or a permission check. — Page type: Concept\n- [What is the difference between cosine, Euclidean, and Manhattan distance?](https://docs.helix-db.com/learn/vector-search/vector-distance-metrics): Cosine distance compares direction, Euclidean measures the straight-line gap, and Manhattan adds up the per-dimension gaps between two embeddings. — Page type: Concept\n\n## Full-text search\n- [What is full-text search?](https://docs.helix-db.com/learn/full-text-search/what-is-full-text-search): Full-text search finds documents by the words inside them and lists the best matches first, using an inverted index and a relevance score such as BM25. — Page type: Concept\n- [What is BM25?](https://docs.helix-db.com/learn/full-text-search/what-is-bm25): BM25 is a scoring formula that ranks documents for a keyword search by how rare each word is, how often it appears, and how long the document is. — Page type: Concept\n- [What is hybrid search?](https://docs.helix-db.com/learn/full-text-search/hybrid-search): Hybrid search runs a keyword search and a vector search for the same query, then merges the results so it finds both exact terms and similar meaning. — Page type: Concept\n\n## AI memory and RAG\n- [What is retrieval-augmented generation (RAG)?](https://docs.helix-db.com/learn/ai-memory/what-is-rag): RAG has an AI model answer from documents looked up at question time, so answers can use private, current data and cite their sources. — Page type: Concept\n- [What is GraphRAG?](https://docs.helix-db.com/learn/ai-memory/what-is-graphrag): GraphRAG finds context for an AI model by following links between facts in a graph, not only by matching text that is similar to the question. — Page type: Concept\n- [What is AI agent memory?](https://docs.helix-db.com/learn/ai-memory/what-is-ai-agent-memory): AI agent memory lets an AI assistant store, update, and recall what it learns across sessions, outside the model's context window. — Page type: Concept\n- [How do you build long-term memory for AI agents?](https://docs.helix-db.com/learn/ai-memory/long-term-memory-for-ai-agents): Build agent long-term memory from versioned, user-scoped facts: catch duplicates and forget on write, then search and expand on read. — Page type: Concept\n\n## Database architecture\n- [Why build a database on object storage?](https://docs.helix-db.com/learn/database-architecture/object-storage-databases): A database on object storage keeps its data in a durable object store and uses server memory and disks as cache, so storage and compute scale separately. — Page type: Concept\n- [Do you need separate graph, vector, and text databases?](https://docs.helix-db.com/learn/database-architecture/one-database-for-graph-vector-and-text): Often not. One database that stores relationships and indexes the same records for vector and keyword search avoids sync pipelines and stale copies. — Page type: Concept\n"}