This page was generated
August  8,  2011
2:24  AM
XQuery Built-In and 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.

Mark Logic 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-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.

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.

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>
   
The dls-user role is required to run this function, or the privilege:
http://marklogic.com/xdmp/privileges/dls-user

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, the your 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 peroperties 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.

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, the your default permissions are applied. The default value used for this parameter can be obtained by calling xdmp:default-collections(). 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, otherwise the creation will throw an XDMP-MUSTHAVEUPDATE exception.
$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.

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. :)