> ## Documentation Index
> Fetch the complete documentation index at: https://helix-claude-document-return-objects-rxi6v.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Nested FOR Loops

> Use multiple levels of iteration for complex operations.

## 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.

```helixql theme={null}
FOR outer_var IN outer_collection {
    FOR inner_var IN inner_collection {
        // Operations using both outer_var and inner_var
    }
}
```

<Note>
  Nested loops are executed for every combination of elements from the outer and inner collections, resulting in a cartesian product of operations.
</Note>

<Warning>
  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).
</Warning>

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

### Example 1: Creating connections between all user pairs

<CodeGroup>
  ```helixql Query focus={1-15} [expandable] theme={null}
  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"
  ```

  ```helixql Schema theme={null}
  N::User {
      name: String,
      age: U8,
      interests: String
  }

  E::Knows {
  }
  ```
</CodeGroup>

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

<CodeGroup>
  ```python Python [expandable] theme={null}
  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)
  ```

  ```rust Rust [expandable] theme={null}
  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(())
  }
  ```

  ```go Go [expandable] theme={null}
  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)
  }
  ```

  ```typescript TypeScript [expandable] theme={null}
  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);
  });
  ```

  ```bash Curl [expandable] theme={null}
  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"}
      ]
    }'
  ```
</CodeGroup>

### Example 2: Cross-product operations with hierarchical data

<CodeGroup>
  ```helixql Query focus={1-20} [expandable] theme={null}
  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"
  ```

  ```helixql Schema theme={null}
  N::Chapter {
      chapter_index: I64,
      title: String
  }

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

  V::Embedding {
      dimension: 384
  }

  E::Contains {
  }

  E::EmbeddingOf {
      chunk: String
  }
  ```
</CodeGroup>

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

<CodeGroup>
  ```python Python [expandable] theme={null}
  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)
  ```

  ```rust Rust [expandable] theme={null}
  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(())
  }
  ```

  ```go Go [expandable] theme={null}
  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)
  }
  ```

  ```typescript TypeScript [expandable] theme={null}
  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);
  });
  ```

  ```bash Curl [expandable] theme={null}
  # 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]}
              ]
            }
          ]
        }
      ]
    }'
  ```
</CodeGroup>

## Performance considerations

<Warning>
  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
</Warning>

### 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

## Related topics

<CardGroup cols={2}>
  <Card title="Basic FOR Loops" icon="arrows-rotate" href="/documentation/hql/control-flow/for-basic">
    Iterate over collections with simple variable binding
  </Card>

  <Card title="FOR Loop Destructuring" icon="code-branch" href="/documentation/hql/control-flow/for-destructuring">
    Extract multiple properties directly in loop variable binding
  </Card>
</CardGroup>