# Query documents

Executes a structured query against all documents in the organization, returning matching results with full control over which fields and traits are returned, how results are filtered, and how pages are navigated.

---

## Query Language

Queries are expressed as a single string using a structured query language with up to four clauses:


fetch().orderBy(, asc|desc))]
from([, ...])
[match('')]
[filter()]


Only fetch and from are required. match and filter are optional and may appear in any order after from.

---

## fetch() — Field and Trait Selection

Specifies which fields or traits to return. Multiple items are comma-separated.

| Syntax | Description |
|---|---|
| fetch(/) | Return the entire root document |
| fetch(/field) | Return a single top-level field |
| fetch(/field/subfield) | Return a nested field |
| fetch($trait) | Return a trait result at the root |
| fetch(/path/$trait) | Return a trait scoped to a field path |
| fetch($trait$subtrait) | Return a trait with a sub-trait qualifier |
| fetch($trait(key=value)) | Return a trait with attribute parameters |
| fetch(/f1, $summary, /path/$preview) | Return multiple items |

Ordering — append .orderBy(, asc|desc) to fetch():

fetch(/).orderBy(/name, asc)
fetch($summary).orderBy(/createdAt, desc)


Pagination — append .limit() or .limit(, ) to fetch():

fetch(/).limit(25)
fetch(/).limit(25, nextPageToken)

The cursor value is the opaque pageCursor string returned in the previous response.

---

## from() — Document Kind Selection

Specifies one or more document kinds to query. Kind names must be lowercase letters and underscores only (3–62 characters).


from(brand)
from(asset, brand, region)


Default platform kinds: media, brand, campaign, category, toolkit, section, block. Custom kinds defined in your organization are also supported.

---

## match() — Full-Text Search

Performs a full-text keyword search across indexed document content. Keywords are provided as a single-quoted string. Results are ranked by relevance when orderBy is not specified.


match('acme global')
match('Q4 campaign hero')


---

## filter() — Field-Level Conditions

Applies field-level conditions to narrow results. Expressions can be simple or compound.

Comparison operators:

| Operator | Meaning |
|---|---|
| == | Equals |
| != | Not equals |
| ` | Greater than |
| >= | Greater than or equal |
| ... | Contains (substring match or array membership) |
| !.. | Does not contain |

Logical operators: && (AND), || (OR), (...) (grouping)

Literal value types:

| Type | Syntax | Examples |
|---|---|---|
| Null | null | null |
| Boolean | true / false | true |
| Number | integer or decimal | 42, 3.14, -10 |
| String | single-quoted | 'active', 'Acme Corp' |


filter(/status == 'active')
filter(/rating >= 4 && /region != null)
filter((/status == 'active' || /status == 'pending') && /owner != null)
filter(/tags ... 'featured')
filter(/$$id == 'assetAbc123')


Strings in filter conditions must be single-quoted. Supported escape sequences: \\, \', \n, \r, \t.

---

## Property Paths

Property paths reference fields within a document and always begin with /. Nested fields are separated by /.

| Path | Description |
|---|---|
| / | The root document |
| /name | Top-level field |
| /metadata/createdBy | Nested field |
| /tags | Array field |
| /$$id | Reserved system field (prefixed with $$) |

Range selectors on link properties — link fields (relationships to other documents) support a range selector [start..end] to limit which linked items are returned. Both bounds are zero-based; start is inclusive, end is exclusive.

| Syntax | Description |
|---|---|
| /items[0..5] | First 5 linked items |
| /items[3..] | All linked items from index 3 onward |
| /items[..10] | First 10 linked items |
| /items[2..8] | Items at indices 2 through 7 |

Ranges can appear at multiple levels of a path:

fetch(/sections[0..3]/media[..10]) from(toolkit)


---

## Traits

Traits define a standard contract for a set of fields a document kind can return. They are referenced in fetch() using the $ prefix.

| Trait | Parameters | Returned Fields |
|---|---|---|
| $summary | — | name, description |
| $tile | — | fgColor, bgColor, iconUrl |
| $children | limit (optional) | items (array), depth |
| $content | — | id, mimeType, contentType, size, filename, description, caption; plus type-specific: image (width, height), video (width, height, durationMs), document (width, height, pages) |
| $preview | w, h, representationType | id, url |
| $insights | — | Array of insight metrics (single value or timeseries) |
| $timeline | — | from, to (timestamps) |
| $version | — | number, isLatest |

Sub-traits apply a secondary trait to each item returned by the parent:

fetch($children$summary)           # fetch children, return $summary for each
fetch($children$summary(limit=5))  # limit to 5 children


---

## Complete Examples


# Fetch all fields from a single kind
fetch(/) from(brand)

# Fetch specific fields
fetch(/name, /status, /region) from(asset)

# Fetch a trait
fetch($summary) from(brand)

# Fetch multiple traits and fields
fetch($summary, $tile, /metadata) from(brand)

# Fetch a trait at a nested path
fetch(/heroImage/$preview(w=800, h=600)) from(campaign)

# Full-text search
fetch($summary) from(asset) match('product launch 2024')

# Filter by a field value
fetch(/) from(asset) filter(/status == 'approved')

# Filter with AND
fetch($summary) from(asset) filter(/status == 'active' && /owner != null)

# Filter with OR and grouping
fetch($summary) from(asset)
filter((/status == 'active' || /status == 'pending') && /region != null)

# Contains / not-contains
fetch(/) from(asset) filter(/tags ... 'featured')
fetch(/) from(brand) filter(/name !.. 'draft')

# Query multiple kinds
fetch($summary) from(brand, region, asset) filter(/status == 'active')

# Order and paginate
fetch($summary).orderBy(/name, asc).limit(20) from(brand)

# Continue from a cursor
fetch($summary).orderBy(/name, asc).limit(20, nextPageCursorToken) from(brand)

# Fetch linked items with a range
fetch(/items[0..5]) from(category)

# Nested ranges
fetch(/sections[0..3]/media[..10]) from(toolkit)

# Limit children with trait attribute
fetch($children(limit=5)) from(category)

# Combined: search, filter, order, paginate
fetch($summary, $preview(w=400, h=300)).orderBy(/name, asc).limit(10, abc123)
from(asset)
match('campaign hero')
filter(/status == 'active' && /region != null)


---

## Request Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| query | string | Yes | The query expression string |
| verbose | boolean | No | When true, includes per-phase execution timing in the response (info field) |

## Response

| Field | Description |
|---|---|
| documents | List of matching document objects |
| pageCursor | Opaque token to pass to the next request to retrieve the next page; absent when no further pages exist |
| info | Query timing breakdown by phase (match, filter, projection) — only present when verbose: true` |

Endpoint: POST /api/v1/document/query
Version: 3.0
Security: bearerAuth

## Request fields (application/json):

  - `query` (string)
    Rule data fields

  - `verbose` (boolean)

## Response 200 fields (application/json):

  - `documents` (array)

  - `documents.id` (string)
    Rule data fields

  - `documents.kind` (string)
    Rule data fields

  - `documents.doc` (any)

  - `documents.createdDt` (object)

  - `documents.createdDt.seconds` (integer)

  - `documents.createdDt.nanos` (integer)

  - `documents.updatedDt` (object)

  - `documents.deletedDt` (object)

  - `pageCursor` (string)
    Rule data fields

  - `info` (object)

  - `info.query` (string)
    Rule data fields

  - `info.timings` (object)

  - `info.timings.match` (number)

  - `info.timings.filter` (number)

  - `info.timings.projection` (number)

## Response 400 fields (application/json):

  - `message` (string)

## Response 401 fields (application/json):

  - `message` (string)

## Response 403 fields (application/json):

  - `message` (string)

## Response 404 fields (application/json):

  - `message` (string)

## Response 409 fields (application/json):

  - `message` (string)

## Response 429 fields (application/json):

  - `message` (string)

## Response 499 fields (application/json):

  - `message` (string)

## Response 500 fields (application/json):

  - `message` (string)

## Response 501 fields (application/json):

  - `message` (string)

## Response 503 fields (application/json):

  - `message` (string)

## Response 504 fields (application/json):

  - `message` (string)