xdmp.documentLoad

xdmp.documentloadxdmpdocumentload

/apidoc/8.0/xdmp:document-load.xml

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.

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.

location

String

The options object for this load operation. The default value is null. This parameter can also include options in xdmp.httpGet.

The xdmp.documentLoad options include:

uri

The URI of the document to be loaded. If omitted, then the location is used for the URI.

permissions

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.defaultPermissions(). 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 (the collections returned from xdmp.defaultCollections()). 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.
This option is an array of collection URIs.

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.

defaultNamespace

(XML only) The namespace to use if there is no namespace at the root node of the document. The default value is "".

repair

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 none.
This option has no effect on binary, text or JSON documents.

format

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.

defaultLanguage

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.

forests

Specifies the ID of the forest in which this document is inserted. This can be a single string or an array of strings, with each string being a forest ID. . 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.

encoding

Specifies the encoding to use when reading the document into MarkLogic Server. Supported values include UTF-8, ISO-8859-1, as well as many other popular encodings. See the Search Developer's Guide for a list of character set encodings by language. All encodings will be translated into UTF-8 from the specified encoding. The string specifed for the encoding option will be matched to an encoding name according to the Unicode Charset Alias Matching rules (http://www.unicode.org/reports/tr22/#Charset_Alias_Matching). An automatic encoding detector will be used if the value auto is specified. If no encoding can be detected, the encoding defaults to UTF-8. If no encoding option is specified and you are using a path with an http:// scheme, the encoding defaults to the encoding specified in the http header (if an encoding header is specified), otherwise it defaults to UTF-8.

options

Object?

null

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.httpGet (combined with xdmp.documentInsert) instead, as xdmp.httpGet allows you to examine the headers returned from the HTTP server.

http://marklogic.com/xdmp/privileges/xdmp-document-load

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).

declareUpdate();
xdmp.documentLoad("c:\\myFile.json",
    {
      "uri" : "/documents/myFile.json",
      "permissions" : xdmp.defaultPermissions()
    })

=> Loads the document with a URI "/documents/myFile.json".

declareUpdate();
xdmp.documentLoad("http://myCompany.com/file.json",
    {
      "uri" : "/documents/myFile.json",
      "permissions" : xdmp.defaultPermissions(),
      "format" : "json",
      "authentication" : {
        "username" : "user",
        "password" : "pass"
      }
    })

=> Loads the document with a URI "/documents/myFile.json"
   from the server http://myCompany.com, sending the
   credentials user/pass. The document is loaded as JSON.

declareUpdate();
xdmp.documentLoad("c:\myFile.json",
    {
      "uri" : "/documents/myFile.json",
      "permissions" : xdmp.defaultPermissions(),
      "collections" : ["myCollection1", "myCollection2"],
      "forests" : xdmp.forest("myForest")
    })

=> Loads the document with a URI "/documents/myFile.json", adding the
   document to the "myCollection1" and "myCollection2" collections,
   and loading the document into the forest named "myForest".