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 Indexes API
version: 3.12.10 (API v0)
description: Improve the performance of queries
tags:
- description: Improve the performance of queries
name: Indexes
paths:
/_db/{database-name}/_api/index:
get:
description: 'Returns an object with an `indexes` attribute containing an array of all
index descriptions for the given collection. The same information is also
available in the `identifiers` attribute as an object with the index identifiers
as object keys.
'
operationId: listIndexes
parameters:
- description: 'The name of the database.
'
example: _system
in: path
name: database-name
required: true
schema:
type: string
- description: 'The collection name.
'
in: query
name: collection
required: true
schema:
type: string
- description: 'Whether to include figures and estimates in the result.
'
in: query
name: withStats
required: false
schema:
default: false
type: boolean
- description: 'Whether to include hidden indexes in the result. Internal indexes
(such as `arangosearch`) and ones that are currently built in the
background are hidden.
'
in: query
name: withHidden
required: false
schema:
default: false
type: boolean
responses:
'200':
description: 'returns a JSON object containing a list of indexes on that collection.
'
summary: List all indexes of a collection
tags:
- Indexes
post:
description: 'Creates a new index in the collection `collection`. Expects
an object containing the index details.
The type of the index to be created must specified in the **type**
attribute of the index details. Depending on the index type, additional
other attributes may need to specified in the request in order to create
the index.
Indexes require the to be indexed attribute(s) in the **fields** attribute
of the index details. Depending on the index type, a single attribute or
multiple attributes can be indexed. In the latter case, an array of
strings is expected.
The `.` character denotes sub-attributes in attribute paths. Attributes with
literal `.` in their name cannot be indexed. Attributes with the name `_id`
cannot be indexed either, neither as a top-level attribute nor as a sub-attribute.
Optionally, an index name may be specified as a string in the **name** attribute.
Index names have the same restrictions as collection names. If no value is
specified, one will be auto-generated.
Persistent indexes (including vertex-centric indexes) can be created as unique
or non-unique variants. Uniqueness can be controlled by specifying the
**unique** option for the index definition. Setting it to `true` creates a
unique index. Setting it to `false` or omitting the `unique` attribute creates a
non-unique index.
> **INFO:**
Unique indexes on non-shard keys are not supported in cluster deployments.
Persistent indexes can optionally be created in a sparse
variant. A sparse index will be created if the **sparse** attribute in
the index details is set to `true`. Sparse indexes do not index documents
for which any of the index attributes is either not set or is `null`.
The optional **deduplicate** attribute is supported by persistent array indexes.
It controls whether inserting duplicate index values
from the same document into a unique array index will lead to a unique constraint
error or not. The default value is `true`, so only a single instance of each
non-unique index value will be inserted into the index per document. Trying to
insert a value into the index that already exists in the index always fails,
regardless of the value of this attribute.
The optional **estimates** attribute is supported by `persistent`, `mdi`, and
`mdi-prefixed` indexes. This attribute controls whether index selectivity estimates are
maintained for the index. Not maintaining index selectivity estimates can have
a slightly positive impact on write performance.
The downside of turning off index selectivity estimates will be that
the query optimizer will not be able to determine the usefulness of different
competing indexes in AQL queries when there are multiple candidate indexes to
choose from.
The `estimates` attribute is optional and defaults to `true` if not set. It will
have no effect on indexes other than persistent indexes.
The optional attribute **cacheEnabled** is supported by indexes of type
`persistent`. This attribute controls whether an extra in-memory hash cache is
created for the index. The hash cache can be used to speed up index lookups.
The cache can only be used for queries that look up all index attributes via
an equality lookup (`==`). The hash cache cannot be used for range scans,
partial lookups or sorting.
The cache will be populated lazily upon reading data from the index. Writing data
into the collection or updating existing data will invalidate entries in the
cache. The cache may have a negative effect on performance in case index values
are updated more often than they are read.
The maximum size of cache entries that can be stored is currently 4 MB, i.e.
the cumulated size of all index entries for any index lookup value must be
less than 4 MB. This limitation is there to avoid storing the index entries
of "super nodes" in the cache.
`cacheEnabled` defaults to `false` and should only be used for indexes that
are known to benefit from an extra layer of caching.
The optional attribute **inBackground** can be set to `true` to keep the
collection/shards available for write operations by not using an exclusive
write lock for the duration of the index creation.
'
operationId: createIndex
parameters:
- description: 'The name of the database.
'
example: _system
in: path
name: database-name
required: true
schema:
type: string
- description: 'The collection name.
'
in: query
name: collection
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
description: 'The options for the index. The available attributes depend on the index type.
'
type: object
responses:
'200':
description: 'If the index already exists, then an *HTTP 200* is returned.
'
'201':
description: 'If the index does not already exist and could be created, then an *HTTP 201*
is returned.
'
'400':
description: 'If an invalid index description is posted or attributes are used that the
target index will not support, then an *HTTP 400* is returned.
'
'404':
description: 'If `collection` is unknown, then an *HTTP 404* is returned.
'
summary: Create an index
tags:
- Indexes
/_db/{database-name}/_api/index#fulltext:
post:
deprecated: true
description: '> **WARNING:**
The fulltext index type is deprecated from version 3.10 onwards.
Creates a fulltext index for the collection `collection-name`, if
it does not already exist. The call expects an object containing the index
details.
'
operationId: createIndexFulltext
parameters:
- description: 'The name of the database.
'
example: _system
in: path
name: database-name
required: true
schema:
type: string
- description: 'The collection name.
'
in: query
name: collection
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
fields:
description: 'A list with exactly one attribute path.
'
items:
type: string
maxItems: 1
minItems: 1
type: array
inBackground:
default: false
description: 'Set this option to `true` to keep the collection/shards available for
write operations by not using an exclusive write lock for the duration
of the index creation.
'
type: boolean
minLength:
default: 2
description: 'Minimum character length of words to index. The default is
low, thus it is recommended to set this value explicitly
when creating the index.
'
type: integer
name:
description: 'An easy-to-remember name for the index to look it up or refer to it in index hints.
Index names are subject to the same character restrictions as collection names.
If omitted, a name is auto-generated so that it is unique with respect to the
collection, e.g. `idx_832910498`.
'
type: string
type:
description: 'Needs to be set to `"fulltext"`.
'
example: fulltext
type: string
required:
- type
- fields
- minLength
type: object
responses:
'200':
description: 'The index exists already.
'
'201':
description: 'The index is created as there is no such existing index.
'
'404':
description: 'The collection is unknown.
'
summary: Create a full-text index
tags:
- Indexes
/_db/{database-name}/_api/index#geo:
post:
description: 'Creates a geo-spatial index in the collection `collection`, if
it does not already exist.
Geo indexes are always sparse, meaning that documents that do not contain
the index attributes or have non-numeric values in the index attributes
will not be indexed.
'
operationId: createIndexGeo
parameters:
- description: 'The name of the database.
'
example: _system
in: path
name: database-name
required: true
schema:
type: string
- description: 'The collection name.
'
in: query
name: collection
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
fields:
description: 'An array with one or two attribute paths.
If it is an array with one attribute path `location`, then a geo-spatial
index on all documents is created using `location` as path to the
coordinates. The value of the attribute must be an array with at least two
double values. The array must contain the latitude (first value) and the
longitude (second value). All documents, which do not have the attribute
path or with value that are not suitable, are ignored.
If it is an array with two attribute paths `latitude` and `longitude`,
then a geo-spatial index on all documents is created using `latitude`
and `longitude` as paths the latitude and the longitude. The values of
the `latitude` and `longitude` attributes must each be a number (double).
All documents which do not have the attribute paths or which have
values that are not suitable are ignored.
'
items:
type: string
maxItems: 2
minItems: 1
type: array
uniqueItems: true
geoJson:
default: false
description: 'If you create a geo-spatial index over a single attribute and `geoJson`
is `true`, then the coordinate order within the attribute''s array is
longitude followed by latitude. This corresponds to the format described in
<http://geojson.org/geojson-spec.html#positions>
'
type: boolean
inBackground:
default: false
description: 'Set this option to `true` to keep the collection/shards available for
write operations by not using an exclusive write lock for the duration
of the index creation.
'
type: boolean
legacyPolygons:
description: "If `geoJson` is set to `true`, then this option controls how GeoJSON Polygons\nare interpreted.\n\n- If `legacyPolygons` is `true`, the smaller of the two regions defined by a\n linear ring is interpreted as the interior of the ring and a ring can at most\n enclose half the Earth's surface.\n- If `legacyPolygons` is `false`, the area to the left of the boundary ring's\n path is considered to be the interior and a ring can enclose the entire\n surface of the Earth.\n\nThe default is `true` for geo indexes that were created in versions before 3.10,\nand `false` for geo indexes created in 3.10 or later.\n"
type: boolean
name:
description: 'An easy-to-remember name for the index to look it up or refer to it in index hints.
Index names are subject to the same character restrictions as collection names.
If omitted, a name is auto-generated so that it is unique with respect to the
collection, e.g. `idx_832910498`.
'
type: string
type:
description: 'Needs to be set to `"geo"`.
'
example: geo
type: string
required:
- type
- fields
type: object
responses:
'200':
description: 'The index exists already.
'
'201':
description: 'The index is created as there is no such existing index.
'
'404':
description: 'The collection is unknown.
'
summary: Create a geo-spatial index
tags:
- Indexes
/_db/{database-name}/_api/index#inverted:
post:
description: 'Creates an inverted index for the collection `collection-name`, if
it does not already exist. The call expects an object containing the index
details.
'
operationId: createIndexInverted
parameters:
- description: 'The name of the database.
'
example: _system
in: path
name: database-name
required: true
schema:
type: string
- description: 'The collection name.
'
in: query
name: collection
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
analyzer:
default: identity
description: 'The name of an Analyzer to use by default. This Analyzer is applied to the
values of the indexed fields for which you don''t define Analyzers explicitly.
'
type: string
cache:
default: false
description: 'Enable this option to always cache the field normalization values in memory
for all fields by default. This can improve the performance of scoring and
ranking queries. Otherwise, these values are memory-mapped and it is up to the
operating system to load them from disk into memory and to evict them from memory.
Normalization values are computed for fields which are processed with Analyzers
that have the `"norm"` feature enabled. These values are used to score fairer if
the same tokens occur repeatedly, to emphasize these documents less.
You can also enable this option to always cache auxiliary data used for querying
fields that are indexed with Geo Analyzers in memory for all fields by default.
This can improve the performance of geo-spatial queries.
See the `--arangosearch.columns-cache-limit` startup option to control the
memory consumption of this cache. You can reduce the memory usage of the column
cache in cluster deployments by only using the cache for leader shards, see the
`--arangosearch.columns-cache-only-leader` startup option (introduced in v3.10.6).
'
type: boolean
cleanupIntervalStep:
default: 2
description: "Wait at least this many commits between removing unused files in the\nArangoSearch data directory (set to `0` to disable).\nFor the case where the consolidation policies merge segments often (i.e. a lot\nof commit+consolidate), a lower value causes a lot of disk space to be\nwasted.\nFor the case where the consolidation policies rarely merge segments (i.e. few\ninserts/deletes), a higher value impacts performance without any added\nbenefits.\n\n_Background:_\n With every \"commit\" or \"consolidate\" operation, a new state of the\n inverted index' internal data structures is created on disk.\n Old states/snapshots are released once there are no longer any users\n remaining.\n However, the files for the released states/snapshots are left on disk, and\n only removed by \"cleanup\" operation.\n"
type: integer
commitIntervalMsec:
default: 1000
description: "Wait at least this many milliseconds between committing inverted index data store\nchanges and making documents visible to queries (set to `0` to disable).\nFor the case where there are a lot of inserts/updates, a higher value causes the\nindex not to account for them and memory usage continues to grow until the commit.\nA lower value impacts performance, including the case where there are no or only a\nfew inserts/updates because of synchronous locking, and it wastes disk space for\neach commit call.\n\n_Background:_\n For data retrieval, ArangoSearch follows the concept of\n \"eventually-consistent\", i.e. eventually all the data in ArangoDB will be\n matched by corresponding query expressions.\n The concept of ArangoSearch \"commit\" operations is introduced to\n control the upper-bound on the time until document addition/removals are\n actually reflected by corresponding query expressions.\n Once a \"commit\" operation is complete, all documents added/removed prior to\n the start of the \"commit\" operation will be reflected by queries invoked in\n subsequent ArangoDB transactions, in-progress ArangoDB transactions will\n still continue to return a repeatable-read state.\n"
type: integer
consolidationIntervalMsec:
default: 5000
description: "Wait at least this many milliseconds between applying `consolidationPolicy` to\nconsolidate the inverted index data store and possibly release space on the filesystem\n(set to `0` to disable).\nFor the case where there are a lot of data modification operations, a higher\nvalue could potentially have the data store consume more space and file handles.\nFor the case where there are a few data modification operations, a lower value\nimpacts performance due to no segment candidates being available for\nconsolidation.\n\n_Background:_\n For data modification, ArangoSearch follows the concept of a\n \"versioned data store\". Thus old versions of data may be removed once there\n are no longer any users of the old data. The frequency of the cleanup and\n compaction operations are governed by `consolidationIntervalMsec` and the\n candidates for compaction are selected via `consolidationPolicy`.\n"
type: integer
consolidationPolicy:
description: "The consolidation policy to apply for selecting which segments should be merged.\n\n_Background:_\n With each ArangoDB transaction that inserts documents, one or more\n ArangoSearch-internal segments get created.\n Similarly, for removed documents, the segments that contain such documents\n have these documents marked as 'deleted'.\n Over time, this approach causes a lot of small and sparse segments to be\n created.\n A \"consolidation\" operation selects one or more segments and copies all of\n their valid documents into a single new segment, thereby allowing the\n search algorithm to perform more optimally and for extra file handles to be\n released once old segments are no longer used.\n"
properties:
maxSkewThreshold:
default: 0.4
description: 'This option is available from v3.12.7 onward:
The skew describes how much segment files vary in file size. It is a number
between `0.0` and `1.0` and is calculated by dividing the largest file size
of a set of segment files by the total size. For example, the skew of a
200 MiB, 300 MiB, and 500 MiB segment file is `0.5` (`500 / 1000`).
A large `maxSkewThreshold` value allows merging large segment files with
smaller ones, consolidation occurs more frequently, and there are fewer
segment files on disk at all times. While this may potentially improve the
read performance and use fewer file descriptors, frequent consolidations
cause a higher write load and thus a higher write amplification.
On the other hand, a small threshold value triggers the consolidation only
when there are a large number of segment files that don''t vary in size a lot.
Consolidation occurs less frequently, reducing the write amplification, but
it can result in a greater number of segment files on disk.
Multiple combinations of candidate segments are checked and the one with
the lowest skew value is selected for consolidation. The selection process
picks the greatest number of segments that together have the lowest skew value
while ensuring that the size of the new consolidated segment remains under
the configured `segmentsBytesMax`.
'
maximum: 1
minimum: 0
type: number
minDeletionRatio:
default: 0.5
description: 'This option is available from v3.12.7 onward:
The `minDeletionRatio` represents the minimum required deletion ratio
in one or more segments to perform a cleanup of those segments.
It is a number between `0.0` and `1.0`.
The deletion ratio is the percentage of deleted documents across one or
more segment files and is calculated by dividing the number of deleted
documents by the total number of documents in a segment or a group of
segments. For example, if there is a segment with 1000 documents of which
300 are deleted and another segment with 1000 documents of which 700 are
deleted, the deletion ratio is `0.5` (50%, calculated as `1000 / 2000`).
The `minDeletionRatio` threshold must be carefully selected. A smaller
value leads to earlier cleanup of deleted documents from segments and
thus reclamation of disk space but it generates a higher write load.
A very large value lowers the write amplification but at the same time
the system can be left with a large number of segment files with a high
percentage of deleted documents that occupy disk space unnecessarily.
During cleanup, the segment files are first arranged in decreasing
order of their individual deletion ratios. Then the largest subset of
segments whose collective deletion ratio is greater than or equal to
`minDeletionRatio` is picked.
'
maximum: 1
minimum: 0
type: number
minScore:
default: 0
description: 'This option is only available up to v3.12.6:
Filter out consolidation candidates with a score less than this.
'
type: integer
segmentsBytesFloor:
default: 25165824
description: 'This option is only available up to v3.12.6:
Defines the value (in bytes) to treat all smaller segments as equal for
consolidation selection.
'
type: integer
segmentsBytesMax:
default: 8589934592
description: 'The maximum allowed size of all consolidated segments in bytes.
'
type: integer
segmentsMax:
default: 200
description: 'This option is only available up to v3.12.6:
The maximum number of segments that are evaluated as candidates for
consolidation.
'
type: integer
segmentsMin:
default: 50
description: 'This option is only available up to v3.12.6:
The minimum number of segments that are evaluated as candidates for
consolidation.
'
type: integer
type:
default: tier
description: "The segment candidates for the \"consolidation\" operation are selected based\nupon several possible configurable formulas as defined by their types.\nThe supported types are:\n\n- `\"tier\"`: consolidate based on segment byte size skew and live\n document count as dictated by the customization attributes.\n"
type: string
type: object
features:
description: 'A list of Analyzer features. You can set this option to overwrite what features
are enabled for the default `analyzer`.
Default: the features as defined by the Analyzer itself.
'
items:
enum:
- frequency
- norm
- position
- offset
type: string
type: array
uniqueItems: true
fields:
description: 'An array of attribute paths. You can use strings to index the fields with the
default options, or objects to specify options for the fields (with the
attribute path in the `name` property), or a mix of both.
'
items:
properties:
analyzer:
description: 'The name of an Analyzer to use for this field.
Default: the value defined by the top-level `analyzer` option.
'
type: string
cache:
description: 'Enable this option to always cache the field normalization values in memory
for this specific field. This can improve the performance of scoring and
ranking queries. Otherwise, these values are memory-mapped and it is up to the
operating system to load them from disk into memory and to evict them from memory.
Normalization values are computed for fields which are processed with Analyzers
that have the `"norm"` feature enabled. These values are used to score fairer if
the same tokens occur repeatedly, to emphasize these documents less.
You can also enable this option to always cache auxiliary data used for querying
fields that are indexed with Geo Analyzers in memory for this specific field.
This can improve the performance of geo-spatial queries.
Default: the value defined by the top-level `cache` option.
See the `--arangosearch.columns-cache-limit` startup option to control the
memory consumption of this cache. You can reduce the memory usage of the column
cache in cluster deployments by only using the cache for leader shards, see the
`--arangosearch.columns-cache-only-leader` startup option (introduced in v3.10.6).
'
type: boolean
features:
description: 'A list of Analyzer features to use for this field. You can set this option to
overwrite what features are enabled for the `analyzer`.
Default: the features as defined by the Analyzer itself, or inherited from the
top-level `features` option if the `analyzer` option adjacent to this option is
not set.
'
items:
enum:
- frequency
- norm
- position
- offset
type: string
type: array
uniqueItems: true
includeAllFields:
description: 'This option only applies if you use the inverted index in a `search-alias` Views.
If set to `true`, then all sub-attributes of this field are indexed, excluding
any sub-attributes that are configured separately by other elements in the
# --- truncated at 32 KB (97 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/arangodb/refs/heads/main/openapi/arangodb-indexes-api-openapi.yml