Skip to content

[Query Rules] clarify query rules API documentation #100732

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Oct 13, 2023
Merged

[Query Rules] clarify query rules API documentation #100732

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3b1fe5e
Update example in query rules docs
kderusso Oct 11, 2023
7ca3a37
Ensure GET docs are also consistent
kderusso Oct 11, 2023
4ff4d48
Update docs/reference/query-rules/apis/put-query-ruleset.asciidoc
kderusso Oct 12, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions docs/reference/query-rules/apis/get-query-ruleset.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,9 +52,9 @@ PUT _query_rules/my-ruleset
"type": "pinned",
"criteria": [
{
"type": "exact",
"type": "contains",
"metadata": "query_string",
"values": [ "marvel" ]
"values": [ "pugs", "puggles" ]
}
],
"actions": {
Expand All @@ -69,9 +69,9 @@ PUT _query_rules/my-ruleset
"type": "pinned",
"criteria": [
{
"type": "exact",
"type": "fuzzy",
"metadata": "query_string",
"values": [ "dc" ]
"values": [ "rescue dogs" ]
}
],
"actions": {
Expand Down Expand Up @@ -117,9 +117,9 @@ A sample response:
"type": "pinned",
"criteria": [
{
"type": "exact",
"type": "contains",
"metadata": "query_string",
"values": [ "marvel" ]
"values": [ "pugs", "puggles" ]
}
],
"actions": {
Expand All @@ -134,9 +134,9 @@ A sample response:
"type": "pinned",
"criteria": [
{
"type": "exact",
"type": "fuzzy",
"metadata": "query_string",
"values": [ "dc" ]
"values": [ "rescue dogs" ]
}
],
"actions": {
Expand Down
72 changes: 36 additions & 36 deletions docs/reference/query-rules/apis/put-query-ruleset.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,29 +22,27 @@ Requires the `manage_search_query_rules` privilege.

[role="child_attributes"]
[[put-query-ruleset-request-body]]
(Required, object)
Contains parameters for a query ruleset:
(Required, object) Contains parameters for a query ruleset:

==== {api-request-body-title}

`rules`::
(Required, array of objects)
The specific rules included in this query ruleset.
(Required, array of objects) The specific rules included in this query ruleset.

Each rule must have the following information:

- `rule_id` (Required, string)
A unique identifier for this rule.
- `type` (Required, string)
The type of rule. At this time only `pinned` query rule types are allowed.
- `criteria` (Required, array of objects)
The criteria that must be met for the rule to be applied. If multiple criteria are specified for a rule, all criteria must be met for the rule to be applied.
- `actions` (Required, object)
The actions to take when the rule is matched. The format of this action depends on the rule type.
- `rule_id` (Required, string) A unique identifier for this rule.
- `type` (Required, string) The type of rule.
At this time only `pinned` query rule types are allowed.
- `criteria` (Required, array of objects) The criteria that must be met for the rule to be applied.
If multiple criteria are specified for a rule, all criteria must be met for the rule to be applied.
- `actions` (Required, object) The actions to take when the rule is matched.
The format of this action depends on the rule type.

Criteria must have the following information:

- `type` (Required, string)
The type of criteria. The following criteria types are supported:
- `type` (Required, string) The type of criteria.
The following criteria types are supported:
+
--
- `exact`
Expand Down Expand Up @@ -77,30 +75,32 @@ Only applicable for numerical values.
- `always`
Matches all queries, regardless of input.
--
- `metadata` (Optional, string)
The metadata field to match against. Required for all criteria types except `global`.
- `values` (Optional, array of strings)
The values to match against the metadata field. Only one value must match for the criteria to be met. Required for all criteria types except `global`.
- `metadata` (Optional, string) The metadata field to match against.
This metadata will be used to match against `match_criteria` sent in the <<query-dsl-rule-query>>.
Required for all criteria types except `global`.
- `values` (Optional, array of strings) The values to match against the metadata field.
Only one value must match for the criteria to be met.
Required for all criteria types except `global`.

Actions depend on the rule type.
For `pinned` rules, actions follow the format specified by the <<query-dsl-pinned-query,Pinned Query>>.
The following actions are allowed:

- `ids` (Optional, array of strings)
The The unique <<mapping-id-field, document IDs>> of the documents to pin.
Only one of `ids` or `docs` may be specified, and at least one must be specified.
- `docs` (Optional, array of objects)
The documents to pin. Only one of `ids` or `docs` may be specified, and at least one must be specified.
You can specify the following attributes for each document:
- `ids` (Optional, array of strings) The unique <<mapping-id-field, document IDs>> of the documents to pin.
Only one of `ids` or `docs` may be specified, and at least one must be specified.
- `docs` (Optional, array of objects) The documents to pin.
Only one of `ids` or `docs` may be specified, and at least one must be specified.
You can specify the following attributes for each document:
+
--
- `_index` (Required, string)
The index of the document to pin.
- `_id` (Required, string)
The unique <<mapping-id-field, document ID>>.
- `_index` (Required, string) The index of the document to pin.
- `_id` (Required, string) The unique <<mapping-id-field, document ID>>.
--

IMPORTANT: Due to limitations within <<query-dsl-pinned-query,Pinned queries>>, you can only pin documents using `ids` or `docs`, but cannot use both in single rule. It is advised to use one or the other in query rulesets, to avoid errors. Additionally, pinned queries have a maximum limit of 100 pinned hits. If multiple matching rules pin more than 100 documents, only the first 100 documents are pinned in the order they are specified in the ruleset.
IMPORTANT: Due to limitations within <<query-dsl-pinned-query,Pinned queries>>, you can only pin documents using `ids` or `docs`, but cannot use both in single rule.
It is advised to use one or the other in query rulesets, to avoid errors.
Additionally, pinned queries have a maximum limit of 100 pinned hits.
If multiple matching rules pin more than 100 documents, only the first 100 documents are pinned in the order they are specified in the ruleset.

[[put-query-ruleset-example]]
==== {api-examples-title}
Expand All @@ -109,8 +109,8 @@ The following example creates a new query ruleset called `my-ruleset`.

Two rules are associated with `my-ruleset`:

- `my-rule1` will pin documents with IDs `id1` and `id2` when `user.query` exactly matches `marvel` _or_ `dc` **and** `user.country` exactly matches `us`.
- `my-rule2` will pin documents from different, specified indices with IDs `id3` and `id4` when the `query_string` fuzzily matches `comic`.
- `my-rule1` will pin documents with IDs `id1` and `id2` when `user_query` contains `pugs` _or_ `puggles` **and** `user_country` exactly matches `us`.
Copy link
Contributor

@leemthompo leemthompo Oct 12, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why the switch from dot notation here? (e.g. user.query -> user_query)

Copy link
Member Author

@kderusso kderusso Oct 12, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The feedback was that all of our examples should be consistent. So since we were using user_query everywhere else, it was easier to update this one document over the others.

- `my-rule2` will pin documents from different, specified indices with IDs `id3` and `id4` when the `query_string` fuzzily matches `rescue dogs`.

[source,console]
----
Expand All @@ -123,12 +123,12 @@ PUT _query_rules/my-ruleset
"criteria": [
{
"type": "contains",
"metadata": "user.query",
"values": [ "marvel", "dc" ]
"metadata": "user_query",
"values": [ "pugs", "puggles" ]
},
{
"type": "exact",
"metadata": "user.country",
"metadata": "user_country",
"values": [ "us" ]
}
],
Expand All @@ -145,8 +145,8 @@ PUT _query_rules/my-ruleset
"criteria": [
{
"type": "fuzzy",
"metadata": "query_string",
"values": [ "comic" ]
"metadata": "user_query",
"values": [ "rescue dogs" ]
}
],
"actions": {
Expand Down