[Query Rules] Add some usability clarifications to docs (#102990) (#1…

…03090) * [Query Rules] Add some usability clarifications to docs * Fix typo
elastic · Dec 6, 2023 · 718849e · 718849e
1 parent cf3ea8a
commit 718849e
Show file tree

Hide file tree

Showing 3 changed files with 12 additions and 0 deletions.
diff --git a/docs/reference/query-dsl/rule-query.asciidoc b/docs/reference/query-dsl/rule-query.asciidoc
@@ -10,6 +10,7 @@ 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]
 ====

diff --git a/docs/reference/query-rules/apis/put-query-ruleset.asciidoc b/docs/reference/query-rules/apis/put-query-ruleset.asciidoc
@@ -29,6 +29,9 @@ Requires the `manage_search_query_rules` privilege.
 `rules`::
 (Required, array of objects) The specific rules included in this query ruleset.
 
+There is a limit of 100 rules per ruleset.
+This can be increased up to 1000 using the `xpack.applications.rules.max_rules_per_ruleset` cluster setting.
+
 Each rule must have the following information:
 
 - `rule_id` (Required, string) A unique identifier for this rule.

diff --git a/docs/reference/search/search-your-data/search-using-query-rules.asciidoc b/docs/reference/search/search-your-data/search-using-query-rules.asciidoc
@@ -174,6 +174,9 @@ PUT /_query_rules/my-ruleset
 
 The API response returns a results of `created` or `updated` depending on whether this was a new or edited ruleset.
 
+NOTE: There is a limit of 100 rules per ruleset.
+This can be increased up to 1000 using the `xpack.applications.rules.max_rules_per_ruleset` cluster setting.
+
 [source,console-result]
 ----
 {
@@ -217,3 +220,8 @@ GET /my-index-000001/_search
 
 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:
+
+- Where the matching rule appears in the ruleset
+- If multiple documents are specified in a single rule, in the order they are specified