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:

  • fields (string): an array of attribute paths.
  • unique: if true, then create a unique index.
  • type: must be equal to "hash".
  • 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.

Example:

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
x-content-type-options: nosniff

{ 
  "deduplicate" : true, 
  "fields" : [ 
    "a", 
    "b" 
  ], 
  "id" : "products/11882", 
  "isNewlyCreated" : true, 
  "selectivityEstimate" : 1, 
  "sparse" : false, 
  "type" : "hash", 
  "unique" : true, 
  "error" : false, 
  "code" : 201 
}

Example:

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
x-content-type-options: nosniff

{ 
  "deduplicate" : true, 
  "fields" : [ 
    "a", 
    "b" 
  ], 
  "id" : "products/11840", 
  "isNewlyCreated" : true, 
  "selectivityEstimate" : 1, 
  "sparse" : false, 
  "type" : "hash", 
  "unique" : false, 
  "error" : false, 
  "code" : 201 
}

Example:

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
x-content-type-options: nosniff

{ 
  "deduplicate" : true, 
  "fields" : [ 
    "a" 
  ], 
  "id" : "products/11896", 
  "isNewlyCreated" : true, 
  "selectivityEstimate" : 1, 
  "sparse" : true, 
  "type" : "hash", 
  "unique" : false, 
  "error" : false, 
  "code" : 201 
}

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
x-content-type-options: nosniff
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
x-content-type-options: nosniff
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
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

A JSON object with these properties is required:

  • skip: The number of documents to skip in the query (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.
  • limit: The maximal amount of documents to return. The skip is applied before the limit restriction. (optional)
  • example: The example document.
  • collection: The name of the collection to query.

This will find all documents matching a given example.

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

Example:

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
x-content-type-options: nosniff

{ 
  "result" : [ 
    { 
      "_key" : "12208", 
      "_id" : "products/12208", 
      "_rev" : "_WQ47fbm--_", 
      "a" : { 
        "k" : 2, 
        "j" : 2 
      }, 
      "i" : 1 
    }, 
    { 
      "_key" : "12202", 
      "_id" : "products/12202", 
      "_rev" : "_WQ47fbi--B", 
      "a" : { 
        "j" : 1 
      }, 
      "i" : 1 
    }, 
    { 
      "_key" : "12198", 
      "_id" : "products/12198", 
      "_rev" : "_WQ47fbi--_", 
      "a" : { 
        "k" : 1, 
        "j" : 1 
      }, 
      "i" : 1 
    }, 
    { 
      "_key" : "12205", 
      "_id" : "products/12205", 
      "_rev" : "_WQ47fbi--D", 
      "i" : 1 
    } 
  ], 
  "hasMore" : false, 
  "count" : 4, 
  "error" : false, 
  "code" : 201 
}

Example:

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
x-content-type-options: nosniff

{ 
  "result" : [ 
    { 
      "_key" : "12228", 
      "_id" : "products/12228", 
      "_rev" : "_WQ47fcK--B", 
      "a" : { 
        "j" : 1 
      }, 
      "i" : 1 
    }, 
    { 
      "_key" : "12224", 
      "_id" : "products/12224", 
      "_rev" : "_WQ47fcK--_", 
      "a" : { 
        "k" : 1, 
        "j" : 1 
      }, 
      "i" : 1 
    } 
  ], 
  "hasMore" : false, 
  "count" : 2, 
  "error" : false, 
  "code" : 201 
}

Example:

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
x-content-type-options: nosniff

{ 
  "result" : [ 
    { 
      "_key" : "12254", 
      "_id" : "products/12254", 
      "_rev" : "_WQ47fcq--B", 
      "a" : { 
        "j" : 1 
      }, 
      "i" : 1 
    } 
  ], 
  "hasMore" : false, 
  "count" : 1, 
  "error" : false, 
  "code" : 201 
}

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
x-content-type-options: nosniff
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
x-content-type-options: nosniff
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
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

A JSON object with these properties is required:

  • example: The example document.
  • collection: The name of the collection to query.

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.

Example:

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
x-content-type-options: nosniff

{ 
  "document" : { 
    "_key" : "12286", 
    "_id" : "products/12286", 
    "_rev" : "_WQ47fdO--F", 
    "a" : { 
      "k" : 2, 
      "j" : 2 
    }, 
    "i" : 1 
  }, 
  "error" : false, 
  "code" : 200 
}

Example:

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
x-content-type-options: nosniff

{ 
  "error" : true, 
  "code" : 404, 
  "errorNum" : 404, 
  "errorMessage" : "no match" 
}

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
x-content-type-options: nosniff
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
x-content-type-options: nosniff
show response body

© ArangoDB - the native multi-model NoSQL database