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, params) ⇒ 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) ⇒ 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, params = {})
  if base.is_a?(Builders::ShellBuilder)
    @base = base
  elsif base.nil?
    @base = Builders::ShellBuilder.new
    @base.index ||= params[:index] || Stretchy.index_name
    @base.type    = params[:type]  if params[:type]
  else
    @base = Builders::ShellBuilder.new(base)
  end
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(params = {}) ⇒ self Also known as: aggs

Allows adding raw aggregation JSON to your query



252
253
254
255
 
# File 'lib/stretchy/clauses/base.rb', line 252

def aggregations(params = {})
  base.aggregate_builder = base.aggregate_builder.merge(params)
  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')

See Also:



216
217
218
 
# File 'lib/stretchy/clauses/base.rb', line 216

def boost
  BoostClause.new(base)
end

#explain ⇒ self

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

See Also:



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

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.

See Also:



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

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

#get_aggregations ⇒ Object Also known as: get_aggs 



258
259
260
 
# File 'lib/stretchy/clauses/base.rb', line 258

def get_aggregations
  base.aggregate_builder
end

#get_explain ⇒ Object 



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

def get_explain
  !!base.explain
end

#get_fields ⇒ Array

Accessor for fields Elasticsearch will return



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

def get_fields
  base.fields
end

#get_limit ⇒ Integer Also known as: limit_value

Accessor for @limit



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

def get_limit
  base.limit
end

#get_offset ⇒ Integer

Accessor for @offset



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

def get_offset
  base.offset
end

#get_page ⇒ Integer Also known as: current_page

Accessor for current page



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

def get_page
  base.page
end

#inverse? ⇒ true, false

Accessor for @inverse



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

def inverse?
  !!@inverse
end

#limit(num) ⇒ self

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

See Also:



78
79
80
81
 
# File 'lib/stretchy/clauses/base.rb', line 78

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

#not(params) ⇒ MatchClause, WhereClause #not(params) ⇒ MatchClause, WhereClause

Filter for documents that do not match the specified fields and values

See Also:

  • Stretchy::Clauses::Base.{MatchClause{MatchClause#not}
  • Stretchy::Clauses::Base.{WhereClause{WhereClause#not}


193
194
195
196
197
198
199
 
# File 'lib/stretchy/clauses/base.rb', line 193

def not(params = {}, options = {})
  if params.is_a?(String)
    build_match.not(params, options)
  else
    build_where.not(params, options)
  end
end

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

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

See Also:



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

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

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

Allows pagination via Kaminari-like accessor



121
122
123
124
125
 
# File 'lib/stretchy/clauses/base.rb', line 121

def page(num, params = {})
  base.limit  = params[:limit] || params[: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.



277
278
279
 
# File 'lib/stretchy/clauses/base.rb', line 277

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

#root ⇒ Base

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 are being processed from the base state.

If you have to call this method, please file an issue. 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.



65
66
67
 
# File 'lib/stretchy/clauses/base.rb', line 65

def root
  Base.new(base)
end

#should(params) ⇒ WhereClause #should(params) ⇒ 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.

See Also:



238
239
240
241
242
243
244
 
# File 'lib/stretchy/clauses/base.rb', line 238

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