Returns a string representing the description of a given item sequence. If you take the output of the xdmp:describe function and evaluate it as an XQuery program, it returns the item(s) input to the function.

If you specify an item that is in a database, xdmp:describe returns the path to the item (or to the items if you specify multiple items). If the item or items are constructed in XQuery, then it prints out the item, truncating the characters in each item according to the maxItemLength parameter.

  xdmp:describe(current-date())

  => xs:date("2007-01-15-08:00")

  let $x := <mynode>Some text here.</mynode>
  return
  xdmp:describe($x)

  => <mynode>Some text here.</mynode>

  (:  assume mydoc.xml is an XML document with
      the following content:
      <mynode>Some text here.</mynode> :)
  xdmp:describe(doc("mydoc.xml")/mynode)

  => doc("mydoc.xml")/mynode

Returns the result of evaluating a string as an XQuery module.

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

You must have the http://marklogic.com/xdmp/privileges/xdmp-eval-in privilege to specify the <database> option with a database other than the context database.

You must have the http://marklogic.com/xdmp/privileges/xdmp-eval-modules-change (for xdmp:eval), http://marklogic.com/xdmp/privileges/xdmp-invoke-modules-change (for xdmp:invoke), or the http://marklogic.com/xdmp/privileges/xdmp-spawn-modules-change (for xdmp:spawn) privilege to change either the modules database to another database or to change the root to another path. You must have the http://marklogic.com/xdmp/privileges/xdmp-eval-modules-change-file (for xdmp:eval), http://marklogic.com/xdmp/privileges/xdmp-invoke-modules-change-file (for xdmp:invoke), or the http://marklogic.com/xdmp/privileges/xdmp-eval-modules-change-file (for xdmp:spawn) privilege to change the modules database to the file system or to change a root on the filesystem.

You must have the http://marklogic.com/xdmp/privileges/xdmp-login privilege to use the user-login option.

  xdmp:eval("1+1")
  => 2

xquery version "1.0-ml";
declare namespace my='http://mycompany.com/test'; 

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

=> hello world
  

  xdmp:eval("doc('/docs/mydoc.xml')",  (),
		  <options xmlns="xdmp:eval">
		    <database>{xdmp:database("otherdb")}</database>
		  </options>)
  => The '/docs/mydoc.xml' document from the
     otherdb database.

xdmp:eval('xdmp:get-current-user()', (), 
 <options xmlns="xdmp:eval">
  <user-id>{xdmp:user("someuser")}</user-id>
 </options>)
(:
  returns "someuser", assuming "someuser" exists in the
  security database and the user running the eval request has the 
  xdmp:login privilege.
:)

[DEPRECATED: use xdmp:eval with the database option instead] Returns the result of evaluating a string as an XQuery module in a given database.

  xdmp:eval-in("1+1",2348790529)
  => 2

xquery version "0.9-ml"
declare namespace my='http://mycompany.com/test' 

let $s := 
      "xquery version '0.9-ml'
       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 parameter to xdmp:eval :)
    xdmp:eval-in($s, 
                 xdmp:database("Documents"), 
		 (xs:QName("my:x"), 
		 "world"))

=> hello world
  

Returns the result of evaluating a module at the given path.

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

  xdmp:invoke("http://example.com/modules/foo.xqy")
  => 2

  This example invokes a module using external variables.
  
  Assume you have a module in the modules database with a URI
  "http://example.com/application/module.xqy" containing the
  following code:

  xquery version "1.0-ml";
  declare namespace my="my-namespace-uri";
  declare variable $my:var as xs:string external;
  xdmp:log($my:var)

  Then you can call this module using xdmp:invoke as follows:

  xquery version "1.0-ml";
  declare namespace my="my-namespace-uri";
  xdmp:invoke("module.xqy", 
        (xs:QName("my:var"), "log this to ErrorLog.txt"), 
        <options xmlns="xdmp:eval">
          <modules>{xdmp:modules-database()}</modules>
	  <root>http://example.com/application/</root>
         </options>)
	 
  => Invokes an XQuery module from the modules database 
     with the URI http://example.com/application/module.xqy.
     The invoked module will then be executed, logging the 
     message sent in the external variable to the log file. 

[DEPRECATED: use xdmp:invoke with the database option instead] Returns the result of evaluating a module at the given path.

  xdmp:invoke-in("http://example.com/modules/foo.xqy",2348790529)
  => 2

Returns the database id where the parameter is stored. If the specified node does not come from a document in a database, then xdmp:node-database returns an empty list.

  xdmp:node-database(doc("http://marklogic.com/document"))
   => 18384173956586417397

Returns the document-uri property of the parameter or its ancestor.

  xdmp:node-uri(doc("http://marklogic.com/document"))
   => "http://marklogic.com/document"

Returns a string whose value corresponds to the path of the node.

  let $arg := <a><b><c>ccc</c></b>
                <b>bbb</b></a>
  return xdmp:path($arg/b[1]/c)
  => "/a/b[1]/c"

Set the value of a variable to the specified expression. The xdmp:set command allows you to introduce changes to the state (side effects) of a query by changing the value of a variable to something other than what it is bound to.

When a variable is bound to a sequence in a for loop, and when that variable is changed by xdmp:set in the return clause, the change only affects the value for one iteration of the for loop at a time; when the next value is sent to the return clause, it is set to the next value in the sequence specified in the for clause. The value changes only after the xdmp:set call is made.

(: set the value of the variable $x 
   to 1234 and then print out $x :)

let $x := 12
return
(xdmp:set($x, 1234), $x)

=> 1234

(: set the value of the variable $x 
   to 5 and then print out $x for 
   each value of $y :)

for $x in (1, 2)
  for $y in ($x, $x)
return
($y, xdmp:set($x, 5), $x)

=> (1, 5, 1, 5, 2, 5, 2, 5)

(: note the effect on $z of changing the 
   value of $x :)

for $x in (1, 2)
  for $y in (3,4)
    for $z in ($x, $x)
return
($z, xdmp:set($x, 5))

=> (1, 1, 5, 5, 2, 2, 5, 5)

(: every time the name of the input node changes,
   output the new name  :)

let $n := ()
for $i in (<x>1</x>, <x>2</x>, <y>3</y>)
return (
   if (name($i) eq $n) 
   then () 
   else (xdmp:set($n, name($i)), $n)
  , data($i)
)

=> (x, 1, 2, y, 3)

Place the specified module on the task queue for evaluation.

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

The xdmp:spawn function places the specified XQuery module in the task queue to be processed. The module will be evaluated when the task server has the available resources to process it. The tasks are processed in the order in which they are added to the queue.

Once xdmp:spawn is called, it cannot be rolled back, even if the transaction from which it is called does not complete. Therefore, use care or preferably avoid calling xdmp:spawn from a module that is performing an update transaction. Once a module is spawned, its evaluation is completely asynchronous of the statement in which xdmp:spawn was called. Consequently, if you call xdmp:spawn from a module that is updating a document, and if the update ends up retrying (for example, if a deadlock is detected), then the entire module is re-evaluated and the xdmp:spawn call is therefore called again. This will only happen in update statements, not in query statements. For details on how transactions work in MarkLogic Server, see "Understanding Transactions in MarkLogic Server" in the Developer's Guide.

  xdmp:spawn("module.xqy", (), 
        <options xmlns="xdmp:eval">
          <modules>{xdmp:modules-database()}</modules>
	  <root>http://example.com/application/</root>
         </options>)
	 
  => Puts the module from the modules database with the 
     URI http://example.com/application/module.xqy 
     in the task server queue.

[DEPRECATED: use xdmp:spawn with the database option instead] Place the specified module on the task queue for evaluation. It will be evaluated in the given database.

The xdmp:spawn-in function places the specified XQuery module in the task queue to be processed. The module will be evaluated when the task server has the available resources to process it. The tasks are processed in the order in which they are added to the queue.

  xdmp:spawn-in("example.xqy",
                324398742983742,
                (),
                xdmp:modules-database(),
                "http://example.com/application/")
  => ()
  Puts the module from the modules database with the 
  URI http://example.com/application/module.xqy 
  in the task server queue. The module will be 
  executed in the context of the database with
  an ID of 324398742983742.

Evaluate a string as an XPath and return the corresponding node(s). Any value that is the result of xdmp:path is a valid input to xdmp:unpath. Any invalid inputs throw an XDMP-UNPATH exception. To evaluate non-XPath expressions, use xdmp:value.

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

  xdmp:unpath("/bookstore/book/title")
  => <title>Querying XML</title>
  

The following example shows how you can use xdmp:unpath and specify namespace bindings that are not in the current query scope.

xquery version "1.0-ml";

let $doc := <html xmlns="http://www.w3.org/1999/xhtml">
              <body><p>This is a document</p></body>
            </html>
let $namespaces:= ("xh", "http://www.w3.org/1999/xhtml")
let $xpath-str := "$doc/xh:body/xh:p"
return xdmp:with-namespaces($namespaces, xdmp:unpath($xpath-str))

=> <p xmlns="http://www.w3.org/1999/xhtml">This is a document</p>
  

The following example shows that xdmp:unpath will throw an error if the specified XPath expression would never be returned by xdmp:path.

  xdmp:unpath("/bookstore/book/title[@name eq 'Querying XML']")
  => throws the XDMP-UNPATH exception, because the specified 
     path expression would never be the output of xdmp:path.
  

Evaluate an expression in the context of the current evaluating statement. This differs from xdmp:eval in that xdmp:value preserves all of the context from the calling query, so you do not need to re-define namespaces, variables, and so on. Although the expression retains the context from the calling query, it is evaluated in its own transaction with same-statement isolation.

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

You can only evaluate expressions with xdmp:value; no prolog definitions (namespace declarations, function definitions, module imports, and so on) are allowed.

If the expression references something not in the context of either the calling query or the value expression, then an error is thrown. For example, the following throws an undefined variable exception:

xdmp:value("$y")

  let $var := 5 
  return
  xdmp:value("$var")
  => 5
  

xquery version "1.0-ml";

xdmp:document-insert("/test.xml",
 <root>
   <step1>this is step1</step1>
   <step2>this is step2</step2>
 </root>)
;

(: 
use xdmp:value to dynamically specify a step 
in an XPath expression
:)
for $x in ("step1", "step2")
return
/root/xdmp:value($x)

=>
<step1>this is step1</step1>
<step2>this is step2</step2>
  

Evaluates the expression in the context of a specific set of namespace bindings.

http://marklogic.com/xdmp/privileges/xdmp-with-namespaces

let $version := "1.2" return 
xdmp:with-namespaces(("p", fn:concat("http://marklogic.com/p/",$version)),
   <p:bar/>
)  

Returns:

   <p:bar xmlns:p="http://marklogic.com/p/1.2"/>
  

xdmp:with-namespaces(
   ('', 'x'),
   <test>
      <test1>hello</test1>
   </test>
=>
<test xmlns="x">
  <test1>hello</test1>
</test>

Returns the XQuery language version of the calling module. Currently supported XQuery versions are:

• "0.9-ml": The legacy MarkLogic XQuery version. This was the only XQuery version available on MarkLogic Server 3.2 and earlier. It is based on the May 2003 XQuery Draft Recommendation, with MarkLogic extensions
• "1.0-ml": XQuery version 1.0, with MarkLogic extensions. This is the preferred version of XQuery beginning with release 4.0.
• "1.0": Strict XQuery version 1.0. This XQuery version complies as closely as possible with the published XQuery 1.0 specification.

  xdmp:xquery-version()
   => "1.0-ml"

Executes an XSLT stylesheet against a node.

When creating the xsl:stylesheet element that is the stylesheet parameter to xdmp:xslt-eval, keep in mind that it has to first be parsed by XQuery before it is evaluated as a stylesheet. Therefore, any characters in the stylesheet that require escaping in XQuery must be escaped, otherwise you get an error in the XQuery. For example, if the stylesheet has any curly braces ( { or } ), you must escape the curly braces (with curly braces). For an example, see the example below.

When running an XSLT stylesheet in MarkLogic, you pass in a node on which the stylesheet operates. Many stylesheets are written to expect the initial node to be a document node. In other XSLT processors, the node you pass to the stylesheet is typically read in from the filesystem and is always treated as a document node. In MarkLogic, you often get the node to pass to the stylesheet as the result of a query or a search, and the node is not necessarily a document node. Therefore, if your stylesheet expects the context node to be a document node, make sure to pass in a document node and not an element node. If you pass in an element node to a stylesheet that has default template rules to expect a document node, then you might miss the processing on the element you passed in (because the stylesheet might expect the child node to be the root element of the XML document, but if you passed in the root element instead of its parent document node, then the child nodes would be the children of the root element, causing the root element to miss its default processing).

let $foo-to-bar :=
  <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                  version="2.0">
    <xsl:template match="foo">
      <bar>
        <xsl:apply-templates select="node()"/>
      </bar>
    </xsl:template>
    <xsl:template match="@*|node()">
      <xsl:copy>
        <xsl:apply-templates select="@*|node()"/>
      </xsl:copy>
    </xsl:template>
  </xsl:stylesheet>
return xdmp:xslt-eval($foo-to-bar,
  <stuff>
   <one/>
   <foo/>
   <two/>
   <foo><blah>42</blah></foo>
   <bar>22</bar>
  </stuff>)/element()

xquery version "1.0-ml" ;

(: Hello World example for xslt:eval, with a parameter :)

let $params := map:map()
let $_put := map:put(
                    $params,
                    xdmp:key-from-QName(fn:QName("foo", "pName")),
                    "Stephen")
let $_put := map:put(
                    $params,
                    xdmp:key-from-QName(fn:QName("bar", "bName")),
                    "Ron")
let $_put := map:put(
                    $params,
                    "cName",
                    "Dave")
return
  xdmp:xslt-eval(
    <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
      xmlns:f="foo" xmlns:b="bar"
      version="2.0">
    <xsl:param name="f:pName"/>
    <xsl:param name="b:bName"/>
    <xsl:param name="cName"/>
    <xsl:param name="greeting" select="'Hi there '"/>
    <xsl:template match="/">
       <output>
         <xsl:copy-of select="node"/>
         <greeting><xsl:value-of select="$greeting"/></greeting>
         <param><xsl:value-of select="$f:pName"/></param>
         <param><xsl:value-of select="$b:bName"/></param>
         <param><xsl:value-of select="$cName"/></param>
       </output>
    </xsl:template>
  </xsl:stylesheet>,
  document { <node>Hello World</node> },
  $params)
=>
<?xml version="1.0" encoding="ASCII"?>
<output xmlns:f="foo" xmlns:b="bar">
  <node>Hello World</node>
  <greeting>Hi there </greeting>
  <param>Stephen</param>
  <param>Ron</param>
  <param>Dave</param>
</output>

xquery version "1.0-ml" ;

(: example that passes in a QName for a mode :)
xdmp:xslt-eval(
    <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
     version="2.0">
    <xsl:template match="/">
       <output>this has no mode</output>
    </xsl:template>
    <xsl:template match="/" mode="my-mode">
      <debug>this has a mode</debug>
    </xsl:template>
  </xsl:stylesheet>, 
  document { <node>Hello World</node> },
  (),
  <options xmlns="xdmp:eval">
    <mode>{fn:QName("", "my-mode")}</mode>
  </options>)
=>
<?xml version="1.0" encoding="ASCII"?>
<debug>this has a mode</debug>

xquery version "1.0-ml";

(:
  Note the esacped curly braces ( {{ and }} on the name attribute
  of xsl:element), as the stylesheet must first be parsed by XQuery 
  before it is evaluated as a stylesheet.  If you do not escape
  the curly braces, the query throws the XQuery exception:
  [1.0-ml] XDMP-CONTEXT: (err:XPDY0002) Expression depends on the context 
           where none is defined
  That is because, without the escaped braces, XQuery tries to evaluate
  the expression in the name attribute, but there is no context for it.
:)
xdmp:xslt-eval(
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
      version="2.0">
    <xsl:template match="foo">
     <xsl:element name="{{name(.)}}"/>
    </xsl:template>
</xsl:stylesheet>
,
document{ <foo>something goes here</foo>} )
=>
<?xml version="1.0" encoding="ASCII"?>
<foo/>

Executes an XSLT stylesheet against a node.

When running an XSLT stylesheet in MarkLogic, you pass in a node on which the stylesheet operates. Many stylesheets are written to expect the initial node to be a document node. In other XSLT processors, the node you pass to the stylesheet is typically read in from the filesystem and is always treated as a document node. In MarkLogic, you often get the node to pass to the stylesheet as the result of a query or a search, and the node is not necessarily a document node. Therefore, if your stylesheet expects the context node to be a document node, make sure to pass in a document node and not an element node. If you pass in an element node to a stylesheet that has default template rules to expect a document node, then you might miss the processing on the element you passed in (because the stylesheet might expect the child node to be the root element of the XML document, but if you passed in the root element instead of its parent document node, then the child nodes would be the children of the root element, causing the root element to miss its default processing).

xquery version "1.0-ml";

(: 
this example requires a document named hello.xsl directly 
at the App Server root with the following content:

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                  version="2.0">
    <xsl:template match="/">
        <xsl:text>hello</xsl:text>
    </xsl:template>
</xsl:stylesheet>
:)
xdmp:xslt-invoke("/hello.xsl", document{ <foo/> })
=>
hello

xquery version "1.0-ml" ;

(: Hello World example for xslt:invoke, with a parameter.
   Assumes a stylesheet names params.xsl directly at
   the App Server root with the following content:
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
      xmlns:f="foo" xmlns:b="bar"
      version="2.0">
    <xsl:param name="f:pName"/>
    <xsl:param name="b:bName"/>
    <xsl:param name="cName"/>
    <xsl:param name="greeting" select="'Hi there '"/>
    <xsl:template match="/">
       <output>
         <xsl:copy-of select="node"/>
         <greeting><xsl:value-of select="$greeting"/></greeting>
         <param><xsl:value-of select="$f:pName"/></param>
         <param><xsl:value-of select="$b:bName"/></param>
         <param><xsl:value-of select="$cName"/></param>
       </output>
    </xsl:template>
  </xsl:stylesheet>
:)

let $params := map:map()
let $_put := map:put(
                    $params,
                    xdmp:key-from-QName(fn:QName("foo", "pName")),
                    "Stephen")
let $_put := map:put(
                    $params,
                    xdmp:key-from-QName(fn:QName("bar", "bName")),
                    "Ron")
let $_put := map:put(
                    $params,
                    "cName",
                    "Dave")
return
xdmp:xslt-invoke("/params.xsl",
    document { <node>Hello World</node> },
    $params)
=>
<?xml version="1.0" encoding="ASCII"?>
<output xmlns:f="foo" xmlns:b="bar">
  <node>Hello World</node>
  <greeting>Hi there </greeting>
  <param>Stephen</param>
  <param>Ron</param>
  <param>Dave</param>
</output>