```{eval-rst}
.. _explanations-query:
```

# 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](../reference/query-syntax.md) for details.

Benefits of indexed querying include:

- Predictable performance
- Consistent execution across nodes

:::{important}
Indexes should be planned during contract design since there are [limited index update
options](./platform-protocol-data-contract.md#updates) for already registered contracts.
:::

## 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](../reference/query-syntax.md#aggregate-queries) for the supported aggregates
and how to request them.