stretchy-model 0.6.5 → 0.7.0

data/lib/stretchy/relations/query_methods/ids.rb

@@ -0,0 +1,40 @@
+module Stretchy
+  module Relations
+    module QueryMethods
+      module Ids
+
+        # Filters documents that only have the provided ids.
+        #
+        # This method is used to filter the results of a query based on document ids. It accepts an array of ids.
+        #
+        # ### Parameters
+        #
+        # - `args:` The Array of ids to be matched by the query.
+        #
+        # ### Returns
+        # Returns a new Stretchy::Relation with the specified ids to be matched.
+        #
+        # ---
+        #
+        # ### Examples
+        #
+        # #### Filter by ids
+        #
+        # ```ruby
+        #   Model.ids([1, 2, 3])
+        # ```
+        #
+        def ids(*args)
+          spawn.ids!(*args)
+        end
+
+        def ids!(*args) # :nodoc:
+          self.ids_values += args
+          self
+        end
+
+        QueryMethods.register!(:ids)
+      end
+    end
+  end
+end

data/lib/stretchy/relations/query_methods/match.rb

@@ -0,0 +1,52 @@
+module Stretchy
+  module Relations
+    module QueryMethods
+      module Match
+
+        # This method is used to add conditions to the query.
+        #
+        # ### Parameters
+        #
+        # - `query:` (Required) - Text, number, boolean value or date you wish to find in the provided field. The match query analyzes any provided text before performing a search. This means the match query can search text fields for analyzed tokens rather than an exact term.
+        # - `options:` (Optional) - A hash of options to customize the match query. Options include:
+        #   - `analyzer:` (string) - Analyzer used to convert the text in the query value into tokens. Defaults to the index-time analyzer mapped for the field. If no analyzer is mapped, the index’s default analyzer is used.
+        #   - `auto_generate_synonyms_phrase_query:` (Boolean) - If true, match phrase queries are automatically created for multi-term synonyms. Defaults to true.
+        #   - `boost:` (float) - Floating point number used to decrease or increase the relevance scores of the query. Defaults to 1.0.
+        #   - `fuzziness:` (string) - Maximum edit distance allowed for matching.
+        #   - `max_expansions:` (integer) - Maximum number of terms to which the query will expand. Defaults to 50.
+        #   - `prefix_length:` (integer) - Number of beginning characters left unchanged for fuzzy matching. Defaults to 0.
+        #   - `fuzzy_transpositions:` (Boolean) - If true, edits for fuzzy matching include transpositions of two adjacent characters (ab → ba). Defaults to true.
+        #   - `fuzzy_rewrite:` (string) - Method used to rewrite the query.
+        #   - `lenient:` (Boolean) - If true, format-based errors, such as providing a text query value for a numeric field, are ignored. Defaults to false.
+        #   - `operator:` (string) - Boolean logic used to interpret text in the query value. Valid values are: OR (Default), AND.
+        #   - `minimum_should_match:` (string) - Minimum number of clauses that must match for a document to be returned.
+        #   - `zero_terms_query:` (string) - Indicates whether no documents are returned if the analyzer removes all tokens, such as when using a stop filter. Valid values are: none (Default), all.
+        #
+        # ### Returns
+        #
+        # Returns a Stretchy::Relation with the specified conditions applied.
+        #
+        # ### Examples
+        #
+        # ```ruby
+        #   Model.match(path: "/new/things")
+        # ```
+        #
+        def match(opts = :chain, *rest)
+          return MatchChain.new(spawn) if opts == :chain
+          return self if opts.blank?
+        
+          spawn.match!(opts, *rest)
+        end
+
+        def match!(opts, *rest) # :nodoc:
+          self.match_values = [Hash[*opts.shift], **opts]
+          self
+        end
+
+        QueryMethods.register!(:match)
+
+      end
+    end
+  end
+end

data/lib/stretchy/relations/query_methods/must_not.rb

@@ -0,0 +1,54 @@
+module Stretchy
+  module Relations
+    module QueryMethods
+      module MustNot
+        extend ActiveSupport::Concern
+        # Adds negated conditions to the query.
+        #
+        # Each argument is a keyword where the key is the attribute name and the value is the value to exclude.
+        # This method acts as a convenience method for adding negated conditions to the query. It can also be used to add
+        # range, regex, terms, and id queries through shorthand parameters.
+        #
+        # ### Parameters:
+        # - `opts:` The keywords containing attribute-value pairs for conditions.
+        #
+        # ### Returns
+        # Returns a new Stretchy::Relation with the specified conditions excluded.
+        #
+        # ---
+        #
+        # ### Examples
+        #
+        # #### Exclude multiple conditions
+        # ```ruby
+        #   Model.must_not(color: 'blue', size: :large)
+        # ```
+        #
+        def must_not(opts = :chain, *rest)
+          if opts == :chain
+            WhereChain.new(spawn)
+          elsif opts.blank?
+            self
+          else
+            spawn.must_not!(opts, *rest)
+          end
+        end
+
+
+        def must_not!(opts, *rest) # :nodoc:
+          if opts == :chain
+            WhereChain.new(self)
+          else
+            self.must_not_values += build_where(opts, rest)
+            self
+          end
+        end
+        
+        # Alias for {#must_not}
+        # @see #must_not
+        alias :where_not :must_not
+        QueryMethods.register!(:where_not, :must_not)
+      end
+    end
+  end
+end

data/lib/stretchy/relations/query_methods/neural.rb

@@ -0,0 +1,58 @@
+module Stretchy
+  module Relations
+    module QueryMethods
+      module Neural
+        extend ActiveSupport::Concern
+        # Perform a neural search on a specific field.
+        #
+        # The `neural` method accepts a Hash with the field name as the key and the query text as the value.
+        # It can also accept a Hash with `query_text` and `query_image` keys for multimodal neural search.
+        #
+        # ### Parameters
+        #
+        # - `opts:` The Hash options used to refine the selection (default: {}):
+        #     - `:field:` The Symbol or String representing the field name.
+        #       - `:query_text:` The String representing the query text (optional).
+        #       - `:query_image:` The String representing the base-64 encoded query image (optional).
+        #     - `:model_id:` The String representing the ID of the model to be used (required if default model ID is not set).
+        #     - `:k:` The Integer representing the number of results to return (optional, default: 10).
+        #     - `:filter:` The Object representing a query to reduce the number of documents considered (optional).
+        #
+        # ### Returns
+        # Returns a new Stretchy::Relation with the neural search applied.
+        #
+        # ---
+        #
+        # ### Examples
+        #
+        # #### Neural search
+        #
+        # ```ruby
+        #   Model.neural(body_embeddings: 'hello world', model_id: '1234')
+        # ```
+        #
+        # #### Multimodal neural search
+        #
+        # ```ruby
+        #   Model.neural(body_embeddings: {
+        #       query_text: 'hello world',
+        #       query_image: 'base64encodedimage'
+        #     }, 
+        #     model_id: '1234'
+        #   )
+        # ```
+        #
+        def neural(opts)
+          spawn.neural!(opts)
+        end
+
+        def neural!(opts) # :nodoc:
+          self.neural_values += [opts]
+          self
+        end
+
+        QueryMethods.register!(:neural)
+      end
+    end
+  end
+end

data/lib/stretchy/relations/query_methods/neural_sparse.rb

@@ -0,0 +1,43 @@
+module Stretchy
+  module Relations
+    module QueryMethods
+      module NeuralSparse
+        extend ActiveSupport::Concern
+        # Perform a neural sparse search on a specific field.
+        #
+        # The `neural_sparse` method accepts a Hash with the `field_name`, `model_id`, and `max_token_score` keys.
+        #
+        # ### Parameters
+        #
+        # - `opts:` The Hash options used to refine the selection (default: {}):
+        #     - `:field_name:` The keyword argument representing the passage to be embedded and the value to be searched.
+        #     - `:model_id:` The String representing the ID of the model to be used.
+        #     - `:max_token_score:` The Integer representing the maximum token score to consider.
+        #
+        # ### Returns
+        # Returns a new Stretchy::Relation with the neural sparse search applied.
+        #
+        # ---
+        #
+        # ### Examples
+        #
+        # #### Neural sparse search
+        #
+        # ```ruby
+        #   Model.neural_sparse(passage_embedding: 'hello world', model_id: '1234', max_token_score: 2)
+        # ```
+        #
+        def neural_sparse(opts)
+          spawn.neural_sparse!(opts)
+        end
+
+        def neural_sparse!(opts) # :nodoc:
+          self.neural_sparse_values += [opts]
+          self
+        end
+
+        QueryMethods.register!(:neural_sparse)
+      end
+    end
+  end
+end

data/lib/stretchy/relations/query_methods/none.rb

@@ -0,0 +1,21 @@
+module Stretchy
+  module Relations
+    module QueryMethods
+      module None
+        extend ActiveSupport::Concern
+
+        # Returns a chainable relation with zero records.
+        def none
+          extending(Stretchy::Relations::NullRelation)
+        end
+
+        def none! # :nodoc:
+          extending!(Stretchy::Relations::NullRelation)
+        end
+
+        QueryMethods.register!(:none)
+
+      end
+    end
+  end
+end

data/lib/stretchy/relations/query_methods/or_filter.rb

@@ -0,0 +1,21 @@
+module Stretchy
+  module Relations
+    module QueryMethods
+      module OrFilter
+        extend ActiveSupport::Concern
+        # @deprecated in elasticsearch 7.x+ use {#filter_query} instead
+        def or_filter(name, options = {}, &block)
+          spawn.or_filter!(name, options, &block)
+        end
+
+        def or_filter!(name, options = {}, &block) # :nodoc:
+          self.or_filter_values += [{name: name, args: options}]
+          self
+        end
+
+        QueryMethods.register!(:or_filter)
+
+      end
+    end
+  end
+end

data/lib/stretchy/relations/query_methods/order.rb

@@ -0,0 +1,63 @@
+module Stretchy
+  module Relations
+    module QueryMethods
+      module Order
+      extend ActiveSupport::Concern
+        # Allows you to add one or more sorts on specified fields.
+        #
+        # This method is used to sort the results of a query based on one or more fields. It accepts a variable number of arguments,
+        # each of which is a hash where the key is the field name and the value is the sort direction or a hash of sort options.
+        #
+        # ### Parameters
+        #
+        # - `args:` The Array of hashes representing the sort fields and directions or options (default: []).
+        #     - `:attribute:` The Symbol or String representing the field name.
+        #     - `:direction:` The Symbol representing the sort direction (:asc or :desc).
+        #     - `:options:` The Hash representing the sort options (optional).
+        #         - `:order:` The Symbol representing the sort direction (:asc or :desc).
+        #         - `:mode:` The Symbol representing the sort mode (:avg, :min, :max, :sum, :median).
+        #         - `:numeric_type:` The Symbol representing the numeric type (:double, :long, :date, :date_nanos).
+        #         - `:missing:` The value to use for documents without the field.
+        #         - `:nested:` The Hash representing the nested sort options.
+        #             - `:path:` The String representing the path to the nested object.
+        #             - `:filter:` The Hash representing the filter to apply to the nested object.
+        #             - `:max_children:` The Integer representing the maximum number of children to consider per root document when picking the sort value.
+        #
+        # ### Returns
+        # Returns a new Stretchy::Relation with the specified order.
+        #
+        # ---
+        #
+        # ### Examples
+        #
+        # #### Single field
+        #
+        # ```ruby
+        #   Model.order(created_at: :asc)
+        # ```
+        #
+        # #### Multiple fields
+        #
+        # ```ruby
+        #   Model.order(age: :desc, name: :asc, price: {order: :desc, mode: :avg})
+        # ```
+        #
+        def order(*args)
+          check_if_method_has_arguments!(:order, args)
+          spawn.order!(*args)
+        end
+
+        def order!(*args) # :nodoc:
+          self.order_values += args.first.zip.map(&:to_h)
+          self
+        end
+
+        # Alias for {#order}
+        # @see #order
+        alias :sort :order
+        QueryMethods.register!(:sort, :order)
+
+      end
+    end
+  end
+end

data/lib/stretchy/relations/query_methods/query_string.rb

@@ -0,0 +1,44 @@
+module Stretchy
+  module Relations
+    module QueryMethods
+      module QueryString
+        extend ActiveSupport::Concern
+        # Adds a query string to the search.
+        #
+        # The query string uses Elasticsearch's Query String Query syntax, which includes a series of terms and operators.
+        # Terms can be single words or phrases. Operators include AND, OR, and NOT, among others.
+        # Field names can be included in the query string to search for specific values in specific fields. (e.g. "eye_color: green")
+        # The default operator between terms are treated as OR operators.
+        #
+        # ### Parameters
+        #
+        # - `opts:` The query string 
+        #
+        # ### Returns
+        # Returns a new Stretchy::Relation, which reflects the query string.
+        #
+        # ---
+        #
+        # ### Examples
+        #
+        # #### Query string
+        #
+        # ```ruby
+        #   Model.query_string("((big cat) OR (domestic cat)) AND NOT panther eye_color: green")
+        # ```
+        #
+        def query_string(opts = :chain, *rest)
+          spawn.query_string!(opts, *rest)
+        end
+
+        def query_string!(opts, *rest) # :nodoc:
+          self.query_string_values += build_where(opts, rest)
+          self
+        end
+
+        QueryMethods.register!(:query_string)
+
+      end
+    end
+  end
+end

data/lib/stretchy/relations/query_methods/regexp.rb

@@ -0,0 +1,61 @@
+module Stretchy
+  module Relations
+    module QueryMethods
+      module Regexp
+        extend ActiveSupport::Concern
+        # Adds a regexp condition to the query.
+        #
+        # This method is used to filter the results of a query based on a regular expression. It accepts a hash where the key is the field name and the value is the regular expression.
+        #
+        # ### Parameters
+        #
+        # - `field:` The Symbol or String representing the field name as the key and the regular expression to be matched as value.
+        # - `opts:` The keywords representing additional options for the regexp query (optional).
+        #     - `flags:` The String representing the flags to use for the regexp query (e.g. 'ALL').
+        #     - `use_keyword:` The Boolean indicating whether to use the .keyword field for the regexp query (default: true).
+        #     - `case_insensitive:` The Boolean indicating whether to use case insensitive matching. If the regexp has ignore case flag `/regex/i`, this is automatically set to true.
+        #     - `max_determinized_states:` The Integer representing the maximum number of states that the regexp query can produce.
+        #     - `rewrite:` The String representing the rewrite method to use for the regexp query.
+        #
+        # ### Returns
+        # Returns a new Stretchy::Relation, which reflects the regexp condition.
+        #
+        # ---
+        #
+        # ### Examples
+        #
+        # #### Regexp condition
+        #
+        # ```ruby
+        #   Model.regexp(name: /john|jane/)
+        #```
+        #
+        # #### Regexp with case insensitive matching
+        # ```ruby
+        #   Model.regexp(name: /john|jane/i)
+        # ```
+        # 
+        # #### Regexp with flags
+        # ```ruby
+        #   Model.regexp(name: /john|jane/i, flags: 'ALL')
+        # ```
+        #
+        def regexp(args)
+          spawn.regexp!(args)
+        end
+
+        def regexp!(args) # :nodoc:
+          args = args.to_a
+          target_field, regex = args.shift
+          opts = args.to_h
+          opts.merge!(case_insensitive: true) if regex.casefold?
+          self.regexp_values += [[Hash[target_field, regex.source], opts]]
+          self
+        end
+  
+        QueryMethods.register!(:regexp)
+  
+      end
+    end
+  end
+end

data/lib/stretchy/relations/query_methods/should.rb

@@ -0,0 +1,51 @@
+module Stretchy
+  module Relations
+    module QueryMethods
+      module Should
+        extend ActiveSupport::Concern
+        # Adds optional conditions to the query.
+        #
+        # Each argument is a hash where the key is the attribute to filter by and the value is the value to match optionally.
+        #
+        # ### Parameters
+        #
+        # - `opts:` The Hash representing the attribute-value pairs to match optionally or a Symbol `:chain` to return a new WhereChain.
+        #
+        # ### Returns
+        # Returns a new Stretchy::Relation, which reflects the optional conditions.
+        #
+        # ---
+        #
+        # ### Examples
+        #
+        # #### Optional conditions
+        #
+        # ```ruby
+        #   Model.should(color: :pink, size: :medium)
+        # ```
+        #
+        def should(opts = :chain, *rest)
+          if opts == :chain
+            WhereChain.new(spawn)
+          elsif opts.blank?
+            self
+          else
+            spawn.should!(opts, *rest)
+          end
+        end
+
+        def should!(opts, *rest) # :nodoc:
+          if opts == :chain
+            WhereChain.new(self)
+          else
+            self.should_values += build_where(opts, rest)
+            self
+          end
+        end
+
+        QueryMethods.register!(:should)
+
+      end
+    end
+  end
+end

data/lib/stretchy/relations/query_methods/size.rb

@@ -0,0 +1,44 @@
+module Stretchy
+  module Relations
+    module QueryMethods
+      module Size
+        extend ActiveSupport::Concern
+        # Sets the maximum number of records to be retrieved.
+        #
+        # This method is used to limit the number of records returned by the query. It accepts an integer as an argument.
+        #
+        # ### Parameters
+        #
+        # - `args:` The Integer representing the maximum number of records to retrieve.
+        #
+        # ### Returns
+        # Returns a new Stretchy::Relation, which reflects the limit.
+        #
+        # ---
+        #
+        # ### Examples
+        #
+        # #### Limit the number of records
+        #
+        # ```ruby
+        #   Model.size(10)
+        # ```
+        #
+        def size(args)
+          spawn.size!(args)
+        end
+
+        def size!(args) # :nodoc:
+          self.size_value = args
+          self
+        end
+
+        # Alias for {#size}
+        # @see #size
+        alias :limit :size
+
+        QueryMethods.register!(:limit, :size)
+      end
+    end
+  end
+end

data/lib/stretchy/relations/query_methods/skip_callbacks.rb

@@ -0,0 +1,47 @@
+module Stretchy
+  module Relations
+    module QueryMethods
+      module SkipCallbacks
+        extend ActiveSupport::Concern
+        # Allows you to skip callbacks for the specified fields.
+        #
+        # This method is used to skip callbacks that are added by `query_must_have` for the specified fields for the current query. It accepts a variable number of arguments, each of which is the name of a field to skip callbacks for.
+        #
+        # ### Parameters
+        #
+        # - `args:` The Array of field names to skip callbacks for.
+        #
+        # ### Returns
+        # Returns a new Stretchy::Relation with the specified fields to skip callbacks for.
+        #
+        # ---
+        #
+        # ### Examples
+        #
+        # #### Skip callbacks for a single field
+        #
+        # ```ruby
+        #   Model.skip_callbacks(:routing)
+        # ```
+        #
+        # #### Skip callbacks for multiple fields
+        #
+        # ```ruby
+        #   Model.skip_callbacks(:routing, :relevance)
+        # ```
+        #
+        def skip_callbacks(*args)
+          spawn.skip_callbacks!(*args)
+        end
+
+        def skip_callbacks!(*args) # :nodoc:
+          self.skip_callbacks_values += args
+          self
+        end
+
+        QueryMethods.register!(:skip_callbacks)
+
+      end
+    end
+  end
+end

data/lib/stretchy/relations/query_methods/source.rb

@@ -0,0 +1,59 @@
+module Stretchy
+  module Relations
+    module QueryMethods
+      module Source
+        extend ActiveSupport::Concern
+
+        # Controls which fields of the source are returned.
+        #
+        # This method supports source filtering, which allows you to include or exclude fields from the source.
+        # You can specify fields directly, use wildcard patterns, or use an object containing arrays
+        # of includes and excludes patterns.
+        #
+        # If the includes property is specified, only source fields that match one of its patterns are returned.
+        # You can exclude fields from this subset using the excludes property.
+        #
+        # If the includes property is not specified, the entire document source is returned, excluding any
+        # fields that match a pattern in the excludes property.
+        #
+        # ### Parameters
+        #   - `:includes:` The Array of fields to be included in the source (default: []).
+        #   - `:excludes:` The Array of fields to be excluded from the source (default: []).
+        #   - Or a Boolean indicating whether to include the source.
+        #
+        # ### Returns
+        # Returns a Stretchy::Relation, which reflects the source filtering.
+        #
+        # ---
+        # 
+        # ### Examples
+        #
+        # #### Include source
+        # ```ruby
+        #   Model.source(includes: [:name, :email])
+        # ```
+        #
+        # #### Exclude source
+        # ```ruby
+        #   Model.source(excludes: [:name, :email])
+        # ```
+        #
+        # #### No source
+        # ```ruby
+        #   Model.source(false) # don't include source
+        # ```
+        #
+        def source(*args)
+          spawn.source!(*args)
+        end
+
+        def source!(*args) # :nodoc:
+          self.source_values += args
+          self
+        end
+
+        QueryMethods.register!(:source)
+      end
+    end
+  end
+end