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.

​
Use nested FOR loops for multi-level iteration

Nest FOR loops to perform operations across multiple collections simultaneously. This is particularly useful for creating relationships between all pairs of elements or processing hierarchical data structures. 
FOR outer_var IN outer_collection {
    FOR inner_var IN inner_collection {
        // Operations using both outer_var and inner_var
    }
}
Nested loops are executed for every combination of elements from the outer and inner collections, resulting in a cartesian product of operations.
Be mindful of performance when using nested loops with large collections. The number of operations grows multiplicatively with collection sizes (N × M operations for two collections).
When using the SDKs or curling the endpoint, the query name must match what is defined in the queries.hx file exactly.

​
Example 1: Creating connections between all user pairs

QUERY CreateUserNetwork (user_data: [{name: String, age: U8, interests: String}]) =>
    // First, create all users
    FOR {name, age, interests} IN user_data {
        user <- AddN<User>({
            name: name,
            age: age,
            interests: interests
        })
    }

    // Then create connections between all users
    all_users <- N<User>
    FOR user1 IN all_users {
        FOR user2 IN all_users {
            // Don't create self-connections
            IF user1::ID != user2::ID THEN {
                AddE<Knows>::From(user1)::To(user2)
            }
        }
    }
    RETURN "User network created"
Here’s how to run the query using the SDKs or curl 
from helix.client import Client

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

# Create a fully connected user network
user_data = [
    {"name": "Alice", "age": 25, "interests": "Technology, Reading"},
    {"name": "Bob", "age": 30, "interests": "Sports, Music"},
    {"name": "Charlie", "age": 28, "interests": "Art, Photography"},
    {"name": "Diana", "age": 22, "interests": "Travel, Cooking"},
]

result = client.query("CreateUserNetwork", {"user_data": user_data})
print("Network creation result:", result)

​
Example 2: Cross-product operations with hierarchical data

QUERY LoadDocumentStructure (
    chapters: [{
        id: I64,
        title: String,
        subchapters: [{
            title: String,
            content: String,
            chunks: [{chunk: String, vector: [F64]}]
        }]
    }]
) =>
    FOR {id, title, subchapters} IN chapters {
        chapter_node <- AddN<Chapter>({
            chapter_index: id,
            title: title
        })

        FOR {title, content, chunks} IN subchapters {
            subchapter_node <- AddN<SubChapter>({
                title: title,
                content: content
            })
            AddE<Contains>::From(chapter_node)::To(subchapter_node)

            FOR {chunk, vector} IN chunks {
                vec <- AddV<Embedding>(vector)
                AddE<EmbeddingOf>({chunk: chunk})::From(subchapter_node)::To(vec)
            }
        }
    }
    RETURN "Document structure loaded"
Here’s how to run the query using the SDKs or curl 
from helix.client import Client
import random

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

# Helper to generate sample embeddings
def generate_embedding(dim=384):
    return [random.random() for _ in range(dim)]

# Load hierarchical document structure
chapters = [
    {
        "id": 1,
        "title": "Introduction",
        "subchapters": [
            {
                "title": "Overview",
                "content": "This chapter provides an overview of the topic.",
                "chunks": [
                    {"chunk": "First chunk of text", "vector": generate_embedding()},
                    {"chunk": "Second chunk of text", "vector": generate_embedding()},
                ]
            },
            {
                "title": "Background",
                "content": "Historical context and background information.",
                "chunks": [
                    {"chunk": "Background chunk 1", "vector": generate_embedding()},
                    {"chunk": "Background chunk 2", "vector": generate_embedding()},
                ]
            }
        ]
    },
    {
        "id": 2,
        "title": "Main Content",
        "subchapters": [
            {
                "title": "Key Concepts",
                "content": "Detailed explanation of key concepts.",
                "chunks": [
                    {"chunk": "Concept explanation 1", "vector": generate_embedding()},
                    {"chunk": "Concept explanation 2", "vector": generate_embedding()},
                ]
            }
        ]
    }
]

result = client.query("LoadDocumentStructure", {"chapters": chapters})
print("Document structure result:", result)

​
Performance considerations

Nested loops can significantly impact performance:
  • Two loops over collections of size N and M result in N × M operations
  • Three nested loops result in N × M × P operations
  • Consider using WHERE clauses to filter collections before looping
  • For large datasets, evaluate whether nested loops are the most efficient approach

​
Tips for optimizing nested loops:

  1. Filter early: Apply WHERE clauses before entering loops to reduce iteration count
  2. Consider alternatives: Sometimes traversals or joins can be more efficient than nested loops
  3. Batch operations: Group related operations to minimize database calls
  4. Monitor performance: Test with realistic data volumes to identify bottlenecks

Basic FOR Loops

Iterate over collections with simple variable binding

FOR Loop Destructuring

Extract multiple properties directly in loop variable binding