Insert or update document contents and/or metadata, at a caller-supplied document URI.
URL Parameters | |
---|---|
uri | The URI of the document to be created or updated. |
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, 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 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. |
perm:{role}* |
Assign the document to the listed role, with the permission given in
the parameter value. For example, perm:editor=update .
Valid values: read, update, execute . Only the named role
is changed. Unspecified roles retain their current permissions. Use
this parameter only when the request includes content; see the Usage
notes for details.
|
prop:{name}* |
Attach the named property to the document, with the given property value.
For example, prop:decade=70 . The property name must be an
xs:NCName . If the property already exists, its value is
replaced. Only the named property is modified. Unspecified properties
are unaffected. Use this parameter only when the request includes
content; see the Usage notes for details.
|
extract? |
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: properties or
document . See note below.
|
repair? |
The type of XML repair to perform on the input content. Accepted 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.
|
transform? |
Names a content transformation previously installed via the
/transforms service. The service applies the transformation
to the content prior to updating or inserting the document or metadata.
|
trans:{name}* |
A transform parameter name and value. For example,
trans:myparam=1 .
|
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. |
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.
|
lang? |
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 xml:lang attribute.
|
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. 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. |
Upon success, MarkLogic Server responds with 201 (Created) or 204 (Updated).
rest-writer
role, or the
following privileges:
http://marklogic.com/xdmp/privileges/rest-writer
http://marklogic.com/xdmp/privileges/rest-reader
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.
When you explicitly set permissions, they are combined with the default
permissions for the role of the current user.
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 collection
,
quality
, perm
, and prop
request
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 format
request
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.
Use category
to completely replace a category of metadata.
For example, 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.
Using 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 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.
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
Stack Overflow: Get the most useful answers to questions from the MarkLogic community, or ask your own question.