HelixDB Docs

Guide

Every traversal starts from a source. Choose the narrowest source that matches the data you already know.

Source choices

Intent	Builder
One or more node IDs	`n(NodeRef…)`
Nodes with a label	`nWithLabel` / `n_with_label`
Nodes matching a source predicate	`nWhere` / `n_where`
One or more edge IDs	`e(EdgeRef…)`
Edges with a label	`eWithLabel` / `e_with_label`
Earlier named entry	`NodeRef.var(...)` / `NodeVar(...)`

Source predicates are eligible for index push-down. Secondary indexes are defined per label, so a source must be scoped to a label to read one: nWithLabelWhere / n_with_label_where, or a .where(...) directly after nWithLabel. A source predicate without a label scans every node. A .where(...) later in a traversal filters the current stream.

Read active users

read_batch()
    .var_as(
        "users",
        g()
            .n_with_label("User")
            .where_(Predicate::eq("status", "active"))
            .limit(25)
            .value_map(Some(vec!["$id", "name"])),
    )
    .returning(["users"]);

readBatch()
  .varAs(
    "users",
    g()
      .nWithLabel("User")
      .where(Predicate.eq("status", "active"))
      .limit(25)
      .valueMap(["$id", "name"]),
  )
  .returning(["users"]);

helix.ReadQuery("active_users").
	VarAs(
		"users",
		helix.G().
			NWithLabel("User").
			Where(helix.PredEq("status", "active")).
			Limit(25).
			ValueMap("$id", "name"),
	).
	Returning("users")

(
    read_batch()
    .var_as(
        "users",
        g()
        .n_with_label("User")
        .where(Predicate.eq("status", "active"))
        .limit(25)
        .value_map(["$id", "name"]),
    )
    .returning(["users"])
)

{
  "request_type": "read",
  "query_name": "active_users",
  "query": {
    "read": {
      "entries": [{
        "query": {
          "name": "users",
          "root": {
            "value_map": {
              "input": {
                "limit": {
                  "input": {
                    "where": {
                      "input": {
                        "nodes_where": {
                          "predicate": {
                            "eq": {
                              "left": { "property": "$label" },
                              "right": { "constant": { "string": "User" } }
                            }
                          }
                        }
                      },
                      "predicate": {
                        "eq": {
                          "left": { "property": "status" },
                          "right": { "constant": { "string": "active" } }
                        }
                      }
                    }
                  },
                  "count": { "literal": 25 }
                }
              },
              "properties": ["$id", "name"]
            }
          }
        }
      }],
      "returns": ["users"]
    }
  }
}

MATCH (u:User)
WHERE u.status = 'active'
WITH u LIMIT 25
RETURN id(u) AS id, u.name AS name

Read by indexed property

Scope the source predicate to the indexed label, so the property read uses its index:

g().n_with_label_where("User", SourcePredicate::eq("email", "alice@example.com"))

g().nWithLabelWhere("User", SourcePredicate.eq("email", "alice@example.com"))

helix.G().NWithLabelWhere("User", helix.SourceEq("email", "alice@example.com"))

g().n_with_label_where("User", SourcePredicate.eq("email", "alice@example.com"))

{
  "request_type": "read",
  "query_name": "user_by_email",
  "query": {
    "read": {
      "entries": [{
        "query": {
          "name": "user",
          "root": {
            "nodes_where": {
              "predicate": {
                "and": {
                  "predicates": [
                    {
                      "eq": {
                        "left": { "property": "$label" },
                        "right": { "constant": { "string": "User" } }
                      }
                    },
                    {
                      "eq": {
                        "left": { "property": "email" },
                        "right": {
                          "constant": { "string": "alice@example.com" }
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }],
      "returns": ["user"]
    }
  }
}

MATCH (user:User {email: 'alice@example.com'})
RETURN id(user) AS user

Read an earlier result

Use NodeRef.var("user") (or the equivalent SDK reference) as the source of a later entry. Named references are transaction-local; they do not create stored variables or routes.

Start Here

Core Concepts

Query Guides

Reading data

Source choices

Read active users

Read by indexed property

Read an earlier result

Next steps

Traverse relationships

Filter and order

​Source choices

​Read active users

​Read by indexed property

​Read an earlier result

​Next steps

Traverse relationships

Filter and order

Source choices

Read active users

Read by indexed property

Read an earlier result

Next steps