---
title: "POST /query/aql"
method: POST
path: "/query/aql"
---

# POST /query/aql

`POST /query/aql`

## Request

- Base URL: `/` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/query/aql`
- Auth: none declared
- TypeScript: <https://skmtc.dev/uber/apis/provide-the-restful-apis-to-interact-with-aresdb/docs/query/aql/post.ts> (a function with typed inputs; its response is checked against the schema)

query in AQL

## Query parameters

- `device` integer
- `verbose` integer
- `debug` integer
- `profiling` string
- `q` string
- `timeout` integer

## Headers

- `accept` string
- `origin` string

## Request body

- AQLRequest
  - `queries` AQLQuery[]
    - `dimensions` Dimension[]: Dimensions to group by on.
      - `numericBucketizer` NumericBucketizerDef: NumericBucketizerDef defines how numbers should be bucketized before being grouped by as a dimension. The returned dimension is a string in the format of `lower_bound`, representing `[lower_bound, uper_bound)`.
        - `bucketWidth` number, double: Generates equal-width buckets. BucketWidth should be positive. The generated buckets are: ... [-2w, -w), [-w, 0), [0, w), [w, 2w) ...
        - `logBase` number, double: Generates exponential/log buckets. LogBase should be positive. The generated buckets are: ... [pow(b, -2), pow(b, -1)), [pow(b, -1), 1), [1, pow(b, 1)), [pow(b, 1), pow(b, 2)) ...
        - `manualPartitions` number[]: Generates a fixed number of buckets using the specified partitions. The numbers should be in sorted order. The generated buckets are: [-inf, p0), [p0, p1), [p1, p2), ... [pn-1, inf)
      - `sqlExpression` string: The SQL expression for computing the dimension. Expr can be empty when TimeBucketizer is specified, which implies the designated time column from the main table is used as the expresssion.
      - `timeBucketizer` string: Decides how to bucketize a timestamp Dimension before grouping by. See https://github.com/uber/aresdb/wiki/aql#time_bucketizer
      - `timeUnit` string
    - `joins` Join[]: Foreign tables to be joined.
      - `alias` string: Alias for the table. Empty means the table name will be used as alias.
      - `conditions` string[]: Condition expressions to be ANDed together for the join.
      - `table` string: Name of the table to join against.
    - `measures` Measure[]: Measures/metrics to report.
      - `rowFilters` string[]: Row level filters to apply for this measure. The filters are ANDed togther.
      - `sqlExpression` string: The SQL expression for computing the measure.
    - `now` integer: This overrides "now" (in seconds)
    - `rowFilters` string[]: Row level filters to apply for all measures. The filters are ANDed togther.
    - `table` string: Name of the main table.
    - `timeFilter` TimeFilter
      - `column` string: A table time column in the format of column, or table_alias.column. When empty, it defaults to the designated time column of the main table.
      - `from` string: The time specified in from and to are both inclusive. See https://github.com/uber/aresdb/wiki/aql#time_filter
      - `to` string
    - `timezone` string: Timezone to use when converting timestamp to calendar time, specified as: 8:00 GMT America/Los_Angeles timezone(city_id) region_timezone(city_id) mega_region_timezone(city_id) sub_region_timezone(city_id) country_timezone(city_id)

## Response `200`

AQLResponse represents queryAQL response.

- AQLResponse
  - `context` AQLQueryContext[]
    - `ReturnHLLData` boolean: whether to serialize the query result as HLLData. If ReturnHLLData is true, we will not release dimension vector and measure vector until serialization is done.
    - `debug` boolean
    - `device` integer
    - `error` string
    - `oopk` OOPKContext: OOPKContext defines additional query context for one-operator-per-kernel execution.
      - `aggregate` integer
      - `archiveStats` OopkQueryStats
        - `batches` integer: Total number of batches.
        - `latency` number, double: Total timing for all query stages **including transfer**.
        - `numBatchSkipped` integer: For archive batch, we skip process empty batch. For live batch, we will skip it if its min or max value does not pass main table filters or time filters.
        - `records` integer: Total number of records processed on GPU. A record could represent multiple data record if firstColumn is compressed.
        - `stages` unknown
        - `tranBytes` integer: Stats for input data transferred via PCIe.
        - `tranCalls` integer
      - `deviceMem` integer: For reporting purpose only.
      - `dimRowBytes` integer: Dim row bytes is the sum number of bytes of all dimension values plus validity bytes, for memory allocation convenience
      - `dimensionVectorIndex` integer[]: Index of single dimension vector in global dimension vector Following sorted order based on bytes
      - `dimensions` Expr[]: Compiled and annotated ASTs for dimensions and measure.
        - `String` string
        - `Type` integer: Expression types are determined at query compilation time, type castings are generated when apprioperiate. Notice that word widths are not specified here.
      - `durationWaitedForDevice` integer: A Duration represents the elapsed time between two instants as an int64 nanosecond count. The representation limits the largest representable duration to approximately 290 years.
      - `foreignTableCommonFilters` Expr[]: ForeignTableCommonFilters match filters with foreign table columns involved
        - `String` string
        - `Type` integer: Expression types are determined at query compilation time, type castings are generated when apprioperiate. Notice that word widths are not specified here.
      - `liveStats` OopkQueryStats
        - `batches` integer: Total number of batches.
        - `latency` number, double: Total timing for all query stages **including transfer**.
        - `numBatchSkipped` integer: For archive batch, we skip process empty batch. For live batch, we will skip it if its min or max value does not pass main table filters or time filters.
        - `records` integer: Total number of records processed on GPU. A record could represent multiple data record if firstColumn is compressed.
        - `stages` unknown
        - `tranBytes` integer: Stats for input data transferred via PCIe.
        - `tranCalls` integer
      - `mainTableCommonFilters` Expr[]: Filters that apply to all archive and live batches. MainTableCommonFilters match filters with only main table columns involved
        - `String` string
        - `Type` integer: Expression types are determined at query compilation time, type castings are generated when apprioperiate. Notice that word widths are not specified here.
      - `measure` Expr
        - `String` string
        - `Type` integer: Expression types are determined at query compilation time, type castings are generated when apprioperiate. Notice that word widths are not specified here.
      - `measureBytes` integer
      - `numDims` integer[]: DimCountsPerDimWidth defines dimension counts per dimension width 16-byte 8-byte 4-byte 2-byte 1-byte
      - `prefilters` Expr[]: Prefilters that only apply to live batches. Archiving cutoff filtering is processed directly by the query engine and not included here (different shards may have different cutoffs).
        - `String` string
        - `Type` integer: Expression types are determined at query compilation time, type castings are generated when apprioperiate. Notice that word widths are not specified here.
      - `resultSize` integer
      - `timeFilters` Expr[]: Lower bound [0] and upper bound [1] time filter. nil if not applicable. [0] should be applied to the first archive batch and all live batches. [1] should be applied to the last archive batch and all live batches.
        - `String` string
        - `Type` integer: Expression types are determined at query compilation time, type castings are generated when apprioperiate. Notice that word widths are not specified here.
    - `prefilters` integer[]: Index to filters in Query.Filters that are identified as prefilters.
    - `profiling` string
    - `query` AQLQuery
      - `dimensions` Dimension[]: Dimensions to group by on.
        - `numericBucketizer` NumericBucketizerDef: NumericBucketizerDef defines how numbers should be bucketized before being grouped by as a dimension. The returned dimension is a string in the format of `lower_bound`, representing `[lower_bound, uper_bound)`.
          - `bucketWidth` number, double: Generates equal-width buckets. BucketWidth should be positive. The generated buckets are: ... [-2w, -w), [-w, 0), [0, w), [w, 2w) ...
          - `logBase` number, double: Generates exponential/log buckets. LogBase should be positive. The generated buckets are: ... [pow(b, -2), pow(b, -1)), [pow(b, -1), 1), [1, pow(b, 1)), [pow(b, 1), pow(b, 2)) ...
          - `manualPartitions` number[]: Generates a fixed number of buckets using the specified partitions. The numbers should be in sorted order. The generated buckets are: [-inf, p0), [p0, p1), [p1, p2), ... [pn-1, inf)
        - `sqlExpression` string: The SQL expression for computing the dimension. Expr can be empty when TimeBucketizer is specified, which implies the designated time column from the main table is used as the expresssion.
        - `timeBucketizer` string: Decides how to bucketize a timestamp Dimension before grouping by. See https://github.com/uber/aresdb/wiki/aql#time_bucketizer
        - `timeUnit` string
      - `joins` Join[]: Foreign tables to be joined.
        - `alias` string: Alias for the table. Empty means the table name will be used as alias.
        - `conditions` string[]: Condition expressions to be ANDed together for the join.
        - `table` string: Name of the table to join against.
      - `measures` Measure[]: Measures/metrics to report.
        - `rowFilters` string[]: Row level filters to apply for this measure. The filters are ANDed togther.
        - `sqlExpression` string: The SQL expression for computing the measure.
      - `now` integer: This overrides "now" (in seconds)
      - `rowFilters` string[]: Row level filters to apply for all measures. The filters are ANDed togther.
      - `table` string: Name of the main table.
      - `timeFilter` TimeFilter
        - `column` string: A table time column in the format of column, or table_alias.column. When empty, it defaults to the designated time column of the main table.
        - `from` string: The time specified in from and to are both inclusive. See https://github.com/uber/aresdb/wiki/aql#time_filter
        - `to` string
      - `timezone` string: Timezone to use when converting timestamp to calendar time, specified as: 8:00 GMT America/Los_Angeles timezone(city_id) region_timezone(city_id) mega_region_timezone(city_id) sub_region_timezone(city_id) country_timezone(city_id)
    - `scanners` TableScanner[]: Scanner for all tables. [0] for the main table; [1:] for tables in joins.
      - `archiveBatchIDEnd` integer
      - `archiveBatchIDStart` integer: Range of archive batches to process: [Start, end). Depending on the archiving progress of each shard, live batches may be skipped for processing if the archiving cutoff is after the time of ArchiveBatchIDEnd.
      - `columnUsage` unknown
      - `columns` integer[]: IDs of columns to be used in this query, in the following order: 1. Columns not from ArchivingSortColumns. 2. Columns from ArchivingSortColumns in reverse order.
      - `equalityPrefilterValues` integer[]: Values of equality prefilters in order. Each 4 bytes of the uint32 is used to store any data type other than UUID (not supported).
      - `rangePrefilterBoundaries` BoundaryType[]: Boundary types and values of the final range prefilter.
      - `rangePrefilterValues` integer[]
      - `shards` integer[]: IDS of all table shards to be scanned on this instance.
    - `tableIDs` object: Map from table alias to ID (index to TableScanners).
  - `errors` string[]
  - `results` AQLTimeSeriesResult[]

## Other responses

- `400`: AQLResponse represents queryAQL response.
- `default`: ErrorResponse represents error response.

---

[API](https://skmtc.dev/uber/apis/provide-the-restful-apis-to-interact-with-aresdb.md) - [All operations](https://skmtc.dev/uber/apis/provide-the-restful-apis-to-interact-with-aresdb/llms.txt) - [OpenAPI document](https://skmtc.dev/uber/apis/provide-the-restful-apis-to-interact-with-aresdb/revisions/d18a58e88958?raw)