mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-04-25 07:37:19 -04:00
02c494963a
* Cleanup: Remove pinned IDs from applied rules in favor of single applied docs * Add support for query rules of type exclude, to exclude specified documents from result sets * Support exluded documents that specify the _index as well as the _id * Cleanup * Update docs/changelog/111420.yaml * Update docs * Spotless * PR feedback - docs updates * Apply PR feedback * PR feedback --------- Co-authored-by: Elastic Machine <elasticmachine@users.noreply.github.com>
179 lines
6.2 KiB
Text
179 lines
6.2 KiB
Text
[role="xpack"]
|
|
[[put-query-ruleset]]
|
|
=== Create or update query ruleset
|
|
|
|
++++
|
|
<titleabbrev>Create or update query ruleset</titleabbrev>
|
|
++++
|
|
|
|
Creates or updates a query ruleset.
|
|
|
|
[[put-query-ruleset-request]]
|
|
==== {api-request-title}
|
|
|
|
`PUT _query_rules/<ruleset_id>`
|
|
|
|
[[put-query-ruleset-prereqs]]
|
|
==== {api-prereq-title}
|
|
|
|
Requires the `manage_search_query_rules` privilege.
|
|
|
|
[role="child_attributes"]
|
|
[[put-query-ruleset-request-body]]
|
|
(Required, object) Contains parameters for a query ruleset:
|
|
|
|
==== {api-request-body-title}
|
|
|
|
`rules`::
|
|
(Required, array of objects) The specific rules included in this query ruleset.
|
|
|
|
There is a limit of 100 rules per ruleset.
|
|
This can be increased up to 1000 using the `xpack.applications.rules.max_rules_per_ruleset` cluster setting.
|
|
|
|
Each rule must have the following information:
|
|
|
|
- `rule_id` (Required, string) A unique identifier for this rule.
|
|
- `type` (Required, string) The type of rule.
|
|
At this time only `pinned` and `exclude` 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.
|
|
- `actions` (Required, object) The actions to take when the rule is matched.
|
|
The format of this action depends on the rule type.
|
|
|
|
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 depend on the rule type.
|
|
The following actions are allowed for `pinned` or `exclude` rules:
|
|
|
|
- `ids` (Optional, array of strings) The unique <<mapping-id-field, document IDs>> of the documents to apply the rule to.
|
|
Only one of `ids` or `docs` may be specified, and at least one must be specified.
|
|
- `docs` (Optional, array of objects) The documents to apply the rule to.
|
|
Only one of `ids` or `docs` may be specified, and at least one must be specified.
|
|
There is a maximum value of 100 documents in a rule.
|
|
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 select 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-ruleset-example]]
|
|
==== {api-examples-title}
|
|
|
|
The following example creates a new query ruleset called `my-ruleset`.
|
|
|
|
Two rules are associated with `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`.
|
|
- `my-rule2` will exclude documents from different, specified indices with IDs `id3` and `id4` when the `query_string` fuzzily matches `rescue dogs`.
|
|
|
|
[source,console]
|
|
----
|
|
PUT _query_rules/my-ruleset
|
|
{
|
|
"rules": [
|
|
{
|
|
"rule_id": "my-rule1",
|
|
"type": "pinned",
|
|
"criteria": [
|
|
{
|
|
"type": "contains",
|
|
"metadata": "user_query",
|
|
"values": [ "pugs", "puggles" ]
|
|
},
|
|
{
|
|
"type": "exact",
|
|
"metadata": "user_country",
|
|
"values": [ "us" ]
|
|
}
|
|
],
|
|
"actions": {
|
|
"ids": [
|
|
"id1",
|
|
"id2"
|
|
]
|
|
}
|
|
},
|
|
{
|
|
"rule_id": "my-rule2",
|
|
"type": "exclude",
|
|
"criteria": [
|
|
{
|
|
"type": "fuzzy",
|
|
"metadata": "user_query",
|
|
"values": [ "rescue dogs" ]
|
|
}
|
|
],
|
|
"actions": {
|
|
"docs": [
|
|
{
|
|
"_index": "index1",
|
|
"_id": "id3"
|
|
},
|
|
{
|
|
"_index": "index2",
|
|
"_id": "id4"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
]
|
|
}
|
|
----
|
|
// TESTSETUP
|
|
|
|
//////////////////////////
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
DELETE _query_rules/my-ruleset
|
|
--------------------------------------------------
|
|
// TEARDOWN
|
|
|
|
//////////////////////////
|