Loading TOC...

xdmp:spawn

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

Summary

Place the specified module on the task queue for evaluation.

Parameters
$path The path, relative to the specified root, of the module to be executed. The module is considered to be JavaScript if the module path ends with a file extension matching the ones configured for application/vnd.marklogic-javascript in MarkLogic's Mimetypes configuration. For more details on resolving paths, see "Importing XQuery Modules and Resolving Paths" in the Application Developer's Guide.
$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 must be in the xdmp:eval namespace. See the xdmp:eval section for a list of options.

Required Privileges

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

Usage Notes

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

Once xdmp:spawn is called, it cannot be rolled back, even if the transaction from which it is called does not complete. Therefore, use care calling xdmp:spawn from an update transaction. Once a module is spawned, its evaluation is asynchronous of the transaction in which xdmp:spawn was called. Consequently, if you call xdmp:spawn 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 the xdmp:spawn call is therefore called again. For details on how transactions work in MarkLogic Server, see "Understanding Transactions in MarkLogic Server" in the Developer's Guide.

Example

  xdmp:spawn("module.xqy", (),
        <options xmlns="xdmp:eval">
          <modules>{xdmp:modules-database()}</modules>
	  <root>http://example.com/application/</root>
         </options>)
	
  => 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
:)  
let $x := xdmp:spawn("/oneplusone.xqy", (),
  <options xmlns="xdmp:eval">
    <result>{fn:true()}</result>
  </options>
)
return
($x + 2)
(:
   if /oneplusone.xqy has the following body:

   1 + 1

   then this query returns 4
:)

Comments

  • The implications of setting result to true are hidden in the examples. Would be useful to have a statement in the summary that spawn does return a useful value when response="true". Without that, there's no motivation to read the examples. In general, all the functions that return item()* have this problem: there's no up-front discussion of what *might* be returned and therefore it's hard to know what the function really does just from reading the function summary and parameters.
  • It would be awesome to see a module a little less trivial than 1+1 - maybe with external variables both with and without namespaces.
Powered by MarkLogic Server 7.0-4.1 and rundmc | Terms of Use | Privacy Policy