stretchy 0.3.6 → 0.3.7

data/lib/stretchy/clauses/boost_match_clause.rb

@@ -2,10 +2,31 @@ require 'stretchy/clauses/boost_clause'
 
 module Stretchy
   module Clauses
+      # 
+      # Boost documents that match a free-text query. Most
+      # options will be passed into {#initialize}, but you 
+      # can also chain `.not` onto it. Calling `.where` or
+      # `.match` from here will apply filters (*not boosts*)
+      # and return to the base state
+      # 
+      # @author [atevans]
+      # 
     class BoostMatchClause < BoostClause
 
       delegate [:range, :geo] => :where
 
+      # 
+      # Adds a match query to the boost functions.
+      # 
+      # @overload initialize(base, opts_or_string)
+      #   @param base [Base] Base query to copy data from
+      #   @param opts_or_string [String] String to do a free-text match across the document
+      # 
+      # @overload initialize(base, opts_or_string)
+      #   @param base [Base] Base query to copy data from
+      #   @param options = {} [Hash] Fields and values to match via full-text search
+      # 
+      # @return [BoostMatchClause] Boost clause in match context, with queries applied
       def initialize(base, opts_or_string = {}, options = {})
         super(base)
         if opts_or_string.is_a?(Hash)
@@ -17,14 +38,52 @@ module Stretchy
         end
       end
 
+      # 
+      # Switches to inverse context, and applies filters as inverse
+      # options (ie, documents that *do not* match the query will
+      # be boosted)
+      # 
+      # @overload not(opts_or_string)
+      #   @param [String] String that must not match anywhere in the document
+      # 
+      # @overload not(opts_or_string)
+      #   @param opts_or_string [Hash] Fields and values that should not match in the document
+      # 
+      # @return [BoostMatchClause] Query with inverse matching boost function applied
       def not(opts_or_string = {}, options = {})
         self.class.new(self, opts_or_string, options.merge(inverse: !inverse?))
       end
 
+      # 
+      # Returns to the base context; filters passed here
+      # will be used to filter documents.
+      # 
+      # @example Returning to base context
+      #   query.boost.match('string').where(other_field: 64)
+      # 
+      # @example Staying in boost context
+      #   query.boost.match('string').boost.where(other_field: 99)
+      # 
+      # @see {WhereClause#initialize}
+      # 
+      # @return [WhereClause] Query with where clause applied
       def where(*args)
         WhereClause.new(self, *args)
       end
 
+      # 
+      # Returns to the base context. Queries passed here
+      # will be used to filter documents.
+      # 
+      # @example Returning to base context
+      #   query.boost.match(message: 'curse word').match('username')
+      # 
+      # @example Staying in boost context
+      #   query.boost.match(message: 'happy word').boost.match('love')
+      # 
+      # @see {MatchClause#initialize}
+      # 
+      # @return [MatchClause] Base context with match queries applied
       def match(*args)
         MatchClause.new(self, *args)
       end

data/lib/stretchy/clauses/boost_where_clause.rb

@@ -2,27 +2,95 @@ require 'stretchy/clauses/boost_clause'
 
 module Stretchy
   module Clauses
+      # 
+      # Boosts documents that match certain filters. Most filters will
+      # be passed into {#initialize}, but you can also use `.range` and 
+      # `.geo` .
+      # 
+      # @author [atevans]
+      # 
     class BoostWhereClause < BoostClause
 
+      # 
+      # Generates a boost that matches a set of filters.
+      # 
+      # @param base [Base] Query to copy data from.
+      # @param options = {} [Hash] Fields and values to filter on.
+      # 
+      # @see {WhereClause#initialize}
+      # 
+      # @return [BoostWhereClause] Query with filter boosts applied
       def initialize(base, options = {})
         super(base, options)
         where_function(:init, options)
         self
       end
 
+      # 
+      # Returns to the base context; filters passed here
+      # will be used to filter documents.
+      # 
+      # @example Returning to base context
+      #   query.boost.where(number_field: 33).where(other_field: 64)
+      # 
+      # @example Staying in boost context
+      #   query.boost.where(number_field: 33).boost.where(other_field: 99)
+      # 
+      # @see {WhereClause#initialize}
+      # 
+      # @return [WhereClause] Query with where clause applied
       def where(*args)
         WhereClause.new(self, *args)
       end
 
+      # 
+      # Returns to the base context. Queries passed here
+      # will be used to filter documents.
+      # 
+      # @example Returning to base context
+      #   query.boost.where(number_field: 89).match('username')
+      # 
+      # @example Staying in boost context
+      #   query.boost.where(number_field: 89).boost.match('love')
+      # 
+      # @see {MatchClause#initialize}
+      # 
+      # @return [MatchClause] Base context with match queries applied
       def match(*args)
         MatchClause.new(self, *args)
       end
 
+      # 
+      # Applies a range filter with a min or max
+      # as a boost.
+      # 
+      # @see {WhereClause#range}
+      # 
+      # @see {Filters::RangeFilter}
+      # 
+      # @see http://www.elastic.co/guide/en/elasticsearch/guide/master/_ranges.html Elastic Guides - Ranges
+      # 
+      # @return [Base] Query in base context with range boost applied
       def range(*args)
         where_function(:range, *args)
         Base.new(self)
       end
 
+      # 
+      # Boosts a document if it matches a geo filter.
+      # This is different than {BoostClause#near} -
+      # while `.near` applies a decay function that boosts
+      # based on how close a field is to a geo point,
+      # `.geo` applies a filter that either boosts or doesn't
+      # boost the document.
+      # 
+      # @see {WhereFunction#geo}
+      # 
+      # @see {Filters::GeoFilter}
+      # 
+      # @see http://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-geo-distance-filter.html Elastic Docs - Geo Distance Filter
+      # 
+      # @return [Base] Query in base context with geo filter boost applied
       def geo(*args)
         where_function(:geo, *args)
         Base.new(self)

data/lib/stretchy/clauses/match_clause.rb

@@ -2,12 +2,49 @@ require 'stretchy/clauses/base'
 
 module Stretchy
   module Clauses
+      # 
+      # A Match clause inherits the same state as any clause.
+      # There aren't any more specific methods to chain, as
+      # this clause only handles basic full-text searches.
+      # 
+      # @author [atevans]
+      # 
     class MatchClause < Base
 
+      # 
+      # Creates a temporary MatchClause outside the main
+      # query scope by using a new {Base}. Primarily
+      # used in {BoostClause} for boosting on full-text
+      # matches.
+      # 
+      # @param options = {} [Hash] Options to pass to the full-text match
+      # 
+      # @return [MatchClause] Temporary clause outside current state
       def self.tmp(options = {})
         self.new(Base.new, options)
       end
 
+      # 
+      # Creates a new state with a match query applied.
+      # 
+      # @overload initialize(base, opts_or_string)
+      #   @param [Base] Base clause to copy data from
+      #   @param [String] Performs a full-text query for this string on all fields in the document.
+      # 
+      # @overload initialize(base, opts_or_string)
+      #   @param [Base] Base clause to copy data from
+      #   @param [Hash] A hash of fields and values to perform full-text matches with
+      # 
+      # @example A basic full-text match
+      #   query.match("anywhere in document")
+      # 
+      # @example A full-text search on specific fields
+      #   query.match(
+      #     my_field: "match in my_field",
+      #     other_field: "match in other_field"
+      #   )
+      # 
+      # @see http://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-match-query.html Elastic Docs - Match Query
       def initialize(base, opts_or_str = {}, options = {})
         super(base)
         if opts_or_str.is_a?(Hash)
@@ -21,14 +58,73 @@ module Stretchy
         end
       end
 
+      # 
+      # Switches to inverted context. Matches applied here work the same way as
+      # {#initialize}, but returned documents must **not** match these filters.
+      # 
+      # @overload not(opts_or_str)
+      #   @param [String] A string that must not be matched anywhere in the document
+      # @overload not(opts_or_str)
+      #   @param [Hash] A hash of fields and strings that must not be matched in those fields
+      # 
+      # @return [MatchClause] inverted query state with match filters applied
+      # 
+      # @example Inverted full-text
+      #   query.match.not("hello")
+      # 
+      # @example Inverted full-text matching for specific fields
+      #   query.match.not(
+      #     my_field: "not_match_1",
+      #     other_field: "not_match_2"
+      #   )
       def not(opts_or_str = {}, options = {})
         self.class.new(self, opts_or_str, options.merge(inverse: true, should: should?))
       end
 
+      # 
+      # Switches to `should` context. Applies full-text matches
+      # that are not required, but boost the relevance score for
+      # matching documents.
+      # 
+      # Can be chained with {#not}
+      # 
+      # @overload not(opts_or_str)
+      #   @param [String] A string that should be matched anywhere in the document
+      # @overload not(opts_or_str)
+      #   @param [Hash] A hash of fields and strings that should be matched in those fields
+      # 
+      # @param opts_or_str = {} [type] [description]
+      # @param options = {} [type] [description]
+      # 
+      # @return [MatchClause] query state with should filters added
+      # 
+      # @example Should match with full-text
+      #   query.match.should("anywhere")
+      # 
+      # @example Should match specific fields
+      #   query.match.should(
+      #     field_one: "one",
+      #     field_two: "two"
+      #   )
+      # 
+      # @example Should not match
+      #   query.match.should.not(
+      #     field_one: "one",
+      #     field_two: "two"
+      #   )
+      # 
+      # @see http://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-bool-query.html Elastic Docs - Bool Query
       def should(opts_or_str = {}, options = {})
         self.class.new(self, opts_or_str, options.merge(should: true))
       end
 
+      # 
+      # Converts this match context to a set of boosts
+      # to use in a {Stretchy::Queries::FunctionScoreQuery}
+      # 
+      # @param weight = nil [Numeric] Weight of generated boost
+      # 
+      # @return [Stretchy::Boosts::FilterBoost] boost containing these match parameters
       def to_boost(weight = nil)
         weight ||= Stretchy::Boosts::FilterBoost::DEFAULT_WEIGHT
         Stretchy::Boosts::FilterBoost.new(
@@ -39,6 +135,10 @@ module Stretchy
         )
       end
 
+      # 
+      # Accessor for `@should`
+      # 
+      # @return [true, false] `@should`
       def should?
         !!@should
       end

data/lib/stretchy/clauses/where_clause.rb

@@ -2,12 +2,62 @@ require 'stretchy/clauses/base'
 
 module Stretchy
   module Clauses
+      # 
+      # A Where clause inherits the same state as any clause, 
+      # but has a few possible states to transition to. You
+      # can call {#range} and {#geo} to add their respective
+      # filters, or you can transition to the inverted state
+      # via {#not}, or the `should` state via {#should}
+      # 
+      # ### STATES:
+      # * **inverted:** any filters added in this state will be
+      #   inverted, ie the document must **NOT** match said
+      #   filters.
+      # * **should:** any filters added in this state will be
+      #   applied to a `should` block. Documents which do
+      #   not match these filters will be returned, but 
+      #   documents which do match will have a higher 
+      #   relevance score.
+      # 
+      # @author [atevans]
+      # 
     class WhereClause < Base
 
+      # 
+      # Creates a temporary context by initializing a new Base object.
+      # Used primarily in {BoostWhereClause}
+      # 
+      # @param options = {} [Hash] Options to filter on
+      # 
+      # @return [WhereClause] A clause outside the main query context
       def self.tmp(options = {})
         self.new(Base.new, options)
       end
 
+      # 
+      # Options passed to the initializer will be interpreted as filters
+      # to be added to the query. This is similar to ActiveRecord's `where`
+      # method.
+      # 
+      # @param base [Base] Used to intialize the new state from the previous clause
+      # @param options = {} [Hash] filters to be applied to the new state
+      # @option  options [true, false] :inverted (nil) Whether the new state is inverted
+      # @option  options [true, false] :should (nil) Whether the new state is should
+      # 
+      # @example Apply ActiveRecord-like filters
+      #   query.where(
+      #     string_field: "string",
+      #     must_not_exist: nil,
+      #     in_range: 27..33,
+      #     included_in: [47, 23, 86]
+      #   )
+      # 
+      # @see http://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-terms-filter.html Elastic Docs - Terms Filter
+      # 
+      # @see http://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-exists-filter.html Elastic Docs - Exists Filter
+      # 
+      # @see http://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-range-filter.html Elastic Docs - Range Filter
+      # 
       def initialize(base, options = {})
         super(base)
         @inverse = options.delete(:inverse)
@@ -15,15 +65,62 @@ module Stretchy
         add_params(options)
       end
 
+      # 
+      # Accessor for `@should`
+      # 
+      # @return [true, false] `@should`
       def should?
         !!@should
       end
 
+      # 
+      # Add a range filter to the current context. While
+      # you can pass a `Range` object to {#where}, this
+      # allows you to specify an open-ended range, such
+      # as only specifying the minimum or maximum value.
+      # 
+      # @param field [String, Symbol] The field to filter with this range
+      # @param options = {} [Hash] Options for the range
+      # @option options [Numeric] :min (nil) Minimum. Ranges are _inclusive_ by default
+      # @option options [Numeric] :max (nil) Maximum. Ranges are _inclusive_ by default
+      # @option options [true, false] :exclusive (nil) Overrides default and makes the range exclusive - 
+      #   equivalent to passing both `:exclusive_min` and `:exclusive_max`
+      # @option options [true, false] :exclusive_min (nil) Overrides default and makes the minimum exclusive
+      # @option options [true, false] :exclusive_max (nil) Overrides default and makes the maximum exclusive
+      # 
+      # @return [self] query state with range filter applied
+      # 
+      # @example Adding a range filter
+      #   query.where.range(:my_range_field,
+      #     min: 33,
+      #     exclusive: true
+      #   )
       def range(field, options = {})
         get_storage(:ranges)[field] = Stretchy::Types::Range.new(options)
         self
       end
 
+      # 
+      # Adds a geo distance filter to the current context.
+      # Documents must have a `geo_point` field that is within
+      # the specified distance of the passed parameters.
+      # 
+      # @param field [String, Symbol] The field this filter will be applied to.
+      # @param options = {} [Hash] Options for the geo distance filter
+      # @option options [String] :distance (nil) The maximum distance from the specified origin. 
+      #   Use an Elastic distance format such as `'21mi'` or `'37km'`
+      # @option options [Float] :lat (nil) The latitude of the origin point. Can also be specified as `:latitude`
+      # @option options [Float] :lng (nil) The longitude of the origin point. 
+      #   Can also be specified as `:lon` or `:longitude`
+      # 
+      # @return [self] query state with geo distance filter applied
+      # 
+      # @example Searching by distance from a point
+      #   query.where.geo(:coords,
+      #     distance: '27km',
+      #     lat: 33.3,
+      #     lng: 29.2
+      #   )
       def geo(field, options = {})
         get_storage(:geos)[field] = {
           distance:  options[:distance],
@@ -32,14 +129,65 @@ module Stretchy
         self
       end
 
+      # 
+      # Switches current state to inverted. Options passed 
+      # here are equivalent to those passed to {#initialize},
+      # except documents *must not* match these filters.
+      # 
+      # Can be chained with {#should} to produce inverted should queries
+      # 
+      # @param options = {} [Hash] Options to filter on
+      # 
+      # @return [WhereClause] inverted query state with not filters applied.
+      # 
+      # @example Inverting filters
+      #   query.where.not(
+      #     must_exist: nil,
+      #     not_matching: "this string",
+      #     not_in: [45, 67, 99],
+      #     not_in_range: 89..23
+      #   )
+      # 
+      # @example Inverted should filters
+      #   query.should.not(
+      #     match_field: [:these, "options"]
+      #   )
       def not(options = {})
         self.class.new(self, options.merge(inverse: true, should: should?))
       end
 
+      # 
+      # Switches the current state to `should`. Options passed
+      # here are equivalent to those passed to {#initialize},
+      # except documents which do not match are still returned
+      # with a lower score than documents which do match.
+      # 
+      # Can be chained with {#not} to produce inverted should queries
+      # 
+      # @param options = {} [Hash] Options to filter on
+      # 
+      # @return [WhereClause] should query state with should filters applied
+      # 
+      # @example Specifying should options
+      #   query.should(
+      #     field: [99, 27]
+      #   )
+      # 
+      # @example Inverted should options
+      #   query.should.not(
+      #     exists_field: nil
+      #   ) 
       def should(options = {})
         self.class.new(self, options.merge(should: true))
       end
 
+      # 
+      # Converts the current context into a boost to
+      # be passed into a {FunctionScoreQuery}.
+      # 
+      # @param weight = nil [Numeric] A weight for the {FunctionScoreQuery}
+      # 
+      # @return [Boosts::FilterBoost] A boost including all the current filters
       def to_boost(weight = nil)
         weight ||= Stretchy::Boosts::FilterBoost::DEFAULT_WEIGHT
         

data/lib/stretchy/results/base.rb

@@ -26,7 +26,14 @@ module Stretchy
       end
 
       def response
-        @response ||= Stretchy.search(type: type, body: request, from: offset, size: limit)
+        params = {
+          type: type, 
+          body: request,
+          from: offset,
+          size: limit
+        }
+        params[:explain] = true if clause.get_explain
+        @response ||= Stretchy.search(params)
       end
 
       def ids
@@ -41,6 +48,18 @@ module Stretchy
       end
       alias :results :hits
 
+      def scores
+        @scores ||= Hash[response['hits']['hits'].map do |hit|
+          [hit['_id'], hit['_score']]
+        end]
+      end
+
+      def explanations
+        @scores ||= Hash[response['hits']['hits'].map do |hit|
+          [hit['_id'], hit['_explanation']]
+        end]
+      end
+
       def took
         @took ||= response['took']
       end

data/lib/stretchy/utils/client_actions.rb

@@ -8,12 +8,14 @@ module Stretchy
         end
       end
 
-      # used for ensuring a concistent index in specs
+      # used for ensuring a consistent index in specs
       def refresh
+        Stretchy.log("Refreshing index: #{index_name}")
         client.indices.refresh index: index_name
       end
 
       def count
+        Stretchy.log("Counting all documents in index: #{index_name}")
         client.cat.count(index: index_name).split(' ')[2].to_i
       end
 
@@ -30,7 +32,10 @@ module Stretchy
           params[field] = options[field] if options[field]
         end
 
-        client.search(params)
+        Stretchy.log("Querying Elastic:", params)
+        response = client.search(params)
+        Stretchy.log("Received response:", response)
+        response
       end
 
       def index(options = {})
@@ -38,7 +43,16 @@ module Stretchy
         type  = options[:type]
         body  = options[:body]
         id    = options[:id] || options['id'] || body['id'] || body['_id'] || body[:id] || body[:_id]
-        client.index(index: index, type: type, id: id, body: body)
+        params = {
+          index:  index,
+          type:   type,
+          id:     id,
+          body:   body
+        }
+        Stretchy.log("Indexing document:", params)
+        response = client.index(params)
+        Stretchy.log("Received response:", response)
+        response
       end
 
       def bulk(options = {})
@@ -51,23 +65,29 @@ module Stretchy
             document
           ]
         end
-        client.bulk body: requests
+        Stretchy.log("Bulk indexing documents:", {body: requests})
+        response = client.bulk body: requests
+        Stretchy.log("Received response:", response)
       end
 
       def exists(_index_name = index_name)
+        Stretchy.log("Checking index existence for: #{_index_name}")
         client.indices.exists(index: _index_name)
       end
       alias :exists? :exists
 
       def delete(_index_name = index_name)
+        Stretchy.log("Deleting index: #{_index_name}")
         client.indices.delete(index: _index_name) if exists?(_index_name)
       end
 
       def create(_index_name = index_name)
+        Stretchy.log("Creating index: #{_index_name}")
         client.indices.create(index: _index_name) unless exists?(_index_name)
       end
 
       def mapping(_index_name, _type, _body)
+        Stretchy.log("Putting mapping:", {index_name: _index_name, type: _type, body: _body})
         client.indices.put_mapping(index: _index_name, type: _type, body: _body)
       end
 

data/lib/stretchy/utils/colorize.rb

@@ -0,0 +1,71 @@
+module Stretchy
+  module Utils
+    class Colorize
+      COLORS = {
+        "default" => "38",
+        "black" => "30",
+        "red" => "31",
+        "green" => "32",
+        "brown" => "33",
+        "blue" => "34",
+        "purple" => "35",
+        "cyan" => "36",
+        "gray" => "37",
+        "dark gray" => "1;30",
+        "light red" => "1;31",
+        "light green" => "1;32",
+        "yellow" => "1;33",
+        "light blue" => "1;34",
+        "light purple" => "1;35",
+        "light cyan" => "1;36",
+        "white" => "1;37"
+      }.freeze
+
+      BG_COLORS = {
+        "default" => "0",
+        "black" => "40",
+        "red" => "41",
+        "green" => "42",
+        "brown" => "43",
+        "blue" => "44",
+        "purple" => "45",
+        "cyan" => "46",
+        "gray" => "47",
+        "dark gray" => "100",
+        "light red" => "101",
+        "light green" => "102",
+        "yellow" => "103",
+        "light blue" => "104",
+        "light purple" => "105",
+        "light cyan" => "106",
+        "white" => "107"
+      }.freeze
+
+      def colorize(string, color = "default", bg = "default")
+        color_code = COLORS[color]
+        bg_code = BG_COLORS[bg]
+        return "\033[#{bg_code};#{color_code}m#{string}\033[0m"
+      end
+
+      module ClassMethods
+        def colors
+          Colorize::COLORS
+        end
+
+        def bgs
+          Colorize::BG_COLORS
+        end
+
+        Colorize::COLORS.keys.each do |color|
+          define_method color do |string|
+            color_code = colors[color]
+            bg_code = bgs["default"]
+            string.split("\n").map{|s| "\033[#{bg_code};#{color_code}m#{s}\033[0m" }.join("\n")
+          end
+        end
+      end
+
+      extend ClassMethods
+    end
+  end
+end