Submit a DDSQL statement and return either a running state with an opaque query_id
for the client to poll, or a completed state with the column-major result set inlined
when the query finishes quickly enough to be served synchronously.
For a scoped application key, include timeseries_query in its scopes.
A query that does not read a data source, such as SELECT 1, requires no additional
data-source permissions. Queries that read data sources also require the user or
service account that owns the application key to have the corresponding data access
permissions through their roles. The timeseries_query permission does not grant
access to the underlying data sources.
This endpoint requires the timeseries_query permission.
OAuth apps require the timeseries_query authorization scope to access this endpoint.
JSON:API resource object for a DDSQL tabular query execution request.
attributes [required]
object
Attributes describing the DDSQL query to execute.
query [required]
string
The DDSQL statement to execute. DDSQL is Datadog's SQL dialect, which is a subset
of PostgreSQL, scoped to Datadog data sources.
row_limit
int64
Cap on the number of rows returned. Defaults to 5,000 when omitted. Must be
between 1 and 10,000 inclusive; values outside this range are rejected with 400.
time [required]
object
Time window scoping the underlying data sources, expressed in Unix milliseconds
since the epoch. Inclusive on from_timestamp, exclusive on to_timestamp.
Results from static tables (for example, dd.hosts) are not affected by the
time window, but the field must still be provided.
from_timestamp [required]
int64
Start of the query window (inclusive), in Unix milliseconds since the epoch.
to_timestamp [required]
int64
End of the query window (exclusive), in Unix milliseconds since the epoch.
type [required]
enum
JSON:API resource type for a DDSQL tabular query request.
Allowed enum values: ddsql_query_request
default: ddsql_query_request
{"data":{"attributes":{"query":"SELECT cloud_provider, count(*) FROM dd.hosts group by cloud_provider","row_limit":1000,"time":{"from_timestamp":1736942400000,"to_timestamp":1736946000000}},"type":"ddsql_query_request"}}
Response envelope for both the execute and fetch DDSQL tabular query endpoints.
Carries the JSON:API primary resource and a top-level meta block with
request-scoped observability handles.
Expand All
フィールド
タイプ
説明
data [required]
object
JSON:API resource object for a DDSQL tabular query response.
attributes [required]
object
Attributes of a DDSQL tabular query response. query_id is set when
state is running; columns is set when state is completed.
columns
[object]
Column-major result set. Each element carries one column's name, type, and values,
with one value per row of the result. Set when state is completed.
name [required]
string
Name of the column as projected by the SQL statement.
type [required]
string
DDSQL data type of the column's values, for example VARCHAR, BIGINT,
DECIMAL, BOOLEAN, TIMESTAMP, JSON, or an array variant such as
VARCHAR[]. See the
DDSQL data-types reference
for the full, up-to-date list.
values [required]
[]
Column values in row order, one entry per result row. The element type
follows the column's type. The following serialization rules should be
taken into account:
BIGINT values are encoded as JSON numbers in the signed 64-bit integer range.
DECIMAL values are encoded as JSON numbers with 64-bit double precision.
TIMESTAMP and DATE values are encoded as Unix-millisecond integers; a
DATE resolves to midnight UTC.
JSON values are returned as a JSON-encoded string.
null is allowed for any column type where a value is missing.
query_id
string
Opaque token to pass to the fetch endpoint to poll for results.
Set when state is running and absent when state is completed.
state [required]
enum
Lifecycle state of a DDSQL tabular query response.
running means the query is still executing and the client should poll
the fetch endpoint with the returned query_id. completed means the
result set is inlined in columns and no further polling is required.
Allowed enum values: running,completed
warnings
[string]
Non-fatal messages emitted by the query engine while serving this response.
id [required]
string
Stable identifier for the query response resource.
type [required]
enum
JSON:API resource type for a DDSQL tabular query response.
Allowed enum values: ddsql_query_response
default: ddsql_query_response
meta [required]
object
Top-level JSON:API meta block accompanying every DDSQL tabular query response.
Carries standard observability handles for client-side correlation.
elapsed [required]
int64
Server-side time spent serving this request, in milliseconds.
request_id [required]
string
Echo of the DD-Request-ID header assigned by Datadog's edge to this request,
for support correlation.
{"data":{"attributes":{"columns":[{"name":"service","type":"VARCHAR","values":["web-store","checkout"]}],"query_id":"eyJxdWVyeSI6ICJTRUxFQ1QgKiBGUk9NIGxvZ3MifQ==","state":"completed","warnings":["Query result was truncated at the configured row_limit."]},"id":"00000000-0000-0000-0000-000000000000","type":"ddsql_query_response"},"meta":{"elapsed":87,"request_id":"req-7f3e7d2c-1a0b-4d3e-9b2a-3c4d5e6f7082"}}
