Class BatchedArrayCursor<T>

The BatchedArrayCursor provides 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

const db = new Database();
const query = aql`FOR x IN 1..5 RETURN x`;
const cursor = await db.query(query) as ArrayCursor<number>;
const batches = cursor.batches;

Example

const db = new Database();
const query = aql`FOR x IN 1..10000 RETURN x`;
const cursor = await db.query(query, { batchSize: 10 });
for await (const batch of cursor.batches) {
// Process all values in a batch in parallel
await Promise.all(batch.map(
value => asyncProcessValue(value)
));
}

Type Parameters

  • T = any

    Type to use for each item. Defaults to any.

Hierarchy

  • BatchedArrayCursor

Accessors

  • get count(): undefined | number
  • Total number of documents in the query result. Only available if the count option was used.

    Returns undefined | number

  • get extra(): Readonly<CursorExtras>
  • Additional information about the cursor.

    Returns Readonly<CursorExtras>

  • get hasMore(): boolean
  • 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.

    Returns boolean

  • get hasNext(): boolean
  • Whether the cursor has more batches. If set to false, the cursor has already been depleted and contains no more batches.

    Returns boolean

Methods

  • 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.

    Example

    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);
    }
    }

    Returns AsyncGenerator<T[], undefined, undefined>

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

    Example

    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

    Returns Promise<T[][]>

  • 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.

    Example

    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

    Example

    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]

    Type Parameters

    • R

      Return type of the callback function.

    Parameters

    • callback: ((currentBatch: T[], index: number, self: BatchedArrayCursor<T>) => R | R[])

      Function to execute on each element.

    Returns Promise<R[]>

  • 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`,
    { 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

    Example

    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

    Parameters

    • callback: ((currentBatch: T[], index: number, self: BatchedArrayCursor<T>) => false | void)

      Function to execute on each element.

    Returns Promise<boolean>

  • Drains the cursor and frees up associated database resources.

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

    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

    Returns Promise<void>

  • Loads all remaining batches from the server.

    Warning: This may impact memory use when working with very large query result sets.

    Example

    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
    }

    Returns Promise<void>

  • 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 forEach, reduce or flatMap instead.

    See also: Array.prototype.map.

    Example

    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

    Type Parameters

    • R

      Return type of the callback function.

    Parameters

    Returns Promise<R[]>

  • 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.

    Example

    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

    Returns Promise<undefined | T[]>

  • 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 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 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

    Example

    // 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] }

    Type Parameters

    • R

      Return type of the reducer function.

    Parameters

    • reducer: ((accumulator: R, currentBatch: T[], index: number, self: BatchedArrayCursor<T>) => R)

      Function to execute on each element.

    • initialValue: R

      Initial value of the accumulator value passed to the reducer function.

    Returns Promise<R>

  • 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.

    Example

    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

    Type Parameters

    • R

      Return type of the reducer function.

    Parameters

    • reducer: ((accumulator: T[] | R, currentBatch: T[], index: number, self: BatchedArrayCursor<T>) => R)

      Function to execute on each element.

        • (accumulator: T[] | R, currentBatch: T[], index: number, self: BatchedArrayCursor<T>): R
        • Parameters

          Returns R

    Returns Promise<undefined | R>

Generated using TypeDoc