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

# POST /query/aql

`POST /query/aql`

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.net/uber/apis/provide-the-restful-apis-to-interact-with-aresdb.md) · [All operations](https://skmtc.net/uber/apis/provide-the-restful-apis-to-interact-with-aresdb/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/uber/provide-the-restful-apis-to-interact-with-aresdb/revisions/d18a58e88958/schema)