| 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:00 AM | XQuery & XSLT Built-In & Modules Function Reference
Built-In: Update
The update built-in functions are XQuery functions to perform update-related tasks such as loading documents, inserting nodes into documents, and so on.
Function Summary
xdmp:collection-delete | Deletes from the database every document in a collection.
xdmp:directory-create | Creates a directory.
xdmp:directory-delete | Deletes a directory and all of its child and descendant documents and directories from the database.
xdmp:document-add-collections | Adds the named document to the given collections.
xdmp:document-add-permissions | Adds the given permissions to the given document or directory.
xdmp:document-add-properties | Adds a sequence of properties to the properties of a document.
xdmp:document-assign | Assign a document URI to a forest index, using the same algorithm as xdmp:document-insert.
xdmp:document-delete | Deletes a document from the database.
xdmp:document-insert | Inserts a new document into the database if a document with the specified URI does not already exist.
xdmp:document-load | Inserts a new document with the specified URI.
xdmp:document-remove-collections | Removes the named document from the given collections.
xdmp:document-remove-permissions | Removes the given permissions from the named document or directory.
xdmp:document-remove-properties | Removes a sequence of properties from the properties of a document.
xdmp:document-set-collections | Sets the named document to belong to the given collections, replacing any previously set collections on the named document.
xdmp:document-set-permissions | Sets the permissions on the named document (or directory) to the given permissions, replacing any permissions previously set on the document (or directory).
xdmp:document-set-properties | Sets the properties of a document to the given sequence of elements, replacing any properties that already exist on the document.
xdmp:document-set-property | Sets a property on a document.
xdmp:document-set-quality | Sets the quality of the document with the given URI.
xdmp:load | [DEPRECATED: use xdmp:document-load instead] Inserts a new document from the XML file at $path if a document with the specified URI does not already exist.
xdmp:lock-acquire | Acquire a lock on a document or directory for an extended amount of time.
xdmp:lock-for-update | Acquires an intent exclusive lock on a URI.
xdmp:lock-release | Unlock a document or directory.
xdmp:merge | Starts merging the forests of the database, subject to specified options.
xdmp:merging | Returns the forest IDs of any currently merging database forests.
xdmp:node-delete | Deletes a node from the database.
xdmp:node-insert-after | Adds an immediately following sibling to a node.
xdmp:node-insert-before | Adds an immediately preceding sibling to a node.
xdmp:node-insert-child | Adds a new last child to a node.
xdmp:node-replace | Replaces a node.
xdmp:save | Serializes a node as text and saves it to a file.
Function Detail
xdmp:collection-delete(
| $uri as xs:string
) as empty-sequence()
Summary: Deletes from the database every document in a collection. If there are no documents in the specified collection, then nothing is deleted, and `xdmp:collection-delete` still returns the empty sequence.
Parameters:
$uri : The URI of the collection to be deleted.
Example:
      xdmp:collection-delete("collection-uri")
xdmp:directory-create(
| $uri as xs:string,
| [$permissions as element(sec:permission)*],
| [$collections as xs:string*],
| [$quality as xs:int?],
| [$forest-ids as xs:unsignedLong*]
) as empty-sequence()
Summary: Creates a directory. If security is enabled, the document permissions and collections are set to the given parameters, if supplied. Otherwise, the current user's default permissions and/or collections are applied. If the beginning of the the document URI is protected, the user must have access to that URI privilege. If the directory URI does not end with a '/' one is added. If the directory already exists, then an XDMP-DIREXISTS exception is thrown.
Parameters:
$uri : The URI of the directory to be inserted.
$permissions (optional): Security permission elements corresponding to the permissions for the document.
$collections (optional): The collections to which the new directory belongs.
$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 directory is created. If the directory 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 directory is created in one of the specifed forests.
Example:
    xdmp:directory-create("http://marklogic.com/a/",
                (xdmp:permission("development", "update"),
                 xdmp:permission("qa", "read")),
                 "http://marklogic.com/directories")

    => Creates a directory named "http://marklogic.com/a/",
       which has the parent directory "http://marklogic.com/".
       The directory is created with the specified permissions,
       and is added to the "http://marklogic.com/directories"
       collection.
Example:
    xdmp:directory-create("/dir/myDirectory/")

    => Creates a directory named "/dir/myDirectory/",
       which has the parent directory "/dir/", which
       in turn has parent directory "/". If
       directory creation is set to automatic in
       the database configuration, this example creates
       all three directories ("/", "/dir/", and
        "/dir/myDirectory/").
xdmp:directory-delete(
| $uri as xs:string
) as empty-sequence()
Summary: Deletes a directory and all of its child and descendant documents and directories from the database.
Parameters:
$uri : The URI of the directory to be deleted.
Usage Notes: If you delete a directory, the directory and all of its children and descendants (recursively) are deleted, including all child documents and directories. A child document or directory of a given directory is one whose URI begins with the same string as the directory URI.
Example:
      xdmp:directory-delete("http://example.com/")
xdmp:document-add-collections(
| $uri as xs:string,
| $collections as xs:string*
) as empty-sequence()
Summary: Adds the named document to the given 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.
Parameters:
$uri : The document URI.
$collections : A set of collection URIs.
Required Privilege: If adding an unprotected collection to a document, the `unprotected-collections` privilege (`http://marklogic.com/xdmp/privileges/unprotected-collections`) is needed; if adding a protected collection, the user must have either permissions to update the collection or the `any-collection` privilege (`http://marklogic.com/xdmp/privileges/any-collection`).
Example:
      xdmp:document-add-collections(
        "/example.xml",
        ("http://examples.com", "http://marklogic.com"))
xdmp:document-add-permissions(
| $uri as xs:string,
| $permissions as element(sec:permission)*
) as empty-sequence()
Summary: Adds the given permissions to the given document or directory. The user must have update or insert permissions on the document.
Parameters:
$uri : The document URI.
$permissions : Permission elements.
Example:
      xdmp:document-add-permissions(
        "/example.xml",
        (xdmp:permission("development", "update"),
         xdmp:permission("qa", "read")))
xdmp:document-add-properties(
| $uri as xs:string,
| $props as element()*
) as empty-sequence()
Summary: Adds a sequence of properties to the properties of a document.
Parameters:
$uri : The URI of the document.
$props : The properties to add.
Example:
      xdmp:document-add-properties(
             "example.xml",
             (<priority>1</priority>,
              <status>unedited</status>))
      => ()
xdmp:document-assign(
| $uri as xs:string,
| $forest-count as xs:positiveInteger
) as xs:positiveInteger
Summary: Assign a document URI to a forest index, using the same algorithm as `xdmp:document-insert`. The return value will be a positive integer from 1 to `$forest-count`. This function does not insert or update the document; instead, it returns the index of the forest to which the document URI would be assigned if it were inserted as a new document. In order to match the document to the correct forest, use the list of forest-IDs as returned by `xdmp:database-forests`. If the document already exists, this function may not return the correct forest for the document. In this case, `xdmp:document-forest` will return the correct forest.
Parameters:
$uri : The document URI to assign.
$forest-count : Specifies the number of forests from which this document may be assigned.
Example:
      xdmp:document-assign("document-1.xml", 2)
       => 1
Example:
      xdmp:document-assign("document-2.xml", 2)
       => 2
Example:
      let $forests := xdmp:database-forests(xdmp:database())
      let $index := xdmp:document-assign("document-1.xml", count($forests))
      return $forests[$index]
       => 17618760155059123769
xdmp:document-delete(
| $uri as xs:string
) as empty-sequence()
Summary: Deletes a document from the database.
Parameters:
$uri : The URI of the document to be deleted.
Usage Notes: The `xdmp:document-delete` function deletes a document and all of its properties, except the directory property; it does not delete a directory with the same URI as the document being deleted. To delete a directory, use the `xdmp:directory-delete` function. If a document does not exist at the specified URI, `xdmp:document-delete` returns an error.
Example:
    xdmp:document-delete("example.xml")
xdmp:document-insert(
| $uri as xs:string,
| $root as node(),
| [$permissions as element(sec:permission)*],
| [$collections as xs:string*],
| [$quality as xs:int?],
| [$forest-ids as xs:unsignedLong*]
) as empty-sequence()
Summary: Inserts a new document into the database if a document with the specified URI does not already exist. If a document already exists at the specified URI, the function replaces the content of the existing document with the specified content (the `$root` parameter) as an update operation. In addition to replacing the content, `xdmp:document-insert` replaces any permissions, collections, and quality with the ones specified (or with the default values for these parameters, if not explicitly specified). Also, if a properties document exists at the same URI, that properties document (including any content it contains) is preserved.
Parameters:
$uri : The URI of the document to be inserted.
$root : The root node. The root node can be one of XML format, binary (BLOB) format, or text (CLOB) format.
$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:
      xdmp:document-insert(
             "/example.xml", <a>aaa</a>,
                (xdmp:permission("editor", "read"),
                 xdmp:permission("editor", "update")),
             "http://examples.com")
Example:
      xdmp:document-insert(
             "/example.xml",
    	 <a>aaa</a>,
             xdmp:default-permissions(),
             xdmp:default-collections(),
    	 10)
Example:
    (:
       Specify the forest IDs to move a delete-only document
       from one forest to another (assuming at least one of
       the forests allows updates).
    :)
      xdmp:document-insert(
             "/example.xml",
    	 <root>new content here</root>, (), (), 0,
    	 xdmp:database-forests(xdmp:database()) )
Example:
    xquery version "1.0-ml";
    (: create a text document :)
    xdmp:document-insert("/text-doc.txt",
       text { "This is a text document." } )
xdmp:document-load(
| $location as xs:string,
| [$options as node()?]
) as empty-sequence()
Summary: Inserts a new document with the specified URI. If a document already exists at the URI, the function replaces the content in the existing document as an update operation.
Parameters:
$location : The location of the input document. If the scheme of the location is HTTP (that is, if the string starts with "http://"), then the document is requested over HTTP. If the scheme is file (that is, if the string starts with "file://"), then the document is requested over file protocol from the local filesystem. Otherwise, the document is fetched from the local filesystem. On the filesystem, the path can be fully qualifed or relative. Relative pathnames are resolved from the directory in which MarkLogic Server is installed.
>   $options (optional): The options node for this load operation. The default value is (). The node for the xdmp:document-load options must be in the `xdmp:document-load` namespace. This parameter can also include option elements in the `xdmp:http` namespace for the HTTP parameters. The `xdmp:document-load` options include: <uri> The URI of the document to be loaded. If omitted, then the location is used for the URI. <permissions> 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> The collection URIs for collections to which this document belongs. If not supplied, the document is added to the current user's default collections (the collections returned from `xdmp: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 `<collections>` element consists of one or more `<collection>` child elements. For example:
>           <collections>
>             <collection>myCollection1</collection>
>             <collection>myCollection2</collection>
>           </collections>
<quality> 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. <default-namespace> The namespace to use if there is no namespace at the root node of the document. The default value is "". <repair> A value of `full` specifies that malformed XML content be repaired. A value of `none` specifies that malformed XML content is rejected. If no repair option is explicitly specified, the default is implicitly specified by the XQuery version of the caller. In XQuery `1.0` and `1.0-ml` the default is `none`. In XQuery `0.9-ml` the default is `full`. This option has no effect on binary or text documents. <format> A value of `text` specifies to get the document as a text document, regardless of the URI specified. A value of `binary` specifies to get the document as a binary document, regardless of the URI specified. A value of `xml` specifies to get the document as an XML document, regardless of the URI specified. <default-language> The language to specify in an `xml:lang` attribute on the root element node if the root element node does not already have an `xml:lang` attribute. If `default-language` is not specified, then nothing is added to the root element node. <forests> Specifies the ID of the forest in which this document is inserted. Each forest ID is in a <forest> child element and is of type `xs:unsignedLong`. If the document already exists in the database, 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 already exists and the forest in which it is stored is set to delete-only, then you must specify the forest IDs to include one or more forests that allow updates, otherwise an exception is thrown. <encoding> Specifies the encoding to use when reading the document into MarkLogic Server. Supported values include `UTF-8`, `ISO-8859-1`, as well as many other popular encodings. See the Search Developer's Guide for a list of character set encodings by language. All encodings will be translated into UTF-8 from the specified encoding. The string specifed for the `encoding` option will be matched to an encoding name according to the Unicode Charset Alias Matching rules (http://www.unicode.org/reports/tr22/#Charset_Alias_Matching). An automatic encoding detector will be used if the value `auto` is specified. If no encoding can be detected, the encoding defaults to UTF-8. If no encoding option is specified and you are using a path with an `http://` scheme, the encoding defaults to the encoding specified in the http header (if an encoding header is specified), otherwise it defaults to UTF-8.
Required Privilege: `http://marklogic.com/xdmp/privileges/xdmp-document-load` If a new document is inserted, you also need the `unprotected-uri` privilege (only if the URI is not protected), the `any-uri` privilege, or an appropriate URI privilege. If adding an unprotected collection to a document, the `unprotected-collections` privilege (`http://marklogic.com/xdmp/privileges/unprotected-collections`) is needed; if adding a protected collection, the user must have either permissions to update the collection or the `any-collection` privilege (`http://marklogic.com/xdmp/privileges/any-collection`).
Usage Notes: When selecting documents over HTTP (where the `$location` parameter begins with `http://`), the response from the webserver is loaded into the database, regardless of what the headers returned from the webserver indicate. For example, if the webserver returns a 404 (file not found), then the response page that says "file not found" is loaded into the database. If you want to examine the headers before loading the document, use `xdmp:http-get` (combined with `xdmp:document-insert`) instead, as `xdmp:http-get` allows you to examine the headers returned from the HTTP server.
Example:
    xdmp:document-load("c:\myFile.xml",
        <options xmlns="xdmp:document-load">
          <uri>/documents/myFile.xml</uri>
          <repair>none</repair>
          <permissions>{xdmp:default-permissions()}</permissions>
        </options>)

    => Loads the document with a URI "/documents/myFile.xml"
       and does not perform tag repair during the load.
Example:
    xdmp:document-load("http://myCompany.com/file.xml",
        <options xmlns="xdmp:document-load"
                 xmlns:http="xdmp:http">
          <uri>/documents/myFile.xml</uri>
          <repair>none</repair>
          <permissions>{xdmp:default-permissions()}</permissions>
          <format>xml</format>
          <http:authentication>
              <http:username>user</http:username>
              <http:password>pass</http:password>
          </http:authentication>
        </options>)

    => Loads the document with a URI "/documents/myFile.xml"
       from the server http://myCompany.com, sending the
       credentials user/pass. Tag repair is not performed
       during the load, and the document is loaded as xml.
Example:
    xdmp:document-load("c:\myFile.xml",
        <options xmlns="xdmp:document-load">
           <uri>/documents/myFile.xml</uri>
           <permissions>{xdmp:default-permissions()}</permissions>
           <collections>
              <collection>myCollection1</collection>
    	  <collection>myCollection2</collection>
           </collections>
           <repair>full</repair>
           <forests>
             <forest>{xdmp:forest("myForest")}</forest>
           </forests>
        </options> )

    => Loads the document with a URI "/documents/myFile.xml"
       performing tag repair during the load, adding the
       document to the "myCollection1" and "myCollection2"
       collections, and loading the document into the forest
       named "myForest".
xdmp:document-remove-collections(
| $uri as xs:string,
| $collections as xs:string*
) as empty-sequence()
Summary: Removes the named document from the given 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.
Parameters:
$uri : The document URI.
$collections : A set of collection URIs.
Example:
      xdmp:document-remove-collections(
        "/example.xml",
        ("http://examples.com", "http://marklogic.com"))
xdmp:document-remove-permissions(
| $uri as xs:string,
| $permissions as element(sec:permission)*
) as empty-sequence()
Summary: Removes the given permissions from the named document or directory. The user must have update permissions on the document or directory.
Parameters:
$uri : The document URI.
$permissions : Permission elements.
Example:
      xdmp:document-remove-permissions(
        "/example.xml",
        (xdmp:permission("development", "update"),
         xdmp:permission("qa", "read")))
xdmp:document-remove-properties(
| $uri as xs:string,
| $property-names as xs:QName*
) as empty-sequence()
Summary: Removes a sequence of properties from the properties of a document. If properties with the QNames given do not exist, nothing is done.
Parameters:
$uri : The URI of the document whose properties are being updated.
$property-names : The properties to remove.
Example:
      xdmp:document-remove-properties(
             "example.xml",
             (fn:QName("", "priority"),
              fn:QName("", "status")))
      => ()
xdmp:document-set-collections(
| $uri as xs:string,
| $collections as xs:string*
) as empty-sequence()
Summary: Sets the named document to belong to the given collections, replacing any previously set collections on the named document. To preserve existing collections, use `xdmp:document-add-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.
Parameters:
$uri : The document URI.
$collections : A set of collection URIs.
Example:
      xdmp:document-set-collections(
        "/example.xml",
        ("http://examples.com", "http://marklogic.com"))
xdmp:document-set-permissions(
| $uri as xs:string,
| $permissions as element(sec:permission)*
) as empty-sequence()
Summary: Sets the permissions on the named document (or directory) to the given permissions, replacing any permissions previously set on the document (or directory). To preserve any existing permissions, use `xdmp:document-add-permissions`. The user must have update permissions on the document or directory.
Parameters:
$uri : The document URI.
$permissions : Permission elements.
Example:
      xdmp:document-set-permissions(
        "/example.xml",
        (xdmp:permission("development", "update"),
         xdmp:permission("qa", "read")))
xdmp:document-set-properties(
| $uri as xs:string,
| $props as element()*
) as empty-sequence()
Summary: Sets the properties of a document to the given sequence of elements, replacing any properties that already exist on the document. To preserve existing document properties, use `xdmp:document-add-properties`. Each element QName is the property name and the element value is the property value. Modifying properties requires update permissions on a document.
Parameters:
$uri : The URI of the document.
$props : The properties to set. Replaces any properties already set on the document.
Example:
      xdmp:document-set-properties(
             "example.xml",
             (<priority>1</priority>,
              <status>unedited</status>))
      => ()
xdmp:document-set-property(
| $uri as xs:string,
| $prop as element()
) as empty-sequence()
Summary: 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 document URI for the property setting.
$prop : The property to set.
Example:
    xdmp:document-set-property(
      "http://marklogic.com/a/example.xml",
      <priority xmlns="http://example.com">5</priority>)
xdmp:document-set-quality(
| $uri as xs:string,
| $quality as xs:int
) as empty-sequence()
Summary: 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 to which you are setting the quality.
$quality : The quality to which to set the document.
Example:
      xdmp:document-set-quality(
        "http://www.marklogic.com/test.xml",10)
      => ()
xdmp:load(
| $path as xs:string,
| [$uri as xs:string?],
| [$permissions as element(sec:permission)*],
| [$collections as xs:string*],
| [$quality as xs:int?],
| [$default-namespace as xs:string?],
| [$options as xs:string*],
| [$forest-ids as xs:unsignedLong*]
) as empty-sequence()
Summary: [DEPRECATED: use `xdmp:document-load` instead] Inserts a new document from the XML file at $path if a document with the specified URI does not already exist. Otherwise, the function replaces the content in the existing document as an update operation.
Parameters:
$path : The path to the input file. The path can be fully qualifed or relative. Relative pathnames are resolved from the directory in which MarkLogic Server is installed.
$uri (optional): The URI of the document to be loaded. If omitted, then the pathname is used.
$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(). To specify no permissions, enter the empty sequence ().
$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. The default value used for $collections can be obtained by calling xdmp:default-collections(). To specify no collections, enter the empty sequence ().
$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.
$default-namespace (optional): If $default-namespace is specified and the root node of the loaded document does not explicitly specify a namespace, $default-namespace will be applied to the root node. The default value for $default-namespace is "".
$options (optional): The options for loading this document. The default value is (). Options include: "repair-full" Specifies that malformed XML content be repaired during loading. This option has no effect on binary or text documents. "repair-none" Specifies that malformed XML content be rejected during loading. This option has no effect on binary or text documents. "format-text" Specifies to load the document as a text document, regardless of the URI specified. "format-binary" Specifies to load the document as a binary document, regardless of the URI specified. "format-xml" Specifies to load the document as an XML document, regardless of the URI specified. "lang=en" Specifies that the document is in english.
$forest-ids (optional): Specifies the ID of the forest in which this document is inserted. If the document already exists in the database, 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.
Required Privilege: `http://marklogic.com/xdmp/privileges/xdmp-load` If a new document is inserted, you also need the `unprotected-uri` privilege (only if the URI is not protected), the `any-uri` privilege, or an appropriate URI privilege.
Usage Notes: If no format is specified in $options, it is specified by the document content type specified by the extension of the document URI. The mimetype extensions and corresponding content types are set in the Admin Interface. If neither "repair-full" nor "repair-none" is present, the default is specified by the XQuery version of the caller. In XQuery version `1.0` and `1.0-ml` the default is "repair-none". In XQuery version `0.9-ml` the default is "repair-full".
Example:
      xdmp:load("/home/test/example.xml", "/example.xml",
                (xdmp:permission("editor", "read"),
                 xdmp:permission("editor", "update")),
                "http://examples.com",
                10,"http://www.marklogic.com/default")
Example:
      xdmp:load("/home/test/example.xml",
    	    "/example.xml",
                xdmp:default-permissions(),
                xdmp:default-collections(),
                0,
    	    "",
    	    "repair-none")
xdmp:lock-acquire(
| $uri as xs:string,
| [$scope as xs:string?],
| [$depth as xs:string?],
| [$owner as item()?],
| [$timeout as xs:unsignedLong?]
) as empty-sequence()
Summary: Acquire a lock on a document or directory for an extended amount of time. Locks restrict updates to a document or directory to the user who acquires the lock.
Parameters:
$uri : The URI of the document or directory to be locked.
$scope (optional): The lock scope ("exclusive" or "shared"). The default is "exclusive".
$depth (optional): The lock depth ("0" or "infinity"). "0" locks the URI only, and "infinity" locks the URI (the document or directory) and all of its children. The default is "0".
$owner (optional): Alternate description of the lock owner. If not specified or if specified as the empty sequence ( () ), then the owner is the user name of the user requesting the lock.
$timeout (optional): Requested lock timeout in seconds. If not specified or if specified as the empty sequence ( () ) or if specified as 0, then the timeout is infinite.
Usage Notes: If you lock a directory specifying a depth of "infinity", the directory and all of it children (all documents and directories with a URI started with the locked directory) are locked. You will not be able to add any children to the directory until the lock is released. When a user locks a URI, it is locked to other users, but not to the user who locked it. For example, if the user sam locks the URI `/home/sam.xml` by issuing the statement `xdmp:lock-acquire("/home/sam.xml")`, the user sam can still issue update commands to the document at that URI, but other users (for example, the user josh) will get an exception if they try to update the document. If you attempt to acquire a lock on a document that already has a lock, the XDMP-LOCKCONFLICT exception is thrown. If you attempt to update a document that is locked by another user, the XDMP-LOCKED exception is thrown.
Example:
    xquery version "1.0-ml";
    declare namespace DAV="DAV:";

    xdmp:lock-acquire("/example.xml",
               "exclusive",
               "0",
               <DAV:href>http://example.com/~user</DAV:href>,
               xs:unsignedLong(120))
    => ()
xdmp:lock-for-update(
| $uri as xs:string
) as empty-sequence()
Summary: Acquires an intent exclusive lock on a URI.
Parameters:
$uri : The URI to be locked for update.
Example:
      xdmp:lock-for-update("/example.xml")
xdmp:lock-release(
| $uri as xs:string
) as empty-sequence()
Summary: Unlock a document or directory. Releases the lock created with `xdmp:lock-acquire`.
Parameters:
$uri : The URI of the document or directory to be unlocked.
Example:
      xdmp:lock-release("/example.xml")
      => ()
xdmp:merge(
| [$options as node()?]
) as empty-sequence()
Summary: Starts merging the forests of the database, subject to specified options.
Parameters:
$options (optional): The options node for this merge. The default value is (). The node for the xdmp:merge options must be in the `xdmp:merge` namespace. The `xdmp:merge` options include: <merge-timestamp> Fragments with a timestamp of this or newer are not garbage collected during this merge <merge-max-size> The maximum allowable size, in megabytes, of a resultant stand <merge-priority> The CPU scheduler priority for the merge ("normal" or "lower") <single-stand> If any forests in the database have a single stand and this parameter is false, do not merge them. The default is `true`. <forests> Specifies the IDs of the forests in which to perform merges. Each forest ID is in the <forest> child element and is of type `xs:unsignedLong`.
Required Privilege: `http://marklogic.com/xdmp/privileges/xdmp-merge`
Example:
      xdmp:merge(<options xmlns="xdmp:merge">
           	       <merge-max-size>500</merge-max-size>
                   <merge-timestamp>8273</merge-timestamp>
                   <single-stand>false</single-stand>
                   <forests>
                     <forest>{xdmp:forest("my-forest")}</forest>
                     <forest>{xdmp:forest("my-other-forest")}</forest>
                   </forests>
    	     </options>)
       => ()
       Performs a merge on my-forest and my-other-forest.  If a stand
       created by this merge would be greater than 500 megabytes, the merge
       will be limited and not all stands will be merged (as many as can be
       merged under 500 MB will be merged).  If my-forest or my-other-forest
       have only one stand, they will not be merged.  Any fragments with
       timestamp 8273 or newer will not be garbage collected.
xdmp:merging( ) as xs:unsignedLong*
Summary: Returns the forest IDs of any currently merging database forests.
Required Privilege: `http://marklogic.com/xdmp/privileges/xdmp-merging`
Example:
      xdmp:merging()
       => 23487234872334
xdmp:node-delete(
| $old as node()
) as empty-sequence()
Summary: Deletes a node from the database. On-the-fly constructed nodes cannot be deleted.
Parameters:
$old : The node to be deleted.
Example:
      xdmp:document-insert("/example.xml",
        <a><b>bbb</b></a>);
      xdmp:node-delete(doc("/example.xml")/a/b);
      doc("/example.xml")
     =>
      <a/>
xdmp:node-insert-after(
| $sibling as node(),
| $new as node()
) as empty-sequence()
Summary: Adds an immediately following sibling to a node.
Parameters:
$sibling : The sibling node to be followed by the new node.
$new : The new node to be inserted.
Usage Notes: Attribute nodes cannot be followed by non-attribute nodes. Non-attribute nodes cannot be followed by attribute nodes. Element nodes cannot have document node children. Document nodes cannot have multiple element node children. On-the-fly constructed nodes cannot be updated.
Example:
      xdmp:document-insert("/example.xml",
        <a><b>bbb</b></a>);
      xdmp:node-insert-after(doc("/example.xml")/a/b,
        <c>ccc</c>);
      doc("/example.xml")
     =>
      <a><b>bbb</b><c>ccc</c></a>
xdmp:node-insert-before(
| $sibling as node(),
| $new as node()
) as empty-sequence()
Summary: Adds an immediately preceding sibling to a node.
Parameters:
$sibling : The sibling node to be preceded by the new node.
$new : The new node to be inserted.
Usage Notes: Attribute nodes cannot be preceded by non-attribute nodes. Non-attribute nodes cannot be preceded by attribute nodes. Element nodes cannot have document node children. Document nodes cannot have multiple element node children. On-the-fly constructed nodes cannot be updated.
Example:
      xdmp:document-insert("/example.xml",
        <a><b>bbb</b></a>);
      xdmp:node-insert-before(doc("/example.xml")/a/b,
        <c>ccc</c>);
      doc("/example.xml")
     =>
      <a><c>ccc</c><b>bbb</b></a>
xdmp:node-insert-child(
| $parent as node(),
| $new as node()
) as empty-sequence()
Summary: Adds a new last child to a node. Only element nodes and document nodes can have children. Element nodes cannot have document node children. Document nodes cannot have multiple element node children. On-the-fly constructed nodes cannot be updated. The parameters must specify individual nodes and not node sets.
Parameters:
$parent : The parent node which will have a new child node.
$new : The new child node to be inserted.
Example:
      xdmp:document-insert("/example.xml",
        <a/>);
      xdmp:node-insert-child(doc("/example.xml")/a,
        <b>bbb</b>);
      doc("/example.xml")
     =>
      <a><b>bbb</b></a>
Example:
      xdmp:document-insert("/example.xml", <a/>);
      xdmp:node-insert-child(doc("/example.xml")/a,
        attribute b { "bbb" });
      doc("/example.xml")
     =>
      <a b="bbb"/>
xdmp:node-replace(
| $old as node(),
| $new as node()
) as empty-sequence()
Summary: Replaces a node.
Parameters:
$old : The old node, to be replaced.
$new : The new node.
Usage Notes: Attribute nodes cannot be replaced by non-attribute nodes. Non-attribute nodes cannot be replaced by attribute nodes. Element nodes cannot have document node children. Document nodes cannot have multiple element node children.
Example:
      xdmp:document-insert("/example.xml",
        <a><b>bbb</b></a>);
      xdmp:node-replace(doc("/example.xml")/a/b, <c>ccc</c>);
      doc("/example.xml")
     =>
      <a><c>ccc</c></a>
Example:
    (: This example shows how to update the root
       node of a text format document.  Start by
       creating a text document.     :)

    xdmp:document-insert("/mydir/doc.txt",
    text{"This is a line of text."} ) ;

    (: Update the text node of the text document
       by appending another line of text to the
       text node.  Note that the text node is the
       root node of a text document.     :)

    xdmp:node-replace(doc("/mydir/doc.txt")/text() ,
    text{ concat(doc("/mydir/doc.txt")/text(), "
    This is another line of text.") } ) ;

    doc("/mydir/doc.txt")
    =>
    This is a line of text.
    This is another line of text.
xdmp:save(
| $path as xs:string,
| $node as node(),
| [$options as node()?]
) as empty-sequence()
Summary: Serializes a node as text and saves it to a file. The node can be any node, including a document node, an element node, a text node, or a binary node.
Parameters:
$path : The output file pathname. The path can be fully qualifed or relative. Relative pathnames are resolved from the directory in which MarkLogic Server is installed.
$node : The node to be serialized.
$options (optional): The options node for this save operation. The default value is (). The node for the xdmp:save options must be in the `xdmp:save` namespace. The `xdmp:save` options include: <output-encoding> Specifies the encoding to use when saving the document. <output-sgml-character-entities> Specifies if character entities should be output upon serialization of the XML. Valid values are `normal`, `none`, `math`, and `pub`. By default (that is, if this option is not specified), no SGML entities are serialized on output, unless the App Server is configured to output SGML character entities. <method> Valid values are `xml`, `html`, `xhtml`, and `text`. This is like the corresponding part of both the XSLT `xsl:output` instruction and the MarkLogic XQuery `xdmp:output` prolog statement. <cdata-section-elements> A list of QNames to output as CDATA sections. This is like the corresponding part of both the XSLT `xsl:output` instruction and the MarkLogic XQuery `xdmp:output` prolog statement. <encoding> The encoding. This is like the corresponding part of both the XSLT `xsl:output` instruction and the MarkLogic XQuery `xdmp:output` prolog statement. <use-character-maps> Valid values are `xdmp:sgml-entities-normal`, `xdmp:sgml-entities-math`, and `xdmp:sgml-entities-pub`. This is like the corresponding part of both the XSLT `xsl:output` instruction and the MarkLogic XQuery `xdmp:output` prolog statement. <media-type> A mimetype representing a media type. For example, `text/plain` or `text/xml` (or other valid mimetypes). This is like the corresponding part of both the XSLT `xsl:output` instruction and the MarkLogic XQuery `xdmp:output` prolog statement. <byte-order-mark> Valid values are `yes` or `no`. This is like the corresponding part of both the XSLT `xsl:output` instruction and the MarkLogic XQuery `xdmp:output` prolog statement. <indent> Specifies if typed XML (that is, XML for which there is an in-scope schema) should be pretty-printed (indented). Valid values are `yes` or `no`. This is like the corresponding part of both the XSLT `xsl:output` instruction and the MarkLogic XQuery `xdmp:output` prolog statement. <indent-untyped> Specifies if untyped XML (that is, XML for which there is no in-scope schema) should be pretty-printed (indented). Valid values are `yes` or `no`. This is like the corresponding part of both the XSLT `xsl:output` instruction and the MarkLogic XQuery `xdmp:output` prolog statement. <include-content-type> Include the content-type declaration when serializing the node. Valid values are `yes` or `no`. <escape-uri-attributes> Valid values are `yes` or `no`. This is like the corresponding part of both the XSLT `xsl:output` instruction and the MarkLogic XQuery `xdmp:output` prolog statement. <doctype-public> A public identifier, which is the public identifier to use on the emitted DOCTYPE. This is like the corresponding part of both the XSLT `xsl:output` instruction and the MarkLogic XQuery `xdmp:output` prolog statement. <doctype-system> A system identifier, which is the system identifier to use on the emitted DOCTYPE. This is like the corresponding part of both the XSLT `xsl:output` instruction and the MarkLogic XQuery `xdmp:output` prolog statement. <omit-xml-declaration> Valid values are `yes` or `no`. This is like the corresponding part of both the XSLT `xsl:output` instruction and the MarkLogic XQuery `xdmp:output` prolog statement. <standalone> Valid values are `yes` or `no`. This is like the corresponding part of both the XSLT `xsl:output` instruction and the MarkLogic XQuery `xdmp:output` prolog statement. <normalization-form> Valid values are `NFC`, `NFD`, and `NFKD`. This is like the corresponding part of both the XSLT `xsl:output` instruction and the MarkLogic XQuery `xdmp:output` prolog statement. <default-attributes> Specifies whether attributes defaulted with a schema should be included in the serialization. Valid values are `yes` or `no`. This is like the corresponding part of both the XSLT `xsl:output` instruction and the MarkLogic XQuery `xdmp:output` prolog statement.
Required Privilege: `http://marklogic.com/xdmp/privileges/xdmp-save`
Example:
      (: serialize an XML document in the database to a file on disk :)
      let $mynode := doc("/mydocs/example.xml")
      return
      xdmp:save("example.xml", $mynode)
Example:
      (: save a text file :)
      let $text := text { "hello" }
      return
      xdmp:save("hello.txt", $text)
Example:
      (: save a pdf stored in the database to disk :)
      let $pdf := doc("/mydocs/stuff.pdf")
      return
      xdmp:save("mystuff.pdf", $pdf)

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