mdb_cursor {thor} | R Documentation |
Use mdb transactions
Description
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 formdb_txn
$put
append
: As formdb_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 callmdb_cursor_get
withMDB_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 aput
within a transaction.Usage:
replace(key, value, as_raw = NULL)
Arguments:
key
: The key to replacevalue
: The new value to storeas_raw
: Return the value as raw. With a value ofNULL
it will return a string if possible (i.e., if there are no null bytes) and a raw vector otherwise. Withas_raw = TRUE
we always return a raw vector. Withas_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 adel
within a transaction.Usage:
pop(key, as_raw = NULL)
Arguments:
key
: The key to deleteas_raw
: Return the value as raw. With a value ofNULL
it will return a string if possible (i.e., if there are no null bytes) and a raw vector otherwise. Withas_raw = TRUE
we always return a raw vector. Withas_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
. Ifkey
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
. Ifkey
does not exist and no key with a key greater thankey
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 anmdb_proxy
object?as_raw
: Return the value as raw. With a value ofNULL
it will return a string if possible (i.e., if there are no null bytes) and a raw vector otherwise. Withas_raw = TRUE
we always return a raw vector. Withas_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 anmdb_proxy
object?as_raw
: Return the value as raw. With a value ofNULL
it will return a string if possible (i.e., if there are no null bytes) and a raw vector otherwise. Withas_raw = TRUE
we always return a raw vector. Withas_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 anmdb_proxy
object?as_raw
: Return the value as raw. With a value ofNULL
it will return a string if possible (i.e., if there are no null bytes) and a raw vector otherwise. Withas_raw = TRUE
we always return a raw vector. Withas_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)
txn <- env$begin(write = TRUE)
cur <- txn$cursor()
# Move the cursor to the first position
cur$first()
# The key and value:
cur$key()
cur$value()
# Move to a different key:
cur$move_to("g")
cur$value()
# Delete the current item
cur$del()
cur$key()
# We can't move to 'g' any more as it's gone:
(cur$move_to("g"))
cur$key() # NULL
# But we can *seek* 'g', which will move to 'h'
(cur$seek("g"))
cur$key() # "h"
# Get raw values out:
cur$value(as_raw = TRUE)
# Cleanup
env$destroy()