HelixDB Docs

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"

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

E::Knows {
}

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)

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);

    // Create a fully connected user network
    let user_data = vec![
        json!({"name": "Alice", "age": 25, "interests": "Technology, Reading"}),
        json!({"name": "Bob", "age": 30, "interests": "Sports, Music"}),
        json!({"name": "Charlie", "age": 28, "interests": "Art, Photography"}),
        json!({"name": "Diana", "age": 22, "interests": "Travel, Cooking"}),
    ];

    let result: serde_json::Value = client.query("CreateUserNetwork", &json!({
        "user_data": user_data
    })).await?;
    println!("Network creation result: {result:#?}");

    Ok(())
}

package main

import (
    "fmt"
    "log"

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

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

    // Create a fully connected user network
    userData := []map[string]any{
        {"name": "Alice", "age": uint8(25), "interests": "Technology, Reading"},
        {"name": "Bob", "age": uint8(30), "interests": "Sports, Music"},
        {"name": "Charlie", "age": uint8(28), "interests": "Art, Photography"},
        {"name": "Diana", "age": uint8(22), "interests": "Travel, Cooking"},
    }

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

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

import HelixDB from "helix-ts";

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

    // Create a fully connected user network
    const userData = [
        { 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" },
    ];

    const result = await client.query("CreateUserNetwork", { user_data: userData });
    console.log("Network creation result:", result);
}

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

curl -X POST \
  http://localhost:6969/CreateUserNetwork \
  -H 'Content-Type: application/json' \
  -d '{
    "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"}
    ]
  }'

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"

N::Chapter {
    chapter_index: I64,
    title: String
}

N::SubChapter {
    title: String,
    content: String
}

V::Embedding {
    dimension: 384
}

E::Contains {
}

E::EmbeddingOf {
    chunk: String
}

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)

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

fn generate_embedding(dim: usize) -> Vec<f64> {
    let mut rng = rand::thread_rng();
    (0..dim).map(|_| rng.gen::<f64>()).collect()
}

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

    // Load hierarchical document structure
    let chapters = vec![
        json!({
            "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(384)},
                        {"chunk": "Second chunk of text", "vector": generate_embedding(384)},
                    ]
                },
                {
                    "title": "Background",
                    "content": "Historical context and background information.",
                    "chunks": [
                        {"chunk": "Background chunk 1", "vector": generate_embedding(384)},
                        {"chunk": "Background chunk 2", "vector": generate_embedding(384)},
                    ]
                }
            ]
        }),
        json!({
            "id": 2,
            "title": "Main Content",
            "subchapters": [
                {
                    "title": "Key Concepts",
                    "content": "Detailed explanation of key concepts.",
                    "chunks": [
                        {"chunk": "Concept explanation 1", "vector": generate_embedding(384)},
                        {"chunk": "Concept explanation 2", "vector": generate_embedding(384)},
                    ]
                }
            ]
        })
    ];

    let result: serde_json::Value = client.query("LoadDocumentStructure", &json!({
        "chapters": chapters
    })).await?;
    println!("Document structure result: {result:#?}");

    Ok(())
}

package main

import (
    "fmt"
    "log"
    "math/rand"

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

func generateEmbedding(dim int) []float64 {
    embedding := make([]float64, dim)
    for i := range embedding {
        embedding[i] = rand.Float64()
    }
    return embedding
}

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

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

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

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

import HelixDB from "helix-ts";

function generateEmbedding(dim: number = 384): number[] {
    return Array.from({ length: dim }, () => Math.random());
}

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

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

    const result = await client.query("LoadDocumentStructure", { chapters });
    console.log("Document structure result:", result);
}

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

# Note: This example shows the structure. In practice, you'd generate actual embedding vectors.
curl -X POST \
  http://localhost:6969/LoadDocumentStructure \
  -H 'Content-Type: application/json' \
  -d '{
    "chapters": [
      {
        "id": 1,
        "title": "Introduction",
        "subchapters": [
          {
            "title": "Overview",
            "content": "This chapter provides an overview of the topic.",
            "chunks": [
              {"chunk": "First chunk of text", "vector": [0.1, 0.2, 0.3]},
              {"chunk": "Second chunk of text", "vector": [0.4, 0.5, 0.6]}
            ]
          }
        ]
      }
    ]
  }'

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:

Filter early: Apply WHERE clauses before entering loops to reduce iteration count
Consider alternatives: Sometimes traversals or joins can be more efficient than nested loops
Batch operations: Group related operations to minimize database calls
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

Getting Started

Schema

Writing Data

Reading Data

Search

Graph Traversals

Aggregation

Advanced Queries

Reference

Nested FOR Loops

Use nested FOR loops for multi-level iteration

Example 1: Creating connections between all user pairs

Example 2: Cross-product operations with hierarchical data

Performance considerations

Tips for optimizing nested loops:

Basic FOR Loops

FOR Loop Destructuring

​Use nested FOR loops for multi-level iteration

​Example 1: Creating connections between all user pairs

​Example 2: Cross-product operations with hierarchical data

​Performance considerations

​Tips for optimizing nested loops:

​Related topics

Basic FOR Loops

FOR Loop Destructuring

Use nested FOR loops for multi-level iteration

Example 1: Creating connections between all user pairs

Example 2: Cross-product operations with hierarchical data

Performance considerations

Tips for optimizing nested loops:

Related topics