Skip to content
OnchainQueries

Results

Results & verification

Every completed query produces numbered parts and a manifest. The manifest is written last, so its presence means the download finished — and every part is checksummed before it gets its final name.

What you get back

./results
results/├── part-00000.parquet├── part-00001.parquet└── manifest.json

A query can produce more than one numbered part. Completed results include:

  • numbered Parquet or Arrow parts
  • output column names, types and nullability
  • physical source-table coverage
  • catalog hash and high-watermark slot
  • row count, byte size and SHA-256 for each part
  • expiration time

How verification works

The CLI downloads each part to a .partial file, verifies its size and checksum, then atomically renames it. Rerun against the same output directory and any part already matching the manifest is reused rather than re-downloaded. Local files remain available after the server-side result expires.

Consistency

OnchainQueries records the source catalog hash and high-watermark slot used to plan a query, and fingerprints source partitions before and after execution. If the catalog or relevant partitions change during execution, OnchainQueries retries the affected work rather than publishing a mixed result — a result never spans two versions of the source.

When dataset coverage matters, read the manifest’s source_coverage.tables field. It lists the physical tables the query actually read.

Arrow Flight

--transport flight stores an Arrow IPC stream and returns a signed flight_ticket in the manifest. Arrow clients pass the decoded ticket as a command descriptor to GetFlightInfo and retrieve batches with DoGet on port 8091.

shell
query sql \  --file query.sql \  --transport flight \  --output ./arrow-results

Expiry

Results expire 24 hours after query submission. Attach before the reported expires_at:

shell
query attach QUERY_ID --output ./results

Attaching to an already complete query downloads it immediately. Attaching to a failed, cancelled or expired query returns an error rather than downloading. Once a server-side result expires the SQL must be submitted again — but anything you already downloaded is untouched.

Query IDs

Keep the query ID if you may need to inspect, resume or cancel later. query status QUERY_ID prints the full record as JSON, including the requested and selected engines, transport, current state, attempt number, timestamps, any error, and the manifest when available.