stretchy-model 0.6.5 → 0.7.0

data/lib/stretchy/relation.rb

@@ -3,6 +3,7 @@ module Stretchy
     # It provides methods for querying and manipulating the documents.
     class Relation
 
+
         # These methods cannot be used with the `delete_all` method.
         INVALID_METHODS_FOR_DELETE_ALL = [:limit, :offset]
 
@@ -14,7 +15,6 @@ module Stretchy
                 Relations::SearchOptionMethods, 
                 Delegation
 
-        # Getters.
         attr_reader :klass, :loaded
         alias :model :klass
         alias :loaded? :loaded
@@ -22,10 +22,28 @@ module Stretchy
         # Delegates to the results array.
         delegate :blank?, :empty?, :any?, :many?, to: :results
 
-        # Constructor.
+        # Initialize a new instance of the relation.
+        #
+        # This constructor method is used to create a new instance of the relation. It accepts a class representing the Elasticsearch documents and a hash of initial values for the relation.
+        #
+        # ### Parameters
+        #
+        # - `klass:` The Class representing the Elasticsearch documents.
+        # - `values:` The Hash representing the initial values for the relation (optional).
+        #
+        # ### Returns
+        # Returns a new instance of the relation.
+        #
+        # ---
+        #
+        # ### Examples
+        #
+        # #### Initialize a new relation
+        #
+        # ```ruby
+        #   relation = Relation.new(Model, {name: 'John Doe', age: 30})
+        # ```
         #
-        # @param klass [Class] The class of the Elasticsearch documents.
-        # @param values [Hash] The initial values for the relation.
         def initialize(klass, values={})
             @klass  = klass
             @values = values.merge(default_size: klass.default_size)
@@ -33,54 +51,173 @@ module Stretchy
             @loaded = false
         end
 
-        # Builds a new Elasticsearch document.
+        # Initialize a new instance of the relation.
+        #
+        # This constructor method is used to create a new instance of the relation. It accepts a class representing the Elasticsearch documents and a hash of initial values for the relation.
+        #
+        # ### Parameters
+        #
+        # - `klass:` The Class representing the Elasticsearch documents.
+        # - `values:` The Hash representing the initial values for the relation (optional).
+        #
+        # ### Returns
+        # Returns a new instance of the relation.
+        #
+        # ---
+        #
+        # ### Examples
+        #
+        # #### Initialize a new relation
+        #
+        # ```ruby
+        #   relation = Relation.new(Model, {name: 'John Doe', age: 30})
+        # ```
         #
-        # @param args [Array] The arguments to pass to the document constructor.
-        # @return [Object] The new document.
         def build(*args)
          @klass.new *args
         end
 
         # Returns the results of the relation as an array.
         #
-        # @return [Array] The results of the relation.
-        def to_a
+        # This instance method is used to load the results of the relation and return them as an array. It calls the `load` method to load the results and then returns the `@records` instance variable.
+        #
+        # ### Returns
+        # Returns an Array representing the results of the relation.
+        #
+        # ---
+        #
+        # ### Examples
+        #
+        # #### Get the results of a relation as an array
+        #
+        # ```ruby
+        #   relation = Relation.new(Model, {name: 'John Doe', age: 30})
+        #   results = relation.results
+        # ```
+        #
+        def results
           load
           @records
         end
-        alias :results :to_a
 
+        # _alias for `results`_
+        alias :to_a :results
+
+        # Returns the raw Elasticsearch response for the relation.
+        #
+        # This instance method is used to get the raw Elasticsearch response for the relation. It calls the `results` method to load the results and then returns the `response` property of the results.
+        #
+        # ### Returns
+        # Returns a Hash representing the raw Elasticsearch response for the relation.
+        #
+        # ---
+        #
+        # ### Examples
+        #
+        # #### Get the raw Elasticsearch response for a relation
+        #
+        # ```ruby
+        #   relation = Relation.new(Model, {name: 'John Doe', age: 30})
+        #   raw_response = relation.response
+        # ```
+        #
+        # #### With a model
+        # ```ruby
+        #  relation = Model.where(name: 'John Doe')
+        #  raw_response = relation.response
+        #  #=> {"took"=>3, "timed_out"=>false, "_shards"=>{"total"=>1, "successful"=>1, "skipped"=>0, "failed"=>0}, "hits"=>{"total"=>{"value"=>0, "relation"=>"eq"}, "max_score"=>nil, "hits"=>[]}}
+        # ```
+        #
         def response
           results.response
         end
 
         # Returns the results of the relation as a JSON object.
         #
-        # @param options [Hash] The options to pass to the `as_json` method.
-        # @return [Hash] The results of the relation as a JSON object.
+        # This instance method is used to get the results of the relation as a JSON object. It calls the `as_json` method on the results of the relation and passes any provided options to it.
+        #
+        # ### Parameters
+        #
+        # - `options:` The Hash representing the options to pass to the `as_json` method (optional).
+        #
+        # ### Returns
+        # Returns a Hash representing the results of the relation as a JSON object.
+        #
+        # ---
+        #
+        # ### Examples
+        #
+        # #### Get the results of a relation as a JSON object
+        #
+        # ```ruby
+        #   relation = Relation.new(Model, {name: 'John Doe', age: 30})
+        #   json_results = relation.as_json
+        # ```
+        #
         def as_json(options = nil)
           results.as_json(options)
         end
 
         # Returns the Elasticsearch query for the relation.
         #
-        # @return [Hash] The Elasticsearch query for the relation.
+        # This instance method is used to get the Elasticsearch query for the relation. It calls the `to_elastic` method on the `query_builder` of the relation.
+        #
+        # ### Returns
+        # Returns a Hash representing the Elasticsearch query for the relation.
+        #
+        # ---
+        #
+        # ### Examples
+        #
+        # #### Get the Elasticsearch query for a relation
+        #
+        # ```ruby
+        #   Model.where(flight: 'goat').to_elastic
+        #   #=> {"query"=>{"bool"=>{"must"=>{"term"=>{"flight.keyword"=>"goat"}}}}}
+        # ```
+        #
         def to_elastic
           query_builder.to_elastic
         end
 
         # Creates a new Elasticsearch document.
         #
-        # @param args [Array] The arguments to pass to the document constructor.
-        # @param block [Proc] The block to pass to the document constructor.
-        # @return [Object] The new document.
+        # This instance method is used to create a new Elasticsearch document within the scope of the relation. It accepts a list of arguments and an optional block to pass to the document constructor.
+        #
+        # ### Parameters
+        #
+        # - `*args:` A list of arguments to pass to the document constructor.
+        # - `&block:` An optional block to pass to the document constructor.
+        #
+        # ### Returns
+        # Returns the newly created document.
+        #
+        # ---
+        #
+        # ### Examples
+        #
+        # #### Create a new document within the scope of a relation
+        #
+        # ```ruby
+        #   document = relation.create(name: 'John Doe', age: 30)
+        # ```
+        #
         def create(*args, &block)
            scoping { @klass.create!(*args, &block) }
         end
 
         # Executes a block of code within the scope of the relation.
         #
-        # @yield The block of code to execute.
+        # This instance method is used to execute a block of code within the scope of the relation. It temporarily sets the current scope of the class to this relation, executes the block, and then resets the current scope to its previous value.
+        #
+        # ### Parameters
+        #
+        # - `&block:` The block of code to execute within the scope of the relation.
+        #
+        # ### Returns
+        # Returns the result of the block execution.
+        #
+        #
         def scoping
           previous, klass.current_scope = klass.current_scope, self
           yield
@@ -90,22 +227,41 @@ module Stretchy
 
         # Loads the results of the relation.
         #
-        # @return [Relation] The relation object.
+        # This instance method is used to load the results of the relation. It calls the `exec_queries` method to execute the queries unless the results have already been loaded.
+        #
+        # ### Returns
+        # Returns the relation object itself.
+        #
+        # ---
+        #
+        # ### Examples
+        #
+        # #### Load the results of a relation
+        #
+        # ```ruby
+        #   relation = Model.where(flight: 'goat')
+        #   relation.load
+        # ```
+        #
         def load
           exec_queries unless loaded?
           self
         end
+
+        # _alias for `load`_
         alias :fetch :load
 
-        # Deletes Elasticsearch documents.
-        #
-        # @param opts [Hash] The options for the delete operation.
-        def delete(opts=nil)
+        def delete(opts=nil) #:nodoc:
         end
 
         # Executes the Elasticsearch query for the relation.
         #
-        # @return [Array] The results of the query.
+        # This instance method is used to execute the Elasticsearch query for the relation. It calls the `execute` method on the `query_builder` of the relation and stores the results in the `@records` instance variable.
+        #
+        # ### Returns
+        # Returns an Array representing the results of the query.
+        #
+        #
         def exec_queries
           # Run safety callback
           klass._circuit_breaker_callbacks.each do |cb|
@@ -128,14 +284,44 @@ module Stretchy
 
         # Returns the values of the relation as a hash.
         #
-        # @return [Hash] The values of the relation.
+        # This instance method is used to get the values of the relation as a hash. It converts the `@values` instance variable to a hash and returns it.
+        #
+        # ### Returns
+        # Returns a Hash representing the values of the relation.
+        #
+        # ---
+        #
+        # ### Examples
+        #
+        # #### Get the values of a relation
+        #
+        # ```ruby
+        #   relation = Model.where(flight: 'goat')
+        #   values = relation.values
+        # ```
+        #
         def values
           Hash[@values]
         end
 
-        # Returns a string representation of the relation.
+        #  Returns a string representation of the relation.
+        #
+        # This instance method is used to get a string representation of the relation. It includes information about the total number of results, the maximum number of results, and any aggregations present in the response.
         #
-        # @return [String] The string representation of the relation.
+        # ### Returns
+        # Returns a String representing the relation.
+        #
+        # ---
+        #
+        # ### Examples
+        #
+        # #### Get a string representation of a relation
+        #
+        # ```ruby
+        #   Model.where(flight: 'goat').terms(:flights, field: :flight).inspect
+        #   #=> #<Stretchy::Relation total: 0, max: 0, aggregations: ["flights"]> 
+        # ```
+        # 
         def inspect
           begin
             entries = to_a.results.take([size_value.to_i + 1, 11].compact.min).map!(&:inspect)
@@ -146,7 +332,7 @@ module Stretchy
             message.unshift entries.join(', ') unless entries.size.zero?
             "#<#{self.class.name} #{message.join(', ')}>"
           rescue StandardError => e
-            e
+            Stretchy.logger.error e.message
             raise e
           end
         end
@@ -155,7 +341,22 @@ module Stretchy
 
         # Returns the query builder for the relation.
         #
-        # @return [QueryBuilder] The query builder for the relation.
+        # This private instance method is used to get the query builder for the relation. It creates a new instance of `Relations::QueryBuilder` with the values of the relation and the attribute types of the class.
+        #
+        # ### Returns
+        # Returns a `Relations::QueryBuilder` representing the query builder for the relation.
+        #
+        # ---
+        #
+        # ### Examples
+        #
+        # #### Get the query builder for a relation
+        #
+        # ```ruby
+        #   relation = Model.where(flight: 'goat')
+        #   query_builder = relation.send(:query_builder)
+        # ```
+        #
         def query_builder
           Relations::QueryBuilder.new(values, klass.attribute_types)
         end

data/lib/stretchy/relations/aggregation_methods/aggregation.rb

@@ -0,0 +1,59 @@
+module Stretchy
+  module Relations
+    module AggregationMethods
+      module Aggregation
+        # Adds an aggregation to the query.
+        #
+        # This method is used to add an aggregation to the query. It accepts a name for the aggregation, a hash of options for the aggregation, and an optional block to further configure the aggregation.
+        #
+        # ### Parameters
+        #
+        # - `name:` The Symbol or String representing the name of the aggregation.
+        # - `options:` The Hash representing the options for the aggregation (default: {}).
+        #     - `:field:` The Symbol or String representing the field to aggregate on.
+        #     - `:ranges:` The Array of Hashes representing the ranges for a range aggregation.
+        # - `block:` The Proc representing an optional block to further configure the aggregation.
+        #
+        # ### Returns
+        # Returns a new Stretchy::Relation with the specified aggregation.
+        #
+        # ---
+        #
+        # ### Examples
+        #
+        # #### Single aggregation
+        #
+        # ```ruby
+        #   Model.aggregation(:avg_price, field: :price)
+        # ```
+        #
+        # #### Aggregation with ranges
+        #
+        # ```ruby
+        #   Model.aggregation(:price_ranges) do
+        #     range field: :price, ranges: [{to: 100}, {from: 100, to: 200}, {from: 200}]
+        #   end
+        # ```
+        #
+        # Aggregation results are available in the `aggregations` method of the results under the name provided in the aggregation.
+        #
+        # ```ruby
+        #   results = Model.where(color: :blue).aggregation(:avg_price, field: :price)
+        #   results.aggregations.avg_price
+        # ```
+        #
+        def aggregation(name, options = {}, &block)
+            spawn.aggregation!(name, options, &block)
+        end
+
+        def aggregation!(name, options = {}, &block) # :nodoc:
+            self.aggregation_values += [{name: name, args: options}]
+            self
+        end
+
+        AggregationMethods.register!(:aggregation)
+
+      end
+    end
+  end
+end

data/lib/stretchy/relations/aggregation_methods/avg.rb

@@ -0,0 +1,45 @@
+module Stretchy
+  module Relations
+    module AggregationMethods
+      module Avg
+        # Perform an average aggregation.
+        #
+        # This method is used to calculate the average of a numeric field. It accepts a name for the aggregation and a hash of options for the aggregation.
+        #
+        # ### Parameters
+        #
+        # - `name:` The Symbol or String representing the name of the aggregation.
+        # - `options:` The Hash representing the options for the aggregation (default: {}).
+        #     - `:field:` The Symbol or String representing the field to calculate the average on.
+        # - `aggs:` The Array of Hashes representing nested aggregations (optional).
+        #
+        # ### Returns
+        # Returns a new Stretchy::Relation with the specified average aggregation.
+        #
+        # ---
+        #
+        # ### Examples
+        #
+        # #### Average aggregation
+        #
+        # ```ruby
+        #   Model.avg(:average_price, field: :price)
+        # ```
+        #
+        # Aggregation results are available in the `aggregations` method of the results under the name provided in the aggregation.
+        #
+        # ```ruby
+        #   results = Model.where(color: :blue).avg(:average_price, field: :price)
+        #   results.aggregations.average_price
+        # ```
+        #
+        def avg(name, options = {}, *aggs)
+            options = {avg: options}.merge(*aggs)
+            aggregation(name, options)
+        end
+      
+        AggregationMethods.register!(:avg)
+      end
+    end
+  end
+end

data/lib/stretchy/relations/aggregation_methods/bucket_script.rb

@@ -0,0 +1,47 @@
+module Stretchy
+  module Relations
+    module AggregationMethods
+      module BucketScript
+        # Perform a bucket_script aggregation.
+        #
+        # This method is used to perform computations on the results of other aggregations. It accepts a name for the aggregation, a hash of options for the aggregation, and an optional array of nested aggregations.
+        #
+        # ### Parameters
+        #
+        # - `name:` The Symbol or String representing the name of the aggregation.
+        # - `options:` The Hash representing the options for the aggregation (default: {}).
+        #     - `:buckets_path:` The Hash representing the paths to the buckets on which to perform computations.
+        #     - `:script:` The String representing the script to execute.
+        # - `aggs:` The Array of Hashes representing nested aggregations (optional).
+        #
+        # ### Returns
+        # Returns a new Stretchy::Relation with the specified bucket_script aggregation.
+        #
+        # ---
+        #
+        # ### Examples
+        #
+        # #### Bucket_script aggregation
+        #
+        # ```ruby
+        #   Model.bucket_script(:total_sales, script: "params.tShirtsSold * params.price", buckets_path: {tShirtsSold: "tShirtsSold", price: "price"})
+        # ```
+        #
+        # Aggregation results are available in the `aggregations` method of the results under the name provided in the aggregation.
+        #
+        # ```ruby
+        #   results = Model.where(color: :blue).bucket_script(:total_sales, script: "params.tShirtsSold * params.price", buckets_path: {tShirtsSold: "tShirtsSold", price: "price"})
+        #   results.aggregations.total_sales
+        # ```
+        #
+        def bucket_script(name, options = {}, *aggs)
+          options = {bucket_script: options}.merge(*aggs)
+          aggregation(name, options)
+        end
+
+        AggregationMethods.register!(:bucket_script)
+
+      end
+    end
+  end
+end

data/lib/stretchy/relations/aggregation_methods/bucket_selector.rb

@@ -0,0 +1,47 @@
+module Stretchy
+  module Relations
+    module AggregationMethods
+      module BucketSelector
+        # Perform a bucket_selector aggregation.
+        #
+        # This method is used to filter buckets of a parent multi-bucket aggregation. It accepts a name for the aggregation, a hash of options for the aggregation, and an optional array of nested aggregations.
+        #
+        # ### Parameters
+        #
+        # - `name:` The Symbol or String representing the name of the aggregation.
+        # - `options:` The Hash representing the options for the aggregation (default: {}).
+        #     - `:script:` The String representing the script to determine whether the current bucket will be retained.
+        #     - `:buckets_path:` The Hash representing the paths to the buckets on which to perform computations.
+        # - `aggs:` The Array of Hashes representing nested aggregations (optional).
+        #
+        # ### Returns
+        # Returns a new Stretchy::Relation with the specified bucket_selector aggregation.
+        #
+        # ---
+        #
+        # ### Examples
+        #
+        # #### Bucket_selector aggregation
+        #
+        # ```ruby
+        #   Model.bucket_selector(:sales_bucket_filter, script: "params.totalSales > 200", buckets_path: {totalSales: "totalSales"})
+        # ```
+        #
+        # Aggregation results are available in the `aggregations` method of the results under the name provided in the aggregation.
+        #
+        # ```ruby
+        #   results = Model.where(color: :blue).bucket_selector(:sales_bucket_filter, script: "params.totalSales > 200", buckets_path: {totalSales: "totalSales"})
+        #   results.aggregations.sales_bucket_filter
+        # ```
+        #
+        def bucket_selector(name, options = {}, *aggs)
+          options = {bucket_selector: options}.merge(*aggs)
+          aggregation(name, options)
+        end
+
+        AggregationMethods.register!(:bucket_selector)
+
+      end
+    end
+  end
+end

data/lib/stretchy/relations/aggregation_methods/bucket_sort.rb

@@ -0,0 +1,47 @@
+module Stretchy
+  module Relations
+    module AggregationMethods
+      module BucketSort
+        # Perform a bucket_sort aggregation.
+        #
+        # This method is used to sort the buckets of a parent multi-bucket aggregation. It accepts a name for the aggregation, a hash of options for the aggregation, and an optional array of nested aggregations.
+        #
+        # ### Parameters
+        #
+        # - `name:` The Symbol or String representing the name of the aggregation.
+        # - `options:` The Hash representing the options for the aggregation (default: {}).
+        #     - `:field:` The Symbol or String representing the field to sort on.
+        # - `aggs:` The Array of Hashes representing nested aggregations (optional).
+        #
+        # ### Returns
+        # Returns a new Stretchy::Relation with the specified bucket_sort aggregation.
+        #
+        # ---
+        #
+        # ### Examples
+        #
+        # #### Bucket_sort aggregation
+        #
+        # ```ruby
+        #   Model.bucket_sort(:my_agg, {field: 'my_field'})
+        #   Model.bucket_sort(:my_agg, {field: 'my_field'}, aggs: {...})
+        # ```
+        #
+        # Aggregation results are available in the `aggregations` method of the results under the name provided in the aggregation.
+        #
+        # ```ruby
+        #   results = Model.where(color: :blue).bucket_sort(:my_agg, {field: 'my_field'})
+        #   results.aggregations.my_agg
+        # ```
+        #
+        def bucket_sort(name, options = {}, *aggs)
+            options = {bucket_sort: options}.merge(*aggs)
+            aggregation(name, options)
+        end
+
+        AggregationMethods.register!(:bucket_sort)
+
+      end
+    end
+  end
+end

data/lib/stretchy/relations/aggregation_methods/cardinality.rb

@@ -0,0 +1,47 @@
+module Stretchy
+  module Relations
+    module AggregationMethods
+      module Cardinality
+        # Perform a cardinality aggregation.
+        #
+        # This method is used to calculate the cardinality (unique count) of a field. It accepts a name for the aggregation, a hash of options for the aggregation, and an optional array of nested aggregations.
+        #
+        # ### Parameters
+        #
+        # - `name:` The Symbol or String representing the name of the aggregation.
+        # - `options:` The Hash representing the options for the aggregation (default: {}).
+        #     - `:field:` The Symbol or String representing the field to calculate the cardinality on.
+        # - `aggs:` The Array of Hashes representing nested aggregations (optional).
+        #
+        # ### Returns
+        # Returns a new Stretchy::Relation with the specified cardinality aggregation.
+        #
+        # ---
+        #
+        # ### Examples
+        #
+        # #### Cardinality aggregation
+        #
+        # ```ruby
+        #   Model.cardinality(:unique_names, {field: 'names'})
+        #   Model.cardinality(:unique_names, {field: 'names'}, aggs: {...})
+        # ```
+        #
+        # Aggregation results are available in the `aggregations` method of the results under the name provided in the aggregation.
+        #
+        # ```ruby
+        #   results = Model.where(color: :blue).cardinality(:unique_names, {field: 'names'})
+        #   results.aggregations.unique_names
+        # ```
+        #
+        def cardinality(name, options = {}, *aggs)
+            options = {cardinality: options}.merge(*aggs)
+            aggregation(name, options)
+        end
+
+        AggregationMethods.register!(:cardinality)
+
+      end
+    end
+  end
+end