Skip to content


Subversion checkout URL

You can clone with
Download ZIP
readingdb time series database
C Python Other
Branch: master
Failed to load latest commit information.
c6 Remove invalid inline to allow compiling on a mac
debian - fix build dependencies for interface module
iface_bin * Fix linux build (what to do about mac)
AUTHORS reorganize reading db to better support packaging
COPYING - add symlink to LICENSE to satisfy automake
ChangeLog - change client interface to always return ascending data for prev u…
INSTALL update install and readme; fix script so make dist works
LICENSE license update install and readme; fix script so make dist works
README update install and readme; fix script so make dist works update install and readme; fix script so make dist works


readingdb is a time-series database designed for efficiency and speed.

Time series data is any data which is a series of (time, sequence,
value) points.  ReadingDB buckets and compresses your data using a
delta encoding and zlib, and then writes this into a bdb installation
with a bdb index.  It uses the bdb transaction manager for write-ahead
logging so that the volume will not become corrupted.

To use it, first follow the instructions in INSTALL to build the
database and the python interface module.  The key objects in
readingdb are "streams", which have an integer id.  The readingdb
python module lets you talk to the server process; traffic between the
client and server is encoded using google protocol buffer definitions
found in c6/pbuf.

A simple python script for inserting data would be:

import readingdb as rdb

# specify default host/port
rdb.db_setup('localhost', 4242)

# create a connection
db = rdb.db_open('localhost')

# add data.  the tuples are  (timestamp, seqno, value)
rdb.db_add(db, 1, [(x, 0, x) for x in xrange(0, 100)])

# read back the data we just wrote using the existing connection
# the args are streamid, start_timestamp, end_timestamp
print rdb.db_query(1, 0, 100, conn=db)
# close

# read back the data again using a connection pool this time.  You can
# specify a list of streamids to range-query multiple streams at once.
rdb.db_query([1], 0, 100) 

ReadingDB supports efficient range querying and interation using the
db_query, db_prev, and db_next operations; you can delete data with

As you can see, db_query can re-use an existing connection if desired.
As of April 20, 2012, the result of querying the TSDB is returned as a
list of numpy matrices.  This is because this is a very
memory-efficient data structure, and creating numpy matrices using the
c API is a lot more efficient than later doing it in python.  

If no connection is specified for db_query/db_prev/db_next, new
connections will be opened to the host/port specified with db_setup.
The most efficient way of downloading data from a large number of
streams is to specify a list of streamids, which allows the client
library to conduct multiple parallel downloads of the data.  Using
this approach we have observed readingdb easily saturating a 100Mb


For reading-server
   libdb4.8, libdb4.8-dev (berkeley database)
   libprotobuf, libprotobuf-dev (google protocol buffers)
   libprotoc6, libprotoc6-dev (c bindings for protobufs)
   zlib, zlib-dev (for compression)
   gcc, make, automake

For python bindings
   python, python-dev, python-numpy (python deps)
   swig (interface generator)
Something went wrong with that request. Please try again.