Cursors

class ApiCursor

The base class remote api cursor. Cursors implement the iterable interface and can be use in for of loops.

close()

Close the remote cursor.

filter(fn)

Exhaust the cursor in-script and return an array of values based on the filter function.

Arguments

• fn {Function} A filter function, fn(doc), that returns true to include the document.

Returns

• { *[] } An array of values.

find(fn)

Exhaust the cursor in-script and return the first matching document based on the find function.

Arguments

• fn {Function} A find function, fn(doc).

Returns

• { * } A value or undefined if no value was found.

forEach(fn)

Exhaust the cursor in-script and calls fn for each document.

Arguments

• fn {Function} A function, fn(doc), called for each document.

Returns

• { *[] } An array of values.

hasNext()

Returns

• { Boolean } true if the cursor has more documents.

isClosed()

Returns

• { Boolean } true if the cursor source has been closed.

map(fn)

Exhaust the cursor in-script and return an array of values based on the map function.

Arguments

• fn {Function} A map function, fn(doc), that returns a transformed value.

Returns

• { *[] } An array of values.

next()

Gets the next document from the cursor. Throws new RangeError('Iterator out of bounds.') if the cursor if past its end. Use hasNext() or iterate through for or to avoid errors.

Returns

• { * } the nect cursor value.

passthru()

Returns an object that represents the serialize representation of the remote api cursor in its current state. This value can be returned from routes in order to stream data directly to the client.

Returns

• { Object }

  • { ObjectID } The remote open cursor identifier.

  • { String } The object name, "cursor".

reduce(fn, memo)

Exhaust the cursor in-script and return a value based on the passed in memo value.

Arguments

• fn {Function} A reduce function, fn(memo, doc), that returns memo.

• memo { * } A value to be passed to the reduce function.

Returns

• { * } the resulting memo value.

toArray()

Exhaust the cursor and return an array of values.

Returns

• { *[] } An array of values.

class BufferedApiCursor extends ApiCursor

A cursor that fetches batchSize number of documents from an api cursor to decrease the number of calls between the api and the script sandbox. In specialized cases, tuning the batchSize depending on the expected document sizes can have a substantive affect on performance in case where the script is exhausting a cursor in a tight loop.

batchSize(size)

Set the batch size for the number of documents fetched from the api for the cursor. The default batch size is 100, which is also the maximum.

hasMore()

Checks for the existence of more documents past the end of an exhausted cursor. This will only be true when there is a limit set on the cursor.

Returns

• { Boolean } true if a limit was set more documents exist past the end of an exhausted cursor.

shared(shared)

Normally, a buffered cursor will fetch batchSize items and iterate through the resulting buffer. If the cursor is then returned to the client, the buffered items in the sandbox would be lost. Setting the shared property before opening a cursor ensures it can be shared between the running script and a transform, for example, at its current location.

Setting this to true essentially sets the batch size to 1, which will slow down in-script cursor iteration. As such, shared() should only be used when a cursor opened in-script before it's returned to the client, or a transform.

When returning a cursor directly from a script, shared(true) is automatically called on the cursor.

passthru(replay) {

When returning a cursor directly from a script, passthru(false) is called so an open cursor maintains its current position.

Arguments

• replay { Boolean = true } when true, re-opens the cursor from the start.

Returns

• { Object }

  • { ObjectID } The remote open cursor identifier.

  • { String } The object name, "cursor".

class WritableBufferedApiCursor extends BufferedApiCursor

A cursor that implements inserting an object into the cursor output stream. This is the cursor passed into Transform handler.

push(...objects)

Push one or more documents or values into the output stream of a script transform.

Arguments

• objects { ...* } A value to add to the output cursor stream.

class db.Cursor extends BufferedApiCursor

access(access)

getOptions()

Returns

• { Object } The options object that describes the cursor options.

grant(grant)

indexed(indexed) {

locale(locale)

maxTimeMS(ms)

pathPrefix(path)

roles(...roles)

skipAcl(skipAcl)

strict(strict)

toList()

transform(script)

class AggregationCursor extends db.Cursor

addFields(addFields)

Adds an $addFields aggregation stage to the pipeline.

Arguments

• addFields { Object } An $addFields object.

group(group)

Adds a $group aggregation stage to the pipeline.

Arguments

• group { Object } A $group object.

limit(limit)

Adds a $limit aggregation stage to the pipeline.

Arguments

• limit { Number } A limit.

match(match)

Adds a $match aggregation stage to the pipeline.

Arguments

• match { Object } A $match object.

native(native)

project(project)

skip(skip)

sort(sort)

unwind(unwind)

class QueryCursor extends db.Cursor

count()

where(where)

expand(...paths)

paths(...paths)

include(...paths)

passive(passive)

limit(limit)

skip(skip)

sort(sort)