> ## Documentation Index
> Fetch the complete documentation index at: https://axiom.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.
## Submitting Feedback
If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:
POST https://axiom.co/docs/feedback
```json
{
"path": "/restapi/endpoints/queryDataset",
"feedback": "Description of the issue"
}
```
Only submit feedback when you have something specific and actionable to report.
# Run query (legacy)
> Query (Legacy)
## OpenAPI
````yaml v1 post /datasets/{dataset_name}/query
openapi: 3.0.1
info:
title: Axiom Public API
description: A public and stable API for interacting with Axiom services
termsOfService: http://axiom.co/terms
contact:
name: Axiom support team
url: https://axiom.co
email: hello@axiom.co
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.0
servers:
- url: https://api.axiom.co/v1/
security:
- Auth: []
paths:
/datasets/{dataset_name}/query:
post:
tags:
- Datasets
description: Query (Legacy)
operationId: queryDataset
parameters:
- name: saveAsKind
in: query
schema:
type: string
- name: dataset_name
in: path
description: Unique name of the dataset.
required: true
schema:
type: string
- name: streaming-duration
in: query
schema:
type: string
- name: nocache
in: query
schema:
type: boolean
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/QueryRequestWithOptions'
required: true
responses:
'200':
description: Result
headers:
X-QueryLimit-Limit:
schema:
type: integer
X-QueryLimit-Remaining:
schema:
type: integer
X-QueryLimit-Reset:
schema:
type: integer
X-Axiom-History-Query-Id:
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Result'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
security:
- Auth:
- CanQuery
components:
schemas:
QueryRequestWithOptions:
required:
- endTime
- resolution
- startTime
type: object
properties:
aggregations:
type: array
items:
$ref: '#/components/schemas/Aggregation'
continuationToken:
type: string
cursor:
type: string
description: >-
A cursor for use in pagination. Use the cursor string returned in
previous responses to fetch the next or previous page of results.
endTime:
type: string
filter:
$ref: '#/components/schemas/Filter'
groupBy:
type: array
items:
type: string
includeCursor:
type: boolean
description: >-
Specifies whether to include the row identified by the `cursor` in
the results. Default is false.
limit:
type: integer
format: uint32
description: >-
Specifies the maximum number of events to return. Default is 1000,
minimum is 0, maximum is 50000.
order:
type: array
items:
$ref: '#/components/schemas/Order'
project:
type: array
items:
$ref: '#/components/schemas/Projection'
queryOptions:
$ref: '#/components/schemas/QueryOptions'
resolution:
type: string
description: >-
The time resolution of the query’s graph, in seconds. Valid values
are
the query’s time range /100 at maximum and /1000 at minimum or
"auto".
startTime:
type: string
description: >-
start and end time for the query, these must be specified as RFC3339
strings
or using relative time expressions (e.g. now-1h, now-1d, now-1w,
etc)
virtualFields:
type: array
items:
$ref: '#/components/schemas/VirtualColumn'
example:
aggregations: []
continuationToken: string
cursor: string
endTime: string
filter: {}
groupBy:
- string
includeCursor: true
limit: 10
order:
- desc: true
field: string
project:
- alias: string
field: string
queryOptions:
displayNull: '0'
resolution: string
startTime: string
Result:
required:
- buckets
- format
- status
type: object
properties:
buckets:
$ref: '#/components/schemas/Timeseries'
fieldsMeta:
type: array
description: >-
FieldsMeta contains the unit information (if we have it) for each
field
items:
$ref: '#/components/schemas/DatasetField'
x-go-name: FieldsMeta
format:
type: string
description: >-
Format specifies the result set format. Either "legacy" (default) or
"tabular".
x-go-name: Format
matches:
type: array
description: >-
Matches hold the matching events of a filter query in the "legacy"
result format
items:
$ref: '#/components/schemas/Entry'
x-go-name: Matches
status:
$ref: '#/components/schemas/Status'
tables:
type: array
description: Tables hold the result tables in the "tabular" result format
items:
$ref: '#/components/schemas/Table'
x-go-name: Tables
example:
buckets:
series:
- endTime: '2022-07-26T03:00:48.925Z'
groups:
- aggregations:
- op: string
value: {}
group:
additionalProp1: {}
additionalProp2: {}
additionalProp3: {}
id: 0
startTime: '2022-07-26T03:00:48.925Z'
totals:
- aggregations:
- op: string
value: {}
group:
additionalProp1: {}
additionalProp2: {}
additionalProp3: {}
id: 0
fieldsMeta:
- description: string
hidden: true
name: string
type: string
unit: string
matches:
- _rowId: string
_sysTime: '2022-07-26T03:00:48.925Z'
_time: '2022-07-26T03:00:48.925Z'
data:
additionalProp1: {}
additionalProp2: {}
additionalProp3: {}
status:
blocksExamined: 0
cacheStatus: 0
continuationToken: string
elapsedTime: 0
isEstimate: true
isPartial: true
maxBlockTime: '2022-07-26T03:00:48.925Z'
messages:
- code: string
count: 0
msg: string
priority: string
minBlockTime: '2022-07-26T03:00:48.925Z'
numGroups: 0
rowsExamined: 0
rowsMatched: 0
x-go-type:
hints:
noValidation: true
import:
alias: dbdatasets
package: github.com/axiomhq/axiom/pkg/db/client/swagger/datasets
type: Result
ForbiddenError:
type: object
properties:
code:
type: string
message:
type: string
example:
code: 403
message: Forbidden
Aggregation:
required:
- field
- op
type: object
properties:
alias:
type: string
x-go-name: Alias
argument:
type: object
properties: {}
x-go-name: Argument
field:
type: string
x-go-name: Field
op:
type: string
enum:
- count
- distinct
- sum
- avg
- min
- max
- topk
- percentiles
- histogram
- stdev
- variance
- argmin
- argmax
- makeset
- rate
- makelist
x-go-name: Op
x-go-type:
hints:
noValidation: true
import:
alias: dbdatasets
package: github.com/axiomhq/axiom/pkg/db/client/swagger/datasets
type: Aggregation
Filter:
required:
- field
- op
type: object
properties:
caseSensitive:
type: boolean
description: >-
Supported for these filters: starts-with, not-starts-with,
ends-with, not-ends-with, contains, not-contains, eq, ne.
x-go-name: CaseSensitive
children:
type: array
description: 'Supported for these filters: and, or, not.'
items:
type: string
x-go-name: Children
field:
type: string
x-go-name: Field
op:
type: string
description: >-
We also support '==', but we’re not exporting that to swagger,
because it can’t deal with it add >, >=, <, <= to that list, it
breaks codegen.
enum:
- and
- or
- not
- eq
- '!='
- ne
- exists
- not-exists
- gt
- gte
- lt
- lte
- starts-with
- not-starts-with
- ends-with
- not-ends-with
- contains
- not-contains
- regexp
- not-regexp
x-go-name: Op
value:
type: object
properties: {}
x-go-name: Value
x-go-type:
hints:
noValidation: true
import:
alias: dbdatasets
package: github.com/axiomhq/axiom/pkg/db/client/swagger/datasets
type: Filter
Order:
required:
- desc
- field
type: object
properties:
desc:
type: boolean
x-go-name: Desc
field:
type: string
x-go-name: Field
x-go-type:
hints:
noValidation: true
import:
alias: dbdatasets
package: github.com/axiomhq/axiom/pkg/db/client/swagger/datasets
type: Order
Projection:
required:
- field
type: object
properties:
alias:
type: string
x-go-name: Alias
field:
type: string
x-go-name: Field
x-go-type:
hints:
noValidation: true
import:
alias: dbdatasets
package: github.com/axiomhq/axiom/pkg/db/client/swagger/datasets
type: Projection
QueryOptions:
type: object
properties:
against:
type: string
againstStart:
type: string
againstTimestamp:
type: string
aggChartOpts:
type: string
caseSensitive:
type: string
containsTimeFilter:
type: string
datasets:
type: string
displayNull:
type: string
editorContent:
type: string
endColumn:
type: string
endLineNumber:
type: string
endTime:
type: string
integrationsFilter:
type: string
openIntervals:
type: string
quickRange:
type: string
resolution:
type: string
shownColumns:
type: string
startColumn:
type: string
startLineNumber:
type: string
startTime:
type: string
timeSeriesVariant:
type: string
timeSeriesView:
type: string
VirtualColumn:
required:
- alias
- expr
type: object
properties:
alias:
type: string
x-go-name: Alias
expr:
type: string
x-go-name: Expr
x-go-type:
hints:
noValidation: true
import:
alias: dbdatasets
package: github.com/axiomhq/axiom/pkg/db/client/swagger/datasets
type: VirtualColumn
Timeseries:
type: object
properties:
series:
type: array
items:
$ref: '#/components/schemas/Interval'
x-go-name: Series
totals:
type: array
items:
$ref: '#/components/schemas/EntryGroup'
x-go-name: Totals
x-go-type:
hints:
noValidation: true
import:
alias: dbdatasets
package: github.com/axiomhq/axiom/pkg/db/client/swagger/datasets
type: Timeseries
DatasetField:
required:
- hidden
- name
- type
- unit
type: object
properties:
description:
type: string
x-go-name: Description
hidden:
type: boolean
x-go-name: Hidden
name:
type: string
x-go-name: Name
type:
type: string
x-go-name: Type
unit:
type: string
x-go-name: Unit
x-go-type:
hints:
noValidation: true
import:
alias: dbdatasets
package: github.com/axiomhq/axiom/pkg/db/client/swagger/datasets
type: DatasetField
Entry:
required:
- _rowId
- _sysTime
- _time
- data
type: object
properties:
_rowId:
type: string
x-go-name: RowID
_sysTime:
type: string
format: date-time
x-go-name: SysTime
_time:
type: string
format: date-time
x-go-name: Time
data:
type: object
additionalProperties:
type: object
properties: {}
x-go-name: Data
x-go-type:
hints:
noValidation: true
import:
alias: dbdatasets
package: github.com/axiomhq/axiom/pkg/db/client/swagger/datasets
type: Entry
Status:
required:
- blocksExamined
- cacheStatus
- elapsedTime
- isPartial
- maxBlockTime
- minBlockTime
- numGroups
- rowsExamined
- rowsMatched
type: object
properties:
blocksExamined:
type: integer
format: uint64
x-go-name: BlocksExamined
cacheStatus:
type: integer
format: uint8
x-go-name: CacheStatus
continuationToken:
type: string
x-go-name: ContinuationToken
elapsedTime:
type: integer
format: int64
x-go-name: ElapsedTime
isEstimate:
type: boolean
x-go-name: IsEstimate
isPartial:
type: boolean
x-go-name: IsPartial
maxBlockTime:
type: string
format: date-time
x-go-name: MaxBlockTime
maxCursor:
type: string
description: >-
Row id of the newest row, as seen server side.
May be higher than what the results include if the server scanned
more data than included in the results.
Can be used to efficiently resume time-sorted non-aggregating
queries (ie filtering only).
x-go-name: MaxCursor
messages:
type: array
items:
$ref: '#/components/schemas/Message'
x-go-name: Messages
minBlockTime:
type: string
format: date-time
x-go-name: MinBlockTime
minCursor:
type: string
description: >-
Row id of the oldest row, as seen server side.
May be lower than what the results include if the server scanned
more data than included in the results.
Can be used to efficiently resume time-sorted non-aggregating
queries (ie filtering only).
x-go-name: MinCursor
numGroups:
type: integer
format: uint32
x-go-name: NumGroups
rowsExamined:
type: integer
format: uint64
x-go-name: RowsExamined
rowsMatched:
type: integer
format: uint64
x-go-name: RowsMatched
x-go-type:
hints:
noValidation: true
import:
alias: dbdatasets
package: github.com/axiomhq/axiom/pkg/db/client/swagger/datasets
type: Status
Table:
required:
- name
- sources
- fields
- order
- groups
title: >-
Table defines the schema for query results in the "tabular" result
format.
type: object
properties:
buckets:
$ref: '#/components/schemas/BucketInfo'
columns:
type: array
description: |-
Columns contain a series of arrays with the raw result data.
The columns here line up with the fields in the Fields array.
items:
type: array
items:
type: object
properties: {}
x-go-name: Columns
fields:
type: array
description: >-
Fields contain information about the fields included in these
results.
The order of the fields match up with the order of the data in
Columns.
items:
$ref: '#/components/schemas/FieldInfo'
x-go-name: Fields
groups:
type: array
description: >-
Groups specifies which grouping operations has been performed on the
results.
items:
$ref: '#/components/schemas/GroupInfo'
x-go-name: GroupBy
name:
type: string
description: >-
Name is the name assigned to this table. Defaults to "0". The name
"_totals" is reserved for system use.
x-go-name: Name
order:
type: array
description: Order echoes the ordering clauses that was used to sort the results.
items:
$ref: '#/components/schemas/Order'
x-go-name: Order
range:
$ref: '#/components/schemas/RangeInfo'
sources:
type: array
description: >-
Sources contain the names of the datasets that contributed data to
these results.
items:
$ref: '#/components/schemas/SourceInfo'
x-go-name: Sources
description: >-
The tabular result format can be enabled via APLQueryParams.ResultFormat
or QueryParams.ResultFormat.
x-go-type:
hints:
noValidation: true
import:
alias: dbdatasets
package: github.com/axiomhq/axiom/pkg/db/client/swagger/datasets
type: Table
Interval:
required:
- endTime
- startTime
type: object
properties:
endTime:
type: string
format: date-time
x-go-name: EndTime
groups:
type: array
items:
$ref: '#/components/schemas/EntryGroup'
x-go-name: Groups
startTime:
type: string
format: date-time
x-go-name: StartTime
x-go-type:
hints:
noValidation: true
import:
alias: dbdatasets
package: github.com/axiomhq/axiom/pkg/db/client/swagger/datasets
type: Interval
EntryGroup:
required:
- group
- id
type: object
properties:
aggregations:
type: array
items:
$ref: '#/components/schemas/EntryGroupAgg'
x-go-name: Aggregations
group:
type: object
additionalProperties:
type: object
properties: {}
x-go-name: Group
id:
type: integer
format: uint64
x-go-name: ID
x-go-type:
hints:
noValidation: true
import:
alias: dbdatasets
package: github.com/axiomhq/axiom/pkg/db/client/swagger/datasets
type: EntryGroup
Message:
required:
- count
- msg
- priority
type: object
properties:
code:
type: string
x-go-name: Code
count:
type: integer
format: int64
x-go-name: Count
msg:
type: string
x-go-name: Msg
priority:
type: string
x-go-name: Priority
x-go-type:
hints:
noValidation: true
import:
alias: dbdatasets
package: github.com/axiomhq/axiom/pkg/db/client/swagger/datasets
type: Message
BucketInfo:
required:
- field
- size
title: >-
BucketInfo captures information about how a grouped query is sorted into
buckets.
type: object
properties:
field:
type: string
description: >-
Field specifies the field used to create buckets on. Normally this
would be _time.
x-go-name: Field
size:
type: object
properties: {}
description: |-
An integer or float representing the fixed bucket size.
When the bucket field is _time this value is in nanoseconds.
x-go-name: Size
description: The standard mode of operation is to create buckets on the _time column,
x-go-type:
hints:
noValidation: true
import:
alias: dbdatasets
package: github.com/axiomhq/axiom/pkg/db/client/swagger/datasets
type: BucketInfo
FieldInfo:
required:
- name
- type
title: >-
FieldInfo captures information about a field used in the tabular result
format. See Table.
type: object
properties:
agg:
$ref: '#/components/schemas/AggInfo'
name:
type: string
x-go-name: Name
type:
type: string
x-go-name: Type
x-go-type:
hints:
noValidation: true
import:
alias: dbdatasets
package: github.com/axiomhq/axiom/pkg/db/client/swagger/datasets
type: FieldInfo
GroupInfo:
title: >-
GroupInfo captures information about a grouping clause in the tabular
result format. See Table.
type: object
properties:
name:
type: string
x-go-name: Name
x-go-type:
hints:
noValidation: true
import:
alias: dbdatasets
package: github.com/axiomhq/axiom/pkg/db/client/swagger/datasets
type: GroupInfo
RangeInfo:
required:
- field
- start
- end
title: RangeInfo specifies the window a query was restricted to.
type: object
properties:
end:
type: string
description: |-
End is the ending time the query is limited by.
Queries are restricted to the interval [start,end).
format: date-time
x-go-name: End
field:
type: string
description: >-
Field specifies the field name on which the query range was
restricted. Normally _time
x-go-name: Field
start:
type: string
description: |-
Start is the starting time the query is limited by.
Queries are restricted to the interval [start,end).
format: date-time
x-go-name: Start
x-go-type:
hints:
noValidation: true
import:
alias: dbdatasets
package: github.com/axiomhq/axiom/pkg/db/client/swagger/datasets
type: RangeInfo
SourceInfo:
required:
- name
title: SourceInfo specifies the provenance of a results Table.
type: object
properties:
name:
type: string
x-go-name: Name
description: >-
Result sources will typically be the names of a datasets that were
searched,
but may be expanded to other things in the future.
x-go-type:
hints:
noValidation: true
import:
alias: dbdatasets
package: github.com/axiomhq/axiom/pkg/db/client/swagger/datasets
type: SourceInfo
EntryGroupAgg:
required:
- op
- value
type: object
properties:
data:
type: object
properties: {}
x-go-name: Data
op:
type: string
x-go-name: Alias
value:
type: object
properties: {}
x-go-name: Value
x-go-type:
hints:
noValidation: true
import:
alias: dbdatasets
package: github.com/axiomhq/axiom/pkg/db/client/swagger/datasets
type: EntryGroupAgg
AggInfo:
required:
- name
type: object
properties:
args:
type: array
description: >-
Args specifies any non-field arguments for the aggregation. Fx. [10]
for topk(players, 10).
items:
type: object
properties: {}
x-go-name: Args
fields:
type: array
description: >-
Fields specifies the names of the fields this aggregation is
computed on.
Fx ["players"] for topk(players, 10)
items:
type: string
x-go-name: Fields
name:
type: string
description: >-
Name is the system name of the aggregation, which is the string form
of aggregation.Type.
If the aggregation is aliased, the alias is stored in the parent
FieldInfo
x-go-name: Name
description: AggInfo captures information about an aggregation
x-go-type:
hints:
noValidation: true
import:
alias: dbdatasets
package: github.com/axiomhq/axiom/pkg/db/client/swagger/datasets
type: AggInfo
securitySchemes:
Auth:
type: http
scheme: bearer
description: >-
Authenticate using an API token or personal access token (PAT). Include
the token as a Bearer token: `Authorization: Bearer `. For more
information, see [Tokens](/reference/tokens).
````