Databases

Once you have established a session with the server, you need a Database instance to access the data. A Database instance is an representation of a database on the server. Database instances allow to access Document instances. Also, Database instances can be used to configure the user and group permissions.

Getting a Database instance

While the constructor of the Database class can be used to get a representation of a specific database, the canonical way to get an instance are the member functions of the CouchDB class.

The following code returns an instance for the animals database.

animals = await session["animals"]

aiocouch only allows to get an instance for a database that exists on the server.

Creating new databases

To create a new database on the server, the create() method of the session object is used.

animals = await session.create("animals")

By default, aiocouch only allows to use the create method for a database that does not exist on the server.

Listing documents

The _all_docs view allows to retrieve all documents stored in a given database on the server. aiocouch also exposes this view as methods of the database class.

The method docs() allows to retrieve documents by a list of ids or all documents with ids matching a given prefix. Similar to a dict, all documents of a database can be iterated with the methods akeys(), and values().

To perform more sophisticated document selections, the method find() allows to search for documents matching the complex selector syntax of CouchDB.

Reference

class aiocouch.database.Database(couchdb, id)

A local representation for the referenced CouchDB database

An instance of this class represents a local copy of a CouchDB database. It allows to create and retrieve Document instances, as well as the iteration other many documents.

Parameters
  • couchdb (CouchDB) – The CouchDB connection session

  • id (str) – the id of the database

await __getitem__(id)

Returns the document with the given id

Raises

NotFoundError – if the given document does not exists

Parameters

id (str) – the name of the document

Return type

Document

Returns

a local copy of the document

async for ... in akeys(**params)

A generator returning the names of all documents in the database

Parameters

params – passed into aiohttp.ClientSession.request()

Return type

AsyncGenerator[str, None]

Returns

returns all document ids

all_docs

Returns the all_docs view of the database

Return type

AllDocsView

Returns

Description of returned object.

await create(id, exists_ok=False, data=None)

Returns a local representation of a new document in the database

This method will check if a document with the given name already exists and return a Document instance.

This method does not create a document with the given name on the server. You need to call save() on the returned document.

Raises

ConflictError – if the document does not exist on the server

Parameters
  • id (str) – the name of the document

  • exists_ok (bool) – If True, do not raise a ConflictError if an document with the given name already exists. Instead return the existing document.

  • data (Optional[dict]) – Description of parameter data. Defaults to None.

Return type

Document

Returns

returns a Document instance representing the requested document

await delete()

Delete the database on the server

Send the request to delete the database and all of its documents.

async for ... in docs(ids=None, create=False, prefix=None, include_ddocs=False, **params)

A generator to iterator over all or a subset of documents in the database.

When neither of ids nor prefix are specified, all documents will be iterated. Only one of ids and prefix can be specified. By default, design documents are not included.

Parameters
  • ids (Optional[list]) – Allows to iterate over a subset of documents by passing a list of document ids

  • create (bool) – If True, every document contained in ids, which doesn’t exists, will be represented by an empty Document instance.

  • prefix (Optional[str]) – Allows to iterator over a subset of documents by specifing a prefix that the documents must match.

  • include_ddocs (bool) – Include the design documents of the database.

  • params – Additional query parameters, see CouchDB view endpoint.

Return type

AsyncGenerator[Document, None]

async for ... in find(selector, limit=None, **params)

Fetch documents based on search criteria

This method allows to use the _find endpoint of the database.

This method supports all request paramters listed in _find.

Note

As this methid returns Document s, which contain the complete data, the fields parameter is not supported.

Parameters

selector (type) – See selectors

Return type

AsyncGenerator[Document, None]

Returns

return all documents matching the passed selector.

await get(id, default=None)

Returns the document with the given id

Raises

NotFoundError – if the given document does not exists and default is None

Parameters
  • id (str) – the name of the document

  • default (Optional[dict]) – if default is not None and the document does not exists on the server, a new Document instance, containing default as its contents, is returned. To create the document on the server, save() has to be called on the returned instance.

Returns

a local representation of the requested document

await info()

Returns basic information about the database

See also GET /db.

Returns

Description of returned object.

Return type

def

async for ... in values(**params)

Iterates over documents in the database

See docs().

Return type

AsyncGenerator[Document, None]