Working with Indexes using HTTP

Read index

returns an index

GET /_api/index/{index-handle}

Path Parameters

  • index-handle (required): The index-handle.

The result is an object describing the index. It has at least the following attributes:

  • id: the identifier of the index

  • type: the index type

All other attributes are type-dependent. For example, some indexes provide unique or sparse flags, whereas others don't. Some indexes also provide a selectivity estimate in the selectivityEstimate attribute of the result.

Example:

shell> curl --dump - http://localhost:8529/_api/index/products/0

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

{ 
  "fields" : [ 
    "_key" 
  ], 
  "id" : "products/0", 
  "selectivityEstimate" : 1, 
  "sparse" : false, 
  "type" : "primary", 
  "unique" : true, 
  "error" : false, 
  "code" : 200 
}

Return Codes

  • 200: If the index exists, then a HTTP 200 is returned.
  • 404: If the index does not exist, then a HTTP 404 is returned.

Examples

shell> curl --dump - http://localhost:8529/_api/index/products/0

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
show response body

Create index

creates an index

POST /_api/index#general

Query Parameters

  • collection (required): The collection name.

Request Body (required)

NOTE Swagger examples won't work due to the anchor.

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.

Indexing the system attribute _id is not supported for user-defined indexes. Manually creating an index using _id as an index attribute will fail with an error.

Some indexes can be created as unique or non-unique variants. Uniqueness can be controlled for most indexes by specifying the unique flag in the index details. Setting it to true will create a unique index. Setting it to false or omitting the unique attribute will create a non-unique index.

Note: The following index types do not support uniqueness, and using the unique attribute with these types may lead to an error:

  • geo indexes
  • fulltext indexes

Note: Unique indexes on non-shard keys are not supported in a cluster.

Hash, skiplist and 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 attribute deduplicate is supported by array indexes of type hash or skiplist. 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 will always fail, regardless of the value of this attribute.

Return Codes

  • 200: If the index already exists, then an HTTP 200 is returned.
  • 201: If the index does not already exist and could be created, then an HTTP 201 is returned.
  • 400: 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: If collection is unknown, then an HTTP 404 is returned.

Delete index

deletes an index

DELETE /_api/index/{index-handle}

Path Parameters

  • index-handle (required): The index handle.

Deletes an index with index-handle.

Example:

shell> curl -X DELETE --dump - http://localhost:8529/_api/index/products/11938

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

{ 
  "id" : "products/11938", 
  "error" : false, 
  "code" : 200 
}

Return Codes

  • 200: If the index could be deleted, then an HTTP 200 is returned.
  • 404: If the index-handle is unknown, then an HTTP 404 is returned.

Examples

shell> curl -X DELETE --dump - http://localhost:8529/_api/index/products/11938

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
show response body

Read all indexes of a collection

returns all indexes of a collection

GET /_api/index

Query Parameters

  • collection (required): The collection name.

Returns an object with an attribute indexes containing an array of all index descriptions for the given collection. The same information is also available in the identifiers as an object with the index handles as keys.

Example:

Return information about all indexes

shell> curl --dump - http://localhost:8529/_api/index?collection=products

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

{ 
  "error" : false, 
  "code" : 200, 
  "indexes" : [ 
    { 
      "fields" : [ 
        "_key" 
      ], 
      "id" : "products/0", 
      "selectivityEstimate" : 1, 
      "sparse" : false, 
      "type" : "primary", 
      "unique" : true 
    }, 
    { 
      "deduplicate" : true, 
      "fields" : [ 
        "name" 
      ], 
      "id" : "products/11780", 
      "selectivityEstimate" : 1, 
      "sparse" : false, 
      "type" : "hash", 
      "unique" : false 
    }, 
    { 
      "deduplicate" : true, 
      "fields" : [ 
        "price" 
      ], 
      "id" : "products/11783", 
      "sparse" : true, 
      "type" : "skiplist", 
      "unique" : false 
    } 
  ], 
  "identifiers" : { 
    "products/0" : { 
      "fields" : [ 
        "_key" 
      ], 
      "id" : "products/0", 
      "selectivityEstimate" : 1, 
      "sparse" : false, 
      "type" : "primary", 
      "unique" : true 
    }, 
    "products/11780" : { 
      "deduplicate" : true, 
      "fields" : [ 
        "name" 
      ], 
      "id" : "products/11780", 
      "selectivityEstimate" : 1, 
      "sparse" : false, 
      "type" : "hash", 
      "unique" : false 
    }, 
    "products/11783" : { 
      "deduplicate" : true, 
      "fields" : [ 
        "price" 
      ], 
      "id" : "products/11783", 
      "sparse" : true, 
      "type" : "skiplist", 
      "unique" : false 
    } 
  } 
}

Return Codes

  • 200: returns a JSON object containing a list of indexes on that collection.

Examples

Return information about all indexes

shell> curl --dump - http://localhost:8529/_api/index?collection=products

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
show response body

© ArangoDB - the native multi-model NoSQL database