Deep Queries

Query nested objects, referenced entities, and arrays using dot notation and wildcards. Access deeply nested data structures for filtering across model relationships.

Syntax

Parameters

Parameter	Type	Required	Description
`attribute (dot notation)`	`string`	Yes	Use dots to traverse: 'reference.property' or 'ref.nested.property'
`attribute ([*] wildcard)`	`string`	Yes	Use [] for arrays: 'items[].property' matches ANY element
`attribute ([n] index)`	`string`	No	Use [0], [1] for specific index: 'items[0].property'

Return Type

Standard query return. Deep paths are resolved during filtering.

Usage Notes

Use dot notation to traverse single-valued references
Use [*] wildcard to match ANY element in an array
Use [n] to query a specific array index (0-based)
Chain multiple levels: customer.address.city
Array wildcards can be chained: items[*].variants[*].color
Check for undefined references first to avoid unexpected results
Verify available refs with model.references.keys()
For performance, see [Derived Properties](/sdk/advanced/derived-properties)

Related Methods

Query Filter - Basic filtering with operators
Query Search - Text search on deep properties
Query Range - Range queries on deep properties

Examples

Single-Level Reference

Query by a property of a referenced entity using dot notation.

Multi-Level Reference

Chain through multiple references with dot notation.

Array Wildcard Query

Query any element in an array using [*] wildcard.

Specific Array Index

Query a specific position in an array.

Nested Array Query

Chain multiple array wildcards for deeply nested arrays.

JSON Property Query

Query nested properties within JSON fields.

Filter by Vendor Location

Practical example: filter products by vendor country.

Handle Missing References

Check for null/undefined references before deep querying.

Text Search in Nested Field

Combine deep queries with text search.

Range Query on Deep Property

Apply range filters to referenced entity properties.