Enhance documentation to clarify support for nested object and array properties, including details on dotted-path filtering and indexing limitations. Update sections on property types, query capabilities, and examples for TypeScript and Rust to reflect the new features and best practices for handling nested structures. Ensure consistency across guides and improve user understanding of property handling in queries and mutations.

xav-db · xav-db · commit e1eacc36620f · 2026-06-02T14:10:42.000+01:00
diff --git a/database/data-model.mdx b/database/data-model.mdx
@@ -13,8 +13,17 @@ Nodes and edges are identified by 64-bit unsigned IDs. Edges are directed: each
 node and a target node. Labels are stored as the reserved `$label` property and are used for
 type-based filtering and label-scoped secondary, vector, and text indexes.
 
-Properties are strongly typed. Supported types: boolean, integer, floating-point, string, bytes,
-and array variants of each.
+Properties are strongly typed. Supported types include boolean, integer,
+floating-point, string, bytes, typed primitive arrays, generic arrays, and object
+maps. Object maps may be nested; query property names such as
+`metadata.externalID` read nested fields with exact-first dotted-path lookup. A
+stored top-level property literally named `metadata.externalID` wins over the
+nested `metadata.externalID` path during scans.
+
+Nested object fields are queryable in filters and projections, but V1 indexing is
+top-level only. Keep secondary, text, and vector indexed values as top-level
+properties. Generic arrays are stored as values and returned as values, but array
+index path syntax such as `tags.0` is not supported.
 
 ## Multigraph
 
diff --git a/database/indexing/secondary.mdx b/database/indexing/secondary.mdx
@@ -17,6 +17,10 @@ storage. Only index properties that are frequently filtered on. Unindexed proper
 queryable via `.where_(Predicate::...)`, but the route will scan the label rather than seek the
 index.
 
+Indexes address top-level properties only. A query may filter a nested object field with a dotted
+path such as `metadata.externalID`, but that filter is scan-only in V1 and cannot be declared as an
+equality or range index. Store frequently indexed metadata as explicit top-level properties.
+
 The DSL fragments below are bare traversals. To execute them, wrap each one in a `read_batch()`
 or `write_batch()` route as shown in [Querying](/database/querying).
 
diff --git a/database/indexing/text.mdx b/database/indexing/text.mdx
@@ -8,6 +8,9 @@ Text indexes provide BM25 full-text search on node and edge properties. They are
 like other indexes rather than rebuilt transiently per query. Indexed values can be `String` or
 `StringArray`, with configurable analyzer presets and optional term positions.
 
+Text index properties are top-level properties. Nested object fields are not flattened into BM25;
+store searchable text directly on the property you pass to the text-search builder.
+
 The third argument to the index-creation builders is an optional tenant property name; pass
 `None::<&str>` for a global index. Tenant-partitioned text indexes currently require the
 partition property name to be `tenant_id` — see [Multi-Tenancy](/database/multi-tenancy) for the
diff --git a/database/indexing/vector.mdx b/database/indexing/vector.mdx
@@ -9,6 +9,9 @@ Helix supports vector indexes on both nodes and edges. Values are normalized to
 indexing, and supported distance metrics are cosine, euclidean, and manhattan. The query vector
 must match the configured index dimension exactly.
 
+Vector index properties are top-level properties. Nested object fields are not indexed as vectors;
+store embeddings directly on the node or edge property you pass to the vector-search builder.
+
 Vector search is approximate by design, trading a small amount of recall for significantly faster
 search over large datasets. The third argument to the index-creation builders is an optional
 tenant property name; pass `None::<&str>` for a global index, or see
diff --git a/database/limits.mdx b/database/limits.mdx
@@ -12,8 +12,8 @@ fundamental architectural boundaries.
 | Limit                  | Value                                                                                          |
 | ---------------------- | ---------------------------------------------------------------------------------------------- |
 | Node and edge ID range | 64-bit unsigned integer (max 2^63)                                                             |
-| Property value types   | boolean, integer, float, string, bytes, and array variants                                     |
-| Nested structures      | Not supported. Properties are flat key-value pairs.                                            |
+| Property value types   | boolean, integer, float, string, bytes, typed primitive arrays, generic arrays, and objects    |
+| Nested structures      | Stored object/array values are supported. Dotted-path lookup such as `metadata.externalID` works in scan-time filters, expressions, projections, `values`, filtered `valueMap`, and fallback ordering. Arrays are opaque; there is no array-index path syntax. |
 | Reserved property keys | `$label` (used for label-based filtering and label-scoped secondary, vector, and text indexes) |
 
 ## Vector Indexes
@@ -32,7 +32,7 @@ fundamental architectural boundaries.
 | Limit                    | Value                                                                                                                                                         |
 | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Scope                    | Node and edge properties                                                                                                                                      |
-| Supported property types | `String` and `StringArray`                                                                                                                                    |
+| Supported property types | Top-level `String` and `StringArray` properties. Nested object fields are not flattened for BM25.                                                            |
 | Unsupported values       | `null` and non-string values are rejected                                                                                                                     |
 | Analyzer config          | Preset analyzers: `standard`, `standard_stem_en`, `whitespace_lowercase`                                                                                      |
 | Term positions           | Optional                                                                                                                                                      |
@@ -42,8 +42,8 @@ fundamental architectural boundaries.
 
 | Limit            | Value                                                                                                      |
 | ---------------- | ---------------------------------------------------------------------------------------------------------- |
-| Equality indexes | Supported on node and edge properties                                                                      |
-| Range indexes    | Supported on numeric and string properties                                                                 |
+| Equality indexes | Supported on top-level node and edge properties. Nested dotted paths are scan-only in V1.                    |
+| Range indexes    | Supported on top-level numeric and string properties. Nested dotted paths are scan-only in V1.               |
 | Encoding         | Range indexes use lexicographic string encoding. Values must be encoded consistently for correct ordering. |
 
 ## Queries
diff --git a/database/querying-guide/advanced.mdx b/database/querying-guide/advanced.mdx
@@ -455,6 +455,10 @@ A few notes specific to `forEachParam`:
 - The parameter must be typed `{"Array": "Object"}` — an array of plain JSON
   objects. `defineParams({ users: param.array(param.object(...)) })` produces this
   shape automatically.
+- Each loop iteration exposes the current object's top-level fields as scoped
+  parameters. If a field itself is an object, pass it through as a whole property
+  value, for example `PropertyInput.param("metadata")`, then query the stored
+  nested fields later with dotted paths such as `metadata.externalID`.
 
 ## Next Steps
 
diff --git a/database/querying-guide/filtering.mdx b/database/querying-guide/filtering.mdx
@@ -176,6 +176,68 @@ Use a `SourcePredicate` when you want the filter to participate in index selecti
 the source step. Use `.where(Predicate.*)` when you need anything outside that set,
 or when you want the filter to run *after* a graph traversal step.
 
+## Nested property paths
+
+Object properties can be filtered with dotted paths. The runtime first checks for
+an exact top-level property name, then walks nested object fields when the name
+contains `.`.
+
+<CodeGroup>
+```ts TypeScript
+import { g, Predicate, readBatch } from "@helix-db/helix-db";
+
+const usersByExternalId = readBatch()
+  .varAs(
+    "users",
+    g()
+      .nWithLabel("User")
+      .where(Predicate.eq("metadata.externalID", "crm-42"))
+      .valueMap(["$id", "username", "metadata.externalID"]),
+  )
+  .returning(["users"]);
+```
+
+```rust Rust
+use helix_db::dsl::prelude::*;
+
+#[register]
+pub fn users_by_external_id() -> ReadBatch {
+    read_batch()
+        .var_as(
+            "users",
+            g().n_with_label("User")
+                .where_(Predicate::eq("metadata.externalID", "crm-42"))
+                .value_map(Some(vec!["$id", "username", "metadata.externalID"])),
+        )
+        .returning(["users"])
+}
+```
+
+```json JSON
+{
+  "queries": [
+    {
+      "Query": {
+        "name": "users",
+        "steps": [
+          { "NWhere": { "Eq": ["$label", { "String": "User" }] } },
+          { "Where": { "Eq": ["metadata.externalID", { "String": "crm-42" }] } },
+          { "ValueMap": ["$id", "username", "metadata.externalID"] }
+        ],
+        "condition": null
+      }
+    }
+  ],
+  "returns": ["users"]
+}
+```
+</CodeGroup>
+
+Dotted paths are scan-only in V1. Pair them with an indexed top-level anchor such
+as label, tenant, or status when the label is large; the indexed predicate narrows
+candidate rows and the dotted predicate runs as a residual filter. Arrays are
+opaque, so `metadata.tags.0` is not supported.
+
 ## Parameter-bound predicates
 
 To filter by a value the caller supplies at request time, use the `*Param` family.
diff --git a/database/querying-guide/mutations.mdx b/database/querying-guide/mutations.mdx
@@ -95,6 +95,121 @@ A few wire-format details:
 - The result of `addN` is a node stream, so the same chain can keep going —
   here, `.project([...])` collects the new id.
 
+## Nested object and array properties
+
+Node and edge properties can store object and array values. Use nested objects for
+metadata you want to return or filter by scan-time dotted paths; keep frequently
+indexed values as top-level properties.
+
+<CodeGroup>
+```ts TypeScript
+import { g, writeBatch } from "@helix-db/helix-db";
+
+const addUserWithMetadata = writeBatch()
+  .varAs(
+    "user",
+    g()
+      .addN("User", {
+        username: "alice",
+        metadata: {
+          externalID: "crm-42",
+          score: 20,
+          tags: ["trial", 7],
+          preferences: { locale: "en-US" },
+        },
+      })
+      .valueMap(["username", "metadata.externalID", "metadata.preferences.locale"]),
+  )
+  .returning(["user"]);
+```
+
+```rust Rust
+use helix_db::dsl::prelude::*;
+
+#[register]
+pub fn add_user_with_metadata() -> WriteBatch {
+    let metadata = PropertyValue::object(vec![
+        ("externalID", PropertyValue::from("crm-42")),
+        ("score", PropertyValue::from(20i64)),
+        (
+            "tags",
+            PropertyValue::array(vec![
+                PropertyValue::from("trial"),
+                PropertyValue::from(7i64),
+            ]),
+        ),
+        (
+            "preferences",
+            PropertyValue::object(vec![("locale", PropertyValue::from("en-US"))]),
+        ),
+    ]);
+
+    write_batch()
+        .var_as(
+            "user",
+            g().add_n(
+                "User",
+                vec![
+                    ("username", PropertyInput::from("alice")),
+                    ("metadata", PropertyInput::from(metadata)),
+                ],
+            )
+            .value_map(Some(vec![
+                "username",
+                "metadata.externalID",
+                "metadata.preferences.locale",
+            ])),
+        )
+        .returning(["user"])
+}
+```
+
+```json JSON
+{
+  "queries": [
+    {
+      "Query": {
+        "name": "user",
+        "steps": [
+          {
+            "AddN": {
+              "label": "User",
+              "properties": [
+                ["username", { "Value": { "String": "alice" } }],
+                [
+                  "metadata",
+                  {
+                    "Value": {
+                      "Object": {
+                        "externalID": { "String": "crm-42" },
+                        "score": { "I64": 20 },
+                        "tags": { "Array": [{ "String": "trial" }, { "I64": 7 }] },
+                        "preferences": {
+                          "Object": { "locale": { "String": "en-US" } }
+                        }
+                      }
+                    }
+                  }
+                ]
+              ]
+            }
+          },
+          { "ValueMap": ["username", "metadata.externalID", "metadata.preferences.locale"] }
+        ],
+        "condition": null
+      }
+    }
+  ],
+  "returns": ["user"]
+}
+```
+</CodeGroup>
+
+Nested property lookup is exact-first. A top-level property literally named
+`metadata.externalID` is read before walking the nested `metadata` object. Dotted
+paths only walk object values; arrays are returned as values and do not support
+path syntax such as `tags.0`.
+
 ## Adding edges between bound nodes
 
 `addE` joins two nodes by label. The `to` argument is a `NodeRef` — most often
diff --git a/database/querying-guide/parameters-bundles.mdx b/database/querying-guide/parameters-bundles.mdx
@@ -340,6 +340,36 @@ A complete envelope produced by `toDynamicJson`:
 }
 ```
 
+Nested object and array parameter values are still bare JSON at envelope
+position. When a parameter is used as a property value, the runtime converts that
+JSON object into a stored object property:
+
+```ts
+const params = defineParams({ metadata: param.object(param.value()) });
+
+writeBatch().varAs(
+  "user",
+  g().addN("User", { metadata: PropertyInput.param("metadata") }),
+);
+```
+
+```json
+{
+  "parameters": {
+    "metadata": {
+      "externalID": "crm-42",
+      "preferences": { "locale": "en-US" },
+      "tags": ["trial", 7]
+    }
+  },
+  "parameter_types": { "metadata": "Object" }
+}
+```
+
+After storage, query nested object fields with dotted paths such as
+`metadata.externalID`. The top-level `parameters` map itself does not use tagged
+`PropertyValue` wrappers.
+
 ## Number handling: `bigint` for `i64`
 
 JavaScript `number` only has 53 bits of integer precision. The DSL accepts a plain
diff --git a/database/querying-guide/projections.mdx b/database/querying-guide/projections.mdx
@@ -154,6 +154,21 @@ pub fn users_for_admin_panel() -> ReadBatch {
 always available even though they are not declared on your schema. `$from`/`$to`
 appear on edge streams; `$distance` appears on vector / text search hits.
 
+Filtered `values(...)` and `valueMap(...)` also accept dotted paths into object
+properties, such as `metadata.externalID`. `valueMap(null)` returns stored
+top-level properties as-is and does not flatten nested objects. When you request a
+dotted path explicitly, the returned object is keyed by the requested source
+string unless you rename it with `project(...)`.
+
+```ts
+g().nWithLabel("User").valueMap(["$id", "metadata.externalID"]);
+```
+
+```rust
+g().n_with_label("User")
+    .value_map(Some(vec!["$id", "metadata.externalID"]));
+```
+
 ## `.project(...)` with renames and expressions
 
 `project([...])` is the most flexible terminal — it accepts a list of items, each one
@@ -166,6 +181,25 @@ either:
 Use it when you want to flatten ids out from under `$id`, return a different name
 than the schema's, or compute a derived field.
 
+`PropertyProjection` and `Expr.prop(...)` use the same property lookup rules as
+filters. This means nested object fields can be projected and renamed:
+
+```ts
+g().nWithLabel("User").project([
+  PropertyProjection.renamed("metadata.externalID", "external_id"),
+]);
+```
+
+```rust
+g().n_with_label("User").project(vec![
+    PropertyProjection::renamed("metadata.externalID", "external_id"),
+]);
+```
+
+Dotted paths are also valid in fallback ordering, for example
+`.orderBy("metadata.score", Order.Desc)`, but they are not backed by secondary
+indexes in V1.
+
 A typical `project` call mixes plain property pulls with one or two renames:
 
 <CodeGroup>
diff --git a/llms-full.txt b/llms-full.txt
