Ad hoc queries
You can execute ad hoc queries with the Scanner API, which allows you to run an arbitrary query over a specified time range.
Last updated
You can execute ad hoc queries with the Scanner API, which allows you to run an arbitrary query over a specified time range.
Last updated
An ad hoc query is a search query with a start_time, an end_time, and query. It runs asynchronously in the background, and you can poll it periodically to check for results.
An ad hoc query is basically analogous to a query you make in the Search tab in Scanner.
The results of an ad hoc query are tabular, consisting of columns and rows.
There are two ways to execute an ad hoc query: asynchronous and blocking.
POST
/v1/start_query
To execute an asynchronous ad hoc query, you first create it via POST /v1/start_query
request. The Scanner API will return the id of the query, which you can use to poll its status with GET /v1/query_progress
requests.
Body
Name | Type | Description |
---|---|---|
Example
Response
When the ad hoc query has been completed successfully, the response HTTP status code will be 200
, and the result will contain the ID of the ad hoc query that was just created.
GET
/v1/query_progress/{qr_id}
Gets the current progress of the query with the supplied qr_id
.
Users are expected to run GET
requests periodically to check for query results. We recommend checking every 1 second.
Example
Response
When the query is still in progress, the response HTTP status code will be 200, and the is_completed
field will be false
:
POST
/v1/blocking_query
To execute a blocking ad hoc query, you just issue a POST /v1/blocking_query
request. The Scanner API will hold the request open until the query completes, or it will time out if the query takes longer than 60 seconds.
Body
Example
Response
When the query has completed successfully, the response HTTP status code will be 200, and the is_completed
field will be true
.
The results
field will contain information you can use to render a table of results. The columns
field is an array of the names of the columns in the results table, and the rows
field is an array of JSON objects representing the rows.
Name | Type | Description |
---|---|---|
query
required
string
Query text
start_time
required
string
Start timestamp for the query (inclusive). The format of the timestamp is RFC 3339
end_time
required
string
End timestamp for the query (exclusive). The format of the timestamp is RFC 3339
max_rows
number
Maximum number of rows to return. Default is 1000, max is 100000
scan_back_to_front
boolean
Whether to scan from back (latest) to front (earliest). Default is true
query
required
string
Query text
start_time
required
string
Start timestamp for the query (inclusive). The format of the timestamp is RFC 3339
end_time
required
string
End timestamp for the query (exclusive). The format of the timestamp is RFC 3339
max_rows
number
Maximum number of rows to return. Default is 1000, max is 100000
scan_back_to_front
boolean
Scan from back (latest) to front (earliest). Default is true