Queries on Rockset typically must complete within 2 minutes. Use `async` mode to run longer queries of up to 30 minutes.

The workflow for Async Queries:

  • Send a query request with async enabled.

  • Receive back a query ID.

  • Poll to check the status of the query, which can have the values of `QUEUED`, `RUNNING`, `COMPLETED`, `ERROR`, or `CANCELLED`.

  • Fetch results when the query completes.

Rockset does not recommend using async queries for latency sensitive workloads due to the overhead of additional network requests.

## Sending an Async Query Request

To send the request asynchronously, set the `async` parameter to true in either a [<<glossary:Query Lambda>>](🔗) or query request.

Example request:

This query request will immediately return with a query id that can be used to poll and retrieve results.

Example response:

## Polling for Query Status

After submitting an async query request, periodically retrieve the query status to find out if the query has completed.

Example request:

The response contains a status field, which has the possible values of `QUEUED`, `RUNNING`, `COMPLETED`, `ERROR`, and `CANCELLED`.

If the status of the query is `ERROR`, the error will be available in the `query_errors` field.

Example response:

When the status of the query is `COMPLETED`, you may retrieve results.

## Retrieving Query Results

Example request for 1000 documents:

The `docs` parameter is optional. If you choose not to add a `docs` parameter, the default will be 10,000 documents. The maximum value for `docs` is 100,000.

There is also an `offset` query parameter, which specifies the offset from the cursor of the first document to be returned. The maximum value for `offset` is 1,000,000,000. `offset` will default to 0 if not specified.

Example response:

If there is more than one page of results, use the `next_cursor` field returned in the response to request the next page of results. Alternatively, you can use the `offset` parameter to go back and forth between results pages.

Example request:

## Advanced Usage

### Setting a Client Timeout

To avoid the additional network requests for short queries, you can optionally set `async_options.client_timeout_ms`. If the query completes before the client timeout, the results will be returned in-band without needing to poll and retrieve results later. For example, if you want queries under 60 seconds to return results in-band, you can make this request:

Response for a query that completes before the client timeout (same as a non-async query):

Since the additional overhead to store query results is avoided when a query completes before the client timeout, the query status and query results will not be available in the `GET .../queries/{queryId}` and `GET .../queries/{queryId}/pages` APIs described below. Instead, the status and results will be returned in-band, as it is for non-async queries.

Make sure to handle both the short and long-running query cases when setting the client timeout since you will not know when the query will complete. A query that completes before the client timeout will have a status of `COMPLETED` in the initial response, while a query that continues to run after the client timeout will have a status of `QUEUED` or `RUNNING`.

Client Timeout Note

Queries with a client timeout set will return a default of 10,000 results in the initial response, with the remaining results to be retrieved through the pagination API.