stretcher 0.0.1 → 1.0.0

data/README.md

@@ -1,6 +1,6 @@
 # Stretcher
 
-A concise, fast,  ElasticSearch client designed to reflect the actual elastic search API as closely as possible, making minimal allowances for convenience.
+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.
 
 # Features
 
@@ -8,14 +8,16 @@ A concise, fast,  ElasticSearch client designed to reflect the actual elastic se
 * Efficiently re-uses connections on a per-server object basis (via net/http/persistent)
 * Supports efficient bulk indexing operations
 * Returns most responses in convenient Hashie::Mash form
-* Easily extensible
 * Configurable logging
+* Pure, threadsafe, ruby
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
-    gem 'stretcher'
+```ruby
+gem 'stretcher'
+```
 
 ## Usage
 
@@ -25,15 +27,15 @@ Add this line to your application's Gemfile:
 # First Create a server
 server = Stretcher::Server.new('http://localhost:9200')
 # Delete an index (in case you already have this one)
-server.index('foo').delete rescue nil
+server.index(:foo).delete rescue nil
 # Create an index
-server.index('foo').create(mapping: {tweet: {properties: {text: 'string'}}})
+server.index(:foo).create(mapping: {tweet: {properties: {text: 'string'}}})
 # Add a document
-server.index('foo').type('tweet').put(123, {text: 'Hello'})
+server.index(:foo).type(:tweet).put(123, {text: 'Hello'})
 # Retrieve a document
-server.index('foo').type('tweet').get(123)
+server.index(:foo).type(:tweet).get(123)
 # Perform a search (Returns a Stretcher::SearchResults instance)
-res = server.index('foo').search({size: 12}, {query: {match_all: {}}})
+res = server.index(:foo).search({size: 12}, {query: {match_all: {}}})
 res.class   # Stretcher::SearchResults
 res.total   # => 1
 res.facets  # => nil
@@ -41,7 +43,7 @@ res.results # => [#<Hashie::Mash _id="123" text="Hello">]
 res.raw     # => #<Hashie::Mash ...> Raw JSON from the search
 ```
 
-### MultiSearch
+### Multi Search
     
 ```ruby
 server.index('foo').msearch([{query: {match_all: {}}}])
@@ -52,9 +54,20 @@ server.index('foo').msearch([{query: {match_all: {}}}])
     
 ```ruby
 docs = [{"_type" => "tweet", "_id" => 91011, "text" => "Bulked"}]
-server.index('foo').bulk_index(docs)
+server.index(:foo).bulk_index(docs)
 ```
 
+### 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).
+
+## Running Specs
+
+Running the specs requires an operational Elastic Search server on http://localhost:9200.
+The test suite is not to be trusted, don't count on your indexes staying around!
+
+Specs may be run with `rake spec`
+
 ## Contributing
 
 1. Fork it

data/lib/stretcher/index.rb

@@ -1,5 +1,7 @@
 require 'stretcher/search_results'
 module Stretcher
+  # Represents an Index context in elastic search.
+  # Generally should be instantiated via Server#index(name).
   class Index
     attr_reader :server, :name, :logger
     
@@ -55,7 +57,14 @@ module Stretcher
     def exists?
       @server.http.head(path_uri).status != 404
     end
-
+    
+    # Issues a search with the given query opts and body, both should be hashes
+    # Ex: res = server.index('foo').search({size: 12}, {query: {match_all: {}}})
+    # * es.class   # Stretcher::SearchResults
+    # * res.total   # => 1
+    # * res.facets  # => nil
+    # * res.results # => [#<Hashie::Mash _id="123" text="Hello">]
+    # * res.raw     # => #<Hashie::Mash ...> Raw JSON from the search
     def search(query_opts={}, body=nil)
       uri = path_uri('/_search?' + Util.querify(query_opts))
       logger.info { "Stretcher Search: curl -XGET #{uri} -d '#{body.to_json}'" }

data/lib/stretcher/index_type.rb

@@ -1,5 +1,6 @@
 module Stretcher
-  # Represents an index, but scoped to a specific type
+  # Represents an index  scoped to a specific type.
+  # Generally should be instantiated via Index#type(name).
   class IndexType
     attr_reader :server, :index, :name, :logger
     

data/lib/stretcher/search_results.rb

@@ -1,5 +1,13 @@
 require 'hashie/dash'
 module Stretcher
+  # Conveniently represents elastic search results in a more compact fashion
+  # 
+  # Available properties:
+  # 
+  # * raw : The raw response from elastic search
+  # * 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

data/lib/stretcher/server.rb

@@ -1,7 +1,11 @@
 module Stretcher
   class Server
     attr_reader :uri, :http, :logger
-
+    
+    # Represents a Server context in elastic search.
+    # The options hash takes an optional instance of Logger under :logger.
+    #
+    # Ex: server = Stretcher::Server.new('http://localhost:9200').
     def initialize(uri, options={})
       @uri = uri
 
@@ -81,7 +85,7 @@ module Stretcher
     # Handy way to query the server, returning *only* the body
     # Will raise an exception when the status is not in the 2xx range
     def request(method, *args, &block)
-      logger.info("Stretcher: Issuing Request #{method.upcase}, #{args}")
+      logger.info { "Stretcher: Issuing Request #{method.upcase}, #{args}" }
       res = if block
               http.send(method, *args) do |req|
                 # Elastic search does mostly deal with JSON

data/lib/stretcher/version.rb

@@ -1,3 +1,3 @@
 module Stretcher
-  VERSION = "0.0.1"
+  VERSION = "1.0.0"
 end

data/stretcher.gemspec

@@ -24,5 +24,6 @@ Gem::Specification.new do |gem|
 
   gem.add_development_dependency 'rspec', '>= 2.5.0'
   gem.add_development_dependency 'simplecov'
+  gem.add_development_dependency 'vcr'
   gem.add_development_dependency 'rake'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stretcher
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 1.0.0
   prerelease: 
 platform: ruby
 authors:
@@ -107,6 +107,22 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement