Use mdb transactions

Source: R/mdb_cursor.R

Cursors are required for some advanced queries on an mdb database, when the basic set of functions in mdb_txn is not sufficient.

Details

Cursors must be created from within a transaction (which in turn are created from an environment).

Methods

close

Close the cursor

Usage: close()

Value: None, called for side effects only

Note: In lmdb.h this is mdb_cursor_close()

put

Store data using the cursor

Usage: put(key, value, overwrite = TRUE, append = FALSE)

Arguments:

  • key: The key (string or raw)

  • value: The value (string or raw)

  • overwrite: As for mdb_txn $put

  • append: As for mdb_txn $put

Value: Logical scalar, indicating if data was previously stored at this key

Note: In lmdb.h this is mdb_cursor_put()

del

Delete the current key

Usage: del()

Value: Logical, indicating if a value was deleted (which will be TRUE if the cursor was valid before this operation). Primarily called for its side effect of deleting the data. After deletion, we call mdb_cursor_get with MDB_GET_CURRENT which will re-validate the cursor.

Note: In lmdb.h this is mdb_cursor_del()

replace

Replace a key's current value with a new value, returning the old value. This is like doing a get() followed by a put within a transaction.

Usage: replace(key, value, as_raw = NULL)

Arguments:

  • key: The key to replace

  • value: The new value to store

  • as_raw: Return the value as raw. With a value of NULL it will return a string if possible (i.e., if there are no null bytes) and a raw vector otherwise. With as_raw = TRUE we always return a raw vector. With as_raw = FALSE we always return a string, or throw an error if this is not possible.

pop

Delete a key's value, returning the value just before it was deleted. This is like doing a get followed by a del within a transaction.

Usage: pop(key, as_raw = NULL)

Arguments:

  • key: The key to delete

  • as_raw: Return the value as raw. With a value of NULL it will return a string if possible (i.e., if there are no null bytes) and a raw vector otherwise. With as_raw = TRUE we always return a raw vector. With as_raw = FALSE we always return a string, or throw an error if this is not possible.

Value: Depending on as_raw and if there is a value stored, NULL, a character string or a raw vector

first

Move the cursor to the first item in the database

Usage: first()

Value: Invisibly, a logical indicating if the cursor position is valid, but primarily called for side effects

last

Move the cursor to the last item in the database

Usage: last()

Value: Invisibly, a logical indicating if the cursor position is valid, but primarily called for side effects

move_next

Move the cursor to the next item in the database. If called while at the last item in the database, this will invalidate the cursor position.

Usage: move_next()

Value: Invisibly, a logical indicating if the cursor position is valid, but primarily called for side effects

move_prev

Move the cursor to the previous item in the database. If called while at the first item in the database, this will invalidate the cursor position.

Usage: move_prev()

Value: Invisibly, a logical indicating if the cursor position is valid, but primarily called for side effects

move_to

Move the cursor to the item in the database with key key. If key does not exist, this will invalidate the cursor position.

Usage: move_to(key)

Arguments:

  • key: Key to move to (string or raw)

Value: Invisibly, a logical indicating if the cursor position is valid, but primarily called for side effects

seek

Move the cursor to the item in the database with key equal to or greater than key. If key does not exist and no key with a key greater than key exists, this will invalidate the cursor position.

Usage: seek(key)

Arguments:

  • key: Key to seek (string or raw)

Value: Invisibly, a logical indicating if the cursor position is valid, but primarily called for side effects

get

Move to a key and fetch the value

Usage: get(key, as_proxy = FALSE, as_raw = NULL)

Arguments:

  • key: The key to find (string or raw)

  • as_proxy: Return as an mdb_proxy object?

  • as_raw: Return the value as raw. With a value of NULL it will return a string if possible (i.e., if there are no null bytes) and a raw vector otherwise. With as_raw = TRUE we always return a raw vector. With as_raw = FALSE we always return a string, or throw an error if this is not possible.

Value: Depending on as_raw and if there is a value stored, NULL, a character string or a raw vector

is_valid

Test if cursor is valid (i.e., that it is pointing at data that can be retrieved). Cursors start off invalid until placed (e.g., first, last) and can be invalidated by moving off the beginning or end of the database.

Usage: is_valid()

key

Return the current key

Usage: key(as_proxy = FALSE, as_raw = NULL)

Arguments:

  • as_proxy: Return as an mdb_proxy object?

  • as_raw: Return the value as raw. With a value of NULL it will return a string if possible (i.e., if there are no null bytes) and a raw vector otherwise. With as_raw = TRUE we always return a raw vector. With as_raw = FALSE we always return a string, or throw an error if this is not possible.

value

Return the current value

Usage: value(as_proxy = FALSE, as_raw = NULL)

Arguments:

  • as_proxy: Return as an mdb_proxy object?

  • as_raw: Return the value as raw. With a value of NULL it will return a string if possible (i.e., if there are no null bytes) and a raw vector otherwise. With as_raw = TRUE we always return a raw vector. With as_raw = FALSE we always return a string, or throw an error if this is not possible.

Examples

# Start by creating a new environment, and within that a write
# transaction, and from that a new cursor.  But first put a bunch
# of data into the database
env <- thor::mdb_env(tempfile())
env$mput(letters, LETTERS)
#> NULL
txn <- env$begin(write = TRUE)
cur <- txn$cursor()

# Move the cursor to the first position
cur$first()

# The key and value:
cur$key()
#> [1] "a"
cur$value()
#> [1] "A"

# Move to a different key:
cur$move_to("g")
cur$value()
#> [1] "G"

# Delete the current item
cur$del()
#> [1] TRUE
cur$key()
#> [1] "h"

# We can't move to 'g' any more as it's gone:
(cur$move_to("g"))
#> [1] FALSE
cur$key() # NULL
#> NULL

# But we can *seek* 'g', which will move to 'h'
(cur$seek("g"))
#> [1] TRUE
cur$key() # "h"
#> [1] "h"

# Get raw values out:
cur$value(as_raw = TRUE)
#> [1] 48

# Cleanup
env$destroy()