repository·main·Indexed 25 days ago
https://github.com/helixdb/helix-dbA graph-vector database built in Rust for AI applications, knowledge graphs, and RAG memory, providing a unified platform for graph, vector, KV, document, and relational data. Includes documentation for the helix-cli (v3.0.8) for local instance and Enterprise Cloud management, as well as SDKs for Rust, TypeScript, Python, and Go.
HelixDB is a graph-vector database that supports graph traversals, vector similarity search, and full-text search.
N::): Graph vertices with properties.E::): Relationships between nodes.V::): High-dimensional embeddings.In, Out, InE, OutE.AddN, AddE, Update, Drop.Follow these steps to set up a local development environment for HelixDB:
query command. This sends the request to the POST /v1/query endpoint.Use the following commands to manage your local development environment:
run: Start a local v2 instance. By default, it runs in the background. Use --foreground to attach to the process or --disk to use persistent local storage.stop: Stop a running local instance.restart: Restart a local instance.status: Check the status of local instances.logs: View local container logs.prune: Clean up Helix-owned local containers, disk-mode volumes, and workspaces.delete: Remove an instance from helix.toml and clean up the local runtime state.The @helix-db/helix-db package provides a TypeScript query DSL and HTTP client for HelixDB. You can define parameter schemas, build queries using functional builders, and serialize them into JSON for dynamic requests.
To create a dynamic request, define your parameters with defineParams, build a query using readBatch() or writeBatch(), and then use .toDynamicJson() or .toDynamicRequest() to prepare the payload.
import { defineParams, g, param, readBatch } from "@helix-db/helix-db";
const params = defineParams({
tenantId: param.string(),
limit: param.i64(),
});
function findUsers(p = params) {
return readBatch()
.varAs("users", g().nWithLabel("User").limit(p.limit).valueMap(["$id", "name"]))
.returning(["users"]);
}
const body = findUsers().toDynamicJson(params, {
tenantId: "acme",
limit: 25n,
});To implement vector search, you must first create a vector index and insert vectors, then perform the search.
1. Create Index and Insert Data:
Use create_vector_index_nodes to initialize the index on a specific label and property, then use add_n to insert nodes with embeddings.
2. Execute Search:
Use vector_search_nodes to find the top-k nearest neighbors. You can use .value_map() to retrieve both the virtual metadata (like $id and $distance) and stored properties (like title).
// 1. Create index and insert vectors
write_batch()
.var_as(
"create_doc_index",
g().create_vector_index_nodes(
"Doc",
"embedding",
None::<&str>,
),
)
.var_as(
"doc_a",
g().add_n(
"Doc",
vec![
("title", PropertyValue::from("A")),
("embedding", PropertyValue::from(vec![1.0f32, 0.0, 0.0])),
],
),
)
.returning(["create_doc_index", "doc_a"]);
// 2. Node vector search
read_batch()
.var_as(
"doc_hits",
g().vector_search_nodes("Doc", "embedding", vec![1.0f32, 0.0, 0.0], 5, None)
.value_map(Some(vec!["$id", "$distance", "title"])),
)
.returning(["doc_hits"]);The Helix CLI is used to manage local instances and interact with Helix Cloud. Use the following command to install it on your system:
curl -sSL "https://install.helix-db.com" | bashTo update an existing installation to the latest version, run:
helix updateinit command to initialize a new v2 project. This creates a helix.toml configuration file and includes a dynamic query example to help you get started.The Python SDK provides an idiomatic query-builder DSL and a dependency-free HTTP client to send dynamic queries to the POST /v1/query endpoint. The DSL uses snake_case methods, but also provides compatibility aliases (e.g., nWithLabel, valueMap) for users translating examples from TypeScript. Use read_batch() to construct queries and Client.query().dynamic().send() to execute them.
from helixdb import Client, Predicate, g, read_batch
query = (
read_batch()
.var_as(
"users",
g()
.n_with_label("User")
.where(Predicate.eq("status", "active"))
.limit(25)
.value_map(["$id", "name", "status"]),
)
.returning(["users"])
)
request = query.to_dynamic_request()
result = Client("http://localhost:6969").query().dynamic(request).send()Use .bind("name") during a traversal to keep track of specific elements (nodes or edges) encountered at a certain step. This allows you to correlate earlier elements with later results in a multi-hop path.
To output these correlated elements, use .project_distinct_bindings(...) with BindingProjection::binding("binding_name", "field", "output_name").
Note: Bindings are row-local. You can also use BindingProjection::coalesce(...) to handle optional branches in your traversal.
read_batch()
.var_as(
"dependencies",
g()
.n_with_label("Service")
.where_(Predicate::eq("tenant_id", "acme"))
.bind("service")
.out(Some("ROUTES_TO"))
.where_(Predicate::eq("tenant_id", "acme"))
.bind("pod")
.in_(Some("MANAGES"))
.where_(Predicate::eq("tenant_id", "acme"))
.bind("owner")
.project_distinct_bindings(vec![
BindingProjection::binding("service", "$id", "service_id"),
BindingProjection::binding("workload", "$id", "workload_id"),
]),
)
.returning(["dependencies"]);Add helix-db to your [dependencies] in Cargo.toml. To use the curated builder API for shorter query code, import the prelude.
Note: The crate is named helix-db in Cargo, but the library is imported as helix_db in your Rust code.
helix-db = "2.0.0"use helix_db::dsl::prelude::*;To run the SDK tests from the repository root, use the following command:
PYTHONPATH=sdks/python/src python -m unittest discover sdks/python/tests