Loading TOC...

POST /v1/eval

Summary

Evaluate an ad-hoc query expressed using XQuery or server-side JavaScript.

URL Parameters
xquery? The query to evaluate, expressed using XQuery. This parameter can only be specified as x-wwww-form-urlencoded data in the request body. You must include either this parameter or the javascript parameter, but not both.
javascript? The query to evaluate, expressed using server-side JavaScript. This parameter can only be specified as x-wwww-form-urlencoded data in the request body. You must include either this parameter or the xquery parameter, but not both.
vars? External variables to pass to the query during evaluation; see the Usage notes for syntax. This parameter can only be specified as x-wwww-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 query.

Required Privileges

This operation requires the following privileges or equivalent.

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

http://marklogic.com/xdmp/privileges/xdmp-eval-in

http://marklogic.com/xdmp/privileges/xdbc-eval

http://marklogic.com/xdmp/privileges/xdbc-eval-in

Usage Notes

This method is equivalent to calling xdmp:eval (XQuery) or xdmp.eval (JavaScript).

If the query 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 prefixing 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 an Ad-Hoc Query in the REST Application Developer's Guide.

Example

$ cat body.sjs
javascript=
xdmp.arrayValues([word1, word2, word1 %2B " " %2B word2])
&
vars={"word1":"hello","word2":"world"}


$ curl --anyauth --user user:password -X POST -i -d @./body.sjs \
    -H "Content-type: application/x-www-form-urlencoded" \
    -H "Accept: multipart/mixed; boundary=BOUNDARY" \
    http://localhost:8000/v1/eval

==> Evaluate the JavaScript query from the file body.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=ccbb9539c65b0631
Content-Length: 279
Connection: Keep-Alive
Keep-Alive: timeout=5


--ccbb9539c65b0631
Content-Type: text/plain
X-Primitive: untypedAtomic

hello
--ccbb9539c65b0631
Content-Type: text/plain
X-Primitive: untypedAtomic

world
--ccbb9539c65b0631
Content-Type: text/plain
X-Primitive: untypedAtomic

hello world
--ccbb9539c65b0631--
  

Example

$ cat body.xqy
xquery=
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))
&
vars={"word1":"hello","word2":"world"}


$ curl --anyauth --user user:password -X POST -i -d @./body.xqy \
    -H "Content-type: application/x-www-form-urlencoded" \
    -H "Accept: multipart/mixed; boundary=BOUNDARY" \
    http://localhost:8000/v1/eval

==> Evaluate the XQuery query from the file body.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=ad4119fdb5f9569e
Content-Length: 258
Connection: Keep-Alive
Keep-Alive: timeout=5


--ad4119fdb5f9569e
Content-Type: text/plain
X-Primitive: string

hello
--ad4119fdb5f9569e
Content-Type: text/plain
X-Primitive: string

world
--ad4119fdb5f9569e
Content-Type: text/plain
X-Primitive: string

hello world
--ad4119fdb5f9569e--
  

Comments

  • Instead of placing the XQuery code in ".xqy file" how can I pass the hard coded XQuery code like: -d "let $x := 10 return $x" When I tried with above example I got "x: undefined variable error"
    • The code has to be URL encoded: curl --anyauth --user admin:admin -X POST -i -d "xquery=let%20%24x%20%3A%3D%2010%20return%20%24x" \ -H "Content-type: application/x-www-form-urlencoded" \ -H "Accept: multipart/mixed; boundary=BOUNDARY" \ http://localhost:8000/v1/eval
      • Thanks David. It's working perfectly :) I have one more query. In the curl you have hard coded the user and password, If we will write like "--user admin" then it will ask for password. Is there any way to ask users for both user-name and password?
  • There are only pure US-ASCII text values for "vars" parameter in the examples. What about non ASCII text, integers, booleans, ... Unless I missed something ?
    • glenfant, you can put other types in the "vars" section of the examples. If you use something other than strings, change the "declare variable ... xs:string external" to match the type you use. I just tried an example with the ™ symbol added and the string example worked with no other changes.
      • David, does this means that you use JSON Unicode notation ? vars='{"unicode_tm": "\u2122"}'
        • For my first try, I just copied & pasted in the TM symbol. Just retried with "\u2122" and that worked too.
          • Many thanks David for your fast answers. I assume you tried in NodeJS. For me (in Python) this means that I need to "json encode" the vars.
Powered by MarkLogic Server 7.0-4.1 and rundmc | Terms of Use | Privacy Policy