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()
orabort_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 byindex_type
, will be removed. Ifindex_type
isNone
, all indexes onpath
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.
-
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 toFalse
. In such cases the user needs to set the path and manually callopen()
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
isTrue
, 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 isFalse
. - compressed – If
True
, the collection will be compressed with DEFLATE compression. Default isFalse
. - records – Expected records number in the collection. Default is
128000
. - cachedrecords – Maximum number of records cached in memory.
Default is
0
.
- large – If
-
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 isTrue
.
-
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.