mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-04-25 23:57:20 -04:00
144 lines
4.9 KiB
Text
144 lines
4.9 KiB
Text
[role="xpack"]
|
|
[[put-query-rule]]
|
|
=== Create or update query rule
|
|
|
|
++++
|
|
<titleabbrev>Create or update query rule</titleabbrev>
|
|
++++
|
|
|
|
Creates or updates an individual query rule within a query ruleset.
|
|
|
|
[[put-query-rule-request]]
|
|
==== {api-request-title}
|
|
|
|
`PUT _query_rules/<ruleset_id>/_rule/<rule_id>`
|
|
|
|
[[put-query-rule-prereqs]]
|
|
==== {api-prereq-title}
|
|
|
|
Requires the `manage_search_query_rules` privilege.
|
|
|
|
[role="child_attributes"]
|
|
[[put-query-rule-request-body]]
|
|
(Required, object) Contains parameters for a query rule:
|
|
|
|
==== {api-request-body-title}
|
|
|
|
`type`::
|
|
(Required, string) The type of rule.
|
|
At this time only `pinned` query rule types are allowed.
|
|
|
|
`criteria`::
|
|
(Required, array of objects) The criteria that must be met for the rule to be applied.
|
|
If multiple criteria are specified for a rule, all criteria must be met for the rule to be applied.
|
|
|
|
Criteria must have the following information:
|
|
|
|
- `type` (Required, string) The type of criteria.
|
|
The following criteria types are supported:
|
|
+
|
|
--
|
|
- `exact`
|
|
Only exact matches meet the criteria defined by the rule.
|
|
Applicable for string or numerical values.
|
|
- `fuzzy`
|
|
Exact matches or matches within the allowed {wikipedia}/Levenshtein_distance[Levenshtein Edit Distance] meet the criteria defined by the rule.
|
|
Only applicable for string values.
|
|
- `prefix`
|
|
Matches that start with this value meet the criteria defined by the rule.
|
|
Only applicable for string values.
|
|
- `suffix`
|
|
Matches that end with this value meet the criteria defined by the rule.
|
|
Only applicable for string values.
|
|
- `contains`
|
|
Matches that contain this value anywhere in the field meet the criteria defined by the rule.
|
|
Only applicable for string values.
|
|
- `lt`
|
|
Matches with a value less than this value meet the criteria defined by the rule.
|
|
Only applicable for numerical values.
|
|
- `lte`
|
|
Matches with a value less than or equal to this value meet the criteria defined by the rule.
|
|
Only applicable for numerical values.
|
|
- `gt`
|
|
Matches with a value greater than this value meet the criteria defined by the rule.
|
|
Only applicable for numerical values.
|
|
- `gte`
|
|
Matches with a value greater than or equal to this value meet the criteria defined by the rule.
|
|
Only applicable for numerical values.
|
|
- `always`
|
|
Matches all queries, regardless of input.
|
|
--
|
|
- `metadata` (Optional, string) The metadata field to match against.
|
|
This metadata will be used to match against `match_criteria` sent in the <<query-dsl-rule-query>>.
|
|
Required for all criteria types except `always`.
|
|
- `values` (Optional, array of strings) The values to match against the metadata field.
|
|
Only one value must match for the criteria to be met.
|
|
Required for all criteria types except `always`.
|
|
|
|
`actions`::
|
|
(Required, object) The actions to take when the rule is matched.
|
|
The format of this action depends on the rule type.
|
|
|
|
Actions depend on the rule type.
|
|
For `pinned` rules, actions follow the format specified by the <<query-dsl-pinned-query,Pinned Query>>.
|
|
The following actions are allowed:
|
|
|
|
- `ids` (Optional, array of strings) The unique <<mapping-id-field, document IDs>> of the documents to pin.
|
|
Only one of `ids` or `docs` may be specified, and at least one must be specified.
|
|
- `docs` (Optional, array of objects) The documents to pin.
|
|
Only one of `ids` or `docs` may be specified, and at least one must be specified.
|
|
You can specify the following attributes for each document:
|
|
+
|
|
--
|
|
- `_index` (Required, string) The index of the document to pin.
|
|
- `_id` (Required, string) The unique <<mapping-id-field, document ID>>.
|
|
--
|
|
|
|
IMPORTANT: Due to limitations within <<query-dsl-pinned-query,Pinned queries>>, you can only pin documents using `ids` or `docs`, but cannot use both in single rule.
|
|
It is advised to use one or the other in query rulesets, to avoid errors.
|
|
Additionally, pinned queries have a maximum limit of 100 pinned hits.
|
|
If multiple matching rules pin more than 100 documents, only the first 100 documents are pinned in the order they are specified in the ruleset.
|
|
|
|
[[put-query-rule-example]]
|
|
==== {api-examples-title}
|
|
|
|
The following example creates a new query rule with the ID `my-rule1` in a query ruleset called `my-ruleset`.
|
|
|
|
`my-rule1` will pin documents with IDs `id1` and `id2` when `user_query` contains `pugs` _or_ `puggles` **and** `user_country` exactly matches `us`.
|
|
|
|
[source,console]
|
|
----
|
|
PUT _query_rules/my-ruleset/_rule/my-rule1
|
|
{
|
|
"type": "pinned",
|
|
"criteria": [
|
|
{
|
|
"type": "contains",
|
|
"metadata": "user_query",
|
|
"values": [ "pugs", "puggles" ]
|
|
},
|
|
{
|
|
"type": "exact",
|
|
"metadata": "user_country",
|
|
"values": [ "us" ]
|
|
}
|
|
],
|
|
"actions": {
|
|
"ids": [
|
|
"id1",
|
|
"id2"
|
|
]
|
|
}
|
|
}
|
|
----
|
|
// TESTSETUP
|
|
|
|
//////////////////////////
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
DELETE _query_rules/my-ruleset
|
|
--------------------------------------------------
|
|
// TEARDOWN
|
|
|
|
//////////////////////////
|