MarkLogic Server
XQUERY/XSLT API DOCUMENTATION
4.2
All XQuery & XSLT Functions
MarkLogic Built-In Functions
XQuery Library Modules
CPF Functions
W3C-Standard Functions
  W3C XQuery/XSLT Reference
W3C XQuery Functions
W3C XQuery Language
W3C XSLT Language
This page was generated
September  12,  2012
6:02  AM
XQuery & XSLT Built-In & Modules Function Reference

Module: Library Services - XInclude Functions

XInclude functions.
Function Summary
dls:document-extract-part This function extracts an element from an existing document and creates a new document from the extracted element.
dls:link-expand This function performs a single level expansion of a single XInclude reference.
dls:link-references This function returns a list of all the distinct URIs of documents referenced (either directly or indirectly) in the expansion of the node.
dls:node-expand This function recursively examines the node for XInclude references and expands them, following the rules of the XInclude specification.
Function Detail
dls:document-extract-part(
$new-uri as xs:string,
$element as element(),
$annotation as item()*,
$retain-history as xs:boolean,
[$permissions as element(sec:permission)*],
[$collections as xs:string*],
[$quality as xs:integer?],
[$forest-ids as xs:unsignedLong*]
)  as   xs:string*
Summary:

This function extracts an 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 (optional): The permissions to be set on the new document. If not supplied, default permissions are applied. The default value used for this parameter can be obtained by calling xdmp:default-collections(). 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 (optional): 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 (optional): 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 (optional): 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 specifed 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 Privilege:

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. :)
dls:link-expand(
$context as node(),
$ref as element(xi:include),
$restriction as cts:query?
)  as   node()*
Summary:

This function performs a single level expansion of a single XInclude reference. Any XInclude references in the referenced node are not expanded.

Parameters:
$context : The node that contains the XInclude reference.
$ref : The XInclude reference to be expanded.
$restriction : Restriction that control which documents may be considered for inclusion. An exact URI match is first considered if it matches the specified restrictions, followed by the most recent numbered version of that URI that matches the restrictions.

Required Privilege:

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";

  declare namespace xi="http://www.w3.org/2001/XInclude";

  let $node := fn:doc("/foo/bar/baz.xml")

  return dls:link-expand($node, 
                         $node/BOOK/xi:include[1], 
                         dls:documents-query())

  (: Returns the first referenced node in the 'BOOK' element in the 
     latest version of the 'baz.xml' document. :)
dls:link-references(
$node as node(),
$restriction as cts:query?
)  as   xs:string*
Summary:

This function returns a list of all the distinct URIs of documents referenced (either directly or indirectly) in the expansion of the node. The URIs are mapped according to the specified restrictions.

Parameters:
$node : The node to be expanded.
$restriction : Restriction that control which documents may be considered for inclusion. An exact URI match is first considered if it matches the specified restrictions, followed by the most recent numbered version of that URI that matches the restrictions.

Required Privilege:

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";

  let $node := fn:doc("/foo/bar/baz.xml")

  return dls:link-references($node, dls:document-version-query(4))

  (: Returns the URIs of the referenced nodes in Version 4 of the 'baz.xml' 
     document and all of the referenced nodes referenced from its referenced 
     nodes. :)
dls:node-expand(
$node as node(),
$restriction as cts:query?
)  as   node()
Summary:

This function recursively examines the node for XInclude references and expands them, following the rules of the XInclude specification. The result is a node in which all the XInclude references have been resolved, or an error if there were unresolvable references with no fallback specifications. The URIs are mapped according to the specified restrictions.

Parameters:
$node : The node to be expanded.
$restriction : Restriction that control which documents may be considered for inclusion. An exact URI match is first considered if it matches the specified restrictions, followed by the most recent numbered version of that URI that matches the restrictions.

Required Privilege:

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

Usage Notes:

This function cannot expand root node documents that contain XInclude links to specific versioned documents. You must use xinc:node-expand to expand such documents.

Example: 
  xquery version "1.0-ml";

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

  let $node := fn:doc("/foo/bar/baz.xml")

  return dls:node-expand(
               $node, 
               dls:as-of-query(xs:dateTime("2009-04-06T09:39:33.576-07:00")))

  (: Returns the contents of the 'baz.xml' document version that was created 
     before the specified date, along with all of its referenced nodes. :)
 © Copyright 2002-2012 MarkLogic Corporation.    All rights reserved.