Query rules retriever

The rule retriever enables fine-grained control over search results by applying contextual query rules to pin or exclude documents for specific queries. This retriever has similar functionality to the rule query, but works out of the box with other retrievers.

To use the rule retriever you must first create one or more query rulesets using the query rules management APIs.

retriever

(Required, retriever)

The child retriever that returns the results to apply query rules on top of. This can be a standalone retriever such as the standard or knn retriever, or it can be a compound retriever.

ruleset_ids

(Required, array)

An array of one or more unique query ruleset IDs with query-based rules to match and apply as applicable. Rulesets and their associated rules are evaluated in the order in which they are specified in the query and ruleset. The maximum number of rulesets to specify is 10.

match_criteria

(Required, object)

Defines the match criteria to apply to rules in the given query ruleset(s). Match criteria should match the keys defined in the criteria.metadata field of the rule.

rank_window_size

(Optional, int)

The number of top documents to return from the rule retriever. Defaults to 10.

This example shows the rule retriever executed without any additional retrievers. It runs the query defined by the retriever and applies the rules from my-ruleset on top of the returned results.

GET movies/_search
{
  "retriever": {
    "rule": {
      "match_criteria": {
        "query_string": "harry potter"
      },
      "ruleset_ids": [
        "my-ruleset"
      ],
      "retriever": {
        "standard": {
          "query": {
            "query_string": {
              "query": "harry potter"
            }
          }
        }
      }
    }
  }
}

This example shows how to combine the rule retriever with other rerank retrievers such as rrf or text_similarity_reranker.

GET movies/_search
{
  "retriever": {
    "rule": {
      "match_criteria": {
        "query_string": "harry potter"
      },
      "ruleset_ids": [
        "my-ruleset"
      ],
      "retriever": {
        "rrf": {
          "retrievers": [
            {
              "standard": {
                "query": {
                  "query_string": {
                    "query": "sorcerer's stone"
                  }
                }
              }
            },
            {
              "standard": {
                "query": {
                  "query_string": {
                    "query": "chamber of secrets"
                  }
                }
              }
            }
          ]
        }
      }
    }
  }
}

1. The rule retriever is the outermost retriever, applying rules to the search results that were previously reranked using the rrf retriever.
2. The rrf retriever returns results from all of its sub-retrievers, and the output of the rrf retriever is used as input to the rule retriever.