MarkLogic 12 EA 1 Product Documentationxdmp:document-load
xdmp:document-load( $location as xs:string, [$options as (element()|map:map)?] ) as empty-sequence()
Summary
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.
| Parameters | |
|---|---|
| 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 qualified 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.
|
Required Privileges
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).
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.
Example
(: Load a document from the file system, using options expressed
: as an XML element. :)
xdmp:document-load("c:\myFile.xml",
<options xmlns="xdmp:document-load">
<uri>/documents/myFile.xml</uri>
<repair>none</repair>
<permissions>{xdmp:default-permissions()}</permissions>
<metadata>{
map:map() => map:with("h", "hello")
=> map:with("w", "world")
}</metadata>
</options>)
(: Loads the document with a URI "/documents/myFile.xml"
: and does not perform tag repair during the load. :)
Example
(: Load a document from the file system, using options expressed
: as a map:map. :)
xdmp:document-load("c:\myFile.xml",
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. :)
Example
xdmp:document-load("http://myCompany.com/file.xml",
<options xmlns="xdmp:document-load"
xmlns:http="xdmp:http">
<uri>/documents/myFile.xml</uri>
<repair>none</repair>
<permissions>{xdmp:default-permissions()}</permissions>
<format>xml</format>
<http:authentication>
<http:username>user</http:username>
<http:password>pass</http:password>
</http:authentication>
</options>)
(: 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'. :)
Example
(: Using a map to expression options, rather than an XML element. :)
xdmp:document-load("c:\myFile.xml",
map:map() => map:with("uri", "/documents/myFiles.xml")
=> map:with("permissions",
(xdmp:default-permissions("objects"),
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". :)