> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sqd.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# How an archival query is served

> How Portal routes one archival query to SQD Network workers.

Clients query SQD Network through Portal. Portal translates the requested block
range into chunk queries, sends those queries to workers, and returns ordered block
records over HTTP.

```mermaid theme={"system"}
sequenceDiagram
  participant Client
  participant Portal
  participant WorkerA as Worker A
  participant WorkerB as Worker B
  Client->>Portal: POST dataset stream
  Portal->>Portal: Map block range to chunks and workers
  Portal->>WorkerA: Signed chunk query
  alt Worker A succeeds
    WorkerA-->>Portal: Query result
  else Worker A fails or times out
    Portal->>WorkerB: Retry the chunk query
    WorkerB-->>Portal: Query result
  end
  Portal->>Portal: Check, order, and encode results
  Portal-->>Client: JSON Lines block records
```

## 1. Map the range to chunks

Portal keeps an in-memory routing view built from the current assignment. For the
requested dataset and block range, it finds the archival chunks that cover the
range and the workers assigned to each chunk.

The Portal process does not store the chunks. It also does not call the smart
contracts to route each request. Contract state is refreshed in the background for
status and accounting; the query path uses the applied assignment and its in-memory
worker state.

## 2. Send work to workers

Portal can query several chunks in parallel. For each attempt it selects an assigned
worker and sends a signed query over the peer-to-peer transport.

The worker runs the query against the chunk files on its local disk. The current
worker uses the SQD query engine and Polars to read the stored tables, applies the
requested fields and filters, and produces a bounded result.

## 3. Check and order results

Portal limits result size and checks that a worker result matches the requested
range. Where result-signature verification is enabled, it verifies the worker's
signature. Results from different chunks are emitted in block order rather than in
the order that workers finish.

If a worker fails, times out, or is temporarily unavailable, Portal can retry the
chunk on a different assigned worker. If no usable worker remains, Portal returns a
defined data-unavailable or retry-exhausted error instead of inventing data.

## 4. Continue at the client

A Portal response is one resumable stream. The client uses the last returned block
to construct the next request. The shared continuation and fork-recovery rules are
covered in the [Portal API introduction](/en/portal/introduction/portal-api) and
[Blockchain forks](/en/portal/introduction/blockchain-forks).

<Info>
  Portal selects the source from the request's first block. At or below the
  archival head it uses the worker path on this page. Above the archival head it
  forwards the complete request to HotblocksDB when configured. Portal never
  combines both sources in one response. See [How real-time data is
  served](/en/network/introduction/how-real-time-data-is-served).
</Info>

## Implementation sources

* [Portal implementation and specification](https://github.com/subsquid/sqd-portal)
* [Worker query path](https://github.com/subsquid/worker-rs)
* [Network messages and transport](https://github.com/subsquid/sqd-network)

Continue with [Reliability and
monitoring](/en/network/introduction/reliability-and-monitoring) for the failure
boundaries and operator signals around this path.


## Related topics

- [How real-time data is served](/en/network/introduction/how-real-time-data-is-served.md)
- [SQD Network components](/en/network/introduction/network-components.md)
- [SQD Network](/en/network/overview.md)
- [From blocks to chunks](/en/network/introduction/blocks-to-chunks.md)
- [Solana Portal API Reference](/en/portal/solana/api.md)