B+ Tree Database — BDB

New in version 0.2.0.

BDB

class tokyocabinet.BDB

Example:

from tokyocabinet import *

bdb = BDB()

# if need be, you should call tune/setcache/setxmsiz/setdfunit before
# open, ex. with default values:
bdb.tune(0, 0, 0, -1, -1, 0)
bdb.setcache(0, 0)
bdb.setxmsiz(0)
bdb.setdfunit(0)

# open the database
bdb.open("casket.tcb", BDBOWRITER | BDBOCREAT)

# store records
for key, value in [("foo", "hop"), ("bar", "step"), ("baz", "jump")]:
    bdb[key] = value

# retrieve one record
print(bdb["foo"])

# traverse records
for key in bdb:
    print(key, bdb[key])

# close the database
bdb.close()

Note

For all methods taking either a key argument or a pair (key, value), key and value must be either str (Python2) or bytes (Python3).

len(bdb)
Return the number of records in the database bdb.
bdb[key]
Return the value of bdb‘s first record corresponding to key. Raises KeyError if key is not in the database.
bdb[key] = value
Set bdb[key] to value. If key has duplicates the first corresponding record is modified.
del bdb[key]
Remove bdb[key] from bdb. Raises KeyError if key is not in the database. If key has duplicates the first corresponding record is deleted.
key in bdb
Return True if bdb has a key key, else False.
key not in bdb
Equivalent to not key in bdb.
iter(bdb)

Return an iterator over the keys of the database.

Note

Better use a BDBCursor to iterate over a database with duplicates.

tune(lmemb, nmemb, bnum, apow, fpow, opts)

Tune a database.

Parameters:
  • lmemb – the number of members in each leaf page. If specified as 0 or as a negative value, the default value (128) is used.
  • nmemb – the number of members in each non-leaf page. If specified as 0 or as a negative value, the default value (256) is used.
  • bnum – the number of elements in a bucket array. If specified as 0 or as a negative value, the default value (32749) is used.
  • apow – (power of 2) TODO. If specified as a negative value, the default value (8) is used (means: 2**8).
  • fpow – (power of 2) TODO. If specified as a negative value, the default value (10) is used (means 2**10).
  • opts – options, see BDB.tune()/BDB.optimize() options.

Note

Tuning an open database is an invalid operation.

setcache(lcnum, ncnum)

Set the cache parameters.

Parameters:
  • lcnum – the maximum number of leaf nodes to be cached. If specified as 0 or as a negative value, the default value (1024) is used.
  • ncnum – the maximum number of non-leaf nodes to be cached. If specified as 0 or as a negative value, the default value (512) is used.

Note

Setting the cache parameters on an open database is an invalid operation.

setxmsiz(xmsiz)

Set the extra mapped memory size.

Parameter:xmsiz – the amount of extra mapped memory (in what unit?). If specified as 0 or as a negative value, the extra mapped memory is disabled (default).

Note

Setting the extra memory size on an open database is an invalid operation.

setdfunit(dfunit)

Set auto defragmentation’s unit step number.

Parameter:dfunit – the unit step number(?). If specified as 0 or as a negative value, auto defragmentation is disabled (default).

Note

Setting this on an open database is an invalid operation.

open(path, mode)

Open a database.

Parameters:
close()

Close the database.

Note

BDBs are closed when garbage-collected.

clear()
Remove all records from the database.
copy(path)

Copy the database file.

Parameter:path – path to the destination file.
begin()
Begin a transaction.
commit()
Commit a transaction.
abort()
Abort a transaction.
get(key[, duplicate=False])
If duplicate is False (default) this is equivalent to bdb[key]. If duplicate is True this method returns a tuple of all the values corresponding to key. It will raise KeyError if key is not in the database.
remove(key[, duplicate=False])
If duplicate is False (default) this is equivalent to del bdb[key]. If duplicate is True this method removes all records corresponding to key. It will raise KeyError if key is not in the database.
put(key, value[, duplicate=False])
If duplicate is False (default) this is equivalent to bdb[key] = value. If duplicate is True and key is already in the database, this method will store a new duplicate record after the last corresponding record.
putkeep(key, value)
Store a record in the database, unlike the standard forms (hdb[key] = value or put()), this method raises KeyError if key is already in the database.
putcat(key, value)
Concatenate a value at the end of an existing one. If there is no corresponding record, a new record is stored. If key has duplicates the first corresponding record is modified.
putdup(key, values)

Store duplicate records in the database, this is equivalent to:

def putdup(self, key, values):
    for value in values:
        self.put(key, value, duplicate=True)
sync()
Flush modifications to the database file.
searchkeys(prefix[, max])
Return a frozenset of keys starting with prefix. If given, max is the maximum number of keys to fetch, if omitted or specified as a negative value no limit is applied.
range([begin=None[, end=None[, max=-1]]])

Return a frozenset of all the keys starting with begin, all the keys starting with end and all the keys in between. If given, max is the maximum number of keys to fetch, if omitted or specified as a negative value no limit is applied. Example:

>>> from tokyocabinet import *
>>> bdb = BDB()
>>> bdb.open("range.tcb", BDBOWRITER | BDBOCREAT)
>>> for key, value in [("a", "a"), ("b", "b"), ("c", "c"), ("d", "d")]:
...     bdb[key] = value
...
>>> bdb.range()
frozenset(['a', 'c', 'b', 'd'])
>>> bdb.range(end="c")
frozenset(['a', 'c', 'b'])
>>>
>>> bdb.range("b", "d") # begin and end are inclusive
frozenset(['c', 'b', 'd'])
>>> bdb.range("b", "z")
frozenset(['c', 'b', 'd'])
>>> bdb.range("z", "b") # end < begin doesn't work
frozenset([])
>>> bdb.range("a", "a") # end == begin works
frozenset(['a'])
>>> bdb.range("A", "Z") # it is case sensitive
frozenset([])
>>> bdb.range("A", "z") # uppercase < lowercase
frozenset(['a', 'c', 'b', 'd'])
>>> bdb.range("z", "A")
frozenset([])
>>> bdb.close()
>>>
cursor()
Return a cursor object (BDBCursor). See BDBCursor operations.
optimize([lmemb=0[, nmemb=0[, bnum=0[, apow=-1[, fpow=-1[, opts=255]]]]]])

Optimize a database.

Parameters:
  • lmemb – the number of members in each leaf page. If specified as 0 or as a negative value, the current setting is kept.
  • nmemb – the number of members in each non-leaf page. If specified as 0 or as a negative value, the current setting is kept.
  • bnum – the number of elements in a bucket array. If specified as 0 or as a negative value, the default value (twice the number of pages) is used.
  • apow – (power of 2) TODO. If specified as a negative value, the current setting is kept.
  • fpow – (power of 2) TODO. If specified as a negative value, the current setting is kept.
  • opts – options, see BDB.tune()/BDB.optimize() options. If specified as 255 (UINT8_MAX), the current setting is kept.

Note

Optimizing a read only database, or during a transaction, is an invalid operation.

addint(key, num)

Store an int in the database. If key is not in the database, this method stores num in the database and returns it. If key is already in the database, then it will add num to its current value and return the result. If key exists but its value cannot be treated as an int this method raises KeyError.

Note

  • The returned value will wrap around INT_MAX and INT_MIN. Example:

    >>> bdb.addint('id', INT_MAX) # setting 'id' to INT_MAX
    2147483647
    >>> bdb.addint('id', 1) # adding 1 to 'id' returns INT_MIN
    -2147483648
    >>>
    
  • Trying to access a value set with addint() using get() or bdb[key] will not return an int. It will instead return the internal binary representation of the value. Example:

    >>> bdb.addint('id', INT_MAX) # setting 'id' to INT_MAX
    2147483647
    >>> bdb['id']
    '\xff\xff\xff\x7f'
    >>>
    

New in version 0.5.0.

adddouble(key, num)

Store a float in the database. If key is not in the database, this method stores num in the database and returns it. If key is already in the database, then it will add num to its current value and return the result. If key exists but its value cannot be treated as a float this method raises KeyError.

Note

Trying to access a value set with adddouble() using get() or bdb[key] will not return a float.

New in version 0.5.0.

Methods keys(), values() and items() are not yet implemented (mainly because I didn’t settle on how to do it: should they return Iterable, Iterator, MappingView, etc.?). Any help would be greatly appreciated in this matter.

For the time being, for those of you who really need these methods, it’s trivial to implement them in python. Here is an example using cursors and generators:

from tokyocabinet import BDB as _BDB

class BDB(_BDB):

    def keys(self):
        c = self.cursor()
        c.first()
        while True:
            yield c.key()
            c.next()

    def values(self):
        c = self.cursor()
        c.first()
        while True:
            yield c.value()
            c.next()

    def items(self):
        c = self.cursor()
        c.first()
        while True:
            yield c.item()
            c.next()
path
The path to the database file.
size
The size in bytes of the database file.

BDB.open() modes

tokyocabinet.BDBOREADER
Open a database in read-only mode.
tokyocabinet.BDBOWRITER
Open a database in read-write mode.

The following constants can only be combined with BDBOWRITER :

  • tokyocabinet.BDBOCREAT

    Create a new database file if it does not exists.

  • tokyocabinet.BDBOTRUNC

    Create a new database file even if one already exists (truncates existing file).

  • tokyocabinet.BDBOTSYNC

    Sync the database file on every transaction.

The following constants can be combined with either BDBOREADER or BDBOWRITER :

  • tokyocabinet.BDBONOLCK

    Opens the database file without file locking.

  • tokyocabinet.BDBOLCKNB

    Locking is performed without blocking.

BDB.tune()/BDB.optimize() options

tokyocabinet.BDBTLARGE
The size of the database can be larger than 2GB.
tokyocabinet.BDBTDEFLATE
Each page is compressed with Deflate encoding.
tokyocabinet.BDBTBZIP
Each page is compressed with BZIP2 encoding.
tokyocabinet.BDBTTCBS
Each page is compressed with TCBS encoding.

BDBCursor operations

class tokyocabinet.BDBCursor

Warning

When first returned by BDB.cursor() a cursor is not fully initialized. You need to call one of the positioning method (first(), last() or jump()) before you can do anything useful with it.

first()
Move to the first record (if there is no such thing StopIteration is raised).
last()
Move to the last record (if there is no such thing StopIteration is raised).
jump(key)
Move to the first occurrence of key. If key is not in the database, the cursor is positioned to the next available record (if there is no such thing StopIteration is raised).
prev()
Move to the previous record (if there is no such thing StopIteration is raised).
next()
Move to the next record (if there is no such thing StopIteration is raised).
put(value[, mode=BDBCPCURRENT])

Store a value at/around the cursor’s current position.

Parameter:mode – see BDBCursor.put() modes.
remove()
Remove the current record. After deletion the cursor is moved to the next available record.
key()
Get current key.
value()
Get current value.
item()
Get current item (a (key, value) tuple).

BDBCursor.put() modes

tokyocabinet.BDBCPCURRENT
The current value is overwritten (default).
tokyocabinet.BDBCPBEFORE
A new item is stored before the current position and the cursor is moved to the newly inserted record.
tokyocabinet.BDBCPAFTER
A new item is stored after the current position and the cursor is moved to the newly inserted record.

Table Of Contents

Previous topic

On-memory Hash Database — MDB

Next topic

On-memory Tree Database — NDB

This Page