HelixDB Docs

Guide

Prefiltering ranks only the nodes or edges that a traversal reaches, instead of a whole index. Use it when graph membership is a correctness boundary, such as “documents this user may access” or “products reachable from this category.” It works the same way for vector and full-text search. For why filtering before ranking matters, see Filtered vector search.

How it works

Every prefiltered search runs in the same order: graph traversal → exact candidate membership → ranking → top k.

The traversal is authoritative. A result outside the candidate set is never returned, even when approximate index structures accelerate ranking.
Output IDs are a deduplicated subset of the input IDs.
Each selected row keeps its bindings, path, and sack, with $distance (vector) or $score (text) attached.
Empty input returns without opening the index.
A tenant-partitioned index requires the same tenant value used to build the candidate stream.

Do not emulate prefiltering by searching the whole index and filtering afterward with .where(...). Excluded high-ranking hits still consume the top k, so the response can hold fewer than k eligible results. Build the candidate traversal first when membership matters.

Vector prefiltering

This request finds the projects a user owns, ranks that exact set by embedding distance, and returns the top five. It requires an active three-dimensional cosine vector index on Project.embedding.

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"
  }
}

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

Full-text search prefiltering

This request finds the documents a user can read, ranks that exact set for "graph databases", and returns the top five. It requires an active text index on Document.body.

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"
  }
}

Results are identical to an exhaustive BM25 search of the tenant partition, intersected with the candidate IDs, followed by deterministic top-k selection: BM25 score descending, then entity ID ascending. BM25 statistics still come from the full tenant partition, not only the candidates.

SDK methods

Rust, TypeScript, and Python pick the node or edge wire operation from the current stream. Go has separate node and edge methods.

Search	Rust and Python	TypeScript	Go
Vector	`vector_search_with`, or `vector_search` for literal inputs	`vectorSearchWith`, or `vectorSearch`	`VectorSearchNodesWithin`, `VectorSearchEdgesWithin`
Text	`text_search_with`, or `text_search` for literal inputs	`textSearchWith`, or `textSearch`	`TextSearchNodesWithin`, `TextSearchEdgesWithin`

Result limits

Search	Limit
Vector	The request fails when `min(k, unique candidates)` exceeds 800. `k` is never reduced silently, so a larger `k` succeeds when 800 or fewer unique candidates exist.
Text	At most `min(unique candidates, k, 800)` rows.
Both	More than 1,000,000 unique candidates is a query error.

Unpublished changes

Prefiltered searches follow the request’s search consistency. A candidate whose indexed vector or text changed in a committed write that the index worker has not published yet is superseded: the search drops that candidate’s published index rows up front and ranks its newest committed value instead, or leaves it out when that write removed the value.

strong (the default) treats every superseded candidate this way. Unlike a whole-index search, a prefiltered search never fails with index_backpressure because of superseded results; only the limits above apply. A prefiltered text search still fails with index_backpressure when its partition holds more unpublished text than a strong text search may analyze, since its BM25 statistics cover every unpublished document, and a prefiltered vector search fails the same way when its index holds more unpublished vector work than a strong search may score. That work counts every tenant partition of the index, so with a lowered bound another tenant’s backlog can fail the search even when its own candidates have nothing unpublished.
eventual does this for the oldest unpublished work within its per-search budget and ranks the remaining candidates by their last published values until publication.

Checklist

Create a compatible index for the candidate label and property. Vector queries must match the index dimension exactly.
Pass the same tenant value as the index when it is tenant-partitioned.
Project $distance or $score before traversing away from a ranked hit.
Bound the candidate traversal when its size can grow without application limits.

Next steps

Vector indexes

Create the dimensioned index used for ranking.

Text indexes

Create the BM25 index used for full-text ranking.

Traversals

Build the candidate set by following relationships.

Project search results

Preserve ranked hit metadata before continuing a traversal.

Start Here

Core Concepts

Query Guides

Prefiltered search

How it works

Vector prefiltering

Full-text search prefiltering

SDK methods

Result limits

Unpublished changes

Checklist

Next steps

Vector indexes

Text indexes

Traversals

Project search results

​How it works

​Vector prefiltering

​Full-text search prefiltering

​SDK methods

​Result limits

​Unpublished changes

​Checklist

​Next steps

Vector indexes

Text indexes

Traversals

Project search results

How it works

Vector prefiltering

Full-text search prefiltering

SDK methods

Result limits

Unpublished changes

Checklist

Next steps