Page History

...

Type of the response - JSON document (even if format in request was CSV it will be serialized as one of JSON attributes)

N1QL API Parameter	Value	Old Asterix API Parameter	Proposed API Parameter	Comment
results	JSONList/stringURI	HTTP response body	results	One of three possible values depending on result delivery 1) A list of all results returned by the query (sync result deliverymode=synchronous). 2) A list of all URIs to QueryStatus endpoint (async result deliveryURI to Status endpoint (mode=asynchronous). 3) No value (statement is DDL\update\load)
signature	JSONObject	-	signature	The schema of the results (if signature=true & format !=CSV)
status	string	HTTP response status	status	The status of the request; possible values are: success, running (async result), error (parse\optimizer error), fatal (execution error).
error	JSONObject	HTTP response body	error	An object containing details of the error
error.code	int	error-code	error.code	A code that identifies the error.
error.msg	string	summary	error.msg	A message describing the error in detail.
	string	stacktrace	error.stacktrace	A stack trace of the error.
metrics	JSONObject	-	metrics	An object containing details of the execution metrics.
metrics.executionTime	string	-	metrics.executionTime	The time taken for the execution of the request, i.e. time from when query execution started until the results were returned. (if mode=synchronous and execute-query=true)
metrics.resultCount	unsigned int	-	metrics.resultCount	The total number of objects in the results (if mode=synchronous and execute-query=true)
	JSONObject	-	metrics.expr_tree	Serialized query expression tree (if expr-tree=true)
	JSONObject	-	metrics.rewritten_expr_tree	Serialized rewritten query expression tree (if rewritten-expr-tree=true)
	JSONObject	-	metrics.logical_plan	Serialized query logical plan (if logical-plan=true)
	JSONObject	-	metrics.optimized_plan	Serialized query optimized logical plan (if optimized-plan=true)
	JSONObject	-	metrics.hyracks_job	Serialized Hyracks job (if hyracks-job=true)

Examples:

DDL request

Code Block

title	Request

curl -v http://localhost:19002/query -X POST \
-d "statement=create dataverse test;"

Code Block

title	Response

< HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "success"
  "metrics": {
    "executionTime": "1ms"
  }
}

Query which is not executed, but returns logical plan

Code Block

title	Request

curl -v http://localhost:19002/query -X POST \
-d "statement=for $x in dataset testDS return $x & lossless=true & logical-plan=true & execute-query=false"

Code Block

title	Response

< HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "success"
  "metrics": {
    "executionTime": "5ms",
    "logical_plan": [
      {"operator": "distribute_result", "args": [{"exp": "var_ref", "var": "$$0"}]},
      {"operator": "datascan", "output_vars": ["$$0", "$$1"]}
  }
}

Query which synchronously returns CSV (with header) result inside JSON response

Code Block

title	Request

curl -v http://localhost:19002/query -X POST -H "Accept: text/csv" \
-d "statement=for $x in dataset Tweets return $x & signature=true"

Code Block

title	Response

< HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "success",
  "results": "'id','screen_name','message_text'\n'1','BarackObama','Four more years'"
  "metrics": {
    "executionTime": "10ms",
    "resultCount": 1
  }
}

Query which returns optimizer error

Code Block

title	Request

curl -v http://localhost:19002/query -X POST \
-d "statement=create dataset Tweets(TweetType) primary key facebook_id"

Code Block

title	Response

< HTTP/1.1 400 Bad Request
Content-Type: application/json
{
  "status": "error",
  "error": {
    "code": 1,
    "msg": "Field 'facebook_id' cannot be found in datatype 'TweetType'"
  }
  "metrics": {
    "executionTime": "1ms"
  }
}

Query which returns runtime error

Code Block

title	Request

curl -v http://localhost:19002/query -X POST \
-d "statement=create dataset Tweets(TweetType) primary key facebook_id"

Code Block

title	Response

< HTTP/1.1 500 Internal Server Error
Content-Type: application/json
{
  "status": "fatal",
  "error": {
    "code": 99,
    "msg": "Something happen during query execution",
    "stacktrace": "java.lang.RuntimeException: \n\r at java.lang.Thread.run(Thread.java:745)"
  }
  "metrics": {
    "executionTime": "1ms"
  }
}

Query which runs synchronously, however does not include them into response, but provides a handle to retrieve them. Also includes ADM signature of the resultRequest also specifies to include ADM type (signature).

Code Block

title	Request

curl -v http://localhost:19002/query -X POST \
-d "statement=for $x in dataset Tweets return $x & include-results=false & signature=true"

Code Block

title	Response

< HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "success",
  "results": "http://localhost:19002/results/071cde2e-0277-11e6-b512-3e1d05defe78",
  "signature": {
    "id": "int64",
    "screen_name": "string",
    "message_text": "string"
  },
  "metrics": {
    "executionTime": "10ms",
    "resultCount": 12
  }
}

Query which returns lossless-JSON results asynchronously

Code Block

title	Request

curl -v http://localhost:19002/query -X POST -H "Accept: application/json" \
-d "statement=for $x in dataset Tweets return $x & lossless=true & mode=asynchronous"

Code Block

title	Response

< HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "running",
  "results": "http://localhost:19002/status/bd7a2b0e-0277-11e6-b512-3e1d05defe78"
  "metrics": {
  }
}

...

status	enum	The status of the request; possible values are: success (query is completed), running (query is still running), fatal (execution error).
results	URI	The URI to /result endpoint, if the query was completed (status=success).
error	JSONObject	An object containing details of the error.
error.code	int	A code that identifies the error.
error.msg	string	A message describing the error in detail.
error.stacktrace	string	A stack trace of the error.
metrics

...

JSONObject	An object containing details of the execution metrics (only when status=success).
metrics.executionTime	string	The time it took to execute of the request
metrics.resultCount	int	The total number of objects in the results

Examples:

Query which returns runtime error

Code Block

title	Request

curl -v http://localhost:19002/status/bd7a2b0e-0277-11e6-b512-3e1d05defe78 -X GET

Code Block

title	Response

< HTTP/1.1 500 Internal Server Error
Content-Type: application/json
{
  "status": "fatal",
  "error": {
    "code": 99,
    "msg": "Something happen during query execution",
    "stacktrace": "java.lang.RuntimeException: \n\r at java.lang.Thread.run(Thread.java:745)"
  }
}

Query which is still executing

Code Block

title	Request

curl -v http://localhost:19002/status/bd7a2b0e-0277-11e6-b512-3e1d05defe78 -X GET

Code Block

title	Response

< HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "running"
}

Query which successfully completes and return URI to its results. Reffer to Query endpoint Example 7 to see the original request.

Code Block

title	Request

curl -v http://localhost:19002/status/bd7a2b0e-0277-11e6-b512-3e1d05defe78 -X GET

Code Block

title	Response

< HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "success",
  "results": "http://localhost:19002/results/c7e7daed-28cd-472f-890d-62e02909e5e9"
  "metrics": {
    "executionTime": 100ms,
    "resultCount": 10
  }
}

Result Endpoint (/result)

This endpoint is used to retrieve results of asynchronous query execution or synchronous results, when the client opted out from having results included into /query request (include-results=false).

Note that the Content-type of the result is set up appropriately to Accept in the initial request.

HTTP Request(GET) format:

http://localhost:19002/results/ID

Where ID is a UUID generated and returned by /query endpoint (include-results=false) or by /status endpoint when the asynchronous result is computed.

HTTP Response format:

The response includes only the results with appropriate Content-Type header.

Examples:

Synchronous query results. Refer to Query endpoint Example 6 to see the original request.

Code Block

title	Request

curl -v http://localhost:19002/results/071cde2e-0277-11e6-b512-3e1d05defe78 -X GET

Code Block

title	Response

< HTTP/1.1 200 OK
Content-Type: application/x-adm
{
  "id": 1,
  "screen_name": "BarackObama",
  "message_text": "Four more years"
}
{
  "id": 2,
  "screen_name": "ElonMusk",
  "message_text": "I Would Like to Die on Mars, Just Not on Impact"
}

Asynchronous query results. Refer to Query endpoint Example 7 & Status endpoint Example 3 to see the original requests.

Code Block

title	Request

curl -v http://localhost:19002/results/c7e7daed-28cd-472f-890d-62e02909e5e9 -X GET

Code Block

title	Response

< HTTP/1.1 200 OK
Content-Type: application/json
[ {
  "id": 1,
  "screen_name": "BarackObama",
  "message_text": "Four more years"
}, {
  "id": 2,
  "screen_name": "ElonMusk",
  "message_text": "I Would Like to Die on Mars, Just Not on Impact"
} ]

Page tree

Versions Compared

Old Version 8

New Version 9

Key

Examples:

Examples:

Result Endpoint (/result)

HTTP Request(GET) format:

HTTP Response format:

Examples: