Class: Stretchy::Clauses::BoostClause

Inherits:
Base
  • Object
show all
Extended by:
Forwardable
Defined in:
lib/stretchy/clauses/boost_clause.rb

Overview

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 to assign that boost.

Author:

  • [atevans]

Direct Known Subclasses

BoostMatchClause, BoostWhereClause

Instance Attribute Summary

Attributes inherited from Base

#base

Instance Method Summary collapse

Methods inherited from Base

#aggregations, #boost, #explain, #fields, #get_aggregations, #get_explain, #get_fields, #get_limit, #get_offset, #get_page, #initialize, #inverse?, #limit, #offset, #page, #query_results, #root, #should

Constructor Details

This class inherits a constructor from Stretchy::Clauses::Base

Instance Method Details

#all(num) ⇒ self

Defines a global boost for all documents in the query

Parameters:

  • num (Numeric) —

    Boost to apply to the whole query

Returns:

  • (self) —

    Boost context with overall boost applied



178
179
180
181
 
# File 'lib/stretchy/clauses/boost_clause.rb', line 178

def all(num)
  base.boost_builder.overall_boost = num
  self
end

#boost_mode(mode) ⇒ self

Set boost mode for when a document matches multiple boost functions.

Parameters:

  • mode (Symbol) —

    Boost mode. Can be one of multiply replace sum avg max min

Returns:

  • (self) —

    Boost context with boost mode applied



213
214
215
216
 
# File 'lib/stretchy/clauses/boost_clause.rb', line 213

def boost_mode(mode)
  base.boost_builder.boost_mode = mode
  self
end

#field(*args) ⇒ self

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 as an options hash.

CAUTION: All documents in the index must have a numeric value for any fields specified here, or the query will fail.

Examples:

Adding two fields with options

query = query.boost.field(:numeric_field, :other_field, factor: 7, modifier: :log2p)

Parameters:

  • *args (Arguments) —

    Fields to add to the document score

  • options —

    = {} [Hash] Options to pass to the field_value_factor boost

Returns:

  • (self) —

    Query state with field boosts applied

See Also:



79
80
81
82
83
84
85
 
# File 'lib/stretchy/clauses/boost_clause.rb', line 79

def field(*args)
  options = args.last.is_a?(Hash) ? args.pop : {}
  args.each do |field|
    base.boost_builder.add_boost(Boosts::FieldValueBoost.new(field, options))
  end
  Base.new(base)
end

#match(params = {}, options = {}) ⇒ BoostMatchClause

Changes query state to "match" in the context of boosting. Options here work the same way as Stretchy::Clauses::Base#initialize, but the combined query will be applied as a boost function.

Parameters:

  • params (defaults to: {}) —

    = {} [Hash] params for full text matching

Returns:



35
36
37
38
39
 
# File 'lib/stretchy/clauses/boost_clause.rb', line 35

def match(params = {}, options = {})
  clause = BoostMatchClause.new(base)
  clause = clause.boost_match(params, options) unless params.empty? && options.empty?
  clause
end

#max(num) ⇒ self

The maximum boost that any document can have

Parameters:

  • num (Numeric) —

    Maximum score a document can have

Returns:

  • (self) —

    Boost context with maximum score applied



189
190
191
192
 
# File 'lib/stretchy/clauses/boost_clause.rb', line 189

def max(num)
  base.boost_builder.max_boost = num
  self
end

#near(params = {}, options = {}) ⇒ Base Also known as: geo

Adds a Boosts::FieldDecayBoost, which boosts 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

Examples:

Boost near a geo point

query.boost.near(
  field: :coords,
  distance: '27km',
  scale: '3mi',
  lat: 33.3,
  lng: 28.2
)

Boost near a date

query.boost.near(
  field: :published_at,
  origin: Time.now,
  scale: '3d'
)

Boost near a number (with params)

query.boost.near(
  field: :followers,
  origin: 100,
  scale: 50,
  offset: 2,
  type: :linear,
  decay: 0.75,
  weight: 10
)

Parameters:

  • params (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (params):

  • :field (Numeric) —

    What field to check with this boost

  • :origin (Date, Time, Numeric, Types::GeoPoint) —

    Boost score based on how close the field is to this value. Required unless Types::GeoPoint is present (:lat, :lng, etc)

  • :lat (Numeric) —

    Latitude, for a geo point

  • :latitude (Numeric) —

    Latitude, for a geo point

  • :lng (Numeric) —

    Longitude, for a geo point

  • :lon (Numeric) —

    Longitude, for a geo point

  • :longitude (Numeric) —

    Longitude, for a geo point

  • :scale (String) —

    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

  • :offset (String) —

    Anything within this distance of the origin is boosted as if it were at the origin

  • :type (Symbol) — default: :gauss —

    What type of decay to use. One of :linear, :exp, or :gauss

  • :decay_amount (Numeric) — default: 0.5 —

    How much the boost falls off when it is :scale distance from :origin

  • :weight (Numeric) — default: 1.2 —

    How strongly to weight this boost compared to others

Returns:

  • (Base) —

    Query with field decay filter added

See Also:



146
147
148
149
150
151
152
153
154
 
# File 'lib/stretchy/clauses/boost_clause.rb', line 146

def near(params = {}, options = {})
  if params[:lat] || params[:latitude]  ||
     params[:lng] || params[:longitude] || params[:lon]

    params[:origin] = Stretchy::Types::GeoPoint.new(params)
  end
  base.boost_builder.add_boost Stretchy::Boosts::FieldDecayBoost.new(params)
  Base.new(base)
end

#not(*args) ⇒ Object

Raises:



87
88
89
 
# File 'lib/stretchy/clauses/boost_clause.rb', line 87

def not(*args)
  raise Errors::InvalidQueryError.new("Cannot call .not directly after boost - use .where.not or .match.not instead")
end

#random(*args) ⇒ Base

Adds a Boosts::RandomBoost to the query, for slightly randomizing search results.

Parameters:

  • seed (Numeric) —

    The seed for the random value

  • weight (Numeric) —

    The weight for this random value

Returns:

  • (Base) —

    Query with random boost applied

See Also:



167
168
169
170
 
# File 'lib/stretchy/clauses/boost_clause.rb', line 167

def random(*args)
  base.boost_builder.functions << Stretchy::Boosts::RandomBoost.new(*args)
  Base.new(base)
end

#score_mode(mode) ⇒ self

Set scoring mode for when a document matches multiple boost functions.

Parameters:

  • mode (Symbol) —

    Score mode. Can be one of multiply sum avg first max min

Returns:

  • (self) —

    Boost context with score mode applied



201
202
203
204
 
# File 'lib/stretchy/clauses/boost_clause.rb', line 201

def score_mode(mode)
  base.boost_builder.score_mode = mode
  self
end

#where(params = {}, options = {}) ⇒ BoostWhereClause Also known as: filter

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.

Parameters:

  • params (defaults to: {}) —

    = {} [Hash] Filters to use in this boost.

Returns:



51
52
53
 
# File 'lib/stretchy/clauses/boost_clause.rb', line 51

def where(params = {}, options = {})
  BoostWhereClause.new(base).boost_where(params, options)
end