MarkLogic 9 Product Documentation

POST /v1/documents

Summary

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

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

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.).

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.

If no permissions are explicitly set, documents you create with the MarkLogic REST API have a read permission for the rest-reader role and an update permission for the rest-writer role. If you explicitly set permissions, the permissions must include at least one update permission.

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

• Writing Multiple Documents in the REST Application Developer's Guide.

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>