...
Currently we have various REST endpoints (/ddl, /query, /update, /aql, /queryServicequery/service), which do similar things (parsing parameters out of the request parameters, assembling the response) but each endpoint does it in a slightly different manner. All of that should be refactored to use the common base endpoint. At the same time old endpoints could be kept for backwards-compatibility if that it really needed.
Current Web interface does the server-side HTML generation and does not use REST calls whatsoever. It would be better to eat our own dog food here and switch to assembling the result on the client side using JavaScript. Especially since we have a potential GSoC project proposal to build such JS-based interface.
- As we are moving towards having more query languages under AsterixDB umbrella (AQL, SQL++, XQuery\/JSONiq as a part of VXQuery) it would be nice to design a generic language-agnostic REST API, which later could be reused by VXQuery since it's also lacking proper API as of now.
...
N1QL API | Value | Old Asterix API | Proposed API Parameter | Comment |
results | JSONList | HTTP response body | results | One of 2 possible values 1) A list of all results returned by the query (mode=synchronous). 2) No value (statement is DDL/update/load) |
- | URI | - | handle | A URI to Status endpoint (mode=asynchronous) or the Result endpoint (mode=asynchronous-deferred) |
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 | - | plans | (Optional) An object containing details of the execution plan at different stages. |
- | JSONObject/string | - | plans.expr_tree | Serialized query expression tree (if expr-tree=true) |
- | JSONObject/string | - | plans.rewritten_expr_tree | Serialized rewritten query expression tree (if rewritten-expr-tree=true) |
- | JSONObject/string | - | plans.logical_plan | Serialized query logical plan (if logical-plan=true) |
- | JSONObject/string | - | plans.optimized_plan | Serialized query optimized logical plan (if optimized-plan=true) |
- | JSONObject/string | - | plans.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" }, "plans": { "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. Request 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", "resultshandle": "http://localhost:19002/results/071cde2e-0277-11e6-b512-3e1d05defe78", "signature": { "id": "int64", "screen_name": "string", "message_text": "string" }, "metrics": { "executionTime": "10ms", "resultCount": 2 } }
Query which returns lossless-JSON results asynchronously and does not include them into response, but provides a handle to retrieve them.
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 & include-results=false"
Code Block title Response < HTTP/1.1 200 OK Content-Type: application/json { "status": "running", "resultshandle": "http://localhost:19002/status/bd7a2b0e-0277-11e6-b512-3e1d05defe78" "metrics": { } }
...
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", "resultshandle": "http://localhost:19002/results/c7e7daed-28cd-472f-890d-62e02909e5e9" "metrics": { "executionTime": 100ms, "resultCount": 10 } }
...