API References

exception ejdb.CollectionDoesNotExist
exception ejdb.DatabaseError
exception ejdb.OperationError
exception ejdb.TransactionError
class ejdb.Collection(database, wrapped)

Representation of a collection inside a database.

You generally should not instantiate a collection directly. Call Database.get_collection() to get a collection inside a database instead.

abort_transaction()

Abort a transaction, discarding all un-committed operations.

begin_transaction(allow_nested=False)

Begin a transaction on this collection.

This can be used directly, with the user calling commit_transaction() or abort_transaction() later manually:

collection.begin_transaction()
try:
    ... # Do things.
except:
    collection.abort_transaction()
    raise
else:
    collection.commit_transaction()

Or as a context manager:

with collection.begin_transaction():
    ... # Do things.

In the latter usage, abort_transaction() will be called automatically when the block exits with an exception; if the block exits normally, commit_transaction() will be called.

commit_transaction()

Commit a transaction.

count(*queries, hints={})

Get the number of documents in this collection.

Parameters:hints – A mapping of possible hints to the selection.
create_array_index(path)
create_index(path, index_type)
create_istring_index(path)
create_number_index(path)
create_string_index(path)
delete_many(*queries, hints={})

Delete documents in the collection.

This is an optimized shortcut for find({..., '$dropall': True}). Use the formal syntax if you want to get the content of deleted documents.

Parameters:hints – A mapping of possible hints to the selection.
Returns:Count of documents deleted.
delete_one(*queries, hints={})

Delete a single document in the collection.

This is an optimized shortcut for find_one({..., '$dropall': True}). Use the formal syntax if you want to get the deleted document’s content.

Parameters:hints – A mapping of possible hints to the selection.
Returns:A boolean specifying whether a document is deleted.
drop()
find(*queries, hints={})

Find documents in the collection.

Parameters:hints – A mapping of possible hints to the selection.
Returns:A Cursor instance corresponding to this query.
find_one(*queries, hints={})

Find a single document in the collection.

Parameters:hints – A mapping of possible hints to the selection.
Returns:A mapping for the document found, or None if no matching document exists.
insert_many(documents)

Insert a list of documents.

Returns:A list of OIDs of the inserted documents.
insert_one(document)

Insert a single document.

Returns:OID of the inserted document.
is_in_transaction()
optimize_array_index(path)
optimize_index(path, index_type)
optimize_istring_index(path)
optimize_number_index(path)
optimize_string_index(path)
rebuild_array_index(path)
rebuild_index(path, index_type)
rebuild_istring_index(path)
rebuild_number_index(path)
rebuild_string_index(path)
remove(oid)

Remove the document matching the given OID from the collection.

This method is provided for compatibility with ejdb-python.

remove_array_index(path)
remove_index(path, index_type=None)

Remove index(es) on path from the collection.

The index of specified type on path, if given by index_type, will be removed. If index_type is None, all indexes on path will be removed.

remove_istring_index(path)
remove_number_index(path)
remove_string_index(path)
save(*documents, merge=False)

Persist one or more documents in the collection.

If a saved document doesn’t have a _id key, an automatically generated unused OID will be used. Otherwise the OID is set to the given document’s _id field, possibly overwriting an existing document in the collection.

This method is provided for compatibility with ejdb-python.

Parameters:merge – If evalutes to True, content of existing document with matching _id will be merged with the provided document’s content.
database

The Database instance this collection belongs to.

name

Name of this collection.

class ejdb.Database(path='', options=READ)

Representation of an EJDB.

A Database instance can be created like this:

db = ejdb.Database(
    path='path_to_db',
    options=(ejdb.WRITE | ejdb.TRUNCATE),
)

The database is opened immediately, unless the path argument evalutes to False. In such cases the user needs to set the path and manually call open() later.

close()

Close this EJDB.

create_collection(name, exist_ok=False, **options)

Create a collection in this database with given options.

The newly-created collection is returned. If exist_ok is True, existing collection with the same name will be returned, otherwise an error will be raised.

Options only apply to newly-created collection. Existing collections will not be affected. Possible options include:

Parameters:
  • large – If True, the collection can be larger than 2 GB. Default is False.
  • compressed – If True, the collection will be compressed with DEFLATE compression. Default is False.
  • records – Expected records number in the collection. Default is 128000.
  • cachedrecords – Maximum number of records cached in memory. Default is 0.
drop_collection(name, unlink=True)

Drop a collection in this database.

Does nothing if a database with matching name does not exist.

Parameters:
  • name – Name of collection to drop.
  • unlink – If True, removes all related index and collection files. Default is True.
find(collection_name, *queries, hints={})

Shortcut to query a collection in the database.

The following usage:

db.find('people', {'name': 'TP'})

is semantically identical to:

collection = db.create_collection('people', exist_ok=True)
collection.find({'name': 'TP'})
find_one(collection_name, *queries, hints={})

Shortcut to query a collection in the database.

The following usage:

db.find_one('people', {'name': 'TP'})

is semantically identical to:

collection = db.create_collection('people', exist_ok=True)
collection.find_one({'name': 'TP'})
get_collection(name)

Get the collection with name name inside this EJDB.

has_collection(name)

Check whether this EJDB contains a collection named name.

is_open()

Check whether this EJDB is currently open.

open()

Open this EJDB.

This can be used directly, with the user calling close() later manually:

db.open()
try:
    ... # Do things.
except:
    ... # Handle exceptions.
finally:
    db.close()

Or as a context manager:

with db.open():
    ... # Do things.

In the latter usage, close() will be called automatically when the block exits.

save(collection_name, *documents, merge=False)

Shortcut to save to a collection in the database.

The following usage:

db.save({'people', {'name': 'TP'})

is semantically identical to:

collection = db.create_collection('people', exist_ok=True)
collection.save({'name': 'TP'})
collection_names
collections
options

Options for the EJDB.

This can be modified if the database instance is not opened.

path

Path to the EJDB.

This can be modified if the database instance is not opened.

writable
ejdb.get_ejdb_version(*args, **kwargs)

Get version of the underlying EJDB C library.

ejdb.init(ejdb_path=None)
ejdb.is_valid_oid(*args, **kwargs)

Check whether the given string can be used as an OID in EJDB.

The current OID format (as of 1.2.x) is a 24-character-long hex string.