ArangoDB v3.4 reached End of Life (EOL) and is no longer supported.

This documentation is outdated. Please see the most recent version here: Latest Docs

Working with Hash Indexes

If a suitable hash index exists, then /_api/simple/by-example will use this index to execute a query-by-example.

Create hash index

creates a hash index

POST /_api/index#hash

Query Parameters

  • collection-name (required): The collection name.

A JSON object with these properties is required:

  • type: must be equal to “hash”.

  • fields: an array of attribute paths.

  • unique: if true, then create a unique index.

  • sparse: if true, then create a sparse index.

  • deduplicate: if false, the deduplication of array values is turned off.

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

Creates a hash index for the collection collection-name if it does not already exist. The call expects an object containing the index details.

In a sparse index all documents will be excluded from the index that do not contain at least one of the specified index attributes (i.e. fields) or that have a value of null in any of the specified index attributes. Such documents will not be indexed, and not be taken into account for uniqueness checks if the unique flag is set.

In a non-sparse index, these documents will be indexed (for non-present indexed attributes, a value of null will be used) and will be taken into account for uniqueness checks if the unique flag is set.

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

Return codes

  • 200: If the index already exists, then a HTTP 200 is returned.

  • 201: If the index does not already exist and could be created, then a HTTP 201 is returned.

  • 400: If the collection already contains documents and you try to create a unique hash index in such a way that there are documents violating the uniqueness, then a HTTP 400 is returned.

  • 404: If the collection-name is unknown, then a HTTP 404 is returned.

Examples

Creating an unique constraint

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/index?collection=products <<EOF
{ 
  "type" : "hash", 
  "unique" : true, 
  "fields" : [ 
    "a", 
    "b" 
  ] 
}
EOF

HTTP/1.1 Created
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
Show response body

Creating a non-unique hash index

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/index?collection=products <<EOF
{ 
  "type" : "hash", 
  "unique" : false, 
  "fields" : [ 
    "a", 
    "b" 
  ] 
}
EOF

HTTP/1.1 Created
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
Show response body

Creating a sparse index

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/index?collection=products <<EOF
{ 
  "type" : "hash", 
  "unique" : false, 
  "sparse" : true, 
  "fields" : [ 
    "a" 
  ] 
}
EOF

HTTP/1.1 Created
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
Show response body

Simple query by-example

returns all documents of a collection matching a given example

PUT /_api/simple/by-example

This route should no longer be used. All endpoints for Simple Queries are deprecated from version 3.4.0 on. They are superseded by AQL queries.

Till ArangoDB versions 3.2.13 and 3.3.7 this API is quite expensive. A more lightweight alternative is to use the HTTP Cursor API. Starting from versions 3.2.14 and 3.3.8 this performance impact is not an issue anymore, as the internal implementation of the API has changed.

A JSON object with these properties is required:

  • collection: The name of the collection to query.

  • example: The example document.

  • skip: The number of documents to skip in the query (optional).

  • limit: The maximal amount of documents to return. The skip is applied before the limit restriction. (optional)

  • batchSize: 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.

This will find all documents matching a given example.

Returns a cursor containing the result, see HTTP Cursor for details.

Return codes

  • 201: is returned if the query was executed successfully.

  • 400: is returned if the body does not contain a valid JSON representation of a query. The response body contains an error document in this case.

  • 404: is returned if the collection specified by collection is unknown. The response body contains an error document in this case.

Examples

Matching an attribute

shell> curl -X PUT --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/simple/by-example <<EOF
{ 
  "collection" : "products", 
  "example" : { 
    "i" : 1 
  } 
}
EOF

HTTP/1.1 Created
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
Show response body

Matching an attribute which is a sub-document

shell> curl -X PUT --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/simple/by-example <<EOF
{ 
  "collection" : "products", 
  "example" : { 
    "a.j" : 1 
  } 
}
EOF

HTTP/1.1 Created
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
Show response body

Matching an attribute within a sub-document

shell> curl -X PUT --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/simple/by-example <<EOF
{ 
  "collection" : "products", 
  "example" : { 
    "a" : { 
      "j" : 1 
    } 
  } 
}
EOF

HTTP/1.1 Created
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
Show response body

Find documents matching an example

returns one document of a collection matching a given example

PUT /_api/simple/first-example

This route should no longer be used. All endpoints for Simple Queries are deprecated from version 3.4.0 on. They are superseded by AQL queries.

Till ArangoDB versions 3.2.13 and 3.3.7 this API is quite expensive. A more lightweight alternative is to use the HTTP Cursor API. Starting from versions 3.2.14 and 3.3.8 this performance impact is not an issue anymore, as the internal implementation of the API has changed.

A JSON object with these properties is required:

  • collection: The name of the collection to query.

  • example: The example document.

This will return the first document matching a given example.

Returns a result containing the document or HTTP 404 if no document matched the example.

If more than one document in the collection matches the specified example, only one of these documents will be returned, and it is undefined which of the matching documents is returned.

Return codes

  • 200: is returned when the query was successfully executed.

  • 400: is returned if the body does not contain a valid JSON representation of a query. The response body contains an error document in this case.

  • 404: is returned if the collection specified by collection is unknown. The response body contains an error document in this case.

Examples

If a matching document was found

shell> curl -X PUT --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/simple/first-example <<EOF
{ 
  "collection" : "products", 
  "example" : { 
    "i" : 1 
  } 
}
EOF

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

If no document was found

shell> curl -X PUT --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/simple/first-example <<EOF
{ 
  "collection" : "products", 
  "example" : { 
    "l" : 1 
  } 
}
EOF

HTTP/1.1 Not Found
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
Show response body
❮  Working with Indexes

© ArangoDB - the native multi-model NoSQL database