Query Syntax#

Overview#

Generally queries will consist of a where clause plus optional modifiers controlling the specific subset of results returned.

Where Clause#

The Where clause is an optional array of conditions. If omitted or empty, all documents of the queried type are returned (subject to limit). For some operators, value will be an array. All fields referenced in a query’s where clause must be defined in the same index. This includes system timestamp fields (e.g., $createdAt, $updatedAt, $transferredAt, and their block-height variants such as $createdAtBlockHeight and $createdAtCoreBlockHeight). See the following general syntax example:

Syntax#

{
  where: [
    [<fieldName>, <operator>, <value>],
    [<fieldName>, <array operator>, [<value1>, <value2>]] 
  ]
}

Fields#

Valid fields consist of the indices defined for the document being queried. For example, the DPNS data contract defines two indices for domain documents:

Index Field(s)	Index Type	Unique
normalizedParentDomainName, normalizedLabel	Compound	Yes
records.identity	Single Field	No

Comparison Operators#

Equal#

Name	Description
== (or =)	Matches values that are equal to a specified value

Range#

Name	Description
<	Matches values that are less than a specified value
<=	Matches values that are less than or equal to a specified value
>=	Matches values that are greater than or equal to a specified value
>	Matches values that are greater than a specified value
in	Matches all document(s) where the value of the field equals any value in the specified array The array must contain between 1 and 100 values, with no duplicates. Empty arrays, oversized arrays, and duplicate values are rejected with `InvalidInClause`
Between	Matches values between two bounds (inclusive on both sides) — value must be a two-element array `[lower, upper]` with `lower < upper`
BetweenExcludeBounds	Matches values strictly between two bounds (exclusive on both sides)
BetweenExcludeLeft	Matches values between two bounds, excluding the lower bound
BetweenExcludeRight	Matches values between two bounds, excluding the upper bound

Range operator constraints

A query can have only one effective range clause. Use Between or one of its variants to express both bounds, or supply two complementary range clauses on the same field; Platform normalizes the pair to the equivalent Between* form
A single in clause is only allowed for the last two indexed properties. This applies to ordinary document queries and grouped aggregates; ranked and having-range queries instead pin each leading index property with one clause, at most one of which may be an in of 2 to 10 elements
Range operators apply to an indexed field that follows any == and in clauses in the index. A standalone range (with no preceding ==/in clause) is valid when a matching index exists
Range operators are only allowed for the last two fields used in the where condition
Queries using range operators (including in, which is treated as a range) must also include an orderBy statement

Evaluation Operators#

Name	Description
startsWith	Selects documents where the value of a field begins with the specified characters. Must include an `orderBy` statement.
inTimeRange	Selects documents falling in one window of a `timeRange` index grid. See Time-range selection. Available on the v1 query surface only.

Time-range selection#

Added in version 4.2.0: Requires protocol version 14.

The inTimeRange operator selects one window of a time grid rather than comparing against a value. The clause’s field must name a timestamp covered by a timeRange index, and the operand is a typed selection rather than an ordinary value:

Selector	Selects
`NEWEST`	The freshest started window - the largest grid start at or before block time, so the latest partial slice of history.
`OLDEST`	The oldest window still active at block time, a near-full trailing window. Best for “trending over the last window” reads.
`BY_START`	A named window, current or historic, identified by its start timestamp.

The relative selectors (NEWEST and OLDEST) are resolved server-side from the current block time, and a proof verifier re-derives the same window from the quorum-signed response metadata time, so neither side has to trust the other’s clock. They must not carry a start timestamp.

BY_START requires a start timestamp in milliseconds, and it must lie on the grid (start_ms == phase + k * step). An unaligned start is rejected rather than snapped to the nearest window. A window holding no documents - including one that has not started yet - is a provable empty answer, not an error.

A query may carry at most one inTimeRange clause. When more than one timeRange grid buckets the field, the clause must also name the grid (its range, step, and phase, in the contract’s own seconds); a bare selector is ambiguous there and rejected. Naming the grid is optional when exactly one grid covers the field.

Operator aliases#

Operator names are matched against a fixed set of aliases:

Operator	Accepted aliases
`==`	`=`
`in`	`In`
`Between`	`between`
`BetweenExclude*`	CamelCase, lowercase, and snake_case variants, such as `betweenExcludeLeft`, `betweenexcludeleft`, and `between_exclude_left`
`startsWith`	`StartsWith`, `startswith`, `starts_with`

Any other spelling is rejected.

Operator Examples#

Range

{
  where: [
    ["nameHash", "<", "56116861626961756e6176657a382e64617368"],
  ],
  orderBy: [
    ["nameHash", "asc"],
  ],
}

Between

{
  where: [
    ["normalizedParentDomainName", "==", "dash"],
    // Return names between "alice" and "carol" (inclusive)
    ["normalizedLabel", "Between", ["alice", "carol"]],
  ],
  orderBy: [
    ["normalizedLabel", "asc"],
  ]
}

in

in#

{
  where: [
      ["normalizedParentDomainName", "==", "dash"],
      // Return all matching names from the provided array
      ["normalizedLabel", "in", ["alice", "bob"]],
    ],
  orderBy: [
    ["normalizedLabel", "asc"],
  ]
}

startsWith

startsWith#

{
  where: [
      ["normalizedParentDomainName", "==", "dash"],
      // Return any names beginning with "al" (e.g. alice, alfred)
      ["normalizedLabel", "startsWith", "al"],
    ],
  orderBy: [
    ["normalizedLabel", "asc"],
  ]
}

Query Modifiers#

The query modifiers described here determine how query results will be sorted and what subset of data matching the query will be returned.

Modifier	Effect	Example
`limit`	Restricts the number of documents returned. An omitted value or `0` uses the configured default (100 by default). Positive values cannot exceed the configured maximum (also 100 by default). See Aggregate query limits for aggregate result modes.	`limit: 10`
`orderBy`	Returns records sorted by the field(s) provided. The `orderBy` fields must match a consecutive run of the index’s properties, read from the end of the index (for a compound index, sort by one or more of its trailing fields). Required for `>`, `<`, `>=`, `<=`, `in`, `Between`, `BetweenExcludeBounds`, `BetweenExcludeLeft`, `BetweenExcludeRight`, and `startsWith` queries. Can also be used with equality-only queries to sort by a trailing field of the matched index.	`orderBy: [['normalizedLabel', 'asc']]`
`startAt`	Returns records beginning with the document ID provided	`startAt: '<document ID>'`
`startAfter`	Returns records beginning after the document ID provided	`startAfter: '<document ID>'`
`offset`	On the v1 `getDocuments` wire, consumed only in ranked aggregate mode, where it skips that many ranks before the returned page and the response reports the skip performed; every other v1 path rejects it with `Unsupported`, so use `startAt` or `startAfter` for pagination there.	`offset: 20`

Ordering compound indexes#

For indices composed of multiple fields (example from the DPNS data contract), the sort order in an orderBy must either match the order defined in the data contract OR be the inverse order.

Combining a cursor with a range operator#

This behavior applies when returning DOCUMENTS; aggregate result modes do not support cursors.

When a startAt / startAfter cursor is combined with a range operator (>, >=, <, <=), the cursor narrows the effective range in the direction of the orderBy sort:

Ascending order — the cursor is the lower bound and the range clause’s value is the upper bound. startAfter excludes the cursor row itself.
Descending order — the roles invert: the range clause’s value is the lower bound and the cursor is the upper bound.

Changed in version 4.1.0: Ascending queries that combined a cursor with a < or <= clause previously built their range backwards, returning incorrect or empty results. Paginating a bounded range now returns the expected results, so a query written against the earlier behavior may return different results after upgrading.

Aggregate Queries#

Added in version 4.0.0.

Changed in version 4.2.0: Protocol version 14 adds ranked and having-range query modes, and relaxes the blanket rejection of HAVING and OFFSET accordingly.

The getDocuments v1 surface adds an aggregate-query mode. The same where / orderBy clauses described above still apply; an additional select projection (and optional groupBy) determines whether the request returns documents or aggregate values over the matched set.

`select`	Returns
`DOCUMENTS`	Matched documents (same as v0).
`COUNT(*)`	Number of documents matching the query.
`SUM(<field>)`	Sum of `<field>` across matching documents.
`AVG(<field>)`	`(count, sum)` pair the client divides to compute the average.

groupBy is optional. With an empty groupBy, the response carries a single aggregate value; with a groupBy of one or two fields, the response carries one entry per group. Each groupBy field must be constrained by the query’s where clause: a single field must carry an in or range clause (startsWith counts as a range here), and two fields must be an (in field, range field) pair. Any other groupBy shape is currently rejected with Unsupported.

Aggregate queries impose extra schema requirements. For unfiltered doctype-wide aggregates, the document type must set the doctype-level flags — COUNT needs documentsCountable, SUM needs documentsSummable, AVG needs documentsAverageable (or both base flags). An aggregate with a where clause or groupBy instead requires an index covering the queried fields that carries the corresponding index-level flags (countable, summable, averageable). Range-grouped aggregates additionally need the range* variants, and ranked and having-range queries need the matching ranked axis (rankedCountable, rankedSummable, or rankedAverageable), each of which costs its own secondary tree and is opted into separately. See the aggregate query flags for the schema annotations and the getDocuments reference for the full select × groupBy shape table.

On the raw gRPC layer, SUM / AVG integer values are delivered to JavaScript clients as strings so they don’t lose precision on values larger than Number.MAX_SAFE_INTEGER.

Aggregate query limits#

The limit modifier behaves differently in aggregate result modes than it does when returning DOCUMENTS, and some select × groupBy combinations reject it outright. On the wire, limit is an optional field:

Omit limit to request the server’s default.
Send a positive value to request an explicit cap.
An explicit limit: 0 is rejected with InvalidLimit in every select mode, including DOCUMENTS. On this wire 0 is never a “use the default” sentinel; that behavior applies to SDK query objects and the v0 getDocuments wire, where the limit field has no unset state and 0 means omitted (see Query Modifiers).

SDK bindings that must pass a numeric argument use -1 as the server-default sentinel; any other negative value is rejected.

Changed in version 4.1.0: In aggregate result modes, an effective limit of zero is now rejected with InvalidLimit rather than walking storage with a zero bound, which previously surfaced as an empty result set.

How a positive limit is interpreted depends on groupBy:

`select` / `groupBy`	Effect of `limit`
`DOCUMENTS`	Uses the general behavior described under Query Modifiers.
`COUNT` with an empty `groupBy`	Rejected with `InvalidLimit`. An aggregate count is a single row by construction.
`COUNT` grouped by an `In` field	Rejected with `InvalidLimit`. The `In` array is already capped at 100 entries, so the result is bounded. Narrow the `In` array instead.
`COUNT` grouped by a range field	Caps the distinct-range walk, so the response carries at most `limit` groups.
`COUNT` grouped by an `In` field and a range field	A global cap over the emitted stream, not a per-branch cap. With three `In` values and `limit: 5`, the response carries at most 5 entries in total across all branches.

SUM and AVG follow the same policy as COUNT: distinct walks apply the default/cap/reject-zero rules, and a zero limit is rejected.

Oversized limits with and without proofs#

On range-grouped aggregates, an oversized limit is handled differently depending on whether a proof is requested. With prove: true, a limit above the node’s configured maximum is rejected with InvalidLimit so that proof bytes stay deterministic. With prove: false, the limit is silently clamped to that maximum instead. With the default maximum of 100, for example, a caller requesting 500 groups receives at most 100 with no error, which can look like missing data.

Compound carrier-aggregate shapes that pair an In field with a range field and request a proof cap the outer range walk at 10 entries. This is a hard ceiling: a limit above it is rejected, and callers needing more results issue repeated queries over disjoint outer-range windows.

Ranked aggregate queries#

Added in version 4.2.0: Requires protocol version 14.

A ranked query returns the top or bottom groups by their aggregate value - a provable “leaderboard” read - instead of every matching group. A request routes to the ranked executor when it combines an aggregate select with exactly one groupBy property and exactly one orderBy clause naming the selected aggregate:

`select`	`orderBy` names
`COUNT(*)`	The reserved `$count` sentinel.
`SUM(<field>)`	`<field>`, the summed property.
`AVG(<field>)`	`<field>`, the averaged property.

The orderBy clause must use the field spelling shown above; naming the aggregate function itself is rejected.

desc walks the axis from the largest aggregate down (the “top n” reading); asc walks from the smallest up (the “bottom n” reading). Groups holding equal aggregate values are returned in group-key order in the direction of the walk.

limit is required and must be between 1 and 100. This is a hard ceiling rather than a clamp: a larger limit is rejected with InvalidLimit, because the limit is part of the traversal a client re-executes when verifying the proof.

offset skips that many ranks before the returned page, so limit: 1, offset: 4 returns the fifth-ranked group. The skip is counted from subtree aggregates rather than walked, so there is deliberately no ceiling on it. The response reports the skip actually performed, which can be smaller than the requested offset when the groups run out. Cursors (startAt / startAfter) are rejected in ranked mode, which makes offset the only way to page a ranked result.

Where clauses are optional. When present, each pins one leading property of a covering compound ranked index with an equality, except that at most one may be an in clause of 2 to 10 distinct elements (a single-element in normalizes to an equality pin). A multi-element in fans the read out into one branch per element, and combining it with a non-zero offset is rejected with InvalidLimit, because the counted rank-skip is attested per-branch and cannot span the union.

The covering index must declare the matching ranking axis - rankedCountable for COUNT(*), rankedSummable for SUM, rankedAverageable for AVG. Each axis is opted into separately and costs its own secondary tree; none implies another. See Document Indices for the schema keywords.

Having-range queries#

Added in version 4.2.0: Requires protocol version 14.

A having-range query filters grouped aggregates by their aggregate value, returning the groups whose aggregate falls in a bounded range. A request routes to the having-range executor when it combines an aggregate select with exactly one groupBy property and exactly one having clause whose aggregate is the selected aggregate.

The operator must describe one contiguous range - ==, >, >=, <, <=, Between, or a BetweenExclude* variant. != and in are rejected, because neither describes a contiguous range of the axis. Multi-clause having is also rejected.

As with ranked queries, limit must be between 1 and 100, and the same ranking-axis index flags apply.

Having-range queries support neither offset nor cursors. To continue past a page cut short by the limit, tighten the having bound past the last aggregate value seen. This cannot cross a tie: several groups sharing the boundary aggregate value must fit inside one limit.

An orderBy on the selected aggregate is accepted and flips the walk direction.

On protocol version 13 and earlier, and for every other having shape at v14, having is rejected with Unsupported. A shape that routes here but carries a bad limit is rejected with InvalidLimit, and one with no groupBy with InvalidParameter.

Other aggregate restrictions#

startAt and startAfter are supported only with DOCUMENTS; every aggregate result mode rejects cursors. How to page instead depends on the mode:
- Grouped COUNT / SUM / AVG - narrow the where range to query a different group range.
- Ranked - use offset, which is counted rather than walked and so stays cheap at any depth.
- Having-range - neither cursors nor offset are available. Tighten the having bound past the last aggregate value seen. A page cut inside a tie cannot be continued, so size limit above the widest expected tie.
COUNT(<field>), MIN, MAX, and multi-projection SELECT are present on the wire but currently return Unsupported. Callers can encode them in builders ahead of server support landing, but evaluation rejects them today.
On the v1 wire, OFFSET is evaluated only in ranked aggregate mode. On the grouped COUNT / SUM / AVG paths, on having-range queries, and when returning DOCUMENTS, it still returns Unsupported.
HAVING is evaluated only in having-range mode. Every other HAVING shape returns Unsupported.

Chained queries#

Added in version 4.2.0: Chained queries have no protocol-version gate of their own, but depend in practice on protocol version 14, which is what admits the indexOnly and refersTo keywords they require.

A chained query is a provable semi-join: it returns the documents of one type whose IDs appear as a property value on the documents of another type. Conceptually:

SELECT * FROM <outerDocumentType> WHERE $id IN (SELECT <joinProperty> FROM <documentType> WHERE ...)

The request’s own document type, where clauses, orderBy, and limit describe the inner query. The outer half is derived from the inner results rather than sent, and a proof verifier re-derives it from the proven inner values - so the join cannot be steered by the node that answers it. The chained request names only the join property and the outer document type.

Chained mode has strict prerequisites:

The inner document type must be indexOnly, and must resolve to an index carrying the join property.
The join property must declare a same-contract refersTo: permanentDocument targeting the outer document type.
limit is required - it bounds the derived outer query, so there is no server-default fallback. A value outside 1 to 100 (the configured max_query_limit, 100 by default) is rejected with InvalidLimit rather than clamped.
The outer document type must not be indexOnly, and selects must be empty or a single DOCUMENTS projection.
groupBy, having, time-range clauses, cursors, and offset are all rejected. Paginate with a range clause on the join property.

The response carries both halves: the inner documents in query order, and the outer documents ordered by the first appearance of their ID among the inner results, deduplicated.

A node predating this feature ignores the chained field and serves the plain inner query. That fails closed on the client: an inner-only proof cannot satisfy the re-derived merged query.

Composite queries#

Added in version 4.2.0.

A composite query returns a page of documents plus one or more sub-queries derived from that page, answered as a single merged proof over one state root. This replaces a round-trip-per-lookup pattern - fetch a page, then fetch each referenced profile - with one provable request. Conceptually:

-- Page
SELECT * FROM <documentType> WHERE ... ORDER BY ... LIMIT <n>

-- Sub-query bound to the page: the IN values are read off the proven page documents
SELECT * FROM <subDocumentType> WHERE <field> IN (SELECT <sourceProperty> FROM <page results>)

-- Sub-query bound to an earlier sub-query
SELECT * FROM <subDocumentType2> WHERE <field> IN (SELECT <sourceProperty> FROM <sub-query 1 results>)

-- Sibling sub-query: unbound, proven under the same state root
SELECT * FROM <subDocumentType3> WHERE ... LIMIT <n>

For example, a page of post documents, a by-ID join fetching each author’s profile ($id IN the posts’ authorId values), and a COUNT sub-query tallying like documents per post (postId IN the posts’ $id values) are answered together as one proof.

The request’s own contract, document type, where clauses, orderBy, and limit describe the page. Each sub-query carries its own fixed clauses, and its IN clause is derived by the node from the proven documents of the page or of an earlier sub-query. As with chained queries, the verifier re-derives every sub-query from the proven page and re-checks the whole composition.

Each sub-query names a document type and optionally a different contract (empty means the page’s own), plus a kind:

Kind	Returns
`DOCUMENTS`	The matching documents.
`COUNT`	One count per derived value, read from the `countable` index covering the fixed clauses plus the bound field. A value with no entry counts zero.

A sub-query may declare a binding describing where its derived IN values come from:

Binding field	Meaning
`source`	Whose proven documents supply the values: `0` is the page, `n` is the preceding sub-query `n - 1`, which must be a `DOCUMENTS` sub-query.
`source_property`	The property read off each source document - `$id`, `$ownerId`, or an identifier-typed property. Dotted paths reach nested properties, and documents lacking the property contribute nothing.
`field`	The sub-query field receiving the derived `IN` clause.

Setting field to $id makes the sub-query a by-ID join, which requires the source property to declare refersTo: permanentDocument targeting the sub-query’s document type - every derived ID must resolve, and a missing document invalidates the proof. Any other field is a lookup, where absence is itself a proven fact. A sub-query with no binding is a sibling: an independent query proven under the same state root.

Composite mode has the same gates as chained mode: the page’s limit is required, and a value outside 1 to 100 is rejected with InvalidLimit rather than clamped. A page addressed by IDs is proven without its limit, so that limit must be at least as large as the number of IDs it addresses. groupBy, having, time-range clauses, cursors, and offset are rejected, and chained and composite modes are mutually exclusive. A request may carry at most 10 sub-queries.

Whether a sub-query takes its own limit depends on whether its lookup is already bounded by its values. A value-bounded lookup - a unique index, or an indexOnly terminal with every prefix fixed - must not carry one, and neither must a by-ID join or a count. Every other lookup, siblings included, requires one.

The response carries the page exactly as the page query alone would return it, followed by one result per sub-query in request order.

Example query#

The following query combines both a where clause and query modifiers.

Query object

const query = {
  limit: 5,
  startAt: '4Qp3menV9QjE92hc3BzkUCusAmHLxh1AU6gsVsPF4L2q',
  where: [
    ['normalizedParentDomainName', '==', 'dash'],
    ['normalizedLabel', 'startsWith', 'test'],
  ],
  orderBy: [
    ['normalizedLabel', 'asc'],
  ],
}

Evo SDK example

import { EvoSDK } from '@dashevo/evo-sdk';

const sdk = EvoSDK.testnetTrusted();
await sdk.connect();

const results = await sdk.documents.query({
  dataContractId: 'GWRSAVFMjXx8HpQFaNJMqBV7MBgMK4br5UESsB4S31Ec',
  documentTypeName: 'domain',
  limit: 5,
  startAt: '4etYFuWbXRXB74gTDp53eLUqjLEAtNSfUX2XtrQ1uMdT',
  where: [
    ['normalizedParentDomainName', '==', 'dash'],
    ['normalizedLabel', 'startsWith', 'test'],
  ],
  orderBy: [
    ['normalizedLabel', 'asc'],
  ],
});

for (const [id, doc] of results) {
  console.log(id.toString(), doc?.toJSON());
}

Evo SDK aggregate example

The Evo SDK does not expose select directly. Each aggregate mode has its own method — documents.count(), documents.sum(query, property), and documents.average(query, property). groupBy is passed as part of the query.

import { EvoSDK } from '@dashevo/evo-sdk';

const sdk = EvoSDK.testnetTrusted();
await sdk.connect();

// COUNT grouped by a range field: one entry per distinct rating.
// The `rating` range clause is what puts the query in grouped mode.
const counts = await sdk.documents.count({
  dataContractId: 'BdgTqaTAPYMyhp1WdeWdcvYSgoD7AuJ7tVCaCSXyQgyP',
  documentTypeName: 'review',
  where: [
    ['resourceId', '==', 'dashnote'],
    ['rating', 'between', [1, 5]],
  ],
  orderBy: [
    ['rating', 'asc'],
  ],
  groupBy: ['rating'],
});

// Keys are hex-encoded index keys, not the raw field values, and
// counts are BigInt. A small positive integer encodes as `0x80 | value`,
// so rating 5 is the key "85".
for (const [key, count] of counts) {
  console.log(`${key - 80} stars: ${count.toString()} review(s)`);
}

The query’s index must support the aggregate: this example needs a [resourceId, rating] index carrying the index-level countable and rangeCountable flags. An ungrouped count() returns a single-entry map keyed by the empty string, so read it with counts.values().next().value.

Query Syntax#

Overview#

Where Clause#

Fields#

Comparison Operators#

Equal#

Range#

Evaluation Operators#

Time-range selection#

Operator aliases#

Operator Examples#

Query Modifiers#

Ordering compound indexes#

Combining a cursor with a range operator#

Aggregate Queries#

Aggregate query limits#

Oversized limits with and without proofs#

Ranked aggregate queries#

Having-range queries#

Other aggregate restrictions#

Chained queries#

Composite queries#

Example query#

This Page