[EXPERIMENTAL] Display ranking details at search #460

README.md

@@ -207,6 +207,54 @@ JSON output:
 }
 ```
 
+#### Display ranking details at search
+
+JSON output:
+
+```json
+{
+  "hits": [
+    {
+      "id": 15359,
+      "title": "Wonder Woman",
+      "_rankingScoreDetails": {
+        "words": {
+          "order": 0,
+          "matchingWords": 2,
+          "maxMatchingWords": 2,
+          "score": 1.0
+        },
+        "typo": {
+          "order": 1,
+          "typoCount": 0,
+          "maxTypoCount": 2,
+          "score": 1.0
+        },
+        "proximity": {
+          "order": 2,
+          "score": 1.0
+        },
+        "attribute": {
+          "order": 3,
+          "attributeRankingOrderScore": 0.8181818181818182,
+          "queryWordDistanceScore": 1.0,
+          "score": 0.8181818181818182
+        },
+        "exactness": {
+          "order": 4,
+          "matchType": "exactMatch",
+          "score": 1.0
+        }
+      }
+    }
+  ]
+}
+```
+
+You can enable it by querying PATCH /experimental-features with { "scoreDetails": true }
+
+This feature is only available with Meilisearch v1.3 and newer (optional).
+
 ## 🤖 Compatibility with Meilisearch
 
 This package guarantees compatibility with [version v1.x of Meilisearch](https://github.com/meilisearch/meilisearch/releases/latest), but some features may not be present. Please check the [issues](https://github.com/meilisearch/meilisearch-ruby/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22+label%3Aenhancement) for more info.

spec/meilisearch/index/search/show_ranking_score_details.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+RSpec.describe 'MeiliSearch::Index - Search with ranking score details' do
+  include_context 'search books with genre'
+
+  it 'experimental feature scoreDetails is not enabled so an error is raised' do
+    enable_score_details(false)
+
+    expect do
+      index.search('hobbit', { show_ranking_score_details: true })
+    end.to raise_error(MeiliSearch::ApiError)
+  end
+
+  it 'shows the ranking score details when showRankingScoreDetails is true' do
+    enable_score_details(true)
+
+    response = index.search('hobbit', { show_ranking_score_details: true })
+    expect(response['hits'][0]).to have_key('_rankingScoreDetails')
+  end
+
+  it 'hides the ranking score details when showRankingScoreDetails is false' do
+    enable_score_details(false)
+
+    response = index.search('hobbit', { show_ranking_score_details: false })
+    expect(response['hits'][0]).not_to have_key('_rankingScoreDetails')
+  end
+
+  it 'hides the ranking score details when showRankingScoreDetails is not set' do
+    enable_score_details(false)
+
+    response = index.search('hobbit')
+    expect(response['hits'][0]).not_to have_key('_rankingScoreDetails')
+  end
+end

spec/support/experimental_feature_helpers.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+
+module ExperimentalFeatureHelpers
+  def enable_score_details(toggle)
+    uri = URI("http://#{ENV.fetch('MEILISEARCH_URL', 'localhost')}")
+    uri.path = '/experimental-features'
+    uri.port = ENV.fetch('MEILISEARCH_PORT', '7700')
+
+    req = Net::HTTP::Patch.new(uri)
+    req.body = { scoreDetails: toggle }.to_json
+    req.content_type = 'application/json'
+    req['Authorization'] = "Bearer #{MASTER_KEY}"
+
+    Net::HTTP.start(uri.hostname, uri.port) { |http| http.request(req) }
+  end
+end