1.5.5. /db/_design/design-doc/_search/index-name — Apache CouchDB® 3.3 Documentation

# 1.5.5. `/db/_design/design-doc/_search/index-name`

Warning

Search endpoints require a running search plugin connected to each cluster node. See Search Plugin Installation for details.

New in version 3.0.

GET /{db}/_design/{ddoc}/_search/{index}

  Executes a search request against the named index in the specified design document.

  Parameters:

    - db – Database name

    - ddoc – Design document name

    - index – Search index name

  Request Headers:

    - Accept –

      - application/json

      - text/plain

  Query Parameters:

    - bookmark (string) – A bookmark received from a previous search. This parameter enables paging through the results. If there are no more results after the bookmark, you get a response with an empty rows array and the same bookmark, confirming the end of the result list.

    - counts (json) – An array of names of string fields for which counts are requested. The response contains counts for each unique value of this field name among the documents that match the search query. Faceting must be enabled for this parameter to function.

    - drilldown (json) – This field can be used several times. Each use defines a pair with a field name and a value. The search matches only documents containing the value that was provided in the named field. It differs from using `"fieldname:value"` in the `q` parameter only in that the values are not analyzed. Faceting must be enabled for this parameter to function.

    - group_field (string) – Field by which to group search matches. :query number group_limit: Maximum group count. This field can be used only if `group_field` is specified.

    - group_sort (json) – This field defines the order of the groups in a search that uses `group_field`. The default sort order is relevance.

    - highlight_fields (json) – Specifies which fields to highlight. If specified, the result object contains a `highlights` field with an entry for each specified field.

    - highlight_pre_tag (string) – A string that is inserted before the highlighted word in the highlights output.

    - highlight_post_tag (string) – A string that is inserted after the highlighted word in the highlights output.

    - highlight_number (number) – Number of fragments that are returned in highlights. If the search term occurs less often than the number of fragments that are specified, longer fragments are returned.

    - highlight_size (number) – Number of characters in each fragment for highlights.

    - include_docs (boolean) – Include the full content of the documents in the response.

    - include_fields (json) – A JSON array of field names to include in search results. Any fields that are included must be indexed with the store:true option.

    - limit (number) – Limit the number of the returned documents to the specified number. For a grouped search, this parameter limits the number of documents per group.

    - q (string) – Alias for `query`.

    - query (string) – Required. The Lucene query string.

    - ranges (json) – This field defines ranges for faceted, numeric search fields. The value is a JSON object where the fields names are faceted numeric search fields, and the values of the fields are JSON objects. The field names of the JSON objects are names for ranges. The values are strings that describe the range, for example “[0 TO 10]”.

    - sort (json) – Specifies the sort order of the results. In a grouped search (when `group_field` is used), this parameter specifies the sort order within a group. The default sort order is relevance. A JSON string of the form `"fieldname<type>"` or `-fieldname<type>` for descending order, where fieldname is the name of a string or number field, and `type` is either a number, a string, or a JSON array of strings. The `type` part is optional, and defaults to number. Some examples are `"foo"`, `"-foo"`, `"bar<string>"`, `"-foo<number>"` and [`"-foo<number>"`, `"bar<string>"`]. String fields that are used for sorting must not be analyzed fields. Fields that are used for sorting must be indexed by the same indexer that is used for the search query.

    - stale (string) – Set to `ok` to allow the use of an out-of-date index.

  Response Headers:

    - Content-Type –

      - application/json

      - text/plain; charset=utf-8

    - ETag – Response signature

    - Transfer-Encoding – `chunked`

  Response JSON Object:

    - rows (array) – Array of view row objects. By default the information returned contains only the document ID and revision.

    - total_rows (number) – Number of documents in the database/view.

    - bookmark (string) – Opaque identifier to enable pagination.

  Status Codes:

    - 200 OK – Request completed successfully

    - 400 Bad Request – Invalid request

    - 401 Unauthorized – Read permission required

    - 404 Not Found – Specified database, design document or view is missed

Note

You must enable faceting before you can use the `counts`, `drilldown`, and `ranges` parameters.

Note

Faceting and grouping are not supported on partitioned searches, so the following query parameters should not be used on those requests: `counts`, `drilldown`, `ranges`, and `group_field`, `group_limit`, group_sort``.

Note

Do not combine the `bookmark` and `stale` options. These options constrain the choice of shard replicas to use for the response. When used together, the options might cause problems when contact is attempted with replicas that are slow or not available.

See also

For more information about how search works, see the Search User Guide.

# 1.5.6. `/db/_design/design-doc/_search_info/index-name`

Warning

Search endpoints require a running search plugin connected to each cluster node. See Search Plugin Installation for details.

New in version 3.0.

GET /{db}/_design/{ddoc}/_search_info/{index}
  Parameters:

    - db – Database name

    - ddoc – Design document name

    - index – Search index name

  Status Codes:

    - 200 OK – Request completed successfully

    - 400 Bad Request – Request body is wrong (malformed or missing one of the mandatory fields)

    - 500 Internal Server Error – A server error (or other kind of error) occurred

Request:

    GET /recipes/_design/cookbook/_search_info/ingredients HTTP/1.1
    Accept: application/json
    Host: localhost:5984

Response:

    HTTP/1.1 200 OK
    Content-Type: application/json

    {
        "name": "_design/cookbook/ingredients",
        "search_index": {
            "pending_seq": 7125496,
            "doc_del_count": 129180,
            "doc_count": 1066173,
            "disk_size": 728305827,
            "committed_seq": 7125496
        }
    }