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



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

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



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

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:



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

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:



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

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:



133
134
135
136
137
 
# File 'lib/stretchy/clauses/base.rb', line 133

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

#get_aggregations ⇒ Object Also known as: get_aggs 



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

def get_aggregations
  base.aggregate_builder
end

#get_explain ⇒ Object 



159
160
161
 
# File 'lib/stretchy/clauses/base.rb', line 159

def get_explain
  !!base.explain
end

#get_fields ⇒ Array

Accessor for fields Elasticsearch will return

Returns:

  • (Array) —

    List of fields in the current query



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

def get_fields
  base.fields
end

#get_limit ⇒ Integer Also known as: limit_value

Accessor for @limit

Returns:

  • (Integer) —

    Value of @limit



70
71
72
 
# File 'lib/stretchy/clauses/base.rb', line 70

def get_limit
  base.limit
end

#get_offset ⇒ Integer

Accessor for @offset

Returns:

  • (Integer) —

    Offset for query



94
95
96
 
# File 'lib/stretchy/clauses/base.rb', line 94

def get_offset
  base.offset
end

#get_page ⇒ Integer Also known as: current_page

Accessor for current page

Returns:

  • (Integer) —

    (offset / limit).ceil



114
115
116
 
# File 'lib/stretchy/clauses/base.rb', line 114

def get_page
  base.page
end

#inverse? ⇒ true, false

Accessor for @inverse

Returns:

  • (true, false) —

    If current context is inverse



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

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:



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

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

#match(options = {}) ⇒ MatchClause

Used for fulltext searching. Works similarly to #where .

Parameters:

  • options (defaults to: {}) —

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

Returns:

See Also:



175
176
177
 
# File 'lib/stretchy/clauses/base.rb', line 175

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:



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

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:



84
85
86
87
 
# File 'lib/stretchy/clauses/base.rb', line 84

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



104
105
106
107
108
 
# File 'lib/stretchy/clauses/base.rb', line 104

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:



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

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:



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

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:



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

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