openapi: 3.2.0
info:
contact:
name: ArangoDB Inc.
url: https://arango.ai
license:
name: Business Source License 1.1
url: https://github.com/arangodb/arangodb/blob/devel/LICENSE
summary: The HTTP API of the ArangoDB graph database system
title: ArangoDB Core Queries API
version: 3.12.10 (API v0)
description: Run, process, and manage AQL queries
tags:
- description: Run, process, and manage AQL queries
name: Queries
paths:
/_db/{database-name}/_api/aqlfunction:
get:
deprecated: true
description: 'Returns all registered user-defined functions (UDFs) for the use in AQL of the
current database.
The call returns a JSON array with status codes and all user functions found under `result`.
'
operationId: listAqlUserFunctions
parameters:
- description: 'The name of the database.
'
example: _system
in: path
name: database-name
required: true
schema:
type: string
- description: 'Returns all registered AQL user functions from the specified namespace.
'
in: query
name: namespace
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties:
code:
description: 'The HTTP response status code.
'
example: 200
type: integer
error:
description: 'A flag indicating that no error occurred.
'
example: false
type: boolean
result:
description: 'All functions, or the ones matching the `namespace` parameter
'
items:
properties:
code:
description: 'A string representation of the function body
'
type: string
isDeterministic:
description: 'Whether the function results are fully deterministic, i.e.
the function return value solely depends on the input value
and the return value is the same for repeated calls with same
input.
This attribute is currently not used but may be used for
optimizations in the future.
'
type: boolean
name:
description: 'The fully qualified name of the user function
'
type: string
required:
- name
- code
- isDeterministic
type: object
type: array
required:
- error
- code
- result
type: object
description: 'on success *HTTP 200* is returned.
'
'400':
content:
application/json:
schema:
properties:
code:
description: 'The HTTP response status code.
'
example: 400
type: integer
error:
description: 'A flag indicating that an error occurred.
'
example: true
type: boolean
errorMessage:
description: 'A descriptive error message.
'
type: string
errorNum:
description: 'The ArangoDB error number for the error that occurred.
'
type: integer
required:
- error
- code
- errorNum
- errorMessage
type: object
description: 'If the user function name is malformed, the server will respond with *HTTP 400*.
'
summary: List the registered user-defined AQL functions
tags:
- Queries
post:
deprecated: true
description: 'Registers a user-defined function (UDF) written in JavaScript for the use in
AQL queries in the current database.
In case of success, HTTP 200 is returned.
If the function isn''t valid etc. HTTP 400 including a detailed error message will be returned.
'
operationId: createAqlUserFunction
parameters:
- description: 'The name of the database.
'
example: _system
in: path
name: database-name
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
code:
description: 'A string representation of the JavaScript function definition.
'
type: string
isDeterministic:
default: false
description: 'Whether the function results are fully deterministic, i.e.
the function return value solely depends on the input value
and the return value is the same for repeated calls with same
input.
This attribute is currently not used but may be used for
optimizations in the future.
'
type: boolean
name:
description: 'The fully qualified name of the user functions.
'
type: string
required:
- name
- code
type: object
responses:
'200':
content:
application/json:
schema:
properties:
code:
description: 'The HTTP response status code.
'
example: 200
type: integer
error:
description: 'A flag indicating that no error occurred.
'
example: false
type: boolean
isNewlyCreated:
description: 'boolean flag to indicate whether the function was newly created (`false` in this case)
'
type: boolean
required:
- error
- code
- isNewlyCreated
type: object
description: 'If the function already existed and was replaced by the
call, the server will respond with *HTTP 200*.
'
'201':
content:
application/json:
schema:
properties:
code:
description: 'The HTTP response status code.
'
example: 201
type: integer
error:
description: 'A flag indicating that no error occurred.
'
example: false
type: boolean
isNewlyCreated:
description: 'boolean flag to indicate whether the function was newly created (`true` in this case)
'
type: boolean
required:
- error
- code
- isNewlyCreated
type: object
description: 'If the function can be registered by the server, the server will respond with
*HTTP 201*.
'
'400':
content:
application/json:
schema:
properties:
code:
description: 'The HTTP response status code.
'
example: 400
type: integer
error:
description: 'A flag indicating that an error occurred.
'
example: true
type: boolean
errorMessage:
description: 'A descriptive error message.
'
type: string
errorNum:
description: 'The ArangoDB error number for the error that occurred.
'
type: integer
required:
- error
- code
- errorNum
- errorMessage
type: object
description: 'If the JSON representation is malformed or mandatory data is missing from the
request, the server will respond with *HTTP 400*.
'
summary: Create a user-defined AQL function
tags:
- Queries
/_db/{database-name}/_api/aqlfunction/{name}:
delete:
deprecated: true
description: 'Deletes an existing user-defined function (UDF) or function group identified by
`name` from the current database.
'
operationId: deleteAqlUserFunction
parameters:
- description: 'The name of the database.
'
example: _system
in: path
name: database-name
required: true
schema:
type: string
- description: 'the name of the AQL user function.
'
in: path
name: name
required: true
schema:
type: string
- description: "Possible values:\n- `true`: The function name provided in `name` is treated as\n a namespace prefix, and all functions in the specified namespace will be deleted.\n The returned number of deleted functions may become 0 if none matches the string.\n- `false`: The function name provided in `name` must be fully\n qualified, including any namespaces. If none matches the `name`, HTTP 404 is returned.\n"
in: query
name: group
required: false
schema:
default: false
type: boolean
responses:
'200':
content:
application/json:
schema:
properties:
code:
description: 'The HTTP response status code.
'
example: 200
type: integer
deletedCount:
description: 'The number of deleted user functions, always `1` when `group` is set to `false`.
Any number `>= 0` when `group` is set to `true`.
'
type: integer
error:
description: 'A flag indicating that no error occurred.
'
example: false
type: boolean
required:
- error
- code
- deletedCount
type: object
description: 'If the function can be removed by the server, the server will respond with
*HTTP 200*.
'
'400':
content:
application/json:
schema:
properties:
code:
description: 'The HTTP response status code.
'
example: 400
type: integer
error:
description: 'A flag indicating that an error occurred.
'
example: true
type: boolean
errorMessage:
description: 'A descriptive error message.
'
type: string
errorNum:
description: 'The ArangoDB error number for the error that occurred.
'
type: integer
required:
- error
- code
- errorNum
- errorMessage
type: object
description: 'If the user function name is malformed, the server will respond with *HTTP 400*.
'
'404':
content:
application/json:
schema:
properties:
code:
description: 'The HTTP response status code.
'
example: 404
type: integer
error:
description: 'A flag indicating that an error occurred.
'
example: true
type: boolean
errorMessage:
description: 'A descriptive error message.
'
type: string
errorNum:
description: 'The ArangoDB error number for the error that occurred.
'
type: integer
required:
- error
- code
- errorNum
- errorMessage
type: object
description: 'If the specified user function does not exist, the server will respond with *HTTP 404*.
'
summary: Remove a user-defined AQL function
tags:
- Queries
/_db/{database-name}/_api/cursor:
post:
description: 'Submits an AQL query for execution in the current database. The server returns
a result batch and may indicate that further batches need to be fetched using
a cursor identifier.
The query details include the query string plus optional query options and
bind parameters. These values need to be passed in a JSON representation in
the body of the POST request.
'
operationId: createAqlQueryCursor
parameters:
- description: 'The name of the database.
'
example: _system
in: path
name: database-name
required: true
schema:
type: string
- description: 'Set this header to `true` to allow the Coordinator to ask any shard replica for
the data, not only the shard leader. This may result in "dirty reads".
The header is ignored if this operation is part of a Stream Transaction
(`x-arango-trx-id` header). The header set when creating the transaction decides
about dirty reads for the entire transaction, not the individual read operations.
'
in: header
name: x-arango-allow-dirty-read
required: false
schema:
type: boolean
- description: 'To make this operation a part of a Stream Transaction, set this header to the
transaction ID returned by the `POST /_api/transaction/begin` call.
'
in: header
name: x-arango-trx-id
required: false
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
batchSize:
default: 1000
description: 'The maximum number of result documents to be transferred from
the server to the client in one roundtrip. If this attribute is
not set, a server-controlled default value will be used. A `batchSize` value of
`0` is disallowed.
'
type: integer
bindVars:
description: 'An object with key/value pairs representing the bind parameters.
For a bind variable `@var` in the query, specify the value using an attribute
with the name `var`. For a collection bind variable `@@coll`, use `@coll` as the
attribute name. For example: `"bindVars": { "var": 42, "@coll": "products" }`.
'
type: object
count:
default: false
description: 'Whether the number of documents in the result set should be returned in
the `count` attribute of the result.
Calculating this count might have a performance impact for some queries
in the future, so this option is turned off by default and `count`
is only returned when requested.
'
type: boolean
memoryLimit:
description: 'The maximum amount of memory (in bytes) that the query is allowed to
use. If set, then the query fails with error "resource limit exceeded" in
case it allocates too much memory. A value of `0` indicates that there is
no memory limit, but the [`--query.global-memory-limit` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--queryglobal-memory-limit)
may still limit it.
Default: You can configure a default per-query memory limit with the
[`--query.memory-limit` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--querymemory-limit). You can only increase
this default memory limit if `--query.memory-limit-override`
is enabled.
'
type: integer
options:
description: 'key/value object with extra options for the query.
'
properties:
allowDirtyReads:
default: false
description: 'If you set this option to `true` and execute the query against a cluster
deployment, then the Coordinator is allowed to read from any shard replica and
not only from the leader.
You may observe data inconsistencies (dirty reads) when reading from followers,
namely obsolete revisions of documents because changes have not yet been
replicated to the follower, as well as changes to documents before they are
officially committed on the leader.
The option is ignored if this operation is part of a Stream Transaction
(`x-arango-trx-id` header). The `x-arango-allow-dirty-read` header set
when creating the transaction decides about dirty reads for the entire
transaction, not the individual read operations.
'
type: boolean
allowRetry:
default: false
description: 'Set this option to `true` to make it possible to retry
fetching the latest batch from a cursor.
If retrieving a result batch fails because of a connection issue, you can ask
for that batch again using the `POST /_api/cursor/<cursor-id>/<batch-id>`
endpoint. The first batch has an ID of `1` and the value is incremented by 1
with every batch. Every result response except the last one also includes a
`nextBatchId` attribute, indicating the ID of the batch after the current.
You can remember and use this batch ID should retrieving the next batch fail.
You can only request the latest batch again (or the next batch).
Earlier batches are not kept on the server-side.
Requesting a batch again does not advance the cursor.
You can also call this endpoint with the next batch identifier, i.e. the value
returned in the `nextBatchId` attribute of a previous request. This advances the
cursor and returns the results of the next batch. This is only supported if there
are more results in the cursor (i.e. `hasMore` is `true` in the latest batch).
From v3.11.1 onward, you may use the `POST /_api/cursor/<cursor-id>/<batch-id>`
endpoint even if the `allowRetry` attribute is `false` to fetch the next batch,
but you cannot request a batch again unless you set it to `true`.
To allow refetching of the very last batch of the query, the server cannot
automatically delete the cursor. After the first attempt of fetching the last
batch, the server would normally delete the cursor to free up resources. As you
might need to reattempt the fetch, it needs to keep the final batch when the
`allowRetry` option is enabled. Once you successfully received the last batch,
you should call the `DELETE /_api/cursor/<cursor-id>` endpoint so that the
server doesn''t unnecessarily keep the batch until the cursor times out
(`ttl` query option).
'
type: boolean
cache:
description: 'Whether the [AQL query results cache](https://docs.arango.ai/arangodb/3.12/aql/execution-and-performance/caching-query-results/)
shall be used for adding as well as for retrieving results.
If the query cache mode is set to `demand` and you set the `cache` query option
to `true` for a query, then its query result is cached if it''s eligible for
caching. If the query cache mode is set to `on`, query results are automatically
cached if they are eligible for caching unless you set the `cache` option to `false`.
If you set the `cache` option to `false`, then any query cache lookup is skipped
for the query. If you set it to `true`, the query cache is checked for a cached result
**if** the query cache mode is either set to `on` or `demand`.
Default: Controlled by the [`--query.cache-mode` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--querycache-mode).
'
type: boolean
failOnWarning:
description: 'If set to `true`, the query throws an exception and aborts instead of producing
a warning. You should use this option during development to catch potential issues
early. When the attribute is set to `false`, warnings are not propagated to
exceptions and are returned with the query result.
Default: Controlled by the [`--query.fail-on-warning` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--queryfail-on-warning),
so you don''t need to set it on a per-query basis.
'
type: boolean
fillBlockCache:
default: true
description: 'If set to `true`, then the query stores the data it
reads via the RocksDB storage engine in the RocksDB block cache. This is usually
the desired behavior. The option can be set to `false` for queries that are
known to either read a lot of data which would thrash the block cache, or for queries
that read data which are known to be outside of the hot set. By setting the option
to `false`, data read by the query does not make it into the RocksDB block cache if
not already in there, thus leaving more room for the actual hot set.
'
type: boolean
fullCount:
default: false
description: 'If set to `true` and the query contains a `LIMIT` clause, then the
result will have an `extra` attribute with the sub-attributes `stats`
and `fullCount`, `{ ... , "extra": { "stats": { "fullCount": 123 } } }`.
The `fullCount` attribute will contain the number of documents in the result before the
last top-level LIMIT in the query was applied. It can be used to count the number of
documents that match certain filter criteria, but only return a subset of them, in one go.
It is thus similar to MySQL''s *SQL_CALC_FOUND_ROWS* hint. Note that setting the option
will disable a few LIMIT optimizations and may lead to more documents being processed,
and thus make queries run longer. Note that the `fullCount` attribute may only
be present in the result if the query has a top-level LIMIT clause and the LIMIT
clause is actually used in the query.
'
type: boolean
intermediateCommitCount:
description: 'The maximum number of operations after which an intermediate commit is performed
automatically.
Default: Controlled by the [`--rocksdb.intermediate-commit-count` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--rocksdbintermediate-commit-count).
'
type: integer
intermediateCommitSize:
description: 'The maximum total size of operations after which an intermediate commit is performed
automatically.
Default: Controlled by [`--rocksdb.intermediate-commit-size` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--rocksdbintermediate-commit-size).
'
type: integer
maxDNFConditionMembers:
description: 'A threshold for the maximum number of `OR` sub-nodes in the internal
representation of an AQL `FILTER` condition.
Yon can use this option to limit the computation time and memory usage when
converting complex AQL `FILTER` conditions into the internal DNF
(disjunctive normal form) format. `FILTER` conditions with a lot of logical
branches (`AND`, `OR`, `NOT`) can take a large amount of processing time and
memory. This query option limits the computation time and memory usage for
such conditions.
Once the threshold value is reached during the DNF conversion of a `FILTER`
condition, the conversion is aborted, and the query continues with a simplified
internal representation of the condition, which **cannot be used for index lookups**.
Default: Controlled by the [`--query.max-dnf-condition-members` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--querymax-dnf-condition-members)
to set the threshold globally instead of per query.
'
type: integer
maxNodesPerCallstack:
description: 'The number of execution nodes in the query plan after that stack splitting is
performed to avoid a potential stack overflow.
This option is only useful for testing and debugging and normally does not need
any adjustment.
Default: Controlled by the [`--query.max-nodes-per-callstack` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--querymax-nodes-per-callstack).
'
type: integer
maxNumberOfPlans:
description: 'Limits the maximum number of plans that are created by the AQL query optimizer.
Default: Controlled by the [`--query.optimizer-max-plans` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--queryoptimizer-max-plans).
'
type: integer
maxRuntime:
description: 'The query has to be executed within the given runtime or it is killed.
The value is specified in seconds. A value of `0.0` means no timeout.
Default: Controlled by the [`--query.max-runtime` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--querymax-runtime).
'
type: number
maxTransactionSize:
description: 'The transaction size limit in bytes.
Default: Controlled by the [`--rocksdb.max-transaction-size` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--rocksdbmax-transaction-size).
'
type: integer
maxWarningCount:
default: 10
description: 'Limits the number of warnings a query can return.
You can increased or decreased the number with this option.
'
type: integer
optimizer:
description: 'Options related to the query optimizer.
'
properties:
rules:
description: 'A list of optimizer rules, telling the optimizer to
include or exclude specific rules. See the
[List of optimizer rules](https://docs.arango.ai/arangodb/3.12/aql/execution-and-performance/query-optimization/#list-of-optimizer-rules).
To disable a rule, prefix its name with `-`. To enable a rule,
prefix it with `+`. There is also a pseudo-rule `all` that
matches all optimizer rules. `-all` disables all rules.
'
items:
type: string
type: array
type: object
profile:
default: 0
description: 'If set to `true` or `1`, then the additional query profiling information is returned
in the `profile` sub-attribute of the `extra` return attribute, unless the query result
is served from the query results cache. If set to `2`, the query includes execution stats
per query plan node in `stats.nodes` sub-attribute of the `extra` return attribute.
Additionally, the query plan is returned in the `extra.plan` sub-attribute.
'
type: integer
satelliteSyncWait:
default: 60
description: 'How long a DB-Server has time (in seconds) to bring the SatelliteCollections
involved in the query into sync. When the maximal time is reached, the query is stopped.
'
type: number
# --- truncated at 32 KB (177 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/arangodb/refs/heads/main/openapi/arangodb-queries-api-openapi.yml