stretchy 0.4.6 → 0.4.7

data/lib/stretchy/clauses/base.rb

@@ -3,7 +3,7 @@ module Stretchy
     # A Clause is the basic unit of Stretchy's chainable query syntax.
     # Think of it as a state machine, with transitions between states
     # being handled by methods that return another Clause. When you
-    # call the `where` method, it stores the params passed as an 
+    # call the `where` method, it stores the params passed as an
     # internal representation, to be compiled down to the Elastic query
     # syntax, and returns a WhereClause. The WhereClause reflects the
     # current state of the query, and gives you access to methods like
@@ -21,18 +21,18 @@ module Stretchy
       delegate [:request, :response, :results, :ids, :hits, :query,
                 :took, :shards, :total, :max_score, :total_pages] => :query_results
       delegate [:to_search] => :base
-      delegate [:where, :range, :geo, :terms, :not] => :build_where
-      delegate [:match, :fulltext, :more_like] => :build_match
+      delegate [:where, :range, :geo, :terms, :not, :filter] => :build_where
+      delegate [:match, :fulltext, :more_like, :query] => :build_match
 
       #
       # Generates a chainable query. The only required option for the
       # first initialization is `:type` , which specifies what type
       # to query on your index.
-      # 
+      #
       # @overload initialize(base_or_opts, params)
       #   @param base [Base] another clause to copy attributes from
       #   @param params [Hash] params to set on the new state
-      # 
+      #
       # @overload initialize(base_or_opts)
       #   @option base_or_opts [String] :index        The Elastic index to query
       #   @option base_or_opts [String] :type         The Lucene type to query on
@@ -49,7 +49,7 @@ module Stretchy
         end
       end
 
-      # 
+      #
       # Exits any state the query is in (boost, inverse, should, etc)
       # and returns to the root query state. You can use this before
       # calling `.where` or other overridden methods to ensure they
@@ -59,44 +59,44 @@ module Stretchy
       # End-of-chain methods (such as `.boost.where.not()`) should
       # always return to the root state, and state is not
       # something you should have to think about.
-      # 
+      #
       # @return [Base] Continue the query chain from the root state
       #
       def root
         Base.new(base)
       end
 
-      # 
+      #
       # Sets how many results to return, similar to
       # ActiveRecord's limit method.
-      # 
+      #
       # @see http://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-body.html Elastic Docs - Request Body Search
-      # 
+      #
       # @param num [Integer] How many results to return
-      # 
+      #
       # @return [self]
       def limit(num)
         base.limit = num
         self
       end
 
-      # 
+      #
       # Accessor for `@limit`
-      # 
+      #
       # @return [Integer] Value of `@limit`
       def get_limit
         base.limit
       end
       alias :limit_value :get_limit
 
-      # 
+      #
       # Sets the offset to start returning results at.
       # Corresponds to Elastic's "from" parameter
-      # 
+      #
       # @param num [Integer] Offset for query
-      # 
+      #
       # @see http://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-body.html Elastic Docs - Request Body Search
-      # 
+      #
       # @return [self]
       def offset(num)
         base.offset = num
@@ -104,19 +104,19 @@ module Stretchy
       end
       alias :per_page :offset
 
-      # 
+      #
       # Accessor for `@offset`
-      # 
+      #
       # @return [Integer] Offset for query
       def get_offset
         base.offset
       end
 
-      # 
+      #
       # Allows pagination via Kaminari-like accessor
       # @param num [Integer] Page number. Natural numbers only, **this is not zero-indexed**
       # @option per_page [Integer] :per_page (DEFAULT_LIMIT) Number of results per page
-      # 
+      #
       # @return [self] Allows continuing the query chain
       def page(num, params = {})
         base.limit  = params[:limit] || params[:per_page] || get_limit
@@ -124,28 +124,28 @@ module Stretchy
         self
       end
 
-      # 
+      #
       # Accessor for current page
-      # 
+      #
       # @return [Integer] (offset / limit).ceil
       def get_page
         base.page
       end
       alias :current_page :get_page
 
-      # 
+      #
       # Select fields for Elasticsearch to return
-      # 
-      # By default, Stretchy will return the entire _source 
+      #
+      # By default, Stretchy will return the entire _source
       # for each document. If you call `.fields` with no
       # arguments or an empty array, Stretchy will pass
       # an empty array and only the "_type" and "_id"
       # fields will be returned.
-      # 
+      #
       # @see  https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-fields.html Elastic Docs - Fields
-      # 
+      #
       # @param new_fields [Array] Fields elasticsearch should return
-      # 
+      #
       # @return [self] Allows continuing the query chain
       def fields(*args)
         base.fields ||= []
@@ -153,20 +153,20 @@ module Stretchy
         self
       end
 
-      # 
+      #
       # Accessor for fields Elasticsearch will return
-      # 
+      #
       # @return [Array] List of fields in the current query
       def get_fields
         base.fields
       end
 
-      # 
+      #
       # Tells the search to explain the scoring
       # mechanism for each document.
-      # 
+      #
       # @see http://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-explain.html Elastic Docs - Request Body Search (explain)
-      # 
+      #
       # @return [self] Allows continuing the query chain
       def explain
         base.explain = true
@@ -177,19 +177,19 @@ module Stretchy
         !!base.explain
       end
 
-      # 
+      #
       # Filter for documents that do not match the specified fields and values
-      # 
+      #
       # @overload not(params)
       #   @param [String] A string that must not be matched anywhere in the document
       # @overload not(params)
       #   @param [Hash] A hash of fields and strings or terms that must not be matched in those fields
-      # 
+      #
       # @return [MatchClause, WhereClause] inverted query state with match filters applied
       #
       # @see {MatchClause#not}
       # @see {WhereClause#not}
-      # 
+      #
       def not(params = {}, options = {})
         if params.is_a?(String)
           build_match.not(params, options)
@@ -198,42 +198,42 @@ module Stretchy
         end
       end
 
-      # 
+      #
       # Used for boosting the relevance score of
       # search results. `match` and `where` clauses
       # added after `boost` will be applied as
       # boosting functions instead of filters
-      # 
+      #
       # @example Boost documents that match a filter
       #   query.boost.where('post.user_id' => current_user.id)
-      # 
+      #
       # @example Boost documents that match fulltext search
       #   query.boost.match('user search terms')
-      # 
+      #
       # @return [BoostClause] query in boost context
-      # 
+      #
       # @see http://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-function-score-query.html Elastic Docs - Function Score Query
       def boost
         BoostClause.new(base)
       end
 
-      # 
+      #
       # Adds filters in the `should` context. Operates just like
-      # {#where}, but these filters only serve to add to the 
+      # {#where}, but these filters only serve to add to the
       # relevance score of the returned documents, rather than
       # being required to match.
-      # 
+      #
       # @overload  should(params)
-      #   @param [String] A string to match via full-text search 
+      #   @param [String] A string to match via full-text search
       #     anywhere in the document.
-      # 
+      #
       # @overload should(params)
       #   @param [Hash] Options to generate filters.
-      # 
+      #
       # @return [WhereClause] current query state with should clauses applied
-      # 
+      #
       # @see http://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-bool-query.html Elastic Docs - Bool Query
-      # 
+      #
       # @see http://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-bool-filter.html Elastic Docs - Bool Filter
       def should(params = {}, options = {})
         if params.is_a?(Hash)
@@ -243,11 +243,11 @@ module Stretchy
         end
       end
 
-      # 
+      #
       # Allows adding raw aggregation JSON to your
       # query
       # @param params = {} [Hash] JSON to aggregate on
-      # 
+      #
       # @return [self] Allows continuing the query chain
       def aggregations(params = {})
         base.aggregate_builder = base.aggregate_builder.merge(params)
@@ -260,19 +260,19 @@ module Stretchy
       end
       alias :get_aggs :get_aggregations
 
-      # 
+      #
       # Accessor for `@inverse`
-      # 
+      #
       # @return [true, false] If current context is inverse
       def inverse?
         !!@inverse
       end
 
-      # 
+      #
       # The Results object for this query, which handles
       # sending the search request and providing convienent
       # accessors for the response.
-      # 
+      #
       # @return [Results::Base] The results returned from Elastic
       def query_results
         @query_results ||= Stretchy::Results::Base.new(base)
@@ -292,6 +292,12 @@ module Stretchy
           params.is_a?(String) ? { '_all' => params } : params
         end
 
+        def merge_state(options = {})
+          options[:should]  = true if options[:should].nil?  && should?
+          options[:inverse] = true if options[:inverse].nil? && inverse?
+          options
+        end
+
     end
   end
 end

data/lib/stretchy/clauses/boost_clause.rb

@@ -2,35 +2,35 @@ require 'stretchy/clauses/base'
 
 module Stretchy
   module Clauses
-      # 
+      #
       # A Boost clause encapsulates the boost query state. It
       # basically says "the next where / range / match filter
       # will be used to boost a document's score instead of
       # selecting documents to return."
-      # 
+      #
       # Calling `.boost` by itself doesn't do anything, but
       # the next method (`.near`, `.match`, etc) will specify
       # a boost using the same syntax as other clauses. These
-      # methods take a `:weight` parameter specifying the weight 
+      # methods take a `:weight` parameter specifying the weight
       # to assign that boost.
-      # 
+      #
       # @author [atevans]
-      # 
+      #
     class BoostClause < Base
 
       extend Forwardable
 
-      delegate [:geo, :range] => :where
-      delegate [:fulltext]    => :match
+      delegate [:geo, :range, :filter] => :where
+      delegate [:fulltext, :query]    => :match
 
-      # 
+      #
       # Changes query state to "match" in the context
       # of boosting. Options here work the same way as
       # {MatchClause#initialize}, but the combined query
       # will be applied as a boost function.
-      # 
+      #
       # @param params = {} [Hash] params for full text matching
-      # 
+      #
       # @return [BoostMatchClause] query with boost match state
       def match(params = {}, options = {})
         clause = BoostMatchClause.new(base)
@@ -38,23 +38,21 @@ module Stretchy
         clause
       end
 
-      # 
+      #
       # Changes query state to "where" in the context
       # of boosting. Works the same way as {WhereClause},
       # but applies the generated filters as a boost
-      # function. 
-      # 
+      # function.
+      #
       # @param params = {} [Hash] Filters to use in this boost.
-      # 
+      #
       # @return [BoostWhereClause] Query state with boost filters applied
-      # 
+      #
       def where(params = {}, options = {})
         BoostWhereClause.new(base).boost_where(params, options)
       end
-      alias :filter :where
 
-
-      # 
+      #
       # Adds a boost based on the value in the specified field.
       # You can pass more than one field as arguments, and
       # you can also pass the `factor` and `modifier` options
@@ -66,16 +64,16 @@ module Stretchy
       #
       # @example Adding two fields with options
       #   query = query.boost.field(:numeric_field, :other_field, factor: 7, modifier: :log2p)
-      # 
+      #
       # @param *args [Arguments] Fields to add to the document score
       # @param options = {} [Hash] Options to pass to the field_value_factor boost
-      # 
+      #
       # @return [self] Query state with field boosts applied
       #
       # @see https://www.elastic.co/guide/en/elasticsearch/guide/current/boosting-by-popularity.html Elasticsearch guide on boosting by popularity
       #
       # @see https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-function-score-query.html#_field_value_factor Elasticsearch field value factor reference
-      # 
+      #
       def field(*args)
         options = args.last.is_a?(Hash) ? args.pop : {}
         args.each do |field|
@@ -88,18 +86,18 @@ module Stretchy
         raise Errors::InvalidQueryError.new("Cannot call .not directly after boost - use .where.not or .match.not instead")
       end
 
-      # 
+      #
       # Adds a {Boosts::FieldDecayBoost}, which boosts
-      # a search result based on how close it is to a 
+      # a search result based on how close it is to a
       # specified value. That value can be a date, time,
       # number, or {Types::GeoPoint}
-      # 
+      #
       # Required:
-      # 
+      #
       # * `:field`
       # * `:origin` or `:lat` & `:lng` combo
       # * `:scale`
-      # 
+      #
       # @option params [Numeric] :field What field to check with this boost
       # @option params [Date, Time, Numeric, Types::GeoPoint] :origin Boost score based on how close the field is to this value. Required unless {Types::GeoPoint} is present (:lat, :lng, etc)
       # @option params [Numeric] :lat Latitude, for a geo point
@@ -109,10 +107,10 @@ module Stretchy
       # @option params [Numeric] :longitude Longitude, for a geo point
       # @option params [String] :scale When the field is this distance from origin, the boost will be multiplied by `:decay` . Default is 0.5, so when `:origin` is a geo point and `:scale` is '10mi', then this boost will be twice as much for a point at the origin as for one 10 miles away
       # @option params [String] :offset Anything within this distance of the origin is boosted as if it were at the origin
-      # @option params [Symbol] :type (:gauss) What type of decay to use. One of `:linear`, `:exp`, or `:gauss` 
+      # @option params [Symbol] :type (:gauss) What type of decay to use. One of `:linear`, `:exp`, or `:gauss`
       # @option params [Numeric] :decay_amount (0.5) How much the boost falls off when it is `:scale` distance from `:origin`
       # @option params [Numeric] :weight (1.2) How strongly to weight this boost compared to others
-      # 
+      #
       # @example Boost near a geo point
       #   query.boost.near(
       #     field: :coords,
@@ -121,14 +119,14 @@ module Stretchy
       #     lat: 33.3,
       #     lng: 28.2
       #   )
-      # 
+      #
       # @example Boost near a date
       #   query.boost.near(
       #     field: :published_at,
       #     origin: Time.now,
       #     scale: '3d'
       #   )
-      # 
+      #
       # @example Boost near a number (with params)
       #   query.boost.near(
       #     field: :followers,
@@ -139,9 +137,9 @@ module Stretchy
       #     decay: 0.75,
       #     weight: 10
       #   )
-      # 
+      #
       # @return [Base] Query with field decay filter added
-      # 
+      #
       # @see http://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-function-score-query.html Elastic Docs - Function Score Query
       def near(params = {}, options = {})
         if params[:lat] || params[:latitude]  ||
@@ -154,61 +152,61 @@ module Stretchy
       end
       alias :geo :near
 
-      # 
+      #
       # Adds a {Boosts::RandomBoost} to the query, for slightly
       # randomizing search results.
-      # 
+      #
       # @param seed [Numeric] The seed for the random value
       # @param weight [Numeric] The weight for this random value
-      # 
+      #
       # @return [Base] Query with random boost applied
-      # 
+      #
       # @see http://www.elastic.co/guide/en/elasticsearch/guide/master/random-scoring.html Elastic Docs - Random Scoring
       def random(*args)
         base.boost_builder.functions << Stretchy::Boosts::RandomBoost.new(*args)
         Base.new(base)
       end
 
-      # 
+      #
       # Defines a global boost for all documents in the query
-      # 
+      #
       # @param num [Numeric] Boost to apply to the whole query
-      # 
+      #
       # @return [self] Boost context with overall boost applied
       def all(num)
         base.boost_builder.overall_boost = num
         self
       end
 
-      # 
+      #
       # The maximum boost that any document can have
-      # 
+      #
       # @param num [Numeric] Maximum score a document can have
-      # 
+      #
       # @return [self] Boost context with maximum score applied
       def max(num)
         base.boost_builder.max_boost = num
         self
       end
 
-      # 
+      #
       # Set scoring mode for when a document matches multiple
       # boost functions.
-      # 
+      #
       # @param mode [Symbol] Score mode. Can be one of `multiply sum avg first max min`
-      # 
+      #
       # @return [self] Boost context with score mode applied
       def score_mode(mode)
         base.boost_builder.score_mode = mode
         self
       end
 
-      # 
+      #
       # Set boost mode for when a document matches multiple
       # boost functions.
-      # 
+      #
       # @param mode [Symbol] Boost mode. Can be one of `multiply replace sum avg max min`
-      # 
+      #
       # @return [self] Boost context with boost mode applied
       def boost_mode(mode)
         base.boost_builder.boost_mode = mode
@@ -217,4 +215,4 @@ module Stretchy
 
     end
   end
-end
+end

data/lib/stretchy/clauses/boost_match_clause.rb

@@ -2,40 +2,57 @@ 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 
+      # 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
 
-      # 
+      #
       # Switches to inverse context, and applies filters as inverse
       # options (ie, documents that *do not* match the query will
       # be boosted)
-      # 
+      #
       # @overload not(params)
       #   @param [String] String that must not match anywhere in the document
-      # 
+      #
       # @overload not(params)
       #   @param params [Hash] Fields and values that should not match in the document
-      # 
+      #
       # @return [BoostMatchClause] Query with inverse matching boost function applied
       def not(params = {})
         @inverse = true
         match_function(hashify_params(params))
       end
 
+      #
+      # Boosts documents that are returned by a Match query.
+      #
+      # @param [Hash] Parameters for the match query. See {MatchClause#match}
+      # @param [Hash] Options for Stretchy to determine behavior of this boost
+      #
+      # @return [BoostMatchClause] Query with boost match applied
       def boost_match(params = {}, options = {})
         match_function(hashify_params(params), options)
       end
 
+      #
+      # Boosts documents according to how closely they match a given phrase.
+      # This acts similarly to {MatchClause#fulltext}, but only adds a boost,
+      # so it will not interfere with the query. For example, it will not
+      # filter out documents that don't match at least one term.
+      #
+      # @param [Hash] Parameters for the match query. See {MatchClause#match}
+      # @param [Hash] Options for Stretchy to determine behavior of this boost
+      #
+      # @return [Base] Query with boost match applied
       def fulltext(params = {}, options = {})
         _params = hashify_params(params)
         weight = _params.delete(:weight) || options[:weight]
@@ -48,35 +65,51 @@ module Stretchy
         Base.new(base)
       end
 
-      # 
+      #
+      # Boosts documents using a query with arbitrary json passed to the
+      # method. See {MatchClause#query}.
+      #
+      # @param [Hash] Arbitrary json to use as a query
+      # @param [Hash] Options for Stretchy to determine behavior of this boost
+      #
+      # @return [Base] Query with arbitrary json query boost added
+      def query(params = {}, options = {})
+        weight = params.delete(:weight) || options[:weight]
+        clause = MatchClause.new.query(params, options)
+        boost = clause.to_boost(weight)
+        base.boost_builder.add_boost(boost) if boost
+        Base.new(base)
+      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(base).where(*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(base).match(*args)
@@ -94,4 +127,4 @@ module Stretchy
 
     end
   end
-end
+end