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