[role="xpack"]
[[query-dsl-rule-query]]
=== Rule query
++++
<titleabbrev>Rule</titleabbrev>
++++

preview::[]

Applies <<query-rules-apis,query rules>> to the query before returning results.
This feature is used to promote documents in the manner of a <<query-dsl-pinned-query>> based on matching defined rules.
If no matching query rules are defined, the "organic" matches for the query are returned.
All matching rules are applied in the order in which they appear in the query ruleset.

[NOTE]
====
To use the rule query, you first need a defined set of query rules.
Use the <<query-rules-apis, query rules management APIs>> to create and manage query rules.
For more information and examples see <<search-using-query-rules>>.
====

==== Example request

////

[source,console]
--------------------------------------------------
PUT _query_rules/my-ruleset
{
  "rules": [
    {
      "rule_id": "my-rule1",
      "type": "pinned",
      "criteria": [
        {
          "type": "exact",
          "metadata": "user_query",
          "values": ["puggles"]
        }
      ],
      "actions": {
        "ids": [ "id1" ]
      }
    }
  ]
}
--------------------------------------------------
// TESTSETUP

[source,console]
--------------------------------------------------
DELETE _query_rules/my-ruleset
--------------------------------------------------
// TEARDOWN

////

[source,console]
--------------------------------------------------
GET /_search
{
  "query": {
    "rule_query": {
      "match_criteria": {
        "user_query": "pugs"
      },
      "ruleset_id": "my-ruleset",
      "organic": {
        "match": {
          "description": "puggles"
        }
      }
    }
  }
}
--------------------------------------------------

[[rule-query-top-level-parameters]]
==== Top-level parameters for `rule_query`

`ruleset_id`::
(Required, string) A unique <<query-rules-apis, query ruleset>> ID with query-based rules to match and apply as applicable.
`match_criteria`::
(Required, object) Defines the match criteria to apply to rules in the given query ruleset.
Match criteria should match the keys defined in the `criteria.metadata` field of the rule.
`organic`::
(Required, object) Any choice of <<query-dsl, query>> used to return results, that may be modified by matching query rules.
If no query rules are matched and applied, this query will be executed with no modification.