1.3.19. /{db}/_index_info

Added in version 3.6.

GET /{db}/_index_info

Return index status grouped by type: view_indexes, search_indexes and nouveau_indexes. Each entry identifies the index by its design document (ddoc) and, for search and nouveau indexes, its name, like GET /{db}/_index. In the info field return the same object returned as we get from the individual design doc _info endpoints: GET /{db}/_design/{ddoc}/_info or the search_index, GET /{db}/_design/{ddoc}/_search_info/{index} and GET /{db}/_design/{ddoc}/_nouveau_info/{index}. See Index Information.

This endpoint may be used when one needs to know whether a database’s indexes are fully built, for example before switching traffic to a replica.

Parameters:

• db – Database name

Query Parameters:

• type (string) – Filter by type. Can be one of these values: view, search and nouveau, or several of them comma separated. Optional, default: all types.

• startkey (json) – Return indexes of design documents with a doc ID greater than or equal to this key. Same as for GET /{db}/_design_docs. To get the next page, pass the bookmark of the previous response as the startkey. see Paging. Optional

• start_key (json) – Alias for startkey. Optional

• endkey (json) – Return indexes of design documents with a doc ID less than or equal to this key. Optional

• end_key (json) – Alias for endkey. Optional

• inclusive_end (boolean) – Whether the design document with the endkey doc ID is included. Default is true. Optional

• descending (boolean) – Traverse design documents in descending order, as GET /{db}/_design_docs does. Default is false. Optional

• limit (number) – Return indexes of at most this many design documents. Design documents without indexes count towards the limit too. A request may traverse at most max_ddoc_number_for_index_info_req design documents, see Paging. Optional

• skip (number) – How many design documents to skip before starting to return results. For paging it’s best to use startkey with the bookmark of the previous response, see Paging. Optional

• keys (json) – Return indexes for the design documents with these doc IDs only. Should be a JSON array of strings. POST /{db}/_index_info can take the same ID list in the request body. Optional

Request Headers:

• Accept –

  • application/json

  • text/plain

Response Headers:

• Content-Type –

  • application/json

  • text/plain; charset=utf-8

Response JSON Object:

• total_rows (number) – Total number of design docs. Same as returned in GET /{db}/_design_docs. Can be used for paging to see how many design document to expect overall. Note: a design document may have more than on index defined.

• bookmark (string) – The doc ID of the first design document after the ones from the result. Use it as the the startkey of the next page to paginate. It will be null when there are no more design documents, or when keys are used. See Paging.

• view_indexes (array) – One entry per design doc for views. See Index Information.

• search_indexes (array) – One entry per search index.

• nouveau_indexes (array) – One entry per nouveau index.

Status Codes:

• 200 OK – Request was successful

• 400 Bad Request – Invalid db name or parameter. Or, total design document selected is over the max_ddoc_number_for_index_info_req limit.

• 401 Unauthorized – Unauthorized request

• 403 Forbidden – Insufficient permissions / Too many requests with invalid credentials

• 404 Not Found – Database doesn’t exist

Request:

GET /recipes/_index_info HTTP/1.1
Accept: application/json
Host: localhost:5984

Response:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Type: application/json
Date: Mon, 01 Sep 2025 15:42:11 GMT
Server: CouchDB (Erlang/OTP)

{
    "total_rows": 2,
    "bookmark": null,
    "view_indexes": [
        {
            "ddoc": "_design/8c2a4caf8ea1b581ac43a062fd43a876dee1382d",
            "views": [
                "by-rating"
            ],
            "ok": true,
            "info": {
                "updates_pending": {
                    "minimum": 54,
                    "preferred": 54,
                    "total": 324,
                    "maximum": 54,
                    "copies": 6,
                    "copies_expected": 6
                },
                "collator_versions": [
                    "153.136"
                ],
                "compact_running": false,
                "language": "query",
                "purge_seq": 0,
                "signature": "b77547252cb8b19ff12831973b576c0f",
                "sizes": {
                    "active": 0,
                    "external": 10,
                    "file": 102
                },
                "update_seq": 0,
                "updater_running": false,
                "waiting_clients": 0,
                "waiting_commit": false
            }
        },
        {
            "ddoc": "_design/cookbook",
            "views": [
                "by_ingredient",
                "by_title"
            ],
            "ok": true,
            "info": {
                "updates_pending": {
                    "minimum": 0,
                    "preferred": 0,
                    "total": 0,
                    "maximum": 0,
                    "copies": 6,
                    "copies_expected": 6
                },
                "collator_versions": [
                    "153.136"
                ],
                "compact_running": false,
                "language": "javascript",
                "purge_seq": 0,
                "signature": "a6d97b0199e54a1eb56e4becb1322587",
                "sizes": {
                    "active": 1825,
                    "external": 1355,
                    "file": 16750
                },
                "update_seq": 54,
                "updater_running": false,
                "waiting_clients": 0,
                "waiting_commit": false
            }
        }
    ],
    "search_indexes": [
        {
            "ddoc": "_design/cookbook",
            "name": "ingredients",
            "ok": true,
            "info": {
                "updates_pending": {
                    "minimum": 0,
                    "preferred": 0,
                    "total": 0,
                    "maximum": 0,
                    "copies": 6,
                    "copies_expected": 6
                },
                "committed_seq": 54,
                "disk_size": 3960,
                "doc_count": 50,
                "doc_del_count": 0,
                "pending_seq": 54,
                "signature": "0b4ba635d5eb4fcbb2f6c9c2247460ec"
            }
        },
        {
            "ddoc": "_design/cookbook",
            "name": "steps",
            "ok": true,
            "info": {
                "updates_pending": {
                    "minimum": 0,
                    "preferred": 0,
                    "total": 12,
                    "maximum": 12,
                    "copies": 6,
                    "copies_expected": 6
                },
                "committed_seq": 42,
                "disk_size": 2210,
                "doc_count": 38,
                "doc_del_count": 0,
                "pending_seq": 42,
                "signature": "efc82e779a1f10ec90b2fbf0bc5246dd"
            }
        }
    ],
    "nouveau_indexes": [
        {
            "ddoc": "_design/cookbook",
            "name": "ingredients",
            "ok": true,
            "info": {
                "updates_pending": {
                    "minimum": 0,
                    "preferred": 0,
                    "total": 0,
                    "maximum": 0,
                    "copies": 6,
                    "copies_expected": 6
                },
                "disk_size": 6324,
                "num_docs": 50,
                "purge_seq": 0,
                "signature": "ea87fe8f9517403691850f51d0a1ce3e5afaf89347204dd79430252a0591e503",
                "update_seq": 54
            }
        }
    ]
}

Here the cookbook design doc has two views, two search indexes and a nouveau index. All are built on all 6 copies except the steps search index, which lags 12 updates behind. The first index is a query (Mango) which wasn’t built yet, so all copies are behind.

POST /{db}/_index_info

Same as GET /{db}/_index_info, with the parameters given in the body, like POST /{db}/_design_docs. A keys array selects the design docs to report by ID, like POST /_dbs_info.

Parameters:

• db – Database name

Request Headers:

• Accept –

  • application/json

  • text/plain

• Content-Type – application/json

Request JSON Object:

• keys (array) – Doc IDs of the design docs to report, for example ["_design/cookbook"]. Other GET /{db}/_index_info parameters can provided in the body as well. Optional

Response Headers:

• Content-Type –

  • application/json

  • text/plain; charset=utf-8

Response JSON Object:

• total_rows (number) – Number of design docs in the database. Same as for GET /{db}/_index_info

• bookmark (string) – Same as for GET /{db}/_index_info. null for a keys request, which has no next page

• view_indexes (array) – Same as GET /{db}/_index_info

• search_indexes (array) – Same as GET /{db}/_index_info

• nouveau_indexes (array) – Same as GET /{db}/_index_info

Status Codes:

• 200 OK – Request was successful

• 400 Bad Request – Invalid db name or parameter, or more keys than the max_ddoc_number_for_index_info_req limit.

• 401 Unauthorized – Unauthorized request

• 403 Forbidden – Insufficient permissions / Too many requests with invalid credentials

• 404 Not Found – Database doesn’t exist

Request:

POST /recipes/_index_info?type=search HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: localhost:5984

{
    "keys": [
        "_design/cookbook"
    ]
}

Response:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Type: application/json
Date: Mon, 01 Sep 2025 15:42:11 GMT
Server: CouchDB (Erlang/OTP)

{
    "total_rows": 2,
    "bookmark": null,
    "view_indexes": [],
    "search_indexes": [
        {
            "ddoc": "_design/cookbook",
            "name": "ingredients",
            "ok": true,
            "info": {
                "updates_pending": {
                    "minimum": 0,
                    "preferred": 0,
                    "total": 0,
                    "maximum": 0,
                    "copies": 6,
                    "copies_expected": 6
                },
                "committed_seq": 54,
                "disk_size": 3960,
                "doc_count": 50,
                "doc_del_count": 0,
                "pending_seq": 54,
                "signature": "0b4ba635d5eb4fcbb2f6c9c2247460ec"
            }
        },
        {
            "ddoc": "_design/cookbook",
            "name": "steps",
            "ok": true,
            "info": {
                "updates_pending": {
                    "minimum": 0,
                    "preferred": 0,
                    "total": 12,
                    "maximum": 12,
                    "copies": 6,
                    "copies_expected": 6
                },
                "committed_seq": 42,
                "disk_size": 2210,
                "doc_count": 38,
                "doc_del_count": 0,
                "pending_seq": 42,
                "signature": "efc82e779a1f10ec90b2fbf0bc5246dd"
            }
        }
    ],
    "nouveau_indexes": []
}

We filter to return only search type indexes.

1.3.19.1. Index Information

All three types of index lists are returned. Each one may be empty if not indexes are found or they are filtered based on the type parameter. Each element of the list will contain:

• ddoc (string): The design doc ID.

• name (string): Index name for search and nouveau indexes.

• views (array): A list of map-reduce views for a view group

• ok (boolean): true if we successfully fetched info about that index and false if we couldn’t (see Errors below).

• info (object): Info object of the index. This is the same as the returned by individual index _info endpoints: View Index Information, GET /{db}/_design/{ddoc}/_search_info/{index} and GET /{db}/_design/{ddoc}/_nouveau_info/{index}.

1.3.19.1.1. Paging

The same traversal parameters as for GET /{db}/_design_docs can be used. Paging is per design document, not per index. total_rows is the number of design documents in the database including design documents which may not have any indexes.

To page, request limit=N and pass the bookmark of each response as the startkey of the next request, until it is null.

GET /recipes/_index_info?limit=100

{
    "total_rows": 250,
    "bookmark": "_design/d0100",
    "view_indexes": [ ... ],
    "search_indexes": [ ... ],
    "nouveau_indexes": [ ... ]
}

GET /recipes/_index_info?limit=100&startkey="_design/d0100"

A single request can process at most [chttpd] max_ddoc_number_for_index_info_req design docs. This is similar to max_db_number_for_dbs_info_req for POST /_dbs_info. If a request selects more than that, the request will fail with an error:

{
    "error": "bad_request",
    "reason": "too_many_design_docs"
}

1.3.19.1.2. Pending updates

The info object of every entry with ok set to true has an updates_pending object. Its fields are described in View Index Information. In summary:

• minimum will be 0 when at least one complete copy of the index exists for every range.

• maximum will be 0 when all shard copies are completely built.

• preferred and total are the backlogs of the preferred shard copies and of all shard copies added together.

• copies how many shard copies returned results. This may be smaller than copies_expected for example if some nodes are not reachable or in maintenance mode

1.3.19.1.3. Errors

If index info could not be obtained for some then the index entry will have ok set to false. And the index entry will have error and reason fields instead of info. This is the same as how POST /{db}/_bulk_docs reports per document errors. For example if clouseau (search indexing system) is down:

{
    "ddoc": "_design/cookbook",
    "name": "ingredients",
    "ok": false,
    "error": "service unavailable",
    "reason": "Search is not available"
}

Invalid type values return a 400 Bad Request:

{
    "error": "query_parse_error",
    "reason": "Invalid type: foo. Must be view, search or nouveau"
}