openapi: 3.0.3
info:
  title: Index Statistics REST API
  version: '7.6'
  license:
    name: Business Source License 1.1
    url: https://github.com/couchbaselabs/cb-swagger/blob/release/7.6/licenses/BSL-Couchbase.txt
  description: |-
    The Index Statistics REST API is provided by the Index service.
    This API enables you to get Index service statistics.

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 running the Index Service.
      port:
        default: "9102"
        description: |-
          The Index Service REST port.
          Use `19102` for secure access.
        enum:
          - "9102"
          - "19102"

paths:
  /api/v1/stats:
    parameters:
      - $ref: "#/components/parameters/QueryPretty"
      - $ref: "#/components/parameters/QueryRedact"
      - $ref: "#/components/parameters/QuerySkipEmpty"
    get:
      operationId: get_node_stats
      summary: Get Statistics for an Index Node
      description: Returns statistics for an index node, and for all indexes on that node.
      security:
        - NodeStatistics: []
        - IndexStatistics: []
      responses:
        "200":
          $ref: '#/components/responses/Node'

  /api/v1/stats/{keyspace}:
    parameters:
      - $ref: "#/components/parameters/PathKeyspace"
      - $ref: "#/components/parameters/QueryPretty"
      - $ref: "#/components/parameters/QueryRedact"
      - $ref: "#/components/parameters/QuerySkipEmpty"
    get:
      operationId: get_keyspace_stats
      summary: Get Statistics for Indexes in a Keyspace
      description: Returns statistics for all indexes within a bucket, scope, or collection.
      security:
        - IndexStatistics: []
      responses:
        "200":
          $ref: '#/components/responses/Keyspace'
        "404":
          $ref: '#/components/responses/NotFound'

  /api/v1/stats/{keyspace}/{index}:
    parameters:
      - $ref: "#/components/parameters/PathKeyspace"
      - $ref: "#/components/parameters/PathIndex"
      - $ref: "#/components/parameters/QueryPretty"
      - $ref: "#/components/parameters/QueryPartition"
      - $ref: "#/components/parameters/QueryRedact"
      - $ref: "#/components/parameters/QuerySkipEmpty"
    get:
      operationId: get_index_stats
      summary: Get Statistics for an Index
      description: Returns statistics for an index.
      security:
        - IndexStatistics: []
      responses:
        "200":
          $ref: '#/components/responses/Index'
        "404":
          $ref: '#/components/responses/NotFound'

components:
 parameters:
  PathKeyspace:
    name: keyspace
    schema:
      type: string
    in: path
    required: true
    description: |
      The name of a keyspace.
      This must contain a bucket name, which may be followed by an optional scope name and an optional collection name, separated by dots.
      For example, `bucket.scope.collection`.


      If any part of the keyspace name contains a dot, that part of the keyspace name must be wrapped in backticks.
      For example, `` `bucket.1`.scope.collection ``.

  PathIndex:
    name: index
    schema:
      type: string
    in: path
    required: true
    description: The name of an index.

  QueryPretty:
    name: pretty
    schema:
      type: boolean
      default: false
    in: query
    required: false
    x-has-default: true
    description: Whether the output should be formatted with indentations and newlines.
    
  QueryPartition:
    name: partition
    schema:
      type: boolean
      default: false
    in: query
    required: false
    x-has-default: true
    description: Whether statistics for index partitions should be included.

  QueryRedact:
    name: redact
    schema:
      type: boolean
      default: false
    in: query
    required: false
    x-has-default: true
    description: >
      Whether keyspace and index names should be redacted in the output.

  QuerySkipEmpty:
    name: skipEmpty
    schema:
      type: boolean
      default: false
    in: query
    required: false
    x-has-default: true
    description: Whether empty, null, or zero statistics should be omitted from the output.

 schemas:

  NodeIdx:
    type: object
    title: Node and Indexes
    allOf:
      - $ref: "#/components/schemas/NodeIdxNode"
      - $ref: "#/components/schemas/PartIdxIndexes"

  NodeIdxNode:
    type: object
    title: Nodes
    description: Node statistics.
    required:
      - indexer
    properties:
      indexer:
        $ref: "#/components/schemas/NodeIdxNodeIndexer"

  NodeIdxNodeIndexer:
    type: object
    title: Node
    description: A nested object containing statistics for the current index node.
    properties:
      indexer_state:
        type: string
        description: Current state of the Index service on this node.
        enum: ["Active","Pause","Warmup"]
        x-has-example: true
        example: Active
      memory_quota:
        type: integer
        format: int64
        description: Memory quota assigned to the Index service on this node by user configuration (bytes).
        x-has-default: true
        x-has-example: true
        example: 536870912
        default: 268435456
        maximum: 1099511992567
      memory_total_storage:
        type: integer
        x-desc-edition: "{enterprise}"
        description: |
          The total size allocated in the indexer across all indexes (bytes).
          This also accounts for memory fragmentation.
        x-has-example: true
        example: 71794688
      memory_used:
        type: integer
        description: Amount of memory used by the Index service on this node (bytes).
        x-has-example: true
        example: 360192000
      total_indexer_gc_pause_ns:
        type: integer
        description: The total time the indexer has spent in GC pause since last startup (ns).
        x-has-example: true
        example: 309778455

  PartIdx:
    type: object
    title: Index and Partitions
    allOf:
      - $ref: "#/components/schemas/PartIdxIndexes"
      - $ref: "#/components/schemas/PartIdxPartitions"

  PartIdxIndexes:
    type: object
    title: Indexes
    description: Index statistics.
    additionalProperties:
      $ref: "#/components/schemas/PartIdxPartitionsIndex"

  PartIdxPartitions:
    type: object
    title: Partitions
    description: Index partition statistics.
    additionalProperties:
      $ref: "#/components/schemas/PartIdxPartitionsIndex"

  PartIdxPartitionsIndex:
    type: object
    title: Index
    description: A nested object containing statistics for an index or index partition.
    properties:
      avg_array_length:
        type: integer
        description: |
          (Array indexes only.)
          The average number of items indexed per document.
      avg_drain_rate:
        type: integer
        description: Average number of items flushed from memory to disk storage per second.
      avg_item_size:
        type: integer
        description: Average size of the keys.
      avg_scan_latency:
        type: integer
        description: Average time to serve a scan request (nanoseconds).
      cache_hit_percent:
        type: integer
        x-desc-edition: "{enterprise}"
        description: Percentage of memory accesses that were served from the managed cache.
      cache_hits:
        type: integer
        description: Accesses to this index data from RAM.
      cache_misses:
        type: integer
        description: Accesses to this index data from disk.
      data_size:
        type: integer
        description: The size of indexable data that is maintained for the index or partition (bytes).
        x-has-example: true
        example: 95728
      disk_size:
        type: integer
        description: Total disk file size consumed by the index or partition.
        x-has-example: true
        example: 889054
      docid_count:
        type: integer
        description: |
          (Array indexes only.)
          The number of documents currently indexed.
      frag_percent:
        type: integer
        description: |
          Percentage fragmentation of the index.
          
          TIP: At small index sizes of less than a hundred kB, the static overhead of the index disk file will inflate the index fragmentation percentage.
      initial_build_progress:
        type: integer
        description: |
          Percentage initial build progress for the index.
          When initial build is completed, the value is `100`.

          For an index partition, the value is listed as `0`.
        x-has-example: true
        example: 100
      items_count:
        type: integer
        description: The number of items currently indexed.
        x-has-example: true
        example: 2155
      last_known_scan_time:
        type: integer
        format: int64
        description: |
          Time of the last scan request received for this index (Unix timestamp in nanoseconds).
          This may be useful for determining whether this index is currently unused.

          NOTE: This statistic is persisted to disk every 15 minutes, so it is preserved when the indexer restarts.
      num_docs_indexed:
        type: integer
        description: Number of documents indexed by the indexer since last startup.
      num_docs_pending:
        type: integer
        description: Number of documents pending to be indexed.
      num_docs_queued:
        type: integer
        description: Number of documents queued to be indexed.
      num_items_flushed:
        type: integer
        description: Number of items flushed from memory to disk storage.
      num_pending_requests:
        type: integer
        description: Number of requests received but not yet served by the indexer.
      num_requests:
        type: integer
        description: Number of requests served by the indexer since last startup.
      num_rows_returned:
        type: integer
        description: Total number of rows returned so far by the indexer.
      num_scan_errors:
        type: integer
        description: Number of requests that failed due to errors other than timeout.
      num_scan_timeouts:
        type: integer
        description: Number of requests that timed out, either waiting for snapshots or during scan in progress.
      recs_in_mem:
        type: integer
        x-desc-edition: "{enterprise}"
        description: |
          For standard index storage, this is the number of records in this index that are stored in memory.

          For memory-optimized index storage, this is the same as `items_count`.
        x-has-example: true
        example: 2155
      recs_on_disk:
        type: integer
        x-desc-edition: "{enterprise}"
        description: For standard index storage, this is the number of records in this index that are stored on disk.

          For memory-optimized index storage, this is `0`.
      resident_percent:
        type: integer
        x-desc-edition: "{enterprise}"
        description: Percentage of the data held in memory.
        x-has-example: true
        example: 100
      scan_bytes_read:
        type: integer
        description: Number of bytes read by a scan since last startup.
      total_scan_duration:
        type: integer
        description: Total time spent by the indexer in scanning rows since last startup (nanoseconds).

 responses:
  NotFound:
    description: |
      Not found.
      Returns the complete specified keyspace name, and the specified index name if provided.

      The keyspace name may be incorrect, the keyspace may contain no indexes, the index may not be located in the specified keyspace, or the index may be warming up after a restart.

  Node:
    description: |
      Success.
      Returns an object containing a nested `indexer` object, and usually one or more nested `<keyspace>:<index>` objects &mdash; one for each index found on the specified node.
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/NodeIdx"

  Keyspace:
    description: |
      Success.
      Returns an object containing one or more nested `<keyspace>:<index>` objects &mdash; one for each index found within the specified bucket, scope, or collection.
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/PartIdxIndexes"

  Index:
    description: |
      Success.
      Returns an object containing one nested `<keyspace>:<index>` object.

      If the [partition](#get_index_stats-parameters) query parameter was set to `true`, the returned object also contains one or more `Partition-<num>` objects &mdash; one for each index partition found on the specified node.
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/PartIdx"

 securitySchemes:
  NodeStatistics:
    x-displayName: Node Statistics
    type: http
    scheme: basic
    description: |
      To get [Node statistics](#NodeIdxNodeIndexer), users must have the Query System Catalog RBAC role.

  IndexStatistics:
    x-displayName: Index Statistics
    type: http
    scheme: basic
    description: |
      To get [Index statistics](#PartIdxPartitionsIndex) for all indexes in a bucket, scope, or collection, users must have the Query System Catalog RBAC role, or the Query Manage Index RBAC role with permissions on that bucket, scope, or collection.


      To get [Index statistics](#PartIdxPartitionsIndex) for an individual index, users must have the Query System Catalog RBAC role, or the Query Manage Index RBAC role with permissions on the bucket, scope, and collection containing that index.