elasticsearch-explain-response 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c2299eb0a20900ac58c72b1bd5dd60bb2b0c3861
+  data.tar.gz: 0f969d270256226f68544794baa05dbce0c2c805
+SHA512:
+  metadata.gz: b0ee27611287865e4013b8d2ee43b2056325377aa2af26f1b2884a84522af89ba9b6a8bfd04289109d1155216fc22bf008f4869cd33f503cc3193b9af1c552c2
+  data.tar.gz: 6852990a83ecf7235c985c767a4d36f83bde12915b1de05a21827a5a73b73c74965950575300228c9d6df26783ccfe0611519d7bb068b004c590704d9d0b8f03

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 2.2.1

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in elasticsearch-explain-viewer.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Tomoya Hirano
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,56 @@
+# Elasticsearch-explain-response
+
+Parse Elasticsearch Explain Response and summarize it in a simple way.
+This gem is intended for developers working with Elasticsearch to debug search scores
+in a easier way.
+The current feature is very simple, but any sugguestions or feature requests are welcomed.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'elasticsearch-explain-response'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install elasticsearch-explain-response
+
+## Usage
+
+### Summarize the explanation in one line
+
+    ```
+    require 'elasticsearch'
+    client = Elasticsearch::Client.new
+    result = client.explain index: "megacorp", type: "employee", id: "1", q: "last_name:Smith"
+    puts Elasticsearch::API::Response::ExplainResponse.new(result["explanation"]).render_in_line
+    #=>
+    1.0 = (1.0(termFreq=1.0)) x 1.0(idf(2/3)) x 1.0(fieldNorm)
+    ```
+
+### Summarize the explanation in lines
+
+    ```
+    require 'elasticsearch'
+    client = Elasticsearch::Client.new
+    result = client.explain index: "megacorp", type: "employee", id: "1", q: "last_name:Smith"
+    puts Elasticsearch::API::Response::ExplainResponse.new(result["explanation"]).render
+    #=>
+    1.0 = 1.0(fieldWeight)
+      1.0 = 1.0(tf(1.0)) x 1.0(idf(2/3)) x 1.0(fieldNorm)
+        1.0 = 1.0(termFreq=1.0)
+    ```
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/elasticsearch-explain-response/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,7 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+

data/elasticsearch-explain-response.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+Gem::Specification.new do |spec|
+  spec.name          = "elasticsearch-explain-response"
+  spec.version       = "0.0.1"
+  spec.authors       = ["Tomoya Hirano"]
+  spec.email         = ["hiranotomoya@gmail.com"]
+  spec.summary       = %q{Parser for Elasticserach Explain response}
+  spec.description   = %q{Parser for Elasticserach Explain response}
+  spec.homepage      = "http://github.com/tomoya55/elasticsearch-explain-response"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.7"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "elasticsearch", "~> 1.0.0"
+  spec.add_development_dependency "ansi", "~> 1.5.0"
+end

data/lib/elasticsearch-explain-response.rb

@@ -0,0 +1 @@
+require "elasticsearch/api/response/explain_response"

data/lib/elasticsearch/api/response/color_helper.rb

@@ -0,0 +1,34 @@
+module Elasticsearch
+  module API
+    module Response
+      module ColorHelper
+        def colorized?
+          unless @ansi_loaded
+            @colorized = load_ansi
+          else
+            !!@colorized
+          end
+        end
+
+        def diable_colorization
+          @ansi_loaded = true
+          @colorized = false
+        end
+
+        def load_ansi
+          require "ansi/core"
+        rescue LoadError
+          false
+        end
+
+        def ansi(str, *codes)
+          if colorized?
+            str.to_s.ansi(*codes)
+          else
+            str.to_s
+          end
+        end
+      end
+    end
+  end
+end

data/lib/elasticsearch/api/response/explain_response.rb

@@ -0,0 +1,179 @@
+require "elasticsearch/api/response/color_helper"
+
+module Elasticsearch
+  module API
+    module Response
+      # Parse Elasticsearch Explain API response json and display them in a neat way
+      #
+      # @example
+      #    require 'elasticsearch'
+      #    client = Elasticsearch::Client.new
+      #    result = client.explain index: "megacorp", type: "employee", id: "1", q: "last_name:Smith"
+      #    Elasticsearch::API::Response::ExplainResponse.new(result["explanation"]).render_in_line
+      #      #=> "1.0 = (1.0(termFreq=1.0)) x 1.0(idf(2/3)) x 1.0(fieldNorm)"
+      class ExplainResponse
+        include ColorHelper
+
+        class << self
+          # Show scoring as a simple math formula
+          # @example
+          #    "1.0 = (1.0(termFreq=1.0)) x 1.0(idf(2/3)) x 1.0(fieldNorm)"
+          def render_in_line(result, max: nil)
+            new(result["explanation"], max: max).render_in_line
+          end
+
+          # Show scoring with indents
+          # @example
+          #   60.62 = 1.12 x 54.3 x 1.0(queryBoost)
+          #     1.12 = 3.35 x 0.33(coord(4/12))
+          #       3.35 = 0.2 + 0.93 + 1.29 + 0.93
+          #     54.3 = 54.3 min 3.4028234999999995e+38(maxBoost)
+          #       54.3 = 2.0 x 10.0 x 3.0 x 0.91
+          def render(result, max: nil)
+            parser = new(result["explanation"], max: max)
+            parser.parse
+            parser.render
+          end
+        end
+
+        attr_reader :explain
+
+        def initialize(explain, max: nil)
+          @explain = explain
+          @indent = 0
+          @max = max || 3
+        end
+
+        def render
+          @buffer = []
+          parse_explain(explain, indent: @indent, max: @max)
+          @buffer.map do |buf|
+            render_result(buf[:score], render_details(buf[:details], indent: @max + 1), indent: buf[:indent])
+          end
+        end
+
+        def render_in_line
+          score = explain["value"]
+          details = parse_for_oneline(explain)
+          render_result(score, render_details(details, indent: 0))
+        end
+
+        private
+
+        def get_score_type(description)
+          case
+          when description.include?("product of")
+            "x"
+          when description.include?("[multiply]")
+            "x"
+          when description.include?("sum of")
+            "+"
+          when description.include?("Math.min of")
+            "min"
+          else
+            " "
+          end
+        end
+
+        def extract_description(description)
+          case description
+          when /\Aweight\((\w+)\:(\w+)\s+in\s+\d+\)\s+\[\w+\]\,\s+result\s+of\:\z/
+            [field($1), value($2)].join(':')
+          when /\Aidf\(docFreq\=(\d+)\,\s+maxDocs\=(\d+)\)\z/
+            "idf(#{$1}/#{$2})"
+          when /\Atf\(freq\=([\d.]+)\)\,\swith\sfreq\sof\:\z/
+            "tf(#{$1})"
+          when /\Ascore\(doc\=\d+\,freq=[\d\.]+\)\,\sproduct\sof\:\z/
+            "score"
+          when /\Amatch\sfilter\:\s(?:cache\()?(?:\w+\()?([\w\*]+)\:([\w\*]+)\)*\z/
+            "match(#{field($1)}:#{value($2)})"
+          when /\AFunction\sfor\sfield\s([\w\_]+)\:\z/
+            "func(#{field($1)})"
+          when /\A(queryWeight|fieldWeight|fieldNorm)/
+            $1
+          when /\Afunction\sscore/
+            nil
+          when "static boost factor"
+            "boost"
+          when "Math.min of", "sum of:", "product of:"
+            nil
+          else
+            description
+          end
+        end
+
+        def field(str)
+          ansi(str, :blue ,:bright)
+        end
+
+        def value(str)
+          ansi(str, :green)
+        end
+
+        def render_details(details, indent:)
+          details[:details].map do |de|
+            case de
+            when Hash
+              if indent < @max
+                detail = render_details(de, indent: indent.succ)
+                wrap_paren(detail)
+              else
+                de[:description]
+              end
+            else
+              de
+            end
+          end.join(" #{details[:symbol]} ")
+        end
+
+        def parse_for_oneline(explain)
+          symbol = get_score_type(explain["description"])
+          description = parse_description(explain)
+          details = explain["details"].map do |de|
+            if de["details"]
+              parse_for_oneline(de)
+            else
+              parse_description(de)
+            end
+          end
+          {details: details, symbol: symbol, description: description}
+        end
+
+        def parse_description(detail)
+          text = render_score(detail["value"])
+          description = extract_description(detail["description"])
+          text += "(#{description})" if description
+          text
+        end
+
+        def parse_explain(explain, indent:, max: )
+          return if indent > max
+          score = explain["value"]
+          symbol = get_score_type(explain["description"])
+          details = explain["details"].map(&method(:parse_description))
+          @buffer << {score: score, details: {details: details, symbol: symbol}, indent: indent}
+
+          explain["details"].each do |de|
+            parse_explain(de, indent: indent.succ, max: max) if de["details"]
+          end
+        end
+
+        def render_score(score)
+          ansi(score.round(2).to_s, :magenta, :bright)
+        end
+
+        def render_result(score, details, indent: 0)
+          " " * indent * 2 + [render_score(score), "=", details].flatten.join(" ")
+        end
+
+        def wrap_paren(string)
+          if string.start_with?("(") && string.end_with?(")")
+            string
+          else
+            "(" + string + ")"
+          end
+        end
+      end
+    end
+  end
+end

data/spec/elasticsearch/api/response/explain_response_spec.rb

@@ -0,0 +1,48 @@
+require 'spec_helper'
+
+describe Elasticsearch::API::Response::ExplainResponse do
+  let(:fake_response) do
+    fixture_load(:response1)
+  end
+
+  describe "#render_in_line" do
+    let(:response) do
+      described_class.new(fake_response["explanation"])
+    end
+
+    subject do
+      response.render_in_line
+    end
+
+    before do
+      response.diable_colorization
+    end
+
+    it "returns summary of explain in line" do
+      expect(subject).to eq("0.05 = (0.43(queryWeight) x 0.25(fieldWeight)) x 0.5(coord(1/2))")
+    end
+  end
+
+  describe "#render" do
+    let(:response) do
+      described_class.new(fake_response["explanation"])
+    end
+
+    subject do
+      response.render
+    end
+
+    before do
+      response.diable_colorization
+    end
+
+    it "returns summary of explain in lines" do
+      expect(subject).to eq [
+        "0.05 = 0.11 x 0.5(coord(1/2))",
+        "  0.11 = 0.11(_all:smith)",
+        "    0.11 = 0.11(score)",
+        "      0.11 = 0.43(queryWeight) x 0.25(fieldWeight)"
+      ]
+    end
+  end
+end

data/spec/fixtures/response1.yml

@@ -0,0 +1,39 @@
+---
+_index: "megacorp"
+_type: "employee"
+_id: "1"
+matched: true
+explanation:
+  value: 0.053770658
+  description: "product of:"
+  details:
+  - value: 0.107541315
+    description: "sum of:"
+    details:
+    - value: 0.107541315
+      description: "weight(_all:smith in 0) [PerFieldSimilarity], result of:"
+      details:
+      - value: 0.107541315
+        description: "score(doc=0,freq=1.0), product of:"
+        details:
+        - value: 0.43016526
+          description: "queryWeight, product of:"
+          details:
+          - value: 1.0
+            description: "idf(docFreq=2, maxDocs=3)"
+          - value: 0.43016526
+            description: "queryNorm"
+        - value: 0.25
+          description: "fieldWeight in 0, product of:"
+          details:
+          - value: 1.0
+            description: "tf(freq=1.0), with freq of:"
+            details:
+            - value: 1.0
+              description: "termFreq=1.0"
+          - value: 1.0
+            description: "idf(docFreq=2, maxDocs=3)"
+          - value: 0.25
+            description: "fieldNorm(doc=0)"
+  - value: 0.5
+    description: "coord(1/2)"

data/spec/spec_helper.rb

@@ -0,0 +1,8 @@
+$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
+require "elasticsearch-explain-response"
+
+Dir[ File.expand_path('../support/**/*.rb', __FILE__) ].each { |f| require f }
+
+RSpec.configure do |config|
+  config.include FixtureHelper
+end

data/spec/support/fixture_helper.rb

@@ -0,0 +1,11 @@
+require "yaml"
+
+module FixtureHelper
+  def fixture_load(name)
+    YAML.load_file(fixture_file_path(name))
+  end
+
+  def fixture_file_path(name)
+    File.expand_path("../../fixtures/#{name}.yml", __FILE__)
+  end
+end

metadata

@@ -0,0 +1,132 @@
+--- !ruby/object:Gem::Specification
+name: elasticsearch-explain-response
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Tomoya Hirano
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-04-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: elasticsearch
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+- !ruby/object:Gem::Dependency
+  name: ansi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.5.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.5.0
+description: Parser for Elasticserach Explain response
+email:
+- hiranotomoya@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- elasticsearch-explain-response.gemspec
+- lib/elasticsearch-explain-response.rb
+- lib/elasticsearch/api/response/color_helper.rb
+- lib/elasticsearch/api/response/explain_response.rb
+- spec/elasticsearch/api/response/explain_response_spec.rb
+- spec/fixtures/response1.yml
+- spec/spec_helper.rb
+- spec/support/fixture_helper.rb
+homepage: http://github.com/tomoya55/elasticsearch-explain-response
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5
+signing_key: 
+specification_version: 4
+summary: Parser for Elasticserach Explain response
+test_files:
+- spec/elasticsearch/api/response/explain_response_spec.rb
+- spec/fixtures/response1.yml
+- spec/spec_helper.rb
+- spec/support/fixture_helper.rb