New

The executive guide to generative AI

Read more
About usPartnersSupport|Login

WARNING: Version 6.1 of Elasticsearch has passed its EOL date.

This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.

« Multi Search API Validate API »
Elastic Docs ›Elasticsearch Reference [6.1] ›Search APIs

Count API

edit

Count API

edit

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 and across one or more types. The query can either be provided using a simple query string as a parameter, or using the Query DSL defined within the request body. Here is an example:

PUT /twitter/tweet/1?refresh
{
    "user": "kimchy"
}

GET /twitter/tweet/_count?q=user:kimchy

GET /twitter/tweet/_count
{
    "query" : {
        "term" : { "user" : "kimchy" }
    }
}
Copy as curlTry in Elastic 

The query being sent in the body must be nested in a query key, same as the 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:

{
    "count" : 1,
    "_shards" : {
        "total" : 5,
        "successful" : 5,
        "skipped" : 0,
        "failed" : 0
    }
}

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

Multi index, Multi type

edit

The count API can be applied to multiple types in multiple indices.

Request Parameters

edit

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:

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.

Request Body

edit

The count can use the 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.

Distributed

edit

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.

Routing

edit

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.

« Multi Search API Validate API »

On this page

Was this helpful?
Feedback