Getting Started

Installing TinyDB

To install TinyDB from PyPI, run:

$ pip install tinydb

You can also grab the latest development version from GitHub. After downloading and unpacking it, you can install it using:

$ python install

Basic Usage

Let’s cover the basics before going more into detail. We’ll start by setting up a TinyDB database:

>>> from tinydb import TinyDB, Query
>>> db = TinyDB('db.json')

You now have a TinyDB database that stores its data in db.json. What about inserting some data? TinyDB expects the data to be Python dicts:

>>> db.insert({'type': 'apple', 'count': 7})
>>> db.insert({'type': 'peach', 'count': 3})


The insert method returns the inserted element’s ID. Read more about it here: Using Element IDs.

Now you can get all elements stored in the database by running:

>>> db.all()
[{'count': 7, 'type': 'apple'}, {'count': 3, 'type': 'peach'}]

Of course you’ll also want to search for specific elements. Let’s try:

>>> Fruit = Query()
>>> == 'peach')
[{'count': 3, 'type': 'peach'}]
>>> > 5)
[{'count': 7, 'type': 'apple'}]

Next we’ll update the count field of the apples:

>>> db.update({'count': 10}, Fruit.type == 'apple')
>>> db.all()
[{'count': 10, 'type': 'apple'}, {'count': 3, 'type': 'peach'}]

In the same manner you can also remove elements:

>>> db.remove(Fruit.count < 5)
>>> db.all()
[{'count': 10, 'type': 'apple'}]

And of course you can throw away all data to start with an empty database:

>>> db.purge()
>>> db.all()


Before we dive deeper, let’s recapitulate the basics:

db.insert(...) Insert an element
Getting data
db.all() Get all elements Get a list of elements matching the query
db.update(fields, query) Update all elements matching the query to contain fields
db.remove(query) Remove all elements matching the query
db.purge() Purge all elements
Query() Create a new query object
Query().field == 2 Match any element that has a key field with value == 2 (also possible: != > >= < <=)

« Introduction | Advanced Usage »