MarkLogic 12 Product Documentation
dls:document-extract-part

dls:document-extract-part(
   $new-uri as xs:string,
   $element as element(),
   $annotation as item()*,
   $retain-history as xs:boolean,
   [$permissions as item()*],
   [$collections as xs:string*],
   [$quality as xs:integer?],
   [$forest-ids as xs:unsignedLong*]
) as xs:string*

Summary

This function extracts an XML element from an existing document and creates a new document from the extracted element. The extracted element is removed from the root node document and replaced by an XInclude to the new document. A new version of the root node document is created. You must have already performed a dls:document-checkout of the document that contains the element to be extracted.

The $new-uri must be an absolute path and is initially not checked out. This will create a new version of both the original document and the newly included document, with $annotation being used to create a dls:annotation property on each of them.

Parameters
new-uri	The URI for the new document.
element	The element to be extracted and used to create the new document. This element can be one of XML format, binary (BLOB) format, or text (CLOB) format.
annotation	Any comments you want to add to the new versions of the documents.
retain-history	Determines whether or not to retain the document's properties fragment in the database. Set to `true` to retain the original document's properties in order to track when the document was updated and by whom. Otherwise, set to `false`.
permissions	The permissions to be set on the new document. When run in an XQuery context, the permissions are a sequence of XML elements (sec:permission). When importing this module into a Server-Side JavaScript context, the permissions are an array of Objects. If not supplied, default permissions are applied. The default value used for this parameter 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.
collections	The collection URIs for the collections to which the new document is to belong. If not supplied, the document is added to your current default collections. For each collection that is protected, you must have permissions to update that collection or have the any-collection privilege. For each unprotected collection, you must have the unprotected-collections privilege. The default value used for this parameter can be obtained by calling `xdmp:default-collections()`.
quality	Specifies the quality of the document created from the extracted element. 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.
forest-ids	Specifies the ID of the forest in which the document created from the extracted element is inserted. If the document already exists in the database and if this parameter 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 specified forests. If the document exists and the forest in which it is stored is set to delete-only, then you must set this parameter to include one or more forests that allow updates, otherwise an exception is thrown.

Required Privileges

The dls-user role is required to run this function, or the privilege:
http://marklogic.com/xdmp/privileges/dls-user

Example

  xquery version "1.0-ml";

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

  dls:document-extract-part("/foo/bar/baz-chapter1.xml", 
      fn:doc("/foo/bar/baz.xml")//CHAPTER1, 
      "part insert",
      fn:true(),
      (xdmp:permission("dls-user","insert"),
       xdmp:permission("dls-user","read"),
       xdmp:permission("dls-user","update"),
       xdmp:permission("admin","insert"),
       xdmp:permission("admin","read"),
       xdmp:permission("admin","update")))

  (: Extracts the <CHAPTER1> element from the 'baz.xml' file and creates a new document,
     named 'baz-chapter1.xml', containing the extracted element. :)

MarkLogic 12 Product Documentationdls:document-extract-part

Summary

Required Privileges

Example

MarkLogic 12 Product Documentation
dls:document-extract-part