elasticsearch-model-queryable 0.1.5

data/lib/elasticsearch/model/response/base.rb

@@ -0,0 +1,44 @@
+module Elasticsearch
+  module Model
+    module Response
+      # Common funtionality for classes in the {Elasticsearch::Model::Response} module
+      #
+      module Base
+        attr_reader :klass, :response
+
+        # @param klass    [Class] The name of the model class
+        # @param response [Hash]  The full response returned from Elasticsearch client
+        # @param options  [Hash]  Optional parameters
+        #
+        def initialize(klass, response, options={})
+          @klass     = klass
+          @response  = response
+        end
+
+        # @abstract Implement this method in specific class
+        #
+        def results
+          raise NotImplemented, "Implement this method in #{klass}"
+        end
+
+        # @abstract Implement this method in specific class
+        #
+        def records
+          raise NotImplemented, "Implement this method in #{klass}"
+        end
+
+        # Returns the total number of hits
+        #
+        def total
+          response.response['hits']['total']
+        end
+
+        # Returns the max_score
+        #
+        def max_score
+          response.response['hits']['max_score']
+        end
+      end
+    end
+  end
+end

data/lib/elasticsearch/model/response/pagination.rb

@@ -0,0 +1,173 @@
+module Elasticsearch
+  module Model
+    module Response
+
+      # Pagination for search results/records
+      #
+      module Pagination
+        # Allow models to be paginated with the "kaminari" gem [https://github.com/amatsuda/kaminari]
+        #
+        module Kaminari
+          def self.included(base)
+            # Include the Kaminari configuration and paging method in response
+            #
+            base.__send__ :include, ::Kaminari::ConfigurationMethods::ClassMethods
+            base.__send__ :include, ::Kaminari::PageScopeMethods
+
+            # Include the Kaminari paging methods in results and records
+            #
+            Elasticsearch::Model::Response::Results.__send__ :include, ::Kaminari::ConfigurationMethods::ClassMethods
+            Elasticsearch::Model::Response::Results.__send__ :include, ::Kaminari::PageScopeMethods
+            Elasticsearch::Model::Response::Records.__send__ :include, ::Kaminari::PageScopeMethods
+
+            Elasticsearch::Model::Response::Results.__send__ :delegate, :limit_value, :offset_value, :total_count, to: :response
+            Elasticsearch::Model::Response::Records.__send__ :delegate, :limit_value, :offset_value, :total_count, to: :response
+
+            base.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+              # Define the `page` Kaminari method
+              #
+              def #{::Kaminari.config.page_method_name}(num=nil)
+                @results  = nil
+                @records  = nil
+                @response = nil
+                @page     = [num.to_i, 1].max
+                @per_page ||= klass.default_per_page
+
+                self.search.definition.update size: @per_page,
+                                              from: @per_page * (@page - 1)
+
+                self
+              end
+            RUBY
+          end
+
+          # Returns the current "limit" (`size`) value
+          #
+          def limit_value
+            case
+              when search.definition[:size]
+                search.definition[:size]
+              else
+                search.klass.default_per_page
+            end
+          end
+
+          # Returns the current "offset" (`from`) value
+          #
+          def offset_value
+            case
+              when search.definition[:from]
+                search.definition[:from]
+              else
+                0
+            end
+          end
+
+          # Set the "limit" (`size`) value
+          #
+          def limit(value)
+            @results  = nil
+            @records  = nil
+            @response = nil
+            @per_page = value
+
+            search.definition.update :size => @per_page
+            search.definition.update :from => @per_page * (@page - 1) if @page
+            self
+          end
+
+          # Set the "offset" (`from`) value
+          #
+          def offset(value)
+            @results  = nil
+            @records  = nil
+            @response = nil
+            @page     = nil
+            search.definition.update :from => value
+            self
+          end
+
+          # Returns the total number of results
+          #
+          def total_count
+            results.total
+          end
+        end
+
+        # Allow models to be paginated with the "will_paginate" gem [https://github.com/mislav/will_paginate]
+        #
+        module WillPaginate
+          def self.included(base)
+            base.__send__ :include, ::WillPaginate::CollectionMethods
+
+            # Include the paging methods in results and records
+            #
+            methods = [:current_page, :offset, :length, :per_page, :total_entries, :total_pages, :previous_page, :next_page, :out_of_bounds?]
+            Elasticsearch::Model::Response::Results.__send__ :delegate, *methods, to: :response
+            Elasticsearch::Model::Response::Records.__send__ :delegate, *methods, to: :response
+          end
+
+          def offset
+            (current_page - 1) * per_page
+          end
+
+          def length
+            search.definition[:size]
+          end
+
+          # Main pagination method
+          #
+          # @example
+          #
+          #     Article.search('foo').paginate(page: 1, per_page: 30)
+          #
+          def paginate(options)
+            page = [options[:page].to_i, 1].max
+            per_page = (options[:per_page] || klass.per_page).to_i
+
+            search.definition.update size: per_page,
+                                     from: (page - 1) * per_page
+            self
+          end
+
+          # Return the current page
+          #
+          def current_page
+            search.definition[:from] / per_page + 1 if search.definition[:from] && per_page
+          end
+
+          # Pagination method
+          #
+          # @example
+          #
+          #     Article.search('foo').page(2)
+          #
+          def page(num)
+            paginate(page: num, per_page: per_page) # shorthand
+          end
+
+          # Return or set the "size" value
+          #
+          # @example
+          #
+          #     Article.search('foo').per_page(15).page(2)
+          #
+          def per_page(num = nil)
+            if num.nil?
+              search.definition[:size]
+            else
+              paginate(page: current_page, per_page: num) # shorthand
+            end
+          end
+
+          # Returns the total number of results
+          #
+          def total_entries
+            results.total
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/elasticsearch/model/response/records.rb

@@ -0,0 +1,69 @@
+module Elasticsearch
+  module Model
+    module Response
+
+      # Encapsulates the collection of records returned from the database
+      #
+      # Implements Enumerable and forwards its methods to the {#records} object,
+      # which is provided by an {Elasticsearch::Model::Adapter::Adapter} implementation.
+      #
+      class Records
+        include Enumerable
+
+        delegate :each, :empty?, :size, :slice, :[], :to_a, :to_ary, to: :records
+
+        include Base
+
+        # @see Base#initialize
+        #
+        def initialize(klass, response, options = {})
+          super
+
+          # Include module provided by the adapter in the singleton class ("metaclass")
+          #
+          adapter = Adapter.from_class(klass)
+          metaclass = class << self; self; end
+          metaclass.__send__ :include, adapter.records_mixin
+
+          self
+        end
+
+        # Returns the hit IDs
+        #
+        def ids
+          response.response["hits"]["hits"].map { |hit| hit["_id"] }
+        end
+
+        # Returns the {Results} collection
+        #
+        def results
+          response.results
+        end
+
+        # Yields [record, hit] pairs to the block
+        #
+        def each_with_hit(&block)
+          records.to_a.zip(results).each(&block)
+        end
+
+        # Yields [record, hit] pairs and returns the result
+        #
+        def map_with_hit(&block)
+          records.to_a.zip(results).map(&block)
+        end
+
+        # Delegate methods to `@records`
+        #
+        def method_missing(method_name, *arguments)
+          records.respond_to?(method_name) ? records.__send__(method_name, *arguments) : super
+        end
+
+        # Respond to methods from `@records`
+        #
+        def respond_to?(method_name, include_private = false)
+          records.respond_to?(method_name) || super
+        end
+      end
+    end
+  end
+end

data/lib/elasticsearch/model/response/result.rb

@@ -0,0 +1,63 @@
+module Elasticsearch
+  module Model
+    module Response
+
+      # Encapsulates the "hit" returned from the Elasticsearch client
+      #
+      # Wraps the raw Hash with in a `Hashie::Mash` instance, providing
+      # access to the Hash properties by calling Ruby methods.
+      #
+      # @see https://github.com/intridea/hashie
+      #
+      class Result
+
+        # @param attributes [Hash] A Hash with document properties
+        #
+        def initialize(attributes={})
+          @result = HashWrapper.new(attributes)
+        end
+
+        # Return document `_id` as `id`
+        #
+        def id
+          @result['_id']
+        end
+
+        # Return document `_type` as `_type`
+        #
+        def type
+          @result['_type']
+        end
+
+        # Delegate methods to `@result` or `@result._source`
+        #
+        def method_missing(name, *arguments)
+          case
+          when name.to_s.end_with?('?')
+            @result.__send__(name, *arguments) || ( @result._source && @result._source.__send__(name, *arguments) )
+          when @result.respond_to?(name)
+            @result.__send__ name, *arguments
+          when @result._source && @result._source.respond_to?(name)
+            @result._source.__send__ name, *arguments
+          else
+            super
+          end
+        end
+
+        # Respond to methods from `@result` or `@result._source`
+        #
+        def respond_to?(method_name, include_private = false)
+          @result.respond_to?(method_name.to_sym) || \
+          @result._source && @result._source.respond_to?(method_name.to_sym) || \
+          super
+        end
+
+        def as_json(options={})
+          @result.as_json(options)
+        end
+
+        # TODO: #to_s, #inspect, with support for Pry
+      end
+    end
+  end
+end

data/lib/elasticsearch/model/response/results.rb

@@ -0,0 +1,31 @@
+module Elasticsearch
+  module Model
+    module Response
+
+      # Encapsulates the collection of documents returned from Elasticsearch
+      #
+      # Implements Enumerable and forwards its methods to the {#results} object.
+      #
+      class Results
+        include Base
+        include Enumerable
+
+        delegate :each, :empty?, :size, :slice, :[], :to_a, :to_ary, to: :results
+
+        # @see Base#initialize
+        #
+        def initialize(klass, response, options={})
+          super
+        end
+
+        # Returns the {Results} collection
+        #
+        def results
+          # TODO: Configurable custom wrapper
+          @results  = response.response['hits']['hits'].map { |hit| Result.new(hit) }
+        end
+
+      end
+    end
+  end
+end

data/lib/elasticsearch/model/response.rb

@@ -0,0 +1,71 @@
+module Elasticsearch
+  module Model
+
+    # Contains modules and classes for wrapping the response from Elasticsearch
+    #
+    module Response
+
+      # Encapsulate the response returned from the Elasticsearch client
+      #
+      # Implements Enumerable and forwards its methods to the {#results} object.
+      #
+      class Response
+        attr_reader :klass, :search, :response,
+                    :took, :timed_out, :shards
+
+        include Enumerable
+
+        delegate :each, :empty?, :size, :slice, :[], :to_ary, to: :results
+
+        def initialize(klass, search, options={})
+          @klass     = klass
+          @search    = search
+        end
+
+        # Returns the Elasticsearch response
+        #
+        # @return [Hash]
+        #
+        def response
+          @response ||= begin
+            HashWrapper.new(search.execute!)
+          end
+        end
+
+        # Returns the collection of "hits" from Elasticsearch
+        #
+        # @return [Results]
+        #
+        def results
+          @results ||= Results.new(klass, self)
+        end
+
+        # Returns the collection of records from the database
+        #
+        # @return [Records]
+        #
+        def records
+          @records ||= Records.new(klass, self)
+        end
+
+        # Returns the "took" time
+        #
+        def took
+          response['took']
+        end
+
+        # Returns whether the response timed out
+        #
+        def timed_out
+          response['timed_out']
+        end
+
+        # Returns the statistics on shards
+        #
+        def shards
+          HashWrapper.new(response['_shards'])
+        end
+      end
+    end
+  end
+end

data/lib/elasticsearch/model/searching.rb

@@ -0,0 +1,107 @@
+module Elasticsearch
+  module Model
+
+    # Contains functionality related to searching.
+    #
+    module Searching
+
+      # Wraps a search request definition
+      #
+      class SearchRequest
+        attr_reader :klass, :definition
+
+        # @param klass [Class] The class of the model
+        # @param query_or_payload [String,Hash,Object] The search request definition
+        #                                              (string, JSON, Hash, or object responding to `to_hash`)
+        # @param options [Hash] Optional parameters to be passed to the Elasticsearch client
+        #
+        def initialize(klass, query_or_payload, options={})
+          @klass   = klass
+
+          __index_name    = options[:index] || klass.index_name
+          __document_type = options[:type]  || klass.document_type
+
+          case
+            # search query: ...
+            when query_or_payload.respond_to?(:to_hash)
+              body = query_or_payload.to_hash
+
+            # search '{ "query" : ... }'
+            when query_or_payload.is_a?(String) && query_or_payload =~ /^\s*{/
+              body = query_or_payload
+
+            # search '...'
+            else
+              q = query_or_payload
+          end
+
+          if body
+            @definition = { index: __index_name, type: __document_type, body: body }.update options
+          else
+            @definition = { index: __index_name, type: __document_type, q: q }.update options
+          end
+        end
+
+        # Performs the request and returns the response from client
+        #
+        # @return [Hash] The response from Elasticsearch
+        #
+        def execute!
+          klass.client.search(@definition)
+        end
+      end
+
+      module ClassMethods
+
+        # Provides a `search` method for the model to easily search within an index/type
+        # corresponding to the model settings.
+        #
+        # @param query_or_payload [String,Hash,Object] The search request definition
+        #                                              (string, JSON, Hash, or object responding to `to_hash`)
+        # @param options [Hash] Optional parameters to be passed to the Elasticsearch client
+        #
+        # @return [Elasticsearch::Model::Response::Response]
+        #
+        # @example Simple search in `Article`
+        #
+        #     Article.search 'foo'
+        #
+        # @example Search using a search definition as a Hash
+        #
+        #     response = Article.search \
+        #                  query: {
+        #                    match: {
+        #                      title: 'foo'
+        #                    }
+        #                  },
+        #                  highlight: {
+        #                    fields: {
+        #                      title: {}
+        #                    }
+        #                  }
+        #
+        #     response.results.first.title
+        #     # => "Foo"
+        #
+        #     response.results.first.highlight.title
+        #     # => ["<em>Foo</em>"]
+        #
+        #     response.records.first.title
+        #     #  Article Load (0.2ms)  SELECT "articles".* FROM "articles" WHERE "articles"."id" IN (1, 3)
+        #     # => "Foo"
+        #
+        # @example Search using a search definition as a JSON string
+        #
+        #     Article.search '{"query" : { "match_all" : {} }}'
+        #
+        def search(query_or_payload, options={})
+          search   = SearchRequest.new(self, query_or_payload, options)
+
+          Response::Response.new(self, search)
+        end
+
+      end
+
+    end
+  end
+end

data/lib/elasticsearch/model/serializing.rb

@@ -0,0 +1,35 @@
+module Elasticsearch
+  module Model
+
+    # Contains functionality for serializing model instances for the client
+    #
+    module Serializing
+
+      module ClassMethods
+      end
+
+      module InstanceMethods
+
+        # Serialize the record as a Hash, to be passed to the client.
+        #
+        # Re-define this method to customize the serialization.
+        #
+        # @return [Hash]
+        #
+        # @example Return the model instance as a Hash
+        #
+        #     Article.first.__elasticsearch__.as_indexed_json
+        #     => {"title"=>"Foo"}
+        #
+        # @see Elasticsearch::Model::Indexing
+        #
+        def as_indexed_json(options={})
+          # TODO: Play with the `MyModel.indexes` method -- reject non-mapped attributes, `:as` options, etc
+          self.as_json(options.merge root: false)
+        end
+
+      end
+
+    end
+  end
+end

data/lib/elasticsearch/model/version.rb

@@ -0,0 +1,5 @@
+module Elasticsearch
+  module Model
+    VERSION = "0.1.5"
+  end
+end