mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-02-08 05:58:44 +00:00
18866c4c0b
This commit changes the format of the `hits.total` in the search response to be an object with a `value` and a `relation`. The `value` indicates the number of hits that match the query and the `relation` indicates whether the number is accurate (in which case the relation is equals to `eq`) or a lower bound of the total (in which case it is equals to `gte`). This change also adds a parameter called `rest_total_hits_as_int` that can be used in the search APIs to opt out from this change (retrieve the total hits as a number in the rest response). Note that currently all search responses are accurate (`track_total_hits: true`) or they don't contain `hits.total` (`track_total_hits: true`). We'll add a way to get a lower bound of the total hits in a follow up (to allow numbers to be passed to `track_total_hits`). Relates #33028
216 lines
9.0 KiB
Plaintext
216 lines
9.0 KiB
Plaintext
[[input-search]]
|
|
=== Search Input
|
|
|
|
Use the `search` input to load the results of an Elasticsearch search request
|
|
into the execution context when the watch is triggered. See
|
|
<<search-input-attributes, Search Input Attributes>> for all of the
|
|
supported attributes.
|
|
|
|
In the search input's `request` object, you specify:
|
|
|
|
* The indices you want to search
|
|
* The {ref}/search-request-search-type.html[search type]
|
|
* The search request body
|
|
|
|
The search request body supports the full Elasticsearch Query DSL--it's the
|
|
same as the body of an Elasticsearch `_search` request.
|
|
|
|
For example, the following input retrieves all `event`
|
|
documents from the `logs` index:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
"input" : {
|
|
"search" : {
|
|
"request" : {
|
|
"indices" : [ "logs" ],
|
|
"types" : [ "event" ],
|
|
"body" : {
|
|
"query" : { "match_all" : {}}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// NOTCONSOLE
|
|
|
|
You can use date math and wildcards when specifying indices. For example,
|
|
the following input loads the latest VIXZ quote from today's daily quotes index:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{
|
|
"input" : {
|
|
"search" : {
|
|
"request" : {
|
|
"indices" : [ "<stock-quotes-{now/d}>" ],
|
|
"body" : {
|
|
"size" : 1,
|
|
"sort" : {
|
|
"timestamp" : { "order" : "desc"}
|
|
},
|
|
"query" : {
|
|
"term" : { "symbol" : "vix"}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// NOTCONSOLE
|
|
|
|
==== Extracting Specific Fields
|
|
|
|
You can specify which fields in the search response you want to load into the
|
|
watch payload with the `extract` attribute. This is useful when a search
|
|
generates a large response and you are only interested in particular fields.
|
|
|
|
For example, the following input loads only the total number of hits into the
|
|
watch payload:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
"input": {
|
|
"search": {
|
|
"request": {
|
|
"indices": [ ".watcher-history*" ]
|
|
},
|
|
"extract": [ "hits.total.value" ]
|
|
}
|
|
},
|
|
--------------------------------------------------
|
|
// NOTCONSOLE
|
|
|
|
==== Using Templates
|
|
|
|
The `search` input supports {ref}/search-template.html[search templates]. For
|
|
example, the following snippet references the indexed template called
|
|
`my_template` and passes a value of 23 to fill in the template's `value`
|
|
parameter:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{
|
|
"input" : {
|
|
"search" : {
|
|
"request" : {
|
|
"indices" : [ "logs" ],
|
|
"template" : {
|
|
"id" : "my_template",
|
|
"params" : {
|
|
"value" : 23
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
...
|
|
}
|
|
--------------------------------------------------
|
|
// NOTCONSOLE
|
|
|
|
==== Applying Conditions
|
|
|
|
The `search` input is often used in conjunction with the <<condition-script,
|
|
`script`>> condition. For example, the following snippet adds a condition to
|
|
check if the search returned more than five hits:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{
|
|
"input" : {
|
|
"search" : {
|
|
"request" : {
|
|
"indices" : [ "logs" ],
|
|
"body" : {
|
|
"query" : { "match_all" : {} }
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"condition" : {
|
|
"compare" : { "ctx.payload.hits.total.value" : { "gt" : 5 }}
|
|
}
|
|
...
|
|
}
|
|
--------------------------------------------------
|
|
// NOTCONSOLE
|
|
|
|
==== Accessing the Search Results
|
|
|
|
Conditions, transforms, and actions can access the search results through the
|
|
watch execution context. For example:
|
|
|
|
* To load all of the search hits into an email body, use `ctx.payload.hits`.
|
|
* To reference the total number of hits, use `ctx.payload.hits.total.value`.
|
|
* To access a particular hit, use its zero-based array index. For example, to
|
|
get the third hit, use `ctx.payload.hits.hits.2`.
|
|
* To get a field value from a particular hit, use
|
|
`ctx.payload.hits.hits.<index>.fields.<fieldname>`. For example, to get the
|
|
message field from the first hit, use `ctx.payload.hits.hits.0.fields.message`.
|
|
|
|
NOTE: The total number of hits in the search response is returned as an object
|
|
in the response. It contains a `value`, the number of hits, and a `relation` that
|
|
indicates if the value is accurate (`"eq"`) or a lower bound of the total hits
|
|
that match the query (`"gte"`). You can set `track_total_hits` to true in
|
|
the search request to tell Elasticsearch to always track the number of hits
|
|
accurately.
|
|
|
|
[[search-input-attributes]]
|
|
==== Search Input Attributes
|
|
|
|
[cols=",^,,", options="header"]
|
|
|======
|
|
| Name |Required | Default | Description
|
|
|
|
| `request.search_type` | no | `query_then_fetch` | The {ref}/search-request-search-type.html#search-request-search-type[type]
|
|
of search request to perform. Valid values are: `dfs_query_and_fetch`,
|
|
`dfs_query_then_fetch`, `query_and_fetch`, and `query_then_fetch`. The
|
|
Elasticsearch default is `query_then_fetch`.
|
|
|
|
| `request.indices` | no | - | The indices to search. If omitted, all indices are searched, which is the
|
|
default behaviour in Elasticsearch.
|
|
|
|
| `request.types` | no | - | The document types to search for. If omitted, all document types are are
|
|
searched, which is the default behaviour in Elasticsearch.
|
|
|
|
| `request.body` | no | - | The body of the request. The {ref}/search-request-body.html[request body]
|
|
follows the same structure you normally send in the body of a REST `_search`
|
|
request. The body can be static text or include `mustache` <<templates, templates>>.
|
|
|
|
| `request.template` | no | - | The body of the search template. See <<templates, configure templates>>
|
|
for more information.
|
|
|
|
| `request.indices_options.expand_wildcards` | no | `open` | How to expand wildcards. Valid values are: `all`, `open`, `closed`, and `none`
|
|
See {ref}/multi-index.html#multi-index[`expand_wildcards`] for more information.
|
|
|
|
| `request.indices_options.ignore_unavailable` | no | `true` | Whether the search should ignore unavailable indices. See
|
|
{ref}/multi-index.html#multi-index[`ignore_unavailable`] for more information.
|
|
|
|
| `request.indices_options.allow_no_indices` | no | `true` | Whether to allow a search where a wildcard indices expression results in no
|
|
concrete indices. See {ref}/multi-index.html#multi-index[allow_no_indices]
|
|
for more information.
|
|
|
|
| `extract` | no | - | A array of JSON keys to extract from the search response and load as the payload.
|
|
When a search generates a large response, you can use `extract` to select the
|
|
relevant fields instead of loading the entire response.
|
|
|
|
| `timeout` | no | 30s | The timeout for waiting for the search api call to return. If no response is
|
|
returned within this time, the search input times out and fails. This setting
|
|
overrides the default search operations timeouts.
|
|
|======
|
|
|
|
You can reference the following variables in the execution context when
|
|
specifying the request `body`:
|
|
|
|
[options="header"]
|
|
|======
|
|
| Name | Description
|
|
| `ctx.watch_id` | The id of the watch that is currently executing.
|
|
| `ctx.execution_time` | The time execution of this watch started.
|
|
| `ctx.trigger.triggered_time` | The time this watch was triggered.
|
|
| `ctx.trigger.scheduled_time` | The time this watch was supposed to be triggered.
|
|
| `ctx.metadata.*` | Any metadata associated with the watch.
|
|
|======
|