Indexes
Index Definition
- GET /api/index
-
Returns all index definitions as JSON.
Permission Required: cluster.bucket[
bucket_name].fts!readRole 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!readRole Required: FTS-Admin
Parameters
-
indexName: required, string, URL path parameterThe 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!writeRole Required: FTS-Admin
Parameters
-
indexName: required, string, URL path parameterThe 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 exampleindexParamsJSON:{ "targets": { "yourIndexName": { "indexUUID": "" } } } -
For indexType
bleve, an exampleindexParamsJSON:{ "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 parameterSupported 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 parameterIntended 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 parameterFor 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!writeRole Required: FTS-Admin
Parameters
-
indexName: required, string, URL path parameterThe 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!manageRole Required: FTS-Admin
Parameters
-
indexName: required, string, URL path parameterThe name of the index whose control values will be modified.
-
op: required, string, URL path parameterAllowed 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!manageRole Required: FTS-Admin
Parameters
-
indexName: required, string, URL path parameterThe name of the index whose control values will be modified.
-
op: required, string, URL path parameterAllowed 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!manageRole Required: FTS-Admin
Parameters
-
indexName: required, string, URL path parameterThe name of the index whose control values will be modified.
-
op: required, string, URL path parameterAllowed 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!readRole 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!readRole 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!readRole Required: FTS-Searcher, FTS-Admin
Parameters
-
indexName: required, string, URL path parameterThe 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!readRole Required: FTS-Searcher, FTS-Admin
Parameters
-
indexName: required, string, URL path parameterThe 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!readRole Required: FTS-Searcher, FTS-Admin
Parameters
-
indexName: required, string, URL path parameterThe 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.