MAmacrometa
Documents

Update documents

Partially update documents. The _key attributes in the body specify which documents should be updated. The body of the request must contain a JSON array of document updates with the attributes to patch (the patch documents). All attributes from the patch documents are added to the existing documents if they do not yet exist and overwritten in the existing documents if they do exist.

Setting an attribute value to null in the patch documents causees a value of null to be saved for the attribute.

If ignoreRevs is false and there is a _rev attribute in a document in the body and its value does not match the revision of the corresponding document in the database, the precondition is violated.

If the document exists and can be updated, a HTTP 201 or a HTTP 202 is returned (depending on waitForSync, see below).

The body of the response contains a JSON array of the same length as the input array with the information about the handle and the revision of the updated documents. In each entry:

  • _id contains the known document-handle of each updated document.
  • _key contains the key that uniquely identifies a document.
  • _rev contains the new document revision.

In case of an error or violated precondition, an error object with the attribute error set to true and the attribute errorCode set to the error code is built.

If the query parameter returnOld is true, then, for each generated document, the previous revision of the document is returned under the old attribute in the result.

If the query parameter returnNew is true, then, for each generated document, the new document is returned under the new attribute in the result.

Note that if any precondition is violated or an error occurred with some of the documents, the return code is still 201 or 202, but the additional HTTP header X-C8-Error-Codes is set, which contains a map of the error codes that occurred together with their multiplicities, as in: 1200:17,1205:10 which means that in 17 cases the error 1200 "revision conflict" and in 10 cases the error 1205 "illegal document handle" has happened.

patch/_fabric/{fabric}/_api/document/{collection}

Request

Path parameters

fabricstring string required

The name of the fabric.

collectionstring string required

The name of the collection in which the documents are updated.

Query parameters

keepNullboolean

If set to false, you can use the patch command to remove attributes from an existing document if the patch document contains the same attributes with a null value.

mergeObjectsboolean

Controls whether objects (not arrays) are merged if present in both the existing and the patch document. If set to false, the value in the patch document overwrites the existing document's value. If set to true, objects are merged.

ignoreRevsboolean

If this is set to true, the _rev attributes in the given documents are ignored. If this is set to false, any _rev attribute given in a body document is taken as a precondition. The document is only updated if the current revision is the one specified.

returnOldboolean

If set to true, adds the old attribute which displays document revisions.

returnNewboolean

If set to true, adds the new documents to the new attribute.

waitForSyncboolean

If set to true, returns only after data has been synced to disk.

Request body

object required

Response

Successfully updated documents when waitForSync is enabled.

_idstring

ID of the collection.

_keystring

_key details of collection.

_revstring

_rev details of collection.

Example response

[
  {
    "_id": "test/foo",
    "_key": "foo",
    "_rev": "_dPRuHxe--_"
  }
]

Changes

No recorded changes to this operation across all 1 revision of this API.