MarkLogic Server
XQUERY API DOCUMENTATION
3.0
This page was generated
March 22, 2006
12:06 PM
XQuery Built-In and Modules Function Reference
 XQuery Built-In Functions
  AppServerBuiltins
   Extension
  SearchBuiltins
   UpdateBuiltins
   Security
   Document Conversion
   MathBuiltins
  XQuery Module Functions
  Security-sec
   Thesaurus
   Spell
   Triggers
   Content Processing Framework
   Links
   Domains
   Pipelines
   Generic Conversion
   MSWord Conversion
   Excel Conversion
   Powerpoint Conversion
   PDF Conversion
   DocBook Conversion
   CSS Conversion
   XHTML Conversion
  W3C XQuery Reference
  W3C XQuery Functions
   W3C XQuery Language

Built-In: Extension

The extension built-in functions are miscellaneous extensions to the XQuery core library, including functions for evaluating strings as XQuery expressions and functions to get information about documents in the database.
Function Summary
xdmp:access Returns whether a given action on the specified document URI would succeed.
xdmp:base64-decode Converts base64-encoded string to plaintext.
xdmp:base64-encode Converts plaintext into base64-encoded string.
xdmp:collection-locks Returns locks of documents in a collection.
xdmp:collection-properties Returns properties of documents in a collection.
xdmp:database Returns the the ID of the database named in the the argument.
xdmp:database-forests Returns a sequence of forest IDs in the specified database.
xdmp:database-name Return the name of the database with the given ID.
xdmp:databases Returns a sequence of the ids of all the databases in the system.
xdmp:describe Returns a string whose value corresponds to the description of a given item sequence.
xdmp:directory Returns the documents in a directory.
xdmp:directory-locks Returns locks of documents in a directory.
xdmp:directory-properties Returns properties of documents in a directory.
xdmp:document-forest Returns the forest ID of the forest in which the document with the specified URI is stored.
xdmp:document-get Returns the document in the XML file specified by $location.
xdmp:document-get-collections Returns the collections to which a given document belongs.
xdmp:document-get-properties Returns the property values for a document's property.
xdmp:document-get-quality Returns the quality of the specified document if the document exists.
xdmp:document-locks Returns the locks for one or more documents or directories.
xdmp:document-properties Returns a sequence of properties for the specified document(s).
xdmp:email Send an email in an XQuery program.
xdmp:estimate Returns the number of fragments selected by an expression.
xdmp:eval Returns the result of evaluating a string as an XQuery.
xdmp:eval-in Returns the result of evaluating a string as an XQuery in a given database.
xdmp:forest Returns the the ID of the forest specified as the argument.
xdmp:forest-databases Returns the database ID corresponding to the database to which the specified forest belongs.
xdmp:forest-name Return the name of the forest with the given id.
xdmp:forests Returns a sequence of the ids of all the forests in the system.
xdmp:get [DEPRECATED] Returns the document in the XML file specified by $path.
xdmp:hash32 Returns the 32-bit hash of a string.
xdmp:hash64 Returns the 64-bit hash of a string.
xdmp:hex-to-integer Parses a hexadecimal string, returning an integer.
xdmp:host Returns the the ID of the host named in the argument.
xdmp:host-name Returns the the name of the host ID specified as the argument.
xdmp:hosts Returns a sequence of the ids of all the hosts in the system.
xdmp:http-delete Sends an http DELETE request to the http server specified in the URI to delete the specified resource.
xdmp:http-get Sends the http GET method to the specified URI.
xdmp:http-head Sends the http HEAD method to the specified URI.
xdmp:http-post Sends the http POST request to the server.
xdmp:http-put Sends an HTTP PUT request to an HTTP server.
xdmp:integer-to-hex Returns a hexadecimal representation of an integer.
xdmp:integer-to-octal Returns an octal representation of an integer.
xdmp:invoke Returns the result of evaluating a module at the given path.
xdmp:invoke-in Returns the result of evaluating a module at the given path.
xdmp:log Logs a debug message to the log file <install_dir>/Logs/ErrorLog.
xdmp:modules-database Returns the database ID of the modules database.
xdmp:node-uri Returns the document-uri property of the argument or its ancestor.
xdmp:octal-to-integer Parses an octal string, returning an integer.
xdmp:path Returns a string whose value corresponds to the path of the node.
xdmp:platform Returns the platform upon which MarkLogic Server is running ("solaris", "winnt", or "linux").
xdmp:product-edition Returns the current Mark Logic product edition.
xdmp:query-meters Returns the current value of the resource meters for this query sequence.
xdmp:query-trace Enables or disables tracing of this query.
xdmp:quote Returns the unevaluated serialized representation of the input argument as a string.
xdmp:random Returns a random unsigned integer up to 64 bits long.
xdmp:request-key Returns the unique key of the current request.
xdmp:schema-database Returns the database ID of the schema database associated with the current database.
xdmp:security-database Returns the database ID of the security database associated with the current database.
xdmp:server Returns the the ID of the request server named in the argument.
xdmp:server-name Return the name of the request server with the given id.
xdmp:servers Returns a sequence of the ids of all the request servers in the system.
xdmp:set Set the value of a variable to the specified expression.
xdmp:spawn Place the specified module on the task queue for evaluation.
xdmp:spawn-in Place the specified module on the task queue for evaluation.
xdmp:strftime Formats a dateTime value using POSIX strftime.
xdmp:subbinary Returns a binary node made up of a subset of the given binary node.
xdmp:trace Signal a trace event.
xdmp:triggers-database Returns the database ID of the triggers database associated with the current database.
xdmp:unquote Parses a string as XML, returning a document node.
xdmp:uri-content-type Returns the content type of the given URI as matched in the mimetypes configuration.
xdmp:uri-format Returns the format of the given URI as matched in the mimetypes configuration.
xdmp:version Returns the current MarkLogic Server version.
Function Detail
xdmp:access(
$uri as xs:string,
$action as xs:string
)  as  xs:boolean
Summary:

Returns whether a given action on the specified document URI would succeed.

Parameters:
$uri : The document URI.
$action : The type of access: "create", "insert", "update", or "execute".

Example: 
  xdmp:access(
         "http://example.com/foo.xml",
         "create")
   => true()
xdmp:base64-decode(
$encoded as xs:string
)  as  xs:string
Summary:

Converts base64-encoded string to plaintext.

Parameters:
$encoded : Encoded text to be decoded.

Example: 
xdmp:base64-decode(
     "c2xpbmdzIGFuZCBhcnJvd3Mgb2Ygb3V0cmFnZW91cyBmb3J0dW5l")
=> slings and arrows of outrageous fortune
xdmp:base64-encode(
$plaintext as xs:string
)  as  xs:string
Summary:

Converts plaintext into base64-encoded string.

Parameters:
$plaintext : Plaintext to be encoded.

Example: 
  xdmp:base64-encode("slings and arrows of outrageous fortune")
   => c2xpbmdzIGFuZCBhcnJvd3Mgb2Ygb3V0cmFnZW91cyBmb3J0dW5l
xdmp:collection-locks(
$uri as xs:string*
)  as  element(lock:lock)*
Summary:

Returns locks of documents in a collection.

Parameters:
$uri : The input URI.

Example: 
  for $d in xdmp:collection-locks(
                     ("http://example.com/col1/",
                      "http://example.com/col2/"))
  return base-uri($d)
  => http://example.com/bar.xml 
     http://example.com/baz.xml
xdmp:collection-properties(
$uri as xs:string*
)  as  element(prop:properties)*
Summary:

Returns properties of documents in a collection.

Parameters:
$uri : The input URI.

Example: 
  for $d in xdmp:collection-properties(
                   ("http://example.com/col1/",
                    "http://example.com/col2/"))
  return base-uri($d)
  => http://example.com/bar.xml http://example.com/baz.xml
xdmp:database(
[$name as xs:string]
)  as  xs:unsignedLong
Summary:

Returns the the ID of the database named in the the argument. Returns the ID of the current database if no argument is given.

Parameters:
$name (optional): The name of the database. The default value is the name of the current database.

Example: 
  xdmp:database("myDB")
  => 74495681647284736476
xdmp:database-forests(
$database as xs:unsignedLong
)  as  xs:unsignedLong*
Summary:

Returns a sequence of forest IDs in the specified database.

Parameters:
$database : A database ID.

Example: 
  xdmp:database-forests(xdmp:database("Documents"))
  => (8456374036761185098, 10615125154705099114)
xdmp:database-name(
$id as xs:unsignedLong
)  as  xs:string
Summary:

Return the name of the database with the given ID.

Parameters:
$id : A database ID.

Example: 
xdmp:database-name(8456374036761185098)
=> "Documents"
xdmp:databases( ) as xs:unsignedLong*
Summary:

Returns a sequence of the ids of all the databases in the system.

Example: 
  xdmp:databases()
   => (14389140626518478220,
          8456374036761185098,
	  10615125154705099114)
xdmp:describe(
$item as item()*,
[$maxLength as xs:unsignedInt]
)  as  xs:string
Summary:

Returns a string whose value corresponds to the description of a given item sequence.

Parameters:
$item : The item sequence whose description is returned.
$maxLength (optional): Represents the number of elements in the sequence to print. Default: 3

Example: 
  xdmp:describe(current-date())
  => xs:date("2003-04-15-08:00")
xdmp:directory(
$uri as xs:string*,
[$depth as xs:string]
)  as  element()*
Summary:

Returns the documents in a directory.

Parameters:
$uri : The input URI.
$depth (optional): "1" for immediate children, "infinity" for all. If not supplied, depth is "1".

Example: 
  for $d in xdmp:directory("http://example.com/foo/","1")
  return base-uri($d)
  => http://example.com/foo/bar.xml 
     http://example.com/foo/baz.xml
xdmp:directory-locks(
$uri as xs:string*,
[$depth as xs:string]
)  as  element(lock:lock)*
Summary:

Returns locks of documents in a directory.

Parameters:
$uri : The input URI.
$depth (optional): "1" for immediate children, "infinity" for all. If not supplied, depth is "1".

Example: 
  for $d in xdmp:directory-locks("http://example.com/foo/","1")
  return base-uri($d)
  => http://example.com/foo/bar.xml 
     http://example.com/foo/baz.xml
xdmp:directory-properties(
$uri as xs:string,
[$depth as xs:string]
)  as  element(prop:properties)*
Summary:

Returns properties of documents in a directory.

Parameters:
$uri : The input URI.
$depth (optional): "1" for immediate children, "infinity" for all children. If not supplied, depth is "1".

Example: 
  xdmp:directory-properties("http://example.com/dir/","1")
  => <prop:properties 
            xmlns:prop="http://marklogic.com/xdmp/property">
         <prop:directory/>
     </prop:properties>

The properties document returned has one directory element, indicating that there is a single directory that is an immediate child of the specified directory.
xdmp:document-forest(
$uri as xs:string
)  as  xs:integer?
Summary:

Returns the forest ID of the forest in which the document with the specified URI is stored. Otherwise, returns the empty sequence.

Parameters:
$uri : The URI of the document.

Example: 
  xdmp:document-forest("example.xml")
  => 12972338785465832200
xdmp:document-get(
$location as xs:string,
[$options as node()]
)  as  node()
Summary:

Returns the document in the XML file specified by $location.

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. 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 getting this document. The default value is (). The node for the xdmp:document-get options must be in the xdmp:document-get namespace. This parameter can also include option elements in the xdmp:http namespace for the HTTP parameters.

The xdmp:document-get options include:

<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. 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.

<lang>

A value of "en" specifies that the document is in english.

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 console.

If neither "repair" option is specified, malformed XML content will be repaired.
Example: 
  xdmp:document-get("myDocument.xml")
  => the xml contained in myDocument.xml, 
        for example, <myDocument/>
Example: 
  xdmp:document-get("myDocument.html", 
       <options xmlns="xdmp:document-get">
           <repair>full</repair>
       </options>)
  => myDocument.html as an XML document that has gone 
     through any needed tag repair
Example: 
  xdmp:document-get("http://myCompany.com/file.xml", 
       <options xmlns="xdmp:document-get"
                xmlns:http="xdmp:http">
           <format>xml</format>
           <http:authentication>
	      <username>user</username>
	      <password>pass</pass>
	   </http:authentication>
       </options>)
  => gets an XML document named file.xml, sending the 
     authentication credentials user/pass to the 
     http://myCompany.com server
xdmp:document-get-collections(
$uri as xs:string
)  as  xs:string*
Summary:

Returns the collections to which a given document belongs.

Parameters:
$uri : The document URI.

Example: 
  xdmp:document-get-collections("chapter5.xml")
  =>("http://marklogic.com/all-books", 
        "http://marklogic.com/xml-books")
xdmp:document-get-properties(
$uri as xs:string,
$property as xs:QName
)  as  element()*
Summary:

Returns the property values for a document's property.

Parameters:
$uri : The document URI.
$property : The property name. This is the QName of the top-level property element in the specified properties document.

Example: 
  xdmp:document-get-properties(
         "http://example.com/foo.xml",
         expanded-QName("http://examples.com/","priority"))
   => <priority xmlns="http://examples.com/">5</priority>
xdmp:document-get-quality(
$uri as xs:string
)  as  xs:integer?
Summary:

Returns the quality of the specified document if the document exists. Otherwise, returns the empty sequence.

Parameters:
$uri : The URI of the document in question.

Example: 
  xdmp:document-get-quality("example.xml")
  => 10
xdmp:document-locks(
[$uri as xs:string*]
)  as  element(lock:lock)*
Summary:

Returns the locks for one or more documents or directories. Returns the locks for all documents and directories in the database if no argument is given.

Parameters:
$uri (optional): A document URI.

Example: 
  xdmp:document-locks("example.xml")
  => <lock:lock>
          <lock:active-locks>
            <lock:active-lock>
              <lock:lock-type>write</lock:lockt-ype>
              <lock:lock-scope>exclusive</lock:lock-scope>
              <lock:depth>infinity</lock:depth>
              <lock:owner>
                http://example.com/~user
              </lock:owner>
              <lock:timeout>5000</lock:timeout>
              <lock:lock-token>
                  http://marklogic.com/xdmp/locks/e71d4fae
              </lock:lock-token>
              <lock:timestamp>5234768</lock:timestamp>
              <sec:user-id>52378234768</sec:user-id>
            </lock:active-lock>
          </lock:active-locks>
        </lock:lock>
xdmp:document-properties(
[$uri as xs:string*]
)  as  element(prop:properties)*
Summary:

Returns a sequence of properties for the specified document(s). If no documents are specified, returns the properties for all documents in the database that contain properties.

Parameters:
$uri (optional): A sequence of document URIs.

Example: 
  xdmp:document-properties()
    => 
    <prop:properties 
          xmlns:prop="http://marklogic.com/xdmp/property">
    Property Node1
    </prop:properties>
    <prop:properties 
          xmlns:prop="http://marklogic.com/xdmp/property">
    Property Node2
    </prop:properties>
    <prop:properties 
          xmlns:prop="http://marklogic.com/xdmp/property">
    Property NodeN
    </prop:properties>
xdmp:email(
$message as node()
)  as  empty()
Summary:

Send an email in an XQuery program. A valid SMTP Relay must be configured in the Groups page of the Admin console for the email to be sent. The format of the email message must be an XML file that complies with the schema files listed below.

Parameters:
$message : An XML representation of an email message to send. The message must comply with the XML schemas defined in the following schema files:
  • install_dir/Config/email-xml.xsd
  • install_dir/Config/rfc822.xsd
where install_dir is the directory in which MarkLogic Server is installed.

Required Privilege:

http://marklogic.com/xdmp/privileges/xdmp-email

Example: 
This example demonstrates sending a message with 
HTML content.
   
xdmp:email(
<em:Message 
 xmlns:em="URN:ietf:params:email-xml:" 
 xmlns:rf="URN:ietf:params:rfc822:">
  <rf:subject>Sample HTML Email</rf:subject>
  <rf:from>
    <em:Address>
      <em:name>Mark Logic</em:name>
      <em:adrs>marklogic@yourdomain</em:adrs>
    </em:Address>
  </rf:from>
  <rf:to>
    <em:Address>
      <em:name>System Administrator</em:name>
      <em:adrs>admin@yourdomain</em:adrs>
    </em:Address>
  </rf:to>
  <em:content>
    <html xmlns="http://www.w3.org/1999/xhtml"> 
      <head>
        <title>Test HTML message</title>
      </head>
      <body>
        <h1>Test HTML message</h1>
        <p>Here is a simple paragraph</p>
      </body> 
    </html>
  </em:content>
</em:Message>)
Example: 
This example demonstrate sending a message with 
plain text content. 

xdmp:email(
<em:Message 
 xmlns:em="URN:ietf:params:email-xml:" 
 xmlns:rf="URN:ietf:params:rfc822:">
  <rf:subject>Sample Plain Text Email</rf:subject>
  <rf:from>
    <em:Address>
      <em:name>Mark Logic</em:name>
      <em:adrs>marklogic@yourdomain</em:adrs>
    </em:Address>
  </rf:from>
  <rf:to>
    <em:Address>
      <em:name>System Administrator</em:name>
      <em:adrs>admin@yourdomain</em:adrs>
    </em:Address>
  </rf:to>
  <em:content xml:space="preserve">
This is a sample email with a plain text body.
</em:content>
</em:Message>)
xdmp:estimate(
$expression as item()*
)  as  xs:integer
Summary:

Returns the number of fragments selected by an expression. This can be used as a fast estimate of the number of items in a sequence.

Parameters:
$expression : An expression to estimate. This must be a partially searchable XPath expression or a cts:search() expression.

Usage Notes:

Queries that use xdmp:estimate require that the XPath expression searched is partially searchable. A partially searchable XPath expression is one whose first step is searchable. You can use xdmp:query-trace() to determine if a step is searchable. If there are no entries in the xdmp:query-trace() output indicating that the first step is unsearchable, then the expression is partially searchable and you can perform an xdmp:estimate operation on it.

Example: 
  xdmp:estimate(input())
   => 10476
xdmp:eval(
$xquery as xs:string,
[$vars as item()*],
[$modules as xs:unsignedLong],
[$root as xs:string]
)  as  item()*
Summary:

Returns the result of evaluating a string as an XQuery.

Parameters:
$xquery : The XQuery string to be evaluated. If the XQuery string contains double quotes ("), surround the string with single quotes (').
$vars (optional): The external variable values for this evaluation. This must be a sequence of even length, alternating QNames and items. Each QName and item pair specify a variable name and value.
$modules (optional): The modules database for processing module imports.
$root (optional): The root path for limiting module imports. Because the root path must be non-empty, the value must be a non-empty string; it cannot be an empty string ( "" ) or an error is raised.

Example: 
  xdmp:eval("1+1")
  => 2
Example: 
declare namespace my='http://mycompany.com/test' 

let $s := 
      "declare namespace my='http://mycompany.com/test' 
       define variable $my:x as xs:string external
       concat('hello ', $my:x)"
return 
    (: evaluate the query string $s using the variables 
       supplied as the second argument to xdmp:eval :)
    xdmp:eval($s, (xs:QName("my:x"), "world"))

=> hello world
xdmp:eval-in(
$xquery as xs:string,
$ID as xs:unsignedLong,
[$vars as item()*],
[$modules as xs:unsignedLong],
[$root as xs:string]
)  as  item()*
Summary:

Returns the result of evaluating a string as an XQuery in a given database.

Parameters:
$xquery : The XQuery string to be evaluated. If the XQuery string contains double quotes ("), surround the string with single quotes (').
$ID : The database ID, from xdmp:database("db_name"), xdmp:security-database(), or xdmp:schema-database().
$vars (optional): The external variable values for this evaluation. This must be a sequence of even length, alternating QNames and items. Each QName and item pair specify a variable name and value.
$modules (optional): The modules database for pr