| 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 - Retention Policy Functions
Retention policy functions.
Function Summary
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-retention-rules | This function returns the retention rules that apply to the document at the specified URI.
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: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-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: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.