| 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
The Library Services API module is used to place documents under library service control, and allows you to perform functions such as checking in a document, checking out a document, and so on. The Library Services API is installed as the following file: `install_dir/Modules/MarkLogic/dls.xqy` where `install_dir` is the directory in which MarkLogic Server is installed. To use the `dls.xqy` module in your own XQuery modules, include the following line in your XQuery prolog:
    	      import module namespace dls = "http://marklogic.com/xdmp/dls"
    		  at "/MarkLogic/dls.xqy";
The library uses the `dls:` namespace, which is not predefined in the server. MarkLogic recommends enabling the URI Lexicon when using Library Services; the URI lexicon will improve performance, especially when the database grows to a large number of documents.
Function Summary
dls:as-of-query | This function returns a query that matches the most recent numbered version of documents that were created before the specified date and time.
dls:author-query | This function returns a query that matches documents authored by the specified user.
dls:break-checkout | This function breaks (unlocks) a checked-out document.
dls:document-add-collections | This function adds the named document to the specified collections.
dls:document-add-permissions | This function adds the specified permissions for the named document.
dls:document-add-properties | This function adds the specified properties to any existing properties associated with the named document.
dls:document-checkin | This function checks in (unlocks) the document at the specified URI to allow other users to modify the document.
dls:document-checkout | This function checks out (locks) the document at the specified URI to prevent other users from modifying the document.
dls:document-checkout-status | This function returns a checkout element containing the checkout status of the specified document.
dls:document-checkout-update-checkin | This function allows you to checkout, update, and checkin a managed document in a single transaction.
dls:document-delete | This function removes the specified managed document.
dls:document-extract-part | This function extracts an element from an existing document and creates a new document from the extracted element.
dls:document-get-permissions | This function gets the permissions for the specified document from the point of view of the Library Services API.
dls:document-history | Returns the version history of the document located at the specified URI.
dls:document-include-query | This function returns a query that matches any managed document that has an XInclude link that exactly matches the specified URI.
dls:document-insert-and-manage | This function inserts a document into the database and places the document under management.
dls:document-is-managed | This function determines whether or not the document at the specified URI is managed.
dls:document-manage | This function places a document under management.
dls:document-purge | This function deletes all numbered versions of the specified managed document and its referenced documents, as specified by the rention policies set by dls:retention-rule.
dls:document-remove-collections | This function removes the named document from the specified collection.
dls:document-remove-permissions | This function removes the specified permissions from the named document.
dls:document-remove-properties | This function removes the specified properties from the named document.
dls:document-retention-rules | This function returns the retention rules that apply to the document at the specified URI.
dls:document-set-collections | This function sets the named document to the specified collections.
dls:document-set-permissions | This function sets the specified permissions for the named document.
dls:document-set-properties | This function sets the properties of a document to the given sequence of elements.
dls:document-set-property | This function sets a property on a document.
dls:document-set-quality | This function sets the quality of the document with the given URI.
dls:document-unmanage | Removes the specified document from management.
dls:document-update | This function updates the managed document at the specified URI with the specified contents.
dls:document-version | This function returns a particular version of a managed document.
dls:document-version-as-of | This function returns the most recent version of a document as of a point in time.
dls:document-version-delete | This function removes the specified version of the managed document at the specified URI.
dls:document-version-query | This function returns a query that matches the specified version of the managed documents.
dls:document-version-uri | This function returns the URI of the specified version of the document located at the specified URI.
dls:document-version-uris | This function returns the URIs of all versions of a managed document.
dls:document-versions-query | This function returns a query that matches any version of the specified URI.
dls:documents-query | This function returns a query that matches the latest versions of the managed documents in the database.
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.
dls:purge | This function deletes all numbered versions of managed documents and its referenced documents (such as /foo/bar.xml_versions/1-bar.xml), as specified by the rention policy set by one or more dls:retention-rule functions.
dls:retention-rule | This function creates and returns a retention rule element.
dls:retention-rule-insert | This function inserts retention rules into the database.
dls:retention-rule-remove | This function removes the specified retention rules from the database.
dls:retention-rules | This function returns the specified retention rules from the database.
Function Detail
dls:as-of-query(
| $when as xs:dateTime
) as cts:properties-query
Summary: This function returns a query that matches the most recent numbered version of documents that were created before the specified date and time.
Parameters:
$when : The date and time before which the documents were created.
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";

      cts:search(fn:doc(), dls:as-of-query(xs:dateTime(fn:current-dateTime())))

      (: Returns the versions of the managed documents that were created before the
         specified date and time. :)
dls:author-query(
| $author as xs:unsignedLong
) as cts:properties-query
Summary: This function returns a query that matches documents authored by the specified user.
Parameters:
$author : The id of the user who authored the documents.
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";

      cts:search(fn:doc(), dls:author-query(xdmp:user("Jim")))

      (: Returns all of the documents authored by 'Jim'. :)
dls:break-checkout(
| $uri as xs:string,
| $deep as xs:boolean
) as empty-sequence()
Summary: This function breaks (unlocks) a checked-out document
Parameters:
$uri : The URI of the checked out document.
$deep : If set to `true`, then the checkout is broken for any checked-out documents that are directly or indirectly included by the specified document.
Required Privilege: The `dls-admin` role is required to run this function, or the privilege: `http://marklogic.com/xdmp/privileges/dls-admin`
Example:
      xquery version "1.0-ml";

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

      dls:break-checkout("/foo/bar/baz.xml", fn:true())

      (: This breaks the checkout of the 'baz.xml' document. :)
dls:document-add-collections(
| $uri as xs:string,
| $collections as xs:string*
) as empty-sequence()
Summary: This function adds the named document to the specified collections.
Parameters:
$uri : The URI of the document to be added to the collection.
$collections : A set of collection URIs.
Required Privilege: The `dls-user` role is required to run this function, or the privilege: `http://marklogic.com/xdmp/privileges/dls-user` For each collection that is protected, the user must have permissions to update that collection or the privilege: `http://marklogic.com/xdmp/privileges/any-collection` For each unprotected collection, the user must have the privilege: `http://marklogic.com/xdmp/privileges/unprotected-collections` The document must specify `dls-user(update)` permission.
Example:
      xquery version "1.0-ml";

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

      dls:document-add-collections(
            "/foo/bar/baz.xml",
            "http://marklogic.com/documents/foo")

      (: Adds 'bax.xml' to the 'foo' collection. :)
dls:document-add-permissions(
| $uri as xs:string,
| $permissions as element(sec:permission)*
) as empty-sequence()
Summary: This function adds the specified permissions for the named document. Any permissions that were previously set for the document are retained.
Parameters:
$uri : The URI of the document.
$permissions : The permissions to be added for the document.
Required Privilege: The `dls-user` role is required to run this function, or the privilege: `http://marklogic.com/xdmp/privileges/dls-user` The document must specify `dls-user(update)` permission.
Example:
      xquery version "1.0-ml";

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

      dls:document-add-permissions("/foo/bar/baz.xml",
                                   (xdmp:permission("dls-user", "read"),
                                    xdmp:permission("dls-user", "update")))

      (: Adds the specified permissions to the list of permissions for the 'baz.xml'
         document. :)
dls:document-add-properties(
| $uri as xs:string,
| $properties as element()*
) as empty-sequence()
Summary: This function adds the specified properties to any existing properties associated with the named document.
Parameters:
$uri : The URI of the document.
$properties : The properties to add.
Required Privilege: The `dls-user` role is required to run this function, or the privilege: `http://marklogic.com/xdmp/privileges/dls-user`
Usage Notes: You cannot add any property nodes to the DLS namespace.
Example:
      xquery version "1.0-ml";

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

      dls:document-add-properties(
                  "/foo/bar/baz.xml",
                  (<priority>1</priority>,
                   <status>unedited</status>))

      (: The <priority> and <status> properties are added to the 'baz.xml' document. :)
dls:document-checkin(
| $uri as xs:string,
| $deep as xs:boolean
) as empty-sequence()
Summary: This function checks in (unlocks) the document at the specified URI to allow other users to modify the document. This function does not create a new version of the document. You must explicitly use `dls:document-update` to create new versions of a document. This function must be called in a separate transaction from the `dls:document-checkout` and `dls:document-update` functions.
Parameters:
$uri : The URI of the document.
$deep : If set to `true`, then any documents directly or indirectly included by the specified document are also checked in.
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-checkin("/foo/bar/baz.xml", fn:true())

      (: Checks in 'baz.xml' and all of its included documents. :)
dls:document-checkout(
| $uri as xs:string,
| $deep as xs:boolean,
| [$annotation as item()?],
| [$timeout as xs:unsignedLong?]
) as empty-sequence()
Summary: This function checks out (locks) the document at the specified URI to prevent other users from modifying the document. An exception is thrown if the document does not yet exist or does exist but is not managed. This function must be called in a separate transaction from the `dls:document-update` and `dls:document-checkin` functions.
Parameters:
$uri : The URI of the document to check out.
$deep : If set to `true`, then any documents directly or indirectly included by the specified document are also checked out.
$annotation (optional): Any comments you want to add to the document's `active-lock` element.
$timeout (optional): The duration of the checkout, in seconds. For infinite, omit this parameter or specify ().
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-checkout("/foo/bar/baz.xml", fn:true(), "updating doc", 3600)

      (: Checks out the 'baz'xml' document, and all of its included documents,
         for one hour. :)
dls:document-checkout-status(
| $uri as xs:string
) as element(dls:checkout)?
Summary: This function returns a `checkout` element containing the checkout status of the specified document.
Parameters:
$uri : The URI of the document.
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-checkout-status("/foo/bar/baz.xml")

      =>

      <dls:checkout xmlns:dls="http://marklogic.com/xdmp/dls">
        <dls:document-uri>/foo/bar/baz.xml</dls:document-uri>
        <dls:annotation>updating doc</dls:annotation>
        <dls:timeout>3600</dls:timeout>
        <dls:timestamp>1239057381</dls:timestamp>
        <sec:user-id xmlns:sec="http://marklogic.com/xdmp/security">10677693687367813363</sec:user-id>
      </dls:checkout>
dls:document-checkout-update-checkin(
| $uri as xs:string,
| $doc as node(),
| $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 allows you to checkout, update, and checkin a managed document in a single transaction.
Parameters:
$uri : The URI of the document to be updated.
$doc : The new contents of the document.
$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 updated document. 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 updated by a non-admin user (that is, by any user who does not have the admin role) must have at least one update permission.
$collections (optional): The collection URIs for the collections to which the updated document is to belong. If not supplied, the document maintains its current 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 updated 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.
$forest-ids (optional): Specifies the ID of the forest in which the updated document is inserted. If this parameter is not specified, the updated document will remain in the original document's 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.
Example:
      xquery version "1.0-ml";

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

      let $bazbook :=
      <BOOK>
        <TITLE>Baz Goes to the Disco</TITLE>
        <CHAPTER1>
          <TITLE>Baz Wakes Up</TITLE>
          <PARA>
            Baz woke up this afternoon to the sound of James Brown.  Soon
            Baz was feeling a little funky, so he put on his cleanest
            propeller hat and headed out in search of a Disco.
          </PARA>
        </CHAPTER1>
      </BOOK>

      return
        dls:document-checkout-update-checkin(
    	"/foo/bar/baz.xml",
    	$bazbook,
    	"Changed the title from Baz Feelin' Funky",
    	fn:true())

      (: Checks out 'baz.xml', updates the content, and checks it back in. :)
dls:document-delete(
| $uri as xs:string,
| $keep-old-versions as xs:boolean,
| $retain-history as xs:boolean
) as empty-sequence()
Summary: This function removes the specified managed document. You must have update permissions on the document to delete it. If you set `$retain-history` to `true`, you can use `xdmp:document-properties` to view the deleted document's properties fragment in the database.
Parameters:
$uri : The URI of the document.
$keep-old-versions : Determines whether to keep old versions of the document. Set to `false` to delete all of the versions of the document.
$retain-history : Determines whether to retain the deleted document's property fragment in the database. Set to `true` to retain the property fragment, or `false` to delete.
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-delete("/foo/bar/baz.xml", fn:false(), fn:true())

      (: Deletes all versions of the 'baz.xml' document and retains the
         property fragment for each version. :)
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:document-get-permissions(
| $uri as xs:string
) as element(sec:permission)*
Summary: This function gets the permissions for the specified document from the point of view of the Library Services API.
Parameters:
$uri : The URI of the document.
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-get-permissions("/foo/bar/baz.xml")

      (: Returns the permissions for the 'baz.xml' document. :)
dls:document-history(
| $uri as xs:string
) as element(dls:document-history)
Summary: Returns the version history of the document located at the specified URI.
Parameters:
$uri : The URI of the document.
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-history("/foo/bar/baz.xml")

       =>

       <dls:document-history uri="/foo/bar/baz.xml" xmlns:dls="http://marklogic.com/xdmp/dls">
       <dls:version>
        <dls:version-id>1</dls:version-id>
        <dls:document-uri>/foo/bar/baz.xml</dls:document-uri>
        <dls:latest>false</dls:latest>
        <dls:created>2009-04-07T13:54:26.721-07:00</dls:created>
        <dls:replaced>2009-04-14T13:52:21.674-07:00</dls:replaced>
        <dls:author>10677693687367813363</dls:author>
        <dls:annotation>part insert</dls:annotation>
        <dls:deleted>false</dls:deleted>
      </dls:version><dls:version>
        <dls:version-id>2</dls:version-id>
        <dls:document-uri>/foo/bar/baz.xml</dls:document-uri>
        <dls:latest>true</dls:latest>
        <dls:created>2009-04-14T13:52:21.674-07:00</dls:created>
        <dls:author>10677693687367813363</dls:author>
        <dls:annotation>Changed the title from Baz Gets Down</dls:annotation>
        <dls:deleted>false</dls:deleted>
      </dls:version>
      </dls:document-history>
dls:document-include-query(
| $uri as xs:string
) as cts:query
Summary: This function returns a query that matches any managed document that has an XInclude link that exactly matches the specified URI.
Parameters:
$uri : The URI of the linked-to document.
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";

      cts:search(fn:doc(), dls:document-include-query("/foo.xml"))

      (: Returns the contents of the documents that contain an XInclude to the
         '/foo.xml' document. :)
dls:document-insert-and-manage(
| $uri as xs:string,
| $deep as xs:boolean,
| $doc as node(),
| [$annotation as item()*],
| [$permissions as element(sec:permission)*],
| [$collections as xs:string*],
| [$quality as xs:integer?],
| [$forest-ids as xs:unsignedLong*]
) as xs:string*
Summary: This function inserts a document into the database and places the document under management.
Parameters:
$uri : The URI of the document.
$deep : Specifies whether to manage this document as well as any documents for which this document has XInclude references to. Specify `true` to manage all XInclude references or `false` to not manage any included documents. The default is `false`.
$doc : The contents of the document (root node). The document root node can be one of XML format, binary (BLOB) format, or text (CLOB) format.
$annotation (optional): Any comments you want to add to the properties.
$permissions (optional): Security permission elements corresponding to the 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 `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 (optional): 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 `xdmp:default-collections`.
$quality (optional): 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.
$forest-ids (optional): Specifies the ID of the forest in which this document is inserted. If the document already exists in the database and if $forest-ids 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 $forest-ids to include one or more forests that allow updates, otherwise an exception is thrown.
Example:
      xquery version "1.0-ml";

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

      let $contents :=
        <BOOK>
          <TITLE>Baz Goes to the Disco</TITLE>
          <CHAPTER1>
             <TITLE>Baz Wakes Up to James Brown and Feels Funky</TITLE>
          </CHAPTER1>
        </BOOK>

       return
          dls:document-insert-and-manage(
             "/foo/bar/baz.xml",
             fn:true(),
             $contents)

       (: Inserts 'baz.xml' into the database and places the document under management. :)
dls:document-is-managed(
| $uri as xs:string
) as xs:boolean
Summary: This function determines whether or not the document at the specified URI is managed. This function returns `true` if the document at the URI is either a managed document or a numbered version of a managed document. Otherwise `false` is returned.
Parameters:
$uri : The URI of the document to test.
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-is-managed("/foo/bar/baz.xml")

      (: Returns true if document is managed.  Otherwise false. :)
dls:document-manage(
| $uri as xs:string,
| $deep as xs:boolean,
| [$annotation as item()*]
) as empty-sequence()
Summary: This function places a document under management. A document must first be managed before it can be checked out. The document at the specified URI will become version 1 of this managed document.
Parameters:
$uri : The URI of the document.
$deep : Specifies whether to manage this document as well as any documents for which this document has XInclude references to. Specify `true` to manage all XInclude references or `false` to not manage any included documents. The default is `false`.
$annotation (optional): Any comments you want to add to the properties.
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-manage("/foo/bar/baz.xml",
                          fn:false(),
                          "Baz is now a managed document")

      (: Makes 'baz.xml' a managed document, but not its referenced documents. :)
dls:document-purge(
| $uri as xs:string,
| $delete as xs:boolean,
| $retain-history as xs:boolean
) as xs:string*
Summary: This function deletes all numbered versions of the specified managed document and its referenced documents, as specified by the rention policies set by `dls:retention-rule`. The document versions are deleted if they have no retention rule causing them to be kept and if they are not included by documents that cannot yet be deleted. If `$delete` is `false`, the document's versions are not actually deleted and instead a list of the documents that would have been deleted is returned. If you set `$retain-history` to `true`, you can use `xdmp:document-properties` to view the deleted document's properties fragment in the database.
Parameters:
$uri : The URI of the document to be purged.
$delete : Determines whether or not to delete the documents. Set to `true` to remove the documents or `false` to list which documents would have been deleted.
$retain-history : Determines whether to retain the deleted document's property fragment in the database. Set to `true` to retain the property fragment, or `false` to delete.
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-purge("/foo/bar/baz.xml", fn:false(), fn:true())

      (: Returns the versions of the 'baz.xml' document and its referenced
         documents, as specified by the rention policy. :)
dls:document-remove-collections(
| $uri as xs:string,
| $collections as xs:string*
) as empty-sequence()
Summary: This function removes the named document from the specified collection.
Parameters:
$uri : The URI of the document.
$collections : The collection from which to remove the document.
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-remove-collections(
            "/foo/bar/baz.xml",
            "http://marklogic.com/documents/foo")

      (: Removes 'bax.xml' from the 'foo' collection. :)
dls:document-remove-permissions(
| $uri as xs:string,
| $permissions as element(sec:permission)*
) as empty-sequence()
Summary: This function removes the specified permissions from the named document.
Parameters:
$uri : The URI of the document.
$permissions : The permissions to be removed from the document.
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-remove-permissions(
                       "/foo/bar/baz.xml",
                       (xdmp:permission("Developer", "read"),
                        xdmp:permission("Developer", "update")))

      (: Removes the specified permissions from the list of permissions for
         the 'baz.xml' document. :)
dls:document-remove-properties(
| $uri as xs:string,
| $property-names as xs:QName*
) as empty-sequence()
Summary: This function removes the specified properties from the named document
Parameters:
$uri : The URI of the document.
$property-names : The properties to be removed.
Required Privilege: The `dls-user` role is required to run this function, or the privilege: `http://marklogic.com/xdmp/privileges/dls-user`
Usage Notes: You cannot remove any property nodes from the DLS namespace.
Example:
      xquery version "1.0-ml";

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

      dls:document-remove-properties(
             "/foo/bar/baz.xml",
             (fn:QName("http://marklogic.com/xdmp/property", "priority"),
              fn:QName("http://marklogic.com/xdmp/property", "status")))

      (: The <priority> and <status> properties are removed from the
         'baz.xml' document. :)
dls:document-retention-rules(
| $uri as xs:string
) as element(dls:retention-rule)*
Summary: This function returns the retention rules that apply to the document at the specified URI. This allows users to determine why a version of a document is being retained.
Parameters:
$uri : The URI of the document. The URI must identify a numbered version of a managed document or an error 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-retention-rules("/foo/bar/baz.xml")

      (: Returns all of the retention rules that apply to the 'baz.xml' document. :)
dls:document-set-collections(
| $uri as xs:string,
| $collections as xs:string*
) as empty-sequence()
Summary: This function sets the named document to the specified collections. Any previously set collections for the document that are not specified are removed.
Parameters:
$uri : The URI of the document to be set to the collection.
$collections : A set of collection URIs.
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-set-collections(
              "/foo/bar/baz.xml",
              "http://marklogic.com/documents/foo")

      (: Sets 'bax.xml' to the 'foo' collection. :)
dls:document-set-permissions(
| $uri as xs:string,
| $permissions as element(sec:permission)*
) as empty-sequence()
Summary: This function sets the specified permissions for the named document. Any unspecified permissions that were previously set for the document are removed.
Parameters:
$uri : The URI of the document.
$permissions : The permissions to be set for the document.
Required Privilege: The `dls-user` role is required to run this function, or the privilege: `http://marklogic.com/xdmp/privileges/dls-user` The document must specify `dls-user(update)` permission.
Example:
      xquery version "1.0-ml";

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

      dls:document-set-permissions("/foo/bar/baz.xml",
                                   (xdmp:permission("dls-user", "read"),
                                    xdmp:permission("dls-user", "update"),
                                    xdmp:permission("Developer", "read"),
                                    xdmp:permission("Developer", "update")))

      (: Sets the permissions on the 'baz.xml' document. :)
dls:document-set-properties(
| $uri as xs:string,
| $properties as element()*
) as empty-sequence()
Summary: This function sets the properties of a document to the given sequence of elements. With the exception of the Library Services properties, any properties that already exist on the document are replaced. To preserve existing document properties, use `dls:document-add-properties`. Each element QName is the property name and the element value is the property value.
Parameters:
$uri : The URI of the document.
$properties : The properties to be set for the document.
Required Privilege: The `dls-user` role is required to run this function, or the privilege: `http://marklogic.com/xdmp/privileges/dls-user` Modifying properties requires update permissions on a document.
Usage Notes: You cannot set any property nodes in the DLS namespace.
Example:
      xquery version "1.0-ml";

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

      dls:document-set-properties(
                  "/foo/bar/baz.xml",
                  (<priority>1</priority>,
                   <status>unedited</status>))

      (: The <priority> and <status> properties are set to the 'baz.xml' document. :)
dls:document-set-property(
| $uri as xs:string,
| $property as element()
) as empty-sequence()
Summary: This function sets a property on a document. If any properties with the same property QName exist, they are replaced with the new property. If no properties exist with the same QName, the new property is added.
Parameters:
$uri : The URI of the document.
$property : The property to set.
Required Privilege: The `dls-user` role is required to run this function, or the privilege: `http://marklogic.com/xdmp/privileges/dls-user`
Usage Notes: You cannot set any property nodes in the DLS namespace.
Example:
      xquery version "1.0-ml";

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

      dls:document-set-property(
                  "/foo/bar/baz.xml",
                  <priority>1</priority>)

      (: The <priority> property is set to the 'baz.xml' document. :)
dls:document-set-quality(
| $uri as xs:string,
| $quality as xs:int
) as empty-sequence()
Summary: This function sets the quality of the document with the given URI. If the quality of the document is positive, the relevance score of the document is increased in text search functions. The converse is true for "negative" quality.
Parameters:
$uri : The URI of the document.
$quality : The quality to which to set the document.
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-set-quality("/foo/bar/baz.xml", 10)

      (: Sets the quality of the 'baz.xml' document to 10. :)
dls:document-unmanage(
| $uri as xs:string,
| $deep as xs:boolean,
| $remove-versions as xs:boolean
) as empty-sequence()
Summary: Removes the specified document from management. You must have update permissions on the document to unmanage the document.
Parameters:
$uri : The URI of the document.
$deep : Specifies whether to unmanage this document as well as any documents for which this document has XInculde references to. Specify `true` to unmanage all XInclude references or `false` to leave any included documents as managed documents. The default is `false`.
$remove-versions : Specify `true` to delete all but the latest version during the unmanage operation, `false` to leave any older versions in the database as unmanaged documents.
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-unmanage("/foo/bar/baz.xml", fn:false(), fn:true())

      (: Unmanages 'baz.xml', but maintains management of its referenced
         documents. All versions but the latest version of this document
         are deleted. :)
dls:document-update(
| $uri as xs:string,
| $doc as node(),
| $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 updates the managed document at the specified URI with the specified contents. This function does an implicit `dls:document-purge` and returns the URI of any version of the document purged as the result of the established retention policy. This function must be called in a separate transaction from the `dls:document-checkout` and `dls:document-checkin` functions. You must first check out the document with `dls:document-checkout` before you can update, otherwise an exception is thrown. If the document does not exist, then an exception is thrown.
Parameters:
$uri : The URI of the document.
$doc : The new contents of the document.
$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 updated document. If not supplied, then the existing permissions set for the document remain.
$collections (optional): The collection URIs for the collections to which the updated document is to belong. If not supplied, then the existing collections set for the document remain.
$quality (optional): Specifies the quality of the updated 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.
$forest-ids (optional): Specifies the ID of the forest in which the updated document is inserted. If this parameter is not specified, the updated document will remain in the original document's 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";

      let $bazbook :=
      <BOOK>
        <TITLE>Baz Goes to the Disco</TITLE>
        <CHAPTER1>
          <TITLE>Baz Wakes Up</TITLE>
          <PARA>
            Baz woke up this afternoon to the sound of James Brown.  Soon
            Baz was feeling a little funky, so he put on his cleanest
            propeller hat and headed out in search of a Disco.
          </PARA>
        </CHAPTER1>
      </BOOK>

      return
        dls:document-update(
    	"/foo/bar/baz.xml",
    	$bazbook,
    	"Changed the title from Baz Feelin' Funky",
    	fn:true())

      (: Updates the contents of 'baz.xml'. :)
dls:document-version(
| $uri as xs:string,
| $version-number as xs:unsignedInt
) as document-node()
Summary: This function returns a particular version of a managed document. An error is thrown if there is no such version.
Parameters:
$uri : The URI of the document.
$version-number : The version of the document to be returned.
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-update(
               "/foo/bar/baz.xml",
                dls:document-version( "/foo/bar/baz.xml", 1),
                "restoring from version 1",
                fn:true() )

      (: Restores version 1 of the 'baz.xml' document. :)
dls:document-version-as-of(
| $uri as xs:string,
| $as-of as xs:dateTime
) as document-node()
Summary: This function returns the most recent version of a document as of a point in time.
Parameters:
$uri : The URI of the document.
$as-of : The date and time from which you want to retrieve the most recent version of the document.
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-version-as-of(
                       "/foo/bar/baz.xml",
                        xs:dateTime("2009-04-07T09:43:16.531-07:00"))

      (: Returns the most recent version of the 'baz.xml' document since the
         specified date and time. :)
dls:document-version-delete(
| $uri as xs:string,
| $version as xs:integer,
| $retain-history as xs:boolean
) as empty-sequence()
Summary: This function removes the specified version of the managed document at the specified URI. This overrides any configured retention policies and should be used with care. You must have update permissions on the document version in order to delete it. If you set `$retain-history` to `true`, you can use `xdmp:document-properties` to view the deleted document's properties fragment in the database. For example, if you had deleted version 1 of `/foo/bar/baz.xml`, you can view its properties by calling: `xdmp:document-properties("/foo/bar/baz.xml_versions/1-baz.xml")`
Parameters:
$uri : The URI of the document.
$version : The version of the document to be deleted.
$retain-history : Determines whether or not to retain the document's properties fragment in the database. Set to `true` to retain the deleted document's properties in order to track when the document was deleted and by whom. Otherwise, set to `false`.
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-version-delete("/foo/bar/baz.xml", 1, fn:true())

      (: Deletes version 1 of the 'baz.xml' document and records it in the document
         history. :)
dls:document-version-query(
| $version as xs:unsignedLong
) as cts:properties-query
Summary: This function returns a query that matches the specified version of the managed documents.
Parameters:
$version : The version of the managed documents.
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";

      cts:search(fn:doc(), dls:document-version-query(3))

      (: Returns Version 3 of all of the managed documents in the database. :)
dls:document-version-uri(
| $document-uri as xs:string,
| $version as xs:integer
) as xs:string
Summary: This function returns the URI of the specified version of the document located at the specified URI. The specified version of the document may, or may not, actually exist.
Parameters:
$document-uri : The URI of the latest version of the document.
$version : The version of the document for which to return the URI.
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-version-uri("/foo/bar/baz.xml", 2)

      =>

      /foo/bar/baz.xml_versions/2-baz.xml
dls:document-version-uris(
| $uri as xs:string
) as xs:string*
Summary: This function returns the URIs of all versions of a managed document. No URIs of deleted versions are returned.
Parameters:
$uri : The URI of the document.
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-version-uris("/foo/bar/baz.xml")

      (: Returns the URIs of all versions of the '/foo/bar/baz.xml' document. :)
dls:document-versions-query(
| $uri as xs:string
) as cts:properties-query
Summary: This function returns a query that matches any version of the specified URI. If the URI contains either of the wildcard characters '?' or '*', then the search is wildcarded. Specifying '*' matches any numbered version of any managed document.
Parameters:
$uri : The URI of the document.
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";

      cts:search(fn:doc(), dls:document-versions-query("/foo/bar/baz.xml"))

      (: Returns the contents of all versions of the 'baz.xml' document. :)
dls:documents-query( ) as cts:properties-query
Summary: This function returns a query that matches the latest versions of the managed documents in the database.
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";

      cts:search(fn:doc(), dls:documents-query())

      (: Returns the latest versions of the managed documents in the database. :)
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. :)
dls:purge(
| $delete as xs:boolean,
| $retain-history as xs:boolean
) as xs:string*
Summary: This function deletes all numbered versions of managed documents and its referenced documents (such as `/foo/bar.xml_versions/1-bar.xml`), as specified by the rention policy set by one or more `dls:retention-rule` functions. Documents are deleted if they have no retention rule causing them to be kept and if they are not included by some document that cannot yet be deleted. If `$delete` is `false`, the document versions are not actually deleted and instead a list of the documents that would have been deleted is returned. This function returns a list of URIs that it would/did delete. If you set `$retain-history` to `true`, you can use `xdmp:document-properties` to view the deleted document's properties fragment in the database.
Parameters:
$delete : Determines whether or not to delete the documents. Set to `true` to delete the documents or `false` to list which documents would have been deleted.
$retain-history : Determines whether to retain the deleted documents' property fragments in the database. Set to `true` to retain the property fragments, or `false` to delete.
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-purge(fn:true(), fn:true())

      (: Deletes all of the versions of the 'baz.xml' document and its
         referenced documents. :)
dls:retention-rule(
| $name as xs:string,
| $comment as item()*,
| $num-versions as xs:unsignedInt?,
| $duration as xs:duration?,
| $document-query-text as xs:string?,
| $document-query as cts:query?
) as element(dls:retention-rule)
Summary: This function creates and returns a retention rule element. Use `dls:insert-retention-rule` to insert the retention rule into the database. Specifying multiple constraints implies AND between them. For example, specifying both `$num-versions` and `$duration` retains a numbered version only if it is both one of the N most recent versions and it was created more recently than "now - duration." If neither `$num-versions` or `$duration` is specified, then any numbered version matching the document query is kept forever. The `$document-query-text` parameter is intended to be used for the human readable form of a query that was used to produce the corresponding `cts:query`. This may be the text that a user typed into a search text field in the UI. This parameter does NOT affect the retention policy.
Parameters:
$name : The name of the retention rule. The name must be unique to this rule.
$comment : Comment that describes this retention rule.
$num-versions : The number of most recent versions to be retained. This means to keep versions greater than (but not equal to) num-versions - current-version, if they still exist.
$duration : Retain all versions that were created on or after the duration date/time.
$document-query-text : Comment that describes the document query.
$document-query : The document query. Typically returned by a Query Constructor Function.
Required Privilege: The `dls-admin` role is required to run this function, or the privilege: `http://marklogic.com/xdmp/privileges/dls-admin`
Example:
      xquery version "1.0-ml";
      import module namespace dls="http://marklogic.com/xdmp/dls"
                  at "/MarkLogic/dls.xqy";

      dls:retention-rule(
          "All Versions Retention Rule",
          "Retain all versions of all documents",
          (),
          (),
          "Locate all of the documents",
          cts:and-query(()))

      (: Returns a retention rule in XML format. :)
Example:
      xquery version "1.0-ml";

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

      dls:retention-rule(
          "Rule1",
          "Keep the five most recent versions of Jim's documents that are
             15 days old or newer",
          5,
          xs:duration("P15D"),
          "Locate documents authored by Jim",
          dls:author-query(xdmp:user("Jim")))

      (: Returns a retention rule in XML format. :)
Example:
      xquery version "1.0-ml";

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

      dls:retention-rule(
          "Rule2",
          "Keep the five most recent versions of Jim's documents in the 'foo'
             collection that are 15 days old or newer",
          5,
          xs:duration("P15D"),
          "Locate documents in the 'foo' collection authored by Jim",
           cts:and-query((
              cts:collection-query("http://marklogic.com/documents/foo"),
              dls:author-query(xdmp:user("Jim")) )) )

      (: Returns a retention rule in XML format. :)
dls:retention-rule-insert(
| $rules as element(dls:retention-rule)*
) as empty-sequence()
Summary: This function inserts retention rules into the database. They will be readable by the dls-user role and modifiable/deletable by the dls-admin role.
Parameters:
$rules : The retention rule to be inserted.
Required Privilege: The `dls-admin` role is required to run this function, or the privilege: `http://marklogic.com/xdmp/privileges/dls-admin`
Example:
      xquery version "1.0-ml";

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

      dls:retention-rule-insert((
        dls:retention-rule(
          "Rule1",
          "Keep the five most recent versions of Jim's documents that are 15 days old or newer",
          5,
          xs:duration("P15D"),
          "Locate all documents authored by Jim",
          dls:author-query(xdmp:user("Jim"))),

       dls:retention-rule(
         "Rule2",
         "Retain the five most recent versions of documents that match the query below",
          5,
          (),
          "Locate only docs that include 'Baz' and 'Disco'" ,
          cts:and-query((
            cts:word-query("Baz"),
            cts:word-query("Disco"))) ) ))

      (: Inserts the retention rules, 'Rule1' and 'Rule2', into the database. :)
dls:retention-rule-remove(
| $names as xs:string*
) as empty-sequence()
Summary: This function removes the specified retention rules from the database.
Parameters:
$names : The names of the retention rules to be removed.
Required Privilege: The `dls-admin` role is required to run this function, or the privilege: `http://marklogic.com/xdmp/privileges/dls-admin`
Example:
      xquery version "1.0-ml";

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

      dls:retention-rule-remove(("Rule1", "Rule2"))

      (: Removes the retention rules, 'Rule1' and 'Rule2'. :)
Example:
      xquery version "1.0-ml";

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

      dls:retention-rule-remove(fn:data(dls:retention-rules("*")//dls:name))

      (: Removes all of the retention rules. :)
dls:retention-rules(
| $names as xs:string*
) as element(dls:retention-rule)*
Summary: This function returns the specified retention rules from the database.
Parameters:
$names : The names of the retention rules to be returned. The name can include wild cards. For example, a `*` can be used to retrieve all of the retention rules.
Required Privilege: The `dls-user` role is required to run this function, or the privilege: `http://marklogic.com/xdmp/privileges/dls-user` You must have `read` permissions on the rentention-rule document to see the rules.
Example:
      xquery version "1.0-ml";

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

      dls:retention-rules("Rule1")

      (: Returns the 'Rule1' retention rule in XML format. :)

© Copyright 2002-2012 MarkLogic Corporation. All rights reserved.