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: 8.0

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

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

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)

readClusterSettings
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)

writeClusterSettings

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)

writeClusterSettings

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)

writeClusterSettings

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)

manageCluster

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)

manageCluster

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)

readClusterLogs

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)

readClusterLogs
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)

readClusterSettings

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)

readClusterSettings
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)

manageCluster

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)

manageCluster

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)

manageCluster

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.

Nullable: yes

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.

Nullable: yes

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.

Nullable: yes

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.

Nullable: yes

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

Nullable: yes

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

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

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

Nullable: yes

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

Nullable: yes

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.

manageCluster

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

Type: http

readClusterSettings

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

Type: http

readClusterLogs

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

Type: http

writeClusterSettings

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

Type: http

For more information, see Roles.