openapi: 3.0.3
info:
  title: Enterprise Analytics Configuration REST API
  version: '2.0'
  description: |
    This API enables you to configure Enterprise Analytics Service.
servers:
  - url: '{scheme}://{host}:{port}'
    description: The URL scheme, host, and port are as follows.
    variables:
      scheme:
        default: http
        description: |-
          The URL scheme.
          Use `https` for secure access.
        enum:
          - http
          - https
      host:
        default: localhost
        description: The host name or IP address of a node.
      port:
        default: '8095'
        description: |-
          The Enterprise Analytics Service REST port.
          Use `18095` for secure access.
        enum:
          - '8095'
          - '18095'
paths:
  /api/v1/config/service:
    get:
      operationId: get_service
      summary: View Service-Level Parameters
      description: Views service-level parameters, which apply to all nodes.
      security:
        - AnalyticsManage: []
      responses:
        '200':
          description: |
            Success. Returns an object listing the configurable service-level parameters and their current values.
          content:
            application/json:
              schema:
                type: object
                properties: &ref_0
                  analyticsHttpRequestQueueSize:
                    description: The maximum number of HTTP requests to queue pending ability to execute.
                    type: integer
                    format: int32
                    x-has-default: true
                    default: 256
                  analyticsHttpThreadCount:
                    description: The number of threads to service HTTP requests.
                    type: integer
                    format: int32
                    x-has-default: true
                    default: 16
                  cloudAccessPreemptiveRefreshIntervalSeconds:
                    description: The interval at which to attempt to preemptively verify cloud access. If access is confirmed to be revoked, the process will halt. (0 == no preemptive refresh)
                    type: integer
                    format: int32
                    x-has-default: true
                    default: 15
                  cloudAccessRefreshHaltTimeoutSeconds:
                    description: The length of time before we will halt on failure to verify cloud access. (0 == wait forever)
                    type: integer
                    format: int32
                    x-has-default: true
                    default: 120
                  cloudAccessTtlSeconds:
                    description: The length of time allowed to assume we have still have write access to cloud resources
                    type: integer
                    format: int32
                    x-has-default: true
                    default: 15
                  cloudMaxReadRequestsPerSecond:
                    description: The maximum number of read requests per second (default 1500, 0 means unlimited)
                    type: integer
                    format: int32
                    x-has-default: true
                    default: 1500
                  cloudMaxWriteRequestsPerSecond:
                    description: The maximum number of write requests per second (default 250, 0 means unlimited)
                    type: integer
                    format: int32
                    x-has-default: true
                    default: 250
                  cloudRequestsHttpConnectionAcquireTimeout:
                    description: The waiting time (in seconds) to acquire an HTTP connection before failing the request. (default 120 seconds)
                    type: integer
                    format: int32
                    x-has-default: true
                    default: 120
                  cloudRequestsMaxHttpConnections:
                    description: The maximum number of HTTP connections to use concurrently for cloud requests per node. (default 1000)
                    type: integer
                    format: int32
                    x-has-default: true
                    default: 1000
                  cloudRequestsMaxPendingHttpConnections:
                    description: The maximum number of HTTP connections allowed to wait for a connection per node. (default 10000)
                    type: integer
                    format: int32
                    x-has-default: true
                    default: 10000
                  cloudStorageAllocationPercentage:
                    description: The percentage of the total disk space that should be allocated for data storage when the 'selective' caching policy is used. The remaining will act as a buffer for query workspace (i.e., for query operations that require spilling to disk). (default 80% of the total disk space)
                    type: number
                    format: double
                    x-has-default: true
                    default: 0.8
                  cloudStorageDiskMonitorInterval:
                    description: The disk monitoring interval time (in seconds) determines how often the system checks for pressure on disk space when using the 'selective' caching policy. (default 120 seconds)
                    type: integer
                    format: int32
                    x-has-default: true
                    default: 120
                  cloudStorageIndexInactiveDurationThreshold:
                    description: The duration in minutes to consider an index is inactive. (default 360 or 6 hours)
                    type: integer
                    format: int32
                    x-has-default: true
                    default: 360
                  cloudStorageSweepThresholdPercentage:
                    description: The percentage of the used storage space at which the disk sweeper starts freeing space by punching holes in stored indexes or by evicting them entirely, when the 'selective' caching policy is used. (default 90% of the allocated space for storage)
                    type: number
                    format: double
                    x-has-default: true
                    default: 0.9
                  cloudWriteBufferSize:
                    description: The write buffer size in bytes. (default 8MB, min 5MB)
                    type: integer
                    format: int32
                    x-has-default: true
                    default: 8388608
                  compilerCbo:
                    description: Set the mode for cost based optimization.
                    type: boolean
                    x-has-default: true
                    default: true
                  compilerColumnFilter:
                    description: Enable/disable the use of column min/max filters.
                    type: boolean
                    x-has-default: true
                    default: true
                  compilerCopyToWriteBufferSize:
                    description: The COPY TO write buffer size in bytes. (default 8MB, min 5MB).
                    type: integer
                    format: int32
                    x-has-default: true
                    default: 8388608
                  compilerExternalFieldPushdown:
                    description: Enable pushdown of field accesses to the external data-scan operator.
                    type: boolean
                    x-has-default: true
                    default: true
                  compilerFramesize:
                    description: The page size (in bytes) for computation.
                    type: integer
                    format: int32
                    x-has-default: true
                    default: 32768
                  compilerGroupmemory:
                    description: The memory budget (in bytes) for a group by operator instance in a partition.
                    type: integer
                    format: int32
                    x-has-default: true
                    default: 33554432
                  compilerJoinmemory:
                    description: The memory budget (in bytes) for a join operator instance in a partition.
                    type: integer
                    format: int32
                    x-has-default: true
                    default: 33554432
                  compilerRuntimeMemoryOverhead:
                    description: A percentage of the job's required memory to be added to account for runtime memory overhead.
                    type: integer
                    format: int32
                    x-has-default: true
                    default: 5
                  compilerSortmemory:
                    description: The memory budget (in bytes) for a sort operator instance in a partition.
                    type: integer
                    format: int32
                    x-has-default: true
                    default: 33554432
                  compilerWindowmemory:
                    description: The memory budget (in bytes) for a window operator instance in a partition.
                    type: integer
                    format: int32
                    x-has-default: true
                    default: 33554432
                  copyToKvBucketWaitUntilReadyTimeout:
                    description: The number of seconds to wait for COPY TO KV bucket WaitUntilReady before timing out.
                    type: integer
                    format: int32
                    x-has-default: true
                    default: 30
                  coresMultiplier:
                    description: The factor to multiply by the number of cores to determine maximum query concurrent execution level.
                    type: integer
                    format: int32
                    x-has-default: true
                    default: 3
                  dcpChannelConnectAttemptTimeout:
                    description: The maximum attempt time to connect to a DCP channel in seconds.
                    type: integer
                    format: int32
                    x-has-default: true
                    default: 120
                  dcpChannelConnectTotalTimeout:
                    description: The maximum time to wait to connect to a DCP channel in seconds.
                    type: integer
                    format: int32
                    x-has-default: true
                    default: 480
                  dcpConnectionBufferSize:
                    type: integer
                    description: |-
                      DCP connection buffer size (in bytes).

                      If the JVM maximum heap size is less than 8GB, the default for this parameter is 10 MB divided by the number of IO Devices on the node.
                      Otherwise, the default is 1% of the JVM maximum heap size divided by the number of IO Devices on the node.
                    format: int32
                    x-has-default: true
                    default: 1048576
                  jobQueueCapacity:
                    description: The maximum number of jobs to queue before rejecting new jobs.
                    type: integer
                    format: int32
                    x-has-default: true
                    default: 4096
                  jvmArgs:
                    description: |-
                      JVM arguments to pass to the Analytics Driver.
                      The default is undefined (null).

                      Note that JVM arguments are generally not secure, and are exposed by [cbcollect_info][1] and the [System Event][2] log.
                      To pass arguments opaquely, you may use [Java command-line argument files][3].

                      [1]: /server/7.6/cli/cbcollect-info-tool.html
                      [2]: /server/7.6/learn/clusters-and-availability/system-events.html
                      [3]: https://docs.oracle.com/en/java/javase/11/tools/java.html#GUID-4856361B-8BFD-4964-AE84-121F5F6CF111
                    type: string
                    nullable: true
                    x-has-default: false
                    default: null
                  kafkaMaxFetchBytes:
                    description: Maximum number of bytes fetched by a kafka consumer in one request.
                    type: integer
                    format: int32
                    x-has-default: true
                    default: 4194304
                  maxRedirectsRemoteLink:
                    description: The number of redirects to follow when communicating with a remote link cluster via http for remote links not configured to prevent redirects.
                    type: integer
                    format: int32
                    x-has-default: true
                    default: 10
                  maxWebRequestSize:
                    description: The maximum accepted web request size in bytes.
                    type: integer
                    format: int64
                    x-has-default: true
                    default: 209715200
                  rebalanceEjectDelaySeconds:
                    description: The delay (in seconds) before a node is ejected from the cluster during rebalance from the time that the health check API on that node will start reporting an error response. This is to allow adequate time for the node to removed from consideration by clients utilizing the health check API, to avoid failures on rebalance out; 0 == means no delay.
                    type: integer
                    format: int32
                    x-has-default: true
                    default: 0
                  remoteLinkConnectTimeoutSeconds:
                    description: |
                      The maximum time (in seconds) to wait for a remote link connection to establish. A value of 0 disables timeout; a value of -1 sets timeout to the system default.
                    type: integer
                    format: int32
                    x-has-default: true
                    default: 30
                  remoteLinkRefreshAuthSeconds:
                    description: The frequency at which permissions should be reevaluated for remote buckets/collections that may have been lost/restored for remote cluster versions at 7.0 or later; a value of 0 disables preemptive reevaluation.
                    type: integer
                    format: int32
                    x-has-default: true
                    default: 0
                  remoteLinkSocketTimeoutSeconds:
                    description: |
                      The maximum time (in seconds) to wait after establishing the connection for remote links; the maximum time of inactivity between two data packets. A value of 0 disables timeout; a value of -1 sets timeout to the system default.
                    type: integer
                    format: int32
                    x-has-default: true
                    default: 60
                  remoteLinkValidationMaxRetries:
                    description: The number of times to retry on a remote link credential / config validation connection failure, i.e. on CREATE or ALTER LINK (0 == don't retry).
                    type: integer
                    format: int32
                    x-has-default: true
                    default: 0
                  remoteStorageSizeMetricTtlMillis:
                    description: The length of time after which remote storage size metric is recomputed.
                    type: integer
                    format: int64
                    x-has-default: true
                    default: 300000
                  requestsArchiveSize:
                    description: The maximum number of archived requests to maintain.
                    type: integer
                    format: int32
                    x-has-default: true
                    default: 1000
                  resultTtl:
                    description: Limits the amount of time results for asynchronous jobs should be retained by the system in milliseconds.
                    type: integer
                    format: int64
                    x-has-default: true
                    default: 86400000
                  storageFormat:
                    description: The default storage format (either row or column).
                    type: string
                    x-has-default: true
                    default: column
                  storageMaxConcurrentFlushesPerPartition:
                    description: The maximum number of concurrently executed flushes per partition (0 means unlimited).
                    type: integer
                    format: int32
                    x-has-default: true
                    default: 1
                  storageMaxConcurrentMergesPerPartition:
                    description: The maximum number of concurrently executed merges per partition (0 means unlimited).
                    type: integer
                    format: int32
                    x-has-default: true
                    default: 1
                  storageMaxScheduledMergesPerPartition:
                    description: The maximum number of scheduled merges per partition (0 means unlimited).
                    type: integer
                    format: int32
                    x-has-default: true
                    default: 8
                  storageMemorycomponentMaxScheduledFlushes:
                    description: The maximum number of scheduled flush operations. 0 means that the value will be calculated as the number of partitions.
                    type: integer
                    format: int32
                    x-has-default: true
                    default: 0
                  txnDatasetCheckpointInterval:
                    description: The interval (in seconds) after which an Analytics collection is considered idle and persisted to disk.
                    type: integer
                    format: int32
                    x-has-default: true
                    default: 3600
        '401':
          description: |-
            Unauthorized.
            The user name or password may be incorrect.

            Returns an object containing an error message.
            Refer to [Error Codes](/server/7.6/analytics/error-codes.html).
          content: &ref_1
            application/json:
              schema:
                type: object
    put:
      operationId: put_service
      summary: Modify Service-Level Parameters
      description: |-
        Modifies service-level parameters, which apply to all nodes.

        IMPORTANT: For the configuration changes to take effect,
        you must restart the Enterprise Analytics Service using the [Service Restart API][1].

        [1]: /server/7.6/analytics-rest-admin.html#restart_cluster
      requestBody:
        description: An object specifying one or more of the configurable service-level parameters.
        content:
          application/json:
            schema:
              type: object
              properties: *ref_0
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties: *ref_0
      security:
        - AnalyticsManage: []
      responses:
        '200':
          description: The operation was successful.
        '400':
          description: |
            Bad request. Unknown parameter or incorrect value.
          content: &ref_3
            application/json:
              schema:
                type: object
                required: &ref_4
                  - error
                properties: &ref_5
                  error:
                    type: string
                    description: An error message.
        '401':
          description: |-
            Unauthorized.
            The user name or password may be incorrect.

            Returns an object containing an error message.
            Refer to [Error Codes](/server/7.6/analytics/error-codes.html).
          content: *ref_1
  /api/v1/config/node:
    get:
      operationId: get_node
      summary: View Node-Specific Parameters
      description: Views node-specific parameters, which apply to the node receiving the request.
      security:
        - AnalyticsManage: []
      responses:
        '200':
          description: |
            Success. Returns an object listing the configurable node-level parameters and their current values.
          content:
            application/json:
              schema:
                type: object
                properties: &ref_2
                  jvmArgs:
                    description: |-
                      JVM arguments to pass to the Analytics Driver.
                      The default is undefined (null).

                      Node-specific JVM arguments are appended to service-level JVM arguments.
                      If the same JVM argument appears in both the service-level arguments and the node-specific arguments, the node-specific argument takes priority.

                      Note that JVM arguments are generally not secure, and are exposed by [cbcollect_info] and the [System Event] log.
                      To pass arguments opaquely, you may use [Java command-line argument files][1].

                      [1]: https://docs.oracle.com/en/java/javase/11/tools/java.html#GUID-4856361B-8BFD-4964-AE84-121F5F6CF111
                    type: string
                    nullable: true
                    x-has-default: false
                    default: null
                  storageBuffercacheSize:
                    description: |-
                      The size of memory allocated to the disk buffer cache.
                      The value should be a multiple of the buffer cache page size.

                      The default is 1/4 of the allocated memory.
                    type: integer
                  storageMemorycomponentGlobalbudget:
                    description: |-
                      The size of memory allocated to the memory components.
                      The value should be a multiple of the memory component page size.

                      The default is 1/4 of the allocated memory.
                    type: integer
        '401':
          description: |-
            Unauthorized.
            The user name or password may be incorrect.

            Returns an object containing an error message.
            Refer to [Error Codes](/server/7.6/analytics/error-codes.html).
          content: *ref_1
    put:
      operationId: put_node
      summary: Modify Node-Specific Parameters
      description: |-
        Views node-specific parameters, which apply to the node receiving the request.

        IMPORTANT: For the configuration changes to take effect,
        you must restart the node using the [Node Restart API][1],
        or restart the Enterprise Analytics Service using the [Service Restart API][2].

        [1]: /server/7.6/analytics-rest-admin.html#restart_node
        [2]: /server/7.6/analytics-rest-admin.html#restart_service
      requestBody:
        description: An object specifying one or more of the configurable node-level parameters on this node.
        content:
          application/json:
            schema:
              type: object
              properties: *ref_2
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties: *ref_2
      security:
        - AnalyticsManage: []
      responses:
        '200':
          description: The operation was successful.
        '400':
          description: |
            Bad request. Unknown parameter or incorrect value.
          content: *ref_3
        '401':
          description: |-
            Unauthorized.
            The user name or password may be incorrect.

            Returns an object containing an error message.
            Refer to [Error Codes](/server/7.6/analytics/error-codes.html).
          content: *ref_1
components:
  schemas:
    Service:
      type: object
      properties: *ref_0
    Node:
      type: object
      properties: *ref_2
    Errors:
      type: object
      required: *ref_4
      properties: *ref_5
  responses:
    OK:
      description: The operation was successful.
    BadRequest:
      description: |
        Bad request. Unknown parameter or incorrect value.
      content: *ref_3
    Unauthorized:
      description: |-
        Unauthorized.
        The user name or password may be incorrect.

        Returns an object containing an error message.
        Refer to [Error Codes](/server/7.6/analytics/error-codes.html).
      content: *ref_1
  securitySchemes:
    AnalyticsManage:
      type: http
      scheme: basic
      description: |-
        Users must have one of the following RBAC roles:

        * Full Admin
        * Cluster Admin
        * Enterprise Analytics Admin
