Couch Client

Full description of all available methods

class async_couch.CouchClient(http_client: async_couch.http_clients.base_client.BaseHttpClient)
attachment_delete(db: str, doc_id: str, attachment_id: str, rev: str = None) → async_couch.types.UniversalResponse

Deletes the attachment with filename {attname} of the specified doc. You must supply the rev query parameter or If-Match with the current revision to delete the attachment.

Parameters:
  • db (str) – Database name
  • doc_id (str) – Document id
  • attachment_id (str) – Attachment name
  • rev (str = None) – Actual document’s revision
Returns:

Operating result
Return type:

UniversalResponse
Raises:

exc.CouchResponseError: – If server error occurred
attachment_exists(db: str, doc_id: str, attachment_id: str, rev: str = None) → async_couch.types.UniversalResponse

Returns the HTTP headers containing a minimal amount of information about the specified attachment. The method supports the same query arguments as the GET /{db}/{docid}/{attname} method, but only the header information (including attachment size, encoding and the MD5 hash as an ETag), is returned

Parameters:
  • db (str) – Database name
  • doc_id (str) – Document id
  • attachment_id (str) – Attachment name
  • rev (str = None) – Actual document’s revision
Returns:

Operating result
Return type:

UniversalResponse
Raises:

exc.CouchResponseError: – If server error occurred
attachment_get(db: str, doc_id: str, attachment_id: str, rev: str = None) → async_couch.types.UniversalResponse

Returns the file attachment associated with the document. The raw data of the associated attachment is returned (just as if you were accessing a static file. The returned Content-Type will be the same as the content type set when the document attachment was submitted into the database.

Parameters:
  • db (str) – Database name
  • doc_id (str) – Document id
  • attachment_id (str) – Attachment name
  • rev (str = None) – Actual document’s revision
Returns:

Operating result
Return type:

UniversalResponse
Raises:

exc.CouchResponseError: – If server error occurred
attachment_upload(db: str, doc_id: str, attachment_id: str, content_type: str, data: bytes, rev: str) → async_couch.types.UniversalResponse

Uploads the supplied content as an attachment to the specified document. The attachment name provided must be a URL encoded string. You must supply the Content-Type header, and for an existing document you must also supply either the rev query argument or the If-Match HTTP header. If the revision is omitted, a new, otherwise empty document will be created with the provided attachment, or a conflict

will occur.

If case when uploading an attachment using an existing attachment name, CouchDB will update the corresponding stored content of the database. Since you must supply the revision information to add an attachment to the document, this serves as validation to update the existing attachment.

Parameters:
  • db (str) – Database name
  • doc_id (str) – Document id
  • attachment_id (str) – Attachment name
  • content_type (str) – Attachment MIME type
  • data (bytes) – Uploading file data
  • rev (str = None) – Actual document’s revision
Returns:

Operating result
Return type:

UniversalResponse
Raises:

exc.CouchResponseError: – If server error occurred
db_all_docs(db: str, conflicts: bool = False, descending: bool = False, end_key: dict = None, end_key_doc_id: str = None, group: bool = False, group_level: int = None, include_docs: bool = False, attachments: bool = False, att_encoding_info: bool = False, inclusive_end: bool = True, key: dict = None, keys: list = None, limit: int = None, reduce: bool = True, skip: int = 0, sort: bool = True, stable: bool = False, stale: str = None, start_key: dict = None, start_key_doc_id: str = None, update: bool = True, update_seq: bool = False) → async_couch.types.UniversalResponse

POST _all_docs functionality supports identical parameters and behavior as specified in the GET /{db}/_all_docs API but allows for the query string parameters to be supplied as keys in a JSON object in the body of the POST request. :param db: Database name :param conflicts: Include conflicts information in response. Ignored if

include_docs isn’t true
Parameters:
  • descending (bool = False) – Return the documents in descending order by key
  • end_key (dict = None) – Stop returning records when the specified key is reached
  • end_key_doc_id (str = None) – Alias for endkey_docid
  • group (bool = False) – Group the results using the reduce function to a group or single row. Implies reduce is true and the maximum group_level
  • group_level (int = None) – Specify the group level to be used. Implies group is true
  • include_docs (bool = False) – Include the associated document with each row
  • attachments (bool = False) – Include the Base64-encoded content of attachments in the documents that are included if include_docs is true. Ignored if include_docs isn’t true.
  • att_encoding_info (bool = False) – Include encoding information in attachment stubs if include_docs is true and the particular attachment is compressed. Ignored if include_docs isn’t true
  • inclusive_end (bool = False) – Specifies whether the specified end key should be included in the result
  • key (dict = None) – Return only documents that match the specified key
  • keys (list = None) – Return only documents where the key matches one of the keys specified in the array
  • limit (int = None) – Limit the number of the returned documents to the specified number
  • reduce (bool = True) – Use the reduction function. Default is true when a reduce function is defined
  • skip (int = 0) – Skip this number of records before starting to return the results
  • sort (bool = False) – Sort returned rows (see Sorting Returned Rows). Setting this to false offers a performance boost. The total_rows and offset fields are not available when this is set to false.
  • stable (bool = False) – Whether or not the view results should be returned from a stable set of shards
  • stale (str = None) – Allow the results from a stale view to be used. Supported values: ok, update_after and false. ok is equivalent to stable=true&update=false. update_after is equivalent to stable=true&update=lazy. false is equivalent to stable=false&update=true
  • start_key (dict = None) – Return records starting with the specified key.
  • start_key_doc_id (str = None) – Return records starting with the specified document ID. Ignored if startkey is not set
  • update (bool = True) – Whether or not the view in question should be updated prior to responding to the user. Supported values: true, false, lazy
  • update_seq (bool = False) – Whether to include in the response an update_seq value indicating the sequence id of the database the view reflects
Returns:

Operating result
Return type:

UniversalResponse
Raises:

exc.CouchResponseError: – If server error occurred
db_bulk_docs(db: str, docs: list, new_edits: bool = True) → async_couch.types.UniversalResponse

The bulk document API allows you to create and update multiple documents at the same time within a single request. The basic operation is similar to creating or updating a single document, except that you batch the document structure and information. When creating new documents the document ID (_id) is optional. For updating existing documents, you must provide the document ID, revision information (_rev), and new document values. In case of batch deleting documents all fields as document ID, revision information and deletion status (_deleted) are required. —————-

db
Database name
docs: list
List of document objects
new_edits: bool=True
If false, prevents the database from assigning them new revision IDs
Returns:Operating result
Return type:UniversalResponse
Raises:exc.CouchResponseError: – If server error occurred
db_bulk_get(db: str, revs: bool = None, id: int = None) → async_couch.types.UniversalResponse

This method can be called to query several documents in bulk. It is well suited for fetching a specific revision of documents, as replicators do for example, or for getting revision history. ————————–

db
Database name
revs: bool = None
Give the revisions history
Returns:Operating result
Return type:UniversalResponse
Raises:exc.CouchResponseError: – If server error occurred
db_create(db: str, q: int = 8, n: int = 3, partitioned: bool = False)

Creates a new database. The database name {db} must be composed by following next rules:

  • Name must begin with a lowercase letter (a-z)
  • Lowercase characters (a-z)
  • Digits (0-9)
  • Any of the characters _, $, (, ), +, -, and /.

If you’re familiar with Regular Expressions, the rules above could be written as ^[a-z][a-z0-9_$()+/-]*$.

Parameters:
  • db (str) – Database name
  • n (int) – Replicas. The number of copies of the database in the cluster. The default is 3, unless overridden in the cluster config
  • q (int) – Shards, aka the number of range partitions. Default is 8, unless overridden in the cluster config.
  • partitioned (bool = False) – Whether to create a partitioned database.
Returns:

Operating result
Return type:

UniversalResponse
Raises:

exc.CouchResponseError: – If server error occurred
db_create_doc(db: str, doc: dict, batch: str = None) → async_couch.types.UniversalResponse

Creates a new document in the specified database, using the supplied JSON document structure. If the JSON structure includes the _id field, then the document will be created with the specified document ID.

If the _id field is not specified, a new unique ID will be generated, following whatever UUID algorithm is configured for that server.

Parameters:
  • db (str) – Database name
  • doc (dict) – document to create
  • batch (str = None) – Stores document in batch mode. Possible values: ok
Returns:

Operating result
Return type:

UniversalResponse
Raises:

exc.CouchResponseError: – If server error occurred
db_delete(db: str)

Deletes the specified database, and all the documents and attachments contained within it.

Parameters:db (str) – Database name
Returns:Operating result
Return type:UniversalResponse
Raises:exc.CouchResponseError: – If server error occurred
db_design_docs(db: str, conflicts: bool = False, descending: bool = False, end_key: str = None, end_key_doc_id: str = None, include_docs: bool = False, inclusive_end: bool = True, key: str = None, keys: str = None, limit: int = None, skip: int = 0, start_key: str = None, start_key_doc_id: str = None, update_seq: bool = False) → async_couch.types.UniversalResponse

POST _all_docs functionality supports identical parameters and behavior as specified in the GET /{db}/_all_docs API but allows for the query string parameters to be supplied as keys in a JSON object in the body of the POST request. ——————-

db
Database name
conflict: bool = false
Includes conflicts information in response. Ignored if include_docs
isn’t true.
end_key: str = none
Stop returning records when the specified design document ID is reached.
end_key_doc_id: str = none
Stop returning records when the specified design document ID is reached.
include_docs: bool = false
Include the full content of the design documents in the return.
inclusive_end: bool = true
Specifies whether the specified end key should be included in the result.
key: str = none
Return only design documents that match the specified key.
keys: str = none
Return only design documents that match the specified keys.
limit: int = none
Limit the number of the returned design documents to the specified number.
skip: int = 0
Skip this number of records before starting to return the results.
start_key: str = none
Return records starting with the specified key.
start_key_doc_id: str = none
Return records starting with the specified design document ID.
update_seq: bool = false
Response includes an update_seq value indicating which sequence id of the underlying database the view reflects.
Returns:Operating result
Return type:UniversalResponse
Raises:exc.CouchResponseError: – If server error occurred
db_exists(db: str) → async_couch.types.UniversalResponse

Returns the HTTP Headers containing a minimal amount of information about the specified database. Since the response body is empty, using the HEAD method is a lightweight way to check if the database exists already or not.

Parameters:db (str) – Database name
Returns:Operating result
Return type:UniversalResponse
Raises:exc.CouchResponseError: – If server error occurred
db_find(db: str, selector: dict, limit: int = 25, skip: int = None, sort: dict = None, fields: dict = None, use_index: dict = None, r: int = 1, bookmark: str = None, update: bool = True, stable: bool = None, stale: str = None, execution_stats: bool = False) → async_couch.clients.designs.responses.ExecuteViewResponse

Find documents using a declarative JSON querying syntax. Queries can use the built-in _all_docs index or custom indexes, specified using the

_index endpoint.
db
Database name
selector: dict
JSON object describing criteria used to select documents. More information provided in the section on selector syntax. Required
limit: int = 25
Maximum number of results returned.
skip: int = None
Skip the first ‘n’ results, where ‘n’ is the value specified.
sort: dict = None
JSON array following sort syntax.
fields: dict = None
JSON array specifying which fields of each object should be returned. If it is omitted, the entire object is returned. More information provided in the section on filtering fields.
use_index: dict = None
Instruct a query to use a specific index. Specified either as “<design_document>” or [“<design_document>”, “<index_name>”].
r: int = 1
Read quorum needed for the result. This defaults to 1, in which case the document found in the index is returned. If set to a higher value, each document is read from at least that many replicas before it is returned in the results. This is likely to take more time than using only the document stored locally with the index.
bookmark: str = None
A string that enables you to specify which page of results you require. Used for paging through result sets. Every query returns an opaque string under the bookmark key that can then be passed back in a query to get the next page of results. If any part of the selector query changes between requests, the results are undefined.
update: bool = True
Whether to update the index prior to returning the result.
stable: bool = None
Whether or not the view results should be returned from a “stable” set of shards.
stale: str = None
Combination of update=false and stable=true options. Possible options: “ok”, false (default).
execution_stats: bool = False
Include execution statistics in the query response.
Returns:Operating result
Return type:UniversalResponse
Raises:exc.CouchResponseError: – If server error occurred
db_info(db: str) → async_couch.clients.database.responses.ServerResponse

Gets information about the specified database.

Parameters:db (str) – Database name
Returns:Operating result
Return type:UniversalResponse
Raises:exc.CouchResponseError: – If server error occurred
des_info(db: str, des_id: str) → async_couch.types.UniversalResponse

Obtains information about the specified design document, including the index, index size and current status of the design document and associated index information.

Parameters:
  • db (str) – Database name
  • des_id (str) – Document id
Returns:

Operating result
Return type:

UniversalResponse
Raises:

exc.CouchResponseError: – If server error occurred
doc_copy(db: str, doc_id: str, destination: str, rev: str = None, batch: str = None) → async_couch.types.UniversalResponse

The COPY (which is non-standard HTTP) copies an existing document to a new or existing document. Copying a document is only possible within the same database.

The source document is specified on the request line, with the Destination header of the request specifying the target document.

Parameters:
  • db (str) – Database name
  • doc_id (str) – Document id
  • destination (str) – Destination document. Must contain the target document ID, and optionally the target document revision, if copying to an existing document
  • rev (str) – Actual document’s revision
  • batch (str = None) – Stores document in batch mode Possible values: ok
Returns:

Operating result
Return type:

UniversalResponse
Raises:

exc.CouchResponseError: – If server error occurred
doc_create_or_update(db: str, doc_id: str, doc: dict, rev: str = None, batch: str = None, new_edits: bool = True, attachments: List[async_couch.utils.content_types.MultipartRelatedAttachment] = None) → async_couch.types.UniversalResponse

The PUT method creates a new named document, or creates a new revision of the existing document. Unlike the POST /{db}, you must specify the document ID in the request URL.

When updating an existing document, the current document revision must be included in the document (i.e. the request body), as the rev query parameter, or in the If-Match request header.

Parameters:
  • attachments (List[Attachment]) – For bulk upload. In this case it should be sent as multipart related
  • db (str) – Database name
  • doc_id (str) – Document id
  • doc (dic) – Document data
  • rev (str = None) – Document’s revision if updating an existing document
  • batch (str = None) – Stores document in batch mode. Possible values: ok
  • new_edits (bool = True) – Prevents insertion of a conflicting document. Possible values: true (default) and false. If false, a well-formed _rev must be included in the document. new_edits=false is used by the replicator to insert documents into the target database even if that leads to the creation of conflicts. Optional
Returns:

Operating result
Return type:

UniversalResponse
Raises:

exc.CouchResponseError: – If server error occurred
doc_delete(db: str, doc_id: str, rev: str, batch: str = None) → async_couch.types.UniversalResponse

Marks the specified document as deleted by adding a field _deleted with the value true. Documents with this field will not be returned within requests anymore, but stay in the database. You must supply the current (latest) revision, either by using the rev parameter or by using the If-Match header to specify the revision.

Parameters:
  • db (str) – Database name
  • doc_id (str) – Document id
  • rev (str) – Actual document’s revision
  • batch (str = None) – Stores document in batch mode Possible values: ok
Returns:

Operating result
Return type:

UniversalResponse
Raises:

exc.CouchResponseError: – If server error occurred
doc_exists(db: str, doc_id: str) → async_couch.types.UniversalResponse

Returns the HTTP Headers containing a minimal amount of information about the specified document. The method supports the same query arguments as the GET /{db}/{docid} method, but only the header information (including document size, and the revision as an ETag), is returned.

Parameters:
  • db (str) – Database name
  • doc_id (str) – Document id
Returns:

Operating result
Return type:

UniversalResponse
Raises:

exc.CouchResponseError: – If server error occurred
doc_get(db: str, doc_id: str, attachments: bool = False, att_encoding_info: bool = False, attributes_since: str = None, conflicts: bool = False, deleted_conflicts: bool = False, latest: bool = False, local_seq: bool = False, meta: bool = False, open_revs: str = None, rev: str = None, revs: bool = False, revs_info: bool = False) → async_couch.types.UniversalResponse

Gets information about the specified database.

Parameters:
  • db (str) – Database name
  • doc_id (str) – Document id
  • attachments (bool = False) – Includes attachments bodies in response
  • att_encoding_info (bool = False) – Includes encoding information in attachment stubs if the particular attachment is compressed
  • attributes_since (str = None) – Includes attachments only since specified revisions. Does not includes attachments for specified revisions
  • conflicts (bool = False) – Includes information about conflicts in document
  • deleted_conflicts (bool = False) – Includes information about deleted conflicted revisions
  • latest (bool = False) – Forces retrieving latest “leaf” revision, no matter what rev was requested.
  • local_seq (bool = False) – Includes last update sequence for the document
  • meta (bool = False) – Acts same as specifying all conflicts, deleted_conflicts and revs_info query parameters
  • open_revs (str = None) – Retrieves documents of specified leaf revisions. Additionally, it accepts value as all to return all leaf revisions
  • rev (str = None) – Retrieves document of specified revision
  • revs (bool = False) – Includes list of all known document revisions
  • revs_info (bool = False) – Includes detailed information for all known document revisions
view_exec(db: str, des_id: str, view_name: str, conflicts: bool = False, descending: bool = False, end_key: dict = None, end_key_doc_id: str = None, group: bool = False, group_level: int = None, include_docs: bool = False, attachments: bool = False, att_encoding_info: bool = False, inclusive_end: bool = True, key: dict = None, keys: list = None, limit: int = None, reduce: bool = True, skip: int = 0, sort: bool = True, stable: bool = False, stale: str = None, start_key: dict = None, start_key_doc_id: str = None, update: bool = True, update_seq: bool = False) → async_couch.types.UniversalResponse

Executes the specified view function from the specified design document.

Parameters:
  • db – Database name
  • des_id – Design document name
  • view_name – View function name
  • conflicts (bool = False) – Include conflicts information in response. Ignored if include_docs isn’t true
  • descending (bool = False) – Return the documents in descending order by key
  • end_key (dict = None) – Stop returning records when the specified key is reached
  • end_key_doc_id (str = None) – Alias for endkey_docid
  • group (bool = False) – Group the results using the reduce function to a group or single row. Implies reduce is true and the maximum group_level
  • group_level (int = None) – Specify the group level to be used. Implies group is true
  • include_docs (bool = False) – Include the associated document with each row
  • attachments (bool = False) – Include the Base64-encoded content of attachments in the documents that are included if include_docs is true. Ignored if include_docs isn’t true.
  • att_encoding_info (bool = False) – Include encoding information in attachment stubs if include_docs is true and the particular attachment is compressed. Ignored if include_docs isn’t true
  • inclusive_end (bool = False) – Specifies whether the specified end key should be included in the result
  • key (dict = None) – Return only documents that match the specified key
  • keys (list = None) – Return only documents where the key matches one of the keys specified in the array
  • limit (int = None) – Limit the number of the returned documents to the specified number
  • reduce (bool = True) – Use the reduction function. Default is true when a reduce function is defined
  • skip (int = 0) – Skip this number of records before starting to return the results
  • sort (bool = False) – Sort returned rows (see Sorting Returned Rows). Setting this to false offers a performance boost. The total_rows and offset fields are not available when this is set to false.
  • stable (bool = False) – Whether or not the view results should be returned from a stable set of shards
  • stale (str = None) – Allow the results from a stale view to be used. Supported values: ok, update_after and false. ok is equivalent to stable=true&update=false. update_after is equivalent to stable=true&update=lazy. false is equivalent to stable=false&update=true
  • start_key (dict = None) – Return records starting with the specified key.
  • start_key_doc_id (str = None) – Return records starting with the specified document ID. Ignored if startkey is not set
  • update (bool = True) – Whether or not the view in question should be updated prior to responding to the user. Supported values: true, false, lazy
  • update_seq (bool = False) – Whether to include in the response an update_seq value indicating the sequence id of the database the view reflects
Returns:

Operating result
Return type:

UniversalResponse
Raises:

exc.CouchResponseError: – If server error occurred