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 any remaining batches that haven't yet been
fetched. If set to false, all batches have been fetched and no
additional requests to the server will be made when consuming any
remaining batches from this cursor.
Whether the cursor has more batches. If set to false, the cursor has
already been depleted and contains no more batches.
An ArrayCursor providing item-wise access to the cursor result set.
See also ArrayCursor#batches.
Enables use with for await to deplete the cursor by asynchronously
yielding every batch 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.
const cursor = await db.query(aql`
FOR user IN users
FILTER user.isActive
RETURN user
`);
for await (const users of cursor.batches) {
for (const user of users) {
console.log(user.email, user.isAdmin);
}
}
Depletes the cursor, then returns an array containing all batches in the cursor's remaining result list.
const cursor = await db.query(
aql`FOR x IN 1..5 RETURN x`,
{ batchSize: 2 }
);
const result = await cursor.batches.all(); // [[1, 2], [3, 4], [5]]
console.log(cursor.hasNext); // false
Depletes the cursor by applying the callback function to each batch in
the cursor's remaining result list. Returns an array containing the
return values of callback for each batch, 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.
const cursor = await db.query(
aql`FOR x IN 1..5 RETURN x`,
{ batchSize: 2 }
);
const squares = await cursor.batches.flatMap((currentBatch) => {
return currentBatch.map((value) => value ** 2);
});
console.log(squares); // [1, 1, 2, 4, 3, 9, 4, 16, 5, 25]
console.log(cursor.hasNext); // false
const cursor = await db.query(
aql`FOR x IN 1..5 RETURN x`,
{ batchSize: 1 }
);
const odds = await cursor.batches.flatMap((currentBatch) => {
if (currentBatch[0] % 2 === 0) {
return []; // empty array flattens into nothing
}
return currentBatch;
});
console.logs(odds); // [1, 3, 5]
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.
Function to execute on each element.
const cursor = await db.query(
aql`FOR x IN 1..5 RETURN x`,
{ batchSize: 2 }
);
const result = await cursor.batches.forEach((currentBatch) => {
for (const value of currentBatch) {
console.log(value);
}
});
console.log(result) // true
console.log(cursor.hasNext); // false
const cursor = await db.query(
aql`FOR x IN 1..5 RETURN x`,
{ batchSize: 2 }
);
const result = await cursor.batches.forEach((currentBatch) => {
for (const value of currentBatch) {
console.log(value);
}
return false; // stop after the first batch
});
console.log(result); // false
console.log(cursor.hasNext); // true
Drains the cursor and frees up associated database resources.
This method has no effect if all batches have already been consumed.
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
Loads all remaining batches from the server.
Warning: This may impact memory use when working with very large query result sets.
const cursor = await db.query(
aql`FOR x IN 1..5 RETURN x`,
{ batchSize: 1 }
);
console.log(cursor.hasMore); // true
await cursor.batches.loadAll();
console.log(cursor.hasMore); // false
console.log(cursor.hasNext); // true
for await (const item of cursor) {
console.log(item);
// No server roundtrips necessary any more
}
Depletes the cursor by applying the callback function to each batch in
the cursor's remaining result list. Returns an array containing the
return values of callback for each batch.
Note: This creates an array of all return values, which may impact memory use when working with very large query result sets. Consider using BatchedArrayCursor#forEach, BatchedArrayCursor#reduce or BatchedArrayCursor#flatMap instead.
See also:
Array.prototype.map.
const cursor = await db.query(
aql`FOR x IN 1..5 RETURN x`,
{ batchSize: 2 }
);
const squares = await cursor.batches.map((currentBatch) => {
return currentBatch.map((value) => value ** 2);
});
console.log(squares); // [[1, 4], [9, 16], [25]]
console.log(cursor.hasNext); // false
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, 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.
const cursor = await db.query(
aql`FOR i IN 1..10 RETURN i`,
{ batchSize: 5 }
);
const firstBatch = await cursor.batches.next(); // [1, 2, 3, 4, 5]
await cursor.next(); // 6
const lastBatch = await cursor.batches.next(); // [7, 8, 9, 10]
console.log(cursor.hasNext); // false
Depletes the cursor by applying the reducer function to each batch in
the cursor's remaining result list. Returns the return value of reducer
for the last batch.
Note: Most complex uses of the reduce method can be replaced with
simpler code using BatchedArrayCursor#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.
function largestValue(baseline, values) {
return Math.max(baseline, ...values);
}
const cursor = await db.query(
aql`FOR x IN 1..5 RETURN x`,
{ batchSize: 3 }
);
const result = await cursor.batches.reduce(largestValue, 0);
console.log(result); // 5
console.log(cursor.hasNext); // false
const emptyResult = await cursor.batches.reduce(largestValue, 0);
console.log(emptyResult); // 0
// BAD! NEEDLESSLY COMPLEX!
const cursor = await db.query(
aql`FOR x IN 1..5 RETURN x`,
{ batchSize: 1 }
);
const result = await cursor.reduce((accumulator, currentBatch) => {
if (currentBatch[0] % 2 === 0) {
accumulator.even.push(...currentBatch);
} else {
accumulator.odd.push(...currentBatch);
}
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 currentBatch of cursor) {
if (currentBatch[0] % 2 === 0) {
even.push(...currentBatch);
} else {
odd.push(...currentBatch);
}
}
console.log({ odd, even }); // { odd: [1, 3, 5], even: [2, 4] }
Depletes the cursor by applying the reducer function to each batch in
the cursor's remaining result list. Returns the return value of reducer
for the last batch.
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.
function largestValue(values1, values2) {
return [Math.max(...values1, ...values2)];
}
const cursor = await db.query(
aql`FOR x IN 1..5 RETURN x`,
{ batchSize: 3 }
);
const result = await cursor.batches.reduce(largestValue);
console.log(result); // [5]
console.log(cursor.hasNext); // false
The
BatchedArrayCursorprovides a batch-wise API to an ArrayCursor.When using TypeScript, cursors can be cast to a specific item type in order to increase type safety.
Example
Example