elastomer-client 0.4.1 → 0.5.0

data/lib/elastomer/client/errors.rb

@@ -26,8 +26,10 @@ module Elastomer
 
         when Faraday::Response
           response = args.shift
-          message = Hash === response.body && response.body['error'] || response.body.to_s
           @status = response.status
+          body = response.body
+
+          message = body.is_a?(Hash) && body['error'] || body.to_s
           super message
 
         else
@@ -59,7 +61,7 @@ module Elastomer
           @fatal = true
         end
         attr_writer :fatal
-        alias :fatal? :fatal
+        alias_method :fatal?, :fatal
       end
 
     end  # Error

data/lib/elastomer/client/index.rb

@@ -1,12 +1,17 @@
 module Elastomer
   class Client
 
-    # Provides access to index-level API commands.
+    # Provides access to index-level API commands. An index name is required for
+    # these API calls. If you want to operate on all inidces - flushing all
+    # indices, for example - then you will need to use the "_all" index name.
+    #
+    # You can override the index name for one-off calls by passing in the
+    # desired index name via the `:index` option.
     #
     # name - The name of the index as a String or an Array of names
     #
     # Returns an Index instance.
-    def index( name )
+    def index( name = nil )
       Index.new self, name
     end
 
@@ -19,32 +24,34 @@ module Elastomer
       #
       def initialize( client, name )
         @client = client
-        @name   = @client.assert_param_presence(name, 'index name')
+        @name   = @client.assert_param_presence(name, 'index name') unless name.nil?
       end
 
       attr_reader :client, :name
 
-      # Check for the existence of the index. If a :type option is given, then
+      # Check for the existence of the index. If a `:type` option is given, then
       # we will check for the existence of the document type in the index.
       #
-      # See http://www.elasticsearch.org/guide/reference/api/admin-indices-indices-exists/
-      # and http://www.elasticsearch.org/guide/reference/api/admin-indices-types-exists/
-      #
       # params - Parameters Hash
+      #   :type - optional type mapping as a String
+      #
+      # See http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/indices-exists.html
+      # and http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/indices-types-exists.html
       #
       # Returns true if the index (or type) exists
       def exists?( params = {} )
         response = client.head '/{index}{/type}', update_params(params, :action => 'index.exists')
         response.success?
       end
-      alias :exist? :exists?
+      alias_method :exist?, :exists?
 
       # Create the index.
-      # See http://www.elasticsearch.org/guide/reference/api/admin-indices-create-index/
       #
       # body   - The index settings and mappings as a Hash or a JSON encoded String
       # params - Parameters Hash
       #
+      # See http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/indices-create-index.html
+      #
       # Returns the response body as a Hash
       def create( body, params = {} )
         response = client.post '/{index}', update_params(params, :body => body, :action => 'index.create')
@@ -52,10 +59,11 @@ module Elastomer
       end
 
       # Delete the index.
-      # See http://www.elasticsearch.org/guide/reference/api/admin-indices-delete-index/
       #
       # params - Parameters Hash
       #
+      # See http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/indices-delete-index.html
+      #
       # Returns the response body as a Hash
       def delete( params = {} )
         response = client.delete '/{index}', update_params(params, :action => 'index.delete')
@@ -63,10 +71,11 @@ module Elastomer
       end
 
       # Open the index.
-      # See http://www.elasticsearch.org/guide/reference/api/admin-indices-open-close/
       #
       # params - Parameters Hash
       #
+      # See http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/indices-open-close.html
+      #
       # Returns the response body as a Hash
       def open( params = {} )
         response = client.post '/{index}/_open', update_params(params, :action => 'index.open')
@@ -74,10 +83,11 @@ module Elastomer
       end
 
       # Close the index.
-      # See http://www.elasticsearch.org/guide/reference/api/admin-indices-open-close/
       #
       # params - Parameters Hash
       #
+      # See http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/indices-open-close.html
+      #
       # Returns the response body as a Hash
       def close( params = {} )
         response = client.post '/{index}/_close', update_params(params, :action => 'index.close')
@@ -85,64 +95,69 @@ module Elastomer
       end
 
       # Retrieve the settings for the index.
-      # See http://www.elasticsearch.org/guide/reference/api/admin-indices-get-settings/
       #
       # params - Parameters Hash
       #
+      # See http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/indices-get-settings.html
+      #
       # Returns the response body as a Hash
       def get_settings( params = {} )
         response = client.get '{/index}/_settings', update_params(params, :action => 'index.get_settings')
         response.body
       end
-      alias :settings :get_settings
+      alias_method :settings, :get_settings
 
       # Change specific index level settings in real time.
-      # See http://www.elasticsearch.org/guide/reference/api/admin-indices-update-settings/
       #
       # body   - The index settings as a Hash or a JSON encoded String
       # params - Parameters Hash
       #
+      # See http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/indices-update-settings.html
+      #
       # Returns the response body as a Hash
       def update_settings( body, params = {} )
         response = client.put '{/index}/_settings', update_params(params, :body => body, :action => 'index.update_settings')
         response.body
       end
 
-      # Retrive one or more mappings from the index. To retrieve a specific
-      # mapping provide the name as the :type parameter.
-      #
-      # See http://www.elasticsearch.org/guide/reference/api/admin-indices-get-mapping/
+      # Retrieve one or more mappings from the index. To retrieve a specific
+      # mapping provide the name as the `:type` parameter.
       #
       # params - Parameters Hash
+      #   :type - specific document type as a String or Array of Strings
+      #
+      # See http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/indices-get-mapping.html
       #
       # Returns the response body as a Hash
-      def mapping( params = {} )
-        response = client.get '/{index}{/type}/_mapping', update_params(params, :action => 'index.mapping')
+      def get_mapping( params = {} )
+        response = client.get '/{index}{/type}/_mapping', update_params(params, :action => 'index.get_mapping')
         response.body
       end
+      alias_method :mapping, :get_mapping
 
       # Register specific mapping definition for a specific type.
-      # See http://www.elasticsearch.org/guide/reference/api/admin-indices-put-mapping/
       #
       # type   - Name of the mapping to update as a String
       # body   - The mapping values to update as a Hash or a JSON encoded String
       # params - Parameters Hash
       #
+      # See http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/indices-put-mapping.html
+      #
       # Returns the response body as a Hash
       def update_mapping( type, body, params = {} )
         response = client.put '/{index}/{type}/_mapping', update_params(params, :body => body, :type => type, :action => 'index.update_mapping')
         response.body
       end
-      alias :put_mapping :update_mapping
+      alias_method :put_mapping, :update_mapping
 
       # Delete the mapping identified by `type`. This deletes all documents of
       # that type from the index.
       #
-      # See http://www.elasticsearch.org/guide/reference/api/admin-indices-delete-mapping/
-      #
       # type   - Name of the mapping to update as a String
       # params - Parameters Hash
       #
+      # See http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/indices-delete-mapping.html
+      #
       # Returns the response body as a Hash
       def delete_mapping( type, params = {} )
         response = client.delete '/{index}/{type}', update_params(params, :type => type, :action => 'index.delete_mapping')
@@ -160,7 +175,7 @@ module Elastomer
         response = client.get '/{index}/_aliases', update_params(:action => 'index.get_aliases')
         response.body
       end
-      alias :aliases :get_aliases
+      alias_method :aliases, :get_aliases
 
       # Return the named aliases associated with this index.
       #
@@ -220,11 +235,12 @@ module Elastomer
       end
 
       # Performs the analysis process on a text and return the tokens breakdown of the text.
-      # See http://www.elasticsearch.org/guide/reference/api/admin-indices-analyze/
       #
       # text   - The text to analyze as a String
       # params - Parameters Hash
       #
+      # See http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/indices-analyze.html
+      #
       # Returns the response body as a Hash
       def analyze( text, params = {} )
         response = client.get '{/index}/_analyze', update_params(params, :body => text.to_s, :action => 'index.analyze')
@@ -234,9 +250,10 @@ module Elastomer
       # Explicitly refresh one or more index, making all operations performed
       # since the last refresh available for search.
       #
-      # See http://www.elasticsearch.org/guide/reference/api/admin-indices-refresh/
-      #
       # params - Parameters Hash
+      #   :index - set to "_all" to refresh all indices
+      #
+      # See http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/indices-refresh.html
       #
       # Returns the response body as a Hash
       def refresh( params = {} )
@@ -245,9 +262,11 @@ module Elastomer
       end
 
       # Flush one or more indices to the index storage.
-      # See http://www.elasticsearch.org/guide/reference/api/admin-indices-flush/
       #
       # params - Parameters Hash
+      #   :index - set to "_all" to flush all indices
+      #
+      # See http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/indices-flush.html
       #
       # Returns the response body as a Hash
       def flush( params = {} )
@@ -257,9 +276,11 @@ module Elastomer
 
       # Optimize one or more indices. Optimizing an index allows for faster
       # search operations but can be resource intensive.
-      # See http://www.elasticsearch.org/guide/reference/api/admin-indices-optimize/
       #
       # params - Parameters Hash
+      #   :index - set to "_all" to optimize all indices
+      #
+      # See http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/indices-optimize.html
       #
       # Returns the response body as a Hash
       def optimize( params = {} )
@@ -270,12 +291,13 @@ module Elastomer
       # Deprecated: Explicitly snapshot (backup) one or more indices to the
       # gateway. By default this happens periodically (every 1 second) but the
       # period can be changed or disabled completely.
-      # See http://www.elasticsearch.org/guide/reference/api/admin-indices-gateway-snapshot/
       #
       # This API was removed in ES 1.2.
       #
       # params - Parameters Hash
       #
+      # See http://www.elasticsearch.org/guide/en/elasticsearch/reference/0.90/indices-gateway-snapshot.html
+      #
       # Returns the response body as a Hash
       def snapshot( params = {} )
         response = client.post '{/index}/_gateway/snapshot', update_params(params, :action => 'index.snapshot')
@@ -285,10 +307,10 @@ module Elastomer
       # Provides insight into on-going index shard recoveries. Recovery status
       # may be reported for specific indices, or cluster-wide.
       #
-      # See http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/indices-recovery.html
-      #
       # params - Parameters Hash
       #
+      # See http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/indices-recovery.html
+      #
       # Returns the response body as a Hash
       def recovery( params = {} )
         response = client.get '{/index}/_recovery', update_params(params, :action => 'index.recovery')
@@ -297,9 +319,11 @@ module Elastomer
 
       # Clear caches for one or more indices. Individual caches can be
       # specified with parameters.
-      # See http://www.elasticsearch.org/guide/reference/api/admin-indices-clearcache/
       #
       # params - Parameters Hash
+      #   :index - set to "_all" to clear all index caches
+      #
+      # See http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/indices-clearcache.html
       #
       # Returns the response body as a Hash
       def clear_cache( params = {} )
@@ -309,22 +333,26 @@ module Elastomer
 
       # Retrieve statistics about one or more indices. Specific statistics
       # can be retrieved with parameters.
-      # See http://www.elasticsearch.org/guide/reference/api/admin-indices-stats/
       #
       # params - Parameters Hash
       #
+      # See http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/indices-stats.html
+      #
       # Returns the response body as a Hash
       def stats( params = {} )
         response = client.get '{/index}/_stats', update_params(params, :action => 'index.stats')
         response.body
       end
 
-      # Retrieve the status of one or more indices. Recovery and snapshot
-      # status can be retrieved with parameters.
-      # See http://www.elasticsearch.org/guide/reference/api/admin-indices-status/
+      # Deprecated: Retrieve the status of one or more indices. Recovery and
+      # snapshot status can be retrieved with parameters.
+      #
+      # This API was deprecated in 1.2 and is slated for removal.
       #
       # params - Parameters Hash
       #
+      # See http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/indices-status.html
+      #
       # Returns the response body as a Hash
       def status( params = {} )
         response = client.get '{/index}/_status', update_params(params, :action => 'index.status')
@@ -333,10 +361,11 @@ module Elastomer
 
       # Retrieve low level Lucene segments information for shards of one
       # or more indices.
-      # See http://www.elasticsearch.org/guide/reference/api/admin-indices-segments/
       #
       # params - Parameters Hash
       #
+      # See http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/indices-segments.html
+      #
       # Returns the response body as a Hash
       def segments( params = {} )
         response = client.get '{/index}/_segments', update_params(params, :action => 'index.segments')
@@ -348,6 +377,8 @@ module Elastomer
       #
       # type - The document type as a String
       #
+      # See http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/docs.html
+      #
       # Returns a Docs instance.
       def docs( type = nil )
         client.docs name, type
@@ -372,6 +403,8 @@ module Elastomer
       #     ...
       #   end
       #
+      # See http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/docs-bulk.html
+      #
       # Returns the response body as a Hash
       def bulk( params = {}, &block )
         raise 'a block is required' if block.nil?
@@ -380,8 +413,37 @@ module Elastomer
         client.bulk params, &block
       end
 
-      # Create a new Scan instance for scrolling all results from a `query`.
-      # The Scan will be scoped to the current index.
+      # Create a new Scroller instance for scrolling all results from a `query`.
+      # The Scroller will be scoped to the current index.
+      #
+      # query  - The query to scroll as a Hash or a JSON encoded String
+      # opts   - Options Hash
+      #   :index  - the name of the index to search
+      #   :type   - the document type to search
+      #   :scroll - the keep alive time of the scrolling request (5 minutes by default)
+      #   :size   - the number of documents per shard to fetch per scroll
+      #
+      # Examples
+      #
+      #   scroll = index.scroll('{"query":{"match_all":{}},"sort":{"date":"desc"}}')
+      #   scroll.each_document do |document|
+      #     document['_id']
+      #     document['_source']
+      #   end
+      #
+      # See http://www.elasticsearch.org/guide/en/elasticsearch/guide/current/scan-scroll.html
+      #
+      # Returns a new Scroller instance
+      def scroll( query, opts = {} )
+        opts = {:index => name}.merge opts
+        client.scroll query, opts
+      end
+
+      # Create a new Scroller instance for scanning all results from a `query`.
+      # The Scroller will be scoped to the current index. The Scroller is
+      # configured to use `scan` semantics which are more efficient than a
+      # standard scroll query; the caveat is that the returned documents cannot
+      # be sorted.
       #
       # query  - The query to scan as a Hash or a JSON encoded String
       # opts   - Options Hash
@@ -398,7 +460,9 @@ module Elastomer
       #     document['_source']
       #   end
       #
-      # Returns a new Scan instance
+      # See http://www.elasticsearch.org/guide/en/elasticsearch/guide/current/scan-scroll.html
+      #
+      # Returns a new Scroller instance
       def scan( query, opts = {} )
         opts = {:index => name}.merge opts
         client.scan query, opts
@@ -427,6 +491,8 @@ module Elastomer
       #     ...
       #   end
       #
+      # See http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-multi-search.html
+      #
       # Returns the response body as a Hash
       def multi_search( params = {}, &block )
         raise 'a block is required' if block.nil?
@@ -450,6 +516,8 @@ module Elastomer
       #   index.warmer('warmer1').get
       #   index.warmer('warmer1').delete
       #
+      # See http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/indices-warmers.html
+      #
       # Returns a new Warmer instance
       def warmer( warmer_name )
         client.warmer(name, warmer_name)

data/lib/elastomer/client/multi_search.rb

@@ -44,7 +44,7 @@ module Elastomer
         response.body
       end
     end
-    alias :msearch :multi_search
+    alias_method :msearch, :multi_search
 
     # The MultiSearch class is a helper for accumulating and submitting
     # multi_search API requests. Instances of the MultiSearch class

data/lib/elastomer/client/nodes.rb

@@ -2,12 +2,15 @@
 module Elastomer
   class Client
 
-    # Provides access to node-level API commands.
+    # Provides access to node-level API commands. The default node is set to
+    # nil which target all nodes. You can pass in "_all" (to get the
+    # same effect) or "_local" to target only the current node the client is
+    # connected to. And you can specify an individual node or multiple nodes.
     #
     # node_id - The node ID as a String or an Array of node IDs
     #
     # Returns a Nodes instance.
-    def nodes( node_id = '_all' )
+    def nodes( node_id = nil )
       Nodes.new self, node_id
     end
 
@@ -70,7 +73,9 @@ module Elastomer
         response.body
       end
 
-      # Get the current hot threads on each node in the cluster.
+      # Get the current hot threads on each node in the cluster. The return
+      # value is a human formatted String - i.e. a String with newlines and
+      # other formatting characters suitable for display in a terminal window.
       #
       # params - Parameters Hash
       #   :node_id  - a single node ID or Array of node IDs
@@ -80,7 +85,7 @@ module Elastomer
       #
       # See http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/cluster-nodes-hot-threads.html
       #
-      # Returns the response as a Hash
+      # Returns the response as a String
       def hot_threads( params = {} )
         response = client.get '/_nodes{/node_id}/hot_threads', update_params(params, :action => 'nodes.hot_threads')
         response.body