Collection API¶

class essentialdb.Collection(documents, threading_lock, onsync_callback, autosync=False, name=None)¶

count()¶: Get the total number of documents in the collection.

createIndex(index, options=None)¶: Create an index.

dropIndexes()¶: Drop all indexes.

find(query={}, filter=None)¶

Finds all documents that match the query. If query is not specified, all documents in the collection will be returned.

Kwargs:: query (dict): If specified, the query to be ran on the collection. filter (fund): If specified, results will be ran through provided function before inclustion in results
Returns:: A list of matching documents or None if no documents match query or the collection is empty.

Example:

with library_db.authors as author_collection:
    document = author_collection.find({'last': 'Smith'})

find_one(query=None, filter=None)¶

Finds one document that matches the query. If multiple documents match (or query is not specified), a single random document is returned from the result set.

Kwargs:: query (dict): If specified, the query to be ran on the collection.
Returns: A single matching document or None if no documents match query or the collection is empty.

Example:

with library_db.authors as author_collection:
    document = author_collection.find_one({'first': 'Ezra', 'last': 'Pound'})

get(key)¶

Get a document previously inserted by ‘set’ or any document whose _id is equal to ‘key’. This is a short-cut function designed designed to provide EssentialDB with semantics similar to a transparent key/value store (like redis).

Args:: key (string) The key (_id) of the item to be retrieved.
Returns:: The document (dict) if found.

Example:

with my_db.cache as request_cache:
    response.text = request_cache.get( request.url )

insert_many(documents)¶

Inserts a list of documents into the collection using the same process as oulined for insert_one

Args:: documents (list) A list of documents (dict) to insert.
Returns: The number of documents inserted into the store.

Example:

with library_db.authors as author_collection:
    authors = [{'first': 'Langston', 'last': 'Hughes', 'born': 1902},
    {'first': 'Ezra', 'last': 'Pound', 'born': 1885}]
    author_collection.insert_many(authors)

insert_one(document)¶

Inserts one document into the collection. If the document already contains an _id, or one is specified in the key word arguments, it will be used as the documents primary identifier on insert. If a document with the same identifier already exists, this operation will overwrite the existing document. If ‘_id’ is not specified, a globally unique identifier will be generated and inserted.

Args:: document (dict) The document to insert.
Returns:: The unique identifier for the inserted document

Example:

with library_db.authors as author_collection:
    #documents are just dictionaries
    author = {'first': 'Langston', 'last': 'Hughes', 'born': 1902}
    author_collection.insert_one(author)

remove(query=None)¶

Remove all documents that match query. If query is not specified, all documents will be removed.

Kwargs:: query (dict): The query to be ran on the collection. An empty dictionary {} matches all.
Returns:: The number of documents removed.

Example:

with library_db.books as book_collection:
    document = book_collection.remove({'period': 'Modern'})

set(key, value)¶

Sets key in the current collection to be equal to the provided value. This is a short-cut function designed designed to provide EssentialDB with semantics similar to a transparent key/value store (like redis). Under the hood, this is creating a document from ‘value’ and assigning it the _id of ‘key’. Any additional sets will overwrite the current value.

Args:

key (string) The key for the value to be inserted. value (dict) The value to set.

Returns:

The unique identifier for the inserted document

Example::

with my_db.cache as request_cache:: request_cache.set( request.url, response.text )

update(query, update)¶

Applies the specified update to all documents in the collection that match the specified query.

Args:: query (dict): The query to be ran on the collection. An empty dictionary {} matches all. update (dict): The update to be ran on matching documents.
Returns:: The number of documents updated.

Example:

with library_db.books as book_collection:
    updated = book_collection.update({'year': {'$gt': 1900}}, {'period': 'Modern'})