Like this project? it on

The Native (file-based) Backend

Stores documents and indexes in flat files on your disk. Can be used without any external software, so it’s a great fit for projects that need a document-oriented database but do not want (or are unable) to use a third-party solution for this.


This backend is transactional, which means that changes on the database will be written to disk only when you call the Backend.commit() function explicitly (there is an autocommit option, though).

The performance of this backend is reasonable for moderately sized datasets (< 100.000 entries).Future version of the backend might support in-memory caching of objects to speed up the performance even more.

class blitzdb.backends.file.Backend(path, config=None, overwrite_config=False, **kwargs)[source]

Bases: blitzdb.backends.base.Backend

A file-based database backend.

Uses flat files to store objects on the hard disk and file-based indexes to optimize querying.

  • path – The path to the database. If non-existant it will be created
  • config – The configuration dictionary. If not specified, Blitz will try to load it from disk. If this fails, the default configuration will be used instead.


It might seem tempting to use the autocommit config and not having to worry about calling commit by hand. Please be advised that this can incur a significant overhead in write time since a commit will trigger a complete rewrite of all indexes to disk.


Start a new transaction.


Commit all pending transactions to the database.


This operation can be expensive in runtime if a large number of documents (>100.000) is contained in the database, since it will cause all database indexes to be written to disk.

create_index(cls_or_collection, params=None, fields=None, ephemeral=False, unique=False)[source]

Create new index on the given collection/class with given parameters.

  • cls_or_collection – The name of the collection or the class for which to create an index
  • params – The parameters of the index
  • ephemeral – Whether to create a persistent or an ephemeral index
  • unique – Whether the indexed field(s) must be unique

params expects either a dictionary of parameters or a string value. In the latter case, it will interpret the string as the name of the key for which an index is to be created.

If ephemeral = True, the index will be created only in memory and will not be written to disk when commit() is called. This is useful for optimizing query performance.


By default, BlitzDB will create ephemeral indexes for all keys over
which you perform queries, so after you've run a query on a given
key for the first time, the second run will usually be much faster.

Specifying keys

Keys can be specified just like in MongoDB, using a dot (‘.’) to specify nested keys.

actor = Actor({'name' : 'Charlie Chaplin',
 'foo' : {'value' : 'bar'}})

If you want to create an index on actor[‘foo’][‘value’] , you can just say



Transcendental indexes (i.e. indexes transcending the boundaries of referenced objects) are currently not supported by Blitz, which means you can’t create an index on an attribute value of a document that is embedded in another document.

rebuild_index(collection, key)[source]

Rebuild a given index using the objects stored in the database.

  • collection – The name of the collection for which to rebuild the index
  • key – The key of the index to be rebuilt

Roll back a transaction.