HTTP API to AsterixDB

Table of Contents

POST /query/service [Back to TOC]

Description Returns result for query as JSON. The response is a JSON object that contains some result metadata along with either an embedded result or an opaque handle that can be used to navigate to the result (see the decription of the mode parameter for more details).

Parameters

  • statement - Specifies at least one valid SQL++ statement to run. The statements need to be urlencoded. Required.
  • pretty - If the parameter pretty is given with the value true, the result will be indented. (Optional)
  • client_context_id - A user-defined sequence of characters that the API receives and returns unchanged. This can be used e.g. to match individual requests, jobs, and responses. Another option could be to use it for groups of requests if an application decides to put e.g. an group identifier into that field to route groups of responses to a particular response processor.
  • mode - Result delivery mode. Possible values are immediate, deferred, async (default: immediate). If the delivery mode is immediate the query result is returned with the response. If the delivery mode is deferred the response contains a handle to the result. If the delivery mode is async the response contains a handle to the query's status.
  • readonly - Reject DDL and DML statements, only accept the following kinds: SELECT, USE, DECLARE FUNCTION, and SET
  • args - (SQL++ only) A JSON array where each item is a value of a positional query parameter
  • $parameter_name - (SQL++ only) a JSON value of a named query parameter.

Command (immediate result delivery)

$ curl -v --data-urlencode "statement=select 1;" \
          --data pretty=true                     \
          --data client_context_id=xyz           \
          http://localhost:19002/query/service

Sample response

> POST /query/service HTTP/1.1
> Host: localhost:19002
> User-Agent: curl/7.43.0
> Accept: */*
> Content-Length: 57
> Content-Type: application/x-www-form-urlencoded
>
< HTTP/1.1 200 OK
< transfer-encoding: chunked
< connection: keep-alive
< content-type: application/json; charset=utf-8
<
{
    "requestID": "5f72e78c-482a-45bf-b174-6443c8273025",
    "clientContextID": "xyz",
    "signature": "*",
    "results": [ {
        "$1" : 1
    } ]
    ,
    "status": "success",
    "metrics": {
        "elapsedTime": "20.263371ms",
        "executionTime": "19.889389ms",
        "resultCount": 1,
        "resultSize": 15
    }
}

Command (deferred result delivery)

$ curl -v --data-urlencode "statement=select 1;" \
          --data mode=deferred                   \
          http://localhost:19002/query/service

Sample response

> POST /query/service HTTP/1.1
> Host: localhost:19002
> User-Agent: curl/7.43.0
> Accept: */*
> Content-Length: 37
> Content-Type: application/x-www-form-urlencoded
>
< HTTP/1.1 200 OK
< transfer-encoding: chunked
< connection: keep-alive
< content-type: application/json; charset=utf-8
<
{
    "requestID": "6df7afb4-5f83-49b6-8c4b-f11ec84c4d7e",
    "signature": "*",
    "handle": "http://localhost:19002/query/service/result/7-0",
    "status": "success",
    "metrics": {
        "elapsedTime": "12.270570ms",
        "executionTime": "11.948343ms",
        "resultCount": 0,
        "resultSize": 0
    }
}

Command (async result delivery)

$ curl -v --data-urlencode "statement=select 1;" \
          --data mode=async                      \
          http://localhost:19002/query/service

Sample response

> POST /query/service HTTP/1.1
> Host: localhost:19002
> User-Agent: curl/7.43.0
> Accept: */*
> Content-Length: 34
> Content-Type: application/x-www-form-urlencoded
>
< HTTP/1.1 200 OK
< transfer-encoding: chunked
< connection: keep-alive
< content-type: application/json; charset=utf-8
<
{
    "requestID": "c5858420-d821-4c0c-81a4-2364386827c2",
    "signature": "*",
    "status": "running",
    "handle": "http://localhost:19002/query/service/status/9-0",
    "metrics": {
        "elapsedTime": "9.727006ms",
        "executionTime": "9.402282ms",
        "resultCount": 0,
        "resultSize": 0
    }
}

GET /query/service/status [Back to TOC]

Description Returns status of an async query request. The response is a JSON object that has a similar structure to the responses for the /query/service endpoint. Possible status values for the status are running, success, timeout, failed, and fatal. If the status value is success, the response also contains a handle to the result. URLs for this endpoint are usually not constructed by the application, they are simply extracted from the handle field of the response to a request to the /query/service endpoint.

Command

This example shows a request/reponse for the (opaque) status handle that was returned by the async result delivery example.

$ curl -v http://localhost:19002/query/service/status/9-0

Sample response

> GET /query/service/status/9-0 HTTP/1.1
> Host: localhost:19002
> User-Agent: curl/7.43.0
> Accept: */*
>
< HTTP/1.1 200 OK
< transfer-encoding: chunked
< connection: keep-alive
< content-type: application/json; charset=utf-8
<
{
    "status": "success",
    "handle": "http://localhost:19002/query/service/result/9-0"
}

GET /query/service/result [Back to TOC]

Description Returns result set for an async or deferred query request. The response is a plain result without a wrapping JSON object. URLs for this endpoint are usually not constructed by the application, they are simply extracted from the handle field of the response to a request to the /query/service or the /query/service/status endpoint.

Command

This example shows a request/reponse for the (opaque) result handle that was returned by the deferred result delivery example.

$ curl -v http://localhost:19002/query/service/result/7-0

Sample response

> GET /query/service/result/7-0 HTTP/1.1
> Host: localhost:19002
> User-Agent: curl/7.43.0
> Accept: */*
>
< HTTP/1.1 200 OK
< transfer-encoding: chunked
< connection: keep-alive
< content-type: application/json
<
[ { "$1": 1 }
 ]