Create 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 create nodes in HelixDB?

Use AddN to create new nodes in your graph with optional properties.

AddN<Type>
AddN<Type>({properties})

⚠️ Warning

When using the SDKs or curling the endpoint, the query name must match what is defined in the queries.hx file exactly.

Example 1: Adding an empty user node

QUERY CreateUsers () =>
    empty_user <- AddN<User>
    RETURN empty_user

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

Here’s how to run the query using the SDKs or curl

from helix.client import Client
client = Client(local=True, port=6969)
print(client.query("CreateUsers"))

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 result: serde_json::Value = client.query("CreateUsers", &json!({})).await?;
    println!("Created empty user: {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
    err := client.Query("CreateUsers").Scan(&result)
    if err != nil {
        log.Fatalf("CreateUsers query failed: %s", err)
    }

    fmt.Printf("Created empty user: %#v\n", result)
}

import HelixDB from "helix-ts";

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

    const result = await client.query("CreateUsers", {});
    console.log("Created empty user:", result);
}

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

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

Example 2: Adding a user with parameters

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

Here’s how to run the query using the SDKs or curl

from helix.client import Client
client = Client(local=True, port=6969)

params = {
    "name": "Alice",
    "age": 25,
    "email": "alice@example.com",
}

print(client.query("CreateUser", params))

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 payload = json!({
        "name": "Alice",
        "age": 25,
        "email": "alice@example.com",
    });

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

    Ok(())
}

package main

import (
    "fmt"
    "log"

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

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

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

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

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

import HelixDB from "helix-ts";

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

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

    console.log("Created user:", result);
}

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

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

Example 3: Adding a user with predefined properties

QUERY CreateUser () =>
    predefined_user <- AddN<User>({
        name: "Alice Johnson",
        age: 30,
        email: "alice@example.com"
    })

    RETURN predefined_user

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

Here’s how to run the query using the SDKs or curl

from helix.client import Client
client = Client(local=True, port=6969)
print(client.query("CreateUser"))

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("CreateUser", &()).await?;
    println!("Created predefined user: {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
    err := client.Query("CreateUser").Scan(&result)
    if err != nil {
        log.Fatalf("CreateUser query failed: %s", err)
    }

    fmt.Printf("Created predefined user: %#v\n", result)
}

import HelixDB from "helix-ts";

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

    const result = await client.query("CreateUser", {});
    console.log("Created predefined user:", result);
}

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

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

Related operations

• Select nodes - Query existing nodes
• Create edges - Connect nodes with relationships
• Update nodes - Modify node properties
• Schema definitions - Define node types