HTTP Interface for Simple Queries

Simple Queries

This is an introduction to ArangoDB's HTTP interface for simple queries.

Simple queries can be used if the query condition is straight forward simple, i.e., a document reference, all documents, a query-by-example, or a simple geo query. In a simple query you can specify exactly one collection and one condition. The result can then be sorted and can be split into pages.

Working with Simples Queries using HTTP

To limit the amount of results to be transferred in one batch, simple queries support a batchSize parameter that can optionally be used to tell the server to limit the number of results to be transferred in one batch to a certain value. If the query has more results than were transferred in one go, more results are waiting on the server so they can be fetched subsequently. If no value for the batchSize parameter is specified, the server will use a reasonable default value.

If the server has more documents than should be returned in a single batch, the server will set the hasMore attribute in the result. It will also return the id of the server-side cursor in the id attribute in the result. This id can be used with the cursor API to fetch any outstanding results from the server and dispose the server-side cursor afterwards.

Return all documents

returns all documents of a collection

PUT /_api/simple/all

Request Body (required)

Contains the query.

Returns all documents of a collections. The call expects a JSON object as body with the following attributes:

  • collection: The name of the collection to query.

  • 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)

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

Example:

Limit the amount of documents using limit

shell> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/all <<EOF
{ "collection": "products", "skip": 2, "limit" : 2 }
EOF

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

{ 
  "result" : [ 
    { 
      "_key" : "12142", 
      "_id" : "products/12142", 
      "_rev" : "_WQ47fae--_", 
      "Hello1" : "World1" 
    }, 
    { 
      "_key" : "12155", 
      "_id" : "products/12155", 
      "_rev" : "_WQ47fae--H", 
      "Hello5" : "World5" 
    } 
  ], 
  "hasMore" : false, 
  "count" : 2, 
  "cached" : false, 
  "extra" : { 
    "stats" : { 
      "writesExecuted" : 0, 
      "writesIgnored" : 0, 
      "scannedFull" : 4, 
      "scannedIndex" : 0, 
      "filtered" : 0, 
      "httpRequests" : 0, 
      "executionTime" : 0.00009989738464355469 
    }, 
    "warnings" : [ ] 
  }, 
  "error" : false, 
  "code" : 201 
}

Example:

Using a batchSize value

shell> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/all <<EOF
{ "collection": "products", "batchSize" : 3 }
EOF

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

{ 
  "error" : false, 
  "code" : 201, 
  "result" : [ 
    { 
      "_key" : "12113", 
      "_id" : "products/12113", 
      "_rev" : "_WQ47fZ2--_", 
      "Hello1" : "World1" 
    }, 
    { 
      "_key" : "12120", 
      "_id" : "products/12120", 
      "_rev" : "_WQ47fZ6--B", 
      "Hello3" : "World3" 
    }, 
    { 
      "_key" : "12123", 
      "_id" : "products/12123", 
      "_rev" : "_WQ47fZ6--D", 
      "Hello4" : "World4" 
    } 
  ], 
  "hasMore" : true, 
  "id" : "12129", 
  "count" : 5, 
  "extra" : { 
    "stats" : { 
      "writesExecuted" : 0, 
      "writesIgnored" : 0, 
      "scannedFull" : 5, 
      "scannedIndex" : 0, 
      "filtered" : 0, 
      "httpRequests" : 0, 
      "executionTime" : 0.00010585784912109375 
    }, 
    "warnings" : [ ] 
  }, 
  "cached" : false 
}

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

Limit the amount of documents using limit

shell> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/all <<EOF
{ "collection": "products", "skip": 2, "limit" : 2 }
EOF

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

Using a batchSize value

shell> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/all <<EOF
{ "collection": "products", "batchSize" : 3 }
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

Find documents by their keys

fetches multiple documents by their keys

PUT /_api/simple/lookup-by-keys

A JSON object with these properties is required:

  • keys (string): array with the _keys of documents to remove.
  • collection: The name of the collection to look in for the documents

Looks up the documents in the specified collection using the array of keys provided. All documents for which a matching key was specified in the keys array and that exist in the collection will be returned. Keys for which no document can be found in the underlying collection are ignored, and no exception will be thrown for them.

The body of the response contains a JSON object with a documents attribute. The documents attribute is an array containing the matching documents. The order in which matching documents are present in the result array is unspecified.

Example:

Looking up existing documents

shell> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/lookup-by-keys <<EOF
{ 
  "keys" : [ 
    "test0", 
    "test1", 
    "test2", 
    "test3", 
    "test4", 
    "test5", 
    "test6", 
    "test7", 
    "test8", 
    "test9" 
  ], 
  "collection" : "test" 
}
EOF

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

{ 
  "documents" : [ 
    { 
      "_key" : "test0", 
      "_id" : "test/test0", 
      "_rev" : "_WQ47ffG--_", 
      "value" : 0 
    }, 
    { 
      "_key" : "test1", 
      "_id" : "test/test1", 
      "_rev" : "_WQ47ffK--_", 
      "value" : 1 
    }, 
    { 
      "_key" : "test2", 
      "_id" : "test/test2", 
      "_rev" : "_WQ47ffK--B", 
      "value" : 2 
    }, 
    { 
      "_key" : "test3", 
      "_id" : "test/test3", 
      "_rev" : "_WQ47ffK--D", 
      "value" : 3 
    }, 
    { 
      "_key" : "test4", 
      "_id" : "test/test4", 
      "_rev" : "_WQ47ffK--F", 
      "value" : 4 
    }, 
    { 
      "_key" : "test5", 
      "_id" : "test/test5", 
      "_rev" : "_WQ47ffK--H", 
      "value" : 5 
    }, 
    { 
      "_key" : "test6", 
      "_id" : "test/test6", 
      "_rev" : "_WQ47ffK--J", 
      "value" : 6 
    }, 
    { 
      "_key" : "test7", 
      "_id" : "test/test7", 
      "_rev" : "_WQ47ffK--L", 
      "value" : 7 
    }, 
    { 
      "_key" : "test8", 
      "_id" : "test/test8", 
      "_rev" : "_WQ47ffK--N", 
      "value" : 8 
    }, 
    { 
      "_key" : "test9", 
      "_id" : "test/test9", 
      "_rev" : "_WQ47ffO--_", 
      "value" : 9 
    } 
  ], 
  "error" : false, 
  "code" : 200 
}

Example:

Looking up non-existing documents

shell> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/lookup-by-keys <<EOF
{ 
  "keys" : [ 
    "foo", 
    "bar", 
    "baz" 
  ], 
  "collection" : "test" 
}
EOF

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

{ 
  "documents" : [ ], 
  "error" : false, 
  "code" : 200 
}

Return Codes

  • 200: is returned if the operation was carried out successfully.
  • 404: is returned if the collection was not found. The response body contains an error document in this case.
  • 405: is returned if the operation was called with a different HTTP METHOD than PUT.

Examples

Looking up existing documents

shell> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/lookup-by-keys <<EOF
{ 
  "keys" : [ 
    "test0", 
    "test1", 
    "test2", 
    "test3", 
    "test4", 
    "test5", 
    "test6", 
    "test7", 
    "test8", 
    "test9" 
  ], 
  "collection" : "test" 
}
EOF

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

Looking up non-existing documents

shell> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/lookup-by-keys <<EOF
{ 
  "keys" : [ 
    "foo", 
    "bar", 
    "baz" 
  ], 
  "collection" : "test" 
}
EOF

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

Return a random document

returns a random document from a collection

PUT /_api/simple/any

Returns a random document from a collection. The call expects a JSON object as body with the following attributes:

A JSON object with these properties is required:

  • collection: The identifier or name of the collection to query. Returns a JSON object with the document stored in the attribute document if the collection contains at least one document. If the collection is empty, the document attrbute contains null.

Example:

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

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

{ 
  "document" : { 
    "_key" : "12170", 
    "_id" : "products/12170", 
    "_rev" : "_WQ47fbC--_", 
    "Hello1" : "World1" 
  }, 
  "error" : false, 
  "code" : 200 
}

Return Codes

  • 200: 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

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

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

Remove documents by their keys

removes multiple documents by their keys

PUT /_api/simple/remove-by-keys

A JSON object with these properties is required:

  • keys (string): array with the _keys of documents to remove.
  • options:
    • returnOld: if set to true and silent above is false, then the above information about the removed documents contains the complete removed documents.
    • silent: if set to false, then the result will contain an additional attribute old which contains an array with one entry for each removed document. By default, these entries will have the _id, _key and _rev attributes.
    • waitForSync: if set to true, then all removal operations will instantly be synchronized to disk. If this is not specified, then the collection's default sync behavior will be applied.
  • collection: The name of the collection to look in for the documents to remove

Looks up the documents in the specified collection using the array of keys provided, and removes all documents from the collection whose keys are contained in the keys array. Keys for which no document can be found in the underlying collection are ignored, and no exception will be thrown for them.

The body of the response contains a JSON object with information how many documents were removed (and how many were not). The removed attribute will contain the number of actually removed documents. The ignored attribute will contain the number of keys in the request for which no matching document could be found.

Example:

shell> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/remove-by-keys <<EOF
{ 
  "keys" : [ 
    "test0", 
    "test1", 
    "test2", 
    "test3", 
    "test4", 
    "test5", 
    "test6", 
    "test7", 
    "test8", 
    "test9" 
  ], 
  "collection" : "test" 
}
EOF

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

{ 
  "removed" : 10, 
  "ignored" : 0, 
  "error" : false, 
  "code" : 200 
}

Example:

shell> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/remove-by-keys <<EOF
{ 
  "keys" : [ 
    "foo", 
    "bar", 
    "baz" 
  ], 
  "collection" : "test" 
}
EOF

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

{ 
  "removed" : 0, 
  "ignored" : 3, 
  "error" : false, 
  "code" : 200 
}

shell> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/remove-by-keys <<EOF
{ 
  "keys" : [ 
    "test0", 
    "test1", 
    "test2", 
    "test3", 
    "test4", 
    "test5", 
    "test6", 
    "test7", 
    "test8", 
    "test9" 
  ], 
  "collection" : "test" 
}
EOF

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
show response body
shell> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/remove-by-keys <<EOF
{ 
  "keys" : [ 
    "foo", 
    "bar", 
    "baz" 
  ], 
  "collection" : "test" 
}
EOF

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

Remove documents by example

removes all documents of a collection that match an example

PUT /_api/simple/remove-by-example

A JSON object with these properties is required:

  • example: An example document that all collection documents are compared against.
  • collection: The name of the collection to remove from.
  • options:
    • limit: an optional value that determines how many documents to delete at most. If limit is specified but is less than the number of documents in the collection, it is undefined which of the documents will be deleted.
    • waitForSync: if set to true, then all removal operations will instantly be synchronized to disk. If this is not specified, then the collection's default sync behavior will be applied.

This will find all documents in the collection that match the specified example object.

Note: the limit attribute is not supported on sharded collections. Using it will result in an error.

Returns the number of documents that were deleted.

Example:

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

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

{ 
  "deleted" : 1, 
  "error" : false, 
  "code" : 200 
}

Example:

Using Parameter: waitForSync and limit

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

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

{ 
  "deleted" : 1, 
  "error" : false, 
  "code" : 200 
}

Example:

Using Parameter: waitForSync and limit with new signature

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

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

{ 
  "deleted" : 1, 
  "error" : false, 
  "code" : 200 
}

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

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

Using Parameter: waitForSync and limit

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

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

Using Parameter: waitForSync and limit with new signature

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

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

Replace documents by example

replaces the body of all documents of a collection that match an example

PUT /_api/simple/replace-by-example

A JSON object with these properties is required:

  • options:
    • limit: an optional value that determines how many documents to replace at most. If limit is specified but is less than the number of documents in the collection, it is undefined which of the documents will be replaced.
    • waitForSync: if set to true, then all removal operations will instantly be synchronized to disk. If this is not specified, then the collection's default sync behavior will be applied.
  • example: An example document that all collection documents are compared against.
  • collection: The name of the collection to replace within.
  • newValue: The replacement document that will get inserted in place of the "old" documents.

This will find all documents in the collection that match the specified example object, and replace the entire document body with the new value specified. Note that document meta-attributes such as _id, _key, _from, _to etc. cannot be replaced.

Note: the limit attribute is not supported on sharded collections. Using it will result in an error.

Returns the number of documents that were replaced.

Example:

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

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

{ 
  "replaced" : 1, 
  "error" : false, 
  "code" : 200 
}

Example:

Using new Signature for attributes WaitForSync and limit

shell> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/replace-by-example <<EOF
{ 
  "collection" : "products", 
  "example" : { 
    "a" : { 
      "j" : 1 
    } 
  }, 
  "newValue" : { 
    "foo" : "bar" 
  }, 
  "options" : { 
    "limit" : 3, 
    "waitForSync" : true 
  } 
}
EOF

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

{ 
  "replaced" : 1, 
  "error" : false, 
  "code" : 200 
}

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

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

Using new Signature for attributes WaitForSync and limit

shell> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/replace-by-example <<EOF
{ 
  "collection" : "products", 
  "example" : { 
    "a" : { 
      "j" : 1 
    } 
  }, 
  "newValue" : { 
    "foo" : "bar" 
  }, 
  "options" : { 
    "limit" : 3, 
    "waitForSync" : true 
  } 
}
EOF

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

Update documents by example

partially updates the body of all documents of a collection that match an example

PUT /_api/simple/update-by-example

A JSON object with these properties is required:

  • options:
    • keepNull: This parameter can be used to modify the behavior when handling null values. Normally, null values are stored in the database. By setting the keepNull parameter to false, this behavior can be changed so that all attributes in data with null values will be removed from the updated document.
    • mergeObjects: Controls whether objects (not arrays) will be merged if present in both the existing and the patch document. If set to false, the value in the patch document will overwrite the existing document's value. If set to true, objects will be merged. The default is true.
    • limit: an optional value that determines how many documents to update at most. If limit is specified but is less than the number of documents in the collection, it is undefined which of the documents will be updated.
    • waitForSync: if set to true, then all removal operations will instantly be synchronized to disk. If this is not specified, then the collection's default sync behavior will be applied.
  • example: An example document that all collection documents are compared against.
  • collection: The name of the collection to update within.
  • newValue: A document containing all the attributes to update in the found documents.

This will find all documents in the collection that match the specified example object, and partially update the document body with the new value specified. Note that document meta-attributes such as _id, _key, _from, _to etc. cannot be replaced.

Note: the limit attribute is not supported on sharded collections. Using it will result in an error.

Returns the number of documents that were updated.

Example:

using old syntax for options

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

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

{ 
  "updated" : 1, 
  "error" : false, 
  "code" : 200 
}

Example:

using new signature for options

shell> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/update-by-example <<EOF
{ 
  "collection" : "products", 
  "example" : { 
    "a" : { 
      "j" : 1 
    } 
  }, 
  "newValue" : { 
    "a" : { 
      "j" : 22 
    } 
  }, 
  "options" : { 
    "limit" : 3, 
    "waitForSync" : true 
  } 
}
EOF

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

{ 
  "updated" : 1, 
  "error" : false, 
  "code" : 200 
}

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

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

using new signature for options

shell> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/update-by-example <<EOF
{ 
  "collection" : "products", 
  "example" : { 
    "a" : { 
      "j" : 1 
    } 
  }, 
  "newValue" : { 
    "a" : { 
      "j" : 22 
    } 
  }, 
  "options" : { 
    "limit" : 3, 
    "waitForSync" : true 
  } 
}
EOF

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

Simple range query

returns all documents of a collection within a range

PUT /_api/simple/range

A JSON object with these properties is required:

  • right: The upper bound.
  • attribute: The attribute path to check.
  • collection: The name of the collection to query.
  • limit: The maximal amount of documents to return. The skip is applied before the limit restriction. (optional)
  • closed: If true, use interval including left and right, otherwise exclude right, but include left.
  • skip: The number of documents to skip in the query (optional).
  • left: The lower bound.

This will find all documents within a given range. In order to execute a range query, a skip-list index on the queried attribute must be present.

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

Note: the range simple query is deprecated as of ArangoDB 2.6. The function may be removed in future versions of ArangoDB. The preferred way for retrieving documents from a collection within a specific range is to use an AQL query as follows: 

FOR doc IN @@collection 
  FILTER doc.value >= @left && doc.value < @right 
  LIMIT @skip, @limit 
  RETURN doc`

Example:

shell> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/range <<EOF
{ 
  "collection" : "products", 
  "attribute" : "i", 
  "left" : 2, 
  "right" : 4 
}
EOF

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

{ 
  "result" : [ 
    { 
      "_key" : "12528", 
      "_id" : "products/12528", 
      "_rev" : "_WQ47fie--B", 
      "i" : 2 
    }, 
    { 
      "_key" : "12531", 
      "_id" : "products/12531", 
      "_rev" : "_WQ47fie--D", 
      "i" : 3 
    } 
  ], 
  "hasMore" : false, 
  "count" : 2, 
  "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 or no suitable index for the range query is present. The response body contains an error document in this case.

Examples

shell> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/range <<EOF
{ 
  "collection" : "products", 
  "attribute" : "i", 
  "left" : 2, 
  "right" : 4 
}
EOF

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

Returns documents near a coordinate

returns all documents of a collection near a given location

PUT /_api/simple/near

A JSON object with these properties is required:

  • distance: If given, the attribute key used to return the distance to the given coordinate. (optional). If specified, distances are returned in meters.
  • skip: The number of documents to skip in the query. (optional)
  • longitude: The longitude of the coordinate.
  • limit: The maximal amount of documents to return. The skip is applied before the limit restriction. The default is 100. (optional)
  • collection: The name of the collection to query.
  • latitude: The latitude of the coordinate.
  • geo: If given, the identifier of the geo-index to use. (optional)

The default will find at most 100 documents near the given coordinate. The returned array is sorted according to the distance, with the nearest document being first in the return array. If there are near documents of equal distance, documents are chosen randomly from this set until the limit is reached.

In order to use the near operator, a geo index must be defined for the collection. This index also defines which attribute holds the coordinates for the document. If you have more than one geo-spatial index, you can use the geo field to select a particular index.

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

Note: the near simple query is deprecated as of ArangoDB 2.6. This API may be removed in future versions of ArangoDB. The preferred way for retrieving documents from a collection using the near operator is to issue an AQL query using the NEAR function as follows: 

FOR doc IN NEAR(@@collection, @latitude, @longitude, @limit)
  RETURN doc`

Example:

Without distance

shell> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/near <<EOF
{ 
  "collection" : "products", 
  "latitude" : 0, 
  "longitude" : 0, 
  "skip" : 1, 
  "limit" : 2 
}
EOF

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

{ 
  "result" : [ 
    { 
      "_key" : "12441", 
      "_id" : "products/12441", 
      "_rev" : "_WQ47fgq--D", 
      "name" : "Name/0.002/", 
      "loc" : [ 
        0.002, 
        0 
      ] 
    }, 
    { 
      "_key" : "12435", 
      "_id" : "products/12435", 
      "_rev" : "_WQ47fgq--_", 
      "name" : "Name/-0.002/", 
      "loc" : [ 
        -0.002, 
        0 
      ] 
    } 
  ], 
  "hasMore" : false, 
  "count" : 2, 
  "error" : false, 
  "code" : 201 
}

Example:

With distance

shell> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/near <<EOF
{ 
  "collection" : "products", 
  "latitude" : 0, 
  "longitude" : 0, 
  "skip" : 1, 
  "limit" : 3, 
  "distance" : "distance" 
}
EOF

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

{ 
  "result" : [ 
    { 
      "distance" : 222.38985328911744, 
      "_id" : "products/12486", 
      "_key" : "12486", 
      "_rev" : "_WQ47fhq--D", 
      "loc" : [ 
        -0.002, 
        0 
      ], 
      "name" : "Name/-0.002/" 
    }, 
    { 
      "distance" : 222.38985328911744, 
      "_id" : "products/12492", 
      "_key" : "12492", 
      "_rev" : "_WQ47fhq--H", 
      "loc" : [ 
        0.002, 
        0 
      ], 
      "name" : "Name/0.002/" 
    }, 
    { 
      "distance" : 444.779706578235, 
      "_id" : "products/12483", 
      "_key" : "12483", 
      "_rev" : "_WQ47fhq--B", 
      "loc" : [ 
        -0.004, 
        0 
      ], 
      "name" : "Name/-0.004/" 
    } 
  ], 
  "hasMore" : false, 
  "count" : 3, 
  "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

Without distance

shell> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/near <<EOF
{ 
  "collection" : "products", 
  "latitude" : 0, 
  "longitude" : 0, 
  "skip" : 1, 
  "limit" : 2 
}
EOF

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

With distance

shell> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/near <<EOF
{ 
  "collection" : "products", 
  "latitude" : 0, 
  "longitude" : 0, 
  "skip" : 1, 
  "limit" : 3, 
  "distance" : "distance" 
}
EOF

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

Find documents within a radius around a coordinate

returns all documents of a collection within a given radius

PUT /_api/simple/within

A JSON object with these properties is required:

  • distance: If given, the attribute key used to return the distance to the given coordinate. (optional). If specified, distances are returned in meters.
  • skip: The number of documents to skip in the query. (optional)
  • longitude: The longitude of the coordinate.
  • radius: The maximal radius (in meters).
  • collection: The name of the collection to query.
  • latitude: The latitude of the coordinate.
  • limit: The maximal amount of documents to return. The skip is applied before the limit restriction. The default is 100. (optional)
  • geo: If given, the identifier of the geo-index to use. (optional)

This will find all documents within a given radius around the coordinate (latitude, longitude). The returned list is sorted by distance.

In order to use the within operator, a geo index must be defined for the collection. This index also defines which attribute holds the coordinates for the document. If you have more than one geo-spatial index, you can use the geo field to select a particular index.

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

Note: the within simple query is deprecated as of ArangoDB 2.6. This API may be removed in future versions of ArangoDB. The preferred way for retrieving documents from a collection using the near operator is to issue an AQL query using the WITHIN function as follows: 

FOR doc IN WITHIN(@@collection, @latitude, @longitude, @radius, @distanceAttributeName)
  RETURN doc

Example:

Without distance

shell> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/near <<EOF
{ 
  "collection" : "products", 
  "latitude" : 0, 
  "longitude" : 0, 
  "skip" : 1, 
  "limit" : 2, 
  "radius" : 500 
}
EOF

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

{ 
  "result" : [ 
    { 
      "_key" : "12854", 
      "_id" : "products/12854", 
      "_rev" : "_WQ47foi--_", 
      "name" : "Name/0.002/", 
      "loc" : [ 
        0.002, 
        0 
      ] 
    }, 
    { 
      "_key" : "12848", 
      "_id" : "products/12848", 
      "_rev" : "_WQ47foe--H", 
      "name" : "Name/-0.002/", 
      "loc" : [ 
        -0.002, 
        0 
      ] 
    } 
  ], 
  "hasMore" : false, 
  "count" : 2, 
  "error" : false, 
  "code" : 201 
}

Example:

With distance

shell> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/near <<EOF
{ 
  "collection" : "products", 
  "latitude" : 0, 
  "longitude" : 0, 
  "skip" : 1, 
  "limit" : 3, 
  "distance" : "distance", 
  "radius" : 300 
}
EOF

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

{ 
  "result" : [ 
    { 
      "distance" : 222.38985328911744, 
      "_id" : "products/12899", 
      "_key" : "12899", 
      "_rev" : "_WQ47fpW--B", 
      "loc" : [ 
        -0.002, 
        0 
      ], 
      "name" : "Name/-0.002/" 
    }, 
    { 
      "distance" : 222.38985328911744, 
      "_id" : "products/12905", 
      "_key" : "12905", 
      "_rev" : "_WQ47fpW--F", 
      "loc" : [ 
        0.002, 
        0 
      ], 
      "name" : "Name/0.002/" 
    }, 
    { 
      "distance" : 444.779706578235, 
      "_id" : "products/12896", 
      "_key" : "12896", 
      "_rev" : "_WQ47fpW--_", 
      "loc" : [ 
        -0.004, 
        0 
      ], 
      "name" : "Name/-0.004/" 
    } 
  ], 
  "hasMore" : false, 
  "count" : 3, 
  "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

Without distance

shell> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/near <<EOF
{ 
  "collection" : "products", 
  "latitude" : 0, 
  "longitude" : 0, 
  "skip" : 1, 
  "limit" : 2, 
  "radius" : 500 
}
EOF

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

With distance

shell> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/near <<EOF
{ 
  "collection" : "products", 
  "latitude" : 0, 
  "longitude" : 0, 
  "skip" : 1, 
  "limit" : 3, 
  "distance" : "distance", 
  "radius" : 300 
}
EOF

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

Within rectangle query

returns all documents of a collection within a rectangle

PUT /_api/simple/within-rectangle

A JSON object with these properties is required:

  • latitude1: The latitude of the first rectangle coordinate.
  • skip: The number of documents to skip in the query. (optional)
  • latitude2: The latitude of the second rectangle coordinate.
  • longitude2: The longitude of the second rectangle coordinate.
  • longitude1: The longitude of the first rectangle coordinate.
  • limit: The maximal amount of documents to return. The skip is applied before the limit restriction. The default is 100. (optional)
  • collection: The name of the collection to query.
  • geo: If given, the identifier of the geo-index to use. (optional)

This will find all documents within the specified rectangle (determined by the given coordinates (latitude1, longitude1, latitude2, longitude2).

In order to use the within-rectangle query, a geo index must be defined for the collection. This index also defines which attribute holds the coordinates for the document. If you have more than one geo-spatial index, you can use the geo field to select a particular index.

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

Example:

shell> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/within-rectangle <<EOF
{ 
  "collection" : "products", 
  "latitude1" : 0, 
  "longitude1" : 0, 
  "latitude2" : 0.2, 
  "longitude2" : 0.2, 
  "skip" : 1, 
  "limit" : 2 
}
EOF

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

{ 
  "result" : [ 
    { 
      "_key" : "12965", 
      "_id" : "products/12965", 
      "_rev" : "_WQ47fqO--F", 
      "name" : "Name/0.008/", 
      "loc" : [ 
        0.008, 
        0 
      ] 
    }, 
    { 
      "_key" : "12962", 
      "_id" : "products/12962", 
      "_rev" : "_WQ47fqO--D", 
      "name" : "Name/0.006/", 
      "loc" : [ 
        0.006, 
        0 
      ] 
    } 
  ], 
  "hasMore" : false, 
  "count" : 2, 
  "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

shell> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/within-rectangle <<EOF
{ 
  "collection" : "products", 
  "latitude1" : 0, 
  "longitude1" : 0, 
  "latitude2" : 0.2, 
  "longitude2" : 0.2, 
  "skip" : 1, 
  "limit" : 2 
}
EOF

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

Fulltext index query

returns documents of a collection as a result of a fulltext query

PUT /_api/simple/fulltext

A JSON object with these properties is required:

  • index: The identifier of the fulltext-index to use.
  • attribute: The attribute that contains the texts.
  • collection: The name of the collection to query.
  • limit: The maximal amount of documents to return. The skip is applied before the limit restriction. (optional)
  • skip: The number of documents to skip in the query (optional).
  • query: The fulltext query. Please refer to Fulltext queries for details.

This will find all documents from the collection that match the fulltext query specified in query.

In order to use the fulltext operator, a fulltext index must be defined for the collection and the specified attribute.

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

Note: the fulltext simple query is deprecated as of ArangoDB 2.6. This API may be removed in future versions of ArangoDB. The preferred way for retrieving documents from a collection using the near operator is to issue an AQL query using the FULLTEXT AQL function as follows:

FOR doc IN FULLTEXT(@@collection, @attributeName, @queryString, @limit) 
  RETURN doc

Example:

shell> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/fulltext <<EOF
{ 
  "collection" : "products", 
  "attribute" : "text", 
  "query" : "word" 
}
EOF

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

{ 
  "result" : [ 
    { 
      "_key" : "12326", 
      "_id" : "products/12326", 
      "_rev" : "_WQ47feO--_", 
      "text" : "this text contains word" 
    }, 
    { 
      "_key" : "12330", 
      "_id" : "products/12330", 
      "_rev" : "_WQ47feS--_", 
      "text" : "this text also has a word" 
    } 
  ], 
  "hasMore" : false, 
  "count" : 2, 
  "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

shell> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/fulltext <<EOF
{ 
  "collection" : "products", 
  "attribute" : "text", 
  "query" : "word" 
}
EOF

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

© ArangoDB - the native multi-model NoSQL database