OpenSearch/docs/reference/search/count.asciidoc

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

Gets the number of matches for a search query.

[source,console]
--------------------------------------------------
GET /twitter/_count?q=user:kimchy
--------------------------------------------------
// TEST[setup:twitter]

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


[[search-count-api-request]]
==== {api-request-title}

`GET /<target>/_count`


[[search-count-api-desc]]
==== {api-description-title}

The count API allows you to execute a query and get the number of matches for 
that query. 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.

The count API supports <<multi-index,multi-target syntax>>. You can run a single
count API search across multiple data streams and indices.

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


[[search-count-api-path-params]]
==== {api-path-parms-title}

`<target>`::

(Optional, string)
Comma-separated list or wildcard (`*`) expression of data streams, indices,
and index aliases used to limit the search.
+
To search all data streams and indices in a cluster, omit this parameter or use
`_all` or `*`.

[[search-count-api-query-params]]
==== {api-query-parms-title}

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=allow-no-indices]
+
Defaults to `true`.

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=analyzer]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=analyze_wildcard]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=default_operator]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=df]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]
+
Defaults to `open`.

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=ignore_throttled]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=lenient]

`min_score`::
(Optional, float)
  Sets the minimum `_score` value that documents must have to be included in the 
  result.

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=preference]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=search-q]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=routing]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=terminate_after]


[[search-count-request-body]]
==== {api-request-body-title}

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=query]


[[search-count-api-example]]
==== {api-examples-title}

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

GET /twitter/_count?q=user:kimchy

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

Both examples above do the same: count the number of tweets from the `twitter` 
index for a certain user. The API returns the following response:

[source,console-result]
--------------------------------------------------
{
    "count" : 1,
    "_shards" : {
        "total" : 1,
        "successful" : 1,
        "skipped" : 0,
        "failed" : 0
    }
}
--------------------------------------------------

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