Loading TOC...
XQuery temporal:document-insert

MarkLogic 12 EA 2 Product Documentation
temporal.documentInsert

temporal.documentInsert(
   temporal-collection as String,
   uri as String,
   root as Node,
   [options as Object?]
) as null

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:collectionCreate function. All versions of the temporal document will be associated with this temporal collection.
uri The URI to be used to identify the document in the database. If the document is not the latest version, a suffix will be concatenated to the document URI with a dot as the new URI of the document.
root The root node of the document. The root node can be one of XML format, JSON format, binary (BLOB) format, or text (CLOB) format.
options Options with which to customize this operation. This function supports the following options, plus the options from the xdmp.httpGet function.
permissions
Security permissions corresponding to the permissions for the document. The permissions specified only apply to the latest document versions created in this operation; previous versions of the documents will retain their previous permissions. If not supplied, the current user's default permissions are applied. The default value used for permissions can be obtained by calling the xdmp.defaultPermissions 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.
collections
The collection URIs for any additional, non-temporal collections the document is to belong to. 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.defaultCollections function. The collections specified only apply to the latest document versions created in this operation; previous versions of the documents will retain their previous 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.
forests
Specifies the ID of the forest in which this document is inserted. 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.statementSetSystemTime 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.

Usage Notes

When using element range indices as system axes, the document being inserted should include placeholders for the system axis start and end range indices.

Example

xquery version "1.0-ml";

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

let $root :=
<tempdoc>
   <content>v1-content here</content>
</tempdoc>

let $options :=  
  map:map() => map:with("metadata",
                 map:map() => map:with("validStart", "2014-04-03T11:00:00")
                           => map:with("validEnd", "2014-04-03T16:00:00")
               )
return 
temporal:document-insert("kool", "koolorder.xml", $root, $options)

Example

declareUpdate();
var root = { content : 'v1-content here' };
var options =
    {metadata:
       {validStart: '2014-04-03T11:00:00',
        validEnd: '2014-04-03T16:00:00'}
    };
temporal.documentInsert('kool', 'koolorder.json', root, options);

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