A newer version of this documentation is available.

View Latest
February 16, 2025
+ 12

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:

where node is the host name or IP address of a node running the Analytics service.

Version information

Version : 7.0

Consumes

  • application/x-www-form-urlencoded

  • application/json

Produces

  • application/json

Paths

This section describes the operations available with this REST API.

Query Service

POST /analytics/service

Description

Enables you to execute a N1QL 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
required

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.

Security

Type Name

basic

Example HTTP request

The example below uses URL-encoded data.

Curl request
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 request
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

Response 200
json
{ "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 N1QL 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
required

Specifies at least one valid N1QL for Analytics statement to run.

string

Query

client_context_id
optional

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
optional

Desired format for the query results.

Note that the only possible format is JSON.

enum (JSON)

"JSON"

Query

pretty
optional

If true, the result is indented.

boolean

"false"

Query

query_context
optional

A scope for the statement. The value of this parameter must start with default:, followed by an Analytics scope name. The default: prefix is a dummy and is ignored when resolving an Analytics collection name or synonym name.

string

"default:Default"

Query

readonly
optional

If true, then DDL statements are not allowed.

boolean

"false"

Query

scan_consistency
optional

The consistency guarantee constraint for index scanning. If not_bounded, the query is executed immediately. If request_plus, the required datasets are updated with data available from the Data service at the time of the request before the query is executed.

enum (not_bounded, request_plus)

"not_bounded"

Query

scan_wait
optional

The maximum time to wait for datasets to be updated before the query is executed. The format includes an amount and a unit: ns, us, ms, s, m, or h. The default is "" (no timeout).

string

""

Query

timeout
optional

Maximum time to spend on the request before timing out. The format includes an amount and a unit: ns, us, ms, s, m, or h. The default is "" (no timeout).

string

""

Query

args
optional

An array of positional parameter values.

< string (URL-encoded) > array

Query

$identifier
optional

A named parameter value.

string

Query

plan-format
optional

The plan format.

enum (JSON, STRING)

"JSON"

Query

logical-plan
optional

If true, the logical plan is included in the query response.

boolean

"false"

Query

organized-logical-plan
optional

If true, the optimized logical plan is included in the query response.

boolean

"true"

Query

expression-tree
optional

If true, the expression tree is included in the query response.

boolean

"false"

Query

rewritten-expression-tree
optional

If true, the rewritten expression tree is included in the query response.

boolean

"false"

Query

job
optional

If true, the job details are included in the query response.

boolean

"false"

Query

max-warnings
optional

An integer specifying the maximum number of warning messages to be included in the query response.

integer (int32)

0

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.

Security

Type Name

basic

Example HTTP request

The example below uses a URL-encoded query parameter. The SQL++ statement is SELECT "hello, beer!" AS greeting.

Curl request
curl -v -u Administrator:password \
http://localhost:8095/analytics/service?statement=SELECT%20%22hello%2C%20beer%21%22%20AS%20greeting

Example HTTP response

Response 200
json
{ "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
required

Specifies at least one valid N1QL for Analytics statement to run.

string

client_context_id
optional

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
optional

Desired format for the query results.

Note that the only possible format is JSON.
Default : "JSON"

enum (JSON)

pretty
optional

If true, the result is indented.
Default : false

boolean

query_context
optional

A scope for the statement. The value of this parameter must start with default:, followed by an Analytics scope name. The default: prefix is a dummy and is ignored when resolving an Analytics collection name or synonym name.
Default : "default:Default"

string

readonly
optional

If true, then DDL statements are not allowed.
Default : false

boolean

scan_consistency
optional

The consistency guarantee constraint for index scanning. If not_bounded, the query is executed immediately. If request_plus, the required datasets are updated with data available from the Data service at the time of the request before the query is executed.
Default : "not_bounded"

enum (not_bounded, request_plus)

scan_wait
optional

The maximum time to wait for datasets to be updated before the query is executed. The format includes an amount and a unit: ns, us, ms, s, m, or h. The default is "" (no timeout).
Default : ""

string

timeout
optional

Maximum time to spend on the request before timing out. The format includes an amount and a unit: ns, us, ms, s, m, or h. The default is "" (no timeout).
Default : ""

string

args
optional

An array of positional parameter values.

< object > array

$identifier
optional

A named parameter value.

string

plan-format
optional

The plan format.
Default : "JSON"

enum (JSON, STRING)

logical-plan
optional

If true, the logical plan is included in the query response.
Default : false

boolean

optimized-logical-plan
optional

If true, the optimized logical plan is included in the query response.
Default : true

boolean

expression-tree
optional

If true, the expression tree is included in the query response.
Default : false

boolean

rewritten-expression-tree
optional

If true, the rewritten expression tree is included in the query response.
Default : false

boolean

job
optional

If true, the job details are included in the query response.
Default : false

boolean

max-warnings
optional

An integer specifying the maximum number of warning messages to be included in the query response.
Default : 0

integer (int32)

Query Responses

Polymorphism : Composition

Name Description Schema

requestID
optional

A unique identifier for the response.

string (UUID)

clientContextID
optional

The client context ID of the request, if one was supplied — refer to client_context_id in Query Parameters.

string

signature
optional

The schema of the results. Present only when the query completes successfully.

object

results
optional

An array of all the objects returned by the query. An object can be any JSON value.

< object > array

status
optional

The status of the request.

enum (success, running, failed, timeout, fatal)

errors
optional

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
optional

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 max-warnings in Query Parameters. By default, no warnings are returned, even if warnings have occurred during processing.

< Warnings > array

plans
optional

An object containing the query plans, if requested.

metrics
optional

An object containing metrics about the request.

Errors

Name Description Schema

code
optional

A number that identifies the error.

integer

msg
optional

A message describing the error in detail. Refer to Error Codes.

string

Warnings

Name Description Schema

code
optional

A number that identifies the warning.

integer

msg
optional

A message describing the warning in detail.

string

Plans

Name Description Schema

logicalPlan
optional

The logical plan.

object

optimizedLogicalPlan
optional

The optimized logical plan.

object

rewrittenExpressionTree
optional

The rewritten expression tree.

string

expressionTree
optional

The expression tree.

string

job
optional

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
optional

The total time taken for the request, that is the time from when the request was received until the results were returned.

string

executionTime
optional

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
optional

The total number of objects in the results.

integer (unsigned)

resultSize
optional

The total number of bytes in the results.

integer (unsigned)

errorCount
optional

The number of errors that occurred during the request.

integer (unsigned)

warningCount
optional

The number of warnings that occurred during the request.

integer (unsigned)

processedObjects
optional

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