OpenSearch/docs/reference/search/count.asciidoc

[[search-count]]
=== Count API

The count API allows to easily execute a query and get the number of
matches for that query. It can be executed across one or more indices.
The query can either be provided using a simple query string as a
parameter, or using the <<query-dsl,Query DSL>> defined within the request
body. Here is an example:

[source,js]
--------------------------------------------------
PUT /twitter/_doc/1?refresh
{
    "user": "kimchy"
}

GET /twitter/_count?q=user:kimchy

GET /twitter/_count
{
    "query" : {
        "term" : { "user" : "kimchy" }
    }
}
--------------------------------------------------
//CONSOLE

NOTE: The query being sent in the body must be nested in a `query` key, same as
the <<search-search,search api>> works

Both examples above do the same thing, which is count the number of
tweets from the `twitter` index for a certain user. The result is:

[source,js]
--------------------------------------------------
{
    "count" : 1,
    "_shards" : {
        "total" : 1,
        "successful" : 1,
        "skipped" : 0,
        "failed" : 0
    }
}
--------------------------------------------------
// TESTRESPONSE

The query is optional, and when not provided, it will use `match_all` to
count all the docs.

[float]
==== Multi index

The count API can be applied to <<search-multi-index,multiple indices>>.

[float]
==== Request Parameters

When executing count using the query parameter `q`, the query passed is
a query string using Lucene query parser. There are additional
parameters that can be passed:

[cols="<,<",options="header",]
|=======================================================================
|Name |Description
|`df` |The default field to use when no field prefix is defined within the
query.

|`analyzer` |The analyzer name to be used when analyzing the query string.

|`default_operator` |The default operator to be used, can be `AND` or
`OR`. Defaults to `OR`.

|`lenient` |If set to true will cause format based failures (like
providing text to a numeric field) to be ignored. Defaults to false.

|`analyze_wildcard` |Should wildcard and prefix queries be analyzed or
not. Defaults to `false`.

|`terminate_after` |The maximum count for each shard, upon
reaching which the query execution will terminate early.
If set, the response will have a boolean field `terminated_early` to
indicate whether the query execution has actually terminated_early.
Defaults to no terminate_after.
|=======================================================================

[float]
==== Request Body

The count can use the <<query-dsl,Query DSL>> within
its body in order to express the query that should be executed. The body
content can also be passed as a REST parameter named `source`.

Both HTTP GET and HTTP POST can be used to execute count with body.
Since not all clients support GET with body, POST is allowed as well.

[float]
==== Distributed

The count operation is broadcast across all shards. For each shard id
group, a replica is chosen and executed against it. This means that
replicas increase the scalability of count.

[float]
==== Routing

The routing value (a comma separated list of the routing values) can be
specified to control which shards the count request will be executed on.