stretchy 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 213d84388de53cfe8d9b815d34ef544349cb2bd0
+  data.tar.gz: 5cdfb873ac77da2e9815c7ac3f36da1dc27889e8
+SHA512:
+  metadata.gz: 590ee2ca8abb6251effe21b6561a29459f80a6e4361158c9d0103c80dc0594a97b00c5c8b77b51beea296ce21350274b5a4ab128e40e010b5fb00b8cb289449b
+  data.tar.gz: e60c32da5e5cf45553f9f2163c0764d6ba0653b22d1e1942a28d777e61f81dca8585dd43c24ac9390a89a13ffe9be954bf598f11b0bf0e817555b43d535d399a

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+.rspec
+*.gem

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+rvm:
+  - 2.1.5
+before_install: gem update bundler
+services:
+  - elasticsearch

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in stretchy.gemspec
+gemspec

data/README.md

@@ -0,0 +1,184 @@
+# Stretchy
+[![Build Status](https://travis-ci.org/hired/stretchy.svg?branch=master)](https://travis-ci.org/hired/stretchy)
+
+Stretchy is a query builder for [Elasticsearch](https://www.elastic.co/products/elasticsearch). It helps you quickly construct the JSON to send to Elastic, which can get [rather complicated](http://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html). 
+
+Stretchy is modeled after ActiveRecord's interface and architecture - query objects are immutable and chainable, which makes quickly building the right query and caching the results easy.
+
+Stretchy is *not*:
+
+1. an integration with ActiveModel to help you index your data
+2. a way to manage Elasticsearch configuration
+3. a general-purpose Elasticsearch API client
+
+The first two are very application-specific. For any non-trivial app, the level of customization necessary will have you writing almost everything yourself. The last one is better handled by the [elasticsearch gem](http://www.rubydoc.info/gems/elasticsearch-api/).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'stretchy'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install stretchy
+
+## Usage
+
+Stretchy is still in early development, so it does not yet support the full feature set of the [Elasticsearch API](http://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html). It does support fairly basic queries in an ActiveRecord-ish style.
+
+### Base
+
+```ruby
+query = Stretchy::Query.new(index: 'app_production', type: 'model_name')
+```
+
+From here, you can chain the following query methods:
+
+### Match
+
+```ruby
+query = query.match('welcome to my web site')
+query = query.match('welcome to my web site', field: 'title', operator: 'or')
+```
+
+Performs a full-text search for the given string. `field` and `operator` are optional, and default to `_all` and `and` respectively.
+
+#### Variants
+
+* `not_match` - filters for documents not matching a full-text search
+
+
+### Where
+
+```ruby
+query = query.where(
+  name: 'Exact Name',
+  email: [
+    'exact@email.com',
+    'another.user.with.same.name@email.com'
+  ]
+)
+```
+
+Allows passing a hash of matchable options in `field: [values]` format. If any one of the values matches, that field will be considered matched. All fields must match for a document to be returned. See the [Terms filter](http://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-terms-filter.html) for more details.
+
+If you pass `field: nil`, Stretchy will construct the relevant `not { exists: field }` filter and apply it as expected.
+
+#### Gotcha
+
+Matches _must_ be exact; the values you pass in here are not analyzed by Elasticsearch, while the values stored in the index are (unless you turned analysis off for that field).
+
+#### Variants
+
+* `not_where` - filters for documents *not* matching the criteria
+* `boost_where` - boosts the relevance score for matching documents
+* `boost_not_where` - boosts the relevance score for documents not matching the criteria
+
+### Range
+
+```ruby
+query = query.range(field: 'rating', min: 3, max: 5)
+```
+
+Only documents with the specified field, and within the specified range (inclusive) match. You can also pass in dates and times as ranges. Currently, you must pass both a min and a max value.
+
+#### Variants
+
+* `not_range` - filters for only documents where the field is *outside* the given range
+* `boost_range` - boosts the relevance score for matching documents
+
+### Geo
+
+```ruby
+query = query.geo(field: 'coords', distance: '20mi', lat: 35.0117, lng: 135.7683)
+```
+
+Filters for documents where the specified `geo_point` field is within the given range.
+
+#### Gotcha
+
+The field must be mapped as a `geo_point` field. See [Elasticsearch types](http://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-geo-point-type.html) for more info.
+
+#### Variants
+
+* `not_geo` - filters for documents outside the specified range
+* `boost_geo` - boosts the relevance score for documents based on how far from the given point they are
+
+### Limit and Offset
+
+```ruby
+query = query.limit(20).offset(1000)
+```
+
+Works the same way as ActiveRecord's limit and offset methods.
+
+### Boost Random
+
+```ruby
+query = query.boost_random(user.id, 1.4)
+```
+
+Provides a random-but-deterministic boost to relevance scores. The first parameter is required, and represents the random seed. The second parameter is optional, and represents the weight for the random factor. See [Random Scoring](http://www.elastic.co/guide/en/elasticsearch/guide/master/random-scoring.html) for more details.
+
+### Explain
+
+```ruby
+query = query.explain.results
+```
+
+Provides Elasticsearch explanation results in `query.response` . See [the explain documentation](http://www.elastic.co/guide/en/elasticsearch/reference/1.x/search-explain.html) for more info.
+
+### Response
+
+```ruby
+query.response
+```
+
+Executes the query, returns the raw JSON response from Elasticsearch and caches it. Use this to get at search API data not in the source documents.
+
+### Results
+
+```ruby
+query.results
+```
+
+Executes the query and provides the parsed json for each hit returned by Elasticsearch. 
+
+### Ids
+
+```ruby
+query.ids
+```
+
+Provides only the ids for each hit. If your document ids are numeric (as is the case for most ActiveRecord-integrated documents), they will be converted to integers.
+
+This is somewhat intelligent - if you have already called `results` the ids will be fetched from there, otherwise it will run the search and skip the data-fetch phase in Elasticsearch.
+
+### Total
+
+```ruby
+query.total
+```
+
+Returns the total number of matches returned by the query - not just the current page. Makes plugging into [Kaminari](https://github.com/amatsuda/kaminari) a snap.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release` to create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/stretchy/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,7 @@
+require "bundler/gem_tasks"
+begin
+  require 'rspec/core/rake_task'
+  RSpec::Core::RakeTask.new(:spec)
+  task default: :spec
+rescue LoadError
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "stretchy"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/stretchy/boosts/filter_boost.rb

@@ -0,0 +1,20 @@
+module Stretchy
+  module Boosts
+    class FilterBoost
+
+      DEFAULT_WEIGHT = 1.2
+
+      def initialize(filter:, weight: DEFAULT_WEIGHT)
+        @filter = filter
+        @weight = weight
+      end
+
+      def to_search
+        {
+          filter: @filter.to_search,
+          weight: @weight
+        }
+      end
+    end
+  end
+end

data/lib/stretchy/boosts/geo_boost.rb

@@ -0,0 +1,38 @@
+module Stretchy
+  module Boosts
+    class GeoBoost
+
+      DEFAULTS = {
+        field: 'coords',
+        offset: '10km',
+        scale: '50km',
+        decay: 0.75,
+        weight: 1.2
+      }.freeze
+
+      def initialize(options = {})
+        @field  = options[:field]   || DEFAULTS[:field]
+        @offset = options[:offset]  || DEFAULTS[:offset]
+        @scale  = options[:scale]   || DEFAULTS[:scale]
+        @decay  = options[:decay]   || DEFAULTS[:decay]
+        @weight = options[:weight]  || DEFAULTS[:weight]
+        @lat    = options[:lat]
+        @lng    = options[:lng]
+      end
+
+      def to_search
+        {
+          gauss: {
+            @field => {
+              origin: { lat: @lat, lon: @lng },
+              offset: @offset,
+              scale: @scale,
+              decay: @decay
+            }
+          },
+          weight: @weight
+        }
+      end
+    end
+  end
+end

data/lib/stretchy/boosts/random_boost.rb

@@ -0,0 +1,26 @@
+module Stretchy
+  module Boosts
+    class RandomBoost
+
+      DEFAULT_WEIGHT = 1.2
+
+      # randomizes order (somewhat) consistently per-user
+      # http://www.elastic.co/guide/en/elasticsearch/guide/current/random-scoring.html
+
+      def initialize(seed, weight = DEFAULT_WEIGHT)
+        @seed   = seed
+        @weight = weight
+      end
+
+      def to_search
+        {
+          random_score: {
+            seed: @seed
+          },
+          weight: @weight
+        }
+      end
+
+    end
+  end
+end

data/lib/stretchy/client_actions.rb

@@ -0,0 +1,61 @@
+require 'json'
+module Stretchy
+  module ClientActions
+
+    def self.extended(base)
+      unless base.respond_to?(:client) && base.respond_to?(:index_name)
+        raise "ClientActions requires methods 'client' and 'index_name'"
+      end
+    end
+
+    # used for ensuring a concistent index in specs
+    def refresh
+      client.indices.refresh index: index_name
+    end
+
+    def count
+      client.cat.count(index: index_name).split(' ')[2].to_i
+    end
+
+    def search(type:, body:, fields: nil)
+      options = { index: index_name, type: type, body: body }
+      options[:fields] = fields if fields.is_a?(Array)
+
+      client.search(options)
+    end
+
+    def index(type:, body:, id: nil)
+      id ||= body['id'] || body['_id'] || body[:id] || body[:_id]
+      client.index(index: index_name, type: type, id: id, body: body)
+    end
+
+    def bulk(type:, documents:)
+      requests = documents.flat_map do |document|
+        id = document['id'] || document['_id'] || document[:id] || document[:_id]
+        [
+          { index: { '_index' => index_name, '_type' => type, '_id' => id } },
+          document
+        ]
+      end
+      client.bulk body: requests
+    end
+
+    def exists(_index_name = index_name)
+      client.indices.exists(index: _index_name)
+    end
+    alias :exists? :exists
+
+    def delete(_index_name = index_name)
+      client.indices.delete(index: _index_name) if exists?(_index_name)
+    end
+
+    def create(_index_name = index_name)
+      client.indices.create(index: _index_name) unless exists?(_index_name)
+    end
+
+    def mapping(_index_name, _type, _body)
+      client.indices.put_mapping(index: _index_name, type: _type, body: _body)
+    end
+
+  end
+end

data/lib/stretchy/configuration.rb

@@ -0,0 +1,34 @@
+module Stretchy
+  module Configuration
+    
+    attr_accessor :index_name, :logger, :url, :adapter, :client
+
+    def self.extended(base)
+      base.set_default_configuration
+    end
+
+    def configure
+      yield self
+    end
+
+    def set_default_configuration
+      self.index_name = 'myapp'
+      self.adapter =    :excon
+      self.url =        ENV['ELASTICSEARCH_URL']
+    end
+
+    def client_options
+      Hash[
+        index_name: index_name,
+        log:        !!logger,
+        logger:     logger,
+        adapter:    adapter,
+        url:        url
+      ]
+    end
+
+    def client(options = {})
+      @client ||= Elasticsearch::Client.new(client_options.merge(options))
+    end
+  end
+end

data/lib/stretchy/filters/and_filter.rb

@@ -0,0 +1,17 @@
+module Stretchy
+  module Filters
+    class AndFilter
+
+      def initialize(filters)
+        @filters = Array(filters)
+      end
+
+      def to_search
+        {
+          and: @filters.map(&:to_search)
+        }
+      end
+
+    end
+  end
+end

data/lib/stretchy/filters/bool_filter.rb

@@ -0,0 +1,19 @@
+module Stretchy
+  module Filters
+    class BoolFilter
+      def initialize(must:, must_not:, should: nil)
+        @must     = Array(must)
+        @must_not = Array(must_not)
+        @should   = Array(should)
+      end
+
+      def to_search
+        json = {}
+        json[:must]     = @must.map(&:to_search)      if @must
+        json[:must_not] = @must_not.map(&:to_search)  if @must_not
+        json[:should]   = @should.map(&:to_search)    if @should
+        { bool: json }
+      end
+    end
+  end
+end

data/lib/stretchy/filters/exists_filter.rb

@@ -0,0 +1,20 @@
+module Stretchy
+  module Filters
+    class ExistsFilter
+
+      # CAUTION: this will match empty strings
+      # see http://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-exists-filter.html
+      def initialize(field)
+        @field = field
+      end
+
+      def to_search
+        {
+          exists: {
+            field: @field
+          }
+        }
+      end
+    end
+  end
+end

data/lib/stretchy/filters/geo_filter.rb

@@ -0,0 +1,24 @@
+module Stretchy
+  module Filters
+    class GeoFilter
+      def initialize(field: 'coords', distance: '50km', lat:, lng:)
+        @field    = field
+        @distance = distance
+        @lat      = lat
+        @lng      = lng
+      end
+
+      def to_search
+        {
+          geo_distance: {
+            distance: @distance,
+            @field => {
+              lat: @lat,
+              lon: @lng
+            }
+          }
+        }
+      end
+    end
+  end
+end

data/lib/stretchy/filters/not_filter.rb

@@ -0,0 +1,20 @@
+module Stretchy
+  module Filters
+    class NotFilter
+
+      def initialize(filters)
+        filters = Array(filters)
+
+        if filters.count == 1
+          @filter = filters.first
+        else
+          @filter = AndFilter.new(filters)
+        end
+      end
+
+      def to_search
+        { not: @filter.to_search }
+      end
+    end
+  end
+end

data/lib/stretchy/filters/query_filter.rb

@@ -0,0 +1,16 @@
+module Stretchy
+  module Filters
+    class QueryFilter
+
+      def initialize(query)
+        @query = query
+      end
+
+      def to_search
+        {
+          query: @query.to_search
+        }
+      end
+    end
+  end
+end

data/lib/stretchy/filters/range_filter.rb

@@ -0,0 +1,22 @@
+module Stretchy
+  module Filters
+    class RangeFilter
+      def initialize(field:, min:, max:)
+        @field = field
+        @min   = min
+        @max   = max
+      end
+
+      def to_search
+        range = {}
+        range[:gte] = @min if @min
+        range[:lte] = @max if @max
+        {
+          range: {
+            @field => range
+          }
+        }
+      end
+    end
+  end
+end

data/lib/stretchy/filters/terms_filter.rb

@@ -0,0 +1,19 @@
+module Stretchy
+  module Filters
+    class TermsFilter
+
+      def initialize(field:, values:)
+        @field = field
+        @values = Array(values)
+      end
+
+      def to_search
+        {
+          terms: {
+            @field => @values
+          }
+        }
+      end
+    end
+  end
+end

data/lib/stretchy/null_query.rb

@@ -0,0 +1,30 @@
+module Stretchy
+  class NullQuery
+    def initialize(options = {})
+    end
+
+    def response
+      {}
+    end
+
+    def id_response
+      {}
+    end
+
+    def results
+      []
+    end
+
+    def ids
+      []
+    end
+
+    def shards
+      []
+    end
+
+    def total
+      0
+    end
+  end
+end

data/lib/stretchy/queries/filtered_query.rb

@@ -0,0 +1,18 @@
+module Stretchy
+  module Queries
+    class FilteredQuery
+
+      def initialize(query: nil, filter:)
+        @query  = query
+        @filter = filter
+      end
+
+      def to_search
+        json = {}
+        json[:query]  = @query.to_search  if @query
+        json[:filter] = @filter.to_search if @filter
+        { filtered: json }
+      end
+    end
+  end
+end

data/lib/stretchy/queries/function_score_query.rb

@@ -0,0 +1,70 @@
+module Stretchy
+  module Queries
+    class FunctionScoreQuery
+
+      SCORE_MODES = %w(multiply sum avg first max min)
+      BOOST_MODES = %w(multiply replace sum avg max min)
+
+      def initialize(options = {})
+        @functions  = Array(options[:functions])
+        @query      = options[:query]
+        @filter     = options[:filter]
+        
+        self.class.attributes.map do |field|
+          instance_variable_set("@#{field}", options[field])
+        end
+        validate
+      end
+
+      def self.attributes
+        [:boost, :max_boost, :score_mode, :boost_mode, :min_score]
+      end
+
+      def validate
+        if @query && @filter
+          raise ArgumentError.new("Cannot have both query and filter -- combine using a FilteredQuery")
+        end
+
+        if @boost && !@boost.is_a?(Numeric)
+          raise ArgumentError.new("Boost must be a number - it is the global boost for the whole query")
+        end
+
+        if @max_boost && !@max_boost.is_a?(Numeric)
+          raise ArgumentError.new("Max boost must be a number")
+        end
+
+        if @min_score && !@min_score.is_a?(Numeric)
+          raise ArgumentError.new("min_score must be a number - it is the global boost for the whole query")
+        end
+
+        if @score_mode && !SCORE_MODES.include?(@score_mode)
+          raise ArgumentError.new("Score mode must be one of #{SCORE_MODES.join(', ')}")
+        end
+
+        if @boost_mode && !BOOST_MODES.include?(@boost_mode)
+          raise ArgumentError.new("Score mode must be one of #{BOOST_MODES.join(', ')}")
+        end
+      end
+
+      def to_search
+        json = {}
+        json[:functions]  = @functions.map(&:to_search)
+        if @query
+          json[:query]    = @query.to_search
+        elsif @filter
+          json[:filter]   = @filter.to_search
+        else
+          json[:query]    = Stretchy::Queries::MatchAllQuery.new.to_search
+        end
+
+        self.class.attributes.reduce(json) do |body, field|
+          ivar = instance_variable_get("@#{field}")
+          body[field] = ivar if ivar
+          body
+        end
+
+        { function_score: json }
+      end
+    end
+  end
+end

data/lib/stretchy/queries/match_all_query.rb

@@ -0,0 +1,9 @@
+module Stretchy
+  module Queries
+    class MatchAllQuery
+      def to_search
+        { match_all: {} }
+      end
+    end
+  end
+end

data/lib/stretchy/queries/match_query.rb

@@ -0,0 +1,24 @@
+module Stretchy
+  module Queries
+    class MatchQuery
+
+      def initialize(string, field: '_all', operator: 'and')
+        @field    = field
+        @operator = operator
+        @string   = string
+      end
+
+      def to_search
+        {
+          match: {
+            @field => {
+              query: @string,
+              operator: @operator
+            }
+          }
+        }
+      end
+
+    end
+  end
+end

data/lib/stretchy/query.rb

@@ -0,0 +1,241 @@
+module Stretchy
+  class Query
+
+    DEFAULT_LIMIT = 40
+
+    def initialize(options = {})
+      @offset       = options[:offset]      || 0
+      @limit        = options[:limit]       || DEFAULT_LIMIT
+      @match        = options[:match]
+      @filters      = options[:filters]
+      @not_filters  = options[:not_filters]
+      @boosts       = options[:boosts]
+      @type         = options[:type]        || 'documents'
+      @index        = options[:index]       || Stretchy.index_name
+      @explain      = options[:explain]
+    end
+
+    def clone_with(options)
+      filters     = [@filters, options[:filters], options[:filter]].flatten.compact
+      not_filters = [@not_filters, options[:not_filters], options[:not_filter]].flatten.compact
+      boosts      = [@boosts, options[:boosts], options[:boost]].flatten.compact
+
+      self.class.new(
+        type:         @type,
+        index:        @index,
+        explain:      options[:explain] || @explain,
+        offset:       options[:offset]  || @offset,
+        limit:        options[:limit]   || @limit,
+        match:        options[:match]   || @match,
+        filters:      filters,
+        not_filters:  not_filters,
+        boosts:       boosts
+      )
+    end
+
+    def offset(num)
+      clone_with(offset: num)
+    end
+
+    def limit(num)
+      clone_with(limit: num)
+    end
+
+    def explain
+      clone_with(explain: true)
+    end
+
+    def where(options = {})
+      return self if options.empty?
+      filters, not_filters = where_clause(options)
+      clone_with(filters: filters, not_filters: not_filters)
+    end
+
+    def not_where(options = {})
+      return self if options.empty?
+      # reverse the order returned here, since we're doing not_where
+      not_filters, filters = where_clause(options)
+      clone_with(filters: filters, not_filters: not_filters)
+    end
+
+    def boost_where(options = {})
+      return self if options.empty?
+      weight = options.delete(:weight) || 1.2
+
+      boosts = options.map do |field, values|
+        filter = nil
+        if values.nil?
+          filter = Filters::NotFilter.new(Filters::ExistsFilter.new(field))
+        else
+          filter = Filters::TermsFilter.new(field: field, values: Array(values))
+        end
+        Boosts::FilterBoost.new(filter: filter, weight: weight)
+      end
+      clone_with(boosts: boosts)
+    end
+
+    def boost_not_where(options = {})
+      return self if options.empty?
+      weight = options.delete(:weight) || 1.2
+
+      boosts = []
+      options.each do |field, values|
+        filter = nil
+        if values.nil?
+          filter = Filters::ExistsFilter.new(field)
+        elsif values.is_a?(Array)
+          filter = NotFilter.new(Filters::TermsFilter.new(field: field, values: Array(values)))
+        end
+        Boosts::FilterBoost.new(filter: filter)
+      end
+      clone_with(boosts: boosts)
+    end
+
+    def range(field:, min: nil, max: nil)
+      return self unless min || max
+      clone_with(filter: Filters::RangeFilter.new(
+        field: field,
+        min: min,
+        max: max
+      ))
+    end
+
+    def not_range(field:, min: nil, max: nil)
+      return self unless min || max
+      clone_with(not_filter: Filters::RangeFilter.new(
+        field: field,
+        min: min,
+        max: max
+      ))
+    end
+
+    def boost_range(field:, min: nil, max: nil, weight: 1.2)
+      return self unless min || max
+      clone_with(boost: Boosts::Boost.new(
+        filter: Filters::RangeFilter.new(
+          field: field,
+          min: min,
+          max: max
+        ),
+        weight: weight
+      ))
+    end
+
+    def geo(field: 'coords', distance: '50km', lat:, lng:)
+      clone_with(filter: Filters::GeoFilter.new(
+        field: field,
+        distance: distance,
+        lat: lat,
+        lng: lng
+      ))
+    end
+
+    def not_geo(field: 'coords', distance: '50km', lat:, lng:)
+      clone_with(not_filter: Filters::GeoFilter.new(
+        field: field,
+        distance: distance,
+        lat: lat,
+        lng: lng
+      ))
+    end
+
+    def boost_geo(options = {})
+      return self if options.empty?
+      clone_with(boost: Boosts::GeoBoost.new(options))
+    end
+
+    def match(string, options = {})
+      return self if string.empty?
+      field     = options[:field] || '_all'
+      operator  = options[:operator] || 'and'
+      clone_with(match: Queries::MatchQuery.new(string, field: field, operator: operator))
+    end
+
+    def not_match(string, options = {})
+      field = options[:field] || '_all'
+      operator = options[:operator] || 'and'
+      clone_with(not_filter: Filters::QueryFilter.new(
+        Queries::MatchQuery.new(string, field: field, operator: operator)
+      ))
+    end
+
+    def boost_random(seed)
+      clone_with(boost: Boosts::RandomBoost.new(seed))
+    end
+
+    def request
+      @request ||= RequestBody.new(
+        match:        @match,
+        filters:      @filters,
+        not_filters:  @not_filters,
+        boosts:       @boosts,
+        limit:        @limit,
+        offset:       @offset,
+        explain:      @explain
+      )
+    end
+
+    def response
+      @response = Stretchy.search(type: @type, body: request.to_search)
+      # caution: huuuuge logs, but pretty helpful
+      # Rails.logger.debug(Colorize.purple(JSON.pretty_generate(@response)))
+      @response
+    end
+
+    def id_response
+      @id_response ||= Stretchy.search(type: @type, body: request.to_search, fields: [])
+      # caution: huuuuge logs, but pretty helpful
+      # Rails.logger.debug(Colorize.purple(JSON.pretty_generate(@id_response)))
+      @id_response
+    end
+
+    def results
+      @results ||= response['hits']['hits'].map do |hit|
+        hit['_source'].merge(
+          '_id' => hit['_id'],
+          '_type' => hit['_type'],
+          '_index' => hit['_index']
+        )
+      end
+    end
+
+    def ids
+      @ids ||= result_metadata('hits', 'hits').map do |hit| 
+        hit['_id'].to_i == 0 ? hit['_id'] : hit['_id'].to_i
+      end
+    end
+
+    def shards
+      @shards ||= result_metadata('shards')
+    end
+
+    def total
+      @total  ||= result_metadata('hits', 'total')
+    end
+
+    private
+      def result_metadata(*args)
+        if @response
+          args.reduce(@response){|json, field| json.nil? ? nil : json[field] }
+        else
+          args.reduce(id_response){|json, field| json.nil? ? nil : json[field] }
+        end
+      end
+
+      def where_clause(options = {})
+        return [[], []] if options.empty?
+        filters = []
+        not_filters = []
+
+        options.each do |field, values|
+          if values.nil?
+            not_filters << Filters::ExistsFilter.new(field)
+          else
+            filters << Filters::TermsFilter.new(field: field, values: Array(values))
+          end
+        end
+        [filters, not_filters]
+      end
+
+  end
+end

data/lib/stretchy/request_body.rb

@@ -0,0 +1,67 @@
+module Stretchy
+  class RequestBody
+
+    def initialize(options = {})
+      @json         = {}
+      @match        = options[:match]
+      @filters      = Array(options[:filters])
+      @not_filters  = Array(options[:not_filters])
+      @boosts       = Array(options[:boosts])
+      @offset       = options[:offset]            || 0
+      @limit        = options[:limit]             || Query::DEFAULT_LIMIT
+      @explain      = options[:explain]
+    end
+
+    def to_search
+      return @json unless @json.empty?
+      
+      query = @match || Queries::MatchAllQuery.new
+
+      if @filters.any? && @not_filters.any?
+        query = Queries::FilteredQuery.new(
+          query: query,
+          filter: Filters::BoolFilter.new(
+            must: @filters,
+            must_not: @not_filters
+          )
+        )
+      elsif @filters.any?
+        if @filters.count == 1
+          query = Queries::FilteredQuery.new(
+            query: query,
+            filter: @filters.first
+          )
+        else
+          query = Queries::FilteredQuery.new(
+            query: query,
+            filter: Filters::AndFilter.new(@filters)
+          )
+        end
+      elsif @not_filters.any?
+        query = Queries::FilteredQuery.new(
+          query: query,
+          filter: Filters::NotFilter.new(@not_filters)
+        )
+      end
+
+      if @boosts.any?
+        query = Queries::FunctionScoreQuery.new(
+          query: query,
+          functions: @boosts,
+          score_mode: 'sum',
+          boost_mode: 'max'
+        )
+      end
+
+      @json = {}
+      @json[:query]   = query.to_search
+      @json[:from]    = @offset
+      @json[:size]    = @limit
+      @json[:explain] = @explain if @explain
+
+      # not a ton of output, usually worth having
+      # puts "Generated elastic query: #{JSON.pretty_generate(@json)}"
+      @json
+    end
+  end
+end

data/lib/stretchy/version.rb

@@ -0,0 +1,3 @@
+module Stretchy
+  VERSION = "0.1.1"
+end

data/lib/stretchy.rb

@@ -0,0 +1,14 @@
+require 'json'
+require 'logger'
+require 'excon'
+require 'elasticsearch'
+
+Dir[File.join(File.dirname(__FILE__), 'stretchy', '**', '*.rb')].each do |path|
+  require path
+end
+
+module Stretchy
+  extend Configuration
+  extend ClientActions
+
+end

data/stretchy.gemspec

@@ -0,0 +1,29 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'stretchy/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "stretchy"
+  spec.version       = Stretchy::VERSION
+  spec.authors       = ["agius"]
+  spec.email         = ["andrew@atevans.com"]
+  spec.licenses      = ['MIT']
+
+  spec.summary       = %q{Query builder for Elasticsearch}
+  spec.description   = %q{Build queries for Elasticsearch with a chainable interface like ActiveRecord's.}
+  spec.homepage      = "https://github.com/hired/stretchy"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "elasticsearch",  "~> 1.0"
+  spec.add_dependency "excon",          "~> 0.45"
+
+  spec.add_development_dependency "bundler",  "~> 1.8"
+  spec.add_development_dependency "rake",     "~> 10.0"
+  spec.add_development_dependency "rspec",    "~> 3.2"
+  spec.add_development_dependency "fuubar",   "~> 2.0"
+end

metadata

@@ -0,0 +1,158 @@
+--- !ruby/object:Gem::Specification
+name: stretchy
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- agius
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2015-04-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: elasticsearch
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: excon
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.45'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.45'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: fuubar
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: Build queries for Elasticsearch with a chainable interface like ActiveRecord's.
+email:
+- andrew@atevans.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- Gemfile
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/stretchy.rb
+- lib/stretchy/boosts/filter_boost.rb
+- lib/stretchy/boosts/geo_boost.rb
+- lib/stretchy/boosts/random_boost.rb
+- lib/stretchy/client_actions.rb
+- lib/stretchy/configuration.rb
+- lib/stretchy/filters/and_filter.rb
+- lib/stretchy/filters/bool_filter.rb
+- lib/stretchy/filters/exists_filter.rb
+- lib/stretchy/filters/geo_filter.rb
+- lib/stretchy/filters/not_filter.rb
+- lib/stretchy/filters/query_filter.rb
+- lib/stretchy/filters/range_filter.rb
+- lib/stretchy/filters/terms_filter.rb
+- lib/stretchy/null_query.rb
+- lib/stretchy/queries/filtered_query.rb
+- lib/stretchy/queries/function_score_query.rb
+- lib/stretchy/queries/match_all_query.rb
+- lib/stretchy/queries/match_query.rb
+- lib/stretchy/query.rb
+- lib/stretchy/request_body.rb
+- lib/stretchy/version.rb
+- stretchy.gemspec
+homepage: https://github.com/hired/stretchy
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Query builder for Elasticsearch
+test_files: []