elastomer-client 0.3.1

data/lib/elastomer/client/bulk.rb

@@ -0,0 +1,257 @@
+module Elastomer
+  class Client
+
+    # The `bulk` method can be used in two ways. Without a block the method
+    # will perform an API call, and it requires a bulk request body and
+    # optional request parameters. If given a block, the method will use a
+    # Bulk instance to assemble the operations called in the block into a
+    # bulk request and dispatch it at the end of the block.
+    #
+    # See http://www.elasticsearch.org/guide/reference/api/bulk/
+    #
+    # body   - Request body as a String (required if a block is _not_ given)
+    # params - Optional request parameters as a Hash
+    #   :request_size - Optional maximum request size in bytes
+    #   :action_count - Optional maximum action size
+    # block  - Passed to a Bulk instance which assembles the operations
+    #          into one or more bulk requests.
+    #
+    # Examples
+    #
+    #   bulk( request_body, :index => 'default-index' )
+    #
+    #   bulk( :index => 'default-index' ) do |b|
+    #     b.index( document1 )
+    #     b.index( document2 )
+    #     b.delete( document3 )
+    #     ...
+    #   end
+    #
+    # Returns the response body as a Hash
+    def bulk( body = nil, params = nil )
+      if block_given?
+        params, body = (body || {}), nil
+        yield bulk_obj = Bulk.new(self, params)
+        bulk_obj.call
+
+      else
+        raise 'bulk request body cannot be nil' if body.nil?
+        params ||= {}
+
+        response = self.post '{/index}{/type}/_bulk', params.merge(:body => body, :action => 'bulk')
+        response.body
+      end
+    end
+
+
+    # The Bulk class provides some abstractions and helper methods for working
+    # with the ElasticSearch bulk API command. Instances of the Bulk class
+    # accumulate indexing and delete operations and then issue a single bulk
+    # API request to ElasticSearch. Those operations are then executed by the
+    # cluster.
+    #
+    # A maximum request size can be set. As soon as the size of the request
+    # body hits this threshold, a bulk request will be made to the search
+    # cluster. This happens as operations are added.
+    #
+    # Additionally, a maximum action count can be set. As soon as the number
+    # of actions equals the action count, a bulk request will be made.
+    #
+    # You can also use the `call` method explicitly to send a bulk request
+    # immediately.
+    #
+    class Bulk
+
+      # Create a new bulk client for handling some of the details of
+      # accumulating documents to index and then formatting them properly for
+      # the bulk API command.
+      #
+      # client - Elastomer::Client used for HTTP requests to the server
+      # params - Parameters Hash to pass to the Client#bulk method
+      #   :request_size - the maximum request size in bytes
+      #   :action_count - the maximum number of actions
+      def initialize( client, params = {} )
+        @client  = client
+        @params  = params
+
+        @actions = []
+        @current_request_size = 0
+        @current_action_count = 0
+        self.request_size = params.delete(:request_size)
+        self.action_count = params.delete(:action_count)
+      end
+
+      attr_reader :client, :request_size, :action_count
+
+      # Set the request size in bytes. If the value is nil, then request size
+      # limiting will not be used and a request will only be made when the call
+      # method is called. It is up to the user to ensure that the request does
+      # not exceed ElasticSearch request size limits.
+      #
+      # If the value is a number greater than zero, then actions will be
+      # buffered until the request size is met or exceeded. When this happens a
+      # bulk request is issued, queued actions are cleared, and the response
+      # from ElasticSearch is returned.
+      def request_size=( value )
+        if value.nil?
+          @request_size = nil
+        else
+          @request_size = value.to_i <= 0 ? nil : value.to_i
+        end
+      end
+
+      # Set the action count. If the value is nil, then action count limiting
+      # will not be used and a request will only be made when the call method
+      # is called. It is up to the user to ensure that the request does not
+      # exceed ElasticSearch request size limits.
+      #
+      # If the value is a number greater than zero, then actions will be
+      # buffered until the action count is met. When this happens a bulk
+      # request is issued, queued actions are cleared, and the response from
+      # ElasticSearch is returned.
+      def action_count=(value)
+        if value.nil?
+          @action_count = nil
+        else
+          @action_count = value.to_i <= 0 ? nil : value.to_i
+        end
+      end
+
+      # Add an index action to the list of bulk actions to be performed when
+      # the bulk API call is made. The `_id` of the document cannot be `nil`
+      # or empty. If this is the case then we remove the `_id` and allow
+      # ElasticSearch to generate one.
+      #
+      # document - The document to index as a Hash or JSON encoded String
+      # params   - Parameters for the index action (as a Hash)
+      #
+      # Returns the response from the bulk call if one was made or nil.
+      def index( document, params = {} )
+        unless String === document
+          overrides = from_document(document)
+          params = params.merge overrides
+        end
+        params.delete(:_id) if params[:_id].nil? || params[:_id].to_s.empty?
+
+        add_to_actions({:index => params}, document)
+      end
+      alias :add :index
+
+      # Add a create action to the list of bulk actions to be performed when
+      # the bulk API call is made. The `_id` of the document cannot be `nil`
+      # or empty.
+      #
+      # document - The document to create as a Hash or JSON encoded String
+      # params   - Parameters for the create action (as a Hash)
+      #
+      # Returns the response from the bulk call if one was made or nil.
+      def create( document, params )
+        unless String === document
+          overrides = from_document(document)
+          params = params.merge overrides
+        end
+        params.delete(:_id) if params[:_id].nil? || params[:_id].to_s.empty?
+
+        add_to_actions({:create => params}, document)
+      end
+
+      # Add an update action to the list of bulk actions to be performed when
+      # the bulk API call is made. The `_id` of the document cannot be `nil`
+      # or empty.
+      #
+      # document - The document to update as a Hash or JSON encoded String
+      # params   - Parameters for the update action (as a Hash)
+      #
+      # Returns the response from the bulk call if one was made or nil.
+      def update( document, params )
+        unless String === document
+          overrides = from_document(document)
+          params = params.merge overrides
+        end
+        params.delete(:_id) if params[:_id].nil? || params[:_id].to_s.empty?
+
+        add_to_actions({:update => params}, document)
+      end
+
+      # Add a delete action to the list of bulk actions to be performed when
+      # the bulk API call is made.
+      #
+      # params - Parameters for the delete action (as a Hash)
+      #
+      # Returns the response from the bulk call if one was made or nil.
+      def delete( params )
+        add_to_actions :delete => params
+      end
+
+      # Immediately execute a bulk API call with the currently accumulated
+      # actions. The accumulated actions list will be cleared after the call
+      # has been made.
+      #
+      # If the accumulated actions list is empty then no action is taken.
+      #
+      # Returns the response body Hash.
+      def call
+        return nil if @actions.empty?
+
+        body = @actions.join("\n") + "\n"
+        client.bulk(body, @params)
+      ensure
+        @current_request_size = 0
+        @current_action_count = 0
+        @actions.clear
+      end
+
+      # Internal: Extract special keys for bulk indexing from the given
+      # `document`. The keys and their values are returned as a Hash from this
+      # method. If a value is `nil` then it will be ignored.
+      #
+      # document - The document Hash
+      #
+      # Returns extracted key/value pairs as a Hash.
+      def from_document( document )
+        opts = {}
+
+        %w[_id _type _index _version _version_type _routing _parent _percolator _timestamp _ttl _retry_on_conflict].each do |field|
+          key = field.to_sym
+          opts[key] = document.delete field if document[field]
+          opts[key] = document.delete key   if document[key]
+        end
+
+        opts
+      end
+
+      # Internal: Add the given `action` to the list of actions that will be
+      # performed by this bulk request. An optional `document` can also be
+      # given.
+      #
+      # If the total size of the accumulated actions meets our desired request
+      # size, then a bulk API call will be performed. After the call the
+      # actions list is cleared and we'll start accumulating actions again.
+      #
+      # action   - The bulk action (as a Hash) to perform
+      # document - Optional document for the action as a Hash or JSON encoded String
+      #
+      # Returns the response from the bulk call if one was made or nil.
+      def add_to_actions( action, document = nil )
+        action = MultiJson.dump action
+        @actions << action
+        @current_request_size += action.bytesize
+        @current_action_count += 1
+
+        unless document.nil?
+          document = MultiJson.dump document unless String === document
+          @actions << document
+          @current_request_size += document.bytesize
+        end
+
+        if (request_size && @current_request_size >= request_size) ||
+           (action_count && @current_action_count >= action_count)
+          call
+        else
+          nil
+        end
+      end
+
+    end  # Bulk
+  end  # Client
+end  # Elastomer

data/lib/elastomer/client/cluster.rb

@@ -0,0 +1,208 @@
+module Elastomer
+  class Client
+
+    # Returns a Cluster instance.
+    def cluster
+      @cluster ||= Cluster.new self
+    end
+
+    class Cluster
+
+      # Create a new cluster client for making API requests that pertain to
+      # the cluster health and management.
+      #
+      # client - Elastomer::Client used for HTTP requests to the server
+      #
+      def initialize( client )
+        @client = client
+      end
+
+      attr_reader :client
+
+      # Simple status on the health of the cluster.
+      # See http://www.elasticsearch.org/guide/reference/api/admin-cluster-health/
+      #
+      # params - Parameters Hash
+      #
+      # Returns the response as a Hash
+      def health( params = {} )
+        response = client.get '/_cluster/health{/index}', params.merge(:action => 'cluster.health')
+        response.body
+      end
+
+      # Comprehensive state information of the whole cluster.
+      # See http://www.elasticsearch.org/guide/reference/api/admin-cluster-state/
+      #
+      # params - Parameters Hash
+      #
+      # Returns the response as a Hash
+      def state( params = {} )
+        response = client.get '/_cluster/state', params.merge(:action => 'cluster.state')
+        response.body
+      end
+
+      # Cluster wide settings that have been modified via the update API.
+      # See http://www.elasticsearch.org/guide/reference/api/admin-cluster-update-settings/
+      #
+      # params - Parameters Hash
+      #
+      # Returns the response as a Hash
+      def get_settings( params = {} )
+        response = client.get '/_cluster/settings', params.merge(:action => 'cluster.get_settings')
+        response.body
+      end
+      alias :settings :get_settings
+
+      # Update cluster wide specific settings. Settings updated can either be
+      # persistent (applied cross restarts) or transient (will not survive a
+      # full cluster restart).
+      #
+      # See http://www.elasticsearch.org/guide/reference/api/admin-cluster-update-settings/
+      #
+      # body   - The new settings as a Hash or a JSON encoded String
+      # params - Parameters Hash
+      #
+      # Returns the response as a Hash
+      def update_settings( body, params = {} )
+        response = client.put '/_cluster/settings', params.merge(:body => body, :action => 'cluster.update_settings')
+        response.body
+      end
+
+      # Explicitly execute a cluster reroute allocation command. For example,
+      # a shard can be moved from one node to another explicitly, an
+      # allocation can be canceled, or an unassigned shard can be explicitly
+      # allocated on a specific node.
+      #
+      # See http://www.elasticsearch.org/guide/reference/api/admin-cluster-reroute/
+      #
+      # commands - A command Hash or an Array of command Hashes
+      # params   - Parameters Hash
+      #
+      # Examples
+      #
+      #   reroute(:move => { :index => 'test', :shard => 0, :from_node => 'node1', :to_node => 'node2' })
+      #
+      #   reroute([
+      #     { :move     => { :index => 'test', :shard => 0, :from_node => 'node1', :to_node => 'node2' }},
+      #     { :allocate => { :index => 'test', :shard => 1, :node => 'node3' }}
+      #   ])
+      #
+      # Returns the response as a Hash
+      def reroute( commands, params = {} )
+        commands = [commands] unless Array === commands
+        body = {:commands => commands}
+
+        response = client.post '/_cluster/reroute', params.merge(:body => body, :action => 'cluster.reroute')
+        response.body
+      end
+
+      # Shutdown the entire cluster.
+      # See http://www.elasticsearch.org/guide/reference/api/admin-cluster-nodes-shutdown/
+      #
+      # params - Parameters Hash
+      #
+      # Returns the response as a Hash
+      def shutdown( params = {} )
+        response = client.post '/_shutdown', params.merge(:action => 'cluster.shutdown')
+        response.body
+      end
+
+      # Retrieve the current aliases. An :index name can be given (or an
+      # array of index names) to get just the aliases for those indexes. You
+      # can also use the alias name here since it is acting the part of an
+      # index.
+      #
+      # See http://www.elasticsearch.org/guide/reference/api/admin-indices-aliases/
+      #
+      # params - Parameters Hash
+      #
+      # Examples
+      #
+      #   get_aliases
+      #   get_aliases( :index => 'users' )
+      #
+      # Returns the response body as a Hash
+      def get_aliases( params = {} )
+        response = client.get '{/index}/_aliases', params.merge(:action => 'cluster.get_aliases')
+        response.body
+      end
+      alias :aliases :get_aliases
+
+      # Perform an aliases action on the cluster. We are just a teensy bit
+      # clever here in that a single action can be given or an array of
+      # actions. This API method will wrap the request in the appropriate
+      # {:actions => [...]} body construct.
+      #
+      # See http://www.elasticsearch.org/guide/reference/api/admin-indices-aliases/
+      #
+      # actions - An action Hash or an Array of action Hashes
+      # params  - Parameters Hash
+      #
+      # Examples
+      #
+      #   update_aliases(:add => { :index => 'users-1', :alias => 'users' })
+      #
+      #   update_aliases([
+      #     { :remove => { :index => 'users-1', :alias => 'users' }},
+      #     { :add    => { :index => 'users-2', :alias => 'users' }}
+      #   ])
+      #
+      # Returns the response body as a Hash
+      def update_aliases( actions, params = {} )
+        if actions.is_a?(Hash) && actions.key?(:actions)
+          body = actions
+        elsif actions.is_a?(Hash)
+          # Array() on a Hash does not do what you think it does - that is why
+          # we are explicitly wrapping the Hash via [actions] here.
+          body = {:actions => [actions]}
+        else
+          body = {:actions => Array(actions)}
+        end
+
+        response = client.post '/_aliases', params.merge(:body => body, :action => 'cluster.update_aliases')
+        response.body
+      end
+
+      # List all templates currently defined. This is just a convenience method
+      # around the `state` call that extracts and returns the templates section.
+      #
+      # Returns the template definitions as a Hash
+      def templates
+        h = state(
+          :filter_blocks        => true,
+          :filter_nodes         => true,
+          :filter_routing_table => true
+        )
+        h['metadata']['templates']
+      end
+
+      # List all indices currently defined. This is just a convenience method
+      # around the `state` call that extracts and returns the indices section.
+      #
+      # Returns the indices definitions as a Hash
+      def indices
+        h = state(
+          :filter_blocks        => true,
+          :filter_nodes         => true,
+          :filter_routing_table => true
+        )
+        h['metadata']['indices']
+      end
+
+      # List all nodes currently part of the cluster. This is just a convenience
+      # method around the `state` call that extracts and returns the nodes
+      # section.
+      #
+      # Returns the nodes definitions as a Hash
+      def nodes
+        h = state(
+          :filter_blocks        => true,
+          :filter_metadata      => true,
+          :filter_routing_table => true
+        )
+        h['nodes']
+      end
+
+    end
+  end
+end