| 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 - Document Management Functions
Document Management functions.
Function Summary
dls:break-checkout | This function breaks (unlocks) a checked-out 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-history | Returns the version history of the document located at 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-unmanage | Removes the specified document from management.
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-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.
Function Detail
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-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-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-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-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-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-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. :)

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