elasticsearch/docs/reference/search/search-your-data/search-using-query-rules.asciidoc

[[search-using-query-rules]]
== Searching with query rules
++++
<titleabbrev>Searching with query rules</titleabbrev>
++++

[[query-rules]]

preview::[]

_Query rules_ allow customization of search results for queries that match specified criteria metadata.
This allows for more control over results, for example ensuring that promoted documents that match defined criteria are returned at the top of the result list.
Metadata is defined in the query rule, and is matched against the query criteria.
Query rules use metadata to match a query.
Metadata is provided as part of the `rule_query` as an object and can be anything that helps differentiate the query, for example:

* A user-entered query string
* Personalized metadata about users (e.g. country, language, etc)
* A particular topic
* A referring site
* etc.

Query rules define a metadata key that will be used to match the metadata provided in the `rule_query` with the criteria specified in the rule.

When a query rule matches the `rule_query` metadata according to its defined criteria, the query rule action is applied to the underlying `organic_query`.

For example, a query rule could be defined to match a user-entered query string of `pugs` and a country `us` and promote adoptable shelter dogs if the rule query met both criteria.

Rules are defined using the <<query-rules-apis, query rules API>> and searched using the <<query-dsl-rule-query,rule query>>.

[discrete]
[[query-rule-definition]]
=== Rule definition

When defining a rule, consider the following:

[discrete]
[[query-rule-type]]
==== Rule type

The type of rule we want to apply. For the moment there is a single rule type:

* `pinned` will re-write the query into a <<query-dsl-pinned-query, pinned query>>, pinning specified results matching the query rule at the top of the returned result set.


[discrete]
[[query-rule-criteria]]
==== Rule criteria

The criteria for which this rule will match. Criteria is defined as `type`, `metadata`, and `values`.
Allowed criteria types are:

[cols="2*", options="header"]
|===
|Type
|Match Requirements

|`exact`
|Rule metadata matches the specified value exactly.

|`fuzzy`
|Rule metadata matches the specified value within an allowed {wikipedia}/Levenshtein_distance[Levenshtein edit distance].

|`prefix`
|Rule metadata starts with the specified value.

|`suffix`
|Rule metadata ends with the specified value.

|`contains`
|Rule metadata contains the specified value.

|`lt`
|Rule metadata is less than the specified value.

|`lte`
|Rule metadata is less than or equal to the specified value.

|`gt`
|Rule metadata is greater than the specified value.

|`gte`
|Rule metadata is greater than or equal to the specified value.

|`always`
|Always matches for all rule queries.
|===

[discrete]
[[query-rule-actions]]
==== Rule actions

The actions to take when the rule matches a query:

* `ids` will pin the specified <<mapping-id-field,`_id`>>s.
* `docs` will pin the specified documents in the specified indices.

Use `ids` when searching over a single index, and `docs` when searching over multiple indices.
`ids` and `docs` cannot be combined in the same query.
See <<query-dsl-pinned-query,pinned query>> for details.

[discrete]
[[add-query-rules]]
=== Add query rules

You can add query rules using the <<put-query-ruleset>> call. This adds a ruleset containing one or more query rules that will be applied to queries that match their specified criteria.

The following command will create a query ruleset called `my-ruleset` with two pinned document rules:

* The first rule will generate a <<query-dsl-pinned-query>> pinning the <<mapping-id-field,`_id`>>s `id1` and `id2` when the `query_string` metadata value is a fuzzy match to either `puggles` or `pugs` _and_ the user's location is in the US.
* The second rule will generate a <<query-dsl-pinned-query>> pinning the <<mapping-id-field, `_id`>> of `id3` specifically from the `my-index-000001` index and `id4` from the `my-index-000002` index when the `query_string` metadata value contains `beagles`.

////
[source,console]
----
PUT /my-index-000001
----
// TESTSETUP
////

[source,console]
----
PUT /_query_rules/my-ruleset
{
  "rules": [
    {
      "rule_id": "rule1",
      "type": "pinned",
      "criteria": [
        {
          "type": "fuzzy",
          "metadata": "query_string",
          "values": [ "puggles", "pugs" ]
        },
        {
          "type": "exact",
          "metadata": "user_country",
          "values": [ "us" ]
        }
      ],
      "actions": {
        "ids": [
          "id1",
          "id2"
        ]
      }
    },
    {
      "rule_id": "rule2",
      "type": "pinned",
      "criteria": [
        {
          "type": "contains",
          "metadata": "query_string",
          "values": [ "beagles" ]
        }
      ],
      "actions": {
        "docs": [
          {
            "_index": "my-index-000001",
            "_id": "id3"
          },
          {
            "_index": "my-index-000002",
            "_id": "id4"
          }
        ]
      }
    }
  ]
}
----

The API response returns a results of `created` or `updated` depending on whether this was a new or edited ruleset.

[source,console-result]
----
{
  "result": "created"
}
----
// TEST[continued]

You can use the <<get-query-ruleset>> call to retrieve the ruleset you just created,
the <<list-query-rulesets>> call to retrieve a summary of all query rulesets,
and the <<delete-query-ruleset>> call to delete a query ruleset.

[discrete]
[[rule-query-search]]
=== Perform a rule query

Once you have defined a query ruleset, you can search this ruleset using the <<query-dsl-rule-query>> query.
An example query for the `my-ruleset` defined above is:

[source,console]
----
GET /my-index-000001/_search
{
  "query": {
    "rule_query": {
      "organic": {
        "query_string": {
          "query": "puggles"
        }
      },
      "match_criteria": {
        "query_string": "puggles",
        "user_country": "us"
      },
      "ruleset_id": "my-ruleset"
    }
  }
}
----
// TEST[continued]

This rule query will match against `rule1` in the defined query ruleset, and will convert the organic query into a pinned query with `id1` and `id2` pinned as the top hits.
Any other matches from the organic query will be returned below the pinned results.