Indexes

Index Definition

GET /api/index

Returns all index definitions as JSON.

Permission Required: cluster.bucket[bucket_name].fts!read

Role Required: FTS-Admin

Sample Response

{
    "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": "fulltext-index",
             "uuid": "6cc599ab7a85bf3b"
          }
       },
       "uuid": "6cc599ab7a85bf3b"
    },
    "status": "ok"
}

GET /api/index/{indexName}

Returns the definition of an index as JSON.

Permission Required: cluster.bucket[bucket_name].fts!read

Role Required: FTS-Admin

Parameters

indexName: required, string, URL path parameter

The name of the index definition to be retrieved.

Sample response

{
    "indexDef": {
        "name": "myFirstIndex",
        "params": "",
        "planParams": {
            "hierarchyRules": null,
            "maxPartitionsPerPIndex": 0,
            "nodePlanParams": null,
            "numReplicas": 0,
            "planFrozen": false
        },
        "sourceName": "",
        "sourceParams": "",
        "source
            ": "nil",
        "sourceUUID": "",
        "type": "fulltext-index",
        "uuid": "6cc599ab7a85bf3b"
      },
      "planPIndexes": [
        {
         "indexName": "myFirstIndex",
         "indexParams": "",
         "indexType": "bleve",
         "indexUUID": "6cc599ab7a85bf3b",
         "name": "myFirstIndex_6cc599ab7a85bf3b_0",
         "nodes": {
            "78fc2ffac2fd9401": {
              "canRead": true,
              "canWrite": true,
              "priority": 0
            }
         },
         "sourceName": "",
         "sourceParams": "",
         "sourcePartitions": "",
         "sourceType": "nil",
         "sourceUUID": "",
         "uuid": "64bed6e2edf354c3"
         }
       ],
       "status": "ok",
       "warnings": []
       }

PUT /api/index/{indexName}

Creates/updates an index definition.

Permission Required: cluster.bucket[bucket_name].fts!write

Role Required: FTS-Admin

Parameters

indexName: required, string, URL path parameter

The name of the to-be-created/updated index definition, validated with the regular expression ^[A-Za-z][0-9A-Za-z_\-]*$.

indexParams: optional (depends on the value of the indexType), string (JSON), form parameter

For indexType alias, an example indexParams JSON:

{
    "targets": {
        "yourIndexName": {
            "indexUUID": ""
        }
     }
}

For indexType bleve, an example indexParams JSON:

{
    "mapping": {
        "default_mapping": {
            "enabled": true,
            "dynamic": true,
            "default_analyzer": ""
         },
         "type_field": "_type",
         "default_type": "_default",
         "default_analyzer": "standard",
         "default_datetime_parser": "dateTimeOptional",
         "default_field": "_all",
         "byte_array_converter": "json",
         "analysis": {}
     },
     "store": {
          "kvStoreName": "mossStore"
     }
     }

indexType: required, string, form parameter

Supported index types include:
- alias: an alias provides a naming level of indirection to one or more actual, target indexes
- bleve: a full-text index powered by the bleve engine
planParams: optional, string (JSON), form parameter
prevIndexUUID: optional, string, form parameter

Intended for clients that want to check that they are not overwriting the index definition updates of concurrent clients.
sourceName: optional, string, form parameter

sourceParams: optional (depends on the value of the sourceType), string (JSON), form parameter

For sourceType couchbase, an example sourceParams JSON:

{
              "authUser": "",
              "authPassword": "",
              "authSaslUser": "",
              "authSaslPassword": "",
              "clusterManagerBackoffFactor": 0,
              "clusterManagerSleepInitMS": 0,
              "clusterManagerSleepMaxMS": 20000,
              "dataManagerBackoffFactor": 0,
              "dataManagerSleepInitMS": 0,
              "dataManagerSleepMaxMS": 20000,
              "feedBufferSizeBytes": 0,
              "feedBufferAckThreshold": 0
}

sourceUUID: optional, string, form parameter
result on error: Non-200 HTTP error code
result on success: HTTP 200 with body JSON of {"status": "ok"}

DELETE /api/index/{indexName}

Deletes an index definition.

Permission Required: cluster.bucket[bucket_name].fts!write

Role Required: FTS-Admin

Parameters

indexName: required, string, URL path parameter

The name of the index definition to be deleted.

Index Management

POST /api/index/{indexName}/ingestControl/{op}

Pause index updates and maintenance (no more ingesting document mutations).

Permission Required: cluster.bucket[bucket_name].fts!manage

Role Required: FTS-Admin

Parameters

indexName: required, string, URL path parameter

The name of the index whose control values will be modified.
op: required, string, URL path parameter

Allowed values for op are "pause" or "resume".

POST /api/index/{indexName}/planFreezeControl/{op}

Freeze the assignment of index partitions to nodes.

Permission Required: cluster.bucket[bucket_name].fts!manage

Role Required: FTS-Admin

Parameters

indexName: required, string, URL path parameter

The name of the index whose control values will be modified.
op: required, string, URL path parameter

Allowed values for op are "freeze" or "unfreeze".

POST /api/index/{indexName}/queryControl/{op}

Disallow queries on an index.

Permission Required: cluster.bucket[bucket_name].fts!manage

Role Required: FTS-Admin

Parameters

indexName: required, string, URL path parameter

The name of the index whose control values will be modified.
op: required, string, URL path parameter

Allowed values for op are "allow" or "disallow".

Index Monitoring And Debugging

GET /api/stats

Returns indexing and data related metrics, timings and counters from the node as JSON.

Permission Required: cluster.bucket[bucket_name].stats!read

Role Required: FTS-Admin

Sample response

{
    "feeds": {
        "myFirstIndex_6cc599ab7a85bf3b": {}
    },
    "manager": {
        "TotCreateIndex": 1,
        "TotCreateIndexOk": 1,
        "TotDeleteIndex": 0,
        "TotDeleteIndexOk": 0,
        "TotIndexControl": 0,
        "TotIndexControlOk": 0,
        "TotJanitorClosePIndex": 0,
        "TotJanitorKick": 2,
        "TotJanitorKickErr": 0,
        "TotJanitorKickOk": 2,
        "TotJanitorKickStart": 2,
        "TotJanitorNOOP": 0,
        "TotJanitorNOOPOk": 0,
        "TotJanitorRemovePIndex": 0,
        "TotJanitorSubscriptionEvent": 0,
        "TotJanitorUnknownErr": 0,
        "TotKick": 0,
        "TotPlannerKick": 2,
        "TotPlannerKickChanged": 1,
        "TotPlannerKickErr": 0,
        "TotPlannerKickOk": 2,
        "TotPlannerKickStart": 2,
        "TotPlannerNOOP": 0,
        "TotPlannerNOOPOk": 0,
        "TotPlannerSubscriptionEvent": 0,
        "TotPlannerUnknownErr": 0,
        "TotSaveNodeDef": 2,
        "TotSaveNodeDefGetErr": 0,
        "TotSaveNodeDefOk": 2,
        "TotSaveNodeDefSame": 0,
        "TotSaveNodeDefSetErr": 0
     },
     "pindexes": {
         "myFirstIndex_6cc599ab7a85bf3b_0": null
     }
}

GET /api/stats/index/{indexName}

Returns metrics, timings and counters for a single index from the node as JSON.

Permission Required: cluster.bucket[bucket_name].stats!read

Role Required: FTS-Admin

Sample response

{
    "feeds": {
        "myFirstIndex_6cc599ab7a85bf3b": {}
    },
    "pindexes": {
        "myFirstIndex_6cc599ab7a85bf3b_0": null
    }
}

POST /api/index/{indexName}/analyzeDoc

Sends a json document to the given index for text analysis.

Permission Required: cluster.bucket[bucket_name].fts!read

Role Required: FTS-Searcher, FTS-Admin

Parameters

indexName: required, string, URL path parameter

The name of the index against which the analysis needs to performed.

The request’s POST body contains any sample json document. For example:
```
{
   "name": "hello world",
   "title": "couchbase blr"}
}
```

Response Object

A sample response for an index definition with keyword analyzer set against the title field and an ngram (min=2, max=5) tokenfilter set against the name field would be like below for the above request.

{
  "status": "ok",
  "analyzed": [
    {
      "couchbase blr": {
        "Term": "Y291Y2hiYXNlIGJscg==",
        "Locations": [
          {
            "Field": "title",
            "ArrayPositions": [],
            "Start": 0,
            "End": 13,
            "Position": 1
          }
        ]
      }
    },
    {
      "he": {
        "Term": "aGU=",
        "Locations": [
          {
            "Field": "name",
            "ArrayPositions": [],
            "Start": 0,
            "End": 5,
            "Position": 1
          }
        ]
      },
      "hel": {
        "Term": "aGVs",
        "Locations": [
          {
            "Field": "name",
            "ArrayPositions": [],
            "Start": 0,
            "End": 5,
            "Position": 1
          }
        ]
      },
      "hell": {
        "Term": "aGVsbA==",
        "Locations": [
          {
            "Field": "name",
            "ArrayPositions": [],
            "Start": 0,
            "End": 5,
            "Position": 1
          }
        ]
      },
      "hello": {
        "Term": "aGVsbG8=",
        "Locations": [
          {
            "Field": "name",
            "ArrayPositions": [],
            "Start": 0,
            "End": 5,
            "Position": 1
          }
        ]
      },
      "wo": {
        "Term": "d28=",
        "Locations": [
          {
            "Field": "name",
            "ArrayPositions": [],
            "Start": 6,
            "End": 11,
            "Position": 2
          }
        ]
      },
      "wor": {
        "Term": "d29y",
        "Locations": [
          {
            "Field": "name",
            "ArrayPositions": [],
            "Start": 6,
            "End": 11,
            "Position": 2
          }
        ]
      },
      "worl": {
        "Term": "d29ybA==",
        "Locations": [
          {
            "Field": "name",
            "ArrayPositions": [],
            "Start": 6,
            "End": 11,
            "Position": 2
          }
        ]
      },
      "world": {
        "Term": "d29ybGQ=",
        "Locations": [
          {
            "Field": "name",
            "ArrayPositions": [],
            "Start": 6,
            "End": 11,
            "Position": 2
          }
        ]
      }
    },
    null
  ]
}

Index Querying

GET /api/index/{indexName}/count

Returns the count of indexed documents.

Permission Required: cluster.bucket[bucket_name].fts!read

Role Required: FTS-Searcher, FTS-Admin

Parameters

indexName: required, string, URL path parameter

The name of the index whose count is to be retrieved.

POST /api/index/{indexName}/query

Queries an index.

Permission Required: cluster.bucket[bucket_name].fts!read

Role Required: FTS-Searcher, FTS-Admin

Parameters

indexName: required, string, URL path parameter

The name of the index to be queried.

The request’s POST body depends on the index type. For index type bleve, here’s a simple query POST body:

{
    "query": {
        "query": "a sample query",
        "boost": 1
    },
    "size": 10,
    "from": 0,
    "highlight": null,
    "fields": null,
    "facets": null,
    "explain": false
    }

An example POST body using from/size for results paging, using ctl for a timeout and for "at_plus" consistency level. On consistency, the index must have incorporated at least mutation sequence-number 123 for partition (vbucket) 0 and mutation sequence-number 234 for partition (vbucket) 1 (where vbucket 1 should have a vbucketUUID of a0b1c2):

{
    "ctl": {
        "timeout": 10000,
        "consistency": {
            "level": "at_plus",
                "vectors": {
                    "customerIndex": {
                        "0": 123,
                        "1/a0b1c2": 234
                    }
                }
            }
        },
        "query": {
            "query": "alice smith",
            "boost": 1
        },
        "size": 10,
        "from": 20,
        "highlight": {
            "style": null,
            "fields": null
        },
        "fields": [
            "*"
        ],
        "facets": null,
        "explain": true
}

Response Object

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 (pindexes) may encounter a timeout or return an error.

Consistency and Timeouts

A query can specify a timeout value, a consistency requirement, or both. This section explains how this affects the query behavior and how to handle the resulting query return values.

logical first phase consistency wait - if timeout in this period, get 416 error with message saying request could not be satisfied).
If consistency wait times out with 416, return value to client will indicate the sequence number range processed so the client will have an idea how far the processing got and has the option of retrying more intelligently.
In phase 2, you have the normal pindex timeout. This will start whenever the first phase completes. At this point, request will return 200 HTTP response code unless there is an internal server error.
Client must check response status, which will return any errors or timeouts for each pindex. If The response includes the number of errors, and the client can determine whether they need the complete results or can continue as long as enough pindexes return to give a reasonable user experience. Note that the query return status will be 200 even if all pindexes return errors so it’s critical to check the response status and code accordingly.
If client sets timeout very low, e.g. 1ms, you may receive a 200 error with all timeouts instead of a consistency wait timeout.