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.

Couchbase Search Node API

  • reference
    +

    Overview

    The Search Node Configuration REST API is provided by the Search service. This API enables you to manage and monitor your Search nodes.

    Version information

    Version : 7.6

    Host information

    {scheme}://{host}:{port}

    The URL scheme, host, and port are as follows.

    Component Description

    scheme

    The URL scheme. Use https for secure access.

    Values: http, https
    Example: http

    host

    The host name or IP address of a node running the Search Service.

    Example: localhost

    port

    The Search Service REST port. Use 18094 for secure access.

    Values: 8094, 18094
    Example: 8094

    Resources

    This section describes the operations available with this REST API. The operations are grouped in the following categories.

    Configuration
    Diagnostics
    Management
    Monitoring

    Configuration

    Operations for node configuration.

    Get Cluster Configuration
    Replan Resource Assignments
    Get Node Capabilities
    Refresh Node Configuration

    Get Cluster Configuration

    GET /api/cfg
    Description

    Returns the node's current view of the cluster's configuration as JSON.

    Produces

    • application/json

    Responses
    HTTP Code Description Schema

    200

    A JSON object containing the node's configuration.

    Cluster Configuration
    Security
    Type Name

    http (basic)

    Read Cluster Settings
    Example HTTP Response
    Response 200
    {
  "indexDefs": {
    "implVersion": "4.0.0",
    "indexDefs": {
      "myFirstIndex": {
        "name": "myFirstIndex",
        "params": "",
        "planParams": {
          "hierarchyRules": null,
          "maxPartitionsPerPIndex": 0,
          "nodePlanParams": null,
          "numReplicas": 0,
          "planFrozen": false
        },
        "sourceName": "",
        "sourceParams": "",
        "sourceType": "nil",
        "sourceUUID": "",
        "type": "blackhole",
        "uuid": "6cc599ab7a85bf3b"
      }
    },
    "uuid": "6cc599ab7a85bf3b"
  },
  "indexDefsCAS": 3,
  "indexDefsErr": null,
  "nodeDefsKnown": {
    "implVersion": "4.0.0",
    "nodeDefs": {
      "78fc2ffac2fd9401": {
        "container": "",
        "extras": "",
        "hostPort": "0.0.0.0:8094",
        "implVersion": "4.0.0",
        "tags": null,
        "uuid": "78fc2ffac2fd9401",
        "weight": 1
      }
    },
    "uuid": "2f0d18fb750b2d4a"
  },
  "nodeDefsKnownCAS": 1,
  "nodeDefsKnownErr": null,
  "nodeDefsWanted": {
    "implVersion": "4.0.0",
    "nodeDefs": {
      "78fc2ffac2fd9401": {
        "container": "",
        "extras": "",
        "hostPort": "0.0.0.0:8094",
        "implVersion": "4.0.0",
        "tags": null,
        "uuid": "78fc2ffac2fd9401",
        "weight": 1
      }
    },
    "uuid": "72d6750878551451"
  },
  "nodeDefsWantedCAS": 2,
  "nodeDefsWantedErr": null,
  "planPIndexes": {
    "implVersion": "4.0.0",
    "planPIndexes": {
      "myFirstIndex_6cc599ab7a85bf3b_0": {
        "indexName": "myFirstIndex",
        "indexParams": "",
        "indexType": "blackhole",
        "indexUUID": "6cc599ab7a85bf3b",
        "name": "myFirstIndex_6cc599ab7a85bf3b_0",
        "nodes": {
          "78fc2ffac2fd9401": {
            "canRead": true,
            "canWrite": true,
            "priority": 0
          }
        },
        "sourceName": "",
        "sourceParams": "",
        "sourcePartitions": "",
        "sourceType": "nil",
        "sourceUUID": "",
        "uuid": "64bed6e2edf354c3"
      }
    },
    "uuid": "6327debf817a5ec7",
    "warnings": {
      "myFirstIndex": []
    }
  },
  "planPIndexesCAS": 5,
  "planPIndexesErr": null,
  "status": "ok"
}

    Replan Resource Assignments

    POST /api/managerKick
    Description

    Forces the node to replan resource assignments, (by running the planner, if enabled) and update its runtime state to reflect the latest plan (by running the janitor, if enabled).

    Responses
    HTTP Code Description Schema

    200

    Success.
    Security
    Type Name

    http (basic)

    Write Cluster Settings

    Get Node Capabilities

    GET /api/managerMeta
    Description

    Returns information on the node's capabilities, including available indexing and storage options as JSON. This operation is intended to help management tools and web UIs to be more dynamically metadata driven.

    Produces

    • application/json

    Responses
    HTTP Code Description Schema

    200

    A JSON object containing the node's capabilities.

    Object
    Security
    Type Name

    http (basic)

    Write Cluster Settings

    Refresh Node Configuration

    POST /api/cfgRefresh
    Description

    Requests the node to refresh its configuration from the configuration provider.

    Responses
    HTTP Code Description Schema

    200

    Success.
    Security
    Type Name

    http (basic)

    Write Cluster Settings

    Diagnostics

    Operations for node diagnostics.

    Capture CPU Profiling Information
    Capture Memory Profiling Information
    Get Diagnostics
    Get Node Logs
    Get Node Runtime Arguments
    Get Node Runtime Information

    Capture CPU Profiling Information

    POST /api/runtime/profile/cpu
    Description

    Requests the node to capture local CPU usage profiling information.

    Responses
    HTTP Code Description Schema

    200

    Success.
    Security
    Type Name

    http (basic)

    Manage Cluster

    Capture Memory Profiling Information

    POST /api/runtime/profile/memory
    Description

    Requests the node to capture local memory usage profiling information.

    Responses
    HTTP Code Description Schema

    200

    Success.
    Security
    Type Name

    http (basic)

    Manage Cluster

    Get Diagnostics

    GET /api/diag
    Description

    Returns the full set of diagnostic information from the node as JSON. The response is the union of the responses from the node's other REST API diagnostic and monitoring endpoints.

    For example, for a 3 node cluster, you could capture diagnostics for each node with something like:

    curl http://cbft-01:8094/api/diag > cbft-01.json
curl http://cbft-02:8094/api/diag > cbft-02.json
curl http://cbft-03:8094/api/diag > cbft-03.json

    The response JSON object can be quite large, 100s of KB or much more.

    The motivation for this operation is to simplify working with the Couchbase community, forums, technical support, and other engineers, by making data capture from each Search node a single step.

    Produces

    • application/json

    Responses
    HTTP Code Description Schema

    200

    A JSON object containing the node's diagnostics.

    Object
    Security
    Type Name

    http (basic)

    Read Cluster Logs

    Get Node Logs

    GET /api/log
    Description

    Returns recent log messages and key events for the node as JSON.

    Produces

    • application/json

    Responses
    HTTP Code Description Schema

    200

    A JSON object containing the node's logs.

    Log Messages
    Security
    Type Name

    http (basic)

    Read Cluster Logs
    Example HTTP Response
    Response 200
    {
  "events": [],
  "messages": []
}

    Get Node Runtime Arguments

    GET /api/runtime/args
    Description

    Returns information on the node's command-line, parameters, environment variables, and OS process values as JSON.

    Produces

    • application/json

    Responses
    HTTP Code Description Schema

    200

    A JSON object containing the node's runtime arguments.

    Object
    Security
    Type Name

    http (basic)

    Read Cluster Settings

    Get Node Runtime Information

    GET /api/runtime
    Description

    Returns information on the node's software, such as version strings and slow-changing runtime settings, as JSON.

    Produces

    • application/json

    Responses
    HTTP Code Description Schema

    200

    A JSON object containing the node's runtime information.

    Runtime Information
    Security
    Type Name

    http (basic)

    Read Cluster Settings
    Example HTTP Response
    Response 200
    {
  "arch": "amd64",
  "go": {
      "GOMAXPROCS": 1,
      "GOROOT": "/usr/local/go",
      "compiler": "gc",
      "version": "go1.4"
  },
  "numCPU": 8,
  "os": "darwin",
  "versionData": "4.0.0",
  "versionMain": "v0.3.1"
}

    Management

    Operations for node management.

    Perform Garbage Collection

    Perform Garbage Collection

    POST /api/runtime/gc
    Description

    Requests the node to perform a garbage collection.

    Responses
    HTTP Code Description Schema

    200

    Success.
    Security
    Type Name

    http (basic)

    Manage Cluster

    Monitoring

    Operations for node monitoring.

    Get Memory Statistics
    Get Runtime Statistics

    Get Memory Statistics

    GET /api/runtime/statsMem
    Description

    Returns information on the node's low-level garbage collection and memory-related runtime stats as JSON.

    Produces

    • application/json

    Responses
    HTTP Code Description Schema

    200

    A JSON object containing the node's memory statistics.

    Object
    Security
    Type Name

    http (basic)

    Manage Cluster

    Get Runtime Statistics

    GET /api/runtime/stats
    Description

    Returns information on the node's low-level runtime stats as JSON.

    Produces

    • application/json

    Responses
    HTTP Code Description Schema

    200

    A JSON object containing the node's low-level runtime statistics.

    Object
    Security
    Type Name

    http (basic)

    Manage Cluster

    Definitions

    This section describes the properties consumed and returned by this REST API.

    Cluster Configuration
    Index Definitions
    Known Nodes
    Wanted Nodes
    Node Definitions Wrapper
    Node Definition
    Plan Partitions
    Plan Partitions Wrapper
    Plan Partition
    Partition Nodes Wrapper
    Partition Node
    Plan Warnings Wrapper
    Plan Warnings
    Index Definitions Wrapper
    Index Definition
    Plan Parameters
    Log Messages
    Runtime Information
    Go Runtime Information

    Cluster Configuration

    Object

    Property Schema

    indexDefs
    optional

    An object containing Search index definitions and related information.

    Index Definitions

    indexDefsCAS
    optional

    Search index definition concurrency (compare and swap) value.

    Integer

    indexDefsErr
    optional

    Search index definition error.

    String

    nodeDefsKnown
    optional

    An object containing known node definitions and related information.

    Known Nodes

    nodeDefsKnownCAS
    optional

    Known node definition concurrency (compare and swap) value.

    Integer

    nodeDefsKnownErr
    optional

    Known node definition error.

    String

    nodeDefsWanted
    optional

    An object containing wanted node definitions and related information.

    Wanted Nodes

    nodeDefsWantedCAS
    optional

    Wanted node definition concurrency (compare and swap) value.

    Integer

    nodeDefsWantedErr
    optional

    Wanted node definition error.

    String

    planPIndexes
    optional

    An object containing Search index partitions and related information.

    Plan Partitions

    planPIndexesCAS
    optional

    Search index partition concurrency (compare and swap) value.

    Integer

    planPIndexesErr
    optional

    Search index partition error.

    String

    status
    optional

    The status of the operation.

    String

    Index Definitions

    Object

    Property Schema

    implVersion
    optional

    String

    indexDefs
    optional

    An object containing 1 or more Search index definitions.

    Index Definitions Wrapper

    Known Nodes

    Object

    Property Schema

    implVersion
    optional

    String

    nodeDefs
    optional

    An object containing the definitions of 1 or more nodes.

    Node Definitions Wrapper

    uuid
    optional

    String

    Wanted Nodes

    Object

    Property Schema

    implVersion
    optional

    String

    nodeDefs
    optional

    An object containing the definitions of 1 or more nodes.

    Node Definitions Wrapper

    uuid
    optional

    String

    Node Definitions Wrapper

    Object

    Property Schema

    additional
    property

    An object containing the definition of a single node. The name of the property is the UUID of the node.

    Node Definition

    Node Definition

    Object

    Property Schema

    container
    optional

    String

    extras
    optional

    String

    hostPort
    optional

    String

    implVersion
    optional

    String

    tags
    optional

    String

    uuid
    optional

    String

    weight
    optional

    Integer

    Plan Partitions

    Object

    Property Schema

    implVersion
    optional

    String

    planPIndexes
    optional

    An object containing information about 1 or more Search index partitions.

    Plan Partitions Wrapper

    uuid
    optional

    String

    warnings
    optional

    An object containing 0, 1, or more nested objects, each containing warnings that apply to a Search index.

    Plan Warnings Wrapper

    Plan Partitions Wrapper

    Object

    Property Schema

    additional
    property

    An object containing information about a single Search index partition.

    Plan Partition

    Plan Partition

    Object

    Property Schema

    indexName
    optional

    The name of the Search index. For more information, see Initial Settings.

    String

    indexParams
    optional

    The Search index's type identifier, type mappings, and analyzers. For more information, see Params Object.

    Object

    indexType
    optional

    The type of the Search index. For more information, see Initial Settings.

    String

    indexUUID
    optional

    The UUID of the Search index. For more information, see Initial Settings.

    String

    name
    optional

    The name of the Search index partition.

    String

    nodes
    optional

    An object containing information about 1 or more Search index partition nodes.

    Partition Nodes Wrapper

    sourceName
    optional

    The name of the bucket where the Search index is stored. For more information, see Initial Settings.

    String

    sourceParams
    optional

    Advanced settings for Search index behavior. For more information, see Initial Settings.

    Object

    sourcePartitions
    optional

    String

    sourceType
    optional

    The type of the bucket where the Search index is stored. For more information, see Initial Settings.

    String

    sourceUUID
    optional

    The UUID of the bucket where the Search index is stored. For more information, see Initial Settings.

    String

    uuid
    optional

    The UUID of the Search index partition.

    String

    Partition Nodes Wrapper

    Object

    Property Schema

    additional
    property

    An object containing information about a single Search index partition node. The name of the property is the node UUID.

    Partition Node

    Partition Node

    Object

    Property Schema

    canRead
    optional

    Boolean

    canWrite
    optional

    Boolean

    priority
    optional

    Integer

    Plan Warnings Wrapper

    Object

    Property Schema

    additional
    property

    Plan Warnings

    Plan Warnings

    Array

    An array of warnings. The name of the property is the name of the Search index.

    Schema

    String

    array

    Index Definitions Wrapper

    Object

    Property Schema

    additional
    property

    The full Search index definition. For a detailed list of all parameters, see Search Index JSON Properties.

    Index Definition

    Index Definition

    Object

    Property Schema

    name
    required

    The name of the Search index. For more information, see Initial Settings.

    String

    type
    required

    The type of the Search index. For more information, see Initial Settings.

    String

    sourceName
    required

    The name of the bucket where the Search index is stored. For more information, see Initial Settings.

    String

    sourceUUID
    optional

    The UUID of the bucket where the Search index is stored. For more information, see Initial Settings.

    String

    sourceParams
    optional

    Advanced settings for Search index behavior. For more information, see Initial Settings.

    Object

    sourceType
    required

    The type of the bucket where the Search index is stored. For more information, see Initial Settings.

    String

    params
    required

    The Search index's type identifier, type mappings, and analyzers. For more information, see Params Object.

    Object

    planParams
    required

    The Search index's partitioning and replication settings. For more information, see Plan Params Object.

    Plan Parameters

    prevIndexUUID
    optional

    The UUID of the previous index. Intended for clients that want to check that they are not overwriting the Search index definition updates of concurrent clients.

    String

    uuid
    optional

    The UUID of the Search index. For more information, see Initial Settings.

    String

    Plan Parameters

    Object

    Property Schema

    hierarchyRules
    optional

    String

    maxPartitionsPerPIndex
    optional

    This setting is deprecated. Use indexPartitions instead.

    Integer

    indexPartitions
    optional

    The number of partitions to split the Search index into, across the nodes you have available in your database with the Search Service enabled.

    Integer

    nodePlanParams
    optional

    String

    numReplicas
    optional

    The number of replicas the Search Service creates for the Search index to ensure high availability.

    Integer

    planFrozen
    optional

    Boolean

    Log Messages

    Object

    Property Schema

    events
    optional

    Object array

    messages
    optional

    Object array

    Runtime Information

    Object

    Property Schema

    arch
    optional

    The architecture of the node.

    String

    go
    optional

    Go Runtime Information

    numCPU
    optional

    The number of CPUs on the node.

    Integer

    os
    optional

    The operating system of the node.

    String

    versionData
    optional

    String

    versionMain
    optional

    String

    Go Runtime Information

    Object

    Property Schema

    GOMAXPROCS
    optional

    Integer

    GOROOT
    optional

    String

    compiler
    optional

    String

    version
    optional

    String

    Security

    The Search REST APIs support HTTP basic authentication. Pass your credentials through HTTP headers.

    Manage Cluster

    You must have the Full Admin or Cluster Admin role, with permissions to manage the cluster.

    Type : http

    Read Cluster Settings

    You must have the Full Admin or Cluster Admin role, with permission to read cluster settings.

    Type : http

    Read Cluster Logs

    You must have the Full Admin or Cluster Admin role, with permission to read cluster logs.

    Type : http

    Write Cluster Settings

    You must have the Full Admin or Cluster Admin role, with permission to write cluster settings.

    Type : http

    For more information, see Roles.