elasticsearch/docs/reference/query-rules/apis/put-query-rule.asciidoc

[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 the following query rule types are allowed:

- `pinned` will identify and pin specific documents to the top of search results.
- `exclude` will exclude specific documents from search results.

`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.
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.
If null, all documents with the specified `_id` will be affected across all searched indices.
- `_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 select documents to promote 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

//////////////////////////