Overview
The Analytics Service REST API is provided by the Analytics service. This API enables you to run Analytics queries and set request-level parameters.
The API schemes and host URLs are as follows:
-
https://node:18095/ (for secure access)
where node
is the host name or IP address of a node running the Analytics service.
Paths
This section describes the operations available with this REST API.
Query Service
POST /analytics/service
Description
Enables you to execute a SQL++ for Analytics statement. This method allows you to run queries and modifying statements, and specify query parameters.
Parameters
By default, the API accepts parameters using the application/x-www-form-urlencoded
MIME type.
You can specify the application/json
MIME type using the Content-Type
header of the POST request.
Type | Name | Description | Schema |
---|---|---|---|
Body |
Parameters |
An object specifying one or more query parameters. |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
The operation was successful. |
|
400 |
Bad request. A parameter has an incorrect value. |
|
401 |
Unauthorized. The user name or password may be incorrect. |
Example HTTP request
The example below uses URL-encoded data.
curl -v -u Administrator:password \
--data-urlencode "statement=select 1;" \
http://localhost:8095/analytics/service
The example below posts the same query statement as data of type application/json
and adds a client context ID.
curl -v -u Administrator:password -H "Content-Type: application/json" -d '{
"statement":"select 1;",
"pretty":true,
"client_context_id":"xyz"
}' http://localhost:8095/analytics/service
Example HTTP response
{
"requestID": "c1984db0-f135-48ee-aea0-39dfe02d55ea",
"clientContextID": "xyz",
"signature": {
"*": "*"
},
"results": [ {
"$1" : 1
} ]
,
"plans":{},
"status": "success",
"metrics": {
"elapsedTime": "41.969099ms",
"executionTime": "31.36645ms",
"resultCount": 1,
"resultSize": 15,
"processedObjects": 0
}
}
Read-Only Query Service
GET /analytics/service
Description
Enables you to execute a SQL++ for Analytics statement. This method only allows you to run queries and specify query parameters. It does not allow you to run modifying statements.
This is intended for situations where use of the POST
method is restricted.
Parameters
Type | Name | Description | Schema | Default |
---|---|---|---|---|
Query |
statement |
Specifies at least one valid SQL++ for Analytics statement to run. |
string |
|
Query |
client_context_id |
An identifier passed by the client that is returned verbatim in the query response. Useful for matching a particular query to a specific caller. |
string |
|
Query |
format |
Desired format for the query results. Note that the only possible format is |
enum (JSON) |
|
Query |
pretty |
If |
boolean |
|
Query |
query_context |
A scope for the statement. The value of this parameter must start with |
string |
|
Query |
readonly |
If |
boolean |
|
Query |
scan_consistency |
The consistency guarantee constraint for index scanning. If |
enum (not_bounded, request_plus) |
|
Query |
scan_wait |
The maximum time to wait for datasets to be updated before the query is executed. The format includes an amount and a unit: |
string |
|
Query |
timeout |
Maximum time to spend on the request before timing out. The format includes an amount and a unit: |
string |
|
Query |
args |
An array of positional parameter values. |
< string (URL-encoded) > array |
|
Query |
$identifier |
A named parameter value. |
string |
|
Query |
plan-format |
The plan format. |
enum (JSON, STRING) |
|
Query |
logical-plan |
If |
boolean |
|
Query |
organized-logical-plan |
If |
boolean |
|
Query |
expression-tree |
If |
boolean |
|
Query |
rewritten-expression-tree |
If |
boolean |
|
Query |
job |
If |
boolean |
|
Query |
max-warnings |
An integer specifying the maximum number of warning messages to be included in the query response. |
integer (int32) |
|
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
The operation was successful. |
|
400 |
Bad request. A parameter has an incorrect value. |
|
401 |
Unauthorized. The user name or password may be incorrect. |
Example HTTP request
The example below uses a URL-encoded query parameter.
The SQL++ statement is SELECT "hello, beer!" AS greeting
.
curl -v -u Administrator:password \
http://localhost:8095/analytics/service?statement=SELECT%20%22hello%2C%20beer%21%22%20AS%20greeting
Example HTTP response
{
"requestID": "bbf382b1-4335-4a10-9eca-3b5d1a70b562",
"signature": {
"*": "*"
},
"results": [ { "greeting": "hello, beer!" }
]
,
"plans":{},
"status": "success",
"metrics": {
"elapsedTime": "56.893471ms",
"executionTime": "51.615165ms",
"resultCount": 1,
"resultSize": 31,
"processedObjects": 0
}
}
Query Service (Alternative)
POST /query/service
Description
An alternative endpoint for the Query Service, provided for tools compatibility.
Read-Only Query Service (Alternative)
GET /query/service
Description
An alternative endpoint for the Read-Only Query Service, provided for tools compatibility.
Definitions
This section describes the properties consumed and returned by this REST API.
Query Parameters
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
statement |
Specifies at least one valid SQL++ for Analytics statement to run. |
string |
client_context_id |
An identifier passed by the client that is returned verbatim in the query response. Useful for matching a particular query to a specific caller. |
string |
format |
Desired format for the query results. Note that the only possible format is |
enum (JSON) |
pretty |
If |
boolean |
query_context |
A scope for the statement. The value of this parameter must start with |
string |
readonly |
If |
boolean |
scan_consistency |
The consistency guarantee constraint for index scanning. If |
enum (not_bounded, request_plus) |
scan_wait |
The maximum time to wait for datasets to be updated before the query is executed. The format includes an amount and a unit: |
string |
timeout |
Maximum time to spend on the request before timing out. The format includes an amount and a unit: |
string |
args |
An array of positional parameter values. |
< object > array |
$identifier |
A named parameter value. |
string |
plan-format |
The plan format. |
enum (JSON, STRING) |
logical-plan |
If |
boolean |
optimized-logical-plan |
If |
boolean |
expression-tree |
If |
boolean |
rewritten-expression-tree |
If |
boolean |
job |
If |
boolean |
max-warnings |
An integer specifying the maximum number of warning messages to be included in the query response. |
integer (int32) |
Query Responses
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
requestID |
A unique identifier for the response. |
string (UUID) |
clientContextID |
The client context ID of the request, if one was supplied — refer to |
string |
signature |
The schema of the results. Present only when the query completes successfully. |
object |
results |
An array of all the objects returned by the query. An object can be any JSON value. |
< object > array |
status |
The status of the request. |
enum (success, running, failed, timeout, fatal) |
errors |
An array of error objects. Present only if 1 or more errors are returned during processing of the request. Each error is represented by an object in this list. |
< Errors > array |
warnings |
An array of warning objects. Present only if 1 or more warnings are returned during processing of the request. Each warning is represented by an object in this list. Note that you can specify the maximum number of warning messages to be returned in the query response — refer to |
< Warnings > array |
plans |
An object containing the query plans, if requested. |
|
metrics |
An object containing metrics about the request. |
Errors
Name | Description | Schema |
---|---|---|
code |
A number that identifies the error. |
integer |
msg |
A message describing the error in detail. Refer to Error Codes. |
string |
Warnings
Name | Description | Schema |
---|---|---|
code |
A number that identifies the warning. |
integer |
msg |
A message describing the warning in detail. |
string |
Plans
Name | Description | Schema |
---|---|---|
logicalPlan |
The logical plan. |
object |
optimizedLogicalPlan |
The optimized logical plan. |
object |
rewrittenExpressionTree |
The rewritten expression tree. |
string |
expressionTree |
The expression tree. |
string |
job |
The job details. |
object |
The structure and content of query plans is expected to change as development of the query processor progresses. |
Metrics
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
elapsedTime |
The total time taken for the request, that is the time from when the request was received until the results were returned. |
string |
executionTime |
The time taken for the execution of the request, that is the time from when query execution started until the results were returned. |
string |
resultCount |
The total number of objects in the results. |
integer (unsigned) |
resultSize |
The total number of bytes in the results. |
integer (unsigned) |
errorCount |
The number of errors that occurred during the request. |
integer (unsigned) |
warningCount |
The number of warnings that occurred during the request. |
integer (unsigned) |
processedObjects |
Number of processed tuples during query execution. |
integer (int64) |
Security
Analytics Manage / Analytics Select
The Analytics Service REST API supports HTTP basic authentication. Credentials can be passed via HTTP headers.
Users must have one of the following RBAC roles:
-
Full Admin
-
Cluster Admin
-
Analytics Manager
-
Analytics Reader
-
Analytics Select
-
Analytics Admin
Refer to Roles for more details.
Type : basic