Cursor API

Cursor instances provide an abstraction over the HTTP API’s limitations. Unless a method explicitly exhausts the cursor, the driver will only fetch as many batches from the server as necessary. Like the server-side cursors, Cursor instances are incrementally depleted as they are read from.

const db = new Database();
const cursor = await db.query(aql`FOR x IN 1..5 RETURN x`);
// query result list: [1, 2, 3, 4, 5]
const value = await cursor.next();
assert.equal(value, 1);
// remaining result list: [2, 3, 4, 5]

cursor.count

cursor.count: number

The total number of documents in the query result. This is only available if the count option was used.

cursor.all

async cursor.all(): Array<Object>

Exhausts the cursor, then returns an array containing all values in the cursor’s remaining result list.

Examples

const cursor = await db.query(aql`FOR x IN 1..5 RETURN x`);
const result = await cursor.all();
// result is an array containing the entire query result
assert.deepEqual(result, [1, 2, 3, 4, 5]);
assert.equal(cursor.hasNext(), false);

cursor.next

async cursor.next(): Object

Advances the cursor and returns the next value in the cursor’s remaining result list. If the cursor has already been exhausted, returns undefined instead.

Examples

// query result list: [1, 2, 3, 4, 5]
const val = await cursor.next();
assert.equal(val, 1);
// remaining result list: [2, 3, 4, 5]

const val2 = await cursor.next();
assert.equal(val2, 2);
// remaining result list: [3, 4, 5]

cursor.hasNext

cursor.hasNext(): boolean

Returns true if the cursor has more values or false if the cursor has been exhausted.

Examples

await cursor.all(); // exhausts the cursor
assert.equal(cursor.hasNext(), false);

cursor.nextBatch

async cursor.nextBatch(): Object

Advances the cursor and returns all remaining values in the cursor’s current batch. If the current batch has already been exhausted, fetches the next batch from the server and returns it. If no more batches are available, returns undefined instead.

Examples

const cursor = await db.query(aql`FOR i IN 1..10 RETURN i`, { batchSize: 5 });
await cursor.nextBatch(); // [1, 2, 3, 4, 5]
await cursor.next(); // 6
await cursor.nextBatch(); // [7, 8, 9, 10]
cursor.hasNext(); // false

cursor.each

async cursor.each(fn): any

Advances the cursor by applying the function fn to each value in the cursor’s remaining result list until the cursor is exhausted or fn explicitly returns false.

Returns the last return value of fn.

Equivalent to Array.prototype.forEach (except async).

Arguments

Examples

const results = [];
function doStuff(value) {
  const VALUE = value.toUpperCase();
  results.push(VALUE);
  return VALUE;
}

const cursor = await db.query(aql`FOR x IN ["a", "b", "c"] RETURN x`);
const last = await cursor.each(doStuff);
assert.deepEqual(results, ["A", "B", "C"]);
assert.equal(cursor.hasNext(), false);
assert.equal(last, "C");

cursor.every

async cursor.every(fn): boolean

Advances the cursor by applying the function fn to each value in the cursor’s remaining result list until the cursor is exhausted or fn returns a value that evaluates to false.

Returns false if fn returned a value that evaluates to false, or true otherwise.

Equivalent to Array.prototype.every (except async).

Arguments

const even = value => value % 2 === 0;

const cursor = await db.query(aql`FOR x IN 2..5 RETURN x`);
const result = await cursor.every(even);
assert.equal(result, false); // 3 is not even
assert.equal(cursor.hasNext(), true);

const value = await cursor.nextBatch();
assert.equal(value, 4); // next value after 3

cursor.some

async cursor.some(fn): boolean

Advances the cursor by applying the function fn to each value in the cursor’s remaining result list until the cursor is exhausted or fn returns a value that evaluates to true.

Returns true if fn returned a value that evaluates to true, or false otherwise.

Equivalent to Array.prototype.some (except async).

Examples

const even = value => value % 2 === 0;

const cursor = await db.query(aql`FOR x IN 1..5 RETURN x`);
const result = await cursor.some(even);
assert.equal(result, true); // 2 is even
assert.equal(cursor.hasNext(), true);

const value = await cursor.next();
assert.equal(value, 3); // next value after 2

cursor.map

async cursor.map(fn): Array<any>

Advances the cursor by applying the function fn to each value in the cursor’s remaining result list until the cursor is exhausted.

Returns an array of the return values of fn.

Equivalent to Array.prototype.map (except async).

Note: This creates an array of all return values. It is probably a bad idea to do this for very large query result sets.

Arguments

Examples

const square = value => value * value;
const cursor = await db.query(aql`FOR x IN 1..5 RETURN x`);
const result = await cursor.map(square);
assert.equal(result.length, 5);
assert.deepEqual(result, [1, 4, 9, 16, 25]);
assert.equal(cursor.hasNext(), false);

cursor.reduce

async cursor.reduce(fn, [accu]): any

Exhausts the cursor by reducing the values in the cursor’s remaining result list with the given function fn. If accu is not provided, the first value in the cursor’s remaining result list will be used instead (the function will not be invoked for that value).

Equivalent to Array.prototype.reduce (except async).

Arguments

Examples

const add = (a, b) => a + b;
const baseline = 1000;

const cursor = await db.query(aql`FOR x IN 1..5 RETURN x`);
const result = await cursor.reduce(add, baseline);
assert.equal(result, baseline + 1 + 2 + 3 + 4 + 5);
assert.equal(cursor.hasNext(), false);

// -- or --

const result = await cursor.reduce(add);
assert.equal(result, 1 + 2 + 3 + 4 + 5);
assert.equal(cursor.hasNext(), false);

cursor.kill

async cursor.kill(): void

Kills the cursor and frees up associated database resources.

This method has no effect if all result batches have already been fetched.

Examples

const cursor = await db.query(aql`FOR x IN 1..5 RETURN x`);
await cursor.kill(); // has no effect

const cursor2 = await db.query(aql`FOR x IN 1..5 RETURN x`, { batchSize: 2 });
await cursor2.kill(); // this kills the cursor