xdmp:document-insert
xdmp:document-insert(
$uri as xs:string,
$root as node(),
[$permissions as element(sec:permission)*],
[$collections as xs:string*],
[$quality as xs:int?],
[$forest-ids as xs:unsignedLong*]
) 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.
|
$permissions |
Security permission elements corresponding to the permissions
for the document. If not supplied, the current user's default
permissions are applied. The default value used for $permissions
can be obtained by calling xdmp:default-permissions(). A document that is
created by a non-admin user (that is, by any user who does not have the
admin role) must have at least one update permission,
otherwise the creation will throw an XDMP-MUSTHAVEUPDATE
exception.
|
collections |
The collection URIs for collections to which this document
belongs. If not supplied, the document is added to the current
user's default collections. For each collection that is protected, the
user must have permissions to update that collection or have the
any-collection privilege. For each unprotected collection,
the user must have the unprotected-collections privilege.
The default value used for $collections can be obtained by calling
xdmp:default-collections() .
|
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.
|
forest-ids |
Specifies the ID of the forest in which this document is inserted.
If the document already exists in the database and if $forest-ids is
not specified, it will remain 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 multiple forests are specified, the document
is inserted into one of the specifed forests. If the document exists
and the forest in which it is stored is set to delete-only, then you
must set $forest-ids to include one or more forests that allow updates,
otherwise an exception is thrown.
If you have local disk failover enabled, specify the ID of the master forest.
In the event of a failover, MarkLogic server will automatically redirect documents
to the replica forest. Specify the ID of the replica forest will result in a
"forest not in database" error.
|
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.
Example
xdmp:document-insert(
"/example.xml", <a>aaa</a>,
(xdmp:permission("editor", "read"),
xdmp:permission("editor", "update")),
"http://examples.com")
Example
xdmp:document-insert(
"/example.xml",
<a>aaa</a>,
xdmp:default-permissions(),
xdmp:default-collections(),
10)
Example
(:
Specify the forest IDs to move a delete-only document
from one forest to another (assuming at least one of
the forests allows updates).
:)
xdmp:document-insert(
"/example.xml",
<root>new content here</root>, (), (), 0,
xdmp:database-forests(xdmp:database()) )
Example
xquery version "1.0-ml";
(: create a text document :)
xdmp:document-insert("/text-doc.txt",
text { "This is a text document." } )
Stack Overflow: Get the most useful answers to questions from the MarkLogic community, or ask your own question.