stretchy-model 0.6.5 → 0.7.0

data/lib/stretchy/relations/finder_methods.rb

@@ -3,6 +3,8 @@ module Stretchy
 
       module FinderMethods
 
+        METHODS = [:first, :first!, :last, :last!]
+
         def first
           return results.first if @loaded
           spawn.first!.results.first
@@ -39,24 +41,6 @@ module Stretchy
           self
         end
 
-        # size is not permitted to the count API but queries are.
-        #
-        # if a query is supplied with `.count` then the user wants a count of the results
-        # matching the query
-        #  
-        # however, the default_size is used to limit the number of results returned
-        # so we remove the size from the query and then call `.count` API
-        #
-        # but if the user supplies a limit, then we should assume they want a count of the results
-        # which could lead to some confusion 
-        # suppose the user calls `.size(100).count` and the default_size is 100
-        # if we remove size from the query, then the count could be greater than 100
-        # 
-        # I think the best way to handle this is to remove the size from the query only if it was  
-        # applied by the default_size
-        # If the user supplies a limit, then we should assume they want a count of the results
-        # 
-        # if size is called with a limit,
         def count
           return results.count if @loaded || @values[:size].present?
           spawn.count!

data/lib/stretchy/relations/null_relation.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Stretchy
+  module Relations
+    module NullRelation # :nodoc:
+      def pluck(*column_names)
+        []
+      end
+
+      def delete_all
+        0
+      end
+
+      def update_all(_updates)
+        0
+      end
+
+      def delete(_id_or_array)
+        0
+      end
+
+      def empty?
+        true
+      end
+
+      def none?
+        true
+      end
+
+      def any?
+        false
+      end
+
+      def one?
+        false
+      end
+
+      def many?
+        false
+      end
+
+      def exists?(_conditions = :none)
+        false
+      end
+
+      def or(other)
+        other.spawn
+      end
+
+      def exec_queries
+        @records = OpenStruct.new(klass: NullRelation, total: 0, results: []).freeze
+      end
+    end
+  end
+end

data/lib/stretchy/relations/query_builder.rb

@@ -27,6 +27,10 @@ module Stretchy
         @query ||= compact_where(values[:where])
       end
 
+      def match_query
+        @match_query ||= values[:match]
+      end
+
       def query_strings
         @query_string ||= compact_where(values[:query_string], bool: false)
       end
@@ -51,12 +55,16 @@ module Stretchy
         @shoulds ||= compact_where(values[:should])
       end
 
+      def ids
+        @ids ||= values[:ids]
+      end
+
       def regexes
         @regexes ||= values[:regexp]
       end
 
       def fields
-        values[:field]
+        values[:fields]
       end
 
       def source
@@ -98,14 +106,14 @@ module Stretchy
         build_highlights unless highlights.blank?
         build_fields unless fields.blank?
         build_source unless source.blank?
-        build_aggregations unless aggregations.blank?
+        build_aggregations(aggregations, structure) unless aggregations.blank?
         structure.attributes!.with_indifferent_access
       end
 
       private
 
       def missing_bool_query?
-        query.nil? && must_nots.nil? && shoulds.nil? && regexes.nil?
+        query.blank? && must_nots.nil? && shoulds.nil? && regexes.nil?
       end
 
       def missing_query_string?
@@ -121,33 +129,42 @@ module Stretchy
       end
 
       def no_query?
-        missing_bool_query? && missing_query_string? && missing_query_filter? && missing_neural?
+        missing_bool_query? && missing_query_string? && missing_query_filter? && missing_neural? && ids.nil? && match_query.nil?
       end
 
       def build_query
         return if no_query?
         structure.query do
+          structure.ids do
+            structure.values ids.flatten.compact.uniq
+          end unless ids.nil?
+
+          structure.match do 
+            mq = match_query.dup
+            field, value = mq.first.shift
+            structure.set! field do
+              structure.query value
+              structure.extract! mq.last, *mq.last.keys
+            end
+          end unless match_query.nil?
 
           structure.hybrid do
             structure.queries do
-                hybrid[:neural].each do |n|
-                  structure.child! do
-                    params = n.dup
-                    field_name, query_text = params.shift
-                    structure.neural do
-                      structure.set! field_name do
-                        structure.query_text query_text
-                        structure.extract! params, *params.keys
-                      end
-                    end
+              structure.child! do
+                params = hybrid[:neural].dup
+                field_name, query_text = params.shift 
+                structure.neural do
+                  structure.set! field_name do
+                    structure.query_text query_text
+                    structure.extract! params, *params.keys
                   end
                 end
+              end
 
-                hybrid[:query].each do |query|
-                  structure.child! do
-                    structure.extract! query, *query.keys
-                  end
-                end
+              structure.child! do
+                hybrid_query = hybrid[:query].dup
+                structure.extract! hybrid_query, *hybrid_query.keys
+              end
 
             end
           end unless hybrid.nil?
@@ -179,8 +196,8 @@ module Stretchy
           end unless neural.blank?
 
           structure.regexp do
-            build_regexp unless regexes.nil?
-          end
+            build_regexp 
+          end unless regexes.nil?
 
           structure.bool do
 
@@ -202,7 +219,7 @@ module Stretchy
 
       def build_regexp
         regexes.each do |args|
-            target_field = args.first.keys.first
+            target_field = keyword_transformer.transform(args.first.keys.first.to_s)
             value_field = args.first.values.first
             structure.set! target_field, args.last.merge(value: value_field)
         end
@@ -257,10 +274,10 @@ module Stretchy
         end
       end
 
-      def build_aggregations
-        structure.aggregations do
-          aggregations.each do |agg|
-            structure.set! agg[:name], aggregation(agg[:name], keyword_transformer.transform(agg[:args], :name))
+      def build_aggregations(aggregation_args, aggregation_structure)
+        aggregation_structure.aggregations do
+          aggregation_args.each do |agg|
+            aggregation_structure.set! agg[:name], aggregation(agg[:name], keyword_transformer.transform(agg[:args], :aggs, :aggregations))
           end
         end
       end
@@ -280,7 +297,7 @@ module Stretchy
 
       def extra_search_options
         unless self.count?
-          values[:size] = size.present? ? size : values[:default_size]
+          values[:size] = size.present? ? size : default_size
         else 
           values[:size] = nil
         end
@@ -290,7 +307,7 @@ module Stretchy
       def compact_where(q, opts = {bool:true})
         return if q.nil?
         if opts.delete(:bool)
-          as_must(q)
+          as_must([merge_and_append(q)])
         else
           as_query_string(q.flatten)
         end
@@ -301,10 +318,16 @@ module Stretchy
         q.each do |arg|
           case arg
           when Hash
-            arg = keyword_transformer.transform(arg)
+            arg = keyword_transformer.transform(arg, :match)
             arg.each_pair do |k,v| 
-              # If v is an array, we build a terms query otherwise a term query
-              _must << (v.is_a?(Array) ? {terms: Hash[k,v]} : {term: Hash[k,v]}) 
+              if k == :match
+                v.each do |field, value|
+                  _must << (field.is_a?(Hash) ? { k => field} : { k => {field => value}})
+                end
+              else
+                # If v is an array, we build a terms query otherwise a term query
+                _must << (v.is_a?(Array) ? {terms: Hash[k,v]} : {term: Hash[k,v]}) 
+              end
             end
           when String
             _must << {term: Hash[[arg.split(/:/).collect(&:strip)]]}
@@ -323,12 +346,30 @@ module Stretchy
 
         q.each do |arg|
           arg.each_pair { |k,v|  _and << "(#{k}:#{v})" } if arg.class == Hash
-          _and << "(#{arg})" if arg.class == String
+          if q.length == 1
+            _and << "#{arg}" if arg.class == String
+          else
+            _and << "(#{arg})" if arg.class == String
+          end
         end
         _and.join(" AND ")
       end
 
-
+      def merge_and_append(queries)
+        result = {}
+        queries.each do |hash|
+          hash.each do |key, value|
+            if result[key].is_a?(Array)
+              result[key] << value
+            elsif result.key?(key)
+              result[key] = [result[key], value]
+            else
+              result[key] = value
+            end
+          end
+        end
+        result
+      end
 
       def extract_highlighter(highlighter)
         Jbuilder.new do |highlight|
@@ -350,12 +391,17 @@ module Stretchy
       end
 
       def aggregation(name, opts = {})
-        Jbuilder.new do |agg|
+        Jbuilder.new do |agg_structure|
           case
           when opts.is_a?(Hash)
-              agg.extract! opts, *opts.keys
+              nested_agg = opts.delete(:aggs) || opts.delete(:aggregations)
+
+              agg_structure.extract! opts, *opts.keys
+
+              build_aggregations(nested_agg.map {|d| {:name => d.first, :args => d.last } }, agg_structure) if nested_agg
+                
           when opts.is_a?(Array)
-              extract_filter_arguments_from_array(agg, opts)
+              extract_filter_arguments_from_array(agg_structure, opts)
           else
             raise "#aggregation only accepts Hash or Array"
           end

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

@@ -0,0 +1,19 @@
+module Stretchy
+  module Relations
+    module QueryMethods
+      module Bind
+        extend ActiveSupport::Concern
+        def bind(value)
+          spawn.bind!(value)
+        end
+
+        def bind!(value) # :nodoc:
+          self.bind_values += [value]
+          self
+        end
+
+        QueryMethods.register!(:bind)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+module Stretchy
+  module Relations
+    module QueryMethods
+      module Extending
+        extend ActiveSupport::Concern
+        def extending(*modules, &block)
+          if modules.any? || block
+            spawn.extending!(*modules, &block)
+          else
+            self
+          end
+        end
+
+        def extending!(*modules, &block) # :nodoc:
+          modules << Module.new(&block) if block
+          modules.flatten!
+
+          self.extending_values += modules
+          extend(*extending_values) if extending_values.any?
+
+          self
+        end
+
+        QueryMethods.register!(:extending)
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,70 @@
+module Stretchy
+  module Relations
+    module QueryMethods
+      module Fields
+        extend ActiveSupport::Concern
+        
+        # Specify the fields to be returned by the Elasticsearch query.
+        #
+        # This method accepts a variable number of arguments, each of which is the name of a field to be returned.
+        # If no arguments are provided, all fields are returned.
+        #
+        # To retrieve specific fields in the search response, use the fields parameter. 
+        # Because it consults the index mappings, the fields parameter provides several advantages over referencing 
+        # the `_source` directly. Specifically, the fields parameter:
+        #   Returns each value in a standardized way that matches its mapping type
+        #   Accepts multi-fields and field aliases
+        #   Formats dates and spatial data types
+        #   Retrieves runtime field values
+        #   Returns fields calculated by a script at index time
+        #   Returns fields from related indices using lookup runtime fields
+        #
+        # ### Parameters
+        # - `args:` The Array of field names to be returned by the query (default: []).
+        #
+        # ### Returns
+        # Returns a new Stretchy::Relation with the specified fields to be returned.
+        #
+        # ---
+        #
+        # ### Examples
+        #
+        # #### Single field
+        # ```ruby
+        #   Model.fields(:title)
+        # ```
+        #
+        # #### Multiple fields
+        # ```ruby
+        #   Model.fields(:title, :author)
+        # ```
+        #
+        # #### Nested fields
+        # ```ruby
+        #   Model.fields('author.name', 'author.age')
+        # ```
+        #
+        # #### Wildcard
+        # ```ruby
+        #   Model.fields('books.*')
+        # ```
+        #
+        def fields(*args)
+          spawn.field!(*args)
+        end
+
+        # Alias for {#field}
+        # @see #field
+        alias :field :fields
+
+        def field!(*args) # :nodoc:
+          self.fields_values += args
+          self
+        end
+
+        QueryMethods.register!(:field, :fields)
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+module Stretchy
+  module Relations
+    module QueryMethods
+      module FilterQuery
+        extend ActiveSupport::Concern
+
+        # Adds a filter to the Elasticsearch query.
+        #
+        # This method is used to filter the results of a query without affecting the score. It accepts a type and a condition.
+        # The type can be any valid Elasticsearch filter type, such as `:term`, `:range`, or `:bool`. The condition is a hash
+        # that specifies the filter conditions.
+        #
+        # ### Parameters
+        # - `type:` The Symbol representing the filter type.
+        # - `condition:` The Hash containing the filter conditions.
+        #
+        # ### Returns
+        # Returns a new Stretchy::Relation with the specified filter applied.
+        #
+        # ---
+        #
+        # ### Examples
+        #
+        # #### Term filter
+        # ```ruby
+        #   Model.filter_query(:term, color: 'blue')
+        # ```
+        #
+        # #### Range filter
+        # ```ruby
+        #   Model.filter_query(:range, age: { gte: 21 })
+        # ```
+        #
+        # #### Bool filter
+        # ```ruby
+        #   Model.filter_query(:bool, must: [{ term: { color: 'blue' } }, { range: { age: { gte: 21 } } }])
+        # ```
+        #
+        def filter_query(name, options = {}, &block)
+          spawn.filter_query!(name, options, &block)
+        end
+
+        def filter_query!(name, options = {}, &block) # :nodoc:
+          self.filter_query_values += [{name: name, args: options}]
+          self
+        end
+
+        QueryMethods.register!(:filter_query)
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+module Stretchy
+  module Relations
+    module QueryMethods
+      module HasField
+        extend ActiveSupport::Concern
+
+        # Checks if a field exists in the Elasticsearch document.
+        #
+        # This method is used to filter the results of a query based on whether a field exists or not in the document.
+        # It accepts a field name as an argument and adds an `exists` filter to the query.
+        #
+        # ### Parameters
+        # - `field:` The Symbol or String representing the field name.
+        #
+        # ### Returns
+        # Returns a new Stretchy::Relation with the `exists` filter applied.
+        #
+        # ---
+        #
+        # ### Examples
+        #
+        # #### Has field
+        # ```ruby
+        #   Model.has_field(:title)
+        # ```
+        #
+        # #### Nested field exists
+        # ```ruby
+        #   Model.has_field('author.name')
+        # ```
+        #
+        def has_field(field)
+          spawn.filter_query(:exists, {field: field})
+        end
+
+        QueryMethods.register!(:has_field)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,75 @@
+module Stretchy
+  module Relations
+    module QueryMethods
+      module Highlight
+        extend ActiveSupport::Concern
+        # Highlights search results on one or more fields.
+        #
+        # This method is used to highlight search results on one or more fields. The fields that match the user query get
+        # highlighted. It accepts a variable number of arguments, each of which is the name of a field to be highlighted.
+        #
+        # ### Parameters
+        #
+        # - `field:` The Symbol of a field name to be highlighted by the query or a series of keyword hashes with the field name as the key and the highlight options as the value
+        # - `options:` The Hash of highlight options
+        #      - `boundary_chars:` The String of the boundary characters (default: ".,!? \t\n")
+        #      - `boundary_max_scan:` The Integer of the maximum number of characters to scan to find the boundary characters (default: 20)
+        #      - `boundary_scanner:` The String of the boundary scanner type (default: "sentence")
+        #      	- "sentence" Breaks text into sentences
+        #       - "word" Breaks text into words
+        #       - "char" Breaks text into characters
+        #      - `boundary_scanner_locale:` The String of the locale for the boundary scanner (default: "en-US")
+        #      - `encoder:` The String of the encoder type (default: "default").
+        #      - `fragmenter:` The String of the fragmenter type (default: "simple").
+        #      - `force_source:` The Boolean to force highlighting on the source (default: false).
+        #      - `fragment_offset:` The Integer of the number of characters to offset the fragment (default: 0).
+        #      - `fragment_size:` The Integer of the number of characters in a fragment (default: 100).
+        #      - `highlight_query:` The Hash of highlight query options (default: {}).
+        #      - `matched_fields:` The Array of fields to be highlighted (default: []).
+        #      - `no_match_size:` The Integer of the number of characters to return if no matches are found (default: 150).
+        #      - `number_of_fragments:` The Integer of the number of fragments to return (default: 5).
+        #      - `order:` The String of the order of the highlighted fragments (default: "score").
+        #      - `phrase_limit:` The Integer of the maximum number of phrases to highlight (default: 256).
+        #      - `pre_tags:` The String or Array of Strings to be used as the pre-highlight tags (default: "<em>").
+        #      - `post_tags:` The String or Array of Strings to be used as the post-highlight tags (default: "</em>").
+        #      - `require_field_match:` The Boolean to require field matching (default: true).
+        #      - `max_analyzed_offset:` The Integer of the maximum number of characters to analyze (default: 1000000).
+        #      - `tags_schema:` The String of the tags schema (default: "styled").
+        #      - `type:` The String of the highlight type (default: "unified").
+        #         * "unified" - Highlights fields based on the Unified Highlighter.
+        #         * "plain" - Highlights fields based on the Plain Highlighter.
+        #         * "fvh" - Highlights fields based on the Fast Vector Highlighter.
+        #
+        # ### Returns
+        # Returns a new Stretchy::Relation with the specified fields to be highlighted.
+        #
+        # ---
+        #
+        # ### Examples
+        #
+        # #### Single field
+		#
+        # ```
+        #  Model.query_string("body:Cat OR Lion").highlight(:body)
+        # ```
+		#
+        # ### Custom highlight options
+		#
+        # ```ruby
+        #  Model.query_string("name: Soph*").highlight(name: {pre_tags: "__", post_tags: "__"})
+		# ```
+        #
+        def highlight(*args)
+          spawn.highlight!(*args)
+        end
+
+        def highlight!(*args) # :nodoc:
+          self.highlight_values += args
+          self
+        end
+
+        QueryMethods.register!(:highlight)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,60 @@
+module Stretchy
+  module Relations
+    module QueryMethods
+      module Hybrid
+        extend ActiveSupport::Concern
+        # Perform a hybrid search using both neural and traditional queries.
+        #
+        # The `hybrid` method accepts two parameters: `neural` and `query`, both of which are arrays.
+        # The `neural` array should contain hashes representing neural queries, with each hash containing
+        # The `query` array should contain hashes representing traditional queries.
+        #
+        # ### Parameters
+        #
+        # - `opts:` The Hash options used to refine the selection (default: {}):
+        #     - `:neural:` The Array of neural queries (default: []).
+        #     - `:query:` The Array of traditional queries (default: []).
+        #         Each element is a Hash representing a traditional query.
+        #
+        # ### Returns
+        # Returns a new relation with the hybrid search applied.
+        #
+        # ---
+        #
+        # ### Examples
+        #
+        # #### Hybrid search
+        #
+        # ```ruby
+        #   Model.hybrid(
+        #     neural: [
+        #      {
+        #         passage_embedding: 'hello world', 
+        #         model_id: '1234', 
+        #         k: 2
+        #      }
+        #     ], 
+        #     query: [
+        #       {
+        #         term: {
+        #           status: :active
+        #           }
+        #         }
+        #       ]
+        #     )
+        # ```
+        #
+        def hybrid(opts)
+          spawn.hybrid!(opts)
+        end
+
+        def hybrid!(opts) # :nodoc:
+          self.hybrid_values = opts
+          self
+        end
+
+        QueryMethods.register!(:hybrid)
+      end
+    end
+  end
+end