Skip to main content

JSON file as a database

Project description


Off-memory json for large data that does not fit the memory.

![Build Status](

To install, simply run ::

python install

Getting started

To create a db: ::

import jsondb

# Create from an empty dict (the default)
db = jsondb.create({})

# Or a list / tuple
db = jsondb.create([])

to create from an existing JSON file: ::

db = jsondb.from_file(json_file_path)
# file-like objects are accepted as well
db = jsondb.from_file(open(json_file_path, 'rb'))

Now add some data to the db and access them:

db['name'] = 'foo'
assert db['name'] == 'foo'

db['items'] = []
for i in range(3):
'id' : i,
'name': chr(97 + i),

assert db['items'][0]['id'] == 0
assert len(db['items']) == 3

assert db.get('nonexists', 'notfound') == 'notfound'

It works like an ordinary dict / list,
but to get its value, use the `data()` method:

# => 'foo'
print db['name'].data()

# Get the data
assert == {
'name' : 'foo',
'items': [
{'id' : 0, 'name' : 'a'},
{'id' : 1, 'name' : 'b'},
{'id' : 2, 'name' : 'c'},


jsondb also supports complex queries, in a syntax based on JSONPath,
which is described here:

`db.query` returns a `QueryResult` object which is iterable.

results = db.query('$')

# Iterating the query result
# => "a b c"
for x in results:

To fetch all the value of the result,

# => ['a', 'b', 'c']
print rslt.values()

To fetch only one value,

# fetch one result
assert db.query('$.name').getone() == 'foo'
# => 'foo'

Example of more complex queries:

# Conditonal query
# => 'b'
print db.query('$.items[?( = 1)].name').getone().data()

# slicing
# => ['a', 'b']
print db.query('$.items[:-1].name').values()


All the data is stored on the disk.
In the current implementation, data is saved as a sqlite database,
but supports for other DBMS are on the table.

both of `create` and `from_file` accept a `url` parameter,
indicating where to store the data:

db = jsondb.create({}, url='path/to/filename.db')
# which is equal to
db = jsondb.create({}, url='sqlite3://path/to/filename.db')

When not specified, a temporary file will be created in `/tmp` by default.

To make sure all the changes made to db being saved to the file,

And when not needed anymore, remember to close it:


Or use context manager:

with jsondb.create(url='path/to/filename.db') as db:
# do all the work here

To load an existing jsondb file later,

db = jsondb.load('path/to/filename.db')


Released under the BSD license.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

jsondb-0.1.2.tar.gz (17.6 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page