sequel-elasticsearch 0.3.3 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9fedd83674e13bf3111df6c01a4a7c997e39cfd16906ea9849c5e22ca9944d36
-  data.tar.gz: 3799f9f9eba3821790e96abf8d00016600dc71cb6620c439c6dd82ffb69dd09e
+  metadata.gz: 4b72432bc6c37b866fb0959c07d71b0bb90fa8773ad0006fe65250f62e80b48e
+  data.tar.gz: 7eb98c377331877a870449a1e3c1060504c70eb6e7f7cc9905a0ad767406090e
 SHA512:
-  metadata.gz: 7219a5449f7c7a88f49a71d43ed1cce202e6312ad050cdde494171289aed5ee199628ba7d2cc36b3c28344aff5fdb76a94acea6701cb224cb15062a474aa3994
-  data.tar.gz: 2db11be8b0cb25339a3399325511a992c69591147b9810978aa03cf2c223f97dc10f7217dbb75720ea6ae82bac2a03ec38c8c5b0451e682959b3eacd448253e3
+  metadata.gz: 1de1abc8e613aeaea8f256626b5f20c370e91f8bad909be2b9c76988a08868aed16caab5c10066fe70098984c49bf0c280e10398957d3b277fcf7a36c39c1297
+  data.tar.gz: 40005b30e9552ceed6e2d560e843eeec2666f9dd444c36007581a59bc4a6ab94d293172502daf5ed3068cb8229b6673318182c66fed1d841a40c695c37b4b62e

data/README.md

@@ -42,11 +42,11 @@ Sequel::Model.plugin :elasticsearch
 Or per model:
 
 ```ruby
-Sequel::Model.plugin Sequel::Elasticsearch
+Document.plugin Sequel::Elasticsearch
 
 # or
 
-class Node < Sequel::Model
+class Document < Sequel::Model
   plugin :elasticsearch
 end
 ```
@@ -62,6 +62,49 @@ Sequel::Model.plugin :elasticsearch,
 
 And that's it! Just transact as you normally would, and your records will be created and updated in the Elasticsearch cluster.
 
+### Searching
+
+Your model is now searchable through Elasticsearch. Just pass down a string that's parsable as a [query string query](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html).
+
+```ruby
+Document.es('title:Sequel')
+Document.es('title:Sequel AND body:Elasticsearch')
+```
+
+The result from the `es` method is an enumerable containing `Sequel::Model` instances of your model:
+
+```ruby
+results = Document.es('title:Sequel')
+results.each { |e| p e }
+# Outputs
+# #<Document @values={:id=>1, :title=>"Sequel", :body=>"Document 1"}>
+# #<Document @values={:id=>2, :title=>"Sequel", :body=>"Document 2"}>
+```
+
+The result also contains the meta info about the Elasticsearch query result:
+
+```ruby
+results = Document.es('title:Sequel')
+p results.count # The number of documents included in this result
+p results.total # The total number of documents in the index that matches the search
+p results.timed_out # If the search timed out or not
+p results.took # How long, in miliseconds the search took
+```
+
+You can also use the scroll API to search and fetch large datasets:
+
+```ruby
+# Get a dataset that will stay consistent for 5 minutes and extend that time with 1 minute on every iteration
+scroll = Document.es('test', scroll: '5m')
+p scroll_id # Outputs the scroll_id for this specific scrolling snapshot
+puts "Found #{scroll.count} of #{scroll.total} documents"
+scroll.each { |e| p e }
+while (scroll = Document.es(scroll, scroll: '1m')) && scroll.empty? == false do
+  puts "Found #{scroll.count} of #{scroll.total} documents"
+  scroll.each { |e| p e }
+end
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
@@ -75,7 +118,7 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/jrgns/
 Features that needs to be built:
 
 - [x] An `es` method to search through the data on the cluster.
-- [ ] Let `es` return an enumerator of `Sequel::Model` instances.
+- [x] Let `es` return an enumerator of `Sequel::Model` instances.
 - [ ] A rake task to create or suggest mappings for a table.
 
 ## License

data/_config.yml

@@ -0,0 +1 @@
+theme: jekyll-theme-architect

data/lib/sequel/plugins/elasticsearch.rb

@@ -3,7 +3,16 @@ require 'sequel/plugins/elasticsearch/result'
 
 module Sequel
   module Plugins
+    # The Sequel::Elasticsearch model plugin
+    #
+    # @example Simple usage
+    #
+    #     require 'sequel-elasticsearch'
+    #     Document.plugin Sequel::Elasticsearch
+    #     Document.es('test')
+    #
     module Elasticsearch
+      # Apply the plugin to the specified model
       def self.apply(model, _opts = OPTS)
         model.instance_variable_set(:@elasticsearch_opts, {})
         model.instance_variable_set(:@elasticsearch_index, nil)
@@ -11,6 +20,7 @@ module Sequel
         model
       end
 
+      # Configure the plugin
       def self.configure(model, opts = OPTS)
         model.elasticsearch_opts = opts[:elasticsearch] || {}
         model.elasticsearch_index = (opts[:index] || model.table_name).to_sym
@@ -18,13 +28,21 @@ module Sequel
         model
       end
 
+      # The class methods that will be added to the Sequel::Model
       module ClassMethods
-        attr_accessor :elasticsearch_opts, :elasticsearch_index, :elasticsearch_type
-
+        # The extra options that will be passed to the Elasticsearch client.
+        attr_accessor :elasticsearch_opts
+        # The Elasticsearch index to which the documents will be written.
+        attr_accessor :elasticsearch_index
+        # The Elasticsearch type to which the documents will be written.
+        attr_accessor :elasticsearch_type
+
+        # Return the Elasticsearch client used to communicate with the cluster.
         def es_client
           @es_client = ::Elasticsearch::Client.new elasticsearch_opts
         end
 
+        # Execute a search on the Model's Elasticsearch index without catching Errors.
         def es!(query = '', opts = {})
           opts = {
             index: elasticsearch_index,
@@ -34,10 +52,20 @@ module Sequel
           Result.new es_client.search(opts), self
         end
 
+        # Fetch the next page in a scroll without catching Errors.
+        def scroll!(scroll_id, duration)
+          scroll_id = scroll_id.scroll_id if scroll_id.is_a? Result
+          return nil unless scroll_id
+          Result.new es_client.scroll(scroll_id: scroll_id, scroll: duration), self
+        end
+
+        # Execute a search or a scroll on the Model's Elasticsearch index.
+        # This method is "safe" in that it will catch the more common Errors.
         def es(query = '', opts = {})
-          call_es { es! query, opts }
+          call_es { query.is_a?(Result) ? scroll!(query, opts) : es!(query, opts) }
         end
 
+        # Wrapper method in which error handling is done for Elasticsearch calls.
         def call_es
           yield
         rescue ::Elasticsearch::Transport::Transport::Errors::NotFound, ::Elasticsearch::Transport::Transport::Error => e
@@ -49,34 +77,45 @@ module Sequel
         end
       end
 
+      # The instance methods that will be added to the Sequel::Model
       module InstanceMethods
+        # Sequel::Model after_create hook to add the new record to the Elasticsearch index.
+        # It's "safe" in that it won't raise an error if it fails.
         def after_create
           super
           self.class.call_es { index_document }
         end
 
+        # Sequel::Model after_destroy hook to remove the record from the Elasticsearch index.
+        # It's "safe" in that it won't raise an error if it fails.
         def after_destroy
           super
           self.class.call_es { destroy_document }
         end
 
+        # Sequel::Model after_update hook to update the record in the Elasticsearch index.
+        # It's "safe" in that it won't raise an error if it fails.
         def after_update
           super
           self.class.call_es { index_document }
         end
 
+        # Return the Elasticsearch client used to communicate with the cluster.
         def es_client
           self.class.es_client
         end
 
         private
 
+        # Determine the ID to be used for the document in the Elasticsearch cluster.
+        # It will join the values of a multi field primary key with an underscore.
         def document_id
           doc_id = pk
           doc_id = doc_id.join('_') if doc_id.is_a? Array
           doc_id
         end
 
+        # Determine the complete path to a document (/index/type/id) in the Elasticsearch cluster.
         def document_path
           {
             index: self.class.elasticsearch_index,
@@ -85,12 +124,14 @@ module Sequel
           }
         end
 
+        # Create or update the document on the Elasticsearch cluster.
         def index_document
           params = document_path
           params[:body] = values.each_key { |k| values[k] = values[k].strftime('%FT%T%:z') if values[k].is_a?(Time) }
           es_client.index params
         end
 
+        # Remove the document from the Elasticsearch cluster.
         def destroy_document
           es_client.delete document_path
         end

data/lib/sequel/plugins/elasticsearch/result.rb

@@ -1,38 +1,59 @@
 module Sequel
   module Plugins
     module Elasticsearch
+      # A wrapper around Elasticsearch results to make it behave more like a Sequel Dataset.
       class Result
         include Enumerable
 
-        attr_reader :results, :scroll_id, :total, :took, :timed_out, :model
+        # The original result returned from the Elasticsearch client
+        attr_reader :result
+        # The scroll id, if set, from the result
+        attr_reader :scroll_id
+        # The total number of documents in the Elasticsearch result
+        attr_reader :total
+        # The time, in miliseconds, the Elasticsearch call took to complete
+        attr_reader :took
+        # If the Elasticsearch call timed out or note
+        attr_reader :timed_out
+        # The model class associated with this result
+        attr_reader :model
 
-        def initialize(results, model = nil)
-          return unless results && results['hits']
-          @results = results
-          @scroll_id = results['_scroll_id']
-          @total = results['hits']['total']
-          @timed_out = results['timed_out']
-          @took = results['took']
+        # Initialize the Result
+        #
+        # * +result+ The result returns from the Elasticsearch client / +.es+ call.
+        # * +model+ The model class on which the results should be applied.
+        def initialize(result, model = nil)
+          return unless result && result['hits']
+
+          @result = result
+          @scroll_id = result['_scroll_id']
+          @total = result['hits']['total']
+          @timed_out = result['timed_out']
+          @took = result['took']
           @model = model
+
+          result['hits']['hits'] = result['hits']['hits'].map { |h| convert(h) }
         end
 
+        # Each implementation for the Enumerable. Yield each element in the +result['hits']['hits']+ array.
         def each
-          return [] unless results['hits'] && results['hits']['hits']
-          results['hits']['hits'].each do |h|
-            yield convert(h)
-          end
-          # TODO: Use the scroll id to get more if needed
-          # We will need access to the client, somehow...
+          return [] unless result['hits'] && result['hits']['hits'].count.positive?
+          result['hits']['hits'].each { |h| yield h }
+        end
+
+        # Send all undefined methods to the +result['hits']['hits']+ array.
+        def method_missing(m, *args, &block)
+          respond_to_missing?(m) ? result['hits']['hits'].send(m, *args, &block) : super
         end
 
-        def all
-          results['hits']['hits'].map do |h|
-            convert(h)
-          end
+        # Send all undefined methods to the +result['hits']['hits']+ array.
+        def respond_to_missing?(m, include_private = false)
+          result['hits']['hits'].respond_to?(m, include_private) || super
         end
 
         private
 
+        # Convert an Elasticsearch hit to a Sequel::Model
         def convert(hit)
           return hit unless model
           source = hit['_source'].each_with_object({}) { |(k, v), h| h[k.to_sym] = v }

data/lib/sequel/plugins/elasticsearch/version.rb

@@ -1,5 +1,6 @@
 module Sequel
   module Elasticsearch
-    VERSION = '0.3.3'.freeze
+    # The Gem's version.
+    VERSION = '0.4.0'.freeze
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sequel-elasticsearch
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 0.4.0
 platform: ruby
 authors:
 - Jurgens du Toit
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-02-08 00:00:00.000000000 Z
+date: 2018-02-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: elasticsearch
@@ -139,6 +139,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- _config.yml
 - lib/sequel/plugins/elasticsearch.rb
 - lib/sequel/plugins/elasticsearch/result.rb
 - lib/sequel/plugins/elasticsearch/version.rb