JavaScript temporal.documentLoad

MarkLogic 10 Product Documentation
temporal:document-load

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

Summary

This function inserts a document into the database and stores it as a temporal document. The document will belong to the specified temporal collection to ensure that it can only be updated or deleted using the temporal functions. If a temporal document already exists at the specified URI, this function performs an update instead of an insert. (Note that updates on temporal documents mean that a new document is created in the temporal collection with a different time period.)

An exception is thrown if $temporal-collection is not temporal or $collection includes temporal collection(s).

Parameters
temporal-collection The URI for the protected temporal collection in which the document is to belong. This must have been previously created by the temporal:collection-create function. All versions of the temporal document will be associated with this temporal collection.
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 "temporal:document-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 xdmp:http-get (when retrieving content via HTTP).
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: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.
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: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: 

    <collections>
      <collection>myCollection1</collection>
      <collection>myCollection2</collection>
    </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.
default-namespace
(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 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.
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.
default-language>
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. 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 specified 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.

metadata
Specifies key-value pairs representing certain metadata associated with the document. Metadata values are strings. Non-string values are converted to strings. Note that attempts to set the system times will be ignored. Instead use temporal:statement-set-system-time to set the system times. For details on how to set the system times, see Last Stable Query Time (LSQT) and Application-controlled System Time in the Temporal Developer's Guide.

Example

xquery version "1.0-ml";

import module namespace temporal = "http://marklogic.com/xdmp/temporal"
      at "/MarkLogic/temporal.xqy";

temporal:document-load("temporalCollection", "c:\myFile.xml",
    <options xmlns="temporal:document-load">
      <uri>/documents/myFile.xml</uri>
      <repair>none</repair>
      <metadata>
       <map:map xmlns:map="http://marklogic.com/xdmp/map">
          <map:entry key="validStart">
            <map:value>1601-01-01T13:59:00Z</map:value>
          </map:entry>
          <map:entry key="validEnd">
            <map:value>9999-12-31T11:59:59Z</map:value>
          </map:entry> 
        </map:map>
      </metadata> 
      <permissions>{xdmp:default-permissions()}</permissions>
    </options>)

=> Loads the temporal document with a URI "/documents/myFile.xml"
   into the temporal collection, "temporalCollection", and does not
   perform tag repair during the load.
Powered by MarkLogic Server | Terms of Use | Privacy Policy