HelixDB Docs

Tutorial

Get Started runs one query that creates two users, connects them with a relationship, and reads that relationship back. This page takes the same query apart: what each operation contributes, what it becomes on the wire, and what the server sends back.

Every tab builds the same request. The JSON tab is the body sent to POST /v2/query, and the v3 SDKs are typed builders for exactly that body.

The whole query

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

#[query]
fn write_users() -> WriteBatch {
    write_batch()
        .var_as("alice", g().add_n("User", vec![("name", "Alice")]))
        .var_as("bob", g().add_n("User", vec![("name", "Bob")]))
        .var_as(
            "follow",
            g()
                .n(NodeRef::var("alice"))
                .add_e(
                    "FOLLOWS",
                    NodeRef::var("bob"),
                    vec![("since", "2026-07-24")],
                ),
        )
        .var_as(
            "friends",
            g()
                .n(NodeRef::var("alice"))
                .out(Some("FOLLOWS"))
                .value_map(Some(vec!["$id", "name"])),
        )
        .returning(["alice", "bob", "friends"])
}

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

const query = writeBatch()
  .varAs("alice", g().addN("User", { name: "Alice" }))
  .varAs("bob", g().addN("User", { name: "Bob" }))
  .varAs(
    "follow",
    g()
      .n(NodeRef.var("alice"))
      .addE("FOLLOWS", NodeRef.var("bob"), { since: "2026-07-24" }),
  )
  .varAs(
    "friends",
    g().n(NodeRef.var("alice")).out("FOLLOWS").valueMap(["$id", "name"]),
  )
  .returning(["alice", "bob", "friends"]);

import helix "github.com/helixdb/helix-db/sdks/go"

request := helix.WriteQuery("write_users").
	VarAs("alice", helix.G().AddN(
		"User",
		helix.Props{helix.Prop("name", "Alice")},
	)).
	VarAs("bob", helix.G().AddN(
		"User",
		helix.Props{helix.Prop("name", "Bob")},
	)).
	VarAs(
		"follow",
		helix.G().
			N(helix.NodeVar("alice")).
			AddE(
				"FOLLOWS",
				helix.NodeVar("bob"),
				helix.Props{helix.Prop("since", "2026-07-24")},
			),
	).
	VarAs(
		"friends",
		helix.G().
			N(helix.NodeVar("alice")).
			Out("FOLLOWS").
			ValueMap("$id", "name"),
	).
	Returning("alice", "bob", "friends")

from helixdb import NodeRef, g, write_batch

query = (
    write_batch()
    .var_as("alice", g().add_n("User", {"name": "Alice"}))
    .var_as("bob", g().add_n("User", {"name": "Bob"}))
    .var_as(
        "follow",
        g()
        .n(NodeRef.var("alice"))
        .add_e(
            "FOLLOWS",
            NodeRef.var("bob"),
            {"since": "2026-07-24"},
        ),
    )
    .var_as(
        "friends",
        g()
        .n(NodeRef.var("alice"))
        .out("FOLLOWS")
        .value_map(["$id", "name"]),
    )
    .returning(["alice", "bob", "friends"])
)

{
  "request_type": "write",
  "query_name": "write_users",
  "query": {
    "write": {
      "entries": [
        {
          "query": {
            "name": "alice",
            "root": {
              "add_n": {
                "label": "User",
                "properties": [
                  ["name", { "value": { "string": "Alice" } }]
                ]
              }
            }
          }
        },
        {
          "query": {
            "name": "bob",
            "root": {
              "add_n": {
                "label": "User",
                "properties": [
                  ["name", { "value": { "string": "Bob" } }]
                ]
              }
            }
          }
        },
        {
          "query": {
            "name": "follow",
            "root": {
              "add_e": {
                "input": {
                  "nodes": { "reference": { "var": "alice" } }
                },
                "label": "FOLLOWS",
                "to": { "var": "bob" },
                "properties": [
                  ["since", { "value": { "string": "2026-07-24" } }]
                ]
              }
            }
          }
        },
        {
          "query": {
            "name": "friends",
            "root": {
              "value_map": {
                "input": {
                  "out": {
                    "input": {
                      "nodes": { "reference": { "var": "alice" } }
                    },
                    "label": "FOLLOWS"
                  }
                },
                "properties": ["$id", "name"]
              }
            }
          }
        }
      ],
      "returns": ["alice", "bob", "friends"]
    }
  }
}

Four named entries run in order, and later entries reuse earlier results by name:

1. Pick the batch type

write_batch()

writeBatch();

helix.WriteQuery("write_users")

write_batch()

{ "write": { "entries": [], "returns": [] } }

A batch is a list of named entries plus the names to return. A write batch is the only batch that accepts a mutating traversal. Rust and TypeScript reject addN in a read batch at compile time, and Go and Python reject it while the request is being built, so a stray write in a read path never reaches the server. All entries in one batch commit or roll back together, which is what lets entry 4 read the edge that entry 3 has only just created.

2. Create the two nodes

.var_as("alice", g().add_n("User", vec![("name", "Alice")]))

.varAs("alice", g().addN("User", { name: "Alice" }))

VarAs("alice", helix.G().AddN("User", helix.Props{helix.Prop("name", "Alice")}))

.var_as("alice", g().add_n("User", {"name": "Alice"}))

{
  "query": {
    "name": "alice",
    "root": {
      "add_n": {
        "label": "User",
        "properties": [
          ["name", { "value": { "string": "Alice" } }]
        ]
      }
    }
  }
}

varAs adds one entry and gives it a name. g() starts an empty traversal, so addN here is a source operation with no input and creates exactly one node. Given an input stream instead, addN creates one node per incoming row. Properties travel as ordered [name, value] pairs, and each value carries its type tag (string, i64, f64, bool, date_time, bytes, and the array and object variants). The { "value": … } wrapper distinguishes a literal from an { "expr": … } reference such as a parameter. The name alice is local to this transaction. It is not a stored variable, a route, or a server-side binding, and it is gone once the response is sent.

3. Connect them with a directed edge

.var_as(
    "follow",
    g()
        .n(NodeRef::var("alice"))
        .add_e("FOLLOWS", NodeRef::var("bob"), vec![("since", "2026-07-24")]),
)

.varAs(
  "follow",
  g()
    .n(NodeRef.var("alice"))
    .addE("FOLLOWS", NodeRef.var("bob"), { since: "2026-07-24" }),
)

VarAs(
	"follow",
	helix.G().
		N(helix.NodeVar("alice")).
		AddE(
			"FOLLOWS",
			helix.NodeVar("bob"),
			helix.Props{helix.Prop("since", "2026-07-24")},
		),
)

.var_as(
    "follow",
    g()
    .n(NodeRef.var("alice"))
    .add_e("FOLLOWS", NodeRef.var("bob"), {"since": "2026-07-24"}),
)

{
  "query": {
    "name": "follow",
    "root": {
      "add_e": {
        "input": { "nodes": { "reference": { "var": "alice" } } },
        "label": "FOLLOWS",
        "to": { "var": "bob" },
        "properties": [
          ["since", { "value": { "string": "2026-07-24" } }]
        ]
      }
    }
  }
}

Unlike addN, addE needs an input stream: the nodes in that stream become the edge sources, and to is the target. n(NodeRef.var("alice")) turns entry 1’s result back into a stream, which is why add_e carries an input of { "nodes": { "reference": { "var": "alice" } } }. Direction comes from the operation, not the label: Alice is the source and Bob is the target, so traversing out from Alice reaches Bob. If the input stream held several nodes, addE would create one edge per source node. since is stored as a plain string here because the value is written as a string. Use a date-time property when you need range comparisons or ordering on it.

follow is not listed in returning, so it never appears in the response. The entry still runs. Leave write-only steps out of returning to keep the payload small.

4. Follow the new edge in the same transaction

.var_as(
    "friends",
    g()
        .n(NodeRef::var("alice"))
        .out(Some("FOLLOWS"))
        .value_map(Some(vec!["$id", "name"])),
)

.varAs(
  "friends",
  g().n(NodeRef.var("alice")).out("FOLLOWS").valueMap(["$id", "name"]),
)

VarAs(
	"friends",
	helix.G().N(helix.NodeVar("alice")).Out("FOLLOWS").ValueMap("$id", "name"),
)

.var_as(
    "friends",
    g().n(NodeRef.var("alice")).out("FOLLOWS").value_map(["$id", "name"]),
)

{
  "query": {
    "name": "friends",
    "root": {
      "value_map": {
        "input": {
          "out": {
            "input": { "nodes": { "reference": { "var": "alice" } } },
            "label": "FOLLOWS"
          }
        },
        "properties": ["$id", "name"]
      }
    }
  }
}

This entry is a read inside a write batch. It starts at Alice again, walks out along FOLLOWS, and projects two fields from whatever it lands on. The edge from entry 3 is uncommitted at this point but still visible, because the batch is one transaction. Each chained operation consumes the previous stream and wraps it as input, so the AST nests in the opposite order to the builder chain: the last operation you write is the outermost JSON object, and the source sits at the innermost position. out returns the destination nodes of outgoing edges. Passing a label does more than filter the results — it narrows which edges are read in the first place, so always pass one when the schema provides it.

Operation	Result
`out(label)`	Destination nodes of outgoing edges
`in(label)`	Source nodes of incoming edges
`both(label)`	Adjacent nodes in either direction
`outE(label)` / `inE(label)`	The edges themselves

valueMap is a terminal operation: it selects properties by name and ends the traversal, so nothing can be chained after it. $id and $label expose identity and label alongside ordinary properties, and omitting the property list returns every property.

5. Choose what comes back

.returning(["alice", "bob", "friends"])

.returning(["alice", "bob", "friends"]);

Returning("alice", "bob", "friends")

.returning(["alice", "bob", "friends"])

{ "returns": ["alice", "bob", "friends"] }

returning picks which named entries appear in the response body. Names it omits still execute; they are simply not serialized back to the client.

6. Name the request

let request = write_users();

const request = query.toQueryRequest({ queryName: "write_users" });

request := helix.WriteQuery("write_users") // named before the entries are added

request = query.to_query_request(query_name="write_users")

{
  "query_name": "write_users"
}

Rust’s #[query] macro rewrites the function to return a request and sets query_name from the function name. TypeScript and Python convert a batch with toQueryRequest / to_query_request, and Go’s WriteQuery(name) took the name up front. query_name is optional diagnostic metadata for gateway logs and query diagnostics. It does not create a stored endpoint or deploy anything; a missing or null name is reported as __dynamic__.

7. Run it

let client = helix_db::Client::new(None)?;
let response: serde_json::Value = client.query(request).send().await?;

import { Client } from "@helix-db/helix-db";

const response = await Client.server("http://localhost:6969")
  .query(request)
  .send();

client, err := helix.NewClient("http://localhost:6969")
if err != nil {
	return err
}
var response map[string]any
err = client.Exec(ctx, request, &response)

from helixdb import Client

response = Client("http://localhost:6969").query(request)

helix query dev --file write_users.json

8. Read the response

The response is a flat object keyed by the names in returning:

{
  "alice": [{ "$id": 0 }],
  "bob": [{ "$id": 1 }],
  "friends": [{ "$id": 1, "name": "Bob" }]
}

The shape of each value depends on how its entry ended:

Key	Entry ended with	Shape
`alice`, `bob`	`add_n`, a node stream	One object per node containing its `$id`
`friends`	`value_map`, a terminal projection	One object per row containing the selected properties

Node and edge IDs are unsigned 64-bit integers, and projected properties come back as plain JSON values rather than the tagged form used in the request. Returning a raw stream is rarely what a caller wants. End an entry with the terminal that produces the shape you need — each of these replaces valueMap on the friends entry:

Terminal	Response
`valueMap(["$id", "name"])`	`[{ "$id": 1, "name": "Bob" }]`
`id()`	`[1]`
`count()`	`1`
`exists()`	`true`
`project(…)`	One object per row with named fields

9. Read it back in a later request

Once the write has committed, the same traversal works from a read batch — Alice is now found by property instead of by a name from an earlier entry:

read_batch()
    .var_as(
        "alice",
        g()
            .n_with_label("User")
            .where_(Predicate::eq("name", "Alice"))
            .limit(1),
    )
    .var_as(
        "friends",
        g()
            .n(NodeRef::var("alice"))
            .out(Some("FOLLOWS"))
            .dedup()
            .value_map(Some(vec!["$id", "name"])),
    )
    .returning(["friends"]);

readBatch()
  .varAs(
    "alice",
    g().nWithLabel("User").where(Predicate.eq("name", "Alice")).limit(1),
  )
  .varAs(
    "friends",
    g()
      .n(NodeRef.var("alice"))
      .out("FOLLOWS")
      .dedup()
      .valueMap(["$id", "name"]),
  )
  .returning(["friends"]);

helix.ReadQuery("alice_friends").
	VarAs(
		"alice",
		helix.G().
			NWithLabel("User").
			Where(helix.PredEq("name", "Alice")).
			Limit(1),
	).
	VarAs(
		"friends",
		helix.G().
			N(helix.NodeVar("alice")).
			Out("FOLLOWS").
			Dedup().
			ValueMap("$id", "name"),
	).
	Returning("friends")

(
    read_batch()
    .var_as(
        "alice",
        g().n_with_label("User").where(Predicate.eq("name", "Alice")).limit(1),
    )
    .var_as(
        "friends",
        g()
        .n(NodeRef.var("alice"))
        .out("FOLLOWS")
        .dedup()
        .value_map(["$id", "name"]),
    )
    .returning(["friends"])
)

{
  "request_type": "read",
  "query_name": "alice_friends",
  "query": {
    "read": {
      "entries": [
        {
          "query": {
            "name": "alice",
            "root": {
              "limit": {
                "input": {
                  "where": {
                    "input": {
                      "nodes_where": {
                        "predicate": {
                          "eq": {
                            "left": { "property": "$label" },
                            "right": { "constant": { "string": "User" } }
                          }
                        }
                      }
                    },
                    "predicate": {
                      "eq": {
                        "left": { "property": "name" },
                        "right": { "constant": { "string": "Alice" } }
                      }
                    }
                  }
                },
                "count": { "literal": 1 }
              }
            }
          }
        },
        {
          "query": {
            "name": "friends",
            "root": {
              "value_map": {
                "input": {
                  "dedup": {
                    "input": {
                      "out": {
                        "input": {
                          "nodes": { "reference": { "var": "alice" } }
                        },
                        "label": "FOLLOWS"
                      }
                    }
                  }
                },
                "properties": ["$id", "name"]
              }
            }
          }
        }
      ],
      "returns": ["friends"]
    }
  }
}

It returns the same rows the write batch already reported:

{ "friends": [{ "$id": 1, "name": "Bob" }] }

Two details are worth noting. nWithLabel becomes a nodes_where source predicate on $label, and the general .where(…) filter wraps it — the label chooses what is scanned, the filter narrows the rows that come out of it. And dedup() guards against the multigraph case, where several FOLLOWS edges between the same pair would otherwise yield the same node more than once. A label scan reads every User. Add a secondary index on name and use nWhere instead, so the lookup is pushed down to the index.

Next steps

Writing data

Use a write batch for graph mutations.

Reading data

Choose an efficient source for a traversal.

Traversals

Follow relationships and keep correlated values.

Add parameters

Separate runtime values from the stable AST.

Start Here

Core Concepts

Query Guides

Build and run a query

The whole query

1. Pick the batch type

2. Create the two nodes

3. Connect them with a directed edge

4. Follow the new edge in the same transaction

5. Choose what comes back

6. Name the request

7. Run it

8. Read the response

9. Read it back in a later request

Next steps

Writing data

Reading data

Traversals

Add parameters

​The whole query

​1. Pick the batch type

​2. Create the two nodes

​3. Connect them with a directed edge

​4. Follow the new edge in the same transaction

​5. Choose what comes back

​6. Name the request

​7. Run it

​8. Read the response

​9. Read it back in a later request

​Next steps

Writing data

Reading data

Traversals

Add parameters

The whole query

1. Pick the batch type

2. Create the two nodes

3. Connect them with a directed edge

4. Follow the new edge in the same transaction

5. Choose what comes back

6. Name the request

7. Run it

8. Read the response

9. Read it back in a later request

Next steps