stretcher 1.19.0 → 1.20.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 35a3ec878b9724b7e1bb69573a589796e8fc2cfa
-  data.tar.gz: 156e3e208e02a9d0e5b16412d1608c281f46d38b
+  metadata.gz: 1b5b15a976457a848c084d824c8cb40274ff0ee4
+  data.tar.gz: 9493a22fb07da4788c7a011a7f6bacbc4f7d8a57
 SHA512:
-  metadata.gz: e3b1d5e27fb23612c24f9da8cd48e515f70ce112b9e02c50b7ce4e64fb30865f3084701d53a8d96e99b01fd92771e19bb362ed7f53b9607f014cdfd4570dfe0f
-  data.tar.gz: 23d81d0f467e589ef5de3f16c94e585d534647b4edf6bd75c6c173fd6f1d6e4dbfbb97afdee90408b1876c02b2e6d3b129eeace66bd2a5985bfe347e60b2eda5
+  metadata.gz: e31a69397b930852118068f572bed8f5dfdada0e0b9a8f41b5bbd246f593a350b4b92585ac293d86c3933b09be784922b7491b9f0d4c72fd01c4442cc39b7bd3
+  data.tar.gz: 373a51fd9cbf6859f6925007b2c313f5ae099755dd91edd5f38a17c78542893bdd0f96a5ce57d63b66de67fea2c253a8f0b663b19295d5daa8f9a96940306ee8

data/.travis.yml

@@ -6,10 +6,6 @@ services:
 rvm:
   - 2.0.0
   - 1.9.3
-  - 1.8.7
-  - ree
   - jruby-head
   - jruby-19mode
-  - jruby-18mode
   - rbx-19mode
-  - rbx-18mode

data/README.md

@@ -5,7 +5,7 @@
 [![Code Climate](https://codeclimate.com/github/PoseBiz/stretcher.png)](https://codeclimate.com/github/PoseBiz/stretcher)
 [![Coverage Status](https://coveralls.io/repos/PoseBiz/stretcher/badge.png)](https://coveralls.io/r/PoseBiz/stretcher)
 
-A concise, fast ElasticSearch client designed to reflect the actual elastic search API as closely as possible. Elastic search's API is complex, and mostly documented on the Elastic Search Guide. This client tries to stay out of your way more than others making advanced techniques easier to implement, and making debugging Elastic Search's sometimes cryptic errors easier.
+A concise, fast ElasticSearch Ruby client designed to reflect the actual elastic search API as closely as possible. Elastic search's API is complex, and mostly documented on the Elastic Search Guide. This client tries to stay out of your way more than others making advanced techniques easier to implement, and making debugging Elastic Search's sometimes cryptic errors easier. Stretcher is currently in production use by Pose, Get Satisfaction, Reverb, and many others.
 
 # Features
 
@@ -18,6 +18,7 @@ A concise, fast ElasticSearch client designed to reflect the actual elastic sear
 * Pure, threadsafe, ruby
 * Easily swap HTTP clients via Faraday
 * Tested against Ruby 2.0,1.9,1.8.7, Jruby, and Rubinius
+* [Semantically versioned](http://semver.org/)
 
 ## Installation
 
@@ -29,6 +30,26 @@ gem 'stretcher'
 
 ## Usage
 
+#### Getting Started
+
+1. [Basic Usage](https://github.com/PoseBiz/stretcher#basic-usage)
+1. [Multi Search](https://github.com/PoseBiz/stretcher#multi-search)
+1. [Bulk Indexing](https://github.com/PoseBiz/stretcher#bulk-indexing)
+1. [Percolate](https://github.com/PoseBiz/stretcher#percolate)
+1. [Logging](https://github.com/PoseBiz/stretcher#logging)
+1. [Rails Integration](https://github.com/PoseBiz/stretcher#rails-integration)
+
+#### RDocs
+
+Stretcher Strives to provide adequate documentation for all methods. Many methods not described in the 'Getting Started' section can be found in the [full rdocs](http://rdoc.info/github/PoseBiz/stretcher/master/frames).
+
+* [Stretcher::Server.new.* (Stretcher::Server)](http://rdoc.info/github/PoseBiz/stretcher/master/Stretcher/Server)
+* [Stretcher::Server.new.index(:foo).* (Stretcher::Index)](http://rdoc.info/github/PoseBiz/stretcher/master/Stretcher/Index)
+* [Stretcher::Server.new.index(:foo).type(:bar).* (Stretcher::IndexType)](http://rdoc.info/github/PoseBiz/stretcher/master/Stretcher/IndexType)
+* [Stretcher::Server.new.index(:foo).search (Stretcher::SearchResult)](http://rdoc.info/github/PoseBiz/stretcher/master/Stretcher/SearchResult)
+* [Stretcher::Server.new.index(:foo).alias(:baz).* (Stretcher::Alias)](http://rdoc.info/github/PoseBiz/stretcher/master/Stretcher/Alias)
+* [Stretcher::Server.new.cluster.* (Stretcher::Cluster)](http://rdoc.info/github/PoseBiz/stretcher/master/Stretcher/Cluster)
+
 ### Basic Usage
 
 ```ruby
@@ -47,9 +68,15 @@ server.index(:foo).type(:tweet).get(3)
 res = server.index(:foo).search(size: 12, query: {match_all: {}})
 res.class   # Stretcher::SearchResults
 res.total   # => 30
-res.results # => [#<Hashie::Mash _id="4" text="Hello 4">, ...]
+res.documents # => [#<Hashie::Mash _id="4" text="Hello 4">, ...]
 res.facets  # => nil
 res.raw     # => #<Hashie::Mash ...> Raw JSON from the search
+# use an alias
+alias = server.index(:foo).alias(:my_alias)
+alias.create({ filter: { term: { user_id: 1 } } })
+alias.index_context.search({ query: { match_all: {} } })
+# or get some cluster health information
+server.cluster.health # Hashie::Mash
 ```
 
 ### Block Syntax
@@ -96,10 +123,6 @@ server.index(:foo).type(:foo1).percolate(doc)
 server.index(:foo).delete_percolator_query(query_name)
 ```
 
-### Full Documentation
-
-This README documents only part of stretcher's API. The full documentation for stretcher is available in its [full rdocs](http://rdoc.info/github/PoseBiz/stretcher/master/frames).
-
 ### Logging
 
 Pass in the `:log_level` parameter to set logging verbosity. cURL statements are surfaced at the `:debug` log level. For instance:
@@ -126,11 +149,6 @@ The test suite is not to be trusted, don't count on your indexes staying around!
 
 Specs may be run with `rake spec`
 
-## Used By
-
-* [Pose](http://pose.com)
-* [Get Satisfaction](https://getsatisfaction.com/corp/)
-
 Email or tweet @andrewvc if you'd like to be added to this list!
 
 ## Contributors

data/lib/stretcher.rb

@@ -13,6 +13,8 @@ require 'stretcher/es_component'
 require 'stretcher/server'
 require 'stretcher/index'
 require 'stretcher/index_type'
+require 'stretcher/alias'
+require 'stretcher/cluster'
 require 'stretcher/util'
 
 module Stretcher

data/lib/stretcher/alias.rb

@@ -0,0 +1,63 @@
+module Stretcher
+
+  # Represents an Alias in elastic search.
+  # Generally should be used via Index#alias(name)
+  class Alias < EsComponent
+
+    attr_reader :name
+
+    def initialize(index, name, options = {})
+      @index = index
+      @server = index.server
+      @name = name
+      @logger = options[:logger] || server.logger
+    end
+
+    # Get the index context of this alias (use it as if it was the index
+    # which it represents)
+    #
+    #   my_alias.index_context.search({ query: { match_all: {} } })
+    def index_context
+      @server.index(@name)
+    end
+
+    # Create the alias in elastic search with the given options
+    #
+    #   my_alias.create({ filter: { term: { user_id: 1 } } })
+    def create(options = {})
+      request(:put) do |req|
+        req.body = {
+          actions: [
+            add: options.merge(:alias => @name)
+          ]
+        }
+      end
+    end
+
+    # Delete an alias from elastic search
+    #
+    #   my_alias.delete
+    def delete
+      request(:delete)
+    end
+
+    # Determine whether an alias by this name exists
+    #
+    #   my_alias.exist? # true
+    def exist?
+      request(:get)
+      true
+    rescue Stretcher::RequestError::NotFound
+      false
+    end
+
+    private
+
+    # Full path to this alias
+    def path_uri(path = nil)
+      p = @index.path_uri("_alias/#{@name}")
+      path ? p << "/#{path}" : p
+    end
+
+  end
+end

data/lib/stretcher/cluster.rb

@@ -0,0 +1,26 @@
+module Stretcher
+
+  # Represents a cluster of servers
+  # should be reached typically through Server#cluster
+  class Cluster < EsComponent
+
+    def initialize(server, options = {})
+      @server = server
+      @logger = options[:logger] || server.logger
+    end
+
+    # Get the health of the cluster
+    def health(options = {})
+      request(:get, 'health', options)
+    end
+
+    private
+
+    def path_uri(path = nil)
+      p = @server.path_uri('/_cluster')
+      path ? "#{p}/#{path}" : p
+    end
+
+  end
+
+end

data/lib/stretcher/es_component.rb

@@ -18,7 +18,7 @@ module Stretcher
       response = request(:get, "_search", query_opts) do |req|
         req.body = body
       end
-      SearchResults.new(:raw => response)
+      SearchResults.new(response)
     end
 
     def do_refresh

data/lib/stretcher/index.rb

@@ -22,6 +22,17 @@ module Stretcher
       block ? block.call(t) : t
     end
 
+    # Returns a Stretcher::Alias object for the alias +name+.
+    # Optionally takes a block, which will be passed a single arg with the Alias obj
+    # The block syntax returns the evaluated value of the block
+    #
+    #   my_server.alias('user_1') # Stretcher::Alias
+    #   my_server.alias { |alias| 1 } # 1
+    def alias(name, &block)
+      al = Alias.new(self, name, :logger => logger)
+      block ? block.call(al) : al
+    end
+
     # Given a hash of documents, will bulk index
     #
     #    docs = [{"_type" => "tweet", "_id" => 91011, "text" => "Bulked"}]
@@ -50,8 +61,8 @@ module Stretcher
           index_meta[key] = d.delete(key) if system_fields.include?(key.to_s)
         end
 
-        post_data << (MultiJson.dump({action => index_meta}) + "\n")
-        post_data << (MultiJson.dump(d) + "\n") unless action == :delete
+        post_data << (MultiJson.dump({action => index_meta}) << "\n")
+        post_data << (MultiJson.dump(d) << "\n") unless action == :delete
         post_data
       }
       @server.bulk body, options

data/lib/stretcher/search_results.rb

@@ -8,24 +8,83 @@ module Stretcher
   # * total : The total number of matched docs
   # * facets : the facets hash
   # * results : The hit results with _id merged in to _source
-  class SearchResults < Hashie::Dash
-    property :raw, :required => true
-    property :total
-    property :facets
-    property :results
+  class SearchResults
+    def initialize(raw)
+      @raw_plain = raw
+    end
+    
+    # Returns a plain (string keyed) hash of the raw response
+    def raw_plain
+      @raw_plain
+    end
+
+    # Returns a Hashie::Mash version of the raw response
+    def raw
+      @raw ||= Hashie::Mash.new(@raw_plain)
+    end
+    
+    # Returns the total number of results
+    def total
+      @total ||= raw_plain['hits']['total']
+    end
+
+    def facets
+      @facets ||= raw[:facets]
+    end    
+
+    # DEPRECATED!
+    # Call #documents instead!
+    def results
+      pretty
+    end
+  
+    # Returns a 'prettier' version of elasticsearch results
+    # This will:
+    # 
+    # 1. Return either '_source' or 'fields' as the base of the result
+    # 2. Merge any keys beginning with a '_' into it as well (such as '_score')
+    # 3. Copy the 'highlight' field into '_highlight'
+    #
+    def pretty
+      # This function and its helpers are side-effecty for speed
+      @documents ||= raw[:hits][:hits].map do |hit|
+        doc = extract_source(hit)
+        copy_underscores(hit, doc)
+        copy_highlight(hit, doc)
+        doc
+      end
+    end
+    
+    private
+    
+    def extract_source(hit)
+      # Memoize the key, since it will be uniform across results
+      @doc_key ||= if hit.key?(:_source)
+                     :_source
+                   elsif hit.key?(:fields)
+                     :fields
+                   else
+                     nil
+                   end
+      
+      Hashie::Mash.new(@doc_key ? hit[@doc_key] : Hashie::Mash.new)      
+    end
 
-    def initialize(*args)
-      super
-      self.total = raw.hits.total
-      self.facets = raw.facets
-      self.results = raw.hits.hits.collect do |r|
-        k = ['_source', 'fields'].detect { |k| r.key?(k) }
-        doc = k.nil? ? Hashie::Mash.new : r[k]
-        if r.key?('highlight')
-          doc.merge!({"_highlight" => r['highlight']})
+    def copy_underscores(hit, doc)
+      # Copy underscore keys into the document
+      hit.each do |k,v|
+        if k && k[0] == "_"
+          doc[k] = v
         end
-        doc.merge!({"_id" => r['_id'], "_index" => r['_index'], "_type" => r['_type'], "_score" => r['_score']})
       end
+      doc
+    end
+
+    def copy_highlight(hit, doc)
+      if highlight = hit.key?("highlight")
+        doc[:_highlight] = highlight
+      end
+      doc
     end
   end
 end

data/lib/stretcher/server.rb

@@ -95,6 +95,14 @@ module Stretcher
       block ? block.call(idx) : idx
     end
 
+    # Returns the Stretcher::Cluster for this server
+    # Optionally takes a block, which will be passed a single arg with the
+    # Cluster object.  The block returns the evaluated value of the block.
+    def cluster(&block)
+      cluster = Cluster.new(self, :logger => logger)
+      block ? block.call(cluster) : cluster
+    end
+
     # Perform a raw bulk operation. You probably want to use Stretcher::Index#bulk_index
     # which properly formats a bulk index request.
     def bulk(data, options={})
@@ -129,7 +137,7 @@ module Stretcher
     #    server.msearch(data)
     def msearch(body=[])
       raise ArgumentError, "msearch takes an array!" unless body.is_a?(Array)
-      fmt_body = body.map {|l| MultiJson.dump(l) }.join("\n") + "\n"
+      fmt_body = body.map {|l| MultiJson.dump(l) }.join("\n") << "\n"
 
       res = request(:get, path_uri("/_msearch"), {}, fmt_body)
 
@@ -138,7 +146,7 @@ module Stretcher
         raise RequestError.new(res), "Could not msearch #{errors.inspect}"
       end
 
-      res['responses'].map {|r| SearchResults.new(:raw => r)}
+      res['responses'].map {|r| SearchResults.new(r)}
     end
 
     # Retrieves multiple documents, possibly from multiple indexes

data/lib/stretcher/version.rb

@@ -1,3 +1,3 @@
 module Stretcher
-  VERSION = "1.19.0"
+  VERSION = "1.20.0.beta1"
 end

data/spec/lib/stretcher_alias_spec.rb

@@ -0,0 +1,50 @@
+require 'spec_helper'
+
+describe Stretcher::Alias do
+
+  let(:server) { Stretcher::Server.new(ES_URL, :logger => DEBUG_LOGGER) }
+  let(:index) { server.index(:foo) }
+  let(:my_alias) { index.alias('user-1') }
+
+  before do
+    index.type(:bar).put(1, { message: 'visible', user_id: 1 })
+    index.type(:bar).put(2, { message: 'hidden', user_id: 2 })
+    index.refresh
+  end
+
+  describe 'creating' do
+
+    before do
+      my_alias.create(filter: {
+        term: { user_id: 1 }
+      })
+    end
+
+    it 'should have the alias' do
+      my_alias.should exist
+    end
+
+  end
+
+  describe 'searching' do
+
+    it 'should be able to search with filter' do
+      resp = my_alias.index_context.search(:query => { :match_all => {} })
+      resp.results.map(&:message).should == ['visible']
+    end
+
+  end
+
+  describe 'destroying' do
+
+    before do
+      my_alias.delete
+    end
+
+    it 'should have removed the alias' do
+      my_alias.should_not exist
+    end
+
+  end
+
+end

data/spec/lib/stretcher_cluster_spec.rb

@@ -0,0 +1,17 @@
+require 'spec_helper'
+
+describe Stretcher::Cluster do
+
+  let(:server) { Stretcher::Server.new(ES_URL, :logger => DEBUG_LOGGER) }
+  let(:cluster) { server.cluster }
+
+  describe :health do
+
+    it 'should return the health' do
+      cluster.health.should be_a Hashie::Mash
+      cluster.health.status.should_not be_nil
+    end
+
+  end
+
+end

data/spec/lib/stretcher_index_spec.rb

@@ -4,24 +4,7 @@ describe Stretcher::Index do
   let(:server) {
     Stretcher::Server.new(ES_URL, :logger => DEBUG_LOGGER)
   }
-  let(:index) {
-    i = server.index('foo')
-    begin
-      i.delete
-    rescue Stretcher::RequestError::NotFound
-    end
-    server.refresh
-    i.create({
-      :settings => {
-        :number_of_shards => 1,
-        :number_of_replicas => 0
-      }
-    })
-    # Why do both? Doesn't hurt, and it fixes some races
-    server.refresh
-    i.refresh
-    i
-  }
+  let(:index) { ensure_test_index(server, :foo) }
   let(:corpus) {
     # underscore field that are not system fields should make it through to _source
     [
@@ -104,6 +87,11 @@ describe Stretcher::Index do
     create_tweet_mapping
   end
 
+  it 'should be able to get mapping' do
+    index.get_mapping.should_not be_nil
+    index.get_mapping.foo.should_not be_nil
+  end
+
   it "should retrieve settings properly" do
     index.get_settings['foo']['settings']['index.number_of_shards'].should eq("1")
     index.get_settings['foo']['settings']['index.number_of_replicas'].should eq("0")

data/spec/lib/stretcher_index_type_spec.rb

@@ -2,8 +2,7 @@ require 'spec_helper'
 
 describe Stretcher::IndexType do
   let(:server) { Stretcher::Server.new(ES_URL, :logger => DEBUG_LOGGER) }
-  let(:index) { server.index(:foo) }
-  
+  let(:index) { ensure_test_index(server, :foo) }
   let(:type) {  index.type(:bar) }
 
   it "should be existentially aware" do
@@ -46,8 +45,8 @@ describe Stretcher::IndexType do
 
     it "should add _highlight field to resulting documents when present" do
       res = type.search(:query => {:match => {:message => 'hello'}}, :highlight => {:fields => {:message => {}}})
-      res.results.first.message.should == @doc[:message]
-      res.results.first.should have_key '_highlight'
+      res.pretty.first.message.should == @doc[:message]
+      res.pretty.first.should have_key '_highlight'
     end
   end
 

data/spec/lib/stretcher_search_results_spec.rb

@@ -3,23 +3,24 @@ require 'spec_helper'
 describe Stretcher::SearchResults do
   let(:result) do
     Hashie::Mash.new({
-      'raw' => {
-        'facets' => [],
-        'hits' => {
-          'total' => 1,
-          'hits'  => [{
-            '_score' => 255,
-            '_id' => 2,
-            '_index' => 'index_name',
-            '_type' => 'type_name'
-          }]
-        }
-      }
-    })
+                       'facets' => [],
+                       'hits' => {
+                         'total' => 1,
+                         'hits'  => [{
+                                       '_score' => 255,
+                                       '_id' => 2,
+                                       '_index' => 'index_name',
+                                       '_type' => 'type_name'
+                                     }]
+                       }
+                     })
   end
 
   context 'merges in select keys' do
-    subject(:search_result) { Stretcher::SearchResults.new(result).results.first }
+    subject(:search_result) {
+      Stretcher::SearchResults.new(result).pretty.first
+    }
+    
     its(:_score) { should == 255 }
     its(:_id) { should == 2 }
     its(:_index) { should == 'index_name' }

data/spec/spec_helper.rb

@@ -8,3 +8,22 @@ File.open("test_logs", 'wb') {|f| f.write("")}
 DEBUG_LOGGER = Logger.new('test_logs')
 ES_URL = 'http://localhost:9200'
 require File.expand_path(File.join(File.dirname(__FILE__), %w[.. lib stretcher]))
+
+def ensure_test_index(server, name)
+  i = server.index(name)
+  begin
+    i.delete
+  rescue Stretcher::RequestError::NotFound
+  end
+  server.refresh
+  i.create({
+             :settings => {
+               :number_of_shards => 1,
+               :number_of_replicas => 0
+             }
+           })
+  # Why do both? Doesn't hurt, and it fixes some races
+  server.refresh
+  i.refresh
+  i
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: stretcher
 version: !ruby/object:Gem::Version
-  version: 1.19.0
+  version: 1.20.0.beta1
 platform: ruby
 authors:
 - Andrew Cholakian
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-08-22 00:00:00.000000000 Z
+date: 2013-09-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -179,6 +179,8 @@ files:
 - README.md
 - Rakefile
 - lib/stretcher.rb
+- lib/stretcher/alias.rb
+- lib/stretcher/cluster.rb
 - lib/stretcher/es_component.rb
 - lib/stretcher/index.rb
 - lib/stretcher/index_type.rb
@@ -187,6 +189,8 @@ files:
 - lib/stretcher/server.rb
 - lib/stretcher/util.rb
 - lib/stretcher/version.rb
+- spec/lib/stretcher_alias_spec.rb
+- spec/lib/stretcher_cluster_spec.rb
 - spec/lib/stretcher_index_spec.rb
 - spec/lib/stretcher_index_type_spec.rb
 - spec/lib/stretcher_search_results_spec.rb
@@ -209,9 +213,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - '>'
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.0.2
@@ -220,6 +224,8 @@ specification_version: 4
 summary: The elegant ElasticSearch client, supporting persistent connections, and
   a clean DSL
 test_files:
+- spec/lib/stretcher_alias_spec.rb
+- spec/lib/stretcher_cluster_spec.rb
 - spec/lib/stretcher_index_spec.rb
 - spec/lib/stretcher_index_type_spec.rb
 - spec/lib/stretcher_search_results_spec.rb