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:

    • http://node:8095/

    • https://node:18095/ (for secure access)

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

    Version information

    Version : 6.6

    Consumes

    • application/x-www-form-urlencoded

    • application/json

    Produces

    • application/json

    Paths

    Table of Contents

    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 following values are deprecated and will be removed in a future release:
    application/x-adm, application/json, application/json;lossless, and text/csv.

    enum (JSON, application/x-adm, application/json, application/json;lossless, text/csv)

    "JSON"

    Query

    pretty
    optional

    If true, the result is indented.

    boolean

    "false"

    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 N1QL 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

    Table of Contents

    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 following values are deprecated and will be removed in a future release:
    application/x-adm, application/json, application/json;lossless, and text/csv.
    Default : "JSON"

    enum (JSON, application/x-adm, application/json, application/json;lossless, text/csv)

    pretty
    optional

    If true, the result is indented.
    Default : false

    boolean

    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, errors, completed, stopped, 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

    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