Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

A newer version of this documentation is available.

View Latest

Analytics Service REST API

      +

      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.1

      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.

      Query Parameters

      Responses

      HTTP Code Description Schema

      200

      The operation was successful.

      Query Responses

      400

      Bad request. A parameter has an incorrect value.

      Query Responses

      401

      Unauthorized. The user name or password may be incorrect.

      Query Responses

      Security

      Type Name

      basic

      Analytics Manage / Analytics Select

      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
      {
  "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.

      Query Responses

      400

      Bad request. A parameter has an incorrect value.

      Query Responses

      401

      Unauthorized. The user name or password may be incorrect.

      Query Responses

      Security

      Type Name

      basic

      Analytics Manage / Analytics Select

      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
      {
  "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.

      Plans

      metrics
      optional

      An object containing metrics about the request.

      Metrics

      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