Loading TOC...
XQuery xdmp:spawn

xdmp.spawn

xdmp.spawn(
   $path as String,
   [$vars as Object?],
   [$options as Object?]
) as Sequence

Summary

Place the specified module on the task queue for evaluation.

Parameters
$path The path of an XQuery or JavaScript module to be executed, as a string. 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 module path resolution, see Importing XQuery Modules, XSLT Stylesheets, and Resolving Paths in the Application Developer's Guide.

The module is considered to be JavaScript if the module path ends with a file extension configured for the MIME type application/vnd.marklogic-javascript in MarkLogic's Mimetypes configuration. Otherwise, it is assumed to be XQuery.
$vars External variable values to make available to the spawned code, expressed as a JavaScript Object. Each property name is a variable name, and its value is the corresponding variable value. When invoking an XQuery module, use Clark notation to represent QNames with a namespace qualifer. That is, use a name of the form ('{namespaceURI}localname'). For example, { '{http://my/ns}num': 42 } specifies that the value of the variable named 'num' in the namespace 'http://my/ns' is 42. You can use the function xdmp.keyFromQName to generate Clark notation for a QName.
$options Options with which to customize this operation. Specify your options as a JavaScript object, with the option names as the object property names. 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. Using 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. Using this option may require 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 may require 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.requestTimestamp). 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.
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.
staticCheck
Whether or not to only perform a static analysis of the code, without executing it. Allowed values: true, false (default).
defaultXqueryVersion
The default XQuery language version to use for the query, if the query does not contain an explicit version declaration. By default, MarkLogic uses the default XQuery version of the App Server that called spawn. The Task Server has no default XQuery version, so the version is passed as 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 this function on strings that may have been passed as parameters, but should be interpreted in the App Server 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 for this operation. Specify the value in seconds. 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.
userId
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 this 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.
defaultCollation
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.
defaultCoordinateSystem
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.
priority
Specify the priority of the spawned task. Allowed values: normal (default), higher.
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. For an example, see The second example.
transactionMode
[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.

Required Privileges

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

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

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-spawn-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-spawn-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-spawn-modules-change-file

To use the userId 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

This function places the specified module in the task queue to be processed. The module will be evaluated when the task server has the available resources to process it. Tasks are processed in the order in which they are added to the queue.

Once this function is called, it cannot be rolled back, even if the transaction from which it is called does not complete. Therefore, use care calling this function from an update transaction. Once a module is spawned, its evaluation is asynchronous of the transaction in which spawn is called. Consequently, if you call this function from a module, and if the module ends up retrying (for example, if a deadlock is detected), then the entire module is re-evaluated and this function is therefore called again.

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.spawn("module.xqy", null,
        {
          "modules" : xdmp.modulesDatabase(),
          "root" : "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.

Example


// This example uses the "result" option to use the results of a
// spawned task in the query

var x = xdmp.spawn("/oneplusone.sjs", null, {result: true})
// because xdmp.spawn returns a Sequence, 
// use fn.head to get the returned value
fn.head(x) + 2

// If  "/oneplusone.sjs" has following code: 
//    1 + 1 
// then this returns 4

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