diff --git a/docs/reference/rest-api/common-parms.asciidoc b/docs/reference/rest-api/common-parms.asciidoc index e40a799dd1520..91ea92de02609 100644 --- a/docs/reference/rest-api/common-parms.asciidoc +++ b/docs/reference/rest-api/common-parms.asciidoc @@ -181,6 +181,12 @@ tag::if_seq_no[] sequence number. See <>. end::if_seq_no[] +tag::ignore_throttled[] +`ignore_throttled`:: +(Optional, boolean) If `true`, concrete, expanded or aliased indices are +ignored when throttled. +end::ignore_throttled[] + tag::index-ignore-unavailable[] `ignore_unavailable`:: (Optional, boolean) If `true`, missing or closed indices are not included in the @@ -383,6 +389,12 @@ tag::search-q[] (Optional, string) Query in the Lucene query string syntax. end::search-q[] +tag::query[] +`query`:: +(Optional, <>) Defines the search definition using the +<>. +end::query[] + tag::refresh[] `refresh`:: (Optional, enum) If `true`, {es} refreshes the affected shards to make this diff --git a/docs/reference/search/count.asciidoc b/docs/reference/search/count.asciidoc index 331cf70685eec..1aa6eb51959b0 100644 --- a/docs/reference/search/count.asciidoc +++ b/docs/reference/search/count.asciidoc @@ -1,11 +1,90 @@ [[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 <> defined within the request -body. Here is an example: +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 <> works. + + +[[search-count-api-request]] +==== {api-request-title} + +`PUT //_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. 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 +<> defined within the request body. + +The count API can be applied to <>. + +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} + +include::{docdir}/rest-api/common-parms.asciidoc[tag=index] + + +[[search-count-api-query-params]] +==== {api-query-parms-title} + +include::{docdir}/rest-api/common-parms.asciidoc[tag=allow-no-indices] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=analyzer] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=analyze_wildcard] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=default_operator] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=df] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=expand-wildcards] ++ +Defaults to `open`. + +include::{docdir}/rest-api/common-parms.asciidoc[tag=ignore_throttled] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable] + +include::{docdir}/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::{docdir}/rest-api/common-parms.asciidoc[tag=preference] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=search-q] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=routing] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=terminate_after] + + +[[search-count-request-body]] +==== {api-request-body-title} + +include::{docdir}/rest-api/common-parms.asciidoc[tag=query] + + +[[search-count-api-example]] +==== {api-examples-title} [source,console] -------------------------------------------------- @@ -24,11 +103,8 @@ GET /twitter/_count } -------------------------------------------------- -NOTE: The query being sent in the body must be nested in a `query` key, same as -the <> 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: +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] -------------------------------------------------- @@ -45,62 +121,3 @@ tweets from the `twitter` index for a certain user. The result is: 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 <>. - -[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 <> 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.