MarkLogic Server 11.0 Product Documentation
temporal:document-inserttemporal:document-insert(
$temporal-collection as xs:string,
$uri as xs:string,
$root as node(),
[$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.
|
| 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. You
can specify options as either an options XML element
in the "xdmp:document-insert" 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.
- 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:default-permissions
function. 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. 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:default-collections
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.
When expressing options as an XML element,
each forest ID is in a <forest> child element and is of
type
xs:unsignedLong. When expressing options as a map,
the value of this option is a sequence of forest IDs. 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.
|
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 :=
<options xmlns="xdmp:document-insert">
<metadata>
<map:map xmlns:map="http://marklogic.com/xdmp/map">
<map:entry key="validStart">
<map:value>2014-04-03T11:00:00</map:value>
</map:entry>
<map:entry key="validEnd">
<map:value>2014-04-03T16:00:00</map:value>
</map:entry>
</map:map>
</metadata>
</options>
return
temporal:document-insert("kool", "koolorder.xml", $root, $options)
Copyright © 2024 MarkLogic Corporation. MARKLOGIC is a
registered trademark of MarkLogic Corporation.