stretchy-model 0.6.5 → 0.6.6

data/lib/stretchy/indexing/bulk.rb

@@ -4,15 +4,62 @@ module Stretchy
             extend ActiveSupport::Concern
 
             class_methods do
-
+                # used to bulk index a collection of records.
+                #
+                # ### Parameters
+                #
+                # - `records:` (Array) - The collection of records to be indexed.
+                #
+                # ### Returns
+                #
+                # - (Hash) - The response from Elasticsearch after performing the bulk operation.
+                #
+                # ### Behavior
+                #
+                # The method sends a bulk request to Elasticsearch with the provided records. The records should be an array of hashes, where each hash describes a single create, index, delete, or update operation.
+                # It always returns the response from Elasticsearch.
+                #
+                # ### Example
+                #
+                # ```ruby
+                # records = [
+                #   { index: { _index: 'my_index', _id: 1, data: { title: 'foo' } } },
+                #   { index: { _index: 'my_index', _id: 2, data: { title: 'bar' } } }
+                # ]
+                # MyModel.bulk(records)
+                # ```
+                # In this example, the `bulk` method is used to index two records into 'my_index'.
                 def bulk(records)
                     self.gateway.client.bulk body: records
                 end
 
-                # bulk_in_batches(records, size: 100) do |batch|
+                # used to bulk index a collection of records in batches.
+                #
+                # ### Parameters
+                #
+                # - `records:` (Array) - The collection of records to be indexed.
+                # - `size:` (Integer) - The size of the batches. Defaults to 1000.
+                # - `&block:` (optional) A block that is evaluated for each batch. This can be used to perform operations on each batch.
+                #
+                # ### Returns
+                #
+                # - (Array) - The results of the bulk operations.
+                #
+                # ### Behavior
+                #
+                # - The method splits the records into batches of the specified size. For each batch, if a block is given, it is evaluated with the batch as argument. Then, the batch is indexed using the `bulk` method.
+                # - After all batches have been processed, it refreshes the index to make the changes available for search.
+                #
+                # ### Example
+                #
+                # ```ruby
+                # records = [Report.new(title: "hello"), Report.new(title: "world"), Report.new(title: "goodbye")]
+                # MyModel.bulk_in_batches(records, size: 100) do |batch|
                 #   # do something with the batch
-                #   batch.each { |record| record.to_bulk(method)}
+                #   batch.map! { |record| record.to_bulk(:index)}
                 # end
+                # ```
+                # In this example, the `bulk_in_batches` method is used to index the `records` in batches of 100. 
                 def bulk_in_batches(records, size: 1000)
                     bulk_results = records.each_slice(size).map do |batch|
                         yield batch if block_given?
@@ -32,6 +79,31 @@ module Stretchy
                 # end
             end
 
+            # used to transform a record into a hash suitable for bulk operations.
+            #
+            # ### Parameters
+            #
+            # - `method:` (Symbol) - The operation to be performed. Can be `:index`, `:delete`, or `:update`. Defaults to `:index`.
+            #
+            # ### Returns
+            #
+            # - (Hash) - The hash representing the record for the bulk operation.
+            #
+            # ### Behavior
+            #
+            # The method transforms the record into a hash that describes the operation to be performed on the record. The operation is specified by the `method` parameter.
+            # For `:index`, it includes the index name and the record data (excluding the id).
+            # For `:delete`, it includes the index name and the record id.
+            # For `:update`, it includes the index name, the record id, and the record data (excluding the id).
+            #
+            # ### Example
+            #
+            # ```ruby
+            # record = MyModel.new(title: "hello")
+            # record.to_bulk(:index)
+            # # => { index: { _index: "my_models", data: { title: "hello" } } }
+            # ```
+            # In this example, the `to_bulk` method is used to transform a `MyModel` instance into a hash suitable for an index operation in a bulk request.
             def to_bulk(method = :index)
                 case method
                 when :index

data/lib/stretchy/model/callbacks.rb

@@ -8,6 +8,7 @@ module Stretchy
         included do
           mattr_accessor :_circuit_breaker_callbacks, default: []
 
+          define_model_callbacks :initialize, only: :after
           define_model_callbacks :create, :save, :update, :destroy
           define_model_callbacks :find, :touch, only: :after
         end

data/lib/stretchy/model/common.rb

@@ -0,0 +1,157 @@
+module Stretchy
+    module Model
+        module Common
+            extend ActiveSupport::Concern
+
+            # Get the highlighted results for a specific field.
+            #
+            # This method is used to get the highlighted results for a specific field from the search results. It accepts a field for which to get the highlighted results.
+            #
+            # ### Parameters
+            #
+            # - `field:` The Symbol or String representing the field for which to get the highlighted results.
+            #
+            # ### Returns
+            # Returns an Array of Strings representing the highlighted results for the specified field.
+            #
+            # ---
+            #
+            # ### Examples
+            #
+            # #### Get the highlighted results for a field
+            #
+            # ```ruby
+            #   result = Model.query_string("name: Soph*").highlight(name: {pre_tags: "__", post_tags: "__"}).first
+            #   result.highlights_for(:name)
+            # ```
+            #
+            def highlights_for(attribute)
+                highlights[attribute.to_s]
+            end
+
+            class_methods do
+
+                # Set or get the default sort key.
+                #
+                # This method is used to set or get the default sort key to be used in sort operations. If a field is provided, it sets the field as the default sort key. If no field is provided, it returns the current default sort key.
+                #
+                # `created_at` is the default sort key.
+                #
+                # ### Parameters
+                #
+                # - `field:` The Symbol or String representing the field to be used as the default sort key (optional).
+                #
+                # ### Returns
+                # Returns the current default sort key if no field is provided. If a field is provided, it sets the field as the default sort key and returns the field.
+                #
+                # ---
+                #
+                # ### Examples
+                #
+                # #### Set the default sort key
+                #
+                # ```ruby
+                #   class Model < StretchyModel
+                #       default_sort_key :updated_at
+                #   end
+                # ```
+                #
+                # #### Get the default sort key
+                #
+                # ```ruby
+                #   Model.default_sort_key
+                # ```
+                #
+                def default_sort_key(field = nil)
+                    @default_sort_key = field unless field.nil?
+                    @default_sort_key
+                end
+
+
+                # Set or get the default size.
+                #
+                # This method is used to set or get the default size to be used in operations that return documents. If a size is provided, it sets the size as the default size. 
+                # If no size is provided, it returns the current default size.
+                # 
+                # 10000 is the default size for StretchyModel
+                #
+                # ### Parameters
+                #
+                # - `size:` The Integer representing the size to be used as the default size (optional).
+                #
+                # ### Returns
+                # Returns the current default size if no size is provided. If a size is provided, it sets the size as the default size and returns the size.
+                #
+                # ---
+                #
+                # ### Examples
+                #
+                # #### Set the default size
+                #
+                # ```ruby
+                #   class Model < StretchyModel
+                #       default_size 100
+                #   end
+                # ```
+                #
+                # #### Get the default size
+                #
+                # ```ruby
+                #   Model.default_size
+                # ```
+                #
+                def default_size(size = nil)
+                    @default_size = size unless size.nil?
+                    @default_size
+                end
+
+                
+                # Set or get the default pipeline.
+                #
+                # This method is used to set or get the default pipeline at the index level to be used in operations that require a pipeline. 
+                #  
+                # If a pipeline is provided, it sets the pipeline as the default pipeline. 
+                # If no pipeline is provided, it returns the current default pipeline.
+                #
+                # ### Parameters
+                #
+                # - `pipeline:` The String representing the pipeline to be used as the default pipeline (optional).
+                #
+                # ### Returns
+                # Returns the current default pipeline if no pipeline is provided. If a pipeline is provided, it sets the pipeline as the default pipeline and returns the pipeline.
+                #
+                # ---
+                #
+                # ### Examples
+                #
+                # #### Set the default pipeline
+                #
+                # ```ruby
+                #   class Model < StretchyModel
+                #       default_pipeline 'my_pipeline'
+                #   end
+                # ```
+                #
+                # #### Get the default pipeline
+                #
+                # ```ruby
+                #   Model.default_pipeline
+                # ```
+                #
+                def default_pipeline(pipeline = nil)
+                    @default_pipeline = pipeline.to_s unless pipeline.nil?
+                    @default_pipeline
+                end
+
+                private
+
+                # Return a Relation instance to chain queries
+                #
+                def relation
+                    Relation.create(self, {})
+                end
+
+            end
+        end
+    end
+end

data/lib/stretchy/model/persistence.rb

@@ -0,0 +1,144 @@
+module Stretchy
+    module Model
+        module Persistence
+            extend ActiveSupport::Concern
+
+            class_methods do
+                # Create a new instance and save it to the database.
+                #
+                # This class method is used to create a new instance of the model and save it to the database. It accepts a list of keyword attributes to set on the new instance.
+                #
+                # ### Parameters
+                #
+                # - `*args:` A list of keyword arguments representing the attributes to set on the new instance.
+                #
+                # ### Returns
+                # Returns the newly created instance of the model.
+                #
+                # ---
+                #
+                # ### Examples
+                #
+                # #### Create a new instance
+                #
+                # ```ruby
+                #   Model.create(name: 'John Doe', age: 30)
+                # ```
+                #
+                def create(*args)
+                    self.new(*args).save
+                end
+            end
+
+            # Save the current instance to the database.
+            #
+            # This instance method is used to save the current instance of the model to the database. If the instance is a new record, it runs the `:create` callbacks and saves the instance to the database. It then sets the `id` of the instance to the `_id` returned by the save operation.
+            #
+            # ### Returns
+            # Returns the `id` of the saved instance.
+            #
+            # ---
+            #
+            # ### Examples
+            #
+            # #### Save an instance
+            #
+            # ```ruby
+            #   model = Model.new(name: 'John Doe', age: 30)
+            #   model.save
+            # ```
+            #
+            def save
+                run_callbacks :save do
+                    if new_record?
+                        run_callbacks :create do
+                            response = self.class.gateway.save(self.attributes)
+                            self.id = response['_id']
+                        end
+                    else
+                        self.class.gateway.save(self.attributes)
+                    end
+                    self
+                end
+            end
+
+            # Destroy the current instance.
+            #
+            # This instance method is used to delete the current instance of the model from the database. 
+            # It differs from delete in that it runs the `:destroy` callbacks before deleting the instance.
+            # 
+            #
+            # ### Returns
+            # Returns `true` if the instance was successfully deleted, `false` otherwise.
+            #
+            # ---
+            #
+            # ### Examples
+            #
+            # #### Delete an instance
+            #
+            # ```ruby
+            #   model = Model.find(id: '1')
+            #   model.destroy
+            # ```
+            #
+            def destroy
+                run_callbacks :destroy do
+                    delete
+                end
+            end
+
+            # Delete the current instance from the database.
+            #
+            # This instance method is used to delete the current instance of the model from the database. It uses the `id` of the instance to perform the delete operation.
+            #
+            # ### Returns
+            # Returns `true` if the instance was successfully deleted, `false` otherwise.
+            #
+            # ---
+            #
+            # ### Examples
+            #
+            # #### Delete an instance
+            #
+            # ```ruby
+            #   model = Model.find(id: '1')
+            #   model.delete
+            # ```
+            #
+            def delete
+                self.class.gateway.delete(self.id)["result"] == 'deleted'
+            end
+
+            # Update the current instance with the given attributes and save it to the database.
+            #
+            # This instance method is used to update the current instance of the model with the given attributes and save it to the database. It accepts a list of keyword arguments representing the attributes to update.
+            #
+            # ### Parameters
+            #
+            # - `*args:` A list of keyword arguments representing the attributes to update.
+            #
+            # ### Returns
+            # Returns `true` if the instance was successfully updated, `false` otherwise.
+            #
+            # ---
+            #
+            # ### Examples
+            #
+            # #### Update an instance
+            #
+            # ```ruby
+            #   model = Model.find(id: '1')
+            #   model.update(name: 'Jane Doe', age: 32)
+            # ```
+            #
+            def update(*args)
+                run_callbacks :update do
+                    self.assign_attributes(*args)
+                    self.save
+                end
+            end
+
+        end
+    end
+end

data/lib/stretchy/model/refreshable.rb

@@ -0,0 +1,26 @@
+module Stretchy
+  module Model
+    # Adds callbacks to the model to refresh the index after save or destroy.
+    #
+    # ```ruby
+    # included do
+    #   after_save :refresh_index
+    #   after_destroy :refresh_index
+    # end
+    # ```
+    module Refreshable
+      extend ActiveSupport::Concern
+
+      
+      included do
+        after_save :refresh_index
+        after_destroy :refresh_index
+      end
+
+      def refresh_index
+        self.class.refresh_index!
+      end
+
+    end
+  end
+end

data/lib/stretchy/pipeline.rb

@@ -30,7 +30,8 @@ module Stretchy
         end
       end
     
-      def find(id)
+      def find(id=nil)
+        id = self.pipeline_name if id.nil?
         client.get_pipeline(id: id)
       end
 

data/lib/stretchy/pipelines/processor.rb

@@ -1,43 +1,45 @@
 module Stretchy::Pipelines
   # Creates a new processor for a pipeline
   # 
-  # Processor type	      Description
-  # append	              Adds one or more values to a field in a document.
-  # bytes	                Converts a human-readable byte value to its value in bytes.
-  # convert	              Changes the data type of a field in a document.
-  # copy	                Copies an entire object in an existing field to another field.
-  # csv	                  Extracts CSVs and stores them as individual fields in a document.
-  # date	                Parses dates from fields and then uses the date or timestamp as the timestamp for a document.
-  # date_index_name	      Indexes documents into time-based indexes based on a date or timestamp field in a document.
-  # dissect	              Extracts structured fields from a text field using a defined pattern.
-  # dot_expander	        Expands a field with dots into an object field.
-  # drop	                Drops a document without indexing it or raising any errors.
-  # fail    	            Raises an exception and stops the execution of a pipeline.
-  # foreach	              Allows for another processor to be applied to each element of an array or an object field in a document.
-  # geoip	                Adds information about the geographical location of an IP address.
-  # geojson-feature	      Indexes GeoJSON data into a geospatial field.
-  # grok	                Parses and structures unstructured data using pattern matching.
-  # gsub	                Replaces or deletes substrings within a string field of a document.
-  # html_strip	          Removes HTML tags from a text field and returns the plain text content.
-  # ip2geo	              Adds information about the geographical location of an IPv4 or IPv6 address.
-  # join	                Concatenates each element of an array into a single string using a separator character between each element.
-  # json	                Converts a JSON string into a structured JSON object.
-  # kv	                  Automatically parses key-value pairs in a field.
-  # lowercase	            Converts text in a specific field to lowercase letters.
-  # pipeline	            Runs an inner pipeline.
-  # remove	              Removes fields from a document.
-  # script	              Runs an inline or stored script on incoming documents.
-  # set	                  Sets the value of a field to a specified value.
-  # sort	                Sorts the elements of an array in ascending or descending order.
-  # sparse_encoding	      Generates a sparse vector/token and weights from text fields for neural sparse search using sparse retrieval.
-  # split	                Splits a field into an array using a separator character.
-  # text_embedding	      Generates vector embeddings from text fields for semantic search.
-  # text_image_embedding	Generates combined vector embeddings from text and image fields for multimodal neural search.
-  # trim	                Removes leading and trailing white space from a string field.
-  # uppercase	            Converts text in a specific field to uppercase letters.
-  # urldecode	            Decodes a string from URL-encoded format.
-  # user_agent	          Extracts details from the user agent sent by a browser to its web requests.
+  # Below is a list of processors that can be used in a pipeline. Each processor has a specific function that can be applied to a document.
+  # 
+  # For more information on processors, see the [Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/current/ingest-processors.html).
+  # or [OpenSearch](https://opensearch.org/docs/latest/ingest-pipelines/processors/index-processors/) documentation.
   #
+  # | type | Description |
+  # | --- | --- |
+  # | append | Adds one or more values to a field in a document. |
+  # | bytes | Converts a human-readable byte value to its value in bytes. |
+  # | convert | Changes the data type of a field in a document. |
+  # | copy | Copies an entire object in an existing field to another field. |
+  # | csv | Extracts CSVs and stores them as individual fields in a document. |
+  # | date | Parses dates from fields and then uses the date or timestamp as the timestamp for a document. |
+  # | date_index_name | Indexes documents into time-based indexes based on a date or timestamp field in a document. |
+  # | dissect | Extracts structured fields from a text field using a defined pattern. |
+  # | dot_expander | Expands a field with dots into an object field. |
+  # | drop | Drops a document without indexing it or raising any errors. |
+  # | fail | Raises an exception and stops the execution of a pipeline. |
+  # | foreach | Allows for another processor to be applied to each element of an array or an object field in a document. |
+  # | geoip | Adds information about the geographical location of an IP address. |
+  # | geojson-feature | Indexes GeoJSON data into a geospatial field. |
+  # | grok | Parses and structures unstructured data using pattern matching. |
+  # | gsub | Replaces or deletes substrings within a string field of a document. |
+  # | html_strip | Removes HTML tags from a text field and returns the plain text content. |
+  # | ip2geo | Adds information about the geographical location of an IPv4 or IPv6 address. |
+  # | join | Concatenates each element of an array into a single string using a separator character between each element. |
+  # | json | Converts a JSON string into a structured JSON object. |
+  # | kv | Automatically parses key-value pairs in a field. |
+  # | lowercase | Converts text in a specific field to lowercase letters. |
+  # | pipeline | Runs an inner pipeline. |
+  # | remove | Removes fields from a document. |
+  # | script | Runs an inline or stored script on incoming documents. |
+  # | set | Sets the value of a field to a specified value. |
+  # | sort | Sorts the elements of an array in ascending or descending order. |
+  # | sparse_encoding | Generates a sparse vector/token and weights from text fields for neural sparse search using sparse retrieval. |
+  # | split | Splits a field into an array using a separator character. |
+  # | text_embedding | Generates vector embeddings from text fields for semantic search. |
+  # | text_image_embedding | Generates combined vector embeddings from text and image fields for multimodal neural search. |
+
   class Processor
     
     attr_reader :type, :opts, :description

data/lib/stretchy/querying.rb

@@ -1,13 +1,13 @@
 module Stretchy
   module Querying
-    delegate :first, :first!, :last, :last!, :exists?, :has_field, :any?, :many?, to: :all
-    delegate :order, :limit, :size, :sort, :rewhere, :eager_load, :includes,  :create_with, :none, :unscope, to: :all
-    delegate :or_filter, :fields, :source, :highlight, to: :all
-    delegate :neural_sparse, :neural, :hybrid, to: :all
-    delegate *Stretchy::Relations::AggregationMethods::AGGREGATION_METHODS, to: :all
+    delegate :exists?, :any?, :many?, :includes, to: :all
+    delegate :rewhere, :eager_load, :create_with, :unscoped, to: :all
+
+    delegate *Stretchy::Relations::FinderMethods::METHODS, to: :all
+    delegate *Stretchy::Relations::SearchOptionMethods::METHODS, to: :all
+    delegate *Stretchy::Relations::QueryMethods.registry, to: :all
+    delegate *Stretchy::Relations::AggregationMethods.registry, to: :all
 
-    delegate :skip_callbacks, :routing, :search_options, to: :all
-    delegate :must, :must_not, :should, :where_not, :where, :filter_query, :query_string, :regexp, to: :all
 
     def fetch_results(es)
       if es.count?
@@ -17,6 +17,5 @@ module Stretchy
       end
     end
 
-
   end
 end

data/lib/stretchy/record.rb

@@ -16,12 +16,12 @@ module Stretchy
                 include ActiveModel::Serializers::JSON
 
                 include Stretchy::Model::Callbacks
+                include Stretchy::Model::Common
+                include Stretchy::Model::Persistence
+                include Stretchy::Model::Refreshable
                 include Stretchy::Indexing::Bulk
-                include Stretchy::Persistence
                 include Stretchy::Associations 
-                include Stretchy::Refreshable
-                include Stretchy::Common
-                include Stretchy::Scoping
+                include Stretchy::Relations::Scoping
                 include Stretchy::Utils
                 include Stretchy::SharedScopes
                 include Stretchy::Attributes
@@ -46,6 +46,7 @@ module Stretchy
                 def initialize(attributes = {})
                     @highlights = attributes.delete(:_highlights) 
                     super(attributes)
+                    run_callbacks :initialize 
                 end
 
             end