Skip to content

Commit

Permalink
Add a query rules tester API call (elastic#114168)
Browse files Browse the repository at this point in the history
* Add a query rules tester API call

* Update docs/changelog/114168.yaml

* Wrap client call in async with origin

* Remove unused param

* PR feedback

* Remove redundant test

* CI workaround - add ent-search as ml dependency so it can find node features
  • Loading branch information
kderusso authored and davidkyle committed Oct 14, 2024
1 parent 8b1a190 commit 7661875
Show file tree
Hide file tree
Showing 19 changed files with 951 additions and 8 deletions.
5 changes: 5 additions & 0 deletions docs/changelog/114168.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
pr: 114168
summary: Add a query rules tester API call
area: Relevance
type: enhancement
issues: []
2 changes: 2 additions & 0 deletions docs/reference/query-rules/apis/index.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ Use the following APIs to manage query rulesets:
* <<put-query-rule>>
* <<get-query-rule>>
* <<delete-query-rule>>
* preview:[] <<test-query-ruleset>>

include::put-query-ruleset.asciidoc[]
include::get-query-ruleset.asciidoc[]
Expand All @@ -31,4 +32,5 @@ include::delete-query-ruleset.asciidoc[]
include::put-query-rule.asciidoc[]
include::get-query-rule.asciidoc[]
include::delete-query-rule.asciidoc[]
include::test-query-ruleset.asciidoc[]

133 changes: 133 additions & 0 deletions docs/reference/query-rules/apis/test-query-ruleset.asciidoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,133 @@
[role="xpack"]
[[test-query-ruleset]]
=== Test query ruleset

++++
<titleabbrev>Tests query ruleset</titleabbrev>
++++

Evaluates match criteria against a query ruleset to identify the rules that would match that criteria.

preview::[]

[[test-query-ruleset-request]]
==== {api-request-title}

`POST _query_rules/<ruleset_id>/_test`

[[test-query-ruleset-prereq]]
==== {api-prereq-title}

Requires the `manage_search_query_rules` privilege.

[[test-query-ruleset-path-params]]
==== {api-path-parms-title}

`<ruleset_id>`::
(Required, string)

[[test-query-rule-request-body]]
==== {api-request-body-title}

`match_criteria`::
(Required, object) Defines the match criteria to apply to rules in the given query ruleset.
Match criteria should match the keys defined in the `criteria.metadata` field of the rule.

[[test-query-ruleset-response-codes]]
==== {api-response-codes-title}

`400`::
The `ruleset_id` or `match_criteria` were not provided.

`404` (Missing resources)::
No query ruleset matching `ruleset_id` could be found.

[[test-query-ruleset-example]]
==== {api-examples-title}

To test a ruleset, provide the match criteria that you want to test against:

////
[source,console]
--------------------------------------------------
PUT _query_rules/my-ruleset
{
"rules": [
{
"rule_id": "my-rule1",
"type": "pinned",
"criteria": [
{
"type": "contains",
"metadata": "query_string",
"values": [ "pugs", "puggles" ]
}
],
"actions": {
"ids": [
"id1",
"id2"
]
}
},
{
"rule_id": "my-rule2",
"type": "pinned",
"criteria": [
{
"type": "fuzzy",
"metadata": "query_string",
"values": [ "rescue dogs" ]
}
],
"actions": {
"docs": [
{
"_index": "index1",
"_id": "id3"
},
{
"_index": "index2",
"_id": "id4"
}
]
}
}
]
}
--------------------------------------------------
// TESTSETUP
[source,console]
--------------------------------------------------
DELETE _query_rules/my-ruleset
--------------------------------------------------
// TEARDOWN
////

[source,console]
----
POST _query_rules/my-ruleset/_test
{
"match_criteria": {
"query_string": "puggles"
}
}
----

A sample response:

[source,console-result]
----
{
"total_matched_rules": 1,
"matched_rules": [
{
"ruleset_id": "my-ruleset",
"rule_id": "my-rule1"
}
]
}
----
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
{
"query_rules.test": {
"documentation": {
"url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/test-query-ruleset.html",
"description": "Tests a query ruleset to identify the rules that would match input criteria"
},
"stability": "experimental",
"visibility": "public",
"headers": {
"accept": [
"application/json"
],
"content_type": [
"application/json"
]
},
"url": {
"paths": [
{
"path": "/_query_rules/{ruleset_id}/_test",
"methods": [
"POST"
],
"parts": {
"ruleset_id": {
"type": "string",
"description": "The unique identifier of the ruleset to test."
}
}
}
]
},
"body": {
"description": "The match criteria to test against the ruleset",
"required": true
}
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -242,6 +242,7 @@ static TransportVersion def(int id) {
public static final TransportVersion ESQL_CACHED_STRING_SERIALIZATION = def(8_766_00_0);
public static final TransportVersion CHUNK_SENTENCE_OVERLAP_SETTING_ADDED = def(8_767_00_0);
public static final TransportVersion OPT_IN_ESQL_CCS_EXECUTION_INFO = def(8_768_00_0);
public static final TransportVersion QUERY_RULE_TEST_API = def(8_769_00_0);

/*
* STOP! READ THIS FIRST! No, really,
Expand Down
Loading

0 comments on commit 7661875

Please sign in to comment.