Class: Stretchy::Clauses::Base

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

Overview

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 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 range and geo to add more specific filters. It inherits other methods from the Base class, allowing other transitions.

Attributes are copied when a new Clause is instanciated, so the underlying storage is maintained throughout the chain.

Direct Known Subclasses

BoostClause, MatchClause, WhereClause

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(base_or_opts, options) ⇒ Base #initialize(base_or_opts) ⇒ Base

Generates a chainable query. The only required option for the first initialization is :type , which specifies what type to query on your index.

Overloads:

  • #initialize(base_or_opts, options) ⇒ Base

    Parameters:

    • base (Base) —

      another clause to copy attributes from

    • options (Hash) —

      options to set on the new state

  • #initialize(base_or_opts) ⇒ Base

    Options Hash (base_or_opts):

    • :index (String) —

      The Elastic index to query

    • :type (String) —

      The Lucene type to query on

    • :inverse (true, false) —

      Whether we are in a not context



38
39
40
41
42
43
44
45
46
47
48
 
# File 'lib/stretchy/clauses/base.rb', line 38

def initialize(base = nil, options = {})
  if base.is_a?(Builders::ShellBuilder)
    @base = base
  elsif base.nil?
    @base = Builders::ShellBuilder.new
  else
    @base = Builders::ShellBuilder.new(base)
  end
  @base.index ||= options[:index] || Stretchy.index_name
  @base.type    = options[:type]  if options[:type]
end

Instance Attribute Details

#base ⇒ Object (readonly)

Returns the value of attribute base.



19
20
21
 
# File 'lib/stretchy/clauses/base.rb', line 19

def base
  @base
end

Instance Method Details

#aggregations(opts = {}) ⇒ self Also known as: aggs

Allows adding raw aggregation JSON to your query

Parameters:

  • opts (defaults to: {}) —

    = {} [Hash] JSON to aggregate on

Returns:

  • (self) —

    Allows continuing the query chain



267
268
269
270
 
# File 'lib/stretchy/clauses/base.rb', line 267

def aggregations(opts = {})
  base.aggregate_builder = base.aggregate_builder.merge(opts)
  self
end

#boost ⇒ BoostClause

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

Examples:

Boost documents that match a filter

query.boost.where('post.user_id' => current_user.id)

Boost documents that match fulltext search

query.boost.match('user search terms')

Returns:

See Also:



208
209
210
 
# File 'lib/stretchy/clauses/base.rb', line 208

def boost
  BoostClause.new(base)
end

#explain ⇒ self

Tells the search to explain the scoring mechanism for each document.

Returns:

  • (self) —

    Allows continuing the query chain

See Also:



152
153
154
155
 
# File 'lib/stretchy/clauses/base.rb', line 152

def explain
  base.explain = true
  self
end

#fields(*args) ⇒ self

Select fields for Elasticsearch to return

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.

Parameters:

  • new_fields (Array) —

    Fields elasticsearch should return

Returns:

  • (self) —

    Allows continuing the query chain

See Also:



131
132
133
134
135
 
# File 'lib/stretchy/clauses/base.rb', line 131

def fields(*args)
  base.fields ||= []
  base.fields += args.flatten if args.any?
  self
end

#get_aggregations ⇒ Object Also known as: get_aggs 



273
274
275
 
# File 'lib/stretchy/clauses/base.rb', line 273

def get_aggregations
  base.aggregate_builder
end

#get_explain ⇒ Object 



157
158
159
 
# File 'lib/stretchy/clauses/base.rb', line 157

def get_explain
  !!base.explain
end

#get_fields ⇒ Array

Accessor for fields Elasticsearch will return

Returns:

  • (Array) —

    List of fields in the current query



141
142
143
 
# File 'lib/stretchy/clauses/base.rb', line 141

def get_fields
  base.fields
end

#get_limit ⇒ Integer Also known as: limit_value

Accessor for @limit

Returns:

  • (Integer) —

    Value of @limit



68
69
70
 
# File 'lib/stretchy/clauses/base.rb', line 68

def get_limit
  base.limit
end

#get_offset ⇒ Integer

Accessor for @offset

Returns:

  • (Integer) —

    Offset for query



92
93
94
 
# File 'lib/stretchy/clauses/base.rb', line 92

def get_offset
  base.offset
end

#get_page ⇒ Integer Also known as: current_page

Accessor for current page

Returns:

  • (Integer) —

    (offset / limit).ceil



112
113
114
 
# File 'lib/stretchy/clauses/base.rb', line 112

def get_page
  base.page
end

#inverse? ⇒ true, false

Accessor for @inverse

Returns:

  • (true, false) —

    If current context is inverse



282
283
284
 
# File 'lib/stretchy/clauses/base.rb', line 282

def inverse?
  !!@inverse
end

#limit(num) ⇒ self

Sets how many results to return, similar to ActiveRecord's limit method.

Parameters:

  • num (Integer) —

    How many results to return

Returns:

  • (self)

See Also:



59
60
61
62
 
# File 'lib/stretchy/clauses/base.rb', line 59

def limit(num)
  base.limit = num
  self
end

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

Used for fulltext searching. Works similarly to #where .

Parameters:

  • options (defaults to: {}) —

    = {} [Hash] Options to be passed to the MatchClause

Returns:

See Also:



173
174
175
 
# File 'lib/stretchy/clauses/base.rb', line 173

def match(options = {})
  MatchClause.new(base, options)
end

#not(string) ⇒ Base #not(opts_or_string) ⇒ Base

Inverts the current context - the next method called, such as #where or #match will generate a filter specifying the document does not match the specified filter.

Overloads:

  • #not(string) ⇒ Base

    Parameters:

    • A (String) —

      string that must not be anywhere in the document

  • #not(opts_or_string) ⇒ Base

    Parameters:

    • Options (Hash) —

      to be passed to an inverted WhereClause

Returns:



227
228
229
230
231
232
233
 
# File 'lib/stretchy/clauses/base.rb', line 227

def not(opts_or_string = {})
  if opts_or_string.is_a?(Hash)
    WhereClause.new(base).not(opts_or_string)
  else
    MatchClause.new(base).not(opts_or_string)
  end
end

#offset(num) ⇒ self Also known as: per_page

Sets the offset to start returning results at. Corresponds to Elastic's "from" parameter

Parameters:

  • num (Integer) —

    Offset for query

Returns:

  • (self)

See Also:



82
83
84
85
 
# File 'lib/stretchy/clauses/base.rb', line 82

def offset(num)
  base.offset = num
  self
end

#page(num, options = {}) ⇒ self

Allows pagination via Kaminari-like accessor

Parameters:

  • num (Integer) —

    Page number. Natural numbers only, this is not zero-indexed

  • per_page (Hash) —

    a customizable set of options

Returns:

  • (self) —

    Allows continuing the query chain



102
103
104
105
106
 
# File 'lib/stretchy/clauses/base.rb', line 102

def page(num, options = {})
  base.limit  = options[:limit] || options[:per_page] || get_limit
  base.offset = [(num - 1), 0].max.ceil * get_limit
  self
end

#query_results ⇒ Results::Base

The Results object for this query, which handles sending the search request and providing convienent accessors for the response.

Returns:



292
293
294
 
# File 'lib/stretchy/clauses/base.rb', line 292

def query_results
  @query_results ||= Stretchy::Results::Base.new(base)
end

#should(opts_or_string) ⇒ WhereClause #should(opts_or_string) ⇒ WhereClause

Adds filters in the should context. Operates just like #where, but these filters only serve to add to the relevance score of the returned documents, rather than being required to match.

Overloads:

  • #should(opts_or_string) ⇒ WhereClause

    Parameters:

    • A (String) —

      string to match via full-text search anywhere in the document.

  • #should(opts_or_string) ⇒ WhereClause

    Parameters:

    • Options (Hash) —

      to generate filters.

Returns:

  • (WhereClause) —

    current query state with should clauses applied

See Also:



253
254
255
256
257
258
259
 
# File 'lib/stretchy/clauses/base.rb', line 253

def should(opts_or_string = {})
  if opts_or_string.is_a?(Hash)
    WhereClause.new(base).should(opts_or_string)
  else
    MatchClause.new(base).should(opts_or_string)
  end
end

#where(options = {}) ⇒ WhereClause Also known as: filter

Used for filtering results. Works similarly to ActiveRecord's where method.

Parameters:

  • options (defaults to: {}) —

    = {} [Hash] Options to be passed to the WhereClause

Returns:

See Also:



188
189
190
 
# File 'lib/stretchy/clauses/base.rb', line 188

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