search-engine-for-typesense 30.1.6.18 → 30.1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01b787168b6ef3694f27552da317fa390eaee171bf0734d94725b4527a883968
-  data.tar.gz: 28b30b42639215b992ce6b152bd9c076dc5dc221f6c9a18be5f2355aa7c63865
+  metadata.gz: 9eea6beb086957bbee9df77008a70750be3a74f6f39a53be361a3f1ae8295219
+  data.tar.gz: 0eaf79b97f1c68b7bdab350f11cbfe09eecfb4944c76fd5c49528b68e63a5f09
 SHA512:
-  metadata.gz: f5229d42405c66d0811102f31654631d8654bd52bdd55605f12f6baf446c2d61428d95a3f6a0c56a05b6dc4b404a68d3772ee13d4a1ca6a1739efd3de2f93390
-  data.tar.gz: faf42770cec8639077c6efae5e0f1599d1d9eabba0b3fdab23149a5a334ba3a3f50cc1156940bbb8b373f95b695f3e70457370687a774e39c0d2934b9f4cc07a
+  metadata.gz: ab9dd851d14c4a7019902afad59af281623576952ade57dd2a7df7d458caf68a3f432ac742873b52bc94fd8a88b14ef8715807d7ab3d7d7fd44cc05765424489
+  data.tar.gz: 546d394202e194705c24f1c2584b57239bca5e1084d299a3c801fc2781c480d666e47e2906992e6885c788a12ec9162c57e18b1e7eb88e65e93d2a661a2d27f3

data/README.md

@@ -116,6 +116,36 @@ SearchEngine::Product.upsert_bulk(records: Product.limit(2))
 
 # Bulk upsert mapped payloads
 SearchEngine::Product.upsert_bulk(data: [mapped])
+
+# Geo search
+class SearchEngine::Venue < SearchEngine::Base
+  collection :venues
+  identify_by :id
+
+  attribute :name, :string
+  attribute :location, :geopoint
+end
+
+# Filter by radius
+SearchEngine::Venue
+  .where_geo(:location, within_radius: { lat: 54.69, lng: 25.28, radius: "10 km" })
+  .order_geo(:location, from: { lat: 54.69, lng: 25.28 })
+  .to_a
+
+# Filter by polygon (viewport)
+SearchEngine::Venue
+  .where_geo(:location, within_polygon: [[54.72, 25.35], [54.72, 25.22], [54.67, 25.22], [54.67, 25.35]])
+  .to_a
+
+# Viewport boost with _eval() + distance tiebreaker
+SearchEngine::Venue
+  .order_eval("location:(54.72,25.35, 54.72,25.22, 54.67,25.22, 54.67,25.35)", direction: :desc)
+  .order_geo(:location, from: { lat: 54.69, lng: 25.28 })
+  .to_a
+
+# Access geo distance on results (present when order_geo is used)
+result = SearchEngine::Venue.all.order_geo(:location, from: { lat: 54.69, lng: 25.28 }).execute
+result.hits.first.geo_distance_meters # => { "location" => 1234 }
 ```
 
 ## Documentation

data/lib/search_engine/active_record_syncable.rb

@@ -235,10 +235,21 @@ module SearchEngine
       end
 
       actions = cfg[:actions]
+      timing = begin
+        SearchEngine.config.syncable_callback_timing
+      rescue StandardError
+        :after_commit
+      end
 
-      ar_klass.after_create :__se_syncable_upsert! if actions.include?(:create)
-      ar_klass.after_update :__se_syncable_upsert! if actions.include?(:update)
-      ar_klass.after_destroy :__se_syncable_delete! if actions.include?(:destroy)
+      if timing == :after_commit
+        ar_klass.after_create_commit :__se_syncable_upsert! if actions.include?(:create)
+        ar_klass.after_update_commit :__se_syncable_upsert! if actions.include?(:update)
+        ar_klass.after_destroy_commit :__se_syncable_delete! if actions.include?(:destroy)
+      else
+        ar_klass.after_create :__se_syncable_upsert! if actions.include?(:create)
+        ar_klass.after_update :__se_syncable_upsert! if actions.include?(:update)
+        ar_klass.after_destroy :__se_syncable_delete! if actions.include?(:destroy)
+      end
 
       ar_klass.instance_variable_set(:@__se_syncable_callbacks_installed__, true)
       nil

data/lib/search_engine/config.rb

@@ -56,6 +56,10 @@ module SearchEngine
     #   @return [String, nil, false] path to host app SearchEngine models directory. May be
     #     relative to `Rails.root` (e.g., "app/search_engine") or absolute. When `nil` or
     #     `false`, gem-managed loading of host SearchEngine models is disabled.
+    # @!attribute [rw] syncable_callback_timing
+    #   @return [Symbol] controls ActiveRecordSyncable callback timing.
+    #     +:after_commit+ (default) uses +after_*_commit+ callbacks (safe, post-transaction).
+    #     +:after_save+ uses legacy +after_*+ callbacks (in-transaction).
     attr_accessor :logger,
                   :default_query_by,
                   :default_infix,
@@ -67,7 +71,8 @@ module SearchEngine
                   :client,
                   :default_console_model,
                   :search_engine_models,
-                  :relation_print_materializes
+                  :relation_print_materializes,
+                  :syncable_callback_timing
 
     # Lightweight nested configuration for schema lifecycle.
     class SchemaConfig
@@ -402,6 +407,9 @@ module SearchEngine
       @search_engine_models = 'app/search_engine'
       # When true, Relation#inspect/pretty_print materialize a preview (AR-like).
       @relation_print_materializes = true
+      # Controls whether ActiveRecordSyncable uses after_*_commit (safe, default)
+      # or after_* (legacy in-transaction) callbacks. Values: :after_commit, :after_save.
+      @syncable_callback_timing = :after_commit
     end
 
     # Whether the engine should avoid network I/O and use an offline client.
@@ -701,7 +709,8 @@ module SearchEngine
         presets: presets_hash_for_to_h,
         curation: curation_hash_for_to_h,
         embedding: embedding_hash_for_to_h,
-        relation_print_materializes: relation_print_materializes ? true : false
+        relation_print_materializes: relation_print_materializes ? true : false,
+        syncable_callback_timing: syncable_callback_timing
       }
     end
 

data/lib/search_engine/relation/dsl/eval.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module SearchEngine
+  class Relation
+    module DSL
+      # Typesense `_eval()` conditional sort expressions.
+      # Mixed into Relation's DSL; preserves copy-on-write semantics.
+      module Eval
+        # Sort by a Typesense `_eval()` conditional expression.
+        #
+        # Accepts a plain filter-syntax string (simple form) or an Array of
+        # `{ expr:, weight: }` hashes (weighted multi-expression form).
+        #
+        # @param expression [String, Array<Hash>] filter expression(s)
+        # @param direction [Symbol] `:desc` (default, matches first) or `:asc`
+        # @return [SearchEngine::Relation]
+        def order_eval(expression, direction: :desc)
+          dir = direction.to_s.downcase
+          unless %w[asc desc].include?(dir)
+            raise ArgumentError, "order_eval: direction must be :asc or :desc (got #{direction.inspect})"
+          end
+
+          sort_token = case expression
+                       when String
+                         raise ArgumentError, 'order_eval: expression must not be blank' if expression.strip.empty?
+
+                         "_eval(#{expression}):#{dir}"
+                       when Array
+                         validate_weighted_expressions!(expression)
+                         weighted = expression.map { |e| "(#{e[:expr]}):#{e[:weight]}" }.join(', ')
+                         "_eval([ #{weighted} ]):#{dir}"
+                       else
+                         raise ArgumentError,
+                               'order_eval: expression must be a String or Array of { expr:, weight: }'
+                       end
+
+          spawn do |s|
+            existing = Array(s[:orders])
+            s[:orders] = dedupe_orders_last_wins(existing + [sort_token])
+          end
+        end
+
+        private
+
+        def validate_weighted_expressions!(expressions)
+          unless expressions.is_a?(Array) && !expressions.empty? && expressions.all? { |e| e.is_a?(Hash) }
+            raise ArgumentError, 'order_eval: weighted form expects a non-empty Array of { expr:, weight: }'
+          end
+
+          expressions.each_with_index do |entry, i|
+            unless entry[:expr].is_a?(String) && !entry[:expr].strip.empty?
+              raise ArgumentError, "order_eval: entry #{i} must have a non-blank :expr"
+            end
+            unless entry[:weight].is_a?(Integer) && entry[:weight].positive?
+              raise ArgumentError, "order_eval: entry #{i} :weight must be a positive Integer"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/search_engine/relation/dsl/geo.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module SearchEngine
+  class Relation
+    module DSL
+      # Geo search chainers: filtering by radius/polygon and geo distance sorting.
+      # Mixed into Relation's DSL; preserves copy-on-write semantics.
+      # See DSL::Eval for `_eval()`-based conditional sort expressions.
+      module Geo
+        # Filter by geographic proximity (radius) or containment (polygon).
+        #
+        # @param field [Symbol, String] a `:geopoint` or `[:geopoint]` attribute
+        # @param within_radius [Hash, nil] `{ lat:, lng:, radius: "10 km" }`
+        # @param within_polygon [Array<Array(Numeric,Numeric)>, nil] three or more `[lat, lng]` pairs
+        # @return [SearchEngine::Relation]
+        def where_geo(field, within_radius: nil, within_polygon: nil)
+          validate_geo_field!(field)
+          validate_geo_predicate_exclusivity!(within_radius, within_polygon)
+
+          fragment = if within_radius
+                       build_radius_filter(field, within_radius)
+                     else
+                       build_polygon_filter(field, within_polygon)
+                     end
+
+          spawn do |s|
+            s[:ast] = Array(s[:ast]) + [SearchEngine::AST.raw(fragment)]
+            s[:filters] = Array(s[:filters])
+          end
+        end
+
+        # Sort by geographic distance from a reference point.
+        #
+        # @param field [Symbol, String] a `:geopoint` or `[:geopoint]` attribute
+        # @param from [Hash] `{ lat:, lng: }` — the reference point
+        # @param direction [Symbol] `:asc` (nearest first, default) or `:desc`
+        # @param exclude_radius [String, nil] e.g. `"2 km"` — exclude results within this radius from distance scoring
+        # @param precision [String, nil] e.g. `"1 km"` — bucket precision for distance sort
+        # @return [SearchEngine::Relation]
+        def order_geo(field, from:, direction: :asc, exclude_radius: nil, precision: nil)
+          validate_geo_field!(field, context: 'order_geo')
+
+          lat = from[:lat]
+          lng = from[:lng]
+          validate_geo_coordinate!(lat, lng, context: 'order_geo')
+
+          dir = direction.to_s.downcase
+          unless %w[asc desc].include?(dir)
+            raise ArgumentError, "order_geo: direction must be :asc or :desc (got #{direction.inspect})"
+          end
+
+          sort_token = build_geo_sort_token(field, lat, lng, dir, exclude_radius, precision)
+
+          spawn do |s|
+            existing = Array(s[:orders])
+            s[:orders] = dedupe_orders_last_wins(existing + [sort_token])
+          end
+        end
+
+        private
+
+        def validate_geo_field!(field, context: 'where_geo')
+          attrs = safe_attributes_map
+          return unless attrs && !attrs.empty?
+
+          type = attrs[field.to_sym]
+          return if [:geopoint, [:geopoint]].include?(type)
+
+          raise ArgumentError,
+                "#{context}: field :#{field} must be declared as :geopoint or [:geopoint]"
+        end
+
+        def validate_geo_predicate_exclusivity!(within_radius, within_polygon)
+          if within_radius.nil? && within_polygon.nil?
+            raise ArgumentError, 'where_geo: provide either within_radius: or within_polygon:'
+          end
+          return unless within_radius && within_polygon
+
+          raise ArgumentError, 'where_geo: within_radius: and within_polygon: are mutually exclusive'
+        end
+
+        def validate_geo_coordinate!(lat, lng, context: 'where_geo')
+          unless lat.is_a?(Numeric) && lat >= -90 && lat <= 90
+            raise ArgumentError, "#{context}: lat must be a number in [-90, 90] (got #{lat.inspect})"
+          end
+          return if lng.is_a?(Numeric) && lng >= -180 && lng <= 180
+
+          raise ArgumentError, "#{context}: lng must be a number in [-180, 180] (got #{lng.inspect})"
+        end
+
+        def validate_radius!(radius, context: 'where_geo')
+          return if radius.is_a?(String) && radius.match?(/\A\d+(\.\d+)?\s*(km|mi)\z/)
+
+          raise ArgumentError,
+                "#{context}: radius must be a string like '10 km' or '5 mi' (got #{radius.inspect})"
+        end
+
+        def build_radius_filter(field, opts)
+          lat = opts[:lat]
+          lng = opts[:lng]
+          radius = opts[:radius]
+          validate_geo_coordinate!(lat, lng)
+          validate_radius!(radius)
+          "#{field}:(#{lat}, #{lng}, #{radius})"
+        end
+
+        def build_polygon_filter(field, points)
+          unless points.is_a?(Array) && points.size >= 3
+            raise ArgumentError, "where_geo: polygon must have >= 3 points (got #{points&.size || 0})"
+          end
+
+          points.each_with_index do |point, i|
+            unless point.is_a?(Array) && point.size == 2
+              raise ArgumentError, "where_geo: polygon point #{i} must be [lat, lng]"
+            end
+
+            validate_geo_coordinate!(point[0], point[1])
+          end
+
+          coords = points.map { |p| "#{p[0]}, #{p[1]}" }.join(', ')
+          "#{field}:(#{coords})"
+        end
+
+        def build_geo_sort_token(field, lat, lng, dir, exclude_radius, precision)
+          parts = +"#{field}(#{lat}, #{lng}"
+          if exclude_radius
+            validate_radius!(exclude_radius, context: 'order_geo')
+            parts << ", exclude_radius: #{exclude_radius}"
+          end
+          if precision
+            validate_radius!(precision, context: 'order_geo')
+            parts << ", precision: #{precision}"
+          end
+          "#{parts}):#{dir}"
+        end
+      end
+    end
+  end
+end

data/lib/search_engine/relation/dsl.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
+require 'search_engine/relation/dsl/eval'
 require 'search_engine/relation/dsl/filters'
+require 'search_engine/relation/dsl/geo'
 require 'search_engine/relation/dsl/selection'
 require 'search_engine/relation/dsl/vectors'
 
@@ -9,7 +11,9 @@ module SearchEngine
     # User-facing chainers and input normalizers.
     # Chainers MUST be copy-on-write and return new Relation instances.
     module DSL
+      include SearchEngine::Relation::DSL::Eval
       include SearchEngine::Relation::DSL::Filters
+      include SearchEngine::Relation::DSL::Geo
       include SearchEngine::Relation::DSL::Selection
       include SearchEngine::Relation::DSL::Vectors
 

data/lib/search_engine/result.rb

@@ -94,6 +94,7 @@ module SearchEngine
 
           obj = hydrate(entry[:document])
           attach_highlighting!(obj, entry)
+          attach_geo_distance!(obj, entry)
           hydrated << obj
         end
         @hits = hydrated.freeze
@@ -284,6 +285,16 @@ module SearchEngine
       end
     end
 
+    # Per-hit geo distance mixin: added onto hydrated objects when Typesense
+    # returns geo_distance_meters metadata (present when sort_by includes a
+    # geopoint distance sort).
+    module GeoDistance
+      # @return [Hash{String=>Numeric}, nil] mapping of geo field name to distance in meters
+      def geo_distance_meters
+        instance_variable_get(:@__se_geo_distance__)&.dup
+      end
+    end
+
     def parse_facets
       @__facets_parsed_memo || {}.freeze
     end
@@ -389,7 +400,9 @@ module SearchEngine
           next unless doc
 
           obj = hydrate(doc)
-          attach_highlighting!(obj, symbolize_hit(sub))
+          sym_sub = symbolize_hit(sub)
+          attach_highlighting!(obj, sym_sub)
+          attach_geo_distance!(obj, sym_sub)
           hydrated << obj
         end
 
@@ -533,6 +546,17 @@ module SearchEngine
       obj
     end
 
+    def attach_geo_distance!(obj, hit_entry)
+      raw_geo = hit_entry[:geo_distance_meters]
+      return obj unless raw_geo.is_a?(Hash) && !raw_geo.empty?
+
+      obj.extend(GeoDistance) unless obj.singleton_class.included_modules.include?(GeoDistance)
+      obj.instance_variable_set(:@__se_geo_distance__, raw_geo)
+      obj
+    rescue StandardError
+      obj
+    end
+
     def safe_highlight_ctx
       ctx = @highlight_ctx || {}
       return {} unless ctx.is_a?(Hash)

data/lib/search_engine/schema.rb

@@ -31,7 +31,8 @@ module SearchEngine
       datetime: 'int64',
       time_string: 'string',
       datetime_string: 'string',
-      vector: 'float[]'
+      vector: 'float[]',
+      geopoint: 'geopoint'
     }.freeze
 
     FIELD_COMPARE_KEYS = %i[
@@ -818,11 +819,13 @@ module SearchEngine
         s = type_string.to_s
         return 'string[]' if s.casecmp('string[]').zero?
         return 'float[]' if s.casecmp('float[]').zero?
+        return 'geopoint[]' if s.casecmp('geopoint[]').zero?
         return 'int64' if s.casecmp('int64').zero?
         return 'int32' if s.casecmp('int32').zero?
         return 'float' if s.casecmp('float').zero?
         return 'bool' if %w[bool boolean].include?(s.downcase)
         return 'string' if s.casecmp('string').zero?
+        return 'geopoint' if s.casecmp('geopoint').zero?
 
         # Fallback: return as-is
         s

data/lib/search_engine/version.rb

@@ -3,5 +3,5 @@
 module SearchEngine
   # Current gem version.
   # @return [String]
-  VERSION = '30.1.6.18'
+  VERSION = '30.1.7.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: search-engine-for-typesense
 version: !ruby/object:Gem::Version
-  version: 30.1.6.18
+  version: 30.1.7.0
 platform: ruby
 authors:
 - Nikita Shkoda
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-04-27 00:00:00.000000000 Z
+date: 2026-05-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -178,7 +178,9 @@ files:
 - lib/search_engine/relation/compiler.rb
 - lib/search_engine/relation/deletion.rb
 - lib/search_engine/relation/dsl.rb
+- lib/search_engine/relation/dsl/eval.rb
 - lib/search_engine/relation/dsl/filters.rb
+- lib/search_engine/relation/dsl/geo.rb
 - lib/search_engine/relation/dsl/selection.rb
 - lib/search_engine/relation/dsl/vectors.rb
 - lib/search_engine/relation/dx.rb