Loading TOC...

MarkLogic 9 Product Documentation
POST /v1/documents?uri={db-uri}

Summary

Perform a partial update to content or metadata of a document at a caller-specified URI. This operation is equivalent to PATCH /v1/documents.

URL Parameters
uri The URI of the document whose content or metadata is being updated. Required.
category* The category of data to insert or update. Category may 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. See the Usage notes below.
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.
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.
X-HTTP-Method-Override This header signals that this request is a partial update to document content or metadata. You must include this header and it must have a value of PATCH.

Response

Upon success, MarkLogic Server responds with 201 (Document Created) or 204 (Updated or Unchanged).

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

Use this form of POST /v1/documents to update a portion of the content and/or metadata for an existing document at a caller-supplied URI. For all other document and metadata creation and update operations, use PUT /v1/documents or one of the other forms of POST /v1/documents.

You can also use a PATCH request to apply a partial update. For details, see PATCH /v1/documents. The functionality and request body contents are the same.

To perform a partial update of content and/or metadata, specify the document URI using the uri parameter, set the category parameter to reflect the content and/or metadata to be modified, and set the request header X-HTTP-Method-Override to PATCH. 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 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 POST -d@'./my-patch.xml' -i \
  -H "Content-type: application/xml" -H "X-HTTP-Method-Override: PATCH" \
  '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 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 POST -d@'./my-patch.json' -i \
  -H "Content-type: application/json" -H "X-HTTP-Method-Override: PATCH" \
  '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
  

Stack Overflow iconStack Overflow: Get the most useful answers to questions from the MarkLogic community, or ask your own question.