Page History

...

N1QL API Parameter	Value	Old Asterix API Parameter	Proposed API Parameter	Comment
results	JSONList/string	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 delivery). 2) A list of all URIs to QueryStatus endpoint (async result delivery). 3) No value (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.
		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 result.

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": 1
  }
}

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": {
  }
}

Page tree

Versions Compared

Old Version 6

New Version 7

Key

Examples:

Status Endpoint (/status)