HelixDB Docs

Guide

Use a source predicate to select the initial candidates and .where(...) for expression-based filtering later in a traversal. Vector and full-text search prefiltering rank only an exact traversal-defined candidate set.

Common predicates

Intent	Builder
Equality	`eq(property, value)`
Comparison	`gt`, `gte`, `lt`, `lte`
Inclusive range	`between`
Set membership	`isIn` / `is_in`
Property exists	`hasKey` / `has_key`
Prefix	`startsWith` / `starts_with`
Boolean composition	`and`, `or`, `not`

Values can be literals or typed parameter expressions.

Filter a stream

g()
    .n_with_label("User")
    .where_(Predicate::gte("score", 100))
    .value_map(Some(vec!["$id", "name", "score"]))

import { Predicate, g } from "@helix-db/helix-db";

g()
  .nWithLabel("User")
  .where(Predicate.gte("score", 100))
  .valueMap(["$id", "name", "score"])

helix.G().
	NWithLabel("User").
	Where(helix.PredGte("score", int64(100))).
	ValueMap("$id", "name", "score")

(
    g()
    .n_with_label("User")
    .where(Predicate.gte("score", 100))
    .value_map(["$id", "name", "score"])
)

{
  "request_type": "read",
  "query_name": "ranked_users",
  "query": {
    "read": {
      "entries": [{
        "query": {
          "name": "users",
          "root": {
            "value_map": {
              "input": {
                "where": {
                  "input": {
                    "nodes_where": {
                      "predicate": {
                        "eq": {
                          "left": { "property": "$label" },
                          "right": { "constant": { "string": "User" } }
                        }
                      }
                    }
                  },
                  "predicate": {
                    "gte": {
                      "left": { "property": "score" },
                      "right": { "constant": { "i64": 100 } }
                    }
                  }
                }
              },
              "properties": ["$id", "name", "score"]
            }
          }
        }
      }],
      "returns": ["users"]
    }
  }
}

Vector prefiltering

Vector prefiltering starts with a node or edge traversal, then ranks only the exact members of that stream. Use it when graph membership is a correctness boundary, such as “documents this user may access” or “products reachable from this category.” The execution order is graph traversal → exact candidate membership → vector ranking → top k. The traversal membership is authoritative. Approximate index structures may accelerate ranking, but a result outside the candidate set cannot be returned.

Rank a node stream

This request finds projects owned by the current user, ranks that exact set by embedding distance, and returns the top five.

This query requires an active three-dimensional cosine vector index on Project.embedding. Create and activate that index before running the request.

use helix_db::dsl::prelude::*;

#[query]
fn owned_project_matches(
    username: String,
    query_vector: Vec<f32>,
    limit: i64,
) -> ReadBatch {
    read_batch()
        .var_as(
            "matches",
            g()
                .n_with_label_where("User", SourcePredicate::eq("username", username))
                .out(Some("OWNS"))
                .vector_search_with("Project", "embedding", query_vector, limit, None)
                .value_map(Some(vec!["$id", "name", "$distance"])),
        )
        .returning(["matches"])
}

let request = owned_project_matches(
    "alice".to_string(),
    vec![1.0f32, 0.0, 0.0],
    5,
)?;

import {
  SourcePredicate,
  defineParams,
  g,
  param,
  readBatch,
} from "@helix-db/helix-db";

const params = defineParams({
  username: param.string(),
  query_vector: param.array(param.f32()),
  limit: param.i64(),
});

const query = readBatch()
  .varAs(
    "matches",
    g()
      .nWithLabelWhere("User", SourcePredicate.eq("username", params.username))
      .out("OWNS")
      .vectorSearchWith("Project", "embedding", params.query_vector, params.limit)
      .valueMap(["$id", "name", "$distance"]),
  )
  .returning(["matches"]);

const request = query.toQueryRequest(
  params,
  { username: "alice", query_vector: [1, 0, 0], limit: 5n },
  { queryName: "owned_project_matches" },
);

q := helix.ReadQuery("owned_project_matches")
username := q.ParamString("username", "alice")
queryVector := q.ParamArray(
	"query_vector",
	[]float32{1, 0, 0},
	helix.ParamTypeF32(),
)
limit := q.ParamI64("limit", 5)

request := q.
	VarAs(
		"matches",
		helix.G().
			NWithLabelWhere("User", helix.SourceEq("username", username)).
			Out("OWNS").
			VectorSearchNodesWithin("Project", "embedding", queryVector, limit).
			ValueMap("$id", "name", "$distance"),
	).
	Returning("matches")

from helixdb import SourcePredicate, define_params, g, param, read_batch

params = define_params({
    "username": param.string(),
    "query_vector": param.array(param.f32()),
    "limit": param.i64(),
})

query = (
    read_batch()
    .var_as(
        "matches",
        g()
        .n_with_label_where(
            "User", SourcePredicate.eq("username", params.username)
        )
        .out("OWNS")
        .vector_search_with(
            "Project", "embedding", params.query_vector, params.limit
        )
        .value_map(["$id", "name", "$distance"]),
    )
    .returning(["matches"])
)

request = query.to_query_request(
    params,
    {
        "username": "alice",
        "query_vector": [1.0, 0.0, 0.0],
        "limit": 5,
    },
    query_name="owned_project_matches",
)

{
  "request_type": "read",
  "query_name": "owned_project_matches",
  "query": {
    "read": {
      "entries": [{
        "query": {
          "name": "matches",
          "root": {
            "value_map": {
              "input": {
                "vector_search_nodes_within": {
                  "input": {
                    "out": {
                      "input": {
                        "nodes_where": {
                          "predicate": {
                            "and": {
                              "predicates": [
                                {
                                  "eq": {
                                    "left": { "property": "$label" },
                                    "right": { "constant": { "string": "User" } }
                                  }
                                },
                                {
                                  "eq": {
                                    "left": { "property": "username" },
                                    "right": { "param": "username" }
                                  }
                                }
                              ]
                            }
                          }
                        }
                      },
                      "label": "OWNS"
                    }
                  },
                  "label": "Project",
                  "property": "embedding",
                  "query_vector": { "expr": { "param": "query_vector" } },
                  "k": { "expr": { "param": "limit" } }
                }
              },
              "properties": ["$id", "name", "$distance"]
            }
          }
        }
      }],
      "returns": ["matches"]
    }
  },
  "parameters": {
    "username": "alice",
    "query_vector": [1, 0, 0],
    "limit": 5
  },
  "parameter_types": {
    "username": "string",
    "query_vector": { "array": "f32" },
    "limit": "i64"
  }
}

Use VectorSearchEdgesWithin in Go after an edge traversal. Rust vector_search_with, TypeScript vectorSearchWith, and Python vector_search_with select the node or edge wire operation from the current stream. Their literal forms are vector_search and vectorSearch.

Requirements

Create a compatible vector index for the candidate label and property.
Match the index dimension exactly.
Use the same tenant partition value as the index when it is tenant-partitioned.
Preserve $distance in a projection before traversing away from a ranked hit.
Bound the candidate traversal when its size can grow without application limits.

Exact membership does not mean the vector engine exhaustively compares every candidate embedding. It means the final result is checked against the exact traversal set.

When to search without a prefilter

Use a source vector search when the whole indexed label and optional tenant partition is the intended candidate set. Use vector prefiltering when relationships, permissions, or earlier filters define membership.

Full Text Search prefiltering

Full-text search (FTS) prefiltering starts with a node or edge traversal, then ranks only the unique IDs in that stream by BM25 score. Use it when relationships, permissions, or earlier predicates define which records are eligible for text search. The execution order is graph traversal → exact candidate membership → BM25 ranking → top k. Results are identical to an exhaustive BM25 search of the selected tenant partition, intersected with the candidate IDs, followed by deterministic top-k selection. BM25 statistics still come from the full tenant partition.

Rank a node stream

This request finds documents the current user can read, ranks that exact set for "graph databases", and returns the top five.

This query requires an active text index on Document.body. Create and activate that index before running the request.

use helix_db::dsl::prelude::*;

#[query]
fn readable_document_matches(
    username: String,
    query_text: String,
    limit: i64,
) -> ReadBatch {
    read_batch()
        .var_as(
            "matches",
            g()
                .n_with_label_where("User", SourcePredicate::eq("username", username))
                .out(Some("CAN_READ"))
                .text_search_with("Document", "body", query_text, limit, None)
                .value_map(Some(vec!["$id", "title", "$score"])),
        )
        .returning(["matches"])
}

let request = readable_document_matches(
    "alice".to_string(),
    "graph databases".to_string(),
    5,
)?;

import {
  SourcePredicate,
  defineParams,
  g,
  param,
  readBatch,
} from "@helix-db/helix-db";

const params = defineParams({
  username: param.string(),
  query_text: param.string(),
  limit: param.i64(),
});

const query = readBatch()
  .varAs(
    "matches",
    g()
      .nWithLabelWhere("User", SourcePredicate.eq("username", params.username))
      .out("CAN_READ")
      .textSearchWith("Document", "body", params.query_text, params.limit)
      .valueMap(["$id", "title", "$score"]),
  )
  .returning(["matches"]);

const request = query.toQueryRequest(
  params,
  { username: "alice", query_text: "graph databases", limit: 5n },
  { queryName: "readable_document_matches" },
);

q := helix.ReadQuery("readable_document_matches")
username := q.ParamString("username", "alice")
queryText := q.ParamString("query_text", "graph databases")
limit := q.ParamI64("limit", 5)

request := q.
	VarAs(
		"matches",
		helix.G().
			NWithLabelWhere("User", helix.SourceEq("username", username)).
			Out("CAN_READ").
			TextSearchNodesWithin("Document", "body", queryText, limit).
			ValueMap("$id", "title", "$score"),
	).
	Returning("matches")

from helixdb import SourcePredicate, define_params, g, param, read_batch

params = define_params({
    "username": param.string(),
    "query_text": param.string(),
    "limit": param.i64(),
})

query = (
    read_batch()
    .var_as(
        "matches",
        g()
        .n_with_label_where(
            "User", SourcePredicate.eq("username", params.username)
        )
        .out("CAN_READ")
        .text_search_with(
            "Document", "body", params.query_text, params.limit
        )
        .value_map(["$id", "title", "$score"]),
    )
    .returning(["matches"])
)

request = query.to_query_request(
    params,
    {
        "username": "alice",
        "query_text": "graph databases",
        "limit": 5,
    },
    query_name="readable_document_matches",
)

{
  "request_type": "read",
  "query_name": "readable_document_matches",
  "query": {
    "read": {
      "entries": [{
        "query": {
          "name": "matches",
          "root": {
            "value_map": {
              "input": {
                "text_search_nodes_within": {
                  "input": {
                    "out": {
                      "input": {
                        "nodes_where": {
                          "predicate": {
                            "and": {
                              "predicates": [
                                {
                                  "eq": {
                                    "left": { "property": "$label" },
                                    "right": { "constant": { "string": "User" } }
                                  }
                                },
                                {
                                  "eq": {
                                    "left": { "property": "username" },
                                    "right": { "param": "username" }
                                  }
                                }
                              ]
                            }
                          }
                        }
                      },
                      "label": "CAN_READ"
                    }
                  },
                  "label": "Document",
                  "property": "body",
                  "query_text": { "expr": { "param": "query_text" } },
                  "k": { "expr": { "param": "limit" } }
                }
              },
              "properties": ["$id", "title", "$score"]
            }
          }
        }
      }],
      "returns": ["matches"]
    }
  },
  "parameters": {
    "username": "alice",
    "query_text": "graph databases",
    "limit": 5
  },
  "parameter_types": {
    "username": "string",
    "query_text": "string",
    "limit": "i64"
  }
}

Use TextSearchEdgesWithin in Go after an edge traversal. Rust text_search_with, TypeScript textSearchWith, and Python text_search_with select the node or edge wire operation from the current stream. Their literal forms are text_search and textSearch.

Result contract

Output IDs are a deduplicated subset of the input IDs.
The result contains at most min(unique candidates, k) rows.
Rows are ordered by BM25 score descending, then entity ID ascending.
The selected input row keeps its bindings, path, and sack; $score is attached.
Empty input returns without opening the text index.
A wrong-kind input or more than 1,000,000 unique candidates is a query error.
A tenant-partitioned index requires the same tenant value used to build the candidate stream.

When to search without a prefilter

Use a source text search when the whole indexed label and optional tenant partition is the intended candidate set. Do not implement exact FTS filtering as source text search followed by .where(...): excluded high-scoring hits can consume the source top-k and leave fewer than k eligible results. Build the candidate stream first and use FTS prefiltering when membership is authoritative.

Next steps

Typed parameters

Move request-specific filter values out of the AST.

Indexes

Back equality and range predicates with an index.

Vector indexes

Create the dimensioned index used for ranking.

Text indexes

Create the BM25 index used for full-text ranking.

Project search results

Preserve ranked hit metadata before continuing a traversal.

Start Here

Core Concepts

Query Guides

Filtering

Common predicates

Filter a stream

Vector prefiltering

Rank a node stream

Requirements

When to search without a prefilter

Full Text Search prefiltering

Rank a node stream

Result contract

When to search without a prefilter

Next steps

Typed parameters

Indexes

Vector indexes

Text indexes

Project search results

​Common predicates

​Filter a stream

​Vector prefiltering

​Rank a node stream

​Requirements

​When to search without a prefilter

​Full Text Search prefiltering

​Rank a node stream

​Result contract

​When to search without a prefilter

​Next steps

Typed parameters

Indexes

Vector indexes

Text indexes

Project search results

Common predicates

Filter a stream

Vector prefiltering

Rank a node stream

Requirements

When to search without a prefilter

Full Text Search prefiltering

Rank a node stream

Result contract

When to search without a prefilter

Next steps