Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.helix-db.com/llms.txt

Use this file to discover all available pages before exploring further.

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

​
Upsert Nodes using UpsertN  

Create new nodes or update existing ones with insert-or-update semantics. 
::UpsertN({properties})
UpsertN is a traversal step that operates on an existing traversal context. The type comes from the preceding traversal (N<Type>), not from the upsert call itself. If the traversal returns existing nodes, they are updated; if no nodes are found, a new node is created.
When using the SDKs or curling the endpoint, the query name must match what is defined in the queries.hx file exactly.

​
Example 1: Basic node upsert with properties

QUERY UpsertPerson(name: String, age: U32) =>
    existing <- N<Person>::WHERE(_::{name}::EQ(name))
    person <- existing::UpsertN({name: name, age: age})
    RETURN person
Here’s how to run the query using the SDKs or curl 
from helix.client import Client

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

# First call creates a new person
person = client.query("UpsertPerson", {
    "name": "Alice",
    "age": 25,
})

print("Created person:", person)

# Subsequent calls with same data update the existing person
updated = client.query("UpsertPerson", {
    "name": "Alice",
    "age": 26,
})

print("Updated person:", updated)

​
Example 2: Upsert from a pre-fetched node by ID

When you already have a node ID, you can fetch it directly and apply the upsert. 
QUERY UpsertPersonById(id: ID, new_age: U32) =>
    existing <- N<Person>(id)
    person <- existing::UpsertN({age: new_age})
    RETURN person
Here’s how to run the query using the SDKs or curl 
from helix.client import Client

client = Client(local=True, port=6969)
result = client.query("UpsertPersonById", {
    "id": "<person_id>",
    "new_age": 30,
})
print("Upserted person:", result)

​
Example 3: Upsert with WHERE filter

Find existing nodes with a WHERE clause and update or create if not found. 
QUERY UpdateOrCreatePerson(name: String, new_age: U32) =>
    existing <- N<Person>::WHERE(_::{name}::EQ(name))
    person <- existing::UpsertN({name: name, age: new_age})
    RETURN person
Here’s how to run the query using the SDKs or curl 
from helix.client import Client

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

# If "Alice" exists, updates her age; otherwise creates a new person
result = client.query("UpdateOrCreatePerson", {
    "name": "Alice",
    "new_age": 30,
})

print("Upserted person:", result)

​
How Upsert differs from Add and Update

OperationBehavior
AddNAlways creates a new node
UPDATEOnly modifies existing nodes (fails if node doesn’t exist)
UpsertNOperates on traversal context: updates if nodes found, creates if empty
When updating, UpsertN merges properties: it updates specified properties while preserving any existing properties that aren’t included in the upsert.