Loading TOC...

POST /v1/documents

Summary

Insert or update content and/or metadata for multiple documents in a single request.

URL Parameters
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.
transform? Names a content transformation previously installed via the /transforms service. Tranforms are applied only to content parts. The transform is applied to the content of a part prior to updating or inserting the document.
trans:{name}* A transform parameter name and value. For example, trans:myparam=1.
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 a temporal collection into which the documents are to be inserted. For details, see Managing Temporal Documents in the Temporal Developer's Guide.
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 or of a part. The Content-Type header for the request must be multipart/mixed. Each part must include a Content-Type header specifying the MIME type of the part. See the Usage Notes for accepted values for the Content-Type of a part.
Content-Disposition Each part must include a Content-Disposition that indicates the part type (content or metadata) and the document uri, and can contain additional options. For details, see Writing Multiple Documents in the REST Application Developer's Guide.
Accept The expected MIME type of the data in the response. Allowed values: application/xml, application/json.

Response

Upon success, MarkLogic Server responds with 200 (OK) and the data in the response body is an XML or JSON summary of the inserted or updated documents. The returned data is sufficient to construct a read request for each document. For details, see Response Overview in the REST Application Developer's Guide.

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

Using the system-time parameter also requires the following privilege:

http://marklogic.com/xdmp/privileges/temporal-statement-set-system-time

Usage Notes

Use this request to insert or update multiple documents in a single request. For single-document operations, see PUT /v1/documents and other forms of POST /v1/documents.

These notes provide only a brief overview of the supported features. For details, see Writing Multiple Documents in the REST Application Developer's Guide.

The multipart POST body can contain a mixture of document content and metadata. Each part must contain either content or metadata, indicated by use of the category parameter in the Content-Disposition part header. Metadata can apply to a specific document or multiple documents, depending on the content disposition.

You can insert or update a document at a known URI or at a server generated URI. For details, see Constructing a Content Part in the REST Application Developer's Guide. You cannot use server URI generation with a metadata part.

The Content-Disposition header can include the parameters listed below. You must include either inline or attachment. Other parameters depend on the type of part (content, request default metadata, document-specific metadata, etc.).

Parameter Description
inline The part contains either content for a document with a server generated URI or request default metadata. Use the category parameter to distinguish content from metadata. If this is a content part, you must also include extension. If this is a metadata part, you must not include extension. Use the category parameter to distinguish content from metadata.
attachment The part contains either content or metadata for a document with a specific URI (provided using filename). Use the category parameter to distinguish content from metadata.
filename=db-uri Specifies an explicit document URI. Use extension to have MarkLogic Server generate a URI instead. For a given part, filename and extension are mutually exclusive.
category=metadata Indicates that the part contains metadata.
extension=suffix Specifies a URI extension to use when the document URI is generated by MarkLogic Server. The generated URI will end with "." plus this extension. For a given part, filename and extension are mutually exclusive. For details, see Automatically Generating a Document URI in the REST Application Developer's Guide.
directory=path Specifies a directory prefix to use when the document URI is generated by MarkLogic Server. The directory prefix must end with "/". If the part header includes a directory parameter, it must also include an extension parameter. For a given part, filename and directory are mutually exclusive. For details, see Automatically Generating a Document URI in the REST Application Developer's Guide.
lang=language This parameter is deprecated and will be ignored if present. For a JSON content part, this parameter specifies the JSON content language. Allowed values: Any value accepted in the xml:lang attribute.
repair=level For an XML content part, the level of XML repair to perform. Allowed values: full (default) or none. Use full to request the server to repair malformed input XML. Use none to request the server to reject malformed input XML. If repair results in multiple root nodes, the update is rejected.
extract=properties-or-document For a binary content part, whether or not to extract metadata, and whether to store the extracted metadata as document properties or in a separate XHTML document. Allowed values: properties or document. See note below.
versionId=id When optimistic locking is enabled by setting the REST instance configuration property update-policy to version-required or version-optional, reject this request if the current version of this document does not match the version in versionId. Only applicable to content parts. Ignored if optimistic locking is not enabled. This option is equivalent to supplying a version id through the If-Match header of a single document update. For details, see Using Optimistic Locking to Update Documents in the REST Application Developer's Guide.
temporal-document=uri 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. You can only use this parameter if the request also includes the temporal-collection parameter.

With the exception of properties, any pre-existing metadata for documents updated by a multi-document write is replaced with either the metadata in the request or the in scope metadata defaults. For details see Constructing a Metadata Part in the REST Application Developer's Guide.

Extracting metadata for a binary content part as properties replaces any existing properties on the document. Extracting metadata to a document creates an XHTML document that differs from the input document only by having a xhtml file name extension. If CPF is installed in the database, the XHTML document includes a link to the binary document. For details, see Extracting Metadata and Text From Binary Documents in the Search Developer's Guide.

The documents you create with the MarkLogic REST API have the default permissions for the user and document as well as any permissions that you set explicitly. The permissions must include at least one update permission. For more detail, see Controlling Access to Documents and Other Artifacts in the REST Application Developer's Guide.

When working with temporal documents, the filename parameter in the Content-Dispotion header always refers to a document URI. When the system manages the version URIs, the document URI and the temporal document collection URI have the same value. When the user manages the version URIs, this may not be the case. When they differ, the filename parameter indicates the document URI, and the temporal-document parameter indicates the temporal document collection URI.

See Also

Example

NOTE: Do not attempt to cut-and-paste this example body. A multipart
body must contain control characters that are not preserved when you
cut-and paste. See "Generating Example Payloads with XQuery" in the
REST Application Developer's Guide for one alternative.

$ cat body
--BOUNDARY
Content-Type: application/xml
Content-Disposition: inline; category=metadata
Content-Length: 554

<?xml version="1.0" encoding="UTF-8"?>
<rapi:metadata xmlns:rapi="http://marklogic.com/rest-api">
  <rapi:quality>1</rapi:quality>
  <prop:properties xmlns:prop="http://marklogic.com/xdmp/property">
    <my-prop>my first property</my-prop>
  </prop:properties>
  <rapi:collections>
    <rapi:collection>my-first-coll</rapi:collection>
  </rapi:collections>
  <rapi:permissions>
    <rapi:permission>
      <rapi:role-name>readers</rapi:role-name>
      <rapi:capability>read</rapi:capability>
    </rapi:permission>
  </rapi:permissions>
</rapi:metadata>
--BOUNDARY
Content-Type: application/xml
Content-Disposition: attachment; filename="doc1.xml"
Content-Length: 60

<?xml version="1.0" encoding="UTF-8"?>
<root>some xml</root>
--BOUNDARY
Content-Type: application/json
Content-Disposition: attachment; filename="doc2.json"
Content-Length: 22

{ "key": "some json" }
--BOUNDARY
Content-Type: application/xml
Content-Disposition: attachment; filename="doc3.xml"
Content-Length: 60

<?xml version="1.0" encoding="UTF-8"?>
<root>some xml</root>
--BOUNDARY--

curl --anyauth --user user:password -X POST -i \
  --data-binary @body \
  -H "Content-type: multipart/mixed; boundary=BOUNDARY" 
  -H "Accept: application/json" 'http://localhost:8000/v1/documents'

==> Insert 3 documents into the database, doc1.xml, doc2.json, and
    doc3.xml. All three documents use the request default metadata
    provided in the first part. For more examples, see the REST
    Application Developer's Guide. MarkLogic Server returns a response
    similar to the following:

HTTP/1.1 200 OK
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 169
Connection: Keep-Alive
Keep-Alive: timeout=5

{ "documents": [
    { "uri": "doc1.xml",
      "mime-type": "application/xml",
      "category": [
        "metadata",
        "content"
      ]
    },
    { "uri": "doc2.json",
      "mime-type": "application/json",
      "category": [
        "metadata",
        "content"
      ]
    },
    { "uri": "doc3.xml",
      "mime-type": "application/xml",
      "category": [
        "metadata",
        "content"
      ]
    }
] }

If you set the Accept header to application/XML, the data in the 
response is similar to the following:

<rapi:documents xmlns:rapi="http://marklogic.com/rest-api">
  <rapi:document>
    <rapi:uri>doc1.xml</rapi:uri>
    <rapi:category>metadata</rapi:category>
    <rapi:category>content</rapi:category>
    <rapi:mime-type>application/xml</rapi:mime-type>
  </rapi:document>
  <rapi:document>
    <rapi:uri>doc2.json</rapi:uri>
    <rapi:category>metadata</rapi:category>
    <rapi:category>content</rapi:category>
    <rapi:mime-type>application/json</rapi:mime-type>
  </rapi:document>
  <rapi:document>
    <rapi:uri>doc3.xml</rapi:uri>
    <rapi:category>metadata</rapi:category>
    <rapi:category>content</rapi:category>
    <rapi:mime-type>application/xml</rapi:mime-type>
  </rapi:document>
</rapi:documents>
  

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