The cursor object of the JavaScript API

The JavaScript API returns cursor objects when you use the following methods of the db object from the @arangodb module in arangosh, as well as in server-side JavaScript contexts if the stream query option is enabled:

• db._query(...)
• db._createStatement(...).execute()

If a query returns a cursor, then you can use the hasNext() and next() methods to iterate over the results, or toArray() to convert them 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 statement is executed using its execute() method. If no batchSize value is specified, the server picks a reasonable default value. If the server has more documents than should be returned in a single batch, the server sets the hasMore attribute in the result. It also returns the ID of the server-side cursor in the id attribute in the response. This ID can be used with the Cursor API to fetch any outstanding results from the server and dispose the server-side cursor afterwards.

cursor.hasNext()

Checks if the cursor is exhausted.

The hasNext() method returns true, then the cursor still has documents. In this case the next document can be accessed using the next operator, which advances the cursor.

Examples

var cursor = db._query("FOR x IN five RETURN x");
while (cursor.hasNext()) {
  print(cursor.next());
}

{ 
  "_key" : "71092", 
  "_id" : "five/71092", 
  "_rev" : "_hg5kz0O---", 
  "name" : "one" 
}
{ 
  "_key" : "71094", 
  "_id" : "five/71094", 
  "_rev" : "_hg5kz0O--_", 
  "name" : "two" 
}
{ 
  "_key" : "71096", 
  "_id" : "five/71096", 
  "_rev" : "_hg5kz0O--A", 
  "name" : "three" 
}
{ 
  "_key" : "71098", 
  "_id" : "five/71098", 
  "_rev" : "_hg5kz0O--B", 
  "name" : "four" 
}
{ 
  "_key" : "71100", 
  "_id" : "five/71100", 
  "_rev" : "_hg5kz0S---", 
  "name" : "five" 
}

cursor.next()

Returns the next result document.

If the hasNext() method 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() method, which advances the underlying cursor. If you use next() on an exhausted cursor, then undefined is returned.

Examples

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

{ 
  "_key" : "71231", 
  "_id" : "five/71231", 
  "_rev" : "_hg5kz9W---", 
  "name" : "one" 
}

cursor.dispose()

Disposes the cursor and its results.

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.

cursor.count()

Counts the number of documents in the result set and returns that number. The count() method ignores any limits and returns the total number of documents found.

cursor.count(true)

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