ArangoDB v2.8 reached End of Life (EOL) and is no longer supported.

This documentation is outdated. Please see the most recent version here: Try latest

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.

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 --data-binary @- --dump - http://localhost:8529/_api/index?collection=products <<EOF
{ 
  "type" : "hash", 
  "unique" : true, 
  "fields" : [ 
    "a", 
    "b" 
  ] 
}
EOF

HTTP/1.1 201 Created
content-type: application/json; charset=utf-8
show response body


Creating a non-unique hash index 

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

HTTP/1.1 201 Created
content-type: application/json; charset=utf-8
show response body


Creating a sparse index 

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

HTTP/1.1 201 Created
content-type: application/json; charset=utf-8
show response body

Simple query by-example

returns all documents of a collection matching a given example

PUT /_api/simple/by-example

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)


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 --data-binary @- --dump - http://localhost:8529/_api/simple/by-example <<EOF
{ 
  "collection" : "products", 
  "example" : { 
    "i" : 1 
  } 
}
EOF

HTTP/1.1 201 Created
content-type: application/json; charset=utf-8
show response body


Matching an attribute which is a sub-document 

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

HTTP/1.1 201 Created
content-type: application/json; charset=utf-8
show response body


Matching an attribute within a sub-document 

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

HTTP/1.1 201 Created
content-type: application/json; charset=utf-8
show response body

Find documents matching an example

returns one document of a collection matching a given example

PUT /_api/simple/first-example

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 --data-binary @- --dump - http://localhost:8529/_api/simple/first-example <<EOF
{ 
  "collection" : "products", 
  "example" : { 
    "i" : 1 
  } 
}
EOF

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


If no document was found 

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

HTTP/1.1 404 Not Found
content-type: application/json; charset=utf-8
show response body
❮  Cap Constraints

© ArangoDB - the native multi-model NoSQL database