Search Index Management and Monitoring

      +
      Use the following endpoints in the Search Service API to manage and monitor your Search indexes.

      Search Index Definitions

      Use the following APIs to retrieve Search index definitions, create new Search indexes, or delete an existing Search index.

      Get All Search Index Definitions

      Returns all Search index definitions from the bucket where you have read permissions, as a JSON object.

      This endpoint is for legacy Search indexes and may be deprecated in a future release. Use GET All Search Index Definitions (Scoped), instead.

      Endpoint

      GET /api/index

      Permission Required

      cluster.bucket[$BUCKET_NAME].fts!read

      Role Required

      Search Reader or Search 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 All Search Index Definitions (Scoped)

      Returns all Search index definitions inside the bucket and scope specified in the endpoint URL as a JSON object.

      Endpoint

      GET /api/bucket/${BUCKET_NAME}/scope/${SCOPE_NAME}/index

      Permission Required

      cluster.bucket[$BUCKET_NAME].fts!read

      Role Required

      Search Reader or Search Admin

      Parameters

      Parameter Required? Type Description

      ${BUCKET_NAME}

      Yes

      String, URL path parameter

      The name of the bucket where you want to return Search index definitions.

      ${SCOPE_NAME}

      Yes

      String, URL path parameter

      The name of the scope where you want to return Search index definitions.

      Sample response
      {
          "status": "ok",
          "indexDefs": {
              "uuid": "23cf9530131858b8",
              "indexDefs": {
                  "travel-sample.inventory.travel-hotel": {
                      "type": "fulltext-index",
                      "name": "travel-hotel",
                      "uuid": "a04a16f178846bc4",
                      "sourceType": "gocbcore",
                      "sourceName": "travel-sample",
                      "sourceUUID": "8f866261438f8b0d415a437552f3ae99",
                      "planParams": {
                          "maxPartitionsPerPIndex": 1024,
                          "indexPartitions": 1
                      },
                      "params": {
                          "doc_config": {
                              "docid_prefix_delim": "",
                              "docid_regexp": "",
                              "mode": "scope.collection.type_field",
                              "type_field": "type"
                          },
                          "mapping": {
                              "analysis": {},
                              "default_analyzer": "standard",
                              "default_datetime_parser": "dateTimeOptional",
                              "default_field": "_all",
                              "default_mapping": {
                                  "dynamic": true,
                                  "enabled": false
                              },
                              "default_type": "_default",
                              "docvalues_dynamic": false,
                              "index_dynamic": true,
                              "store_dynamic": false,
                              "type_field": "_type",
                              "types": {
                                  "inventory.hotel": {
                                      "dynamic": false,
                                      "enabled": true,
                                      "properties": {
                                          "reviews": {
                                              "dynamic": false,
                                              "enabled": true,
                                              "properties": {
                                                  "content": {
                                                      "dynamic": false,
                                                      "enabled": true,
                                                      "fields": [
                                                          {
                                                              "docvalues": true,
                                                              "include_in_all": true,
                                                              "include_term_vectors": true,
                                                              "index": true,
                                                              "name": "content",
                                                              "store": true,
                                                              "type": "text"
                                                          }
                                                      ]
                                                  }
                                              }
                                          }
                                      }
                                  }
                              }
                          },
                          "store": {
                              "indexType": "scorch",
                              "segmentVersion": 15
                          }
                      },
                      "sourceParams": {}
                  },
                  "travel-sample.inventory.travel-test": {
                      "type": "fulltext-index",
                      "name": "travel-test",
                      "uuid": "766ddce5d41a3b41",
                      "sourceType": "gocbcore",
                      "sourceName": "travel-sample",
                      "sourceUUID": "8f866261438f8b0d415a437552f3ae99",
                      "planParams": {
                          "maxPartitionsPerPIndex": 1024,
                          "indexPartitions": 1
                      },
                      "params": {
                          "doc_config": {
                              "docid_prefix_delim": "",
                              "docid_regexp": "",
                              "mode": "scope.collection.type_field",
                              "type_field": "type"
                          },
                          "mapping": {
                          "analysis": {},
                          "default_analyzer": "standard",
                          "default_datetime_parser": "dateTimeOptional",
                          "default_field": "_all",
                          "default_mapping": {
                              "dynamic": true,
                              "enabled": true
                          },
                          "default_type": "_default",
                          "docvalues_dynamic": false,
                          "index_dynamic": true,
                          "store_dynamic": false,
                          "type_field": "_type"
                          },
                          "store": {
                              "indexType": "scorch",
                              "segmentVersion": 15
                          }
                      },
                      "sourceParams": {}
                  }
              },
              "implVersion": "5.7.0"
          }
      }

      GET Index Definition

      Returns the definition of the Search index specified in the endpoint URL as a JSON object.

      This endpoint is for legacy Search indexes and may be deprecated in a future release. Use GET Index Definition (Scoped), instead.

      Endpoint

      GET /api/index/${INDEX_NAME}

      Permission Required

      cluster.bucket[$BUCKET_NAME].fts!read

      Role Required

      Search Reader or Search Admin

      Parameters

      Parameter Required? Type Description

      ${INDEX_NAME}

      Yes

      String, URL path parameter

      The name of the Search index definition you want to return. You must use the fully qualified name for the index, which includes the bucket and scope.

      To view the full, scoped name for an index for use with this endpoint:

      1. Go to the Search tab in the Couchbase Server Web Console.

      2. Point to the Index Name for an index.

      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": []
             }

      GET Index Definition (Scoped)

      Returns the Search index definition for the Search index specified in the endpoint URL as a JSON object. Unlike GET /api/index/{indexName}, this endpoint is scoped and does not require a fully qualified ${INDEX_NAME} value.

      Endpoint

      GET /api/bucket/${BUCKET_NAME}/scope/${SCOPE_NAME}/index/${INDEX_NAME}

      Permission Required

      cluster.bucket[$BUCKET_NAME].fts!read

      Role Required

      Search Reader or Search Admin

      Parameters

      Parameter Required? Type Description

      ${BUCKET_NAME}

      Yes

      String, URL path parameter

      The name of the bucket used to create the Search index definition.

      ${SCOPE_NAME}

      Yes

      String, URL path parameter

      The name of the scope used to create the Search index definition.

      ${INDEX_NAME}

      Yes

      String, URL path parameter

      The name of the Search index definition to return.

      Sample Response for a Vector Search index
      {
          "status": "ok",
          "indexDef": {
              "type": "fulltext-index",
              "name": "color-test",
              "uuid": "6ea521a918bd3837",
              "sourceType": "gocbcore",
              "sourceName": "vector-sample",
              "sourceUUID": "614177a67bdfbd2823c5f9c3e62f5991",
              "planParams": {
                  "maxPartitionsPerPIndex": 1024,
                  "indexPartitions": 1
              },
              "params": {
                  "doc_config": {
                      "docid_prefix_delim": "",
                      "docid_regexp": "",
                      "mode": "scope.collection.type_field",
                      "type_field": "type"
                  },
                  "mapping": {
                      "analysis": {},
                      "default_analyzer": "standard",
                      "default_datetime_parser": "dateTimeOptional",
                      "default_field": "_all",
                      "default_mapping": {
                          "dynamic": false,
                          "enabled": false
                      },
                      "default_type": "_default",
                      "docvalues_dynamic": false,
                      "index_dynamic": false,
                      "store_dynamic": false,
                      "type_field": "_type",
                      "types": {
                          "color.rgb": {
                              "dynamic": false,
                              "enabled": true,
                              "properties": {
                                  "color": {
                                      "dynamic": false,
                                      "enabled": true,
                                      "fields": [
                                          {
                                              "analyzer": "en",
                                              "docvalues": true,
                                              "include_in_all": true,
                                              "include_term_vectors": true,
                                              "index": true,
                                              "name": "color",
                                              "store": true,
                                              "type": "text"
                                          }
                                      ]
                                  },
                                  "colorvect_dot": {
                                      "dynamic": false,
                                      "enabled": true,
                                      "fields": [
                                          {
                                              "dims": 3,
                                              "index": true,
                                              "name": "colorvect_dot",
                                              "similarity": "dot_product",
                                              "type": "vector",
                                              "vector_index_optimized_for": "recall"
                                          }
                                      ]
                                  }
                              }
                          }
                      }
                  },
                  "store": {
                      "indexType": "scorch",
                      "segmentVersion": 16
                  }
              },
              "sourceParams": {}
          },
          "planPIndexes": [
              {
                  "name": "vector-sample.color.color-test_6ea521a918bd3837_4c1c5584",
                  "uuid": "1543820346544e08",
                  "indexType": "fulltext-index",
                  "indexName": "vector-sample.color.color-test",
                  "indexUUID": "6ea521a918bd3837",
                  "sourceType": "gocbcore",
                  "sourceName": "vector-sample",
                  "sourceUUID": "614177a67bdfbd2823c5f9c3e62f5991",
                  "sourcePartitions": "0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130,131,132,133,134,135,136,137,138,139,140,141,142,143,144,145,146,147,148,149,150,151,152,153,154,155,156,157,158,159,160,161,162,163,164,165,166,167,168,169,170,171,172,173,174,175,176,177,178,179,180,181,182,183,184,185,186,187,188,189,190,191,192,193,194,195,196,197,198,199,200,201,202,203,204,205,206,207,208,209,210,211,212,213,214,215,216,217,218,219,220,221,222,223,224,225,226,227,228,229,230,231,232,233,234,235,236,237,238,239,240,241,242,243,244,245,246,247,248,249,250,251,252,253,254,255,256,257,258,259,260,261,262,263,264,265,266,267,268,269,270,271,272,273,274,275,276,277,278,279,280,281,282,283,284,285,286,287,288,289,290,291,292,293,294,295,296,297,298,299,300,301,302,303,304,305,306,307,308,309,310,311,312,313,314,315,316,317,318,319,320,321,322,323,324,325,326,327,328,329,330,331,332,333,334,335,336,337,338,339,340,341,342,343,344,345,346,347,348,349,350,351,352,353,354,355,356,357,358,359,360,361,362,363,364,365,366,367,368,369,370,371,372,373,374,375,376,377,378,379,380,381,382,383,384,385,386,387,388,389,390,391,392,393,394,395,396,397,398,399,400,401,402,403,404,405,406,407,408,409,410,411,412,413,414,415,416,417,418,419,420,421,422,423,424,425,426,427,428,429,430,431,432,433,434,435,436,437,438,439,440,441,442,443,444,445,446,447,448,449,450,451,452,453,454,455,456,457,458,459,460,461,462,463,464,465,466,467,468,469,470,471,472,473,474,475,476,477,478,479,480,481,482,483,484,485,486,487,488,489,490,491,492,493,494,495,496,497,498,499,500,501,502,503,504,505,506,507,508,509,510,511,512,513,514,515,516,517,518,519,520,521,522,523,524,525,526,527,528,529,530,531,532,533,534,535,536,537,538,539,540,541,542,543,544,545,546,547,548,549,550,551,552,553,554,555,556,557,558,559,560,561,562,563,564,565,566,567,568,569,570,571,572,573,574,575,576,577,578,579,580,581,582,583,584,585,586,587,588,589,590,591,592,593,594,595,596,597,598,599,600,601,602,603,604,605,606,607,608,609,610,611,612,613,614,615,616,617,618,619,620,621,622,623,624,625,626,627,628,629,630,631,632,633,634,635,636,637,638,639,640,641,642,643,644,645,646,647,648,649,650,651,652,653,654,655,656,657,658,659,660,661,662,663,664,665,666,667,668,669,670,671,672,673,674,675,676,677,678,679,680,681,682,683,684,685,686,687,688,689,690,691,692,693,694,695,696,697,698,699,700,701,702,703,704,705,706,707,708,709,710,711,712,713,714,715,716,717,718,719,720,721,722,723,724,725,726,727,728,729,730,731,732,733,734,735,736,737,738,739,740,741,742,743,744,745,746,747,748,749,750,751,752,753,754,755,756,757,758,759,760,761,762,763,764,765,766,767,768,769,770,771,772,773,774,775,776,777,778,779,780,781,782,783,784,785,786,787,788,789,790,791,792,793,794,795,796,797,798,799,800,801,802,803,804,805,806,807,808,809,810,811,812,813,814,815,816,817,818,819,820,821,822,823,824,825,826,827,828,829,830,831,832,833,834,835,836,837,838,839,840,841,842,843,844,845,846,847,848,849,850,851,852,853,854,855,856,857,858,859,860,861,862,863,864,865,866,867,868,869,870,871,872,873,874,875,876,877,878,879,880,881,882,883,884,885,886,887,888,889,890,891,892,893,894,895,896,897,898,899,900,901,902,903,904,905,906,907,908,909,910,911,912,913,914,915,916,917,918,919,920,921,922,923,924,925,926,927,928,929,930,931,932,933,934,935,936,937,938,939,940,941,942,943,944,945,946,947,948,949,950,951,952,953,954,955,956,957,958,959,960,961,962,963,964,965,966,967,968,969,970,971,972,973,974,975,976,977,978,979,980,981,982,983,984,985,986,987,988,989,990,991,992,993,994,995,996,997,998,999,1000,1001,1002,1003,1004,1005,1006,1007,1008,1009,1010,1011,1012,1013,1014,1015,1016,1017,1018,1019,1020,1021,1022,1023",
                  "nodes": {
                      "b7d460b7d4145482ac132dfa23727c5c": {
                          "canRead": true,
                          "canWrite": true,
                          "priority": 0
                      }
                  },
                  "indexParams": {
                      "doc_config": {
                          "docid_prefix_delim": "",
                          "docid_regexp": "",
                          "mode": "scope.collection.type_field",
                          "type_field": "type"
                      },
                      "mapping": {
                          "analysis": {},
                          "default_analyzer": "standard",
                          "default_datetime_parser": "dateTimeOptional",
                          "default_field": "_all",
                          "default_mapping": {
                              "dynamic": false,
                              "enabled": false
                          },
                          "default_type": "_default",
                          "docvalues_dynamic": false,
                          "index_dynamic": false,
                          "store_dynamic": false,
                          "type_field": "_type",
                          "types": {
                              "color.rgb": {
                                  "dynamic": false,
                                  "enabled": true,
                                  "properties": {
                                      "color": {
                                          "dynamic": false,
                                          "enabled": true,
                                          "fields": [
                                              {
                                                  "analyzer": "en",
                                                  "docvalues": true,
                                                  "include_in_all": true,
                                                  "include_term_vectors": true,
                                                  "index": true,
                                                  "name": "color",
                                                  "store": true,
                                                  "type": "text"
                                              }
                                          ]
                                      },
                                      "colorvect_dot": {
                                          "dynamic": false,
                                          "enabled": true,
                                          "fields": [
                                              {
                                                  "dims": 3,
                                                  "index": true,
                                                  "name": "colorvect_dot",
                                                  "similarity": "dot_product",
                                                  "type": "vector",
                                                  "vector_index_optimized_for": "recall"
                                              }
                                          ]
                                      }
                                  }
                              }
                          }
                      },
                      "store": {
                          "indexType": "scorch",
                          "segmentVersion": 16
                      }
                  }
              }
          ],
          "warnings": []
      }

      PUT Create or Update an Index Definition

      If the Search index in the endpoint URL does not exist, this endpoint uses a JSON object in the request body to create a new index. If the Search index already exists, this endpoint updates the Search index definition.

      This endpoint is for legacy Search indexes and may be deprecated in a future release. Use PUT Create or Update an Index Definition (Scoped), instead.

      Endpoint

      PUT /api/index/${INDEX_NAME}

      Permission Required

      cluster.bucket[$BUCKET_NAME].fts!write

      Role Required

      Search Admin

      Parameters

      For a detailed list of all parameters for the Request Body for the PUT /api/index/${INDEX_NAME} endpoint, see Search Index JSON Properties.

      Parameter Required? Type Description

      ${INDEX_NAME}

      Yes

      String, URL path parameter

      The name of the Search index definition to create or update. The name must satisfy the regular expression ^[A-Za-z][0-9A-Za-z_\-]*$.

      If you want to update an index definition, you must use the fully qualified name for the index, which includes the bucket and scope.

      To view the full, scoped name for an index for use with this endpoint:

      1. Go to the Search tab in the Couchbase Server Web Console.

      2. Point to the Index Name for an index.

      params

      Yes

      String (JSON), form parameter

      Sets the Search index’s type identifier, type mappings, and analyzers. For more information, see Params Object.

      type

      Yes

      String, form parameter

      The type of Search index you want to create. For more information, see Initial Settings.

      planParams

      Yes

      String (JSON), form parameter

      Set a Search index’s partition and replication settings. For more information, see planParams Object.

      prevIndexUUID

      No

      String, form parameter

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

      sourceName

      No

      String, form parameter

      The name of the bucket where you want to create the Search index. For more information, see Initial Settings.

      sourceUUID

      No

      String, form parameter

      The UUID of the bucket where you want to create the Search index. For more information, see Initial Settings.

      Sample failure response
      {
          "error": "rest_create_index: index type is required, indexName: travel-test",
          "request": "",
          "status": "fail"
      }

      The Search Service returns a non-200 HTTP error code when a request fails.

      Sample success response
      {
          "status": "ok",
          "name": "travel-test",
          "uuid": "565ca041af3baf9d"
      }

      The Search Service returns a HTTP 200 status code with a response that includes "status": "ok".

      PUT Create or Update an Index Definition (Scoped)

      If the Search index in the endpoint URL does not exist, this endpoint uses a JSON object in the request body to create a new index. If the Search index already exists, this endpoint updates the Search index definition. Unlike PUT /api/index/{indexName}, this endpoint is scoped and does not require a fully qualified ${INDEX_NAME} value.

      Endpoint

      PUT /api/bucket/${BUCKET_NAME}/scope/${SCOPE_NAME}/index/${INDEX_NAME}

      Permission Required

      cluster.bucket[$BUCKET_NAME].fts!write

      Role Required

      Search Admin

      Parameters

      Parameter Required? Type Description

      ${BUCKET_NAME}

      Yes

      String, URL path parameter

      The name of the bucket where the Search Service should create or update the Search index definition.

      ${SCOPE_NAME}

      Yes

      String, URL path parameter

      The name of the scope where the Search Service should create or update the Search index definition.

      ${INDEX_NAME}

      Yes

      String, URL path parameter

      The name of the Search index definition to create or update. The name must satisfy the regular expression ^[A-Za-z][0-9A-Za-z_\-]*$.

      Request Body

      Add a JSON object with the full Search index definition you want to create or update. For more information about how to create an index definition JSON, see Search Index JSON Properties.

      Sample failure response
      {
          "error": "rest_create_index: index type is required, indexName: travel-test",
          "request": {},
          "status": "fail"
      }

      The Search Service returns a non-200 HTTP error code when a request fails.

      Sample success response
      {
          "status": "ok",
          "name": "travel-sample.inventory.travel-test",[.var]`${BUCKET_NAME}`
          "uuid": "654cb62baebf2d26"
      }

      The Search Service returns a HTTP 200 status code with a response that includes "status": "ok".

      DELETE Index Definition

      Deletes the Search index definition specified in the endpoint URL.

      This endpoint is for legacy Search indexes and may be deprecated in a future release. Use DELETE Index Definition (Scoped), instead.

      Endpoint

      DELETE /api/index/${INDEX_NAME}

      Permission Required

      cluster.bucket[$BUCKET_NAME].fts!write

      Role Required

      Search Admin

      Parameters

      Parameter Required? Type Description

      ${INDEX_NAME}

      Yes

      String, URL path parameter

      The name of the Search index definition you want to delete. You must use the fully qualified name for the index, which includes the bucket and scope.

      To view the full, scoped name for an index for use with this endpoint:

      1. Go to the Search tab in the Couchbase Server Web Console.

      2. Point to the Index Name for an index.

      Sample failure response
      {
          "error": "rest_auth: preparePerms, err: index not found",
          "request": "",
          "status": "fail"
      }

      The Search Service returns a non-200 HTTP error code when a request fails.

      Sample success response
      {
          "status": "ok",
          "uuid": "123294e5a4efbe39"
      }

      The Search Service returns a HTTP 200 status code with a response that includes "status": "ok".

      DELETE Index Definition (Scoped)

      Delete the Search index definition from the bucket and scope specified in the endpoint URL. Unlike DELETE /api/index/{indexName}, this endpoint is scoped and does not require a fully qualified ${INDEX_NAME} value.

      Endpoint

      DELETE /api/bucket/${BUCKET_NAME}/scope/${SCOPE_NAME}/index/${INDEX_NAME}

      Permission Required

      cluster.bucket[$BUCKET_NAME].fts!write

      Role Required

      Search Admin

      Parameters

      Parameter Required? Type Description

      ${BUCKET_NAME}

      Yes

      String, URL path parameter

      The name of the bucket used to create the Search index definition.

      ${SCOPE_NAME}

      Yes

      String, URL path parameter

      The name of the scope used to create the Search index definition.

      ${INDEX_NAME}

      Yes

      String, URL path parameter

      The name of the Search index definition you want to delete.

      Sample failure response
      {
          "error": "rest_auth: preparePerms, err: index not found",
          "request": "",
          "status": "fail"
      }

      The Search Service returns a non-200 HTTP error code when a request fails.

      Sample success response
      {
          "status": "ok",
          "uuid": "687be6a2ad647c34"
      }

      The Search Service returns a HTTP 200 status code with a response that includes "status": "ok".

      Index Management

      Use the following endpoints to manage index controls, such as document ingestion, partition assignment, and queries.

      POST Set Index IngestControl

      For the Search index specified in the endpoint URL, pause or resume index updates and maintenance. While paused, the Search index does not load any new document mutations.

      This endpoint is for legacy Search indexes and may be deprecated in a future release. Use POST Set Index IngestControl (Scoped), instead.

      Endpoint

      POST /api/index/${INDEX_NAME}/ingestControl/${OP}

      Permission Required

      cluster.bucket[$BUCKET_NAME].fts!manage

      Role Required

      Search Admin

      Parameters

      Parameter Required? Type Description

      ${INDEX_NAME}

      Yes

      String, URL path parameter

      The name of the Search index definition where you want to pause or resume document loading. You must use the fully qualified name for the index, which includes the bucket and scope.

      To view the full, scoped name for an index for use with this endpoint:

      1. Go to the Search tab in the Couchbase Server Web Console.

      2. Point to the Index Name for an index.

      ${OP}

      Yes

      String, URL path parameter

      To pause ingestion and maintenance, set ${OP} to pause. To resume ingestion and maintenance on a paused index, set ${OP} to resume.

      Sample success response
      {
          "status": "ok",
      }

      The Search Service returns a HTTP 200 status code with a response that includes "status": "ok".

      POST Set Index IngestControl (Scoped)

      For the Search index specified in the endpoint URL, pause or resume index updates and maintenance. While paused, the Search index does not load any new document mutations. Unlike POST /api/index/{indexName}/ingestControl/${OP}, this endpoint is scoped and does not require a fully qualified ${INDEX_NAME} value.

      Endpoint

      POST /api/bucket/${BUCKET_NAME}/scope/${SCOPE_NAME}/index/${INDEX_NAME}/ingestControl/${OP}

      Permission Required

      cluster.bucket[$BUCKET_NAME].fts!manage

      Role Required

      Search Admin

      Parameters

      Parameter Required? Type Description

      ${BUCKET_NAME}

      Yes

      String, URL path parameter

      The name of the bucket used to create the Search index definition.

      ${SCOPE_NAME}

      Yes

      String, URL path parameter

      The name of the scope used to create the Search index definition.

      ${INDEX_NAME}

      Yes

      String, URL path parameter

      The name of the Search index definition where you want to pause or resume document loading.

      ${OP}

      Yes

      String, URL path parameter

      To pause ingestion and maintenance, set ${OP} to pause. To resume ingestion and maintenance on a paused index, set ${OP} to resume.

      Sample success response
      {
          "status": "ok",
      }

      The Search Service returns a HTTP 200 status code with a response that includes "status": "ok".

      POST Freeze Index Partition Assignment

      For the Search index specified in the endpoint URL, freeze or unfreeze the assignment of index partitions to nodes. While frozen, the Search index stops assigning partitions during index rebalancing and index definition updates.

      This endpoint is for legacy Search indexes and may be deprecated in a future release. Use POST Freeze Index Partition Assignment (Scoped), instead.

      Endpoint

      POST /api/index/${INDEX_NAME}/planFreezeControl/${OP}

      Permission Required

      cluster.bucket[$BUCKET_NAME].fts!manage

      Role Required

      Search Admin

      Parameters

      Parameter Required? Type Description

      ${INDEX_NAME}

      Yes

      String, URL path parameter

      The name of the Search index definition to freeze or unfreeze for partition assignment. You must use the fully qualified name for the index, which includes the bucket and scope.

      To view the full, scoped name for an index for use with this endpoint:

      1. Go to the Search tab in the Couchbase Server Web Console.

      2. Point to the Index Name for an index.

      ${OP}

      Yes

      String, URL path parameter

      To freeze partition assignment, set ${OP} to freeze. To unfreeze partition assignment on a frozen index, set ${OP} to unfreeze.

      Sample success response
      {
          "status": "ok",
      }

      The Search Service returns a HTTP 200 status code with a response that includes "status": "ok".

      POST Freeze Index Partition Assignment (Scoped)

      For the Search index specified in the endpoint URL, freeze or unfreeze the assignment of index partitions to nodes. While frozen, the Search index stops assigning partitions during index rebalancing and index definition updates. Unlike POST /api/index/{indexName}/planFreezeControl/${OP}, this endpoint is scoped and does not require a fully qualified ${INDEX_NAME} value.

      Endpoint

      POST /api/bucket/${BUCKET_NAME}/scope/${SCOPE_NAME}/index/${INDEX_NAME}/planFreezeControl/${OP}

      Permission Required

      cluster.bucket[$BUCKET_NAME].fts!manage

      Role Required

      Search Admin

      Parameters

      Parameter Required? Type Description

      ${BUCKET_NAME}

      Yes

      String, URL path parameter

      The name of the bucket used to create the Search index definition.

      ${SCOPE_NAME}

      Yes

      String, URL path parameter

      The name of the scope used to create the Search index definition.

      ${INDEX_NAME}

      Yes

      String, URL path parameter

      The name of the Search index definition to freeze or unfreeze for partition assignment.

      ${OP}

      Yes

      String, URL path parameter

      To freeze partition assignment, set ${OP} to freeze. To unfreeze partition assignment on a frozen index, set ${OP} to unfreeze.

      Sample success response
      {
          "status": "ok",
      }

      The Search Service returns a HTTP 200 status code with a response that includes "status": "ok".

      POST Stop Queries on an Index

      For the Search index specified in the endpoint URL, disallow or allow queries. While queries are disallowed, users see an error that the Search index’s partitions could not be reached.

      This endpoint is for legacy Search indexes and may be deprecated in a future release. Use POST Stop Queries on an Index (Scoped), instead.

      Endpoint

      POST /api/index/${INDEX_NAME}/queryControl/${OP}

      Permission Required

      cluster.bucket[$BUCKET_NAME].fts!manage

      Role Required

      Search Admin

      Parameters

      Parameter Required? Type Description

      ${INDEX_NAME}

      Yes

      String, URL path parameter

      The name of the Search index definition where you want to allow or disallow Search queries. You must use the fully qualified name for the index, which includes the bucket and scope.

      To view the full, scoped name for an index for use with this endpoint:

      1. Go to the Search tab in the Couchbase Server Web Console.

      2. Point to the Index Name for an index.

      ${OP}

      Yes

      String, URL path parameter

      To allow queries against a Search index, set ${OP} to allow. To block queries against a Search index, set ${OP} to disallow.

      Sample success response
      {
          "status": "ok",
      }

      The Search Service returns a HTTP 200 status code with a response that includes "status": "ok".

      POST Stop Queries on an Index (Scoped)

      For the Search index specified in the endpoint URL, disallow or allow queries. While queries are disallowed, users see an error that the Search index’s partitions could not be reached. Unlike POST /api/index/{indexName}/queryControl/${OP}, this endpoint is scoped and does not require a fully qualified ${INDEX_NAME} value.

      Endpoint

      POST /api/bucket/${BUCKET_NAME}/scope/${SCOPE_NAME}/index/${INDEX_NAME}/queryControl/${OP}

      Permission Required

      cluster.bucket[$BUCKET_NAME].fts!manage

      Role Required

      Search Admin

      Parameters

      Parameter Required? Type Description

      ${BUCKET_NAME}

      Yes

      String, URL path parameter

      The name of the bucket used to create the Search index definition.

      ${SCOPE_NAME}

      Yes

      String, URL path parameter

      The name of the scope used to create the Search index definition.

      ${INDEX_NAME}

      Yes

      String, URL path parameter

      The name of the Search index definition where you want to allow or disallow Search queries.

      ${OP}

      Yes

      String, URL path parameter

      To allow queries against a Search index, set ${OP} to allow. To block queries against a Search index, set ${OP} to disallow.

      Sample success response
      {
          "status": "ok",
      }

      The Search Service returns a HTTP 200 status code with a response that includes "status": "ok".

      Index Monitoring And Debugging

      Use the following endpoints to get statistics about Search indexes for monitoring and debugging.

      GET Indexing and Data Metrics for All Indexes

      Use this endpoint to get indexing and data related metrics, timings, and counters from the node running the Search Service, for all Search indexes. The endpoint returns the data as a JSON object.

      Endpoint

      GET /api/stats

      Permission Required

      cluster.bucket[$BUCKET_NAME].stats!read

      Role Required

      Search 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 Search Index Statistics

      Return indexing and data related metrics, timings, and counters for the Search index specified in the endpoint URL. The endpoint returns the data as a JSON object.

      Use this endpoint for monitoring the number of requests, documents, and more for a specific index. For more detailed partition information and more overall statistics for an index, see GET Indexing and Data Metrics, Timings, and Other Statistics.

      Endpoint

      GET /api/nsstats/index/${INDEX_NAME}

      Permission Required

      cluster.bucket[$BUCKET_NAME].stats!read

      Role Required

      FTS-Searcher, FTS-Admin

      Sample response
      {
          "avg_grpc_internal_queries_latency": 0,
          "avg_grpc_queries_latency": 0,
          "avg_internal_queries_latency": 0,
          "avg_queries_latency": 1.523718,
          "batch_merge_count": 0,
          "doc_count": 15000,
          "iterator_next_count": 0,
          "iterator_seek_count": 0,
          "last_access_time": "2023-09-20T03:05:55.440-07:00",
          "num_bytes_live_data": 0,
          "num_bytes_read_at_query_time": 4638582,
          "num_bytes_used_disk": 28062406,
          "num_bytes_used_disk_by_root": 23651161,
          "num_bytes_used_disk_by_root_reclaimable": 0,
          "num_bytes_written_at_index_time": 21208735,
          "num_files_on_disk": 6,
          "num_mutations_to_index": 0,
          "num_persister_nap_merger_break": 40,
          "num_persister_nap_pause_completed": 7,
          "num_pindexes_actual": 1,
          "num_pindexes_target": 1,
          "num_recs_to_persist": 0,
          "num_root_filesegments": 4,
          "num_root_memorysegments": 0,
          "reader_get_count": 0,
          "reader_multi_get_count": 0,
          "reader_prefix_iterator_count": 0,
          "reader_range_iterator_count": 0,
          "timer_batch_store_count": 0,
          "timer_data_delete_count": 0,
          "timer_data_update_count": 15000,
          "timer_opaque_get_count": 2048,
          "timer_opaque_set_count": 2048,
          "timer_rollback_count": 0,
          "timer_snapshot_start_count": 1024,
          "tot_seq_received": 19096,
          "total_bytes_indexed": 4866486,
          "total_bytes_query_results": 1798,
          "total_compaction_written_bytes": 87917849,
          "total_compactions": 0,
          "total_grpc_internal_queries": 0,
          "total_grpc_queries": 0,
          "total_grpc_queries_error": 0,
          "total_grpc_queries_slow": 0,
          "total_grpc_queries_timeout": 0,
          "total_grpc_request_time": 0,
          "total_internal_queries": 0,
          "total_queries": 4,
          "total_queries_error": 1,
          "total_queries_slow": 0,
          "total_queries_timeout": 0,
          "total_request_time": 6276461,
          "total_term_searchers": 7,
          "total_term_searchers_finished": 7,
          "writer_execute_batch_count": 0
      }

      GET Indexing and Data Metrics, Timings, and Other Statistics

      Return indexing and data related metrics, timings, and counters for the Search index specified in the endpoint URL. The endpoint returns the data as a JSON object.

      Use this endpoint for more detailed partition information and more available statistics than GET Search Index Statistics.

      Endpoint

      GET /api/stats/index/${INDEX_NAME}

      Permission Required

      cluster.bucket[$BUCKET_NAME].stats!read

      Role Required

      Search Admin

      Parameters

      Parameter Required? Type Description

      ${INDEX_NAME}

      Yes

      String, URL path parameter

      The name of the Search index where you want to retrieve statistics. You must use the fully qualified name for the index, which includes the bucket and scope.

      To view the full, scoped name for an index for use with this endpoint:

      1. Go to the Search tab in the Couchbase Server Web Console.

      2. Point to the Index Name for an index.

      Sample response
      {
          "feeds": {},
          "pindexes": {
              "travel-sample.inventory.travel-test_3858c70e4d4d8df9_4c1c5584": {
                  "pindexStoreStats": {
                      "TimerBatchStore": {
                          "count": 0,
                          "min": 0,
                          "max": 0,
                          "mean": 0.00,
                          "stddev": 0.00,
                          "percentiles": {
                              "99%": 0.00,
                              "99.9%": 0.00,
                              "median": 0.00,
                              "75%": 0.00,
                              "95%": 0.00
                          },
                          "rates": {
                              "mean": 0.00,
                              "1-min": 0.00,
                              "5-min": 0.00,
                              "15-min": 0.00
                          }
                      },
                      "Errors": []
                  },
                  "bleveIndexStats": {
                      "index": {
                          "CurFilesIneligibleForRemoval": 0,
                          "CurOnDiskBytes": 34007668,
                          "CurOnDiskFiles": 4,
                          "CurRootEpoch": 0,
                          "LastMergedEpoch": 44,
                          "LastPersistedEpoch": 44,
                          "MaxBatchIntroTime": 0,
                          "MaxFileMergeZapIntroductionTime": 0,
                          "MaxFileMergeZapTime": 0,
                          "MaxMemMergeZapTime": 0,
                          "TotAnalysisTime": 0,
                          "TotBatchIntroTime": 0,
                          "TotBatches": 0,
                          "TotBatchesEmpty": 0,
                          "TotBytesReadAtQueryTime": 294892,
                          "TotBytesWrittenAtIndexTime": 0,
                          "TotDeletes": 0,
                          "TotEventTriggerCompleted": 2,
                          "TotEventTriggerStarted": 2,
                          "TotFileMergeForceOpsCompleted": 0,
                          "TotFileMergeForceOpsStarted": 0,
                          "TotFileMergeIntroductions": 0,
                          "TotFileMergeIntroductionsDone": 0,
                          "TotFileMergeIntroductionsObsoleted": 0,
                          "TotFileMergeIntroductionsSkipped": 0,
                          "TotFileMergeLoopBeg": 2,
                          "TotFileMergeLoopEnd": 1,
                          "TotFileMergeLoopErr": 0,
                          "TotFileMergePlan": 1,
                          "TotFileMergePlanErr": 0,
                          "TotFileMergePlanNone": 1,
                          "TotFileMergePlanOk": 0,
                          "TotFileMergePlanTasks": 0,
                          "TotFileMergePlanTasksDone": 0,
                          "TotFileMergePlanTasksErr": 0,
                          "TotFileMergePlanTasksSegments": 0,
                          "TotFileMergePlanTasksSegmentsEmpty": 0,
                          "TotFileMergeSegments": 0,
                          "TotFileMergeSegmentsEmpty": 0,
                          "TotFileMergeWrittenBytes": 0,
                          "TotFileMergeZapBeg": 0,
                          "TotFileMergeZapEnd": 0,
                          "TotFileMergeZapIntroductionTime": 0,
                          "TotFileMergeZapTime": 0,
                          "TotFileSegmentsAtRoot": 1,
                          "TotIndexTime": 0,
                          "TotIndexedPlainTextBytes": 0,
                          "TotIntroduceLoop": 3,
                          "TotIntroduceMergeBeg": 0,
                          "TotIntroduceMergeEnd": 0,
                          "TotIntroducePersistBeg": 0,
                          "TotIntroducePersistEnd": 0,
                          "TotIntroduceRevertBeg": 0,
                          "TotIntroduceRevertEnd": 0,
                          "TotIntroduceSegmentBeg": 0,
                          "TotIntroduceSegmentEnd": 0,
                          "TotIntroducedItems": 0,
                          "TotIntroducedSegmentsBatch": 0,
                          "TotIntroducedSegmentsMerge": 0,
                          "TotItemsToPersist": 0,
                          "TotMemMergeBeg": 0,
                          "TotMemMergeDone": 0,
                          "TotMemMergeErr": 0,
                          "TotMemMergeSegments": 0,
                          "TotMemMergeZapBeg": 0,
                          "TotMemMergeZapEnd": 0,
                          "TotMemMergeZapTime": 0,
                          "TotMemorySegmentsAtRoot": 0,
                          "TotOnErrors": 0,
                          "TotPersistLoopBeg": 2,
                          "TotPersistLoopEnd": 1,
                          "TotPersistLoopErr": 0,
                          "TotPersistLoopProgress": 0,
                          "TotPersistLoopWait": 2,
                          "TotPersistLoopWaitNotified": 0,
                          "TotPersistedItems": 0,
                          "TotPersistedSegments": 0,
                          "TotPersisterMergerNapBreak": 1,
                          "TotPersisterNapPauseCompleted": 1,
                          "TotPersisterSlowMergerPause": 0,
                          "TotPersisterSlowMergerResume": 0,
                          "TotSnapshotsRemovedFromMetaStore": 0,
                          "TotTermSearchersFinished": 13,
                          "TotTermSearchersStarted": 13,
                          "TotUpdates": 0,
                          "analysis_time": 0,
                          "batches": 0,
                          "deletes": 0,
                          "errors": 0,
                          "index_time": 0,
                          "num_bytes_read_at_query_time": 294892,
                          "num_bytes_used_disk": 34007668,
                          "num_bytes_used_disk_by_root": 15644303,
                          "num_bytes_used_disk_by_root_reclaimable": 0,
                          "num_bytes_written_at_index_time": 0,
                          "num_files_on_disk": 4,
                          "num_items_introduced": 0,
                          "num_items_persisted": 0,
                          "num_persister_nap_merger_break": 1,
                          "num_persister_nap_pause_completed": 1,
                          "num_plain_text_bytes_indexed": 0,
                          "num_recs_to_persist": 0,
                          "num_root_filesegments": 1,
                          "num_root_memorysegments": 0,
                          "term_searchers_finished": 13,
                          "term_searchers_started": 13,
                          "total_compaction_written_bytes": 0,
                          "updates": 0
                      },
                      "search_time": 40353204,
                      "searches": 1
                  },
                  "basic": {
                      "DocCount": 917
                  },
                  "partitions": {},
                  "copyPartitionStats": {
                      "TotCopyPartitionStart": 0,
                      "TotCopyPartitionFinished": 0,
                      "TotCopyPartitionTimeInMs": 0,
                      "TotCopyPartitionFailed": 0,
                      "TotCopyPartitionRetries": 0,
                      "TotCopyPartitionErrors": 0,
                      "TotCopyPartitionSkipped": 0,
                      "TotCopyPartitionCancelled": 0,
                      "TotCopyPartitionOnHttp2": 0
                  }
              }
          }
      }

      GET Query, Mutation, Partition, and Other Index Statistics

      Return query, mutation, document, partition, and compaction statistics for the Search index specified in the endpoint URL. The endpoint returns the data as a JSON object.

      Endpoint

      GET /api/nsstats/index/${INDEX_NAME}

      Permission Required

      cluster.bucket[$BUCKET_NAME].stats!read

      Role Required

      Search Admin

      Parameters

      Parameter Required? Type Description

      ${INDEX_NAME}

      Yes

      String, URL path parameter

      The name of the Search index where you want to retrieve statistics. You must use the fully qualified name for the index, which includes the bucket and scope.

      To view the full, scoped name for an index for use with this endpoint:

      1. Go to the Search tab in the Couchbase Server Web Console.

      2. Point to the Index Name for an index.

      Sample response
      {
          "avg_grpc_internal_queries_latency": 0,
          "avg_grpc_queries_latency": 0,
          "avg_internal_queries_latency": 0,
          "avg_queries_latency": 12.971812,
          "batch_merge_count": 0,
          "doc_count": 917,
          "iterator_next_count": 0,
          "iterator_seek_count": 0,
          "last_access_time": "2023-12-05T17:09:09.326+00:00",
          "num_bytes_live_data": 0,
          "num_bytes_read_at_query_time": 269399,
          "num_bytes_used_disk": 16692286,
          "num_bytes_used_disk_by_root": 15643710,
          "num_bytes_used_disk_by_root_reclaimable": 0,
          "num_bytes_written_at_index_time": 12524609,
          "num_files_on_disk": 2,
          "num_mutations_to_index": 0,
          "num_persister_nap_merger_break": 2,
          "num_persister_nap_pause_completed": 2,
          "num_pindexes_actual": 1,
          "num_pindexes_target": 1,
          "num_recs_to_persist": 0,
          "num_root_filesegments": 1,
          "num_root_memorysegments": 0,
          "reader_get_count": 0,
          "reader_multi_get_count": 0,
          "reader_prefix_iterator_count": 0,
          "reader_range_iterator_count": 0,
          "timer_batch_store_count": 0,
          "timer_data_delete_count": 0,
          "timer_data_update_count": 917,
          "timer_opaque_get_count": 2048,
          "timer_opaque_set_count": 2048,
          "timer_rollback_count": 0,
          "timer_snapshot_start_count": 96,
          "tot_seq_received": 87974,
          "total_bytes_indexed": 8523422,
          "total_bytes_query_results": 35846,
          "total_compaction_written_bytes": 15643710,
          "total_compactions": 0,
          "total_grpc_internal_queries": 0,
          "total_grpc_queries": 0,
          "total_grpc_queries_error": 0,
          "total_grpc_queries_slow": 0,
          "total_grpc_queries_timeout": 0,
          "total_grpc_request_time": 0,
          "total_internal_queries": 0,
          "total_queries": 2,
          "total_queries_error": 0,
          "total_queries_slow": 0,
          "total_queries_timeout": 0,
          "total_request_time": 25947312,
          "total_term_searchers": 15,
          "total_term_searchers_finished": 15,
          "writer_execute_batch_count": 0
      }

      POST Analyze Document

      Use the Search index specified in the endpoint URL to analyze a document from the request body.

      Endpoint

      POST /api/index/${INDEX_NAME}/analyzeDoc

      Permission Required

      cluster.bucket[$BUCKET_NAME].fts!read

      Role Required

      Search Reader or Search Admin

      Parameters

      Parameter Required? Type Description

      ${INDEX_NAME}

      Yes

      String, URL path parameter

      The name of the Search index to use to analyze the document in the request body. You must use the fully qualified name for the index, which includes the bucket and scope.

      To view the full, scoped name for an index for use with this endpoint:

      1. Go to the Search tab in the Couchbase Server Web Console.

      2. Point to the Index Name for an index.

      Request Body

      Add any valid JSON document to the request body. For example:

      {
         "name": "hello world",
         "title": "couchbase blr"
      }

      Response Object

      In the following example, a Search index with the following settings analyzed the document from the sample Request Body:

      • A keyword analyzer for the title field.

      • An ngram token filter with a min of 2 and a max of 5 for the name field.

      {
        "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
        ]
      }

      GET Index Status (Scoped)

      Returns the status of the Search index specified in the endpoint URL, including whether all index partitions are created and ready to use.

      Endpoint

      GET /api/bucket/${BUCKET_NAME}/scope/${SCOPE_NAME}/index/${INDEX_NAME}/status

      Permission Required

      cluster.bucket[$BUCKET_NAME].fts!read

      Role Required

      Search Reader or Search Admin

      Parameters

      Parameter Required? Type Description

      ${BUCKET_NAME}

      Yes

      String, URL path parameter

      The name of the bucket used to create the Search index definition.

      ${SCOPE_NAME}

      Yes

      String, URL path parameter

      The name of the scope used to create the Search index definition.

      ${INDEX_NAME}

      Yes

      String, URL path parameter

      The name of the Search index definition to status check.

      Sample success response
      {
          "status": "ok",
          "indexStatus": "Ready"
      }

      The Search Service returns a HTTP 200 status code with a response that includes "status": "ok".

      Index Querying

      Use the following endpoints to query the contents of a Search index.

      GET Indexed Documents Count

      Returns the number of indexed documents inside the Search index specified in the endpoint URL.

      Endpoint

      GET /api/index/${INDEX_NAME}/count

      Permission Required

      cluster.bucket[$BUCKET_NAME].fts!read

      Role Required

      Search Reader or Search Admin

      Parameters

      Parameter Required? Type Description

      ${INDEX_NAME}

      Yes

      String, URL path parameter

      The name of the index where you want to count the number of available documents. You must use the fully qualified name for the index, which includes the bucket and scope.

      To view the full, scoped name for an index for use with this endpoint:

      1. Go to the Search tab in the Couchbase Server Web Console.

      2. Point to the Index Name for an index.

      Sample success response
      {
          "status": "ok",
          "count": 285
      }

      The Search Service returns a HTTP 200 status code with a response that includes "status": "ok".

      POST Return the Index Partition and ID for a Document (Scoped)

      Send a document ID in the request body and return the Search index partition ID for where the document is stored. The endpoint returns a JSON object as a response.

      Endpoint

      POST /api/bucket/${BUCKET_NAME}/scope/${SCOPE_NAME}/index/${INDEX_NAME}/pindexLookup

      Permission Required

      cluster.bucket[$BUCKET_NAME].fts!read

      Role Required

      Search Reader or Search Admin

      Parameters

      Parameter Required? Type Description

      ${BUCKET_NAME}

      Yes

      String, URL path parameter

      The name of the bucket used to create the Search index definition.

      ${SCOPE_NAME}

      Yes

      String, URL path parameter

      The name of the scope used to create the Search index definition.

      ${INDEX_NAME}

      Yes

      String, URL path parameter

      The name of the Search index definition that contains the document.

      Request Body

      Add a valid JSON object that contains the docID property, with a value that matches the document ID for a document in the Search index.

      For example:

      {
          "docID": "hotel_5848"
      }
      Sample success response
      {
          "status": "ok",
          "pindexes": {
              "travel-sample.inventory.travel-test": {
                  "id": "travel-sample.inventory.travel-test_123294e5a4efbe39_4c1c5584"
              }
          }
      }

      The Search Service returns a HTTP 200 status code with a response that includes "status": "ok".

      POST Query a Search Index

      Run a query formatted as a JSON object against the Search index definition specified in the endpoint URL. The endpoint returns a JSON object as a response.

      This endpoint is for legacy Search indexes and may be deprecated in a future release. Use POST Query a Search Index (Scoped), instead.

      Endpoint

      POST /api/index/${INDEX_NAME}/query

      Permission Required

      cluster.bucket[$BUCKET_NAME].fts!read

      Role Required

      Search Reader or Search Admin

      Parameters

      Parameter Required? Type Description

      ${INDEX_NAME}

      Yes

      String, URL path parameter

      The name of the Search index definition to query with the request body. You must use the fully qualified name for the index, which includes the bucket and scope.

      To view the full, scoped name for an index for use with this endpoint:

      1. Go to the Search tab in the Couchbase Server Web Console.

      2. Point to the Index Name for an index.

      Request Body

      For more detailed information about how to format the request body for the POST /api/index/${INDEX_NAME}/query endpoint, see Search Request JSON Properties.

      For example, the following request body searches for the text a sample query in the documents included in the Search index:

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

      The following request body uses from/size for results paging, uses ctl for a timeout and the "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
      }

      The following hybrid search request body searches for a specified normalized color vector in colorvect_dot, but uses regular query parameters to limit the brightness value of the returned color to the range of 70-80:

      {
            "fields": ["*"],
            "query": {
              "min": 70,
              "max": 80,
              "inclusive_min": false,
              "inclusive_max": true,
              "field": "brightness"
            },
            "knn": [
              {
                "k": 10,
                "field": "colorvect_dot",
                "vector": [ 0.707106781186548, 0, 0.707106781186548 ]
              }
            ],
            "size": 10
      }

      For more information about vector searches, see Use Vector Search for AI Applications.

      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.

      POST Query a Search Index (Scoped)

      Run a query formatted as a JSON object against the Search index definition specified in the endpoint URL. The endpoint returns a JSON object as a response. Unlike POST /api/index/{indexName}/query, this endpoint is scoped and does not require a fully qualified ${INDEX_NAME} value.

      Endpoint

      POST /api/bucket/${BUCKET_NAME}/scope/${SCOPE_NAME}/index/${INDEX_NAME}/query

      Permission Required

      cluster.bucket[$BUCKET_NAME].fts!read

      Role Required

      Search Reader or Search Admin

      Parameters

      Parameter Required? Type Description

      ${BUCKET_NAME}

      Yes

      String, URL path parameter

      The name of the bucket used to create the Search index definition.

      ${SCOPE_NAME}

      Yes

      String, URL path parameter

      The name of the scope used to create the Search index definition.

      ${INDEX_NAME}

      Yes

      String, URL path parameter

      The name of the Search index definition to query with the request body.

      Request Body

      Add 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.

      Sample failure response
      {
          "error": "rest_index: Query, indexName: travel-sample.inventory.travel-test, err: bleve: QueryBleve parsing searchRequest, err: unknown query type",
          "request": {
              "collections": [
                  "hotel"
              ],
              "ctl": {
                  "consistency": {
                      "level": "at_plus",
                      "results": "complete",
                      "vectors": {
                          "searchIndexName": {
                              "607/205096593892159": 2,
                              "640/298739127912798": 4
                          }
                      }
                  },
                  "timeout": 10000
              },
              "explain": true,
              "from": 0,
              "highlight": {
                  "fields": [
                      "reviews.content"
                  ],
                  "style": "html"
              },
              "includeLocations": false,
              "limit": 10,
              "offset": 0,
              "query": {},
              "score": "none",
              "size": 10,
              "sort": [
                  "reviews.Ratings.Cleanliness",
                  {
                      "by": "field",
                      "desc": false,
                      "field": "reviews.Ratings.Cleanliness",
                      "missing": "last",
                      "mode": "default",
                      "type": "number"
                  },
                  "-_score",
                  "-_id"
              ]
          },
          "status": "fail"
      }

      The Search Service returns a non-200 HTTP error code when a request fails.

      Sample success response - regular query
      {
          "status": {
              "total": 1,
              "failed": 0,
              "successful": 1
          },
          "request": {
              "query": {
                  "conjuncts": [
                      {
                          "match": "location",
                          "field": "reviews.content",
                          "prefix_length": 0,
                          "fuzziness": 0,
                          "operator": "or"
                      },
                      {
                          "match_phrase": "nice view",
                          "field": "reviews.content"
                      }
                  ]
              },
              "size": 10,
              "from": 0,
              "highlight": {
                  "style": "html",
                  "fields": [
                      "reviews.content"
                  ]
              },
              "fields": null,
              "facets": null,
              "explain": true,
              "sort": [
                  "reviews.Ratings.Cleanliness",
                  {
                      "by": "field",
                      "field": "reviews.Ratings.Cleanliness",
                      "type": "number"
                  },
                  "-_score",
                  "-_id"
              ],
              "includeLocations": false,
              "score": "none",
              "search_after": null,
              "search_before": null
          },
          "hits": [
              {
                  "index": "travel-sample.inventory.travel-test_53373d2948c55e82_4c1c5584",
                  "id": "hotel_7388",
                  "score": 0,
                  "explanation": {
                      "value": 0,
                      "message": "sum of:",
                      "children": [
                          {
                              "value": 0,
                              "message": "product of:",
                              "children": [
                                  {
                                      "value": 0,
                                      "message": "sum of:",
                                      "children": [
                                          {
                                              "value": 0,
                                              "message": "weight(reviews.content:location^1.000000 in \u0000\u0000\u0000\u0000\u0000\u0000\u0003\n), product of:",
                                              "children": [
                                                  {
                                                      "value": 0.5320504947307548,
                                                      "message": "queryWeight(reviews.content:location^1.000000), product of:",
                                                      "children": [
                                                          {
                                                              "value": 1,
                                                              "message": "boost"
                                                          },
                                                          {
                                                              "value": 1.4291903588638628,
                                                              "message": "idf(docFreq=596, maxDocs=917)"
                                                          },
                                                          {
                                                              "value": 0.3722740581273647,
                                                              "message": "queryNorm"
                                                          }
                                                      ]
                                                  },
                                                  {
                                                      "value": 0,
                                                      "message": "fieldWeight(reviews.content:location in \u0000\u0000\u0000\u0000\u0000\u0000\u0003\n), product of:",
                                                      "children": [
                                                          {
                                                              "value": 0,
                                                              "message": "tf(termFreq(reviews.content:location)=0"
                                                          },
                                                          {
                                                              "value": 0,
                                                              "message": "fieldNorm(field=reviews.content, doc=\u0000\u0000\u0000\u0000\u0000\u0000\u0003\n)"
                                                          },
                                                          {
                                                              "value": 1.4291903588638628,
                                                              "message": "idf(docFreq=596, maxDocs=917)"
                                                          }
                                                      ]
                                                  }
                                              ]
                                          }
                                      ]
                                  },
                                  {
                                      "value": 1,
                                      "message": "coord(1/1)"
                                  }
                              ]
                          },
                          {
                              "value": 0,
                              "message": "sum of:",
                              "children": [
                                  {
                                      "value": 0,
                                      "message": "weight(reviews.content:view^1.000000 in \u0000\u0000\u0000\u0000\u0000\u0000\u0003\n), product of:",
                                      "children": [
                                          {
                                              "value": 0.6867550119496617,
                                              "message": "queryWeight(reviews.content:view^1.000000), product of:",
                                              "children": [
                                                  {
                                                      "value": 1,
                                                      "message": "boost"
                                                  },
                                                  {
                                                      "value": 1.8447565629585312,
                                                      "message": "idf(docFreq=393, maxDocs=917)"
                                                  },
                                                  {
                                                      "value": 0.3722740581273647,
                                                      "message": "queryNorm"
                                                  }
                                              ]
                                          },
                                          {
                                              "value": 0,
                                              "message": "fieldWeight(reviews.content:view in \u0000\u0000\u0000\u0000\u0000\u0000\u0003\n), product of:",
                                              "children": [
                                                  {
                                                      "value": 0,
                                                      "message": "tf(termFreq(reviews.content:view)=0"
                                                  },
                                                  {
                                                      "value": 0,
                                                      "message": "fieldNorm(field=reviews.content, doc=\u0000\u0000\u0000\u0000\u0000\u0000\u0003\n)"
                                                  },
                                                  {
                                                      "value": 1.8447565629585312,
                                                      "message": "idf(docFreq=393, maxDocs=917)"
                                                  }
                                              ]
                                          }
                                      ]
                                  },
                                  {
                                      "value": 0,
                                      "message": "weight(reviews.content:nice^1.000000 in \u0000\u0000\u0000\u0000\u0000\u0000\u0003\n), product of:",
                                      "children": [
                                          {
                                              "value": 0.4952674273751292,
                                              "message": "queryWeight(reviews.content:nice^1.000000), product of:",
                                              "children": [
                                                  {
                                                      "value": 1,
                                                      "message": "boost"
                                                  },
                                                  {
                                                      "value": 1.3303839377539577,
                                                      "message": "idf(docFreq=658, maxDocs=917)"
                                                  },
                                                  {
                                                      "value": 0.3722740581273647,
                                                      "message": "queryNorm"
                                                  }
                                              ]
                                          },
                                          {
                                              "value": 0,
                                              "message": "fieldWeight(reviews.content:nice in \u0000\u0000\u0000\u0000\u0000\u0000\u0003\n), product of:",
                                              "children": [
                                                  {
                                                      "value": 0,
                                                      "message": "tf(termFreq(reviews.content:nice)=0"
                                                  },
                                                  {
                                                      "value": 0,
                                                      "message": "fieldNorm(field=reviews.content, doc=\u0000\u0000\u0000\u0000\u0000\u0000\u0003\n)"
                                                  },
                                                  {
                                                      "value": 1.3303839377539577,
                                                      "message": "idf(docFreq=658, maxDocs=917)"
                                                  }
                                              ]
                                          }
                                      ]
                                  }
                              ]
                          }
                      ]
                  },
                  "locations": {
                      "reviews.content": {
                          "location": [
                              {
                                  "pos": 312,
                                  "start": 1641,
                                  "end": 1649,
                                  "array_positions": [
                                      4
                                  ]
                              }
                          ],
                          "nice": [
                              {
                                  "pos": 165,
                                  "start": 840,
                                  "end": 844,
                                  "array_positions": [
                                      2
                                  ]
                              }
                          ],
                          "view": [
                              {
                                  "pos": 166,
                                  "start": 845,
                                  "end": 849,
                                  "array_positions": [
                                      2
                                  ]
                              }
                          ]
                      }
                  },
                  "fragments": {
                      "reviews.content": [
                          "…at\u0026#39;s her name checked us in, very friendly and knowlegeable of the area. I would stay here again get area and right at the street car stop. nice resturants in walking distance. \u003cmark\u003enice\u003c/mark\u003e \u003cmark\u003eview\u003c/mark\u003e of the city o…"
                      ]
                  },
                  "sort": [
                      "􏿿􏿿􏿿",
                      "􏿿􏿿􏿿",
                      "_score",
                      "hotel_7388"
                  ]
              },
              
              {...}
          ],
          "total_hits": 27,
          "cost": 108906,
          "max_score": 0,
          "took": 14964461,
          "facets": null
      }

      The Search Service returns a HTTP 200 status code with a response that includes "status": "ok".

      Sample success response - hybrid vector search
      {
          "status": {
              "total": 1,
              "failed": 0,
              "successful": 1
          },
          "request": {
              "fields": ["*"], 
              "query": { 
                  "match_none": ""
              }, 
              "knn": [
                  {
                      "k": 2, 
                      "field": "colorvect_dot", 
                      "vector": [ 0.707106781186548, 0, 0.707106781186548 ]
                  }
              ]
          },
          "hits": [
              {
                  "index": "vector-sample.color.color-test_4d6a4a2f00f48fa2_4c1c5584",
                  "id": "#FF00FF",
                  "score": 0.9999999403953552,
                  "sort": [
                      "_score"
                  ],
                  "fields": {
                      "color": "magenta / fuchsia"
                  }
              },
              {
                  "index": "vector-sample.color.color-test_4d6a4a2f00f48fa2_4c1c5584",
                  "id": "#B000B0",
                  "score": 0.9999999403953552,
                  "sort": [
                      "_score"
                  ],
                  "fields": {
                      "color": "dark lavender"
                  }
              }
          ],
          "total_hits": 2,
          "cost": 0,
          "max_score": 0.9999999403953552,
          "took": 4608572,
          "facets": null
      }