Datasets and query arguments
Look up the datasets each GraphQL API endpoint serves and the filter, sort, pagination, and resample arguments a query accepts.
A dataset is the set of records a GraphQL API query reads, named as the top-level field of the query. Each of the five endpoints serves its own datasets. Every dataset takes the same arguments to filter, aggregate, group, sort, and page through its records, and most metrics datasets also take resample.
Datasets
The table lists the datasets of each endpoint. The Endpoint column names the URL segment: a metrics dataset goes to https://api.azion.com/v4/metrics/graphql, and the same pattern holds for events, billing, accounting, and consumption. Send each query in a POST request with the header Authorization: Token [TOKEN VALUE]:
| Dataset | Endpoint | Data |
|---|---|---|
workloadMetrics | metrics | Requests that Applications and Firewall handled, aggregated into time buckets |
workloadBreakdownMetrics | metrics | Requests by client address, path, user agent, referer, and country, aggregated by hour, with counts of blocked and threat requests |
functionsMetrics | metrics | Invocations and compute time of Functions |
dnsQueriesMetrics | metrics | Queries that Edge DNS answered, by zone and record type |
idnsQueriesMetrics | metrics | The same rows as dnsQueriesMetrics |
imagesProcessedMetrics | metrics | Images that Image Processor processed |
tieredCacheMetrics | metrics | Requests that Tiered Cache handled |
l2CacheMetrics | metrics | The same fields as tieredCacheMetrics |
dataStreamedMetrics | metrics | Data that Data Stream sent to your endpoints |
connectedUsersMetrics | metrics | Users connected to your applications through Live Ingest, by minute |
botManagerMetrics | metrics | Requests that Bot Manager evaluated and the actions it took; requires a Bot Manager subscription |
botManagerBreakdownMetrics | metrics | The URLs that bad bots request most, from Bot Manager data; requires a Bot Manager subscription |
workloadEvents | events | One record per request that Applications and Firewall handled |
functionEvents | events | One record per execution of Functions |
functionConsoleEvents | events | Lines that functions running on Azion Runtime write to the console, with their level |
dnsQueriesEvents | events | One record per query that Edge DNS answered, with its response code |
idnsQueriesEvents | events | The same fields as dnsQueriesEvents |
imagesProcessedEvents | events | One record per image that Image Processor processed |
tieredCacheEvents | events | One record per request that Tiered Cache handled |
l2CacheEvents | events | The same fields as tieredCacheEvents |
dataStreamedEvents | events | Deliveries that Data Stream sent to your endpoints, with the endpoint URL and status code |
activityHistoryEvents | events | Account activity in Azion Console, as Activity History records it; kept for 2 years |
telemetryDeviceInfoEvents | events | Hardware and software details of the devices that Azion Mobile SDK records |
telemetrySensorsEvents | events | Device sensor readings that Azion Mobile SDK records, such as touchscreen and gyroscope data |
balanceFinancialEntry | billing | Financial entries by type, with their amounts |
paymentsClientDebt | billing | Debts and payments of the account, with their amounts |
billDetail | billing | Billed amounts per product, metric, and region for each billing period |
accountingDetail | accounting | Accounted amounts per product, metric, and region |
workloadConsumptionMetrics | consumption | Accounted usage per workload, product, and metric |
Datasets on the events endpoint return raw records, one per event, as Raw data shows. Datasets on the metrics endpoint return data grouped into time buckets, as Aggregated data shows.
The fields of each dataset are on Real-Time Metrics fields, Real-Time Events fields, Billing fields, Accounting fields, and Consumption fields. An introspection query returns the same information from the endpoint itself: every dataset and field it serves, with their descriptions and types. For more information, refer to Query metadata.
Deprecated datasets
The schema marks the dataset names below as deprecated. A deprecated dataset takes the same fields as its replacement and returns the same rows, so moving a query to the replacement changes only the dataset name:
| Deprecated dataset | Use instead |
|---|---|
httpMetrics | workloadMetrics |
httpBreakdownMetrics | workloadBreakdownMetrics |
edgeFunctionsMetrics | functionsMetrics |
edgeDnsQueriesMetrics | dnsQueriesMetrics |
httpEvents | workloadEvents |
edgeFunctionsEvents | functionEvents |
cellsConsoleEvents | functionConsoleEvents |
edgeDnsQueriesEvents | dnsQueriesEvents |
Query arguments
Every GraphQL API dataset, on every endpoint, takes the first six arguments below, and resample applies to metrics datasets only. All of them are optional, but a query on a metrics, events, or consumption dataset needs a time window inside filter:
| Argument | Type | Default | What it does |
|---|---|---|---|
filter | Input object | — | Selects the records to read: the time window and any field conditions. |
aggregate | Input object | — | Applies functions, such as count or sum, to a field. |
groupBy | List of fields | — | Returns one row per combination of the listed fields. |
orderBy | List of sort keys | — | Sorts the rows by fields or function outputs. |
offset | Int | 0 | Sets how many rows the API skips before the first row it returns. |
limit | Int | 10 | Sets how many rows the API returns, from 0 to 10,000. |
resample | Input object | — | Combines the rows into a set number of time points. metrics datasets only. |
The aggregate functions, and what groupBy does with them, are on Queries.
Filtering
The filter argument selects the records a GraphQL API query reads, and it accepts any field of the dataset. Each key names a field and, through a suffix, an operator: statusGte: 400 keeps the records whose status is 400 or higher. A key with no suffix compares for equality, so host: "www.example.com" and hostEq: "www.example.com" return the same records.
This query returns the time buckets of a seven-day window that hold requests from Brazil:
The response holds 10 rows, cut here after the third:
Operators
The operators a field takes depend on its type. A string field holds text, such as host. A numeric field holds a raw value, such as status or requestTime. A computed field holds a value the API calculates, such as requestsTotal or dataTransferredTotal:
| Operator | Matches | Applies to | Example |
|---|---|---|---|
Eq | Values equal to the given value | String, numeric, computed, and ts fields | hostEq: "www.example.com" |
Ne | Values different from the given value | String, numeric, computed, and ts fields | hostNe: "www.example.com" |
Like | Values that match a pattern, case-sensitive | String fields | hostLike: "%example%" |
Ilike | Values that match a pattern, case-insensitive | String fields | hostIlike: "%EXAMPLE%" |
In | Values in a list | String, numeric, and ts fields, and some computed fields | statusIn: [403, 404] |
NotIn | Values outside a list | String, numeric, and ts fields | statusNotIn: [200, 304] |
IsNull | Empty values with true, present values with false | String and numeric fields | hostIsNull: false |
Lt | Values less than the given value | Numeric, computed, and ts fields | statusLt: 300 |
Lte | Values less than or equal to the given value | Numeric and ts fields | statusLte: 300 |
Gt | Values greater than the given value | Numeric, computed, and ts fields | statusGt: 399 |
Gte | Values greater than or equal to the given value | Numeric and ts fields | statusGte: 400 |
Range | Values between begin and end | Numeric, computed, and ts fields | statusRange: {begin: 400, end: 499} |
An operator a field does not take returns 400. For example, requestsTotalLte on workloadMetrics returns Unknown field., because computed fields take no Lte or Gte.
A Like or Ilike pattern uses % for any run of characters. "Braz%" matches values that start with Braz, "%ao Paulo" matches values that end with ao Paulo, and "%ttp%" matches values that contain ttp. The case of the pattern matters only with Like: hostLike: "%EXAMPLE%" does not match www.example.com, and hostIlike: "%EXAMPLE%" does.
Datasets on the billing and accounting endpoints have no ts field. Their filters take the bare field, Eq, In, and Range, on fields such as periodFrom, periodTo, and created.
Combined conditions
The keys inside one filter object all apply together. To combine conditions explicitly, and and or take a list of filters, and not takes one filter:
andkeeps the records that match every filter in the list, such asand: [{ hostEq: "www.example.com" }, { statusGte: 400 }].orkeeps the records that match at least one filter in the list.notexcludes the records that match its filter, such asnot: { requestUriLike: "%/_astro/%" }.
This query counts the requests of a seven-day window whose status is 304 or falls between 200 and 299, by status:
The response is cut after the third row:
The schema types or as a list. The API also accepts or as a single object, such as or: { status: 304, statusRange: {begin: 200, end: 299} }, and treats its keys as alternatives.
Time window
A query on a metrics, events, or consumption dataset sets its time window inside filter. tsRange takes a begin and an end. tsGt and tsLt set one bound each, and tsGt alone is accepted. Without any of them, the API returns 400 with To execute queries it is mandatory to provide the desired time interval.
The two bounds of a window use the same timezone. A bound with Z next to a bound without it returns 400 with The start and end dates must have the same timezone. Bounds with the same offset, such as -03:00, are accepted, and the API converts them to UTC. A window whose begin comes after its end returns an empty list.
This query sums the requests of a one-hour window per time bucket, with tsGt and tsLt:
The response holds only the buckets of the window that hold requests:
The billing and accounting datasets filter by period instead, as Queries shows.
Sorting
The orderBy argument sorts the rows a GraphQL API query returns. It takes a list of keys, and each key is a field or a function output followed by _ASC, lowest first, or _DESC, highest first. For example, orderBy: [avg_ASC] puts the lowest average first. A query can list several keys, such as orderBy: [ts_ASC, requestId_ASC].
A key without a direction returns 400. For orderBy: [host] on workloadMetrics, the message ends with Expected type "WorkloadMetricsOrderByFields", found host.
This query sums the bytes sent per host over a seven-day window, highest first:
The response is cut after the third row:
Pagination
The offset and limit arguments page through the rows of a GraphQL API query. offset sets how many rows the API skips, 0 by default. limit sets how many rows it returns, 10 by default and at most 10,000. For example, offset: 15 with limit: 30 returns rows 16 to 45. A limit outside 0 to 10,000 returns 400, as GraphQL API limits describes.
This query returns rows 6 to 10 of the requests in a 24-hour window, sorted by time and then by request ID:
The response holds five rows, cut here after the third:
The same query with limit: 10 and no offset returns rows 1 to 10, and its last five rows are the five rows above. An offset past the last row returns an empty list.
Each page is a separate query. When the data changes between two queries, rows can shift from one page to the next, so a page can miss a row or repeat one. The query above sorts by ts and then by requestId, so rows with the same timestamp come back in the same order on every page.
Resampling
The resample argument combines the rows of a metrics dataset into fewer time points, to fit a chart. It complements limit: limit caps the rows, and resample sets how many points the time window is split into. It takes two keys:
function, required, sets how the points inside each interval combine.points, anInt, sets the number of intervals to aim for.
function takes one of four values:
sumreturns the total of the points in the interval.meanreturns their average.maxreturns the largest point.minreturns the smallest point.
Every metrics dataset takes resample except connectedUsersMetrics and objectStorageMetrics. On an events dataset, the argument returns 400 with Unknown argument "resample" on field "workloadEvents" of type "Query". A resampled query also needs ts in groupBy, with every groupBy field selected. Without them, the API returns 400 with a message that starts Query syntax error. In resample queries, you must provide the timestamp (ts) field in the group_by parameter.
The API divides the time window by points and rounds the interval down to a whole number of time buckets, so the response can hold more points than points. For example, a seven-day window with points: 10 returns 11 points, 16 hours apart, because 168 hours divided by 10 is 16.8 hours. An interval with no data still returns a point, with a value of zero. With points: 100, the same window returns one point per hour, empty hours included, while the same query without resample returns only the hours that hold data.
This query averages the hourly request counts of a seven-day window into about ten points:
The response holds 11 rows, 16 hours apart, cut here after the third: