| 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 Update Functions
Document Update functions.
Function Summary
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-get-permissions | This function gets the permissions for the specified document from the point of view of the Library Services API.
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-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-update | This function updates the managed document at the specified URI with the specified contents.
Function Detail
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-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-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-set-collections(
| $uri as xs:string,
| $collections as xs:string*
) as empty-sequence()
Summary: This function sets the named document to the specified collections. Any previously set collections for the document that are not specified are removed.
Parameters:
$uri : The URI of the document to be set to the collection.
$collections : A set of collection URIs.
Required Privilege: The `dls-user` role is required to run this function, or the privilege: `http://marklogic.com/xdmp/privileges/dls-user`
Example:
      xquery version "1.0-ml";

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

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

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

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

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

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

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

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

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

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

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

      (: The <priority> property is set to the 'baz.xml' document. :)
dls:document-set-quality(
| $uri as xs:string,
| $quality as xs:int
) as empty-sequence()
Summary: This function sets the quality of the document with the given URI. If the quality of the document is positive, the relevance score of the document is increased in text search functions. The converse is true for "negative" quality.
Parameters:
$uri : The URI of the document.
$quality : The quality to which to set the document.
Required Privilege: The `dls-user` role is required to run this function, or the privilege: `http://marklogic.com/xdmp/privileges/dls-user`
Example:
      xquery version "1.0-ml";

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

      dls:document-set-quality("/foo/bar/baz.xml", 10)

      (: Sets the quality of the 'baz.xml' document to 10. :)
dls:document-update(
| $uri as xs:string,
| $doc as node(),
| $annotation as item()*,
| $retain-history as xs:boolean,
| [$permissions as element(sec:permission)*],
| [$collections as xs:string*],
| [$quality as xs:integer?],
| [$forest-ids as xs:unsignedLong*]
) as xs:string*
Summary: This function updates the managed document at the specified URI with the specified contents. This function does an implicit `dls:document-purge` and returns the URI of any version of the document purged as the result of the established retention policy. This function must be called in a separate transaction from the `dls:document-checkout` and `dls:document-checkin` functions. You must first check out the document with `dls:document-checkout` before you can update, otherwise an exception is thrown. If the document does not exist, then an exception is thrown.
Parameters:
$uri : The URI of the document.
$doc : The new contents of the document.
$annotation : Any comments you want to add to the new versions of the documents.
$retain-history : Determines whether or not to retain the document's properties fragment in the database. Set to `true` to retain the original document's properties in order to track when the document was updated and by whom. Otherwise, set to `false`.
$permissions (optional): The permissions to be set on the updated document. If not supplied, then the existing permissions set for the document remain.
$collections (optional): The collection URIs for the collections to which the updated document is to belong. If not supplied, then the existing collections set for the document remain.
$quality (optional): Specifies the quality of the updated document. A positive value increases the relevance score of the document in text search functions. The converse is true for a negative value. The default value is 0.
$forest-ids (optional): Specifies the ID of the forest in which the updated document is inserted. If this parameter is not specified, the updated document will remain in the original document's forest. If no such forest exists or if no such forest is attached to the context database, an error is raised. If multiple forests are specified, the document is inserted into one of the specifed forests. If the document exists and the forest in which it is stored is set to delete-only, then you must set this parameter to include one or more forests that allow updates, otherwise an exception is thrown.
Required Privilege: The `dls-user` role is required to run this function, or the privilege: `http://marklogic.com/xdmp/privileges/dls-user`
Example:
      xquery version "1.0-ml";

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

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

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

      (: Updates the contents of 'baz.xml'. :)

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