ArangoDB Manual Pages


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.

PUT /_api/simple/all
(executes simple query "all")
PUT /_api/simple/all
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 Interface for AQL Query Cursors for details.
Examples
Limit the amount of documents using limit
> curl --data @- -X PUT --dump - http://localhost:8529/_api/simple/all
{ "collection" : "4421689145", "skip" : 2900, "limit" : 2 }

HTTP/1.1 201 Created
content-type: application/json

{
  "code": 201,
  "hasMore": false,
  "result": [
    {
      "n": 1679,
      "_rev": "4533165881",
      "_id": "4421689145/4533165881"
    },
    {
      "n": 679,
      "_rev": "4467629881",
      "_id": "4421689145/4467629881"
    }
  ],
  "count": 2,
  "error": false
}
Using a batchSize value
> curl --data @- -X PUT --dump - http://localhost:8529/_api/simple/all
{ "collection" : "4421689145", "batchSize" : 2 }

HTTP/1.1 201 Created
content-type: application/json

{
  "code": 201,
  "hasMore": true,
  "result": [
    {
      "n": 1679,
      "_rev": "4533165881",
      "_id": "4421689145/4533165881"
    },
    {
      "n": 679,
      "_rev": "4467629881",
      "_id": "4421689145/4467629881"
    }
  ],
  "id":142116766,
  "count": 3000,
  "error": false
}

PUT /_api/simple/by-example
(executes simple query "by-example")
PUT /_api/simple/by-example
This will find all documents matching a given example.The call expects a JSON hash array as body with the following attributes:
  • collection: The name of the collection to query.
  • example: The example.
  • skip: The documents to skip in the query. (optional)
  • limit: The maximal amount of documents to return. (optional)
Returns a cursor containing the result, see HTTP Interface for AQL Query Cursors for details.
Examples
Matching an attribute:
> curl --data @- -X PUT --dump - http://localhost:8529/_api/simple/by-example
{ "collection" : "3179705695", "example" : [ { "i" : 1 } ] }

HTTP/1.1 201 Created
content-type: application/json

{
  "result": [
    { "a": { "k": 2, "j": 2 }, "i": 1, "_rev": "3181802847", "_id": "3179705695/3181802847" },
    { "a": { "j": 1 }, "i": 1, "_rev": "3181475167", "_id": "3179705695/3181475167" },
    { "a": { "k": 1, "j": 1 }, "i": 1, "_rev": "3181737311", "_id": "3179705695/3181737311" },
    { "i": 1, "_rev": "3181147487", "_id": "3179705695/3181147487" }
  ],
  "count": 4,
  "error": false,
  "hasMore": false,
  "code": 201
}
Matching an attribute which is a sub-document:
> curl --data @- -X PUT --dump - http://localhost:8529/_api/simple/by-example
{ "collection" : "3179705695", "example" : [ { "a" : { "j" : 1 } } ] }

HTTP/1.1 201 Created
content-type: application/json

{
  "result": [
    { "a": { "j": 1 }, "i": 1, "_rev": "3181475167", "_id": "3179705695/3181475167" }
  ],
  "count": 1,
  "error": false,
  "hasMore": false,
  "code": 201
}
Matching an attribute within a sub-document:
> curl --data @- -X PUT --dump - http://localhost:8529/_api/simple/by-example
{ "collection" : "3179705695", "example" : [ "a.j", 1 ] }

HTTP/1.1 201 Created
content-type: application/json

{
  "result": [
    { "a": { "j": 1 }, "i": 1, "_rev": "3181475167", "_id": "3179705695/3181475167" },
    { "a": { "k": 1, "j": 1 }, "i": 1, "_rev": "3181737311", "_id": "3179705695/3181737311" }
  ],
  "count": 2,
  "error": false,
  "hasMore": false,
  "code": 201
}

PUT /_api/simple/first-example
(executes simple query "first-example")
PUT /_api/simple/first-example
This will return the first document matching a given example.The call expects a JSON hash array as body with the following attributes:
  • collection: The name of the collection to query.
  • example: The example.
Returns a result containing the document or HTTP 404 if no document matched the example.
Examples
If a matching document was found:
> curl --data @- -X PUT --dump - http://localhost:8529/_api/simple/first-example
{ "collection" : "666351134", "example" : [ "a.j", 1, "a.k", 1 ] }

HTTP/1.1 200 OK
content-type: application/json

{
  "error": false,
  "code": 200,
  "document": { "_rev": "668382750", "_id": "666351134/668382750", "a": { "k": 1, "j": 1, "l" : 10 }, "i": 1 }
}
If no document was found:
> curl --data @- -X PUT --dump - http://localhost:8529/_api/simple/first-example
{ "collection" : "666351134", "example" : [ "a.j", 1, "a.k", 2 ] }

HTTP/1.1 404 Not Found
content-type: application/json

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

PUT /_api/simple/any
(executes simple query "any")
PUT /_api/simple/any
Returns a random document of a collection. The call expects a JSON object as body with the following attributes:
  • 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 attrbute contains null.
Examples
> curl --data @- -X PUT --dump - http://localhost:8529/_api/simple/any
{ "collection" : 222186062247 }
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
content-length: 114
{
"document": {
"_id": "222186062247/223172116903",
"_rev": 223172116903,
"Hello": "World"
},
"error": false,
"code":200
}

PUT /_api/simple/range
(executes simple range query)
PUT /_api/simple/range
This will find all documents within a given range. You must declare a skip-list index on the attribute in order to be able to use a range query.The call expects a JSON hash array as body with the following attributes:
  • collection: The name of the collection to query.
  • attribute: The attribute path to check.
  • left: The lower bound.
  • right: The upper bound.
  • closed: If true, use interval including left and right, otherwise exclude right, but include left.
  • skip: The documents to skip in the query. (optional)
  • limit: The maximal amount of documents to return. (optional)
Returns a cursor containing the result, see HTTP Interface for AQL Query Cursors for details.
Examples
> curl --data @- -X PUT --dump - http://localhost:8529/_api/simple/range
{ "collection" : "6328369086", "attribute" : "i", "left" : 2, "right" : 4 }

HTTP/1.1 201 Created
content-type: application/json

{
  "code": 201,
  "result": [
    { "_id": "6328369086/6329876414", "i": 2, "_rev": "6329876414" },
    { "_id": "6328369086/6329941950", "i": 3, "_rev": "6329941950" }
  ],
  "count": 2,
  "hasMore": false,
  "error": false
}

PUT /_api/simple/near
(executes simple query "near")
PUT /_api/simple/near
The default will find at most 100 documents near a given coordinate. The returned list is sorted according to the distance, with the nearest document coming first. 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 then one geo-spatial index, you can use the geo field to select a particular index.The call expects a JSON hash array as body with the following attributes:
  • collection: The name of the collection to query.
  • latitude: The latitude of the coordinate.
  • longitude: The longitude of the coordinate.
  • distance: If given, the attribute key used to store the distance. (optional)
  • 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. The default is 100. (optional)
  • geo: If given, the identifier of the geo-index to use. (optional)
Returns a cursor containing the result, see HTTP Interface for AQL Query Cursors for details.
Examples
Without distance:
> curl --data @- -X PUT --dump - http://localhost:8529/_api/simple/near
{ "collection" : "11172897562", "latitude" : 0, "longitude" : 0, "skip" : 1, "limit" : 2 }

HTTP/1.1 201 Created
content-type: application/json

{
  "hasMore": false,
  "count": 5,
  "result": [
    {
      "_id": "11172897562/11178271514",
      "loc": [ 0, -10 ],
      "_rev": "11178271514"
    },
    {
      "_id": "11172897562/11177616154",
      "loc": [ -10, 0 ],
      "_rev": "11177616154"
    }
  ],
  "code": 201,
  "error": false
}
With distance:
> curl --data @- -X PUT --dump - http://localhost:8529/_api/simple/near
{ "collection" : "11182465818", "latitude" : 0, "longitude" : 0, "limit" : 2, "distance" : "distance" }

HTTP/1.1 201 Created
content-type: application/json

{
  "hasMore": false,
  "count": 5,
  "result": [
    {
      "distance": 0,
      "_id": "11182465818/11187905306",
      "loc": [ 0, 0 ],
      "_rev": "11187905306"
    },
    {
      "distance": 1111949.26644559,
      "_id": "11182465818/11187839770",
      "loc": [ 0, -10 ],
      "_rev": "11187839770"
    }
  ],
  "code": 201,
  "error": false
}

PUT /_api/simple/within
(executes simple query "within")
PUT /_api/simple/within
This will find all documents with in 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 then one geo-spatial index, you can use the geo field to select a particular index.The call expects a JSON hash array as body with the following attributes:
  • collection: The name of the collection to query.
  • latitude: The latitude of the coordinate.
  • longitude: The longitude of the coordinate.
  • radius: The maximal radius (in meters).
  • distance: If given, the result attribute key used to store the distance values (optional). If specified, distances are returned in meters.
  • skip: The documents to skip in the query. (optional)
  • limit: The maximal amount of documents to return. (optional)
  • geo: If given, the identifier of the geo-index to use. (optional)
Returns a cursor containing the result, see HTTP Interface for AQL Query Cursors for details.
Examples
Without distance:
> curl --data @- -X PUT --dump - http://localhost:8529/_api/simple/within
{ "collection" : "2076584128", "latitude" : 0, "longitude" : 0, "skip" : 1, "radius" : 1111950 }

HTTP/1.1 201 Created
content-type: application/json

{
  "result": [
    {
      "_id": "2076584128/2082744512",
      "loc": [ 10, 0 ],
      "_rev": "2082744512"
    },
    {
      "_id": "2076584128/2082089152",
      "loc": [ 0, 10 ],
      "_rev": "2082089152"
    },
    {
      "_id": "2076584128/2081302720",
      "loc": [ -10, 0 ],
      "_rev": "2081302720"
    },
    {
      "_id": "2076584128/2081958080",
      "loc": [ 0, -10 ],
      "_rev": "2081958080"
    }
  ],
  "code": 201,
  "hasMore": false,
  "count": 4,
  "error": false
}
With distance:
> curl --data @- -X PUT --dump - http://localhost:8529/_api/simple/within
{ "collection" : "2086152384", "latitude" : 0, "longitude" : 0, "distance" : "distance", "radius" : 1111950 }

HTTP/1.1 201 Created
content-type: application/json

{
  "result": [
    {
      "distance": 0,
      "_id": "2086152384/2091591872",
      "loc": [ 0, 0 ],
      "_rev": "2091591872"
    },
    {
      "distance": 1111949.26644559,
      "_id": "2086152384/2090870976",
      "loc": [ -10, 0 ],
      "_rev": "2090870976"
    },
    {
      "distance": 1111949.26644559,
      "_id": "2086152384/2091657408",
      "loc": [ 0, 10 ],
      "_rev": "2091657408"
    },
    {
      "distance": 1111949.26644559,
      "_id": "2086152384/2092312768",
      "loc": [ 10, 0 ],
      "_rev": "2092312768"
    },
    {
      "distance": 1111949.26644559,
      "_id": "2086152384/2091526336",
      "loc": [ 0, -10 ],
      "_rev": "2091526336"
    }
  ],
  "code": 201,
  "hasMore": false,
  "count": 5,
  "error": false
}

PUT /_api/simple/fulltext
(executes simple query "fulltext")
PUT /_api/simple/fulltext
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.The call expects a JSON hash array as body with the following attributes:
  • collection: The name of the collection to query.
  • attribute: The attribute that contains the texts.
  • query: The fulltext query.
  • skip: The documents to skip in the query. (optional)
  • limit: The maximal amount of documents to return. (optional)
  • index: If given, the identifier of the fulltext-index to use. (optional)
Returns a cursor containing the result, see HTTP Interface for AQL Query Cursors for details.
Examples
> curl --data @- -X PUT --dump - http://localhost:8529/_api/simple/fulltext
{ "collection" : "2076584128", "attribute" : "text", "query" : "word" }

HTTP/1.1 201 Created
content-type: application/json

{
  "result": [
    {
      "_id": "2076584128/2082744512",
      "text" : "this text contains a word",
      "_rev": "2082744512"
    },
    {
      "_id": "2076584128/2082089152",
      "text" : "this text also contains a word",
      "loc": [ 0, 10 ],
      "_rev": "2082089152"
    }
  ],
  "code": 201,
  "hasMore": false,
  "count": 2,
  "error": false
}

PUT /_api/simple/remove-by-example
(removes documents by example)
PUT /_api/simple/remove-by-example
This will find all documents in the collection that match the specified example object.The call expects a JSON hash array as body with the following attributes:
  • collection: The name of the collection to remove from.
  • example: An example object that all collection objects are compared against.
  • waitForSync: if set to true, then all removal operations will instantly be synchronised to disk. If this is not specified, then the collection's default sync behavior will be applied.
  • 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.
Returns the number of documents that were deleted
Examples
> curl --data @- -X PUT --dump - http://localhost:8529/_api/simple/remove-by-example
{ "collection" : "test", "example" : { "age" : 37, "likes" : "tennis" } }

HTTP/1.1 200 Ok
content-type: application/json

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

PUT /_api/simple/replace-by-example
(replaces documents by example)
PUT /_api/simple/replace-by-example
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.The call expects a JSON hash array as body with the following attributes:
  • collection: The name of the collection to replace within.
  • example: An example object that all collection objects are compared against.
  • newValue: The replacement document that will get inserted in place of the "old" documents.
  • waitForSync: if set to true, then all removal operations will instantly be synchronised to disk. If this is not specified, then the collection's default sync behavior will be applied.
  • 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.
Returns the number of documents that were replaced
Examples
> curl --data @- -X PUT --dump - http://localhost:8529/_api/simple/replace-by-example
{ "collection" : "test", "example" : { "age" : 37, "likes" : "tennis" }, "newValue" : { "foo" : "bar" }, "limit" : 3 }

HTTP/1.1 200 Ok
content-type: application/json

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

PUT /_api/simple/update-by-example
(updates documents by example)
PUT /_api/simple/update-by-example
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.The call expects a JSON hash array as body with the following attributes:
  • collection: The name of the collection to update within.
  • example: An example object that all collection objects are compared against.
  • newValue: The update value that will get inserted in place of the "old" version of the found documents.
  • 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.
  • waitForSync: if set to true, then all removal operations will instantly be synchronised to disk. If this is not specified, then the collection's default sync behavior will be applied.
  • 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.
Returns the number of documents that were updated
Examples
> curl --data @- -X PUT --dump - http://localhost:8529/_api/simple/update-by-example
{ "collection" : "test", "example" : { "age" : 37, "likes" : "tennis" }, "newValue" : { "age" : null, "likes" : "foo" }, "keepNull" : false }

HTTP/1.1 200 Ok
content-type: application/json

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