MarkLogic Server 11.0 Product DocumentationPOST /v1/invoke
Summary
Evaluate an XQuery or server-side JavaScript module installed in MarkLogic Server.
| URL Parameters | |
|---|---|
| module |
The path of the module to be evaluated. The path is resolved against
the root of the App Server that is part of your REST API instance
or to the Modules database or directory. The module filename suffix
determines whether the module is treated as XQuery or JavaScript;
for details, see the Usage Notes below. This parameter can only be
specified as x-www-form-urlencoded data in the request
body.
|
| vars? |
External variables to pass to the module; see the Usage notes for
syntax. This parameter can only be specified as
x-www-form-urlencoded data in the request body.
|
| database? | Perform this operation on the named content database instead of the default content database associated with the REST API instance. The database can be identified by name or by database id. Using an alternative database requires the "eval-in" privilege; for details, see Security Requirements in the REST Application Developer's Guide. |
| txid? |
The transaction identifier of the multi-statement transaction in
which to service this request. Use the /transactions
service to create and manage multi-statement transactions.
|
| Response Headers | |
|---|---|
| Content-type |
The MIME type of the data in the response body. This request always
returns multipart/mixed, in the same format returned
by the XDBC protocol.
|
Response
Upon success, MarkLogic Server responds with 200 OK. The response
body is multipart/mixed, with one part for each result
produced by evaluating the module.
Required Privileges
This operation requires the following privileges or equivalent:http://marklogic.com/xdmp/privileges/xdmp-invoke
http://marklogic.com/xdmp/privileges/xdmp-invoke-in
http://marklogic.com/xdmp/privileges/xdbc-invoke
http://marklogic.com/xdmp/privileges/xdbc-invoke-in
Usage Notes
This method is equivalent to calling xdmp:invoke (XQuery)
or xdmp.invoke (JavaScript).
The expected implementation language of the module is determined by
the MIME type mapping defined for the file extension with which the
path ends. For example, the "sjs" extension is mapped to
application/vnd.marklogic-javascript MIME type by default,
so module=/some/path/mymodule.sjs is expected to be a
JavaScript module. Similarly, the "xqy" file extension is mapped to
XQuery by default.
If the module depends on external variables, supply the variables values
using the vars parameter. Use following format for the
value of the vars parameter in the request body:
{"paramName":"paramValue", "paramName":"paramValue",...}
For XQuery external parameters, you can include a namesapce URI by
using Clark notation. That is, prefix the parameter name with
{theURI}. For example, to supply a value for the parameter
"title" in the namespace "http://marklogic.com/example", express the
parameter name and value as:
{"http://marklogic.com/example}title":"value".
For details, see Evaluating a Module Installed on MarkLogic Server in the REST Application Developer's Guide.
Example
Install the module in the modules database:
------------------------------------------
$ cat module.sjs
xdmp.arrayValues([word1, word2, word1 + " " + word2])
$ curl --anyauth --user user:password -X PUT -i --data-binary @./module.sjs \
-H "Content-type: application/vnd.marklogic-javascript" \
http://localhost:8000/v1/ext/invoke/my.sjs
Invoke the module:
-----------------
$ curl --anyauth --user user:password -X POST -i \
--data-urlencode module=/ext/invoke/my.sjs \
--data-urlencode vars='{"word1":"hello","word2":"world"}' \
-H "Content-type: application/x-www-form-urlencoded" \
-H "Accept: multipart/mixed" \
http://localhost:8000/v1/invoke
==> Evaluate the JavaScript module installed under /ext/invoke/my.sjs on
MarkLogic Server. The response includes 3 parts, corresponding to the
three items returned by the query: The value of word1, the value of
word2, and the result of concantenating the two values. MarkLogic returns
a response similar to the following:
HTTP/1.1 200 OK
Server: MarkLogic 8.0-20141122
Set-Cookie: TxnMode=query; path=/
Set-Cookie: TxnID=null; path=/
Content-Type: multipart/mixed; boundary=1176113105d6eaed
Content-Length: 279
Connection: Keep-Alive
Keep-Alive: timeout=5
--1176113105d6eaed
Content-Type: text/plain
X-Primitive: untypedAtomic
hello
--1176113105d6eaed
Content-Type: text/plain
X-Primitive: untypedAtomic
world
--1176113105d6eaed
Content-Type: text/plain
X-Primitive: untypedAtomic
hello world
--1176113105d6eaed--
Example
Install the module in the modules database:
------------------------------------------
$ cat module.xqy
xquery version "1.0-ml";
declare variable $word1 as xs:string external;
declare variable $word2 as xs:string external;
($word1, $word2, fn:concat($word1, " ", $word2))
$ curl --anyauth --user user:password -X PUT -i -d @./module.xqy \
-H "Content-type: application/xquery" \
http://localhost:8000/v1/ext/invoke/my.xqy
Invoke the module:
------------------
$ curl --anyauth --user user:password -X POST -i \
--data-urlencode module=/ext/invoke/my.xqy \
--data-urlencode vars='{"word1":"hello","word2":"world"}' \
-H "Content-type: application/x-www-form-urlencoded" \
-H "Accept: multipart/mixed; boundary=BOUNDARY" \
http://localhost:8000/v1/invoke
==> Evaluate the module installed in the modules database with the URI
/ext/invoke/my.xqy on MarkLogic Server. The response includes 3 parts,
corresponding to the three items returned by the query: The value of
$word1, the value of $word2, and the result of concantenating the two
values. MarkLogic returns a response similar to the following:
HTTP/1.1 200 OK
Server: MarkLogic 8.0-20141122
Set-Cookie: TxnMode=auto; path=/
Set-Cookie: TxnID=null; path=/
Content-Type: multipart/mixed; boundary=5abb9090cf59622a
Content-Length: 258
Connection: Keep-Alive
Keep-Alive: timeout=5
--5abb9090cf59622a
Content-Type: text/plain
X-Primitive: string
hello
--5abb9090cf59622a
Content-Type: text/plain
X-Primitive: string
world
--5abb9090cf59622a
Content-Type: text/plain
X-Primitive: string
hello world
--5abb9090cf59622a--