Loading TOC...

xdmp.eval

xdmp.eval(
   javascript as String,
   [vars as Object],
   [options as Object?]
) as ValueIterator

Summary

Returns the result of evaluating a string as a Javascript program.

Parameters
javascript The Javascript string to be evaluated. If the Javascript string contains double quotes ("), surround the string with single quotes (').
vars The external variable values for this evaluation. This can either be a sequence of map:map objects, or a sequence of even length, alternating QNames and items.

Each key in the map(s) is a string representing the name of the parameter in Clark notation: "{namespaceURI}localname". The function xdmp.keyFromQName is a convenient way to generate these keys. Each entry in the map is the value of the corresponding external variable.

Alternatively, the alternating sequence should contain QName and item pairs that specify a variable name and value for an external variable.

options The options object. The default value is null. The following is a sample options object:
    {
      "isolation" : "different-transaction",
      "preventDeadlocks" : true
    } 

The xdmp.eval options include:

database

The database ID, from xdmp:database("db_name") xdmp.database("db_name"), xdmp.securityDatabase(), or xdmp.schemaDatabase(). 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 module option 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 ), 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 option specifies the current root. You need the same privilege to modify the root as you need to change the module option.

timestamp

The system timestamp to use for this evaluation. Specifying no timestamp options 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.requestTimestamp()). Specifying a timestamp requires the http://marklogic.com/xdmp/privileges/xdmp-timestamp execute privilege.

ignoreAmps

(Only valid with xdmp.eval, xdmp.invoke, xdmp.xsltEval, xdmp.xsltInvoke; does not apply to xdmp.spawn, dbg.eval or dbg.invoke). Either true or false. When set to true, the statement is evaluated without using any Amps from the caller. The default value for this option is false.

isolation

Default value is different-transaction. Valid values are same-statement and 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.

commit

Default value is auto. Valid values are auto, meaning a transaction is committed for every statement, and explicit, meaning a transaction needs to be explicitly committed or rolled back.

update

Default value is auto. Valid values are auto, meaning determined based on the statement, true, meaning evaluate as update, false, meaning evaluate as query.

staticCheck

Specify true to only perform static checks on the module, and not to actually execute it. The default is false, which means the the code is fully evaluated.

preventDeadlocks

(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 this option is false.

defaultXqueryVersion

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.xqueryVersion().

timeLimit

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.

userId

Specifies the user ID for the user to run the request being evaluated (the request specified in the $xquery parameter). If this option 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 this 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.

defaultCollation

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.

priority

Specify the priority of the spawned task. Allowable values for this option are "normal" and "higher". This option only applies to xdmp.spawn, not to xdmp.invoke or xdmp.eval.

result

Return a value future for the result of the spawned task. This value future can bound be to a variable without waiting so that work can proceed concurrently with the spawned task. When the calling request uses the value future in any operation, it will automatically wait for the spawned task to complete and it will use the result. This option only applies to xdmp.spawn, not to xdmp.invoke or xdmp.eval. For an example, see The second example.

transactionMode

[DEPRECATED: Use update and commit options instead.] Explicitly set the transaction mode for this context. Valid values are auto, query, update-auto-commit, and update. The default is auto.

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, an XDMP-NESTEDMULTI error is returned. If a new multi-statement transaction is specified but another has already been concurrently created in the same session by another request, an XDMP-SESSIONTXN error is returned and the current request is retried.

An xdmp:transaction-mode prolog option in evaluated XQuery will override any transaction mode specified with this option.

Required Privileges

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

Example

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

Example

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

Example

xdmp.eval('xdmp.getCurrentUser()', null,
  {
    "userId" : xdmp.user("someuser")
  })
=>
  returns "someuser", assuming "someuser" exists in the
  security database and the user running the eval request has the
  xdmp:login privilege.

Example

//pass external variables into JavaScript eval
var q = '"The value of a is:\\n" + a + "\\n\\nThe value of b is:\\n" + b';
// the key in the below object is the external variable name 
// and the value is that variable's value
var ext = {a:"some text", b:"other stuff"};
xdmp.eval(q, ext);
=>
 return the following string:
The value of a is:
some text

The value of b is:
other stuff 

Stack Overflow iconStack Overflow: Get the most useful answers to questions from the MarkLogic community, or ask your own question.