Class ArrayCursor<T>

A BatchedArrayCursor providing batch-wise access to the cursor result set.

See also BatchedArrayCursor#items.

Total number of documents in the query result. Only available if the count option was used.

Additional information about the cursor.

Whether the cursor has more values. If set to false, the cursor has already been depleted and contains no more items.

Enables use with for await to deplete the cursor by asynchronously yielding every value in the cursor's remaining result set.

Note: If the result set spans multiple batches, any remaining batches will only be fetched on demand. Depending on the cursor's TTL and the processing speed, this may result in the server discarding the cursor before it is fully depleted.

Example

const cursor = await db.query(aql`
  FOR user IN users
  FILTER user.isActive
  RETURN user
`);
for await (const user of cursor) {
  console.log(user.email, user.isAdmin);
}
Copy

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

Example

const cursor = await db.query(aql`FOR x IN 1..5 RETURN x`);
const result = await cursor.all(); // [1, 2, 3, 4, 5]
console.log(cursor.hasNext); // false
Copy

Depletes the cursor by applying the callback function to each item in the cursor's remaining result list. Returns an array containing the return values of callback for each item, flattened to a depth of 1.

Note: If the result set spans multiple batches, any remaining batches will only be fetched on demand. Depending on the cursor's TTL and the processing speed, this may result in the server discarding the cursor before it is fully depleted.

See also: Array.prototype.flatMap.

Example

const cursor = await db.query(aql`FOR x IN 1..5 RETURN x`);
const squares = await cursor.flatMap((currentValue) => {
  return [currentValue, currentValue ** 2];
});
console.log(squares); // [1, 1, 2, 4, 3, 9, 4, 16, 5, 25]
console.log(cursor.hasNext); // false
Copy

Example

const cursor = await db.query(aql`FOR x IN 1..5 RETURN x`);
const odds = await cursor.flatMap((currentValue) => {
  if (currentValue % 2 === 0) {
    return []; // empty array flattens into nothing
  }
  return currentValue; // or [currentValue]
});
console.logs(odds); // [1, 3, 5]
Copy

Advances the cursor by applying the callback function to each item in the cursor's remaining result list until the cursor is depleted or callback returns the exact value false. Returns a promise that evalues to true unless the function returned false.

Note: If the result set spans multiple batches, any remaining batches will only be fetched on demand. Depending on the cursor's TTL and the processing speed, this may result in the server discarding the cursor before it is fully depleted.

See also: Array.prototype.forEach.

Example

const cursor = await db.query(aql`FOR x IN 1..5 RETURN x`);
const result = await cursor.forEach((currentValue) => {
  console.log(currentValue);
});
console.log(result) // true
console.log(cursor.hasNext); // false
Copy

Example

const cursor = await db.query(aql`FOR x IN 1..5 RETURN x`);
const result = await cursor.forEach((currentValue) => {
  console.log(currentValue);
  return false; // stop after the first item
});
console.log(result); // false
console.log(cursor.hasNext); // true
Copy

Kills the cursor and frees up associated database resources.

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

Example

const cursor1 = await db.query(aql`FOR x IN 1..5 RETURN x`);
console.log(cursor1.hasMore); // false
await cursor1.kill(); // no effect

const cursor2 = await db.query(
  aql`FOR x IN 1..5 RETURN x`,
  { batchSize: 2 }
);
console.log(cursor2.hasMore); // true
await cursor2.kill(); // cursor is depleted
Copy

Depletes the cursor by applying the callback function to each item in the cursor's remaining result list. Returns an array containing the return values of callback for each item.

Note: This creates an array of all return values, which may impact memory use when working with very large query result sets. Consider using ArrayCursor#forEach, ArrayCursor#reduce or ArrayCursor#flatMap instead.

See also: Array.prototype.map.

Example

const cursor = await db.query(aql`FOR x IN 1..5 RETURN x`);
const squares = await cursor.map((currentValue) => {
  return currentValue ** 2;
});
console.log(squares); // [1, 4, 9, 16, 25]
console.log(cursor.hasNext); // false
Copy

Advances the cursor and returns the next value in the cursor's remaining result list, or undefined if the cursor has been depleted.

Note: If the result set spans multiple batches, any remaining batches will only be fetched on demand. Depending on the cursor's TTL and the processing speed, this may result in the server discarding the cursor before it is fully depleted.

Example

const cursor = await db.query(aql`FOR x IN 1..3 RETURN x`);
const one = await cursor.next(); // 1
const two = await cursor.next(); // 2
const three = await cursor.next(); // 3
const empty = await cursor.next(); // undefined
Copy

Depletes the cursor by applying the reducer function to each item in the cursor's remaining result list. Returns the return value of reducer for the last item.

Note: Most complex uses of the reduce method can be replaced with simpler code using ArrayCursor#forEach or the for await syntax.

Note: If the result set spans multiple batches, any remaining batches will only be fetched on demand. Depending on the cursor's TTL and the processing speed, this may result in the server discarding the cursor before it is fully depleted.

See also: Array.prototype.reduce.

Example

function largestOfTwo(one, two) {
  return Math.max(one, two);
}
const cursor = await db.query(aql`FOR x IN 1..5 RETURN x`);
const result = await cursor.reduce(largestOfTwo, 0);
console.log(result); // 5
console.log(cursor.hasNext); // false
const emptyResult = await cursor.reduce(largestOfTwo, 0);
console.log(emptyResult); // 0
Copy

Example

// BAD! NEEDLESSLY COMPLEX!
const cursor = await db.query(aql`FOR x IN 1..5 RETURN x`);
const result = await cursor.reduce((accumulator, currentValue) => {
  if (currentValue % 2 === 0) {
    accumulator.even.push(...currentValue);
  } else {
    accumulator.odd.push(...currentValue);
  }
  return accumulator;
}, { odd: [], even: [] });
console.log(result); // { odd: [1, 3, 5], even: [2, 4] }

// GOOD! MUCH SIMPLER!
const cursor = await db.query(aql`FOR x IN 1..5 RETURN x`);
const odd = [];
const even = [];
for await (const currentValue of cursor) {
  if (currentValue % 2 === 0) {
    even.push(currentValue);
  } else {
    odd.push(currentValue);
  }
}
console.log({ odd, even }); // { odd: [1, 3, 5], even: [2, 4] }
Copy

Depletes the cursor by applying the reducer function to each item in the cursor's remaining result list. Returns the return value of reducer for the last item.

Note: If the result set spans multiple batches, any remaining batches will only be fetched on demand. Depending on the cursor's TTL and the processing speed, this may result in the server discarding the cursor before it is fully depleted.

See also: Array.prototype.reduce.

Example

function largestOfTwo(one, two) {
  return Math.max(one, two);
}
const cursor = await db.query(aql`FOR x IN 1..5 RETURN x`);
const result = await cursor.reduce(largestOfTwo);
console.log(result); // 5
console.log(cursor.hasNext); // false
const emptyResult = await cursor.reduce(largestOfTwo);
console.log(emptyResult); // undefined
Copy