Query Capabilities#
Dash Platform allows applications to retrieve data in a structured and deterministic manner. Clients query the latest committed state of identities, data contracts, documents, and other Platform data similar to traditional databases while retaining decentralized trust benefits.
Querying the State#
Queries operate on the finalized data stored within Platform’s state tree. Responses reflect the most recently committed block and do not include pending changes.
This means:
Query results are consistent across nodes
Clients do not need to process blockchain history
Data retrieval is deterministic and efficient
Note
By default, queries return the current finalized state rather than the sequence of events that created it. Data contracts and document types configured to retain history are the exception: dedicated history queries return their successive revisions, and those responses support proofs like any other query.
Deterministic Results#
All queries produce deterministic results. The same query executed on two honest and up-to-date Platform nodes will always produce the same result. This ensures consistent application behavior regardless of which node provides the response.
Data Proofs#
Queries can return locally verifiable cryptographic proofs, allowing clients to verify response accuracy without trusting the responding node.
Two types of proofs exist:
Proof Type |
Purpose |
|---|---|
Inclusion Proof |
Confirms that specific data exists and has not been modified |
Non-Inclusion Proof |
Confirms that specific data does not exist (useful for uniqueness checks such as usernames) |
Proofs are especially valuable for:
Light clients
Browser-based and serverless environments
Trust-minimized applications
Indexed Queries#
Dash Platform requires queries to use indexes defined in the data contract for the relevant document type. If a field is not indexed, it cannot be used for filtering or sorting.
System fields are recognized by the query engine without being declared as normal schema properties. $id is implicitly queryable as the primary key. Other system fields like $ownerId, $createdAt, $updatedAt, and $transferredAt are built-in field names, but document queries still need to match an appropriate contract index. Querying and sorting on indexed fields also follows compound-index prefix and range/orderBy rules - see the query syntax reference for details.
A query is served only when its filters line up with a leading, gap-free run of an index’s properties. Since protocol version 14, a query that skips a property in the middle of an index is rejected rather than served from a partial match. Set-membership filters can also be applied to more than one adjacent index property in a single query.
Some document types can be declared index-only in the data contract. Their documents are never stored as a body, so queries return documents reconstructed from the index entries themselves. This suits cheap relation-style rows such as likes or follows, and these types are what the chained queries described below are built on. See indexOnly document types in the data contract reference.
Benefits of indexed querying include:
Predictable performance
Consistent execution across nodes
Aggregate Queries#
Beyond returning whole documents, Dash Platform can compute a value over the set of documents a query matches - how many there are, their total, or their average - and return that instead of the documents themselves. Results can optionally be grouped, so a single query returns one value per group.
Aggregates are not available on every document type. The contract must opt in for the document type being queried, which means this is another decision to make during contract design. See the query syntax reference for the supported aggregates and how to request them.
Ranked, Windowed, and Composed Queries#
Since protocol version 14, Platform can answer several further kinds of question in a single verifiable round trip:
Which groups rank highest? Ranked queries return the top (or bottom) groups by a count, sum, or average, such as a leaderboard.
Which groups fall in a value band? Having-range queries return only the groups whose aggregate falls within a given range.
What happened in this time window? Time-range selection reads documents bucketed into fixed time windows, for trending-style views.
Which documents does this page refer to? Chained queries use the results of one query to select the documents returned by a second, and composite queries return a page of documents together with related documents or counts derived from that page.
Contract Design Considerations#
An application’s expected queries shape its data contract. Fields used for filtering and sorting need suitable indexes, while capabilities such as aggregation, ranking, time-range selection, and composed queries require additional contract declarations. These choices should be made before registering the contract because updates are limited. See the data contract reference and query syntax reference for the exact configuration and query rules.