A key role in aiocouch takes the Document class. Every data send and retrieved from the server is represented by an instance of that class. There are no other ways in aiocouch to interact with documents.

Getting a Document instance

While the constructor can be used to get an instance representing a specific document, the canonical way is the usage of member functions of instances of the Database class.

butterfly_doc = await database["butterfly"]
wolpertinger = await database.get("wolpertinger")

These methods create a Document and fetch the data from the server. For some cases, though, a precise control other the performed requests are required. The above code snippet is equivalent to this:

butterfly_doc = Document(database, "butterly")
await butterfly_doc.fetch()

Creating new Documents

The creation of a new document on the server consists of three steps. First, you need a local document handle, i.e., an Document instance. Then you set the contents of the document. And finally, the local document is saved to the server.

# get an Document instance
doc = await database.create["new_doc"]

# set the document content
doc["name"] = "The new document"

# actually perform the request to save the document on the server

Modify existing documents

The modification of an existing document works very similarly to the creation. Retrieving the document, updating its contents, and finally saving the modified data to the server.

# get an Document instance
doc = await database["existing_doc"]

# update the document content
doc["name"] = "The modified document"

# actually perform the request to save the modification to the server

Conflict handling

Whenever, two or more different Document instances want to save the same document on the server, a ConflictError can occur. To cope with conflicts, there are a set of different strategies, which can be used.

One trivial solution is to simply ignore conflicts.This is a viable strategy if only the existance of the document matters.

with contextlib.suppress(aiocouch.ConflictError):

Another straight-forward solution is to override the contents of the existing document.

except aiocouch.ConflictError:
    info = await
    doc.rev = info["rev"]

Other use cases may require a more sophisticated merging of documents. However, there isn’t a generic solution to such an approach. Thus, we forego to show example code here.


class aiocouch.document.Document(database, id, data=None)

A local representation for the referenced CouchDB document

An instance of this class represents a local copy of the document data on the server. This class behaves like a dict containing the document data and allows to fetch() and save() documents. For details about the dict-like interface, please refer to the Python manual.

Constructing an instance of this class does not cause any network requests.


id – the id of the document

  • database (Database) – The database of the document

  • id (str) – the id of the document

  • data (Optional[dict]) – the inital data used to set the body of the document


Returns the attachment object

The attachment object is returned, but this method doesn’t actually fetch any data from the server. Use fetch() and save(), respectively.


id (str) – the id of the attachment

Return type



Returns the attachment object

await copy(new_id)

Create a copy of the document on the server

Creates a new document with the data currently stored on the server.


new_id (str) – the id of the new document

Return type



an instance for the new document after it was copied


Returns the local copy of the document as a dict

If the document doesn’t exist on the server, this function returns None.

This method does not perform a network request.

Return type



Returns the data of the document or None

await delete(discard_changes=False)

Deletes the document from the server

Calling this method deltes the local data and the document on the server. Afterwards, the instance can be filled with new data and call save() again.

  • ConflictError – if the local data has changed without saving

  • ConflictError – if the local revision is different from the server. See TODO.


Denotes whether the document exists

A document exists, if it was fetch() ed from the server and wasn’t deleted on the server.

This method does not perform a network request.

Return type



True if the document exists, False overwise

await fetch(discard_changes=False)

Retrieves the document data from the server

Fetching the document will retrieve the data from the server using a network request and update the local data.


ConflictError – if the local data has changed without saving


discard_changes (bool) – If set to True, the local data object will the overridden with the retrieved content. If the local data was changed, no exception will be raised.

await info()

Returns a short information about the document.

This method sends a request to the server to retrieve the current status.


NotFoundError – if the document does not exist on the server

Return type



A dict containing the id and revision of the document on the server


Allows to set and get the local revision

If the local document wasn’t fetched or saved, this is None.

Return type


await save()

Saves the current state to the CouchDB server


ConflictError – if the local revision is different from the server. See TODO.