PATCH /v1/documents

Summary

Perform a partial update to content or metadata of a document.

URL Parameters
uri The URI of the document to be updated.
category* The category of data to insert or update. Category can be specified multiple times to insert or replace any combination of content and metadata. Valid categories: content (default), metadata, metadata-values, collections, permissions, properties, and quality. Use metadata to update all metadata.
database? Perform this operation on the named content database instead of the default content database associated with the REST API instance. Using an alternative database requires the "eval-in" privilege; for details, see Security Requirements in the REST Application Developer's Guide.
format? The content type of the patch specification and any metadata in the request body. Specifying format overrides the Content-type header if the Content-type header does not map to a MIME type equivalent to XML or JSON. Allowed values: xml, json. For details, see Controlling Input and Output Content Type in the REST Application Developer's Guide.
txid? The transaction identifier of the multi-statement transaction in which to service this request. Use the /transactions service to create and manage multi-statement transactions.
temporal-collection? Specify the name of the temporal collection to which the document being updated belongs. For details, see Managing Temporal Documents in the Temporal Developer's Guide.
temporal-document? The "logical" document URI in the temporal collection specified using the temporal-collection request parameter. For details, see Managing Temporal Documents in the Temporal Developer's Guide. This parameter can only be used when the temporal-collection parameter is also present.
source-document? The temporal collection document URI of the document to be patched. This must be the URI of a document in the collection specified by the temporal-collection parameter. See the Usage Notes for details.
system-time? Set the system start time for the insertion or update. This time will override the system time set by MarkLogic. Ignored if temporal-collection is not included in the request.
Request Headers
Content-Type? The MIME type of the data in the request body. See the usage notes for details on special handling for XML, JSON, and binary content.
If-Match? Specifies a document version identifier that must match the current version of the target document for the update to succeed. If the current version of the document does not match, a 412 (Precondition Failed) status is returned. A value of 0 indicates the document must not already exist in the database. Ignored unless optimistic locking is enabled; for details see Using Optimistic Locking to Update Documents in the REST Application Developer's Guide.

Response

Upon success, MarkLogic Server responds with 204 (Content Updated).

Required Privileges

This operation requires the rest-writer role, or the following privileges:

http://marklogic.com/xdmp/privileges/rest-writer

http://marklogic.com/xdmp/privileges/rest-reader

Usage Notes

If using the PATCH method is problematic in your environment, you can use POST instead. For details, see POST /v1/documents.

To perform a partial update of content and/or metadata for an existing document, specify the document URI using the uri parameter and set the category parameter to reflect what to update, if needed. The request body must be a JSON or XML patch specification.

You can only apply partial updates of content to XML and JSON documents. You can apply partial updates of metadata to any document type.

When updating document permissions, the permissions must include at least one update permission.

When patching a temporal document, the uri parameter specifies the URI of the output document. If you do not specify a source document using source-document or temporal-document, then uri also specifies the URI of the input document.

Use the temporal-document parameter to identify the temporal document collection URI. If temporal-document is present and source-document is not present, then temporal-document identifies the input document. If source-document is present, then it identifies the input document. The input document must be in the temporal collection specified in the temporal-collection parameter.

The metadata-values category represents "metadata fields" document metadata. For more details, see Metadata Fields in the Administrator's Guide.

See Also

Example

$ cat ./my-patch.xml
<rapi:patch xmlns:rapi="http://marklogic.com/rest-api" 
    xmlns:my-ns="http://marklogic.com/examples">
  <rapi:insert context="/my-ns:parent" position="last-child">
    <my-ns:child>inserted</my-ns:child>
  </rapi:insert>
</rapi:patch>

curl --anyauth --user user:password -X PATCH -d@'./my-patch.xml' -i \
  -H "Content-type: application/xml" \
  'http://localhost:8000/v1/documents?uri=/doc/example.xml'

==> Perform a partial update on the document with URI /doc/example.xml.
    A <child/> element is added as the last child of the node with
    the XPath /my-ns:parent. MarkLogic Server responds with headers
    similar to the following:

Content-type: application/xml
Server: MarkLogic
Content-Length: 211
Connection: Keep-Alive
Keep-Alive: timeout=5

HTTP/1.1 204 Content Updated
Server: MarkLogic
Content-Length: 0
Connection: Keep-Alive
Keep-Alive: timeout=5

Example

$ cat ./my-patch.json
{ "patch": [
    { "insert": {
          "context": "/parent",
          "position": "last-child",
          "content": { "child": "inserted" }
    }}
] }

curl --anyauth --user user:password -X PATCH -d@'./my-patch.json' -i \
  -H "Content-type: application/json" \
  'http://localhost:8000/v1/documents?uri=/doc/example.json'

==> Perform a partial update on the document with URI /doc/example.json.
    A key-value pair with key 'child' is added as the last child of the 
    top level 'parent' key.  MarkLogic Server responds with headers
    similar to the following:

Content-type: application/xml
Server: MarkLogic
Content-Length: 211
Connection: Keep-Alive
Keep-Alive: timeout=5

HTTP/1.1 204 Updated
Server: MarkLogic
Content-Length: 0
Connection: Keep-Alive
Keep-Alive: timeout=5
Powered by MarkLogic Server | Terms of Use | Privacy Policy