MarkLogic 9 Product Documentation
xdmp.documentInsert

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

Summary

Inserts a new document into the database if a document with the specified URI does not already exist. If a document already exists at the specified URI, the function replaces the content of the existing document with the specified content (the $root parameter) as an update operation. In addition to replacing the content, xdmp:document-insert replaces any permissions, collections, and quality with the ones specified (or with the default values for these parameters, if not explicitly specified). Also, if a properties document exists at the same URI, that properties document (including any content it contains) is preserved.

Parameters
uri	The URI of the document to be inserted.
root	The root node. The root node can be one of JSON format, XML 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 Specify 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 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 collections to which this document belongs. 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. 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 IDs of one or more forests in which this document is inserted. Each forest is specified in a separate `<forest>` element. If the document already exists in the database and if `forests` is not specified, 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 exists and the forest in which it is stored is set to delete-only, then the `forests` option must 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.

Required Privileges

If a new document is inserted, the unprotected-uri privilege (only if the URI is not protected), the any-uri privilege, or an appropriate URI privilege is also needed. If adding an unprotected collection to a document, the unprotected-collections privilege is needed; if adding a protected collection, the user must have either permissions to update the collection or the any-collection privilege.

Example

declareUpdate();
xdmp.documentInsert(
       '/example.json', {a:'aaa'},
       {metadata: {foo:'bar'},
        permissions : 
          [xdmp.permission('app-user', 'read'),
           xdmp.permission('app-user', 'update')],
        collections : 'http://examples.com'})

Example

declareUpdate();
xdmp.documentInsert(
       '/example.json',
       {a:'aaa'},
       {permissions : xdmp.defaultPermissions(),
        collections : xdmp.defaultCollections(),
        quality : 10})

Example

// Specify the valid start and end time for a temporal document.
declareUpdate();
xdmp.documentInsert(
    '/example.json',
    {foo:'new content here'}, 
    {metadata: {'valid-start' : '2014-06-03T14:13:05.472585-07:00',
                'valid-end' : '9999-12-31T11:59:59Z'}})

Example

// create a text document
declareUpdate();
var textNode = new NodeBuilder();
textNode.addText('This is a text document');
textNode = textNode.toNode();
xdmp.documentInsert('/text-doc.txt', textNode);

MarkLogic 9 Product Documentationxdmp.documentInsert

Summary

Required Privileges

Example

Example

Example

Example

MarkLogic 9 Product Documentation
xdmp.documentInsert