Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Nodes

⚠️ Warning

HelixQL is deprecated in HelixDB v2. Queries are now written with the Rust DSL and dispatched as JSON — see the Querying guide. This section is kept as a reference for legacy HelixQL projects.

For the complete documentation index optimized for AI agents, see llms.txt.

How do I select nodes in HelixDB?

Use N to select nodes from your graph by ID, type, or property values to begin traversals.

#![allow(unused)]
fn main() {
N<Type>(node_id)
N<Type>({field: value})
}

Example 1: Selecting a user by ID

QUERY GetUser (user_id: ID) =>
    user <- N<User>(user_id)
    RETURN user

QUERY CreateUser (name: String, age: U8, email: String) =>
    user <- AddN<User>({
        name: name,
        age: age,
        email: email
    })
    RETURN user

N::User {
    name: String,
    age: U8,
    email: String,
}

from helix.client import Client

client = Client(local=True, port=6969)

user = client.query("CreateUser", {
    "name": "Alice",
    "age": 25,
    "email": "alice@example.com",
})
user_id = user[0]["user"]["id"]

result = client.query("GetUser", {"user_id": user_id})
print(result)

use helix_rs::{HelixDB, HelixDBClient};
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = HelixDB::new(Some("http://localhost"), Some(6969), None);

    let alice: serde_json::Value = client.query("CreateUser", &json!({
        "name": "Alice",
        "age": 25,
        "email": "alice@example.com",
    })).await?;
    let user_id = alice["user"]["id"].as_str().unwrap().to_string();

    let result: serde_json::Value = client.query("GetUser", &json!({
        "user_id": user_id,
    })).await?;

    println!("GetUser result: {result:#?}");

    Ok(())
}
package main

import (
    "fmt"
    "log"

    "github.com/HelixDB/helix-go"
)

func main() {
    client := helix.NewClient("http://localhost:6969")

    createPayload := map[string]any{
        "name":  "Alice",
        "age":   uint8(25),
        "email": "alice@example.com",
    }

    var created map[string]any
    if err := client.Query("CreateUser", helix.WithData(createPayload)).Scan(&created); err != nil {
        log.Fatalf("CreateUser failed: %s", err)
    }

    userID := created["user"].(map[string]any)["id"].(string)

    var result map[string]any
    if err := client.Query("GetUser", helix.WithData(map[string]any{"user_id": userID})).Scan(&result); err != nil {
        log.Fatalf("GetUser failed: %s", err)
    }

    fmt.Printf("GetUser result: %#v\n", result)
}

import HelixDB from "helix-ts";

async function main() {
    const client = new HelixDB("http://localhost:6969");

    const created = await client.query("CreateUser", {
        name: "Alice",
        age: 25,
        email: "alice@example.com",
    });
    const userId: string = created.user.id;

    const result = await client.query("GetUser", {
        user_id: userId,
    });

    console.log("GetUser result:", result);
}

main().catch((err) => {
    console.error("GetUser query failed:", err);
});

curl -X POST \
  http://localhost:6969/CreateUser \
  -H 'Content-Type: application/json' \
  -d '{"name":"Alice","age":25,"email":"alice@example.com"}'

curl -X POST \
  http://localhost:6969/GetUser \
  -H 'Content-Type: application/json' \
  -d '{"user_id":"<user_id>"}'

Example 2: Selecting all users

QUERY GetAllUsers () =>
    users <- N<User>
    RETURN users

N::User {
    name: String,
    age: U8,
    email: String,
}

from helix.client import Client

client = Client(local=True, port=6969)

result = client.query("GetAllUsers")
print(result)

use helix_rs::{HelixDB, HelixDBClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = HelixDB::new(Some("http://localhost"), Some(6969), None);

    let result: serde_json::Value = client.query("GetAllUsers", &()).await?;
    println!("GetAllUsers result: {result:#?}");

    Ok(())
}
package main

import (
    "fmt"
    "log"

    "github.com/HelixDB/helix-go"
)

func main() {
    client := helix.NewClient("http://localhost:6969")

    var result map[string]any
    if err := client.Query("GetAllUsers").Scan(&result); err != nil {
        log.Fatalf("GetAllUsers failed: %s", err)
    }

    fmt.Printf("GetAllUsers result: %#v\n", result)
}

import HelixDB from "helix-ts";

async function main() {
    const client = new HelixDB("http://localhost:6969");

    const result = await client.query("GetAllUsers", {});
    console.log("GetAllUsers result:", result);
}

main().catch((err) => {
    console.error("GetAllUsers query failed:", err);
});

curl -X POST \
  http://localhost:6969/GetAllUsers \
  -H 'Content-Type: application/json' \
  -d '{}'

Example 3: Selecting nodes by property value

Select nodes by matching INDEX field values instead of ID. This is useful when you need to find nodes with specific property values.

QUERY GetUserByEmail (email: String) =>
    user <- N<User>({email: email})
    RETURN user

N::User {
    INDEX email: String,
    name: String,
    age: U8,
}

ℹ️ Note

Property-based selection returns all nodes matching the specified INDEX field values. For more complex filtering conditions, use WHERE clauses.

ℹ️ Note

You can also do specific property-based filtering, e.g., returning only ID, see the Property Filtering. You can also do aggregation steps, e.g., returning the count of nodes, see the Aggregations.