Loading TOC...


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


Inserts a new document with the specified URI. If a document already exists at the URI, the function replaces the content in the existing document as an update operation.

$location The location of the input document. If the scheme of the location is HTTP (that is, if the string starts with "http://"), then the document is requested over HTTP. If the scheme is file (that is, if the string starts with "file://"), then the document is requested over file protocol from the local filesystem. Otherwise, the document is fetched from the local filesystem. On the filesystem, the path can be fully qualifed or relative. Relative pathnames are resolved from the directory in which MarkLogic Server is installed.
$options Options with which to customize this operation. You can specify options as either an options XML element in the "xdmp:load" 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.
The URI of the document to be loaded. If omitted, then the location is used for the URI.
Security permission 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. 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 (the collections returned from xdmp: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 <collections> element consists of one or more <collection> child elements. For example:


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.
(XML only) The namespace to use if there is no namespace at the root node of the document. The default value is "".
A value of full specifies that malformed XML content be repaired. A value of none specifies that malformed XML content is rejected.

If no repair option is explicitly specified, the default is implicitly specified by the XQuery version of the caller. In XQuery 1.0 and 1.0-ml the default is none. In XQuery 0.9-ml the default is full.

This option has no effect on binary, text or JSON documents.
A value of text specifies to get the document as a text document, regardless of the URI specified. A value of binary specifies to get the document as a binary document, regardless of the URI specified. A value of xml specifies to get the document as an XML document, regardless of the URI specified. A value of json specifies to get the document as a JSON document, regardless of the URI specified.
The language to specify in an xml:lang attribute on the root element node if the root element node does not already have an xml:lang attribute. This option applies only to XML documents. If this option is not specified, then nothing is added to the root element node.
Specifies the encoding to use when reading the document into MarkLogic Server. The value must either be "auto" or match an encoding name according to the Unicode Charset Alias Matching rules (http://www.unicode.org/reports/tr22/#Charset_Alias_Matching). When the value is "auto", MarkLogic guesses the encoding from the document content. For a list of character set encodings by language, see Collations and Character Sets By Language in the Search Developer's Guide. If you do not set this option, MarkLogic uses the encoding specified in the HTTP headers, if present. If you do not set this option and no encoding is available from HTTP headers, the encoding defaults to UTF-8. For more details, see Character Encoding in the Search Developer's Guide.
Specifies the ID of the forest in which this document is inserted. Each forest ID is in a <forest> child element and is of type xs:unsignedLong. . If the document already exists in the database, 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 already exists and the forest in which it is stored is set to delete-only, then you must specify the 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.

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

Required Privileges


If a new document is inserted, you also need the unprotected-uri privilege (only if the URI is not protected), the any-uri privilege, or an appropriate URI privilege.

If adding an unprotected collection to a document, the unprotected-collections privilege (http://marklogic.com/xdmp/privileges/unprotected-collections) is needed; if adding a protected collection, the user must have either permissions to update the collection or the any-collection privilege (http://marklogic.com/xdmp/privileges/any-collection).

Usage Notes

When selecting documents over HTTP (where the $location parameter begins with http://), the response from the webserver is loaded into the database, regardless of what the headers returned from the webserver indicate. For example, if the webserver returns a 404 (file not found), then the response page that says "file not found" is loaded into the database. If you want to examine the headers before loading the document, use xdmp:http-get (combined with xdmp:document-insert ) instead, as xdmp:http-get allows you to examine the headers returned from the HTTP server.


(: Load a document from the file system, using options expressed
 : as an XML element. :)
    <options xmlns="xdmp:document-load">
        map:map() => map:with("h", "hello")
                  => map:with("w", "world")

(: Loads the document with a URI "/documents/myFile.xml"
 : and does not perform tag repair during the load. :)


(: Load a document from the file system, using options expressed
 : as a map:map. :)
    map:map() => map:with("uri", "/documents/myFile.xml")
              => map:with("repair", "none")
              => map:with("metadata", map:map() => map:with("key", "value"))

(: Loads the document with a URI "/documents/myFile.xml"
 : and does not perform tag repair during the load. :)


    <options xmlns="xdmp:document-load"

(: Loads the document with a URI "/documents/myFile.xml"
 : from the server http://myCompany.com, sending the
 : credentials user/pass. Tag repair is not performed
 : during the load, the document is loaded as xml with
 : metadata key-value pairs of 'h:hello' and 'w:world'. :)


(: Using a map to expression options, rather than an XML element. :)
  map:map() => map:with("uri", "/documents/myFiles.xml")
            => map:with("permissions", 
                         xdmp:permission("some-role", "read", "object")))
            => map:with("collections", ("myCollection1", "myCollection2"))
            => map:with("repair", "full")
            => map:with("forests", (xdmp:forest("myForest")))

(: Loads the document with a URI "/documents/myFile.xml"
 : performing tag repair during the load, adding the
 : document to the "myCollection1" and "myCollection2"
 : collections, and loading the document into the forest
 : named "myForest". :)

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.
  • If the file name or directory name has a space in it. How to handle it in Makrlogic? While loading it through xdmp:document-load it throws an error. And in case of MLCP it replaces the space with %. Please help!!
    • A well-formed URI does not contain whitespace. That is why mlcp URI-encodes them. You can read more about it here: https://developer.marklogic.com/blog/whitespace-in-uris.
  • xdmp:document-load("C:/MarkLogic Sample Project/MLProto/PDF/Mexico.pdf",<options xmlns="xdmp:document-load"> <uri>/PDF</uri> <repair>none</repair></options> <format>pdf</format>) What is the problem in the above code? I am trying to ingest PDF files into ML.
    • It would be helpful to see the exact error you are getting, but for starters, "pdf" is not a supported document format. Your choices are xml, json, binary, and text. A PDF file should be loaded as a binary document. Also, though this will not cause an error, I think it unlikely that you want your document URI to be "/PDF". Perhaps, "/PDF/Mexico.pdf"? The <code>uri</code> option is the URI for the document in the database, not simply the name of a directory. Lastly, I strongly encourage you to ask questions like this on stackoverflow. They'll reach a wider audience.
  • can we load multiple documents in a local directory using xdmp:document-load? i know that we can use MLCP for bulk loading but is it possible in using XQUERY
    • xdmp:document-load() will not read multiple files at once. However, you can use xdmp:filesystem-directory() to get a listing of files and then call xdmp:document-load for each of them. I would definitely prefer using MLCP to this approach if there are a lot of files to load, but for a smaller number this should be fine.
  • Why oh why is the relative file location relative to the MarkLogic installation folder? The current xquery script file would be so much more convenient ...
    • Because it wouldn't be useful or consistent. To execute a 'current xquery script' it needs to be in the Modules database or directory. If its in the Modules DB then there is no 'current directory' for the xquery except the Database, which isn't a filesystem so document-load wouldn't work at all. If its in the filesystem then it would depend on which App Server you were running, and if the code is in an included module or not, and its associated Modules Root setting to determine the source file and the default destination URI. The server's install directory is one of the few consistent paths that is unlikely to change over time or differ between runtime contexts. Use xdmp:modules-root() to explicitly locate filesystem based xquery files.
  • Tip: If the first argument is "rest::" then the document will be streamed directly from the PUT or POST request body.  See Modules/MarkLogic/rest-api/models/document-model-update.xqy.