Home

Welcome to the PyVidarDB wiki!

PyVidarDB is the Python binding for VidarDB, which is a simple, fast, and persistent key-value store that can store terabytes of data.

Basic Usage

Open a database

import pyvidardb

db = pyvidardb.DB()
db.open("hello_world")

Open a database with options

import pyvidardb

db = pyvidardb.DB()

opts = pyvidardb.Options()
opts.ram_size = 1024 * 1024 * 1024

db.open("./hello_world", opts)

Available options (These are advanced options, normally you can ignore them):

• ram_size: the RAM size that can be used to store data, when the data size is larger than the RAM size, the data will be stored in the disk (default value: 512 * 1024 * 1024)
• max_background_parallelism: the maximum number of concurrent background compaction jobs (default value: 1)

Python byte strings

PyVidarDB uses python byte strings everywhere, that is, it accepts byte strings, and returns byte strings as well. To define a bytes variable, simply prepend a b to the string. For example, b"This is a byte string."

Put

To store a pair of key and value into the database:

db.put(b"key1", b"value1")

It is also possible to store a pair of key and multiple values:

db.put(b"key2", [b"value1", b"value2", b"value3"])

Yes, PyVidarDB supports to store one key with multiple values. Try it by passing a list of bytes.

Get

Get the value(s) of a provided key from the database (The return type is a list of bytes if the key exists, else None):

single_value = db.get(b"key1")
assert single_value == [b"value1"]

multiple_values = db.get(b"key2")
assert multiple_values == [b"value1", b"value2", b"value3"]

key_not_exist = db.get(b"no_such_key")
assert key_not_exist is None

Delete

Delete a key from the database is very straightforward:

db.delete(b"key2")

Update

To update the value(s) of a key in the database:

# Case 1: new values depend on the old values
value = db.get(b"key1")
db.put(b"key1", [b"new value"] + value)

Or:

# Case 2: replace old values with new values
db.put(b"key1", [b"new value"])

Iterator

PyVidarDB only exposes the most commonly used iterator APIs from VidarDB:

• valid(): true if the iterator is valid, else false when the iterator points to the next position of the last element
• key(): return the key for the current entry, which type is bytes
• value(): return the value for the current entry, which type is a list of bytes
• next(): move to the next entry

A basic usage of iterator:

db_iter = db.iter()

while db_iter.valid():
    key, value = db_iter.key(), db_iter.value()
    print(key, value)
    db_iter.next()

Compact

After continuous data insertion, to make get() faster, you may want to call this method manually:

# executing a lot of db.put()
db.compact()
# db.get() will be faster after db.compact()

Close

To close the database:

db.close()