Sequential Access and Cursors

Sequential Access and Cursors

If a query returns a cursor (for example by calling db._query(...)), then you can use hasNext and next to iterate over the result set or toArray to convert it to an array.

If the number of query results is expected to be big, it is possible to limit the amount of documents transferred between the server and the client to a specific value. This value is called batchSize. The batchSize can optionally be set when a query is executed using its execute method. If no batchSize value is specified, the server will pick 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.

Has Next

checks if the cursor is exhausted cursor.hasNext()

The hasNext operator returns true, then the cursor still has documents. In this case the next document can be accessed using the next operator, which will advance the cursor.

Examples

arangosh> var a = db._query("FOR x IN five RETURN x");
arangosh> while (a.hasNext()) print(a.next());

Show execution results

Hide execution results

{ 
  "_key" : "70752", 
  "_id" : "five/70752", 
  "_rev" : "_cuv9bcq---", 
  "name" : "one" 
}
{ 
  "_key" : "70754", 
  "_id" : "five/70754", 
  "_rev" : "_cuv9bcq--_", 
  "name" : "two" 
}
{ 
  "_key" : "70756", 
  "_id" : "five/70756", 
  "_rev" : "_cuv9bcu---", 
  "name" : "three" 
}
{ 
  "_key" : "70758", 
  "_id" : "five/70758", 
  "_rev" : "_cuv9bcy---", 
  "name" : "four" 
}
{ 
  "_key" : "70760", 
  "_id" : "five/70760", 
  "_rev" : "_cuv9bcy--_", 
  "name" : "five" 
}

returns the next result document cursor.next()

If the hasNext operator returns true, then the underlying cursor of the AQL query still has documents. In this case the next document can be accessed using the next operator, which will advance the underlying cursor. If you use next on an exhausted cursor, then undefined is returned.

Examples

arangosh> db._query("FOR x IN five RETURN x").next();

Show execution results

Hide execution results

{ 
  "_key" : "70771", 
  "_id" : "five/70771", 
  "_rev" : "_cuv9bdK--_", 
  "name" : "one" 
}

Execute Query

executes a query query.execute(batchSize)

Executes an AQL query. If the optional batchSize value is specified, the server will return at most batchSize values in one roundtrip. The batchSize cannot be adjusted after the query is first executed.

Note: There is no need to explicitly call the execute method if another means of fetching the query results is chosen. The following two approaches lead to the same result:

arangosh> var result = db.users.all().toArray();
........> print(result);
........> var q = db._query("FOR x IN users RETURN x");
........> result = [ ];
........> while (q.hasNext()) {
........>   result.push(q.next());
........> }
........> print(result);

Show execution results

Hide execution results

[ 
  { 
    "_key" : "71404", 
    "_id" : "users/71404", 
    "_rev" : "_cuv9brC--_", 
    "name" : "Gerhard" 
  }, 
  { 
    "_key" : "71406", 
    "_id" : "users/71406", 
    "_rev" : "_cuv9brG---", 
    "name" : "Helmut" 
  }, 
  { 
    "_key" : "71408", 
    "_id" : "users/71408", 
    "_rev" : "_cuv9brG--_", 
    "name" : "Angela" 
  } 
]
[ 
  { 
    "_key" : "71404", 
    "_id" : "users/71404", 
    "_rev" : "_cuv9brC--_", 
    "name" : "Gerhard" 
  }, 
  { 
    "_key" : "71406", 
    "_id" : "users/71406", 
    "_rev" : "_cuv9brG---", 
    "name" : "Helmut" 
  }, 
  { 
    "_key" : "71408", 
    "_id" : "users/71408", 
    "_rev" : "_cuv9brG--_", 
    "name" : "Angela" 
  } 
]

The following two alternatives both use a batch size and return the same result:

arangosh> var result = [ ];
........> var q = db.users.all();
........> q.execute(1);
........> while(q.hasNext()) {
........>   result.push(q.next());
........> }
........> print(result);
........> result = [ ];
........> q = db._query("FOR x IN users RETURN x", {}, { batchSize: 1 });
........> while (q.hasNext()) {
........>   result.push(q.next());
........> }
........> print(result);

Show execution results

Hide execution results

[ 
  { 
    "_key" : "71385", 
    "_id" : "users/71385", 
    "_rev" : "_cuv9bqi---", 
    "name" : "Gerhard" 
  }, 
  { 
    "_key" : "71387", 
    "_id" : "users/71387", 
    "_rev" : "_cuv9bqi--_", 
    "name" : "Helmut" 
  }, 
  { 
    "_key" : "71389", 
    "_id" : "users/71389", 
    "_rev" : "_cuv9bqm---", 
    "name" : "Angela" 
  } 
]
[ 
  { 
    "_key" : "71385", 
    "_id" : "users/71385", 
    "_rev" : "_cuv9bqi---", 
    "name" : "Gerhard" 
  }, 
  { 
    "_key" : "71387", 
    "_id" : "users/71387", 
    "_rev" : "_cuv9bqi--_", 
    "name" : "Helmut" 
  }, 
  { 
    "_key" : "71389", 
    "_id" : "users/71389", 
    "_rev" : "_cuv9bqm---", 
    "name" : "Angela" 
  } 
]

Dispose

disposes the result cursor.dispose()

If you are no longer interested in any further results, you should call dispose in order to free any resources associated with the cursor. After calling dispose you can no longer access the cursor.

Count

counts the number of documents cursor.count()

The count operator counts the number of document in the result set and returns that number. The count operator ignores any limits and returns the total number of documents found.

cursor.count(true)

If the result set was limited by the limit operator or documents were skipped using the skip operator, the count operator with argument true will use the number of elements in the final result set - after applying limit and skip.