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, #inverse?, #limit, #offset, #page, #query_results, #should

Constructor Details

#initialize(base) ⇒ BoostClause

Switch to the boost state, specifying that the next where / range / etc will be a boost instead of a regular filter / range / etc.

Parameters:

  • base (Base) —

    a clause to copy query state from

  • options —

    = {} [Hash] Options for the boost clause



34
35
36
 
# File 'lib/stretchy/clauses/boost_clause.rb', line 34

def initialize(base)
  super(base)
end

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



154
155
156
157
 
# File 'lib/stretchy/clauses/boost_clause.rb', line 154

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



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

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

#match(options = {}) ⇒ BoostMatchClause Also known as: fulltext

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.

Parameters:

  • options (defaults to: {}) —

    = {} [Hash] options for full text matching

Returns:



47
48
49
 
# File 'lib/stretchy/clauses/boost_clause.rb', line 47

def match(options = {})
  BoostMatchClause.new(base, options)
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



165
166
167
168
 
# File 'lib/stretchy/clauses/boost_clause.rb', line 165

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

#near(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 options)

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

Parameters:

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

    a customizable set of options

Options Hash (options):

  • :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 (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:



122
123
124
125
126
127
128
129
130
 
# File 'lib/stretchy/clauses/boost_clause.rb', line 122

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

    options[:origin] = Stretchy::Types::GeoPoint.new(options)
  end
  base.boost_builder.functions << Stretchy::Boosts::FieldDecayBoost.new(options)
  Base.new(base)
end

#not(options = {}) ⇒ BoostClause

Switches to inverse context - boosts added with #where and ##match will be applied to documents which do not match said filters.

Returns:



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

def not(options = {})
  @inverse = true
  self
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:



143
144
145
146
 
# File 'lib/stretchy/clauses/boost_clause.rb', line 143

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



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

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

#where(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:

  • options (defaults to: {}) —

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

Returns:



62
63
64
 
# File 'lib/stretchy/clauses/boost_clause.rb', line 62

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