Count API
editCount API
editGets the number of matches for a search query.
GET /my-index-000001/_count?q=user:kimchy
The query being sent in the body must be nested in a query
key, same as
the search API works.
Request
editGET /<target>/_count
Prerequisites
edit-
If the Elasticsearch security features are enabled, you must have the
read
index privilege for the target data stream, index, or index alias.
Description
editThe 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 defined within the request body.
The count API supports 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.
Path parameters
edit-
<target>
-
(Optional, string) Comma-separated list of data streams, indices, and index aliases to search. Wildcard (
*
) expressions are supported.To search all data streams and indices in a cluster, omit this parameter or use
_all
or*
.
Query parameters
edit-
allow_no_indices
-
(Optional, Boolean) If
false
, the request returns an error if any wildcard expression, index alias, or_all
value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targetingfoo*,bar*
returns an error if an index starts withfoo
but no index starts withbar
.Defaults to
true
. -
analyzer
-
(Optional, string) Analyzer to use for the query string.
This parameter can only be used when the
q
query string parameter is specified. -
analyze_wildcard
-
(Optional, Boolean) If
true
, wildcard and prefix queries are analyzed. Defaults tofalse
.This parameter can only be used when the
q
query string parameter is specified. -
default_operator
-
(Optional, string) The default operator for query string query: AND or OR. Defaults to
OR
.This parameter can only be used when the
q
query string parameter is specified. -
df
-
(Optional, string) Field to use as default where no field prefix is given in the query string.
This parameter can only be used when the
q
query string parameter is specified. -
expand_wildcards
-
(Optional, string) Controls what kind of indices that wildcard expressions can expand to. Multiple values are accepted when separated by a comma, as in
open,hidden
. Valid values are:-
all
- Expand to open and closed indices, including hidden indices.
-
open
- Expand only to open indices.
-
closed
- Expand only to closed indices.
-
hidden
-
Expansion of wildcards will include hidden indices.
Must be combined with
open
,closed
, or both. -
none
- Wildcard expressions are not accepted.
Defaults to
open
. -
-
ignore_throttled
-
(Optional, Boolean) If
true
, concrete, expanded or aliased indices are ignored when frozen. Defaults totrue
. -
ignore_unavailable
-
(Optional, Boolean) If
false
, the request returns an error if it targets a missing or closed index. Defaults tofalse
. -
lenient
-
(Optional, Boolean) If
true
, format-based query failures (such as providing text to a numeric field) in the query string will be ignored. Defaults tofalse
.This parameter can only be used when the
q
query string parameter is specified. -
min_score
-
(Optional, float)
Sets the minimum
_score
value that documents must have to be included in the result. -
preference
- (Optional, string) Specifies the node or shard the operation should be performed on. Random by default.
-
q
- (Optional, string) Query in the Lucene query string syntax.
-
routing
- (Optional, string) Target the specified primary shard.
-
terminate_after
- (Optional, integer) The maximum number of documents to collect for each shard, upon reaching which the query execution will terminate early.
Request body
edit-
query
- (Optional, query object) Defines the search definition using the Query DSL.
Examples
editPUT /my-index-000001/_doc/1?refresh { "user.id": "kimchy" } GET /my-index-000001/_count?q=user:kimchy GET /my-index-000001/_count { "query" : { "term" : { "user.id" : "kimchy" } } }
Both examples above do the same: count the number of documents in
my-index-000001
with a user.id
of kimchy
. The API returns the following response:
{ "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.