JavaScript xdmp.eval

MarkLogic 9 Product Documentation
xdmp:eval

xdmp:eval(
   $xquery as xs:string,
   [$vars as item()* | map:map],
   [$options as (element()|map:map)?]
) as item()*

Summary

Returns the result of evaluating a string as an XQuery module. To evaluate JavaScript, see xdmp:javascript-eval.

Parameters
$xquery A string containing the XQuery code to be evaluated. If the string contains double quotes ("), surround the string with single quotes (').
$vars External variable values to make available to the evaluated code, expressed as either a sequence of alternating QName-value pairs, or a map:map. If you use a sequence, it must contain alternating variable QNames and values. e.g. (xs:QName("var1"), "val1", xs:Qname("var2"), "val2"). If you use a map, then each key is a string representing the Clark notation of the variable QName ("{namespaceURI}localname"), and its value is the corresponding variable value. You can use xdmp:key-from-QName to generate the Clark notation to use as a key.
options Options with which to customize this operation. You can specify options as either an options XML element in the namespace "xdmp:eval", or as a map:map. The option names below are XML localnames. When using a map, replace any hyphens in an option name with camel casing. For example, "an-option" becomes "anOption" when used as a map:map entry key. This function supports the following options:
database
The id of the content database. You can use functions such as xdmp:database to get a database ID. See the Usage Notes for more details. Use of this option to specify a database other than the context database requires additional privileges. For details, see Required Privileges, below.
modules
The ID of the modules database to use for resolving module imports. If you do not specify a modules option, this operation uses the current modules database. Use a value of 0 to specify using the file system to resolve module imports. Use of this option to specify a modules database other than the one configured for the App Server requires additional privileges. For details, see Required Privileges, below.
root
The root path for modules. If you do not explicitly specify a root option, the current root is used. Use of this option to specify a root path other than the one configured for the App Server requires additional privileges. For details, see Required Privileges, below.
timestamp
The system timestamp to use for this evaluation. If you omit this option, the most recent timestamp is used. You may only specify a timestamp for a query statement, not for an update statement. Use a value of zero to specify the current system timestamp (the value that would be returned by xdmp:request-timestamp ). For more details see Understanding Point-In-Time Queries in the Application Developer's Guide. Use of this option requires additional privileges. For details, see Required Privileges, below.
ignore-amps
Whether or not to evaluate the code without using any Amps from the caller. Allowed values: true, false (default). If this option is set to true, the code is evaluated without using Amps from the caller. For more details, see Temporarily Increasing Privileges with Amps in the Security Guide. You cannot use this option with dbg:eval.
isolation
Specify the transaction isolation for this operation. Allowed values: same-statement, different-transaction (default). When set to same-statement, the evaluation occurs in the same transaction in which this function is called. When set to different-transaction, the evaluation occurs in a separate transaction from the one in which this function is called. If you use same-statement isolation in a query (read-only) statement and the eval'd code attempts an update, MarkLogic throws the exception XDMP-UPDATEFUNCTIONFROMQUERY. For more details, see Isolation Option to xdmp:eval/invoke in the Application Developer's Guide.
commit
The commit mode for the transaction in which the code is evaluated. Allowed values: auto (default), explicit. In auto mode, a transaction is committed for every statement. In explicit mode, the transaction must be explicitely committed or rolled back. For more details, see Commit Mode in the Application Developer's Guide.
update
Specify the transaction type in which to evaluate this code, or let MarkLogic determine the transaction type. Allowed values: "true", "false", "auto" (default). For more details, see Transaction Type Overview in the Application Developer's Guide.
static-check
Whether or not to only perform a static analysis of the code, without executing it. Allowed values: true, false (default).
prevent-deadlocks
Whether or not to disallow update requests from an update transaction. Allowed values: true, false (default). This option only has an effect when you set the isolation option to different-transaction since there is no possibility of deadlock if the isolation is same-statement. When you set this option to true in an update request calling another update request, MarkLogic throws the exception XDMP-PREVENTDEADLOCKS. Setting this option to true prevents deadlocks from occurring when evaluating or invoking an update transaction from another update transaction. For more details, see Preventing Deadlocks in the Application Developer's Guide.
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, then MarkLogic uses the default XQuery version for the App Server that called this function. The version may vary from module to module if a query consists of modules written in multiple XQuery versions. If may also var from run to run if the App Server default changes across runs.

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 this function on strings that may have been passed as parameters, but should be interpreted in the App Server default language version. A module can discover its own XQuery language version with xdmp:xquery-version() .

user-id
The ID of the user under which this operation should be performed. If you do not set this option, the operation is performed as the current user. Use of htis option requires additional privileges. For details, see Required Privileges, below. NOTE: This is a very privileged operation since it enables a user to evaluate requests as any other user. For an example, see the fourth example below.
default-collation
Specifies the collation to use for this operation if a collation is not explicitly specified, such as in the XQuery prolog or in a function call that allows you to specify a collation. For more details, see Encodings and Collations in the Search Developer's Guide.
default-coordinate-system
Specifies the geospatial coordinate system to use for this operation, if a coordinate system is not explicitly specified, such as in the XQuery prolog or in a function call that allows you to specify a coordinate system. For more details, see Controlling Coordinate System and Precision in the Search Developer's Guide and Supported Coordinate Systems in the Search Developer's Guide.
transaction-mode
[DEPRECATED: Use the update and commit options instead.] Explicitly set the transaction mode for this context. Allowed values: auto (default), query, update-auto-commit, update. For details, see Transaction Mode in the Application Developer's Guide.

For simple updates to be implicitly committed, specify a transaction mode of update-auto-commit. A transaction mode of update creates a new multi-statement update transaction and requires an explicit commit in the code.

Within a session there can be only one active multi-statement transaction at a time. If a new multi-statement transaction is specified nested inside a multi-statement transaction, MarkLogic throws the exception XDMP-NESTEDMULTI. If a new multi-statement transaction is specified after another has been concurrently created in the same session by another request, MarkLogic throws the exception XDMP-SESSIONTXN and retries the current request.

An xdmp:transaction-mode XQuery prolog option in the evaluated code overrides any transaction mode specified with this option.

Required Privileges

To use this function, you must have the following privilege:

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

To use the database option to specify a content database other than the default database for the current App Server, you must have the following privilege:

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

To use the modules or root options to specify to specify a modules database or root other than that configured for the current App Server, you must have the following privilege:

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

To use the modules or root options to specify to specify using the file system as the modules database or root path, you you must have the following privilege:

http://marklogic.com/xdmp/privileges/xdmp-eval-modules-change-file

To use the user-id option, you must have the following privilege:

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

To use the timestamp option, you must have the following privileges:

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

Usage Notes

To get the database ID for options that require one, such as the database or modules options, you can use functions such as the following. Use the function appropriate to the database you want to reference.

See Also

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;
       declare variable $my:y as xs:string external := 'goodbye';
       concat('hello ', $my:x, ' ', $my:y)"
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 goodbye
   (the "goodbye" comes from the default value specified for $my:y)

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.
:)
Powered by MarkLogic Server | Terms of Use | Privacy Policy