Merge pull request #4 from friendsofcat/add-explain-feature

Add `explain` feature to better understand scores
friendsofcat · May 19, 2023 · a00ea7b · a00ea7b
2 parents b350570 + 57d340c
commit a00ea7b
Show file tree

Hide file tree

Showing 7 changed files with 89 additions and 48 deletions.
diff --git a/README.md b/README.md
@@ -146,6 +146,7 @@ The builder supports various search parameters and provides a number of useful h
 * [trackScores](docs/available-methods.md#trackscores)
 * [trackTotalHits](docs/available-methods.md#tracktotalhits)
 * [when](docs/available-methods.md#when)
+* [explain](docs/available-methods.md#explain)
 
 ### Search Results
 
@@ -168,7 +169,7 @@ You can get more familiar with the `$searchResult` object and learn how to pagin
 
 ### Custom Routing
 
-If you want to use a [custom shard routing](https://opensearch.org/docs/1.3/opensearch/mappings/)
+If you want to use a [custom shard routing](https://opensearch.org/docs/opensearch/mappings/)
 for your model, override the `searchableRouting` method:
 
 ```php

diff --git a/composer.json b/composer.json
@@ -31,7 +31,7 @@
     },
     "require": {
         "php": "^7.4 || ^8.0",
-        "friendsofcat/opensearch-scout-driver": "^2.0"
+        "friendsofcat/opensearch-scout-driver": "^2.1"
     },
     "require-dev": {
         "phpunit/phpunit": "^9.5",

diff --git a/docs/available-methods.md b/docs/available-methods.md
@@ -22,10 +22,11 @@
 * [trackTotalHits](#tracktotalhits)
 * [unless](#unless)
 * [when](#when)
+* [explain](#explain)
 
 ### aggregate
 
-This method can be used to [aggregate data](https://opensearch.org/docs/1.3/opensearch/aggregations/) 
+This method can be used to [aggregate data](https://opensearch.org/docs/opensearch/aggregations/) 
 based on a search query;
 
 ```php
@@ -81,7 +82,7 @@ $searchResult = Book::searchQuery($query)
 
 ### from
 
-`from` defines [the starting document offset](https://opensearch.org/docs/1.3/opensearch/rest-api/search/):
+`from` defines [the starting document offset](https://opensearch.org/docs/opensearch/rest-api/search/):
 
 ```php
 $searchResult = Book::searchQuery($query)
@@ -91,7 +92,7 @@ $searchResult = Book::searchQuery($query)
 
 ### highlight
 
-This method allows you to get [highlighted snippets](https://opensearch.org/docs/1.3/opensearch/supported-field-types/text/)
+This method allows you to get [highlighted snippets](https://opensearch.org/docs/opensearch/supported-field-types/text/)
 from one or more fields in your search results:
 
 ```php
@@ -135,7 +136,7 @@ $raw = $highlight->raw();
 
 ### join
 
-This method enables [multi indices](https://opensearch.org/docs/1.3/opensearch/rest-api/multi-search/)
+This method enables [multi indices](https://opensearch.org/docs/opensearch/rest-api/multi-search/)
 search:
 
 ```php
@@ -157,7 +158,7 @@ Note that the result collection of models includes both types:
 $models = $searchResult->models();
 ```
 
-When searching in multiple indices, you can [boost results from a specific index](https://opensearch.org/docs/1.3/opensearch/rest-api/multi-search/)
+When searching in multiple indices, you can [boost results from a specific index](https://opensearch.org/docs/opensearch/rest-api/multi-search/)
 by providing the second argument in `join` method:
 
 ```php
@@ -188,7 +189,7 @@ $searchResult = Book::searchQuery($query)
 
 ### minScore
 
-This method allows you to [set minimum score for matching documents](https://opensearch.org/docs/1.3/opensearch/rest-api/search/):
+This method allows you to [set minimum score for matching documents](https://opensearch.org/docs/opensearch/rest-api/search/):
 
 ```php
 $searchResult = Book::searchQuery($query)
@@ -220,7 +221,7 @@ $searchResult = Book::searchQuery($query)
 
 ### preference
 
-`preference` defines [nodes and shards used for the search](https://opensearch.org/docs/1.3/opensearch/rest-api/search/):
+`preference` defines [nodes and shards used for the search](https://opensearch.org/docs/opensearch/rest-api/search/):
 
 ```php
 $searchResult = Book::searchQuery($query)
@@ -313,7 +314,7 @@ $searchResult = Book::searchQuery($query)
 
 ### searchType
 
-`searchType` defines [how distributed term frequencies are calculated for relevance scoring](https://opensearch.org/docs/1.3/opensearch/rest-api/search/):
+`searchType` defines [how distributed term frequencies are calculated for relevance scoring](https://opensearch.org/docs/opensearch/rest-api/search/):
 
 ```php
 $searchResult = Book::searchQuery($query)
@@ -323,7 +324,7 @@ $searchResult = Book::searchQuery($query)
 
 ### size
 
-`size` method [limits the number of hits to return](https://opensearch.org/docs/1.3/opensearch/rest-api/search/):
+`size` method [limits the number of hits to return](https://opensearch.org/docs/opensearch/rest-api/search/):
 
 ```php
 $searchResult = Book::searchQuery($query)
@@ -486,3 +487,13 @@ $searchResult = Book::searchQuery($query)
      })
     ->execute();
 ```
+
+### explain
+
+This method can be used to [retrieve an explanation of how the relevance score (_score) is calculated for every result](https://opensearch.org/docs/api-reference/explain/):
+
+```php
+$searchResult = Book::searchQuery($query)
+    ->explain()
+    ->execute();
+```
diff --git a/docs/compound-queries.md b/docs/compound-queries.md
@@ -4,7 +4,7 @@
 
 ## Boolean
 
-You can use `OpenSearch\ScoutDriverPlus\Support\Query::bool()` to build a [boolean query](https://opensearch.org/docs/1.3/opensearch/query-dsl/bool/):
+You can use `OpenSearch\ScoutDriverPlus\Support\Query::bool()` to build a [boolean query](https://opensearch.org/docs/opensearch/query-dsl/bool/):
 
 ```php
 $query = Query::bool()->must(
@@ -28,7 +28,7 @@ Available methods:
 
 ### <a name="bool-filter"></a> filter
 
-The query defined with `filter` [must appear in the matching documents](https://opensearch.org/docs/1.3/opensearch/query-dsl/bool/),
+The query defined with `filter` [must appear in the matching documents](https://opensearch.org/docs/opensearch/query-dsl/bool/),
 but won’t contribute to the score:
 
 ```php
@@ -63,7 +63,7 @@ $searchResult = Book::searchQuery($query)->execute();
 
 ### <a name="bool-minimum-should-match"></a> minimumShouldMatch
 
-You can use `minimumShouldMatch` to specify [the number of `should` queries](https://opensearch.org/docs/1.3/opensearch/query-dsl/bool/)
+You can use `minimumShouldMatch` to specify [the number of `should` queries](https://opensearch.org/docs/opensearch/query-dsl/bool/)
 the documents must match:
 
 ```php
@@ -77,7 +77,7 @@ $searchResult = Book::searchQuery($query)->execute();
 
 ### <a name="bool-must"></a> must
 
-The query defined with `must` [must appear in the matching documents](https://opensearch.org/docs/1.3/opensearch/query-dsl/bool/)
+The query defined with `must` [must appear in the matching documents](https://opensearch.org/docs/opensearch/query-dsl/bool/)
 and will contribute to the score:
 
 ```php
@@ -112,7 +112,7 @@ $searchResult = Book::searchQuery($query)->execute();
 
 ### <a name="bool-must-not"></a> mustNot
 
-The query defined with `mustNot` [must not appear in the matching documents](https://opensearch.org/docs/1.3/opensearch/query-dsl/bool/)
+The query defined with `mustNot` [must not appear in the matching documents](https://opensearch.org/docs/opensearch/query-dsl/bool/)
 and won’t contribute to the score:
 
 ```php
@@ -159,7 +159,7 @@ $searchResult = Book::searchQuery($query)->execute();
 
 ### <a name="bool-should"></a> should
 
-The query defined with `should` [should appear in the matching documents](https://opensearch.org/docs/1.3/opensearch/query-dsl/bool/):
+The query defined with `should` [should appear in the matching documents](https://opensearch.org/docs/opensearch/query-dsl/bool/):
 
 ```php
 // you can make a query using builder