MarkLogic 12 Product Documentationxdmp:document-insert
xdmp:document-insert( $uri as xs:string, $root as node(), [$options as (element()|map:map)?] ) as empty-sequence()
Summary
Inserts a new document into the database if a document with the
specified URI does not already exist. If a document already exists
at the specified URI, the function replaces the content of the existing
document with the specified content (the $root parameter)
as an update operation. In addition to replacing the content,
xdmp:document-insert replaces any permissions, collections,
and quality with the ones specified (or with the default values for these
parameters, if not explicitly specified). Also, if a properties
document exists at the same URI, that properties document (including any
content it contains) is preserved.
| Parameters | |
|---|---|
| uri | The URI of the document to be inserted. |
| root | The root node. The root node can be one of JSON format, XML format, binary (BLOB) format, or text (CLOB) format. |
| options |
Options with which to customize this operation. You
can specify options as either an options XML element
in the "xdmp:document-insert" namespace, or as a map:map.
The options names below are XML element localnames. When using a map,
replace the hyphens with camel casing. For example, "an-option"
becomes "anOption" when used as a map:map key.
This function supports the following options, plus the options from the
xdmp:http-get
function.
|
Required Privileges
If a new document is inserted, the unprotected-uri privilege
(only if the URI is not protected), the any-uri privilege, or an
appropriate URI privilege is also needed. If adding an unprotected
collection to a document, the unprotected-collections privilege
is needed; if adding a protected collection, the user must have either
permissions to update the collection or the
any-collection privilege.
Usage Notes
If a document is inserted with the admin user and its default permissions, the document will only be accessible by a user with the admin role as the default permissions of the admin user is empty.
Example
xdmp:document-insert(
"/example.xml", <a>aaa</a>,
<options xmlns="xdmp:document-insert">
<metadata>{
map:map() => map:with("w", "world")
=> map:with("h", "hello")
}</metadata>
<permissions>{xdmp:default-permissions()}</permissions>
</options>)
Example
(: Insert with perm, collection, and quality options. Notice that this
: example adds to, rather than replaces, the default collections. :)
xdmp:document-insert(
"/example.xml",
<a>aaa</a>,
<options xmlns="xdmp:document-insert">
<permissions>{xdmp:default-permissions()}</permissions>
<collections>{
<collection>/my/additional/collection</collection>,
for $coll in xdmp:default-collections()
return <collection>{$coll}</collection>
}</collections>
<quality>10</quality>
</options>)
Example
(: Expressing options as a map instead of an element :)
xquery version "1.0-ml";
xdmp:document-insert("/example.xml", <a>aaa</a>,
map:map() => map:with("collections", ("coll1","coll2"))
=> map:with("quality", 2)
=> map:with("permissions",
(xdmp:default-permissions("objects"),
xdmp:permission("some-role", "read", "object")))
)
Example
(:
Specify the valid start and end time for a temporal document.
:)
xdmp:document-insert(
"/example.xml",
<root>new content here</root>,
<options xmlns="xdmp:document-insert">
<metadata>{
map:map() => map:with("valid-start", "2014-06-03T14:13:05.472585-07:00")
=> map:with("valid-end", "9999-12-31T11:59:59Z")
}</metadata>
</options>)Example
xquery version "1.0-ml";
(: create a text document :)
xdmp:document-insert("/text-doc.txt",
text { "This is a text document." } )