MarkLogic 12 Product Documentationxdmp:invoke
xdmp:invoke( $path as xs:string, [$vars as item()* | map:map], [$options as (element()|map:map)?] ) as item()*
Summary
Returns the result of evaluating an XQuery or Server-Side JavaScript module at the given path.
| 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.
The module is considered to be JavaScript if the module path ends with
a file extension configured for the MIME type
|
| $vars |
External variable values to make available to the evaluated code,
expressed as either a sequence of alternating QName-value pairs, or
a map:map. If you use a sequence, it must contain
alternating variable QNames and values. e.g.
(xs:QName("var1"), "val1", xs:Qname("var2"), "val2").
If you use a map, then each key is a string representing the Clark
notation of the variable QName ("{namespaceURI}localname"), and its
value is the corresponding variable value. You can use
xdmp:key-from-QName
to generate the Clark notation to use as a key.
|
| options |
Options with which to customize this operation.
You can specify options as either an options XML element
in the namespace "xdmp:eval", or as a map:map. The
option names below are XML localnames. When using a map, replace any
hyphens in an option name with camel casing. For example, "an-option"
becomes "anOption" when used as a map:map entry key.
This function supports the following options:
|
Required Privileges
To use this function, you must have the following privilege:http://marklogic.com/xdmp/privileges/xdmp-invoke
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-invoke-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-invoke-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-invoke-modules-change-file
To use the user-id
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
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
- For asynchronous module invocation, see xdmp:spawn
- For synchronous evaluation of an an in-memory block of XQuery code, see xdmp:eval
- For synchronous evaluation of an an in-memory block of JavaScript code, see xdmp:javascript-eval
- Understanding Transactions in MarkLogic Server
Example
xdmp:invoke("http://example.com/modules/foo.xqy")
=> 2
Example
This example invokes a module using external variables.
Assume you have a module in the modules database with a URI
"http://example.com/application/module.xqy" containing the
following code:
xquery version "1.0-ml";
declare namespace my="my-namespace-uri";
declare variable $my:var as xs:string external;
xdmp:log($my:var)
Then you can call this module using xdmp:invoke as follows:
xquery version "1.0-ml";
declare namespace my="my-namespace-uri";
xdmp:invoke("module.xqy",
(xs:QName("my:var"), "log this"),
<options xmlns="xdmp:eval">
<modules>{xdmp:modules-database()}</modules>
<root>http://example.com/application/</root>
</options>)
=> Invokes an XQuery module from the modules database
with the URI http://example.com/application/module.xqy.
The invoked module will then be executed, logging the
message sent in the external variable to the log.
Stack Overflow: Get the most useful answers to questions from the MarkLogic community, or ask your own question.