elasticsearch-persistence 0.0.0 → 0.0.1

data/lib/elasticsearch/persistence/repository/naming.rb

@@ -0,0 +1,115 @@
+module Elasticsearch
+  module Persistence
+    module Repository
+
+      # Wraps all naming-related features of the repository (index name, the domain object class, etc)
+      #
+      module Naming
+
+        # Get or set the class used to initialize domain objects when deserializing them
+        #
+        def klass name=nil
+          @klass = name || @klass
+        end
+
+        # Set the class used to initialize domain objects when deserializing them
+        #
+        def klass=klass
+          @klass = klass
+        end
+
+        # Get or set the index name used when storing and retrieving documents
+        #
+        def index_name name=nil
+          @index_name = name || @index_name || begin
+            if respond_to?(:host) && host && host.is_a?(Module)
+              self.host.to_s.underscore.gsub(/\//, '-')
+            else
+              self.class.to_s.underscore.gsub(/\//, '-')
+            end
+          end
+        end; alias :index :index_name
+
+        # Set the index name used when storing and retrieving documents
+        #
+        def index_name=(name)
+          @index_name = name
+        end; alias :index= :index_name=
+
+        # Get or set the document type used when storing and retrieving documents
+        #
+        def document_type name=nil
+          @document_type = name || @document_type || (klass ? klass.to_s.underscore : nil)
+        end; alias :type :document_type
+
+        # Set the document type used when storing and retrieving documents
+        #
+        def document_type=(name)
+          @document_type = name
+        end; alias :type= :document_type=
+
+        # Get the Ruby class from the Elasticsearch `_type`
+        #
+        # @example
+        #     repository.__get_klass_from_type 'note'
+        #     => Note
+        #
+        # @return [Class] The class corresponding to the passed type
+        # @raise [NameError] if the class cannot be found
+        #
+        # @api private
+        #
+        def __get_klass_from_type(type)
+          klass = type.classify
+          klass.constantize
+        rescue NameError => e
+          raise NameError, "Attempted to get class '#{klass}' from the '#{type}' type, but no such class can be found."
+        end
+
+        # Get the Elasticsearch `_type` from the Ruby class
+        #
+        # @example
+        #     repository.__get_type_from_class Note
+        #     => "note"
+        #
+        # @return [String] The type corresponding to the passed class
+        #
+        # @api private
+        #
+        def __get_type_from_class(klass)
+          klass.to_s.underscore
+        end
+
+        # Get a document ID from the document (assuming Hash or Hash-like object)
+        #
+        # @example
+        #     repository.__get_id_from_document title: 'Test', id: 'abc123'
+        #     => "abc123"
+        #
+        # @api private
+        #
+        def __get_id_from_document(document)
+          document[:id] || document['id'] || document[:_id] || document['_id']
+        end
+
+        # Extract a document ID from the document (assuming Hash or Hash-like object)
+        #
+        # @note Calling this method will *remove* the `id` or `_id` key from the passed object.
+        #
+        # @example
+        #     options = { title: 'Test', id: 'abc123' }
+        #     repository.__extract_id_from_document options
+        #     # => "abc123"
+        #     options
+        #     # => { title: 'Test' }
+        #
+        # @api private
+        #
+        def __extract_id_from_document(document)
+          document.delete(:id) || document.delete('id') || document.delete(:_id) || document.delete('_id')
+        end
+      end
+
+    end
+  end
+end

data/lib/elasticsearch/persistence/repository/response/results.rb

@@ -0,0 +1,90 @@
+module Elasticsearch
+  module Persistence
+    module Repository
+      module Response # :nodoc:
+
+        # Encapsulates the domain objects and documents returned from Elasticsearch when searching
+        #
+        # Implements `Enumerable` and forwards its methods to the {#results} object.
+        #
+        class Results
+          include Enumerable
+
+          attr_reader :repository
+
+          # @param repository [Elasticsearch::Persistence::Repository::Class] The repository instance
+          # @param response   [Hash]  The full response returned from the Elasticsearch client
+          # @param options    [Hash]  Optional parameters
+          #
+          def initialize(repository, response, options={})
+            @repository = repository
+            @response   = Hashie::Mash.new(response)
+            @options    = options
+          end
+
+          def method_missing(method_name, *arguments, &block)
+            results.respond_to?(method_name) ? results.__send__(method_name, *arguments, &block) : super
+          end
+
+          def respond_to?(method_name, include_private = false)
+            results.respond_to?(method_name) || super
+          end
+
+          # The number of total hits for a query
+          #
+          def total
+            response['hits']['total']
+          end
+
+          # The maximum score for a query
+          #
+          def max_score
+            response['hits']['max_score']
+          end
+
+          # Yields [object, hit] pairs to the block
+          #
+          def each_with_hit(&block)
+            results.zip(response['hits']['hits']).each(&block)
+          end
+
+          # Yields [object, hit] pairs and returns the result
+          #
+          def map_with_hit(&block)
+            results.zip(response['hits']['hits']).map(&block)
+          end
+
+          # Return the collection of domain objects
+          #
+          # @example Iterate over the results
+          #
+          #     results.map { |r| r.attributes[:title] }
+          #     => ["Fox", "Dog"]
+          #
+          # @return [Array]
+          #
+          def results
+            @results ||= response['hits']['hits'].map do |document|
+              repository.deserialize(document.to_hash)
+            end
+          end
+
+          # Access the response returned from Elasticsearch by the client
+          #
+          # @example Access the aggregations in the response
+          #
+          #     results = repository.search query: { match: { title: 'fox dog' } },
+          #                                 aggregations: { titles: { terms: { field: 'title' } } }
+          #     results.response.aggregations.titles.buckets.map { |term| "#{term['key']}: #{term['doc_count']}" }
+          #     # => ["brown: 1", "dog: 1", ...]
+          #
+          # @return [Hashie::Mash]
+          #
+          def response
+            @response
+          end
+        end
+      end
+    end
+  end
+end

data/lib/elasticsearch/persistence/repository/search.rb

@@ -0,0 +1,60 @@
+module Elasticsearch
+  module Persistence
+    module Repository
+
+      # Returns a collection of domain objects by an Elasticsearch query
+      #
+      module Search
+
+        # Returns a collection of domain objects by an Elasticsearch query
+        #
+        # Pass the query either as a string or a Hash-like object
+        #
+        # @example Return objects matching a simple query
+        #
+        #     repository.search('fox or dog')
+        #
+        # @example Return objects matching a query in the Elasticsearch DSL
+        #
+        #    repository.search(query: { match: { title: 'fox dog' } })
+        #
+        # @example Define additional search parameters, such as highlighted excerpts
+        #
+        #    results = repository.search(query: { match: { title: 'fox dog' } }, highlight: { fields: { title: {} } })
+        #     results.map_with_hit { |d,h| h.highlight.title.join }
+        #     # => ["quick brown <em>fox</em>", "fast white <em>dog</em>"]
+        #
+        # @example Perform aggregations as part of the request
+        #
+        #     results = repository.search query: { match: { title: 'fox dog' } },
+        #                                 aggregations: { titles: { terms: { field: 'title' } } }
+        #     results.response.aggregations.titles.buckets.map { |term| "#{term['key']}: #{term['doc_count']}" }
+        #     # => ["brown: 1", "dog: 1", ... ]
+        #
+        # @example Pass additional options to the search request, such as `size`
+        #
+        #     repository.search query: { match: { title: 'fox dog' } }, size: 25
+        #     # GET http://localhost:9200/notes/note/_search
+        #     # > {"query":{"match":{"title":"fox dog"}},"size":25}
+        #
+        # @return [Elasticsearch::Persistence::Repository::Response::Results]
+        #
+        def search(query_or_definition, options={})
+          type = document_type || (klass ? __get_type_from_class(klass) : nil  )
+
+          case
+          when query_or_definition.respond_to?(:to_hash)
+            response = client.search( { index: index_name, type: type, body: query_or_definition.to_hash }.merge(options) )
+          when query_or_definition.is_a?(String)
+            response = client.search( { index: index_name, type: type, q: query_or_definition }.merge(options) )
+          else
+            raise ArgumentError, "[!] Pass the search definition as a Hash-like object or pass the query as a String" +
+                                 " -- #{query_or_definition.class} given."
+          end
+          Response::Results.new(self, response)
+        end
+      end
+
+    end
+  end
+end

data/lib/elasticsearch/persistence/repository/serialize.rb

@@ -0,0 +1,31 @@
+module Elasticsearch
+  module Persistence
+    module Repository
+
+      # Provide serialization and deserialization between Ruby objects and Elasticsearch documents
+      #
+      # Override these methods in your repository class to customize the logic.
+      #
+      module Serialize
+
+        # Serialize the object for storing it in Elasticsearch
+        #
+        # In the default implementation, call the `to_hash` method on the passed object.
+        #
+        def serialize(document)
+          document.to_hash
+        end
+
+        # Deserialize the document retrieved from Elasticsearch into a Ruby object
+        #
+        # Use the `klass` property, if defined, otherwise try to get the class from the document's `_type`.
+        #
+        def deserialize(document)
+          _klass = klass || __get_klass_from_type(document['_type'])
+          _klass.new document['_source']
+        end
+      end
+
+    end
+  end
+end

data/lib/elasticsearch/persistence/repository/store.rb

@@ -0,0 +1,95 @@
+module Elasticsearch
+  module Persistence
+    module Repository
+
+      # Save and delete documents in Elasticsearch
+      #
+      module Store
+
+        # Store the serialized object in Elasticsearch
+        #
+        # @example
+        #     repository.save(myobject)
+        #     => {"_index"=>"...", "_type"=>"...", "_id"=>"...", "_version"=>1, "created"=>true}
+        #
+        # @return {Hash} The response from Elasticsearch
+        #
+        def save(document, options={})
+          serialized = serialize(document)
+          id   = __get_id_from_document(serialized)
+          type = document_type || __get_type_from_class(klass || document.class)
+          client.index( { index: index_name, type: type, id: id, body: serialized }.merge(options) )
+        end
+
+        # Update the serialized object in Elasticsearch with partial data or script
+        #
+        # @example Update the document with partial data
+        #
+        #     repository.update id: 1, title: 'UPDATED',  tags: []
+        #     # => {"_index"=>"...", "_type"=>"...", "_id"=>"1", "_version"=>2}
+        #
+        # @example Update the document with a script
+        #
+        #     repository.update 1, script: 'ctx._source.views += 1'
+        #     # => {"_index"=>"...", "_type"=>"...", "_id"=>"1", "_version"=>3}
+        #
+        # @return {Hash} The response from Elasticsearch
+        #
+        def update(document, options={})
+          case
+            when document.is_a?(String) || document.is_a?(Integer)
+              id = document
+            when document.respond_to?(:to_hash)
+              serialized = document.to_hash
+              id = __extract_id_from_document(serialized)
+            else
+              raise ArgumentError, "Expected a document ID or a Hash-like object, #{document.class} given"
+          end
+
+          type = options.delete(:type) || \
+                 (defined?(serialized) && serialized && serialized.delete(:type)) || \
+                 document_type || \
+                 __get_type_from_class(klass)
+
+          if defined?(serialized) && serialized
+            body = if serialized[:script]
+                       serialized.select { |k, v| [:script, :params, :upsert].include? k }
+                     else
+                       { doc: serialized }
+                   end
+          else
+            body = {}
+            body.update( doc: options.delete(:doc)) if options[:doc]
+            body.update( script: options.delete(:script)) if options[:script]
+            body.update( params: options.delete(:params)) if options[:params]
+            body.update( upsert: options.delete(:upsert)) if options[:upsert]
+          end
+
+          client.update( { index: index_name, type: type, id: id, body: body }.merge(options) )
+        end
+
+        # Remove the serialized object or document with specified ID from Elasticsearch
+        #
+        # @example Remove the document with ID 1
+        #
+        #     repository.delete(1)
+        #     # => {"_index"=>"...", "_type"=>"...", "_id"=>"1", "_version"=>4}
+        #
+        # @return {Hash} The response from Elasticsearch
+        #
+        def delete(document, options={})
+          if document.is_a?(String) || document.is_a?(Integer)
+            id   = document
+            type = document_type || __get_type_from_class(klass)
+          else
+            serialized = serialize(document)
+            id   = __get_id_from_document(serialized)
+            type = document_type || __get_type_from_class(klass || document.class)
+          end
+          client.delete( { index: index_name, type: type, id: id }.merge(options) )
+        end
+      end
+
+    end
+  end
+end

data/lib/elasticsearch/persistence/version.rb

@@ -1,5 +1,5 @@
 module Elasticsearch
   module Persistence
-    VERSION = "0.0.0"
+    VERSION = "0.0.1"
   end
 end

data/test/integration/repository/custom_class_test.rb

@@ -0,0 +1,85 @@
+require 'test_helper'
+
+module Elasticsearch
+  module Persistence
+    class RepositoryCustomClassIntegrationTest < Elasticsearch::Test::IntegrationTestCase
+
+      class ::MyNote
+        attr_reader :attributes
+
+        def initialize(attributes={})
+          @attributes = Hashie::Mash.new(attributes)
+        end
+
+        def method_missing(method_name, *arguments, &block)
+          attributes.respond_to?(method_name) ? attributes.__send__(method_name, *arguments, &block) : super
+        end
+
+        def respond_to?(method_name, include_private=false)
+          attributes.respond_to?(method_name) || super
+        end
+
+        def to_hash
+          @attributes
+        end
+      end
+
+      context "A custom repository class" do
+        setup do
+          class ::MyNotesRepository
+            include Elasticsearch::Persistence::Repository
+
+            klass MyNote
+
+            settings number_of_shards: 1 do
+              mapping do
+                indexes :title, analyzer: 'snowball'
+              end
+            end
+
+            create_index!
+
+            def deserialize(document)
+              klass.new document.merge(document['_source'])
+            end
+          end
+
+          @repository = MyNotesRepository.new
+
+          @repository.client.cluster.health wait_for_status: 'yellow'
+        end
+
+        should "save the object under a correct index and type" do
+          @repository.save MyNote.new(id: '1', title: 'Test')
+          result = @repository.find(1)
+
+          assert_instance_of MyNote, result
+          assert_equal 'Test', result.title
+
+          assert_not_nil Elasticsearch::Persistence.client.get index: 'my_notes_repository',
+                                                               type: 'my_note',
+                                                               id: '1'
+        end
+
+        should "delete the object" do
+          note = MyNote.new id: 1, title: 'Test'
+          @repository.save note
+
+          assert_not_nil @repository.find(1)
+
+          @repository.delete(note)
+          assert_raise(Elasticsearch::Persistence::Repository::DocumentNotFound) { @repository.find(1) }
+        end
+
+        should "retrieve the object via a search query" do
+          note = MyNote.new title: 'Testing'
+          @repository.save note, refresh: true
+
+          results = @repository.search query: { match: { title: 'Test' } }
+          assert_equal 'Testing', results.first.title
+        end
+      end
+
+    end
+  end
+end