| XQUERY/XSLT API DOCUMENTATION 4.2 |
All XQuery & XSLT Functions MarkLogic Built-In Functions Admin (xdmp:) AppServer (xdmp:) Classifier (cts:) Debug (dbg:) Document Conversion (xdmp:) Extension (xdmp:) Documents, Directories, Properties, and Locks Functions Extension Functions Function Values Functions HTTP Functions JSON Functions MarkLogic Server Functions Search Functions XML Functions XQuery Context Functions XSLT Functions map (map:) Math (math:) Profile (prof:) Search (cts:) cts:query Constructors Functions Geospatial Functions Geospatial Lexicon Functions Lexicon Functions Search Functions Search Clustering Functions Security (xdmp:) Server Monitoring (xdmp:) Spell (spell:) Update (xdmp:) XQuery Library Modules Admin Library (admin:) Actions Functions Appserver Functions Database Functions Forest Functions Group Functions Host Functions Mimetypes Functions Scheduler Functions Alerting (alert:) Elastic Compute Cloud (ec2:) Entity Enrichment (entity:) Flexible Replication (flexrep:) Geospatial Supporting Functions GEO Functions GeoRSS Functions GML Functions KML Functions MCGM Functions Information Studio (info:) Information Studio Developer (infodev:) Library Services (dls:) cts:query Constructor Functions Document Management Functions Document Update Functions Retention Policy Functions XInclude Functions Modular Documents XInclude Functions XPointer Functions PKI (pki:) Plugin (plugin:) Search (search:) Security-sec (sec:) Spelling Dictionary Management (spell:) Thesaurus (thsr:) Triggers (trgr:) Triggers Library (trgr:) WordProcessingML (ooxml:) ZIP Package (ooxml:) CPF Functions Content Processing Framework (cpf:) CSS Conversion (css:) DocBook Conversion (dbk:) Domains (dom:) Excel Conversion (excel:) Generic Conversion (cvt:) Links (lnk:) MSWord Conversion (msword:) PDF Conversion (pdf:) Pipelines (p:) Powerpoint Conversion (ppt:) XHTML Conversion (xhtml:) W3C-Standard Functions Accessor (fn:) AnyURI (fn:) Boolean (fn:) Context (fn:) DurationDateTime (fn:) Error and Trace (fn:) Node (fn:) Numeric (fn:) QName (fn:) Sequence (fn:) String (fn:) XSLT (fn:) W3C XQuery/XSLT Reference W3C XQuery Functions W3C XQuery Language W3C XSLT Language
This page was generated September 12, 2012 5:59 AM | XQuery & XSLT Built-In & Modules Function Reference
Built-In: Extension - XQuery Context Functions
The XQuery Context functions are XQuery extensions that allow you to start a new query context, manipulate the current context, or get information about the current context.
Function Summary
xdmp:describe | Returns a string representing the description of a given item sequence.
xdmp:eval | Returns the result of evaluating a string as an XQuery module.
xdmp:eval-in | [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:invoke | Returns the result of evaluating a module at the given path.
xdmp:invoke-in | [DEPRECATED: use xdmp:invoke with the database option instead] Returns the result of evaluating a module at the given path.
xdmp:node-database | Returns the database id where the parameter is stored.
xdmp:node-uri | Returns the document-uri property of the parameter or its ancestor.
xdmp:path | Returns a string whose value corresponds to the path of the node.
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 | [DEPRECATED: use xdmp:spawn with the database option instead] Place the specified module on the task queue for evaluation.
xdmp:unpath | Evaluate a string as an XPath and return the corresponding node(s).
xdmp:value | Evaluate an expression in the context of the current evaluating statement.
xdmp:with-namespaces | Evaluates the expression in the context of a specific set of namespace bindings.
xdmp:xquery-version | Returns the XQuery language version of the calling module.
xdmp:xslt-eval | Executes an XSLT stylesheet against a node.
xdmp:xslt-invoke | Executes an XSLT stylesheet against a node.
Function Detail
xdmp:describe(
| $item as item()*,
| [$maxSequenceLength as xs:unsignedInt?],
| [$maxItemLength as xs:unsignedInt*]
) as xs:string
Summary: 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.
Parameters:
$item : The item sequence whose description is returned.
$maxSequenceLength (optional): Represents the maximum number of items per sequence to print. The default is 3. () means no maximum.
$maxItemLength (optional): Represents the maximum number of characters per item to print. The default is 64. The minimum is 8. () means no limit.
Usage Notes: 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.
Example:
      xdmp:describe(current-date())

      => xs:date("2007-01-15-08:00")
Example:
      let $x := <mynode>Some text here.</mynode>
      return
      xdmp:describe($x)

      => <mynode>Some text here.</mynode>
Example:
      (:  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
xdmp:eval(
| $xquery as xs:string,
| [$vars as item()*],
| [$options as node()?]
) as item()*
Summary: Returns the result of evaluating a string as an XQuery module.
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.
$options (optional): The options node. The default value is (). The node for the `xdmp:eval` options must be in the `xdmp:eval` namespace. The following is a sample options node:
        <options xmlns="xdmp:eval">
          <isolation>different-transaction</isolation>
          <prevent-deadlocks>true</prevent-deadlocks>
        </options>
The `xdmp:eval` options include: <database> The database ID, from `xdmp:database("db_name")`, `xdmp:security-database()`, or `xdmp:schema-database()`. To specify a database other than the context database, the `http://marklogic.com/xdmp/privileges/xdmp-eval-in` privilege is required. <modules> The modules database ID for processing module imports. Specifying no `<modules>` element in the options node specifies the current modules database. Specifying `0` specifies using the file system to process module imports. 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. <root> The root path for modules. Specifying no `<root>` element in the options node specifies the current root. You need the same privileges to modify the root as you need to change the `module` option. <timestamp> The system timestamp to use for this evaluation. Specifying no `<timestamp>` element in the options node specifies the most recent timestamp. You may only specify a timestamp for a query statement, not for an update statement. The timestamp is a number that is incremented by 1 each time any configuration or content change is made to the system. Specifying a timestamp of 0 uses the current system timestamp (the value returned by `xdmp:request-timestamp()`). Specifying a timestamp requires the `xdmp:timestamp` execute privilege. <isolation> (Only valid with `xdmp:eval` or `xdmp:invoke`; does not apply to `xdmp:spawn`.) Either `same-statement` or `different-transaction`. When set to `same-statement`, the statement is evaluated in the same transaction as the one from which it is called, and subsequent expressions in the calling statement will not see any updates performed in the eval/invoke/spawn. You can only use `same-statement` isolation with update statements; query statements with `same-statement` isolation will throw an exception. When set to `different-transaction`, the statement is evaluated in a separate transaction from the one in which it is called, making those updates available to subsequent expressions in the calling statement (assuming the calling statement is an update statement; if the calling statement is not an update, then subsequent expressions will see the version of the database at the system timestamp when the calling statement begins its evaluation). When using `different-transaction` in an update statement that calls another update statement, do not update the same document as the calling statement is updating; doing so can cause a deadlock. You cannot evaluate a statement in a different database with the `isolation` option set to `same-statement`. The default value for the `isolation` option is `different-transaction`. For more details, see the "Understanding Transactions in MarkLogic Server" chapter of the Developer's Guide. <prevent-deadlocks> (Only valid with `xdmp:eval` or `xdmp:invoke`; does not apply to `xdmp:spawn`.) Specify `true` for the server to disallow update requests from an update transaction. Only has an effect when the `isolation` option is set to `different-transaction` as there is no possibility of a deadlock if the `isolation` option is set to `same-statement`. When set to `true` in an update request calling another update request, MarkLogic Server throws the `XDMP-PREVENTDEADLOCKS` exception. Setting this option to `true` prevents the possibility of deadlocks occurring when running eval/invoke of an update transaction from another update transaction. The default value for the `prevent-deadlocks` option is `false`. <default-xquery-version> The default XQuery language version to use for the query, if the query does not contain an explicit version declaration. If this option is not provided, the defaults are: `xdmp:eval`: The XQuery language version of the module that called eval. This version may vary module-by-module if a query consists of modules written in multiple language versions. It may also vary from run to run if the app-server default is changed. `xdmp:invoke`: The default XQuery version for the app server that the invocation occurs on. Note that this may be different than the XQuery version of the module that calls `xdmp:invoke`. `xdmp:spawn`: The XQuery version default set on the app server that called `xdmp:spawn`. The Task Server has no default XQuery version, the version to use is passed as a part of the task request. Allowable values for this option are "0.9-ml", "1.0-ml", "1.0" and the special value "app-server". The first three are XQuery language versions. The last indicates that the default XQuery language version set on this app-server should be used. This is useful if code written in an older XQuery version needs to call `xdmp:eval` on strings that may have been passed as parameters, but should be interpreted in the app-server's default language version. A module may discover its own XQuery language version with `xdmp:xquery-version`. <time-limit> Override the default time limit with this time limit, in seconds, for this evaluation. You can set the value up to the maximum-time-limit value for the App Server in which the request is evaluated or to a lower value than the default time limit. This option only applies to `xdmp:spawn`, not to `xdmp:invoke` or `xdmp:eval`. <user-id> Specifies the user ID for the user to run the request being evaluated (the request specified in the `$xquery` parameter). If no `user-id` is specified, then the request is run as the current user. You need to have the `xdmp:login` (`http://marklogic.com/xdmp/privileges/xdmp-login`) privilege to use the `user-id` option. Be aware that this is a very privileged operation, as it allows a user with this privilege to evaluate requests as any other user. For an example, see the fourth example below. <default-collation> Specifies the collation to use for this context, unless a collation is explicitly specified in the XQuery prolog or in a function call that allows you to specify a collation.
Required Privilege: `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.
Example:
      xdmp:eval("1+1")
      => 2
Example:
    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
Example:
      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.
Example:
    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.
    :)
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: [DEPRECATED: use `xdmp:eval` with the database option instead] Returns the result of evaluating a string as an XQuery module 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 processing module imports. The empty sequence specifies the current modules database.
$root (optional): The root path for modules. The empty sequence specifies the current root.
Example:
      xdmp:eval-in("1+1",2348790529)
      => 2
Example:
    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
xdmp:invoke(
| $path as xs:string,
| [$vars as item()*],
| [$options as node()?]
) as item()*
Summary: Returns the result of evaluating a module at the given path.
Parameters:
$path : The path of the module to be executed. The path is resolved against the root of the App Server evaluating the query, the Modules directory, or relative to the calling module. For details on resolving paths, see "Importing XQuery Modules and Resolving Paths" in the Application Developer's Guide.
$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.
$options (optional): The options node. The default value is (). The node must be in the `xdmp:eval` namespace. See the `xdmp:eval` section for a list of options.
Required Privilege: `http://marklogic.com/xdmp/privileges/xdmp-invoke`
Example:
      xdmp:invoke("http://example.com/modules/foo.xqy")
      => 2
Example:
      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.
xdmp:invoke-in(
| $uri as xs:string,
| $ID as xs:unsignedLong,
| [$vars as item()*],
| [$modules as xs:unsignedLong?],
| [$root as xs:string?]
) as item()*
Summary: [DEPRECATED: use `xdmp:invoke` with the database option instead] Returns the result of evaluating a module at the given path.
Parameters:
$uri : The path of the module to be executed. The path is resolved against the root of the App Server evaluating the query. The path must resolve to a main module (not a library module).
$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 containing the module to invoke. The empty sequence specifies the current modules database.
$root (optional): The root path for modules. The empty sequence specifies the current root.
Example:
      xdmp:invoke-in("http://example.com/modules/foo.xqy",2348790529)
      => 2
xdmp:node-database(
| $node as node()
) as xs:unsignedLong?
Summary: 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.
Parameters:
$node : The node whose database is returned.
Example:
      xdmp:node-database(doc("http://marklogic.com/document"))
       => 18384173956586417397
xdmp:node-uri(
| $node as node()
) as xs:string?
Summary: Returns the document-uri property of the parameter or its ancestor.
Parameters:
$node : The node whose URI is returned.
Example:
      xdmp:node-uri(doc("http://marklogic.com/document"))
       => "http://marklogic.com/document"
xdmp:path(
| $node as node(),
| [$include-document as xs:boolean?]
) as xs:string
Summary: Returns a string whose value corresponds to the path of the node.
Parameters:
$node : The node whose path is returned.
$include-document (optional): If true, then the path is presented with a leading `doc(..)/..`, otherwise the path is presented as `/..`.
Example:
      let $arg := <a><b><c>ccc</c></b>
                    <b>bbb</b></a>
      return xdmp:path($arg/b[1]/c)
      => "/a/b[1]/c"
xdmp:set(
| $variable as item()*,
| $expr as item()*
) as empty-sequence()
Summary: 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.
Parameters:
$variable : A variable to set.
$expr : A value to set the variable.
Usage Notes: 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.
Example:
    (: set the value of the variable $x
       to 1234 and then print out $x :)

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

    => 1234
Example:
    (: 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)
Example:
    (: 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)
Example:
    (: 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)
xdmp:spawn(
| $path as xs:string,
| [$vars as item()*],
| [$options as node()?]
) as empty-sequence()
Summary: Place the specified module on the task queue for evaluation.
Parameters:
$path : The path, relative to the specified root, of the module to be executed. For more details on resolving paths, see "Importing XQuery Modules and Resolving Paths" in the Application Developer's Guide.
$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.
$options (optional): The options node. The default value is (). The node must be in the `xdmp:eval` namespace. See the `xdmp:eval` section for a list of options.
Required Privilege: `http://marklogic.com/xdmp/privileges/xdmp-spawn`
Usage Notes: 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.
Example:
      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.
xdmp:spawn-in(
| $path as xs:string,
| $ID as xs:unsignedLong,
| [$vars as item()*],
| [$modules as xs:unsignedLong?],
| [$root as xs:string?]
) as empty-sequence()
Summary: [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.
Parameters:
$path : The path, relative to the specified root, of the module to be executed.
$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 that contains the module to invoke. The empty sequence specifies the current modules database.
$root (optional): The root path for modules. The empty sequence specifies the current root.
Usage Notes: 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.
Example:
      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.
xdmp:unpath(
| $expr as xs:string
) as item()*
Summary: 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`.
Parameters:
$expr : The XPath expression string to evaluate. The XPath expression must be of the form returned by `xdmp:path`.
Required Privilege: `http://marklogic.com/xdmp/privileges/xdmp-value`
Example:
      xdmp:unpath("/bookstore/book/title")
      => <title>Querying XML</title>
Example: 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>
Example: 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.
xdmp:value(
| $expr as xs:string
) as item()*
Summary: 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.
Parameters:
$expr : The string representing an expression to evaluate.
Required Privilege: `http://marklogic.com/xdmp/privileges/xdmp-value`
Usage Notes: 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")
Example:
      let $var := 5
      return
      xdmp:value("$var")
      => 5
Example:
    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>
xdmp:with-namespaces(
| $nsbindings as xs:string*,
| $expr as item()*
) as item()*
Summary: Evaluates the expression in the context of a specific set of namespace bindings.
Parameters:
$nsbindings : An alternating sequence of prefixes and URIs. Each prefix is bound to the following URI. If the prefix is the empty string, the following URI becaomes the default namespace of the resulting item(s).
$expr : An expression to evaluate in the context of the given namespace bindings.
Required Privilege: `http://marklogic.com/xdmp/privileges/xdmp-with-namespaces`
Example:
    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"/>
Example:
    xdmp:with-namespaces(
       ('', 'x'),
       <test>
          <test1>hello</test1>
       </test>
    =>
    <test xmlns="x">
      <test1>hello</test1>
    </test>
xdmp:xquery-version( ) as xs:string
Summary: 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.
Example:
      xdmp:xquery-version()
       => "1.0-ml"
xdmp:xslt-eval(
| $stylesheet as element(),
| $input as node()?,
| [$params as map:map?],
| [$options as node()?]
) as document-node()*
Summary: Executes an XSLT stylesheet against a node.
Parameters:
$stylesheet : The stylesheet to be executed.
$input : The context node to which the stylesheet is applied.
$params (optional): The stylesheet parameter values for this evaluation. Each key in the map is a string representing the name of the parameter in Clark notation: "{namespaceURI}localname". The function xdmp:key-from-QName is a convenient way to generate these keys. Each entry in the map is the value of the corresponding parameter.
$options (optional): The options node. The default value is (). The node must be in the `xdmp:eval` namespace. See the `xdmp:eval` section for a list of options. Additional options include: <mode> A QName specifying the initial stylesheet mode to use (the `<xsl:template>` with the specified `mode` attribute). <template> A QName specifying the name of the initial template to apply.
Usage Notes: 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).
Example:
    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()
Example:
    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>
Example:
    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>
Example:
    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/>
xdmp:xslt-invoke(
| $path as xs:string,
| $input as node()?,
| [$params as map:map?],
| [$options as node()?]
) as document-node()*
Summary: Executes an XSLT stylesheet against a node.
Parameters:
$path : The path of the stylesheet to be executed. The path is resolved against the root of the App Server evaluating the query, the Modules directory, or relative to the calling module. For details on resolving paths, see "Importing XQuery Modules and Resolving Paths" in the Application Developer's Guide.
$input : The context node to which the stylesheet is applied.
$params (optional): The stylesheet parameter values for this evaluation. Each key in the map is a string representing the name of the parameter in Clark notation: "{namespaceURI}localname". The function xdmp:key-from-QName is a convenient way to generate these keys. Each entry in the map is the value of the corresponding parameter.
$options (optional): The options node. The default value is (). The node must be in the `xdmp:eval` namespace. See the `xdmp:eval` section for a list of options. Additional options include: <mode> A QName specifying the initial stylesheet mode to use (the `<xsl:template>` with the specified `mode` attribute). <template> A QName specifying the name of the initial template to apply. <encoding> Specifies the encoding to use when reading the stylesheet into MarkLogic Server. Supported values include `UTF-8`, `ISO-8859-1`, as well as many other popular encodings. See the Search Developer's Guide for a list of character set encodings by language. All encodings will be translated into UTF-8 from the specified encoding. The string specifed for the `encoding` option will be matched to an encoding name according to the Unicode Charset Alias Matching rules (http://www.unicode.org/reports/tr22/#Charset_Alias_Matching). An automatic encoding detector will be used if the value `auto` is specified. If no encoding can be detected, the encoding defaults to UTF-8.
Usage Notes: 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).
Example:
    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
Example:
    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>

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