Loading TOC...

xdmp:eval

xdmp:eval(
   $xquery as xs:string,
   [$vars as item()*],
   [$options as (element()|map:map)?]
) 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 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:key-from-QName 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 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 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 xdmp:invokexdmp.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 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:request-timestamp() ). Specifying a timestamp requires the http://marklogic.com/xdmp/privileges/xdmp-timestamp execute privilege.

<ignore-amps>

(Only valid with xdmp:eval, xdmp:invoke, xdmp:xslt-eval, xdmp:xslt-invokexdmp.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.

<static-check>

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

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

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

<default-coordinate-system>

Specifies the coordinate system to use for this context, unless a coordinate system is explicitly specified in the XQuery prolog or in a function call that allows you to specify a coordinate system.

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

<transaction-mode>

[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 user-id 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;
       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.
:)

Comments

  • Is it possible to use xdmp:eval to execute xquery in rest-api? For example, I have xquery for renaming forests that I converted to rest-api, installed it as extension but I get curl(52) error, so I was digging into how other functions are created and in "/opt/MarkLogic/Modules/MarkLogic/appservices/appbuilder/util-amped.xqy" function amped-build:appbuilder-create-database is just wrapping around xquery. I just wanted to see if in ML7 something like that is supported for all other functions. Does that mean we can simple is this function as a wrapper to any xquery and then add it as rest-api extension? Thank you
    • You *could* write an extension that would take an XQuery string and eval it, but I would strongly discourage that. You're much better off writing extensions for what you need, or doing them through existing endpoints where your needs are supported. xdmp.eval is good for working with a different database, or having something happen in a different transaction, but you can usually accomplish things like this through REST API parameters as well.
  • having problems trying to pass a sequence into xdmp:eval with vars ? Check out David Cassel's blog entry on the subject http://blog.davidcassel.net/2010/01/passing-a-sequence-to-xdmpeval/
    • Alternative to the delimited list is to send in a map, it's actually quite easy, although a bit convoluted, and note that you cannot send an empty sequence directly with this technique since empty sequences can't be stored in maps. (:~ : Gets a list of role names from an id : Requires permissions (amp or admin, see ML docs for required permissions.) ~:) declare function local:get-role-names( $role-ids as xs:unsignedLong* ) { if (fn:exists($role-ids)) then xdmp:eval(' xquery version "1.0-ml"; import module namespace sec="http://marklogic.com/xdmp/security" at "/MarkLogic/security.xqy"; declare variable $role-ids as xs:unsignedLong* external; sec:get-role-names($role-ids) ', map:new(( map:entry("{}role-ids", $role-ids) )), <options xmlns="xdmp:eval"> <database>{xdmp:security-database()}</database> </options> ) else () };
Powered by MarkLogic Server 7.0-4.1 and rundmc | Terms of Use | Privacy Policy