<apidoc:module name="UpdateBuiltins" category="UpdateBuiltins" lib="xdmp" xmlns:apidoc="http://marklogic.com/xdmp/apidoc"><apidoc:summary access="public">
The update built-in functions are XQuery functions to perform update-related 
tasks such as loading documents, inserting nodes into documents, and so on.
</apidoc:summary><apidoc:function name="lock-for-update" type="builtin" lib="xdmp" category="UpdateBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Acquires an intent exclusive lock on a URI.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="uri" type="xs:string" optional="false">
    The URI to be locked for update.
  </apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:lock-for-update("/example.xml")
</pre></apidoc:example>
    <algorithm xmlns="http://www.w3.org/1999/xhtml"></algorithm>
  </apidoc:function><apidoc:function name="save" type="builtin" lib="xdmp" category="UpdateBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc: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.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="path" type="xs:string" optional="false">
    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.
  </apidoc:param>
      <apidoc:param name="node" type="node()" optional="false">
    The node to be serialized.
  </apidoc:param>
      <apidoc:param name="options" type="node()?" optional="true">
    The options node for this save operation. The default value is ().  
    The node for the xdmp:save options must be in the
    <code xmlns="http://www.w3.org/1999/xhtml">xdmp:save</code> namespace. 
    <p xmlns="http://www.w3.org/1999/xhtml">The <code>xdmp:save</code> options include:</p> 
    <blockquote xmlns="http://www.w3.org/1999/xhtml"><dl>
    <dt><p>&lt;output-encoding&gt;</p></dt>
    <dd>Specifies the encoding to use when saving the document.</dd>
    <dt><p>&lt;output-sgml-character-entities&gt;</p></dt>
    <dd>Specifies if character entities should be output upon serialization
    of the XML.  Valid values are <code>normal</code>, <code>none</code>, 
    <code>math</code>, and <code>pub</code>. 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.</dd>
    <dt><p>&lt;method&gt;</p></dt>
    <dd>Valid values are <code>xml</code>, <code>html</code>, 
    <code>xhtml</code>, and <code>text</code>. This is like 
    the corresponding part of both the 
    XSLT <a href="http://www.w3.org/TR/xslt20/#serialization"><code>xsl:output</code></a>
    instruction and the MarkLogic XQuery 
    <code>xdmp:output</code> prolog statement. 
    </dd>
    <dt><p>&lt;cdata-section-elements&gt;</p></dt>
    <dd>A list of QNames to output as CDATA sections.   This is like 
    the corresponding part of both the 
    XSLT <a href="http://www.w3.org/TR/xslt20/#serialization"><code>xsl:output</code></a>
    instruction and the MarkLogic XQuery 
    <code>xdmp:output</code> prolog statement.</dd>
    <dt><p>&lt;encoding&gt;</p></dt>
    <dd>The encoding. This is like 
    the corresponding part of both the 
    XSLT <a href="http://www.w3.org/TR/xslt20/#serialization"><code>xsl:output</code></a>
    instruction and the MarkLogic XQuery 
    <code>xdmp:output</code> prolog statement.</dd>
    <dt><p>&lt;use-character-maps&gt;</p></dt>
    <dd>Valid values are <code>xdmp:sgml-entities-normal</code>, 
    <code>xdmp:sgml-entities-math</code>, 
    and <code>xdmp:sgml-entities-pub</code>. This is like 
    the corresponding part of both the 
    XSLT <a href="http://www.w3.org/TR/xslt20/#serialization"><code>xsl:output</code></a>
    instruction and the MarkLogic XQuery 
    <code>xdmp:output</code> prolog statement.</dd>
    <dt><p>&lt;media-type&gt;</p></dt>
    <dd>A mimetype representing a media type. For example,
    <code>text/plain</code> or <code>text/xml</code> (or other valid 
    mimetypes). This is like 
    the corresponding part of both the 
    XSLT <a href="http://www.w3.org/TR/xslt20/#serialization"><code>xsl:output</code></a>
    instruction and the MarkLogic XQuery 
    <code>xdmp:output</code> prolog statement.</dd>
    <dt><p>&lt;byte-order-mark&gt;</p></dt>
    <dd>Valid values are <code>yes</code> or <code>no</code>.  This is like 
    the corresponding part of both the 
    XSLT <a href="http://www.w3.org/TR/xslt20/#serialization"><code>xsl:output</code></a>
    instruction and the MarkLogic XQuery 
    <code>xdmp:output</code> prolog statement.</dd>
    <dt><p>&lt;indent&gt;</p></dt>
    <dd>Specifies if typed XML (that is, XML for which there is an 
    in-scope schema) should be pretty-printed (indented).  Valid
    values are <code>yes</code> or <code>no</code>.  This is like 
    the corresponding part of both the 
    XSLT <a href="http://www.w3.org/TR/xslt20/#serialization"><code>xsl:output</code></a>
    instruction and the MarkLogic XQuery 
    <code>xdmp:output</code> prolog statement.</dd>
    <dt><p>&lt;indent-untyped&gt;</p></dt>
    <dd>Specifies if untyped XML (that is, XML for which there is no 
    in-scope schema) should be pretty-printed (indented).  Valid
    values are <code>yes</code> or <code>no</code>.  This is like 
    the corresponding part of both the 
    XSLT <a href="http://www.w3.org/TR/xslt20/#serialization"><code>xsl:output</code></a>
    instruction and the MarkLogic XQuery 
    <code>xdmp:output</code> prolog statement.</dd>
    <dt><p>&lt;include-content-type&gt;</p></dt>
    <dd>Include the content-type declaration when serializing the node.  
    Valid values are 
    <code>yes</code> or <code>no</code>.</dd>
    <dt><p>&lt;escape-uri-attributes&gt;</p></dt>
    <dd>Valid values are <code>yes</code> or <code>no</code>.  
    This is like 
    the corresponding part of both the 
    XSLT <a href="http://www.w3.org/TR/xslt20/#serialization"><code>xsl:output</code></a>
    instruction and the MarkLogic XQuery 
    <code>xdmp:output</code> prolog statement.</dd>
    <dt><p>&lt;doctype-public&gt;</p></dt>
    <dd>A public identifier, which is the public identifier to use on the 
    emitted DOCTYPE.  This is like 
    the corresponding part of both the 
    XSLT <a href="http://www.w3.org/TR/xslt20/#serialization"><code>xsl:output</code></a>
    instruction and the MarkLogic XQuery 
    <code>xdmp:output</code> prolog statement.</dd>
    <dt><p>&lt;doctype-system&gt;</p></dt>
    <dd>A system identifier, which is the system identifier to use on the 
    emitted DOCTYPE.  This is like 
    the corresponding part of both the 
    XSLT <a href="http://www.w3.org/TR/xslt20/#serialization"><code>xsl:output</code></a>
    instruction and the MarkLogic XQuery 
    <code>xdmp:output</code> prolog statement.</dd>
    <dt><p>&lt;omit-xml-declaration&gt;</p></dt>
    <dd>Valid values are <code>yes</code> or <code>no</code>.
    This is like 
    the corresponding part of both the 
    XSLT <a href="http://www.w3.org/TR/xslt20/#serialization"><code>xsl:output</code></a>
    instruction and the MarkLogic XQuery 
    <code>xdmp:output</code> prolog statement.</dd>
    <dt><p>&lt;standalone&gt;</p></dt>
    <dd>Valid values are <code>yes</code> or <code>no</code>.
    This is like 
    the corresponding part of both the 
    XSLT <a href="http://www.w3.org/TR/xslt20/#serialization"><code>xsl:output</code></a>
    instruction and the MarkLogic XQuery 
    <code>xdmp:output</code> prolog statement.</dd>
    <dt><p>&lt;normalization-form&gt;</p></dt>
    <dd>Valid values are <code>NFC</code>, <code>NFD</code>, 
    and <code>NFKD</code>.  This is like 
    the corresponding part of both the 
    XSLT <a href="http://www.w3.org/TR/xslt20/#serialization"><code>xsl:output</code></a>
    instruction and the MarkLogic XQuery 
    <code>xdmp:output</code> prolog statement.</dd>
    <dt><p>&lt;default-attributes&gt;</p></dt>
    <dd>Specifies whether attributes defaulted with a schema should be
    included in the serialization.
    Valid values are <code>yes</code> or <code>no</code>.
    This is like 
    the corresponding part of both the 
    XSLT <a href="http://www.w3.org/TR/xslt20/#serialization"><code>xsl:output</code></a>
    instruction and the MarkLogic XQuery 
    <code>xdmp:output</code> prolog statement.</dd>
    </dl></blockquote> 
  </apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:privilege>
  <p xmlns="http://www.w3.org/1999/xhtml"><code>http://marklogic.com/xdmp/privileges/xdmp-save</code></p>
</apidoc:privilege>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  (: serialize an XML document in the database to a file on disk :)
  let $mynode := doc("/mydocs/example.xml")
  return
  xdmp:save("example.xml", $mynode)
</pre></apidoc:example>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  (: save a text file :)
  let $text := text { "hello" }
  return
  xdmp:save("hello.txt", $text)
</pre></apidoc:example>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  (: save a pdf stored in the database to disk :)
  let $pdf := doc("/mydocs/stuff.pdf")
  return
  xdmp:save("mystuff.pdf", $pdf)
</pre></apidoc:example>
    <algorithm xmlns="http://www.w3.org/1999/xhtml"></algorithm>
  </apidoc:function><apidoc:function name="document-load" type="builtin" lib="xdmp" category="UpdateBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc: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.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="location" type="xs:string" optional="false">
    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. 
  </apidoc:param>
      <apidoc:param name="options" type="node()?" optional="true">
    The options node for this load operation. The default value is ().  
    The node for the xdmp:document-load options must be in the
    <code xmlns="http://www.w3.org/1999/xhtml">xdmp:document-load</code> namespace. This parameter can also include
    option elements in the <code xmlns="http://www.w3.org/1999/xhtml">xdmp:http</code> namespace for the HTTP 
    parameters.  
    <p xmlns="http://www.w3.org/1999/xhtml">The <code>xdmp:document-load</code> options include:</p> 
    <blockquote xmlns="http://www.w3.org/1999/xhtml"><dl>
    <dt><p>&lt;uri&gt;</p></dt>
    <dd> The URI of the document to be loaded. If omitted, then the location 
    is used for the URI.</dd>
    <dt><p>&lt;permissions&gt;</p></dt>
    <dd>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 <code>xdmp:default-permissions()</code>.  A document that is 
    created by a non-admin user (that is, by any user who does not have the 
    <code>admin</code> role) must have at least one update permission, 
    otherwise the creation will throw an <code>XDMP-MUSTHAVEUPDATE</code>
    exception.</dd>
    <dt><p>&lt;collections&gt;</p></dt>
    <dd>  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
    <code>xdmp:default-collections()</code>). For each collection that is 
    protected, the user must have permissions to update that collection 
    or have the <code>any-collection</code> privilege. For each unprotected 
    collection, the user must have the <code>unprotected-collections</code> 
    privilege. The 
    <code>&lt;collections&gt;</code> element consists of one or more 
    <code>&lt;collection&gt;</code> child elements. For example:
    <pre xml:space="preserve">
    &lt;collections&gt;
      &lt;collection&gt;myCollection1&lt;/collection&gt;
      &lt;collection&gt;myCollection2&lt;/collection&gt;
    &lt;/collections&gt; </pre>  </dd>
    <dt><p>&lt;quality&gt;</p></dt>
    <dd> 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.</dd>
    <dt><p>&lt;default-namespace&gt;</p></dt>
    <dd>The namespace to use if there is no namespace at the root node of
    the document.  The default value is "".</dd>
    <dt><p>&lt;repair&gt;</p></dt>
    <dd>A value of <code>full</code> specifies that malformed XML 
        content be repaired.  A value of <code>none</code> 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 <code>1.0</code> and <code>1.0-ml</code> the default 
	is <code>none</code>.  In XQuery <code>0.9-ml</code> the 
	default is <code>full</code>.
        This option has no effect on binary or text documents.</dd>
    <dt><p>&lt;format&gt;</p></dt>
    <dd>A value of <code>text</code> specifies to get the document as a text 
        document, regardless of the URI specified. A value of 
	<code>binary</code> specifies to get the document as a binary 
	document, regardless of the URI specified. A value of <code>xml</code>
       	specifies to get the document as an XML document, regardless of the 
	URI specified.</dd>
    <dt><p>&lt;default-language&gt;</p></dt>
    <dd>The language to specify in an <code>xml:lang</code> attribute on the
    root element node if the root element node does not already have an 
    <code>xml:lang</code> attribute. If <code>default-language</code> is
    not specified, then nothing is added to the root element node.</dd>
    <dt><p>&lt;forests&gt;</p></dt>
    <dd>Specifies the ID of the forest in which this document is inserted. 
    Each forest ID is in a &lt;forest&gt; child element and is of 
    type <code>xs:unsignedLong</code>. 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. </dd>
    <dt><p>&lt;encoding&gt;</p></dt>
    <dd>Specifies the encoding to use when reading the document into MarkLogic
    Server.  Supported values include <code>UTF-8</code>, 
    <code>ISO-8859-1</code>, as well as many other popular encodings.  
    See the <em>Search Developer's Guide</em> 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 
    <code>encoding</code> option will be matched to an encoding name according
    to the Unicode Charset Alias Matching rules 
    (<a href="http://www.unicode.org/reports/tr22/#Charset_Alias_Matching">http://www.unicode.org/reports/tr22/#Charset_Alias_Matching</a>).
    An automatic encoding detector will be used if the value <code>auto</code>
    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
    <code>http://</code> scheme, the encoding defaults to the 
    encoding specified in the http header (if an encoding header is specified),
    otherwise it defaults to UTF-8.
    </dd>
    </dl></blockquote> 
  </apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:privilege>
  <p xmlns="http://www.w3.org/1999/xhtml"><code>http://marklogic.com/xdmp/privileges/xdmp-document-load</code></p>
  <p xmlns="http://www.w3.org/1999/xhtml">If a new document is inserted, you also need the 
  <code>unprotected-uri</code> privilege (only if the URI is not protected), 
  the <code>any-uri</code> privilege, or an appropriate URI privilege. </p>
  <p xmlns="http://www.w3.org/1999/xhtml">If adding an unprotected collection to a document, the 
  <code>unprotected-collections</code> privilege
  (<code>http://marklogic.com/xdmp/privileges/unprotected-collections</code>)
  is needed; if adding a protected collection, the user must have either 
  permissions to update the collection or the 
  <code>any-collection</code> privilege
  (<code>http://marklogic.com/xdmp/privileges/any-collection</code>).
  </p>
</apidoc:privilege>
    <apidoc:usage>
  <p xmlns="http://www.w3.org/1999/xhtml">When selecting documents over HTTP (where the <code>$location</code>
  parameter begins with <code>http://</code>), 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 <code>xdmp:http-get</code> (combined with 
  <code>xdmp:document-insert</code>) instead, as <code>xdmp:http-get</code>
  allows you to examine the headers returned from the HTTP server.
  </p>
</apidoc:usage>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
xdmp:document-load("c:\myFile.xml", 
    &lt;options xmlns="xdmp:document-load"&gt;
      &lt;uri&gt;/documents/myFile.xml&lt;/uri&gt;
      &lt;repair&gt;none&lt;/repair&gt;
      &lt;permissions&gt;{xdmp:default-permissions()}&lt;/permissions&gt;
    &lt;/options&gt;)

=&gt; Loads the document with a URI "/documents/myFile.xml"
   and does not perform tag repair during the load.


</pre></apidoc:example>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
xdmp:document-load("http://myCompany.com/file.xml", 
    &lt;options xmlns="xdmp:document-load"
             xmlns:http="xdmp:http"&gt;
      &lt;uri&gt;/documents/myFile.xml&lt;/uri&gt;
      &lt;repair&gt;none&lt;/repair&gt;
      &lt;permissions&gt;{xdmp:default-permissions()}&lt;/permissions&gt;
      &lt;format&gt;xml&lt;/format&gt;
      &lt;http:authentication&gt;
          &lt;http:username&gt;user&lt;/http:username&gt;
          &lt;http:password&gt;pass&lt;/http:password&gt;
      &lt;/http:authentication&gt;
    &lt;/options&gt;)

=&gt; 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.


</pre></apidoc:example>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
xdmp:document-load("c:\myFile.xml",
    &lt;options xmlns="xdmp:document-load"&gt;
       &lt;uri&gt;/documents/myFile.xml&lt;/uri&gt;
       &lt;permissions&gt;{xdmp:default-permissions()}&lt;/permissions&gt; 
       &lt;collections&gt;
          &lt;collection&gt;myCollection1&lt;/collection&gt;
	  &lt;collection&gt;myCollection2&lt;/collection&gt;
       &lt;/collections&gt; 
       &lt;repair&gt;full&lt;/repair&gt;
       &lt;forests&gt;
         &lt;forest&gt;{xdmp:forest("myForest")}&lt;/forest&gt;
       &lt;/forests&gt;
    &lt;/options&gt; )

=&gt; 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".


</pre></apidoc:example>
  </apidoc:function><apidoc:function name="load" type="builtin" lib="xdmp" category="UpdateBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  [DEPRECATED: use <a href="#xdmp:document-load" xmlns="http://www.w3.org/1999/xhtml"><code>xdmp:document-load</code></a>
  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.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="path" type="xs:string" optional="false">
    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. 
  </apidoc:param>
      <apidoc:param name="uri" type="xs:string?" optional="true">
    The URI of the document to be loaded.  
    If omitted, then the pathname is used.
  </apidoc:param>
      <apidoc:param name="permissions" type="element(sec:permission)*" optional="true">
    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 ().
  </apidoc:param>
      <apidoc:param name="collections" type="xs:string*" optional="true">
    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 ().
  </apidoc:param>
      <apidoc:param name="quality" type="xs:int?" optional="true">
    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.
  </apidoc:param>
      <apidoc:param name="default-namespace" type="xs:string?" optional="true">
    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 "".
  </apidoc:param>
      <apidoc:param name="options" type="xs:string*" optional="true">
    The options for loading this document.  
    The default value is ().
    <p xmlns="http://www.w3.org/1999/xhtml">Options include:</p>
    <blockquote xmlns="http://www.w3.org/1999/xhtml"><dl>
    <dt>"repair-full"</dt>
    <dd>Specifies that malformed XML content be repaired during loading.  
        This option has no effect on binary or text documents.</dd>
    <dt>"repair-none"</dt>
    <dd>Specifies that malformed XML content be rejected during loading. 
        This option has no effect on binary or text documents.</dd>
    <dt>"format-text"</dt>
    <dd>Specifies to load the document as a text document, 
        regardless of the URI specified.</dd>
    <dt>"format-binary"</dt>
    <dd>Specifies to load the document as a binary document, 
        regardless of the URI specified.</dd>
    <dt>"format-xml"</dt>
    <dd>Specifies to load the document as an XML document, 
        regardless of the URI specified.</dd>
    <dt>"lang=en"</dt>
    <dd>Specifies that the document is in english.</dd>
    </dl></blockquote>
  </apidoc:param>
      <apidoc:param name="forest-ids" type="xs:unsignedLong*" optional="true">
    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.
  </apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:privilege>
  <p xmlns="http://www.w3.org/1999/xhtml"><code>http://marklogic.com/xdmp/privileges/xdmp-load</code></p>
  <p xmlns="http://www.w3.org/1999/xhtml">If a new document is inserted, you also need the 
  <code>unprotected-uri</code> privilege (only if the URI is not protected), 
  the <code>any-uri</code> privilege, or an appropriate URI privilege. </p> 
</apidoc:privilege>
    <apidoc:usage>
  <p xmlns="http://www.w3.org/1999/xhtml">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.</p>
  <p xmlns="http://www.w3.org/1999/xhtml">If neither "repair-full" nor "repair-none" is present, 
  the default is specified by the XQuery version of the caller.
  In XQuery version <code>1.0</code> and <code>1.0-ml</code> the default is 
  "repair-none".  In XQuery version <code>0.9-ml</code> the default is 
  "repair-full".</p>
</apidoc:usage>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  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")
</pre></apidoc:example>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:load("/home/test/example.xml", 
	    "/example.xml", 
            xdmp:default-permissions(), 
            xdmp:default-collections(),
            0, 
	    "", 
	    "repair-none")
</pre></apidoc:example>
    <algorithm xmlns="http://www.w3.org/1999/xhtml"></algorithm>
  </apidoc:function><apidoc:function name="document-insert" type="builtin" lib="xdmp" category="UpdateBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc: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 <code xmlns="http://www.w3.org/1999/xhtml">$root</code> parameter) 
  as an update operation.  In addition to replacing the content, 
  <code xmlns="http://www.w3.org/1999/xhtml">xdmp:document-insert</code> 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.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="uri" type="xs:string" optional="false">
    The URI of the document to be inserted.  
  </apidoc:param>
      <apidoc:param name="root" type="node()" optional="false">
    The root node.  The root node can be one of XML format, binary (BLOB) 
    format, or text (CLOB) format.
  </apidoc:param>
      <apidoc:param name="permissions" type="element(sec:permission)*" optional="true">
    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 
    <code xmlns="http://www.w3.org/1999/xhtml">admin</code> role) must have at least one update permission, 
    otherwise the creation will throw an <code xmlns="http://www.w3.org/1999/xhtml">XDMP-MUSTHAVEUPDATE</code>
    exception.  
  </apidoc:param>
      <apidoc:param name="collections" type="xs:string*" optional="true">
    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 
    <code xmlns="http://www.w3.org/1999/xhtml">any-collection</code> privilege. For each unprotected collection, 
    the user must have the <code xmlns="http://www.w3.org/1999/xhtml">unprotected-collections</code> privilege.
    The default value used for $collections can be obtained by calling 
    <code xmlns="http://www.w3.org/1999/xhtml">xdmp:default-collections()</code>.
  </apidoc:param>
      <apidoc:param name="quality" type="xs:int?" optional="true">
    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.
  </apidoc:param>
      <apidoc:param name="forest-ids" type="xs:unsignedLong*" optional="true">
    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. 
  </apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:privilege>
  <p xmlns="http://www.w3.org/1999/xhtml">If a new document is inserted, the <code>unprotected-uri</code> privilege 
  (only if the URI is not protected), the <code>any-uri</code> privilege, or an 
  appropriate URI privilege is also needed.  If adding an unprotected
  collection to a document, the <code>unprotected-collections</code> privilege
  is needed; if adding a protected collection, the user must have either 
  permissions to update the collection or the 
  <code>any-collection</code> privilege.</p> 
</apidoc:privilege>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:document-insert(
         "/example.xml", &lt;a&gt;aaa&lt;/a&gt;,
            (xdmp:permission("editor", "read"), 
             xdmp:permission("editor", "update")),
         "http://examples.com")
</pre></apidoc:example>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:document-insert(
         "/example.xml", 
	 &lt;a&gt;aaa&lt;/a&gt;,
         xdmp:default-permissions(), 
         xdmp:default-collections(), 
	 10)
</pre></apidoc:example>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
(: 
   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", 
	 &lt;root&gt;new content here&lt;/root&gt;, (), (), 0,
	 xdmp:database-forests(xdmp:database()) )
</pre></apidoc:example>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
xquery version "1.0-ml";
(: create a text document :)
xdmp:document-insert("/text-doc.txt", 
   text { "This is a text document." } )

</pre></apidoc:example>
  </apidoc:function><apidoc:function name="directory-create" type="builtin" lib="xdmp" category="UpdateBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc: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.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="uri" type="xs:string" optional="false">
    The URI of the directory to be inserted.  
  </apidoc:param>
      <apidoc:param name="permissions" type="element(sec:permission)*" optional="true">
    Security permission elements corresponding to the permissions
    for the document.
  </apidoc:param>
      <apidoc:param name="collections" type="xs:string*" optional="true">
    The collections to which the new directory belongs.
  </apidoc:param>
      <apidoc:param name="quality" type="xs:int?" optional="true">
    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.
  </apidoc:param>
      <apidoc:param name="forest-ids" type="xs:unsignedLong*" optional="true">
    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.
  </apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
xdmp:directory-create("http://marklogic.com/a/",
            (xdmp:permission("development", "update"),
             xdmp:permission("qa", "read")),
             "http://marklogic.com/directories")

=&gt; 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.  
  
</pre></apidoc:example>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
xdmp:directory-create("/dir/myDirectory/")

=&gt; 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/").  
  
</pre></apidoc:example>
    <algorithm xmlns="http://www.w3.org/1999/xhtml"></algorithm>
  </apidoc:function><apidoc:function name="document-delete" type="builtin" lib="xdmp" category="UpdateBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Deletes a document from the database.
  </apidoc:summary>
    <apidoc:params>
      <apidoc:param name="uri" type="xs:string" optional="false">
    The URI of the document to be deleted.
    </apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:usage><p xmlns="http://www.w3.org/1999/xhtml">The <code>xdmp:document-delete</code> 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 <code>xdmp:directory-delete</code> function.  
  </p><p xmlns="http://www.w3.org/1999/xhtml">If a document does not exist at the specified URI, 
  <code>xdmp:document-delete</code> returns an error.</p>
  </apidoc:usage>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
xdmp:document-delete("example.xml")
</pre></apidoc:example>
  </apidoc:function><apidoc:function name="directory-delete" type="builtin" lib="xdmp" category="UpdateBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Deletes a directory and all of its child and descendant documents and
  directories from the database.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="uri" type="xs:string" optional="false">
    The URI of the directory to be deleted.
  </apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:usage>
  <p xmlns="http://www.w3.org/1999/xhtml">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.</p>
</apidoc:usage>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:directory-delete("http://example.com/")
</pre></apidoc:example>
    <algorithm xmlns="http://www.w3.org/1999/xhtml"></algorithm>
  </apidoc:function><apidoc:function name="collection-delete" type="builtin" lib="xdmp" category="UpdateBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Deletes from the database every document in a collection. If there are
  no documents in the specified collection, then nothing is deleted, and 
  <code xmlns="http://www.w3.org/1999/xhtml">xdmp:collection-delete</code> still returns the empty sequence.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="uri" type="xs:string" optional="false">
    The URI of the collection to be deleted.
  </apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:collection-delete("collection-uri")
</pre></apidoc:example>
    <algorithm xmlns="http://www.w3.org/1999/xhtml"></algorithm>
  </apidoc:function><apidoc:function name="node-replace" type="builtin" lib="xdmp" category="UpdateBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Replaces a node.  
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="old" type="node()" optional="false">
    The old node, to be replaced.
  </apidoc:param>
      <apidoc:param name="new" type="node()" optional="false">
    The new node.
  </apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:usage>
  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.
</apidoc:usage>
    <apidoc:example>
<pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:document-insert("/example.xml", 
    &lt;a&gt;&lt;b&gt;bbb&lt;/b&gt;&lt;/a&gt;);
  xdmp:node-replace(doc("/example.xml")/a/b, &lt;c&gt;ccc&lt;/c&gt;);
  doc("/example.xml")
 =&gt;
  &lt;a&gt;&lt;c&gt;ccc&lt;/c&gt;&lt;/a&gt;
</pre>
</apidoc:example>
    <apidoc:example>
<pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
(: 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")
=&gt;
This is a line of text.
This is another line of text.

</pre>
</apidoc:example>
    <algorithm xmlns="http://www.w3.org/1999/xhtml"></algorithm>
  </apidoc:function><apidoc:function name="node-delete" type="builtin" lib="xdmp" category="UpdateBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Deletes a node from the database.
  On-the-fly constructed nodes cannot be deleted.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="old" type="node()" optional="false">
    The node to be deleted.
  </apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:document-insert("/example.xml", 
    &lt;a&gt;&lt;b&gt;bbb&lt;/b&gt;&lt;/a&gt;);
  xdmp:node-delete(doc("/example.xml")/a/b);
  doc("/example.xml")
 =&gt; 
  &lt;a/&gt;
</pre></apidoc:example>
    <algorithm xmlns="http://www.w3.org/1999/xhtml"></algorithm>
  </apidoc:function><apidoc:function name="node-insert-before" type="builtin" lib="xdmp" category="UpdateBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Adds an immediately preceding sibling to a node.  
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="sibling" type="node()" optional="false">
    The sibling node to be preceded by the new node.
  </apidoc:param>
      <apidoc:param name="new" type="node()" optional="false">
    The new node to be inserted.
  </apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:usage>
  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.  
</apidoc:usage>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:document-insert("/example.xml", 
    &lt;a&gt;&lt;b&gt;bbb&lt;/b&gt;&lt;/a&gt;);
  xdmp:node-insert-before(doc("/example.xml")/a/b, 
    &lt;c&gt;ccc&lt;/c&gt;);
  doc("/example.xml")
 =&gt; 
  &lt;a&gt;&lt;c&gt;ccc&lt;/c&gt;&lt;b&gt;bbb&lt;/b&gt;&lt;/a&gt;
</pre>
</apidoc:example>
    <algorithm xmlns="http://www.w3.org/1999/xhtml"></algorithm>
  </apidoc:function><apidoc:function name="node-insert-after" type="builtin" lib="xdmp" category="UpdateBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Adds an immediately following sibling to a node.  
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="sibling" type="node()" optional="false">
    The sibling node to be followed by the new node.
  </apidoc:param>
      <apidoc:param name="new" type="node()" optional="false">
    The new node to be inserted.
  </apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:usage>
  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.  
</apidoc:usage>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:document-insert("/example.xml", 
    &lt;a&gt;&lt;b&gt;bbb&lt;/b&gt;&lt;/a&gt;);
  xdmp:node-insert-after(doc("/example.xml")/a/b, 
    &lt;c&gt;ccc&lt;/c&gt;);
  doc("/example.xml")
 =&gt; 
  &lt;a&gt;&lt;b&gt;bbb&lt;/b&gt;&lt;c&gt;ccc&lt;/c&gt;&lt;/a&gt;
</pre>
</apidoc:example>
    <algorithm xmlns="http://www.w3.org/1999/xhtml"></algorithm>
  </apidoc:function><apidoc:function name="node-insert-child" type="builtin" lib="xdmp" category="UpdateBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc: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.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="parent" type="node()" optional="false">
    The parent node which will have a new child node.
  </apidoc:param>
      <apidoc:param name="new" type="node()" optional="false">
    The new child node to be inserted.
  </apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:document-insert("/example.xml", 
    &lt;a/&gt;);
  xdmp:node-insert-child(doc("/example.xml")/a,
    &lt;b&gt;bbb&lt;/b&gt;);
  doc("/example.xml")
 =&gt; 
  &lt;a&gt;&lt;b&gt;bbb&lt;/b&gt;&lt;/a&gt;
</pre>
</apidoc:example>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:document-insert("/example.xml", &lt;a/&gt;);
  xdmp:node-insert-child(doc("/example.xml")/a, 
    attribute b { "bbb" });
  doc("/example.xml")
 =&gt; 
  &lt;a b="bbb"/&gt;
</pre>
</apidoc:example>
    <algorithm xmlns="http://www.w3.org/1999/xhtml"></algorithm>
  </apidoc:function><apidoc:function name="document-add-collections" type="builtin" lib="xdmp" category="UpdateBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc: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 <code xmlns="http://www.w3.org/1999/xhtml">any-collection</code> privilege.  
  For each unprotected collection, the user must have the 
  <code xmlns="http://www.w3.org/1999/xhtml">unprotected-collections</code> privilege.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="uri" type="xs:string" optional="false">
    The document URI.
  </apidoc:param>
      <apidoc:param name="collections" type="xs:string*" optional="false">
    A set of collection URIs.
  </apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:privilege>
 <p xmlns="http://www.w3.org/1999/xhtml">If adding an unprotected collection to a document, the 
  <code>unprotected-collections</code> privilege
  (<code>http://marklogic.com/xdmp/privileges/unprotected-collections</code>)
  is needed; if adding a protected collection, the user must have either 
  permissions to update the collection or the 
  <code>any-collection</code> privilege
  (<code>http://marklogic.com/xdmp/privileges/any-collection</code>).
  </p> 
</apidoc:privilege>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:document-add-collections(
    "/example.xml", 
    ("http://examples.com", "http://marklogic.com"))
</pre></apidoc:example>
    <algorithm xmlns="http://www.w3.org/1999/xhtml"></algorithm>
  </apidoc:function><apidoc:function name="document-remove-collections" type="builtin" lib="xdmp" category="UpdateBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc: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 <code xmlns="http://www.w3.org/1999/xhtml">any-collection</code> privilege.  For each
  unprotected collection, the user must have the 
  <code xmlns="http://www.w3.org/1999/xhtml">unprotected-collections</code> privilege.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="uri" type="xs:string" optional="false">
    The document URI.
  </apidoc:param>
      <apidoc:param name="collections" type="xs:string*" optional="false">
    A set of collection URIs.
  </apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:document-remove-collections(
    "/example.xml", 
    ("http://examples.com", "http://marklogic.com"))
</pre></apidoc:example>
    <algorithm xmlns="http://www.w3.org/1999/xhtml"></algorithm>
  </apidoc:function><apidoc:function name="document-set-collections" type="builtin" lib="xdmp" category="UpdateBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc: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 <code xmlns="http://www.w3.org/1999/xhtml">xdmp:document-add-collections</code>.  For each
  collection that is protected, the user must have permissions to update
  that collection or have the <code xmlns="http://www.w3.org/1999/xhtml">any-collection</code> privilege.  For each
  unprotected collection, the user must have the 
  <code xmlns="http://www.w3.org/1999/xhtml">unprotected-collections</code> privilege.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="uri" type="xs:string" optional="false">
    The document URI.
  </apidoc:param>
      <apidoc:param name="collections" type="xs:string*" optional="false">
    A set of collection URIs.
  </apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:document-set-collections(
    "/example.xml", 
    ("http://examples.com", "http://marklogic.com"))
</pre></apidoc:example>
    <algorithm xmlns="http://www.w3.org/1999/xhtml"></algorithm>
  </apidoc:function><apidoc:function name="document-add-permissions" type="builtin" lib="xdmp" category="UpdateBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Adds the given permissions to the given document or directory.  
  The user must have update or insert permissions on the document.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="uri" type="xs:string" optional="false">
    The document URI.
  </apidoc:param>
      <apidoc:param name="permissions" type="element(sec:permission)*" optional="false">
    Permission elements.
  </apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:document-add-permissions(
    "/example.xml", 
    (xdmp:permission("development", "update"), 
     xdmp:permission("qa", "read")))
</pre></apidoc:example>
    <algorithm xmlns="http://www.w3.org/1999/xhtml"></algorithm>
  </apidoc:function><apidoc:function name="document-remove-permissions" type="builtin" lib="xdmp" category="UpdateBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Removes the given permissions from the named document or directory.  
  The user must have update permissions on the document or directory.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="uri" type="xs:string" optional="false">
    The document URI.
  </apidoc:param>
      <apidoc:param name="permissions" type="element(sec:permission)*" optional="false">
    Permission elements.
  </apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:document-remove-permissions(
    "/example.xml", 
    (xdmp:permission("development", "update"), 
     xdmp:permission("qa", "read")))
</pre></apidoc:example>
    <algorithm xmlns="http://www.w3.org/1999/xhtml"></algorithm>
  </apidoc:function><apidoc:function name="document-set-permissions" type="builtin" lib="xdmp" category="UpdateBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc: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 
  <code xmlns="http://www.w3.org/1999/xhtml">xdmp:document-add-permissions</code>.
  The user must have update permissions on the document or directory.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="uri" type="xs:string" optional="false">
    The document URI.
  </apidoc:param>
      <apidoc:param name="permissions" type="element(sec:permission)*" optional="false">
    Permission elements.
  </apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:document-set-permissions(
    "/example.xml", 
    (xdmp:permission("development", "update"), 
     xdmp:permission("qa", "read")))
</pre></apidoc:example>
    <algorithm xmlns="http://www.w3.org/1999/xhtml"></algorithm>
  </apidoc:function><apidoc:function name="document-set-quality" type="builtin" lib="xdmp" category="UpdateBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc: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.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="uri" type="xs:string" optional="false">
    The URI of the document to which you are setting the quality. 
  </apidoc:param>
      <apidoc:param name="quality" type="xs:int" optional="false">
    The quality to which to set the document.
  </apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:document-set-quality(
    "http://www.marklogic.com/test.xml",10)
  =&gt; ()
</pre></apidoc:example>
    <algorithm xmlns="http://www.w3.org/1999/xhtml"></algorithm>
  </apidoc:function><apidoc:function name="merge" type="builtin" lib="xdmp" category="UpdateBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Starts merging the forests of the database, subject to specified 
  options.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="options" type="node()?" optional="true">
    The options node for this merge. The default value is ().  
    The node for the xdmp:merge options must be in the
    <code xmlns="http://www.w3.org/1999/xhtml">xdmp:merge</code> namespace. 
    <p xmlns="http://www.w3.org/1999/xhtml">The <code>xdmp:merge</code> options include:</p> 
    <blockquote xmlns="http://www.w3.org/1999/xhtml"><dl>
    <dt><p>&lt;merge-timestamp&gt;</p></dt>
    <dd>Fragments with a timestamp of this or newer are not garbage collected
    during this merge</dd> 
    <dt><p>&lt;merge-max-size&gt;</p></dt>
    <dd> The maximum allowable size, in megabytes, of a resultant stand</dd>
    <dt><p>&lt;merge-priority&gt;</p></dt>
    <dd>The CPU scheduler priority for the merge ("normal" or "lower")</dd>
    <dt><p>&lt;single-stand&gt;</p></dt>
    <dd> If any forests in the database have a single stand and this parameter
    is false, do not merge them.  The default is <code>true</code>.
    </dd>
    <dt><p>&lt;forests&gt;</p></dt>
    <dd>Specifies the IDs of the forests in which to perform merges.
    Each forest ID is in the &lt;forest&gt; child element and is of 
    type <code>xs:unsignedLong</code>.</dd>
    </dl></blockquote> 
  </apidoc:param>
    </apidoc:params>
    <apidoc:privilege>
  <p xmlns="http://www.w3.org/1999/xhtml"><code>http://marklogic.com/xdmp/privileges/xdmp-merge</code></p>
</apidoc:privilege>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:merge(&lt;options xmlns="xdmp:merge"&gt;
       	       &lt;merge-max-size&gt;500&lt;/merge-max-size&gt;
               &lt;merge-timestamp&gt;8273&lt;/merge-timestamp&gt;
               &lt;single-stand&gt;false&lt;/single-stand&gt;
               &lt;forests&gt;
                 &lt;forest&gt;{xdmp:forest("my-forest")}&lt;/forest&gt;
                 &lt;forest&gt;{xdmp:forest("my-other-forest")}&lt;/forest&gt;
               &lt;/forests&gt;
	     &lt;/options&gt;)
   =&gt; ()
   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.
</pre></apidoc:example>
    <algorithm xmlns="http://www.w3.org/1999/xhtml"></algorithm>
  </apidoc:function><apidoc:function name="merging" type="builtin" lib="xdmp" category="UpdateBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Returns the forest IDs of any currently merging database forests.
</apidoc:summary>
    <apidoc:params/>
    <apidoc:privilege>
  <p xmlns="http://www.w3.org/1999/xhtml"><code>http://marklogic.com/xdmp/privileges/xdmp-merging</code></p>
</apidoc:privilege>
    <apidoc:return>xs:unsignedLong*</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:merging()
   =&gt; 23487234872334
</pre></apidoc:example>
    <algorithm xmlns="http://www.w3.org/1999/xhtml"></algorithm>
  </apidoc:function><apidoc:function name="lock-acquire" type="builtin" lib="xdmp" category="UpdateBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc: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. 
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="uri" type="xs:string" optional="false">
    The URI of the document or directory to be locked.
  </apidoc:param>
      <apidoc:param name="scope" type="xs:string?" optional="true">
    The lock scope ("exclusive" or "shared").  The default is "exclusive".
  </apidoc:param>
      <apidoc:param name="depth" type="xs:string?" optional="true">
    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".
  </apidoc:param>
      <apidoc:param name="owner" type="item()?" optional="true">
    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.
  </apidoc:param>
      <apidoc:param name="timeout" type="xs:unsignedLong?" optional="true">
    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.
  </apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:usage>
   <p xmlns="http://www.w3.org/1999/xhtml">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.</p>
   <p xmlns="http://www.w3.org/1999/xhtml">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 <em>sam</em> locks the URI
   <code>/home/sam.xml</code> by issuing the statement 
   <code>xdmp:lock-acquire("/home/sam.xml")</code>, the user <em>sam</em>
   can still issue update commands to the document at that URI, but other users
   (for example, the user <em>josh</em>) will get an exception if they try 
   to update the document.</p>
   <p xmlns="http://www.w3.org/1999/xhtml">If you attempt to acquire a lock on a document that already has a lock,
   the XDMP-LOCKCONFLICT exception is thrown.</p>
   <p xmlns="http://www.w3.org/1999/xhtml">If you attempt to update a document that is locked by another user,
   the XDMP-LOCKED exception is thrown.</p>
</apidoc:usage>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
xquery version "1.0-ml";
declare namespace DAV="DAV:";

xdmp:lock-acquire("/example.xml", 
           "exclusive",
           "0",
           &lt;DAV:href&gt;http://example.com/~user&lt;/DAV:href&gt;,
           xs:unsignedLong(120))
=&gt; ()
</pre></apidoc:example>
  </apidoc:function><apidoc:function name="lock-release" type="builtin" lib="xdmp" category="UpdateBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Unlock a document or directory.  Releases the lock created with 
  <code xmlns="http://www.w3.org/1999/xhtml">xdmp:lock-acquire</code>.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="uri" type="xs:string" optional="false">
    The URI of the document or directory to be unlocked.
  </apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:lock-release("/example.xml")
  =&gt; () </pre>
</apidoc:example>
    <algorithm xmlns="http://www.w3.org/1999/xhtml"></algorithm>
  </apidoc:function><apidoc:function name="document-set-properties" type="builtin" lib="xdmp" category="UpdateBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc: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 <code xmlns="http://www.w3.org/1999/xhtml">xdmp:document-add-properties</code>.  
  Each element QName is the property name and the element value is the 
  property value.  Modifying properties requires update permissions on a 
  document.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="uri" type="xs:string" optional="false">
    The URI of the document.  
  </apidoc:param>
      <apidoc:param name="props" type="element()*" optional="false">
    The properties to set. Replaces any properties already set on the 
    document.
  </apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:document-set-properties(
         "example.xml", 
         (&lt;priority&gt;1&lt;/priority&gt;,
          &lt;status&gt;unedited&lt;/status&gt;))
  =&gt; ()
</pre></apidoc:example>
    <algorithm xmlns="http://www.w3.org/1999/xhtml"></algorithm>
  </apidoc:function><apidoc:function name="document-add-properties" type="builtin" lib="xdmp" category="UpdateBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Adds a sequence of properties to the properties of a document.  
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="uri" type="xs:string" optional="false">
    The URI of the document.  
  </apidoc:param>
      <apidoc:param name="props" type="element()*" optional="false">
    The properties to add.
  </apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:document-add-properties(
         "example.xml", 
         (&lt;priority&gt;1&lt;/priority&gt;,
          &lt;status&gt;unedited&lt;/status&gt;))
  =&gt; ()
</pre></apidoc:example>
    <algorithm xmlns="http://www.w3.org/1999/xhtml"></algorithm>
  </apidoc:function><apidoc:function name="document-remove-properties" type="builtin" lib="xdmp" category="UpdateBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Removes a sequence of properties from the properties of a document.  If
  properties with the QNames given do not exist, nothing is done.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="uri" type="xs:string" optional="false">
    The URI of the document whose properties are being updated.  
  </apidoc:param>
      <apidoc:param name="property-names" type="xs:QName*" optional="false">
    The properties to remove.
  </apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:document-remove-properties(
         "example.xml", 
         (fn:QName("", "priority"),
          fn:QName("", "status")))
  =&gt; ()
</pre></apidoc:example>
    <algorithm xmlns="http://www.w3.org/1999/xhtml"></algorithm>
  </apidoc:function><apidoc:function name="document-set-property" type="builtin" lib="xdmp" category="UpdateBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc: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.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="uri" type="xs:string" optional="false">
    The document URI for the property setting.
  </apidoc:param>
      <apidoc:param name="prop" type="element()" optional="false">
    The property to set.
  </apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
xdmp:document-set-property(
  "http://marklogic.com/a/example.xml",
  &lt;priority xmlns="http://example.com"&gt;5&lt;/priority&gt;)
  
</pre></apidoc:example>
    <algorithm xmlns="http://www.w3.org/1999/xhtml"></algorithm>
  </apidoc:function><apidoc:function name="document-assign" type="builtin" lib="xdmp" category="UpdateBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Assign a document URI to a forest index,
  using the same algorithm as <code xmlns="http://www.w3.org/1999/xhtml">xdmp:document-insert</code>.
  The return value will be a positive integer
  from 1 to <code xmlns="http://www.w3.org/1999/xhtml">$forest-count</code>.

  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 <code xmlns="http://www.w3.org/1999/xhtml">xdmp:database-forests</code>.

  If the document already exists,
  this function may not return the correct forest for the document.
  In this case, <code xmlns="http://www.w3.org/1999/xhtml">xdmp:document-forest</code> will return the 
  correct forest.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="uri" type="xs:string" optional="false">
    The document URI to assign.
  </apidoc:param>
      <apidoc:param name="forest-count" type="xs:positiveInteger" optional="false">
    Specifies the number of forests from which this document
    may be assigned.
  </apidoc:param>
    </apidoc:params>
    <apidoc:return>xs:positiveInteger</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:document-assign("document-1.xml", 2)
   =&gt; 1
</pre></apidoc:example>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:document-assign("document-2.xml", 2)
   =&gt; 2
</pre></apidoc:example>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  let $forests := xdmp:database-forests(xdmp:database())
  let $index := xdmp:document-assign("document-1.xml", count($forests))
  return $forests[$index]
   =&gt; 17618760155059123769
</pre></apidoc:example>
  </apidoc:function></apidoc:module>