Query Cursors Examples

This API is used to execute queries directly on the ArangoDB database.

Query Cursor Normal Request

{
  "query": "FOR t IN things FILTER HAS(t.properties, @property_name) RETURN t._key",
  "count": true,
  "batchSize": 2,
  "bindVars": {
    "property_name": "cpu"
  }
}

In this request we find out multiple attributes:

query: Contains the query string to be executed. Only read-only queries are allowed.
count: This is a boolean attribute. If we set it to true, the response will return a "count" field, with the total number of elements in the database that match the query sent.
batchSize: Indicates the maximum number of results we want to be returned.
bindVars: Key/values pair representing the bind parameters in the query. In this example @property_name.

There are more parameters that can be sent in the request, which you can find in the API.

With the request sent above a possible answer that you can obtain is the following:

{
  "code": 201,
  "count": 3,
  "error": false,
  "extra": {
    "stats": {
      "executionTime": 0.006785640027374029,
      "peakMemoryUsage": 32768
    }
  },
  "hasMore": true,
  "id": "9895653453478",
  "result": [
    "01H416JXT187JZ8R58NYW6GN97",
    "01H416KYGQ0X22HKAY0KCXEM9J"
  ]
}

Here, multiple attributes are returned:

code: Indicates the HTTP status code of the response.
count: Total number of elements in the database that match the query sent.
error: A boolean attribute that indicates if there has been any error executing the request.
extra: An optional JSON object with extra information about the query result contained in its stats sub-attribute.
hasMore: Boolean attribute that indicates if there are more results available for the cursor on the server.
id: Temporary cursor id that is returned if there is more available data. It can be used on the /spaces/{space}/query/cursor/{cursor-id} endpoint.
result: Array of result data expected from the query sent.

Query Cursor with Operations to Apply

Operations can be applied to the results returned but only on Things.

{
  "query": "FOR t IN things FILTER HAS(t.properties, @property_name) RETURN t._key",
  "count": true,
  "batchSize": 2,
  "bindVars": {
    "property_name": "cpu"
  },
  "then": {
    "op": "update",
    "resource": "properties",
    "data": {
      "cpu": 10
    }
  }
}

There is a new attribute in the request called then, with the following parameters:

op: Indicates the type of operation that we want to execute. In this case, we want to update a Thing.
resource: Indicate on which resource you want to apply the indicated "op". In this case, we are updating the Properties of the Things.
data: Data to be sent. In this case, we indicate the new cpu value.

The response will be as follows:

{
  "code": 201,
  "count": 3,
  "error": false,
  "extra": {
    "stats": {
      "executionTime": 0.0069512189365923405,
      "peakMemoryUsage": 32768
    }
  },
  "hasMore": true,
  "id": "9895653458933",
  "result": [
    "01GZG7BNXKECSVFENWDVZT0FA0",
    "01H416JXT187JZ8R58NYW6GN97"
  ],
  "then": {
    "error_count": 0,
    "success_count": 2
  }
}

There is a new attribute in the response called then, and it has 2 parameters:

error_count: Number of failed operations. In this case, number of things that have not been updated.
success_count: Number of succeeded operations. In this case, the number of Things updated correctly.

Query Cursors to Return Linked Things

Since ArangoDB is a graph database, this functionality has been included for the Links of the Things, so every time a Link of a Thing points to another Thing, a connection between them will be created.

The following example shows which Things are linked to each other:

{
	"query": "FOR l in links FILTER l._from == @from RETURN l._to",
	"count": true,
	"bindVars": {
		"from": "things/01H4G9T37EYV2BQ0GXRV7V2MMG"
	}
}

The response will be as follows, with the result parameters containing all the Things IDs that matched the previous request:

{
    "result": [
        "things/01H4G4CWKPBZE6GY2SECA88RYJ",
        "things/01H4G4CYRHTNT3XSJ2XZHY9Z4R"
    ],
    "hasMore": false,
    "count": 2,
    "extra": {
        "stats": {
            "executionTime": 0.00025816199922701344,
            "peakMemoryUsage": 32768
        }
    },
    "error": false,
    "code": 201
}