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 Advanced API

  • reference

Overview

The Advanced Search REST APIs are provided by the Search service. These APIs enable you to manage and query Search index partitions and to specify advanced settings.

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.

Definition
Query
Quota

Definition

Operations for Search index partition definition.

Get Index Partition Information
Get Index Partition by Name

Get Index Partition Information

GET /api/pindex
Description

Get information about a Search index partition.

Produces

  • application/json

Responses
HTTP Code Description Schema

200

A JSON object containing the Search index partition information.

Index Partitions
Security
Type Name

http (basic)

Read
Example HTTP Response
Response 200
{
  "pindexes" : {
    "myFirstIndex_6cc599ab7a85bf3b_0" : {
      "indexName" : "myFirstIndex",
      "indexParams" : "",
      "indexType" : "blackhole",
      "indexUUID" : "6cc599ab7a85bf3b",
      "name" : "myFirstIndex_6cc599ab7a85bf3b_0",
      "sourceName" : "",
      "sourceParams" : "",
      "sourcePartitions" : "",
      "sourceType" : "nil",
      "sourceUUID" : "",
      "uuid" : "2d9ecb8b574a9f6a"
    }
  },
  "status" : "ok"
}

Get Index Partition by Name

GET /api/pindex/{pindexName}
Description

Get information about a specific Search index partition by name.

Parameters
Path Parameters

Name Description Schema

pindexName
required

The name of the Search index partition.

String
Responses
HTTP Code Description Schema

200

Success
Security
Type Name

http (basic)

Read

Query

Operations for querying Search index partitions.

Get Index Partition Document Count
Query Index Partition

Get Index Partition Document Count

GET /api/pindex/{pindexName}/count
Description

Get the document count of a specific Search index partition.

Produces

  • application/json

Parameters
Path Parameters

Name Description Schema

pindexName
required

The name of the Search index partition.

String
Responses
HTTP Code Description Schema

200

The Search Service returns a response that includes the status ok.

Document Count
Security
Type Name

http (basic)

Read

Query Index Partition

POST /api/pindex/{pindexName}/query
Description

Execute a query against a specific Search index partition by name.

Consumes

  • application/json

Produces

  • application/json

Parameters
Path Parameters

Name Description Schema

pindexName
required

The name of the Search index partition.

String
Body Parameter

Name Description Schema

Body
required

A JSON object to define the settings for your Search query. For more information about how to create a Search query JSON object, see Search Request JSON Properties.

Query Request
Responses
HTTP Code Description Schema

200

The response object has a status section that must be checked for every request. Under nearly all circumstances, the query response will be HTTP 200 even though individual index shards (partitions) may encounter a timeout or return an error.

Query Response
Security
Type Name

http (basic)

Write

Quota

Operations for managing Search memory quota.

Set Search Memory Quota

Set Search Memory Quota

POST /pools/default
Description

Sets the memory quota for the Search Service.

Consumes

  • application/x-www-form-urlencoded

Parameters
Form Parameters

Name Description Schema

ftsMemoryQuota
optional

The memory quota for the Search service.

Example: 56

Integer
Responses
HTTP Code Description Schema

200

Memory quota set.
Security
Type Name

http (basic)

Manage

Definitions

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

Document Count
Index Partitions
Index Partitions Wrapper
Index Partition
Query Request
Query Response

Document Count

Object

Property Schema

status
optional

The status of the operation.

String

count
optional

The document count for the specified index.

Integer

Index Partitions

Object

Property Schema

pindexes
optional

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

Index Partitions Wrapper

status
optional

The status of the request.

String

Index Partitions Wrapper

Object

Property Schema

additional
property

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

Index Partition

Index 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

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

Query Request

Object

Property Schema

query
optional

An object that contains the properties for one of the supported query types. For more information, see Query Object.

Object

knn
optional

An array that contains objects that describe a Vector Search query. For more information, see Knn Objects.

Object array

ctl
optional

An object that contains properties for query consistency. For more information, see Ctl Object.

Object

size
optional

Set the total number of results to return for a single page of search results.

Integer

from
optional

Set an offset value to change where pagination starts for search results.

Integer

highlight
optional

Contains properties to control search result highlighting. For more information, see Highlight Objects.

Object

fields
optional

An array of strings to specify each indexed field you want to return in search results.

String array

facets
optional

Contains nested objects to define each facet you want to return with search results. For more information, see Facet Objects.

Object

explain
optional

Whether to create an explanation for a search result's score in search results.

Boolean

sort
optional

Contains an array of strings or JSON objects to set how to sort search results. For more information, see Sort Object.

Any Type array

includeLocations
optional

Whether to return the position of each occurrence of a search term inside a document.

Boolean

score
optional

Whether to include document relevancy scoring in search results.

String

search_after
optional

Use to control pagination in search results.

String array

search_before
optional

Use to control pagination in search results.

String array

collections
optional

An array of strings that specify the collections where you want to run the query.

String array

Query Response

Object

Property Schema

status
optional

The status of the operation.

String

results
optional

The results of the Search query.

Object array

Security

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

Manage

You must have the Search Admin role, with FTS Manage permissions on the required bucket.

Type: http

Read

You must have the Search Reader or Search Admin role, with FTS Read permissions on the required bucket.

Type: http

Write

You must have the Search Admin role, with FTS Write permissions on the required bucket.

Type: http

For more information, see Roles.