Loading TOC...


   $uri as xs:string,
   $root as node(),
   [$options as (element()|map:map)?]
) as empty-sequence()


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.

$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.
Specify 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 the xdmp:default-permissions function. 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. When expressing options using a map:map, use the "object" format for permissions; see the output-kind parameter of xdmp:permission and xdmp:default-permissions.
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 the xdmp:default-collections function. When expressing options as an XML element, specify the collection URIs in <collection> child elements of this option, one URI per child. When expressing options as a map:map, specify the value of the collections key as a sequence of collection URIs.
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.
Specifies the IDs of one or more forests in which this document is inserted. Each forest is specified in a separate <forest> element. If the document already exists in the database and if forests 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 the forests option must 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.

Specifies key-value pairs representing certain metadata associated with the document. When you express options as an XML element, the value of a metadata element is a serialized map containing the key-value pairs. When you express options as a map:map, the value associated with "metadata" key is also a map:map.

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.xml", <a>aaa</a>,
    <options xmlns="xdmp:document-insert">
        map:map() => map:with("w", "world")
                  => map:with("h", "hello")


(: Insert with perm, collection, and quality options. Notice that this
 : example adds to, rather than replaces, the default collections. :)
    <options xmlns="xdmp:document-insert">  
        for $coll in xdmp:default-collections()
        return <collection>{$coll}</collection>


(: 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:permission("some-role", "read", "object")))


   Specify the valid start and end time for a temporal document.
    <root>new content here</root>, 
    <options xmlns="xdmp:document-insert">  
        map:map() => map:with("valid-start", "2014-06-03T14:13:05.472585-07:00")
                  => map:with("valid-end", "9999-12-31T11:59:59Z")


xquery version "1.0-ml";
(: create a text document :)
   text { "This is a text document." } )

Stack Overflow iconStack Overflow: Get the most useful answers to questions from the MarkLogic community, or ask your own question.


The commenting feature on this page is enabled by a third party. Comments posted to this page are publicly visible.
  • Is there a way to look at the source code for this xdmp:document-insert function?
  • What if i want to add date Time to my uri, how do i transform it so as to get multiple versions of a document? For example :- uri := '/example/sam/20181231T02:31:22.xml'
    • Hello, I recommend that you ask this on <a href="https://stackoverflow.com/questions/tagged/marklogic">Stack Overflow</a> where it will reach a wider audience, as well as others who may have the same question. For now, check out this old thread: https://developer.marklogic.com/pipermail/general/2013-May/013134.html
      • Thanks! Will do that. I was able to achieve it in Data Hub Framework.
  • How do you specify the contentType? When I try to insert a doc, which has a .xml extend, it sets it back to a txt content.
    • What kind of node are you inserting? For example, is it an XML element node? The document type is implicit in the node type (the second parameter). If you're trying to create a document by reading something from the filesystem, you might look at xdmp:document-get or xdmp:document-load, both of which have a "format" option with which you can specify the document type. Also, in future, you should consider asking questions like this on stackoverflow.com. You'll reach a wider audience there.
  • One way to ingest / insert text /XQY documents to MarkLogic https://uploads.disquscdn.com/images/ad35b39ef6b867698636f79e9578f09a3fba2e3137a03a2fff9457679566cd34.png
  • Gives an error while providing a forestID as mentioned in the example:( [1.0-ml] XDMP-PLACEKEYSLOCKING
    • Generally speaking, you should not specify the forest using the forestID parameter. For more information, see http://docs.marklogic.com/guide/ingestion/xquery#id_24146
  • while not specifically about xdmp:document-insert, this tutorial http://developer.marklogic.com/learn/config_status (specifically the client-manage-example-ml5.xqy) does a great job at explaining how it works