[DOCS] Reformats count API (#46377)
* [DOCS] Reformats count API. Co-Authored-By: James Rodewig <james.rodewig@elastic.co>
This commit is contained in:
István Zoltán Szabó
parent
c045bc7f54
commit
595bf52927
|
|
@ -197,6 +197,12 @@ tag::if_seq_no[]
|
|||
sequence number. See <<optimistic-concurrency-control-index>>.
|
||||
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
|
||||
|
|
@ -399,6 +405,12 @@ tag::search-q[]
|
|||
(Optional, string) Query in the Lucene query string syntax.
|
||||
end::search-q[]
|
||||
|
||||
tag::query[]
|
||||
`query`::
|
||||
(Optional, <<query-dsl,query object>>) Defines the search definition using the
|
||||
<<query-dsl,Query DSL>>.
|
||||
end::query[]
|
||||
|
||||
tag::refresh[]
|
||||
`refresh`::
|
||||
(Optional, enum) If `true`, {es} refreshes the affected shards to make this
|
||||
|
|
|
|||
|
|
@ -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 <<query-dsl,Query DSL>> 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 <<search-search,search api>> works.
|
||||
|
||||
|
||||
[[search-count-api-request]]
|
||||
==== {api-request-title}
|
||||
|
||||
`PUT /<index>/_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
|
||||
<<query-dsl,Query DSL>> defined within the request body.
|
||||
|
||||
The count API can be applied to <<search-multi-index,multiple 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}
|
||||
|
||||
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 <<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:
|
||||
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 <<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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue