Skip to main content

Cursors

Database cursors are special objects returned from #db.f(..).

Usage​

Cursors are exclusively returned from #db.f(..):

let cursor = #db.f(query, projection)

A cursor MUST be closed before the script run finishes, otherwise the following error occurs:

:::TRUST COMMUNICATION::: 1 db cursors were left open at end of script run

Cursors can be closed via the close method, or by using a terminating method such as first.

After a cursor is closed, it can no longer be used. Subsequent attempts to use the cursor result in the following error:

:::TRUST COMMUNICATION::: cursor was invalid. this can happen if it was used after being closed

Cursor Handles​

A 'cursor' as returned from #db.f(..) consists of two parts: an internal cursor handle, and a cursor object wrapping that handle. Your scripts will never interact with cursor handles directly, only cursor objects.

All cursor state, including whether the cursor is open, is tracked based on cursor handles, not cursor objects. This means you only need to call a closing method (such as close) on one cursor object per handle.

Methods that affect cursor state, such as skip and limit, affect all cursor objects wrapping the same handle.

Some methods (such as skip) return a new cursor object that refers to the same cursor handle as the object they are called on.

Two cursor objects wrapping the same handle do not compare equal (i.e. a === b yields false). There is no built-in way to check if two cursor objects refer to the same handle.

Methods​

The following is an auto-generated list of cursor methods: