Loading TOC...

MarkLogic Server 11.0 Product Documentation
POST /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.
Request Headers
Accept* The expected MIME type of the response. The only allowed MIME type is multipart/mixed.
Content-type The MIME type of the data in the request body. Allowed values: application/x-www-form-urlencoded.
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--

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