Searching with query rules

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:

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 API and searched using the rule query.

When defining a rule, consider the following:

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

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

The actions to take when the rule matches a query:

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 pinned query for details.

You can add query rules using the Create or update 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:

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.

{
  "result": "created"
}

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.

Once you have defined one or more query rulesets, you can search these rulesets using the Rule query. Rulesets are evaluated in order, so rules in the first ruleset you specify will be applied before any subsequent rulesets.

An example query for the my-ruleset defined above is:

resp = client.search(
    index="my-index-000001",
    query={
        "rule": {
            "organic": {
                "query_string": {
                    "query": "puggles"
                }
            },
            "match_criteria": {
                "query_string": "puggles",
                "user_country": "us"
            },
            "ruleset_ids": [
                "my-ruleset"
            ]
        }
    },
)
print(resp)

const response = await client.search({
  index: "my-index-000001",
  query: {
    rule: {
      organic: {
        query_string: {
          query: "puggles",
        },
      },
      match_criteria: {
        query_string: "puggles",
        user_country: "us",
      },
      ruleset_ids: ["my-ruleset"],
    },
  },
});
console.log(response);

GET /my-index-000001/_search
{
  "query": {
    "rule": {
      "organic": {
        "query_string": {
          "query": "puggles"
        }
      },
      "match_criteria": {
        "query_string": "puggles",
        "user_country": "us"
      },
      "ruleset_ids": ["my-ruleset"]
    }
  }
}

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.

It’s possible to have multiple rules in a ruleset match a single rule query. In this case, the pinned documents are returned in the following order: