# Dec 11th, 2024: \[EN\] Troubleshooting query rules

**URL:** <https://discuss.elastic.co/t/dec-11th-2024-en-troubleshooting-query-rules/369452>\
**Category:** Advent Calendar\
**Created:** [December 11, 2024, 8:00am UTC](https://discuss.elastic.co/t/dec-11th-2024-en-troubleshooting-query-rules/369452 "2024-12-11T08:00:40Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![Kathleen\_DeRusso](https://sea2.discourse-cdn.com/elastic/user_avatar/discuss.elastic.co/kathleen_derusso/32/132039_2.png) [@Kathleen\_DeRusso](https://discuss.elastic.co/u/Kathleen_DeRusso)\
**Post date:** [December 11, 2024, 8:00am UTC](https://discuss.elastic.co/t/dec-11th-2024-en-troubleshooting-query-rules/369452/1 "2024-12-11T08:00:40Z")

</div>

[Query rules](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-using-query-rules.html) offer users a way to have fine grained control over specific queries. Currently, the capabilities of query rules allow you to pin the search results you choose at the top of the result set, and/or exclude specific documents from a result set based on contextual query data.

There are several use cases for this type of find tuned control. These include applying business rules such as promotional campaigns to your search results or “fixing” highly visible problematic queries.

Query rules are accessible using the [rule query](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-rule-query.html) and will soon be available as a [retriever](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-rules-apis.html) that works with reranking strategies such as [RRF](https://www.elastic.co/guide/en/elasticsearch/reference/current/rrf.html)!

This post is about how you know whether your query rules are working as intended.

Let's start with a very simple example, that contains a single pinned rule and a single exclude rule:

```auto
PUT my-index/_doc/my-pinned-doc
{
  "title": "My pinned document"
}

PUT my-index/_doc/my-excluded-doc
{
  "title": "My excluded document"
}

PUT _query_rules/my-ruleset
{
  "rules": [
    {
      "rule_id": "my-pinned-rule",
      "type": "pinned",
      "criteria": [
        {
          "type": "exact",
          "metadata": "match",
          "values": [
            "pinned"
          ]
        }
      ],
      "actions": {
        "ids": [
          "my-pinned-doc"
        ]
      }
    },
    {
      "rule_id": "my-exclude-rule",
      "type": "exclude",
      "criteria": [
        {
          "type": "exact",
          "metadata": "match",
          "values": [
            "exclude"
          ]
        }
      ],
      "actions": {
        "ids": [
          "my-excluded-doc"
        ]
      }
    }
  ]
}

```

When query rules launched, we only supported the `pinned` rule. This rule guarantees that specified document(s) appear at the top of search results, regardless of whether they would have been returned in the original query. Therefore, a workaround to validate that rules are applied could be to issue a [match\_none](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-match-all-query.html#query-dsl-match-none-query) query as the `organic` part of the rule query, ensuring that any returned documents were pinned hits due to rule matches.

For the above example, that might look like:

```auto
POST my-index/_search
{
  "query": {
    "rule": {
      "organic": {
        "match_none": {}
      },
      "ruleset_ids": [
        "my-ruleset"
      ],
      "match_criteria": {
        "match": "pinned"
      }
    }
  }
}

```

We have since added `exclude` rules, which identify documents that should never be returned in a result set.

Similarly, for `exclude` rules, you could run a rule query against an [ids](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-ids-query.html) query or maybe a [match\_all](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-match-all-query.html) query for a very small dataset:

```auto
POST my-index/_search
{
  "query": {
    "rule": {
      "organic": {
        "ids": {
          "values": [
            "my-excluded-doc"
          ]
        }
      },
      "ruleset_ids": [
        "my-ruleset"
      ],
      "match_criteria": {
        "match": "exclude"
      }
    }
  }
}

```

This isn't the best solution, so with Elasticsearch version 8.16 we introduced a new [query rule tester API call](https://www.elastic.co/guide/en/elasticsearch/reference/master/test-query-ruleset.html), that allows you to determine which rules would have matched specific criteria, and the order that they would be applied. Here's an example of how to call it:

```auto
POST _query_rules/my-ruleset/_test
{
  "match_criteria": {
    "match": "exclude"
  }
}

```

This call will return the following response:

```auto
{
  "total_matched_rules": 1,
  "matched_rules": [
    {
      "ruleset_id": "my-ruleset",
      "rule_id": "my-exclude-rule"
    }
  ]
}

```

This will also work in the future if new rules are added that don't select or exclude documents from the search results.

Happy search result curation!