elastictastic 0.5.0 → 0.10.2

data/lib/elastictastic/scope.rb

@@ -1,12 +1,12 @@
 require 'hashie'
+require 'elastictastic/search'
 
 module Elastictastic
   class Scope < BasicObject
     attr_reader :clazz, :index
 
-    def initialize(index, clazz, search = Search.new, parent_collection = nil)
-      @index, @clazz, @search, @parent_collection =
-        index, clazz, search, parent_collection
+    def initialize(index, clazz, search = Search.new, parent = nil, routing = nil)
+      @index, @clazz, @search, @parent, @routing = index, clazz, search, parent, routing
     end
 
     def initialize_instance(instance)
@@ -26,6 +26,29 @@ module Elastictastic
       end
     end
 
+    #
+    # Iterate over all documents matching this scope. The underlying mechanism
+    # used differs depending on the construction of this scope:
+    #
+    # * If the scope has a size, documents will be retrieved in a single request
+    # * If the scope has a sort but no size, documents will be retrieved in
+    #   batches using a `query_then_fetch` search. *In this case, it is
+    #   impossible to guarantee a consistent result set if concurrent
+    #   modification is occurring.*
+    # * If the scope has neither a sort nor a size, documents will be retrieved
+    #   in batches using a cursor (search type `scan`). In this case, the result
+    #   set is guaranteed to be consistent even if concurrent modification
+    #   occurs.
+    #
+    # @param (see #find_in_batches)
+    # @option (see #find_in_batches)
+    # @yield [document, hit] Each result is yielded to the block
+    # @yieldparam [Document] document A materialized Document instance
+    # @yieldparam [Hashie::Mash] hit The raw hit from ElasticSearch, wrapped in
+    #   a Hashie::Mash. Useful for extracting metadata, e.g. highlighting
+    # @return [Enumerator] An enumerator, if no block is passed
+    # @see http://www.elasticsearch.org/guide/reference/api/search/search-type.html
+    #
     def find_each(batch_options = {}, &block)
       if block
         find_in_batches(batch_options) { |batch| batch.each(&block) }
@@ -34,6 +57,20 @@ module Elastictastic
       end
     end
 
+    #
+    # Yield batches of documents matching this scope. See #find_each for a
+    # discussion of different strategies for retrieving documents from
+    # ElasticSearch depending on the construction of this scope.
+    #
+    # @option batch_options [Fixnum] :batch_size (Elastictastic.config.default_batch_size)
+    #   How many documents to retrieve from the server in each batch.
+    # @option batch_options [Fixnum] :ttl (60) How long to keep the cursor
+    #   alive, in the case where search is performed with a cursor.
+    # @yield [batch] Once for each batch of hits
+    # @yieldparam [Enumerator] batch An enumerator for this batch of hits.
+    #   The enumerator will yield a materialized Document and a Hashie::Mash wrapping each raw hit.
+    # @return [Enumerator] An enumerator that yields batches, if no block is passed.
+    #
     def find_in_batches(batch_options = {}, &block)
       return ::Enumerator.new(self, :find_in_batches, batch_options) unless block
       if params.key?('size') || params.key?('from')
@@ -73,6 +110,20 @@ module Elastictastic
       scoped({})
     end
 
+    def [](index_or_range)
+      case index_or_range
+      when ::Integer
+        from(index_or_range).size(1).to_a.first
+      when ::Range
+        range_size = index_or_range.last - index_or_range.first
+        range_size += 1 unless index_or_range.exclude_end?
+        from(index_or_range.first).
+          size(range_size)
+      else
+        raise ::ArgumentError, "Expected Integer or Range"
+      end
+    end
+
     def all_facets
       return @all_facets if defined? @all_facets
       populate_counts
@@ -84,10 +135,16 @@ module Elastictastic
         @index,
         @clazz,
         @search.merge(Search.new(params)),
-        @parent_collection
+        @parent,
+        @routing
       )
     end
 
+    #
+    # Destroy all documents in this index.
+    #
+    # @note This will *not* take into account filters or queries in this scope.
+    #
     def destroy_all
       #FIXME support delete-by-query
       ::Elastictastic.client.delete(@index, @clazz.type)
@@ -98,13 +155,40 @@ module Elastictastic
       ::Elastictastic.client.put_mapping(index, type, @clazz.mapping)
     end
 
+    def exists?(id)
+      ::Elastictastic.client.
+        exists?(index, type, id, params_for_find.slice('routing'))
+    end
+
+    #
+    # Look up one or more documents by ID.
+    #
+    # Retrieve one or more Elastictastic documents by ID
+    #
+    # @overload find(*ids)
+    #   Retrieve a single document or a collection of documents
+    #
+    #   @param [String] ids Document IDs
+    #   @return [Elastictastic::BasicDocument,Array] Collection of documents with the given IDs
+    #
+    # @overload find(id)
+    #   Retrieve a single Elastictastic document
+    #   
+    #   @param [String] id ID of the document
+    #   @return [Elastictastic::BasicDocument] The document with that ID, or nil if not found
+    #
+    # @overload find(ids)
+    #   Retrieve a collection of Elastictastic documents by ID. This will
+    #   return an Array even if the ids argument is a one-element Array.
+    #
+    #   @param [Array] ids Document IDs
+    #   @return [Array] Collection of documents with the given IDs
+    #
     def find(*ids)
       #TODO support combining this with other filters/query
       force_array = ::Array === ids.first
       ids = ids.flatten
-      if ::Hash === ids.first
-        find_many_in_many_indices(*ids)
-      elsif ids.length == 1
+      if ids.length == 1
         instance = find_one(ids.first)
         force_array ? [instance] : instance
       else
@@ -128,6 +212,12 @@ module Elastictastic
       RUBY
     end
 
+    def routing(routing)
+      scope = scoped({})
+      scope.routing = routing
+      scope
+    end
+
     def method_missing(method, *args, &block)
       if ::Enumerable.method_defined?(method)
         each.__send__(method, *args, &block)
@@ -142,11 +232,76 @@ module Elastictastic
 
     def inspect
       inspected = "#{@clazz.name}:#{@index.name}"
-      inspected << @search.params.to_json unless @search.params.empty?
+      inspected << ::Elastictastic.json_encode(@search.params) unless @search.params.empty?
       inspected
     end
 
+    #
+    # @private
+    #
+    def response=(response)
+      self.counts = response
+      @materialized_hits = materialize_hits(response['hits']['hits'])
+    end
+
+    #
+    # @private
+    #
+    def counts=(response)
+      @count ||= response['hits']['total']
+      if response['facets']
+        @all_facets ||= ::Hashie::Mash.new(response['facets'])
+      end
+    end
+
+    #
+    # @private
+    #
+    def find_one(id, params = {})
+      data = ::Elastictastic.client.
+        get(index, type, id, params_for_find_one.merge(params.stringify_keys))
+      return nil if data['exists'] == false
+      case data['status']
+      when nil
+        materialize_hit(data)
+      when 404
+        nil
+      end
+    end
+
+    def multi_get_params
+      {
+        '_type' => type,
+        '_index' => @index.name
+      }.tap do |params|
+        params['fields'] = ::Kernel.Array(@search['fields']) if @search['fields']
+        if @routing
+          params['routing'] = @routing
+        elsif @clazz.routing_required?
+          ::Kernel.raise ::Elastictastic::MissingParameter,
+            "Must specify routing parameter to look up #{@clazz.name} by ID"
+        end
+      end
+    end
+
+    def multi_search_headers
+      {'type' => type, 'index' => @index.name}.tap do |params|
+        params['routing'] = @routing if @routing
+      end
+    end
+
+    #
+    # @private
+    #
+    def materialize_hit(hit)
+      @clazz.new.tap do |result|
+        result.parent = @parent if @parent
+        result.elasticsearch_hit = hit
+      end
+    end
+
     protected
+    attr_writer :routing
 
     def search(search_params = {})
       ::Elastictastic.client.search(
@@ -160,9 +315,11 @@ module Elastictastic
     private
 
     def search_all
-      response = search(:search_type => 'query_then_fetch')
-      populate_counts(response)
-      materialize_hits(response['hits']['hits'])
+      return @materialized_hits if defined? @materialized_hits
+      search_params = {:search_type => 'query_then_fetch'}
+      search_params[:routing] = @routing if @routing
+      self.response = search(search_params)
+      @materialized_hits
     end
 
     def search_in_batches(&block)
@@ -170,8 +327,10 @@ module Elastictastic
       scope_with_size = self.size(size)
       begin
         scope = scope_with_size.from(from)
-        response = scope.search(:search_type => 'query_then_fetch')
-        populate_counts(response)
+        params = {:search_type => 'query_then_fetch'}
+        params[:routing] = @routing if @routing
+        response = scope.search(params)
+        self.counts = response
         yield materialize_hits(response['hits']['hits'])
         from += size
         @count ||= scope.count
@@ -184,6 +343,7 @@ module Elastictastic
         :scroll => "#{batch_options[:ttl] || 60}s",
         :size => batch_options[:batch_size] || ::Elastictastic.config.default_batch_size
       }
+      scroll_options[:routing] = @routing if @routing
       scan_response = ::Elastictastic.client.search(
         @index,
         @clazz.type,
@@ -201,51 +361,22 @@ module Elastictastic
       end until response['hits']['hits'].empty?
     end
 
-    def populate_counts(response = nil)
-      response ||= search(:search_type => 'count')
-      @count ||= response['hits']['total']
-      if response['facets']
-        @all_facets ||= ::Hashie::Mash.new(response['facets'])
-      end
+    def populate_counts
+      params = {:search_type => 'count'}
+      params[:routing] = @routing if @routing
+      self.counts = search(params)
     end
 
-    def find_one(id)
-      data = ::Elastictastic.client.get(index, type, id, params_for_find_one)
-      return nil if data['exists'] == false
-      case data['status']
-      when nil
-        materialize_hit(data)
-      when 404
-        nil
-      end
-    end
-
-    def find_many(ids)
+    def find_many(ids, params = {})
       docspec = ids.map do |id|
-        { '_id' => id }.merge!(params_for_find_many)
+        { '_id' => id }.merge!(params_for_find_many).
+          merge!(params.stringify_keys)
       end
       materialize_hits(
         ::Elastictastic.client.mget(docspec, index, type)['docs']
       ).map { |result, hit| result }
     end
 
-    def find_many_in_many_indices(ids_by_index)
-      docs = []
-      ids_by_index.each_pair do |index, ids|
-        ::Kernel.Array(ids).each do |id|
-          docs << doc = {
-            '_id' => id.to_s,
-            '_type' => type,
-            '_index' => index
-          }
-          doc['fields'] = ::Kernel.Array(@search['fields']) if @search['fields']
-        end
-      end
-      materialize_hits(
-        ::Elastictastic.client.mget(docs)['docs']
-      ).map { |result, hit| result }
-    end
-
     def params_for_find_one
       params_for_find.tap do |params|
         params['fields'] &&= params['fields'].join(',')
@@ -259,6 +390,12 @@ module Elastictastic
     def params_for_find
       {}.tap do |params|
         params['fields'] = ::Kernel.Array(@search['fields']) if @search['fields']
+        if @routing
+          params['routing'] = @routing
+        elsif @clazz.routing_required?
+          ::Kernel.raise ::Elastictastic::MissingParameter,
+            "Must specify routing parameter to look up #{@clazz.name} by ID"
+        end
       end
     end
 
@@ -272,12 +409,5 @@ module Elastictastic
         end
       end
     end
-
-    def materialize_hit(hit)
-      @clazz.new.tap do |result|
-        result.parent_collection = @parent_collection if @parent_collection
-        result.elasticsearch_hit = hit
-      end
-    end
   end
 end

data/lib/elastictastic/server_error.rb

@@ -1,6 +1,9 @@
 module Elastictastic
   module ServerError
-    class ServerError < StandardError
+    ERROR_PATTERN = /^([A-Z][A-Za-z]*)(?::\s*)?(.*)$/
+    NESTED_PATTERN = /^.*nested:\s+(.*)$/
+
+    class ServerError < Elastictastic::Error
       attr_accessor :status
     end
 
@@ -10,6 +13,22 @@ module Elastictastic
           const_set(name, error)
         end
       end
+
+      def [](server_message, status = nil)
+        match = ERROR_PATTERN.match(server_message)
+        if match
+          if (nested_match = NESTED_PATTERN.match(match[2]))
+            return self[nested_match[1], status]
+          else
+            clazz = Elastictastic::ServerError.const_get(match[1])
+            error = clazz.new(match[2])
+            error.status = status
+            error
+          end
+        else
+          Elastictastic::ServerError::ServerError.new(server_message)
+        end
+      end
     end
   end
 end