Skip to main content
For the complete documentation index optimized for AI agents, see llms.txt.
This page covers the steps that narrow a stream rather than walking the graph: property and label filters, the full Predicate catalog, ordering, and slicing the result with limit / skip / range.

​
.has, .hasLabel, .hasKey

The simplest filters are equality checks on a single property. They work on both node and edge streams. 
import { g, readBatch } from "@helix-db/helix-db";

const proUsers = readBatch()
  .varAs(
    "users",
    g().nWithLabel("User").has("tier", "pro").valueMap(["$id", "username"]),
  )
  .returning(["users"]);
  • .has(property, value) — property equals the given value.
  • .hasLabel(label) — node/edge label equals.
  • .hasKey(property) — property exists (any non-null value).
These are convenience wrappers; under the hood they could all be expressed via .where(...).

​
.where(Predicate.*)

For anything richer than equality, use .where(Predicate.*). Predicate exposes the full set:
GroupBuilders
Comparisoneq, neq, gt, gte, lt, lte, between
StringstartsWith, endsWith, contains
CollectionisIn, isInExpr
Property presencehasKey, isNull, isNotNull
Logicaland([...]), or([...]), not(p)
Parameter-boundeqParam, neqParam, gtParam, gteParam, ltParam, lteParam, isInParam, containsParam
Expressioncompare(left, op, right) — for arithmetic on either side
A typical multi-predicate filter: 
import { g, Predicate, readBatch } from "@helix-db/helix-db";

const recentProPosts = readBatch()
  .varAs(
    "posts",
    g()
      .nWithLabel("Post")
      .where(
        Predicate.and([
          Predicate.gte("createdAt", "2026-01-01"),
          Predicate.or([
            Predicate.contains("title", "graph"),
            Predicate.contains("title", "database"),
          ]),
          Predicate.isNotNull("body"),
        ]),
      )
      .valueMap(["$id", "title", "createdAt"]),
  )
  .returning(["posts"]);

​
SourcePredicate vs Predicate

Use a SourcePredicate at source steps when the filter should participate in index selection; use .where(Predicate.*) for anything outside that set or to filter after a traversal step. See SourcePredicate vs Predicate for the full breakdown.

​
Nested property paths

Object properties can be filtered with dotted paths. The runtime first checks for an exact top-level property name, then walks nested object fields when the name contains .. 
import { g, Predicate, readBatch } from "@helix-db/helix-db";

const usersByExternalId = readBatch()
  .varAs(
    "users",
    g()
      .nWithLabel("User")
      .where(Predicate.eq("metadata.externalID", "crm-42"))
      .valueMap(["$id", "username", "metadata.externalID"]),
  )
  .returning(["users"]);
Dotted paths are scan-only in V1. Pair them with an indexed top-level anchor such as label, tenant, or status when the label is large; the indexed predicate narrows candidate rows and the dotted predicate runs as a residual filter. Arrays are opaque, so metadata.tags.0 is not supported.

​
Parameter-bound predicates

To filter by a value the caller supplies at request time, use the *Param family. Pass the parameter name as a string; the runtime substitutes the value at execution. Full parameter declaration via defineParams is covered on Parameters & bundles; this page focuses on the predicate shape. 
import {
  g,
  Predicate,
  defineParams,
  param,
  readBatch,
} from "@helix-db/helix-db";

const params = defineParams({ username: param.string() });

function userByUsername(p = params) {
  return readBatch()
    .varAs(
      "user",
      g()
        .nWithLabel("User")
        .where(Predicate.eqParam("username", "username"))
        .valueMap(["$id", "username", "tier"]),
    )
    .returning(["user"]);
}

const body = userByUsername().toDynamicJson(params, { username: "alice" });
A few wire-format details worth noting:
  • Predicate.eqParam(prop, name) desugars to a generic Compare predicate with a Property on the left and a Param on the right. The same shape applies to neqParam, gtParam, gteParam, ltParam, lteParam (the op field varies).
  • Predicate.isInParam("status", "statuses") becomes {"IsInExpr": ["status", {"Param": "statuses"}]} — a Param-valued expression, not a Compare.
  • Predicate.containsParam("body", "needle") becomes {"ContainsExpr": ["body", {"Param": "needle"}]}.

​
Filtering edges in the middle of a traversal

When you’re walking through an edge stream and want to filter on edge properties without leaving the stream, use the same generic filters as node streams: .has(prop, value), .hasLabel(label), .hasKey(prop), and .where(Predicate.*). Edge predicates can read stored edge properties plus the virtual edge fields $id, $label, $from, $to, $distance, and $score. Use .edgeHas(prop, value) when the right-hand side must be a PropertyInput expression or runtime parameter. 
import { g, NodeRef, Predicate, readBatch, SourcePredicate } from "@helix-db/helix-db";

const aliceStrongFollows = readBatch()
  .varAs("user", g().nWhere(SourcePredicate.eq("username", "alice")))
  .varAs(
    "strong_following",
    g()
      .n(NodeRef.var("user"))
      .outE("FOLLOWS")
      .where(Predicate.gte("weight", 0.8))
      .inN()
      .valueMap(["$id", "username"]),
  )
  .returning(["strong_following"]);

​
Ordering

.orderBy(property, Order.Asc | Order.Desc) sorts by a single property. .orderByMultiple([[prop, order], ...]) sorts by several at once with explicit direction per key. 
import { g, Order, readBatch } from "@helix-db/helix-db";

const recentPosts = readBatch()
  .varAs(
    "posts",
    g()
      .nWithLabel("Post")
      .orderBy("createdAt", Order.Desc)
      .limit(20)
      .valueMap(["$id", "title", "createdAt"]),
  )
  .returning(["posts"]);
For multi-key ordering: 
g()
  .nWithLabel("Post")
  .orderByMultiple([
    ["createdAt", Order.Desc],
    ["title", Order.Asc],
  ]);

helix.G().NWithLabel("Post").OrderByMultiple(
	helix.Ordering{Property: "createdAt", Order: helix.OrderDesc},
	helix.Ordering{Property: "title", Order: helix.OrderAsc},
)
which serializes as: 
{ "OrderByMultiple": [["createdAt", "Desc"], ["title", "Asc"]] }

​
Paging: .limit, .skip, .range

The three slicing steps all accept either a literal number / bigint or a StreamBound for parameter-bound bounds.
  • .limit(n) — keep the first n.
  • .skip(n) — drop the first n.
  • .range(start, end) — keep the half-open [start, end) slice.

​
Literal bounds

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

const secondPage = readBatch()
  .varAs(
    "posts",
    g()
      .nWithLabel("Post")
      .orderBy("createdAt", Order.Desc)
      .range(20, 40)
      .valueMap(["$id", "title"]),
  )
  .returning(["posts"]);

​
Parameter-bound limits

For request-time pagination, wrap the bound in StreamBound.expr(Expr.param("...")). The JSON variant changes too: Limit becomes LimitBy, Skip becomes SkipBy, Range becomes RangeBy. 
import {
  defineParams,
  Expr,
  g,
  Order,
  param,
  readBatch,
  StreamBound,
} from "@helix-db/helix-db";

const params = defineParams({ page_size: param.i64() });

function recentPostsPaged(p = params) {
  return readBatch()
    .varAs(
      "posts",
      g()
        .nWithLabel("Post")
        .orderBy("createdAt", Order.Desc)
        .limit(StreamBound.expr(Expr.param("page_size")))
        .valueMap(["$id", "title"]),
    )
    .returning(["posts"]);
}

const body = recentPostsPaged().toDynamicJson(params, { page_size: 25n });
The Range parameter-bound variant looks like: 
{ "RangeBy": [{ "Literal": 0 }, { "Expr": { "Param": "end" } }] }
— each bound is independently a Literal or an Expr, so you can mix-and-match a constant start with a parameterized end.

​
Next Steps

Projections

Choose what the caller sees: values, valueMap, project, terminal aggregations.

Mutations

addN, addE, setProperty, drop — write batches end-to-end.