Insert or update document contents and/or metadata, at a caller-supplied document URI.
|uri||The URI of the document to be created or updated.|
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: |
|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 metadata in the request body. Specifying a format overrides the Content-Type request header value when inserting only metadata. For details, see the Usage Notes and Controlling Input and Output Content Type in the REST Application Developer's Guide.|
|collection*||The URI of a collection to which to add the document. Use this parameter only when the request includes content; see the Usage notes for details.|
|quality?||The quality of this document. A positive value increases the relevance score of the document in text search functions. The converse is true for a negative value. The default value is 0. Use this parameter only when the request includes content; see the Usage notes for details.|
Assign the document to the listed role, with the permission given in
the parameter value. For example, |
Attach the named property to the document, with the given property value.
For example, |
For binary content, whether or not to extract metadata, and whether to
store the extracted metadata as properties or in a separate XHTML
document. Accepted values: |
The type of XML repair to perform on the input content. Accepted values:
Names a content transformation previously installed via the
A transform parameter name and value. For example,
|forest-name?||Specifies the name of a forest into which this document is inserted. If the document already exists in the database, it remains in its existing forest. If no such forest exists or if no such forest is attached to the context database, an error is raised. If the document already exists and the forest in which it is stored is set to delete-only, an error is raised.|
The transaction identifier of the multi-statement transaction in
which to service this request. Use the |
This parameter is deprecated and will be ignored. When ingesting JSON
content, this parameter specifies the JSON content language. Accepted
values: Any value accepted in the |
|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.|
Set the system start time for the insertion or update. Ignored if
|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.|
Upon success, MarkLogic Server responds with 201 (Created) or 204 (Updated).
rest-writerrole, or the following privileges:
If no permissions are explicitly set, documents you create with the
MarkLogic REST API have a read permission for the
role and an update permission for the
You can add or update content and metadata in a single request in two
ways: Construct a
multipart/mixed request with the
metadata and content in the request body parts, or place the content
in the request body and specify metadata using the
parameters. You cannot combine these methods: Metadata request parameters
are ignored when the request body includes metadata. The metadata request
parameters are only usable when you also insert or update content.
To use a
multipart/mixed request to insert/update content
and metadata in the same request, put the metadata in the
first part and specify its content type (XML or JSON) using the
Content-type header of the part or the
parameter. Put the content in the second part and set the Content-type
header on the part to the appropriate MIME type for the content.
To add or replace just metadata, specify the metadata in the request
body and specify its content type (XML or JSON) using the Content-type
header or the
format request parameter. You cannot use
the metadata request parameters without content.
For metadata values supplied in the request body, use a single XML or JSON container, as described in Loading Content into the Database in the REST Application Developer's Guide.
category to completely replace a category of metadata.
category=properties replaces all existing
properties of a document. Use the specific metadata parameters to
selectively modify a metadata category. For example, use
prop:decade=70 to add or modify just the "decade" property.
category=metadata replaces all metadata for
the document. Metadata request parameters are ignored when the request
body includes metadata.
Extracting metadata 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
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.
When updating document permissions, the permissions must include at least one update permission.
For more details, see Loading Content into the Database in the REST Application Developer's Guide.
curl --anyauth --user user:password -T ./my-content -i \ -H "Content-type: application/xml" \ http://localhost:8000/v1/documents?uri=/shakespeare/plays/a_and_c.xml ==> If a document already exists with URI /shakespeare/plays.a_and_c.xml, the document contents are updated with the contents of the file ./my-content, and the following headers are returned: Server: MarkLogic Content-Type: text/plain; charset=UTF-8 Content-Length: 31 Connection: close HTTP/1.1 100 Continue HTTP/1.1 204 Updated Server: MarkLogic Content-Length: 0 Connection: close ==> If a document does not already exist with URI /shakespeare/plays/a_and_c.xml, a new document in created with that URI, and the following headers are returned: Server: MarkLogic Content-Type: text/plain; charset=UTF-8 Content-Length: 31 Connection: close HTTP/1.1 100 Continue HTTP/1.1 201 Document Created Location: /shakespeare/plays/a_and_c.xml Server: MarkLogic Content-Length: 0 Connection: close