| XQUERY/XSLT API DOCUMENTATION 4.2 |
All XQuery & XSLT Functions MarkLogic Built-In Functions Admin (xdmp:) AppServer (xdmp:) Classifier (cts:) Debug (dbg:) Document Conversion (xdmp:) Extension (xdmp:) Documents, Directories, Properties, and Locks Functions Extension Functions Function Values Functions HTTP Functions JSON Functions MarkLogic Server Functions Search Functions XML Functions XQuery Context Functions XSLT Functions map (map:) Math (math:) Profile (prof:) Search (cts:) cts:query Constructors Functions Geospatial Functions Geospatial Lexicon Functions Lexicon Functions Search Functions Search Clustering Functions Security (xdmp:) Server Monitoring (xdmp:) Spell (spell:) Update (xdmp:) XQuery Library Modules Admin Library (admin:) Actions Functions Appserver Functions Database Functions Forest Functions Group Functions Host Functions Mimetypes Functions Scheduler Functions Alerting (alert:) Elastic Compute Cloud (ec2:) Entity Enrichment (entity:) Flexible Replication (flexrep:) Geospatial Supporting Functions GEO Functions GeoRSS Functions GML Functions KML Functions MCGM Functions Information Studio (info:) Information Studio Developer (infodev:) Library Services (dls:) cts:query Constructor Functions Document Management Functions Document Update Functions Retention Policy Functions XInclude Functions Modular Documents XInclude Functions XPointer Functions PKI (pki:) Plugin (plugin:) Search (search:) Security-sec (sec:) Spelling Dictionary Management (spell:) Thesaurus (thsr:) Triggers (trgr:) Triggers Library (trgr:) WordProcessingML (ooxml:) ZIP Package (ooxml:) CPF Functions Content Processing Framework (cpf:) CSS Conversion (css:) DocBook Conversion (dbk:) Domains (dom:) Excel Conversion (excel:) Generic Conversion (cvt:) Links (lnk:) MSWord Conversion (msword:) PDF Conversion (pdf:) Pipelines (p:) Powerpoint Conversion (ppt:) XHTML Conversion (xhtml:) W3C-Standard Functions Accessor (fn:) AnyURI (fn:) Boolean (fn:) Context (fn:) DurationDateTime (fn:) Error and Trace (fn:) Node (fn:) Numeric (fn:) QName (fn:) Sequence (fn:) String (fn:) XSLT (fn:) 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.