search-engine-for-typesense 30.1.6.17 → 30.1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1bd17994c46590322f8d32265bf5f1a5ae91be3b911a120c48730ba6339fb9e3
-  data.tar.gz: e7d9785f65c500ddffaef1898b8620c13142ade4f737d6b93f7f1b88a31ee582
+  metadata.gz: 9eea6beb086957bbee9df77008a70750be3a74f6f39a53be361a3f1ae8295219
+  data.tar.gz: 0eaf79b97f1c68b7bdab350f11cbfe09eecfb4944c76fd5c49528b68e63a5f09
 SHA512:
-  metadata.gz: 744c09d6abd7bce828543b0cd11bb354d94cdff2c17a89d690efd25948993901341c0177890e07256e0b1a9e376925f6ed790c1b5ad64f629e68a99dca9b6ad9
-  data.tar.gz: aee5a996ae1f5075533786e58347e0771737ecc8278cd25b380df7b8c21b6ea917e052a9ad34216eab7f6a2b8a80c90e6701241843eb9698572f1adc9fd201c1
+  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/base/index_maintenance/cleanup.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'active_support/concern'
+require 'search_engine/logging/output'
 
 module SearchEngine
   class Base
@@ -44,13 +45,15 @@ module SearchEngine
           # @return [Integer] number of deleted documents
           def cleanup(into: nil, partition: nil, clear_cache: false)
             logical = respond_to?(:collection) ? collection.to_s : name.to_s
-            puts
-            puts(SearchEngine::Logging::Color.header(%(>>>>>> Cleanup Collection "#{logical}")))
+            SearchEngine::Logging::Output.puts
+            SearchEngine::Logging::Output.puts(
+              SearchEngine::Logging::Color.header(%(>>>>>> Cleanup Collection "#{logical}"))
+            )
 
             filters = SearchEngine::StaleRules.compile_filters(self, partition: partition)
             filters.compact!
             filters.reject! { |f| f.to_s.strip.empty? }
-            step = SearchEngine::Logging::StepLine.new('Cleanup')
+            step = SearchEngine::Logging::StepLine.new('Cleanup', io: SearchEngine::Logging::Output.io)
             if filters.empty?
               step.skip('no stale configuration')
               return 0
@@ -76,14 +79,14 @@ module SearchEngine
             step&.close
             if clear_cache
               begin
-                puts("Cleanup — #{SearchEngine::Logging::Color.bold('cache clear')}")
+                SearchEngine::Logging::Output.puts("Cleanup — #{SearchEngine::Logging::Color.bold('cache clear')}")
                 SearchEngine::Cache.clear
               rescue StandardError => error
                 err_msg = "Cleanup — cache clear error=#{error.class}: #{error.message.to_s[0, 200]}"
                 warn(SearchEngine::Logging::Color.apply(err_msg, :red))
               end
             end
-            puts(SearchEngine::Logging::Color.header(%(>>>>>> Cleanup Done)))
+            SearchEngine::Logging::Output.puts(SearchEngine::Logging::Color.header(%(>>>>>> Cleanup Done)))
           end
 
           private

data/lib/search_engine/base/index_maintenance/lifecycle.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'search_engine/logging/output'
+
 module SearchEngine
   class Base
     module IndexMaintenance
@@ -16,8 +18,10 @@ module SearchEngine
           # @return [Hash, nil] result hash with :status, :docs_total, :success_total, :failed_total, :sample_error
           def index_collection(partition: nil, client: nil, pre: nil, force_rebuild: false)
             logical = respond_to?(:collection) ? collection.to_s : name.to_s
-            puts
-            puts(SearchEngine::Logging::Color.header(%(>>>>>> Indexing Collection "#{logical}")))
+            SearchEngine::Logging::Output.puts
+            SearchEngine::Logging::Output.puts(
+              SearchEngine::Logging::Color.header(%(>>>>>> Indexing Collection "#{logical}"))
+            )
             client_obj = client || SearchEngine.client
 
             result = if partition.nil?
@@ -56,7 +60,7 @@ module SearchEngine
 
             diff = SearchEngine::Schema.diff(self, client: client)[:diff] || {}
             missing = __se_schema_missing?(diff)
-            step = SearchEngine::Logging::StepLine.new('Presence')
+            step = SearchEngine::Logging::StepLine.new('Presence', io: SearchEngine::Logging::Output.io)
             missing ? step.finish_warn('missing') : step.finish('present')
 
             applied, indexed_inside_apply = __se_full_apply_if_missing(client, missing)
@@ -76,7 +80,7 @@ module SearchEngine
           def __se_full_apply_if_missing(client, missing)
             applied = false
             indexed_inside_apply = false
-            step = SearchEngine::Logging::StepLine.new('Schema')
+            step = SearchEngine::Logging::StepLine.new('Schema', io: SearchEngine::Logging::Output.io)
             if missing
               step.update('creating')
               begin
@@ -100,7 +104,7 @@ module SearchEngine
           end
 
           def __se_full_check_drift(diff, missing, force_rebuild)
-            step = SearchEngine::Logging::StepLine.new('Schema Status')
+            step = SearchEngine::Logging::StepLine.new('Schema Status', io: SearchEngine::Logging::Output.io)
             unless missing
               step.update('checking')
               drift = __se_schema_drift?(diff)
@@ -118,7 +122,7 @@ module SearchEngine
           end
 
           def __se_full_apply_if_drift(client, drift, applied, indexed_inside_apply, force_rebuild)
-            step = SearchEngine::Logging::StepLine.new('Schema Apply')
+            step = SearchEngine::Logging::StepLine.new('Schema Apply', io: SearchEngine::Logging::Output.io)
             if drift
               step.update('applying')
               begin
@@ -143,7 +147,7 @@ module SearchEngine
 
           def __se_full_indexation(applied, indexed_inside_apply)
             result = nil
-            step = SearchEngine::Logging::StepLine.new('Indexing')
+            step = SearchEngine::Logging::StepLine.new('Indexing', io: SearchEngine::Logging::Output.io)
             if applied && indexed_inside_apply
               result = indexed_inside_apply if indexed_inside_apply.is_a?(Hash)
               if __se_result_status(result) == :ok
@@ -177,7 +181,7 @@ module SearchEngine
           end
 
           def __se_full_retention(applied, logical, client)
-            step = SearchEngine::Logging::StepLine.new('Retention')
+            step = SearchEngine::Logging::StepLine.new('Retention', io: SearchEngine::Logging::Output.io)
             if applied
               step.skip('handled by schema apply')
             else
@@ -195,7 +199,7 @@ module SearchEngine
             diff = diff_res[:diff] || {}
 
             missing = __se_schema_missing?(diff)
-            step = SearchEngine::Logging::StepLine.new('Presence')
+            step = SearchEngine::Logging::StepLine.new('Presence', io: SearchEngine::Logging::Output.io)
             if missing
               step.finish_warn('missing — collection not present, exit early')
               return { status: :failed, docs_total: 0, success_total: 0, failed_total: 0,
@@ -203,7 +207,7 @@ module SearchEngine
             end
             step.finish('present')
 
-            step = SearchEngine::Logging::StepLine.new('Schema Status')
+            step = SearchEngine::Logging::StepLine.new('Schema Status', io: SearchEngine::Logging::Output.io)
             step.update('checking')
             drift = __se_schema_drift?(diff)
             if drift
@@ -215,12 +219,13 @@ module SearchEngine
 
             __se_preflight_dependencies!(mode: pre, client: client) if pre
 
-            step = SearchEngine::Logging::StepLine.new('Partial Indexing')
+            step = SearchEngine::Logging::StepLine.new('Partial Indexing', io: SearchEngine::Logging::Output.io)
             step.update('indexing')
             step.yield_line!
 
             renderer = SearchEngine::Logging::LiveRenderer.new(
-              labels: partitions.map(&:inspect), partitions: partitions
+              labels: partitions.map(&:inspect), partitions: partitions,
+              io: SearchEngine::Logging::Output.io
             )
             renderer.start
             summaries = []
@@ -255,35 +260,30 @@ module SearchEngine
           # rubocop:disable Metrics/PerceivedComplexity, Metrics/AbcSize
           def __se_cascade_after_indexation!(context: :full)
             if SearchEngine::Instrumentation.context&.[](:bulk_suppress_cascade)
-              puts
-              puts(SearchEngine::Logging::Color.dim('>>>>>> Cascade Referencers — suppressed (bulk)'))
+              SearchEngine::Logging::Output.puts
+              SearchEngine::Logging::Output.puts(
+                SearchEngine::Logging::Color.dim('>>>>>> Cascade Referencers — suppressed (bulk)')
+              )
               return
             end
-            puts
-            puts(SearchEngine::Logging::Color.header(%(>>>>>> Cascade Referencers)))
+            SearchEngine::Logging::Output.puts
+            SearchEngine::Logging::Output.puts(
+              SearchEngine::Logging::Color.header(%(>>>>>> Cascade Referencers))
+            )
             results = SearchEngine::Cascade.cascade_reindex!(source: self, ids: nil, context: context)
             outcomes = Array(results[:outcomes])
             if outcomes.empty?
-              puts(SearchEngine::Logging::Color.dim('  none'))
+              SearchEngine::Logging::Output.puts(SearchEngine::Logging::Color.dim('  none'))
             else
               outcomes.each do |o|
                 coll = o[:collection] || o['collection']
                 mode = (o[:mode] || o['mode']).to_s
-                case mode
-                when 'partial'
-                  puts(%(  Referencer "#{coll}" → #{SearchEngine::Logging::Color.apply('partial reindex', :green)}))
-                when 'full'
-                  puts(%(  Referencer "#{coll}" → #{SearchEngine::Logging::Color.apply('full reindex', :green)}))
-                when 'skipped_unregistered'
-                  puts(SearchEngine::Logging::Color.dim(%(  Referencer "#{coll}" → skipped (unregistered))))
-                when 'skipped_cycle'
-                  puts(SearchEngine::Logging::Color.dim(%(  Referencer "#{coll}" → skipped (cycle))))
-                else
-                  puts(%(  Referencer "#{coll}" → #{mode}))
-                end
+                __se_log_cascade_outcome(coll, mode)
               end
             end
-            puts(SearchEngine::Logging::Color.header('>>>>>> Cascade Done'))
+            SearchEngine::Logging::Output.puts(
+              SearchEngine::Logging::Color.header('>>>>>> Cascade Done')
+            )
           rescue StandardError => error
             base = "Cascade — error=#{error.class}: #{error.message.to_s[0, 200]}"
             if error.respond_to?(:status) || error.respond_to?(:body)
@@ -314,6 +314,22 @@ module SearchEngine
           end
           # rubocop:enable Metrics/PerceivedComplexity, Metrics/AbcSize
 
+          def __se_log_cascade_outcome(coll, mode)
+            msg = case mode
+                  when 'partial'
+                    %(  Referencer "#{coll}" → #{SearchEngine::Logging::Color.apply('partial reindex', :green)})
+                  when 'full'
+                    %(  Referencer "#{coll}" → #{SearchEngine::Logging::Color.apply('full reindex', :green)})
+                  when 'skipped_unregistered'
+                    SearchEngine::Logging::Color.dim(%(  Referencer "#{coll}" → skipped (unregistered)))
+                  when 'skipped_cycle'
+                    SearchEngine::Logging::Color.dim(%(  Referencer "#{coll}" → skipped (cycle)))
+                  else
+                    %(  Referencer "#{coll}" → #{mode})
+                  end
+            SearchEngine::Logging::Output.puts(msg)
+          end
+
           # Raise {SearchEngine::Errors::IndexationAborted} when the result
           # from {__se_index_partitions!} indicates a non-ok status. Called
           # inside a {Schema.apply!} block to prevent the alias swap.

data/lib/search_engine/base/index_maintenance/schema.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'search_engine/logging/output'
+
 module SearchEngine
   class Base
     module IndexMaintenance
@@ -27,7 +29,7 @@ module SearchEngine
 
           def update_collection!
             client = SearchEngine.client
-            step = SearchEngine::Logging::StepLine.new('Update Collection')
+            step = SearchEngine::Logging::StepLine.new('Update Collection', io: SearchEngine::Logging::Output.io)
             step.update('analyzing diff')
             updated = SearchEngine::Schema.update!(self, client: client)
 
@@ -51,14 +53,16 @@ module SearchEngine
             physicals = __se_list_all_physicals(logical, client)
             bare_schema = client.retrieve_collection_schema(logical, timeout_ms: 10_000)
 
-            step = SearchEngine::Logging::StepLine.new('Drop Collection')
+            step = SearchEngine::Logging::StepLine.new('Drop Collection', io: SearchEngine::Logging::Output.io)
             if !has_alias && physicals.empty? && bare_schema.nil?
               step.skip('not present')
               return
             end
 
-            puts
-            puts(SearchEngine::Logging::Color.header(%(>>>>>> Dropping Collection "#{logical}")))
+            SearchEngine::Logging::Output.puts
+            SearchEngine::Logging::Output.puts(
+              SearchEngine::Logging::Color.header(%(>>>>>> Dropping Collection "#{logical}"))
+            )
 
             physicals.each do |name|
               step.update("dropping physical #{name}")
@@ -76,7 +80,9 @@ module SearchEngine
             end
 
             step.finish("done (physicals=#{physicals.size})")
-            puts(SearchEngine::Logging::Color.header(%(>>>>>> Dropped Collection "#{logical}")))
+            SearchEngine::Logging::Output.puts(
+              SearchEngine::Logging::Color.header(%(>>>>>> Dropped Collection "#{logical}"))
+            )
             nil
           ensure
             step&.close
@@ -110,7 +116,7 @@ module SearchEngine
             physicals = __se_list_all_physicals(logical, client)
             bare_schema = client.retrieve_collection_schema(logical)
 
-            step = SearchEngine::Logging::StepLine.new('Recreate Collection')
+            step = SearchEngine::Logging::StepLine.new('Recreate Collection', io: SearchEngine::Logging::Output.io)
             if has_alias || physicals.any? || bare_schema
               step.update("dropping existing (logical=#{logical})")
               physicals.each { |name| client.delete_collection(name) }

data/lib/search_engine/base/index_maintenance.rb

@@ -8,6 +8,7 @@ require 'search_engine/logging/color'
 require 'search_engine/logging/batch_line'
 require 'search_engine/logging/step_line'
 require 'search_engine/logging/live_renderer'
+require 'search_engine/logging/output'
 
 module SearchEngine
   class Base
@@ -43,11 +44,11 @@ module SearchEngine
           return if deps.empty?
 
           indent = '  ' * depth
-          puts if depth.zero?
+          SearchEngine::Logging::Output.puts if depth.zero?
           header = SearchEngine::Logging::Color.header(
             %(#{indent}>>>>>> Preflight Dependencies (mode: #{mode}, collection: "#{current}"))
           )
-          puts(header)
+          SearchEngine::Logging::Output.puts(header)
 
           deps.each do |cfg|
             dep_coll = (cfg[:collection] || cfg['collection']).to_s
@@ -56,7 +57,9 @@ module SearchEngine
             dep_klass = __se_resolve_dep_class(dep_coll)
 
             if dep_klass.nil?
-              puts(SearchEngine::Logging::Color.dim(%(#{indent}  "#{dep_coll}" → skipped (unregistered))))
+              SearchEngine::Logging::Output.puts(
+                SearchEngine::Logging::Color.dim(%(#{indent}  "#{dep_coll}" → skipped (unregistered)))
+              )
               visited.add(dep_coll)
               next
             end
@@ -78,7 +81,9 @@ module SearchEngine
             visited.add(dep_coll)
           end
 
-          puts(SearchEngine::Logging::Color.header(%(#{indent}>>>>>> Preflight Done (collection: "#{current}"))))
+          SearchEngine::Logging::Output.puts(
+            SearchEngine::Logging::Color.header(%(#{indent}>>>>>> Preflight Done (collection: "#{current}")))
+          )
         end
 
         # @return [String] current collection logical name; empty string when unavailable
@@ -172,28 +177,32 @@ module SearchEngine
           when 'ensure'
             if missing
               status_word = SearchEngine::Logging::Color.apply('ensure (missing)', :yellow)
-              puts(%(#{indent}"#{dep_coll}" → #{status_word} → index_collection))
-              # Avoid nested preflight to prevent redundant recursion cycles
+              SearchEngine::Logging::Output.puts(%(#{indent}"#{dep_coll}" → #{status_word} → index_collection))
               SearchEngine::Instrumentation.with_context(bulk_suppress_cascade: true) do
                 dep_klass.index_collection(client: client)
               end
             else
-              puts(SearchEngine::Logging::Color.dim(%(#{indent}"#{dep_coll}" → present (skip))))
+              SearchEngine::Logging::Output.puts(
+                SearchEngine::Logging::Color.dim(%(#{indent}"#{dep_coll}" → present (skip)))
+              )
             end
           when 'index'
             if missing || drift
               reason = missing ? 'missing' : 'drift'
               status_word = SearchEngine::Logging::Color.apply("index (#{reason})", :yellow)
-              puts(%(#{indent}"#{dep_coll}" → #{status_word} → index_collection))
-              # Avoid nested preflight to prevent redundant recursion cycles
+              SearchEngine::Logging::Output.puts(%(#{indent}"#{dep_coll}" → #{status_word} → index_collection))
               SearchEngine::Instrumentation.with_context(bulk_suppress_cascade: true) do
                 dep_klass.index_collection(client: client)
               end
             else
-              puts(SearchEngine::Logging::Color.dim(%(#{indent}"#{dep_coll}" → in_sync (skip))))
+              SearchEngine::Logging::Output.puts(
+                SearchEngine::Logging::Color.dim(%(#{indent}"#{dep_coll}" → in_sync (skip)))
+              )
             end
           else
-            puts(SearchEngine::Logging::Color.dim(%(#{indent}"#{dep_coll}" → skipped (unknown mode: #{mode}))))
+            SearchEngine::Logging::Output.puts(
+              SearchEngine::Logging::Color.dim(%(#{indent}"#{dep_coll}" → skipped (unknown mode: #{mode})))
+            )
           end
         end
 
@@ -201,7 +210,9 @@ module SearchEngine
           return unless batches.is_a?(Array)
 
           batches.each_with_index do |batch_stats, idx|
-            puts(SearchEngine::Logging::BatchLine.format(batch_stats, idx + 1, indifferent: true))
+            SearchEngine::Logging::Output.puts(
+              SearchEngine::Logging::BatchLine.format(batch_stats, idx + 1, indifferent: true)
+            )
           end
         end
 
@@ -285,7 +296,8 @@ module SearchEngine
           docs_estimate = __se_heuristic_docs_estimate(1)
           renderer = SearchEngine::Logging::LiveRenderer.new(
             labels: ['single'], partitions: [nil],
-            per_partition_docs_estimates: [docs_estimate]
+            per_partition_docs_estimates: [docs_estimate],
+            io: SearchEngine::Logging::Output.io
           )
           renderer.start
 
@@ -348,7 +360,9 @@ module SearchEngine
         def __se_index_partitions_seq!(parts, into, compiled)
           docs_estimates = __se_per_partition_docs_estimates(parts, compiled)
           renderer = SearchEngine::Logging::LiveRenderer.new(
-            labels: parts.map(&:inspect), partitions: parts, per_partition_docs_estimates: docs_estimates
+            labels: parts.map(&:inspect), partitions: parts,
+            per_partition_docs_estimates: docs_estimates,
+            io: SearchEngine::Logging::Output.io
           )
           renderer.start
 
@@ -387,7 +401,9 @@ module SearchEngine
 
           docs_estimates = __se_per_partition_docs_estimates(parts, compiled)
           renderer = SearchEngine::Logging::LiveRenderer.new(
-            labels: parts.map(&:inspect), partitions: parts, per_partition_docs_estimates: docs_estimates
+            labels: parts.map(&:inspect), partitions: parts,
+            per_partition_docs_estimates: docs_estimates,
+            io: SearchEngine::Logging::Output.io
           )
           renderer.start
 

data/lib/search_engine/bulk.rb

@@ -18,9 +18,10 @@ module SearchEngine
       # When no targets are provided, all declared/registered collections are indexed
       # (models are eagerly loaded from the configured `search_engine_models` path).
       # @param targets [Array<Symbol, String, Class>] collections or model classes
+      # @param silent [Boolean] suppress progress output to stdout (errors still go to stderr)
       # @return [Hash] summary (includes :failed_collections_total for unresolved targets)
-      def index_collections(*targets, client: nil)
-        run!(mode: :index, targets: targets, client: client)
+      def index_collections(*targets, client: nil, silent: false)
+        run!(mode: :index, targets: targets, client: client, silent: silent)
       end
 
       # Index all registered/declared collections.
@@ -30,20 +31,22 @@ module SearchEngine
       # and runs indexing as if they were passed to {.index_collections}.
       #
       # @param client [SearchEngine::Client, nil]
+      # @param silent [Boolean] suppress progress output to stdout (errors still go to stderr)
       # @return [Hash] summary (includes :failed_collections_total for unresolved targets)
-      def index_all(client: nil)
+      def index_all(client: nil, silent: false)
         ensure_models_loaded_from_configured_path!
         names = SearchEngine::CollectionResolver.models_map.keys
-        run!(mode: :index, targets: names, client: client)
+        run!(mode: :index, targets: names, client: client, silent: silent)
       end
 
       # Drop+index (destructive), mirroring {SearchEngine::Base.reindex_collection!}.
       # When no targets are provided, all declared/registered collections are reindexed
       # (models are eagerly loaded from the configured `search_engine_models` path).
       # @param targets [Array<Symbol, String, Class>] collections or model classes
+      # @param silent [Boolean] suppress progress output to stdout (errors still go to stderr)
       # @return [Hash] summary (includes :failed_collections_total for unresolved targets)
-      def reindex_collections!(*targets, client: nil)
-        run!(mode: :reindex, targets: targets, client: client)
+      def reindex_collections!(*targets, client: nil, silent: false)
+        run!(mode: :reindex, targets: targets, client: client, silent: silent)
       end
 
       # Reindex all registered/declared collections.
@@ -53,11 +56,12 @@ module SearchEngine
       # and runs reindexing as if they were passed to {.reindex_collections!}.
       #
       # @param client [SearchEngine::Client, nil]
+      # @param silent [Boolean] suppress progress output to stdout (errors still go to stderr)
       # @return [Hash] summary (includes :failed_collections_total for unresolved targets)
-      def reindex_all!(client: nil)
+      def reindex_all!(client: nil, silent: false)
         ensure_models_loaded_from_configured_path!
         names = SearchEngine::CollectionResolver.models_map.keys
-        run!(mode: :reindex, targets: names, client: client)
+        run!(mode: :reindex, targets: names, client: client, silent: silent)
       end
 
       # Drop orphaned physical collections across all logical collections.
@@ -74,8 +78,9 @@ module SearchEngine
       # @param mode [Symbol] :index | :reindex
       # @param targets [Array]
       # @param client [SearchEngine::Client, nil]
+      # @param silent [Boolean]
       # @return [Hash]
-      def run!(mode:, targets:, client: nil)
+      def run!(mode:, targets:, client: nil, silent: false)
         raise ArgumentError, 'mode must be :index or :reindex' unless %i[index reindex].include?(mode.to_sym)
 
         ts_client = client || SearchEngine.client
@@ -119,7 +124,9 @@ module SearchEngine
         collection_results = []
         failed_collections_total = 0
 
-        SearchEngine::Instrumentation.with_context(bulk: true, bulk_suppress_cascade: true, bulk_mode: mode.to_sym) do
+        ctx = { bulk: true, bulk_suppress_cascade: true, bulk_mode: mode.to_sym }
+        ctx[:bulk_silent] = true if silent
+        SearchEngine::Instrumentation.with_context(ctx) do
           SearchEngine::Instrumentation.instrument('search_engine.bulk.run', payload.merge(stats)) do |ctx|
             run_stage!(mode, stage1_list, :input, collection_results)
             run_stage!(mode, cascade_order, :cascade, collection_results)

data/lib/search_engine/cascade.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'search_engine/logging/output'
+
 module SearchEngine
   # Cascade reindexing for collections that reference other collections via
   # Typesense field-level references.
@@ -192,12 +194,16 @@ into: nil
           parts = parts.reject { |p| p.nil? || p.to_s.strip.empty? }
 
           if parts.empty?
-            puts(SearchEngine::Logging::Color.dim(%(  Referencer "#{coll_display}" — partitions=0 → skip)))
+            SearchEngine::Logging::Output.puts(
+              SearchEngine::Logging::Color.dim(%(  Referencer "#{coll_display}" — partitions=0 → skip))
+            )
             return false
           end
 
           parts_str = SearchEngine::Logging::Color.bold("partitions=#{parts.size}")
-          puts(%(  Referencer "#{coll_display}" — #{parts_str} parallel=#{compiled.max_parallel}))
+          SearchEngine::Logging::Output.puts(
+            %(  Referencer "#{coll_display}" — #{parts_str} parallel=#{compiled.max_parallel})
+          )
           mp = compiled.max_parallel.to_i
           if mp > 1 && parts.size > 1
             require 'concurrent-ruby'
@@ -214,7 +220,9 @@ into: nil
           end
 
         else
-          puts(%(  Referencer "#{coll_display}" — #{SearchEngine::Logging::Color.bold('single')}))
+          SearchEngine::Logging::Output.puts(
+            %(  Referencer "#{coll_display}" — #{SearchEngine::Logging::Color.bold('single')})
+          )
           SearchEngine::Indexer.rebuild_partition!(ref_klass, partition: nil, into: nil)
           executed = true
         end
@@ -336,7 +344,7 @@ into: nil
         coll_display = physical && physical != logical ? "#{logical} (physical: #{physical})" : logical
         action = force_rebuild ? 'force_rebuild index_collection' : 'index_collection'
         status_word = SearchEngine::Logging::Color.apply("schema rebuild required, running #{action}", :yellow)
-        puts(%(  Referencer "#{coll_display}" — #{status_word}))
+        SearchEngine::Logging::Output.puts(%(  Referencer "#{coll_display}" — #{status_word}))
 
         SearchEngine::Instrumentation.with_context(bulk_suppress_cascade: true) do
           ref_klass.index_collection(client: client, pre: :ensure, force_rebuild: force_rebuild)
@@ -344,7 +352,7 @@ into: nil
         true
       rescue StandardError => error
         err_line = %(  Referencer "#{logical}" — schema rebuild failed: #{error.message})
-        puts(SearchEngine::Logging::Color.apply(err_line, :red))
+        warn(SearchEngine::Logging::Color.apply(err_line, :red))
         false
       end
 
@@ -353,7 +361,9 @@ into: nil
           pool.post do
             SearchEngine::Instrumentation.with_context(ctx) do
               summary = SearchEngine::Indexer.rebuild_partition!(ref_klass, partition: p, into: nil)
-              mtx.synchronize { puts(SearchEngine::Logging::PartitionProgress.line(p, summary)) }
+              mtx.synchronize do
+                SearchEngine::Logging::Output.puts(SearchEngine::Logging::PartitionProgress.line(p, summary))
+              end
             end
           end
         end
@@ -363,7 +373,7 @@ into: nil
         executed = false
         parts.each do |p|
           summary = SearchEngine::Indexer.rebuild_partition!(ref_klass, partition: p, into: nil)
-          puts(SearchEngine::Logging::PartitionProgress.line(p, summary))
+          SearchEngine::Logging::Output.puts(SearchEngine::Logging::PartitionProgress.line(p, summary))
           executed = true
         end
         executed

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/indexer/bulk_import.rb

@@ -2,6 +2,7 @@
 
 require 'search_engine/logging/color'
 require 'search_engine/logging/batch_line'
+require 'search_engine/logging/output'
 
 module SearchEngine
   class Indexer
@@ -151,7 +152,11 @@ module SearchEngine
           shared_state[:on_batch] = on_batch
           producer_error = nil
 
-          puts(SearchEngine::Logging::Color.dim('  Starting parallel batch processing...')) if log_batches
+          if log_batches
+            SearchEngine::Logging::Output.puts(
+              SearchEngine::Logging::Color.dim('  Starting parallel batch processing...')
+            )
+          end
           started_at = monotonic_ms
 
           producer_thread = start_producer_thread(
@@ -234,7 +239,7 @@ module SearchEngine
                          else
                            "  Processed #{batch_count} batches... (#{elapsed}ms)"
                          end
-              puts(SearchEngine::Logging::Color.dim(progress))
+              SearchEngine::Logging::Output.puts(SearchEngine::Logging::Color.dim(progress))
             end
           rescue StandardError => error
             yield error if block_given?
@@ -680,7 +685,7 @@ module SearchEngine
         end
 
         def log_batch(stats, batch_number)
-          puts(SearchEngine::Logging::BatchLine.format(stats, batch_number))
+          SearchEngine::Logging::Output.puts(SearchEngine::Logging::BatchLine.format(stats, batch_number))
         end
       end
     end

data/lib/search_engine/indexer.rb

@@ -83,7 +83,7 @@ module SearchEngine
           enum: docs_enum,
           batch_size: nil,
           action: :upsert,
-          log_batches: partition.nil? && on_batch.nil?,
+          log_batches: !SearchEngine::Instrumentation.context[:bulk_silent] && partition.nil? && on_batch.nil?,
           max_parallel: max_parallel,
           on_batch: on_batch
         )

data/lib/search_engine/logging/output.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module SearchEngine
+  module Logging
+    # Thread-safe output routing for indexation progress logging.
+    #
+    # When the instrumentation context includes `bulk_silent: true`,
+    # all output is routed to {File::NULL}. Otherwise, output goes to `$stdout`.
+    # Error output via `warn()` is unaffected — it always reaches `$stderr`.
+    #
+    # @since M10
+    module Output
+      NULL_IO = File.open(File::NULL, 'w')
+
+      module_function
+
+      # @return [Boolean] true when the current thread context indicates silent mode
+      def silent?
+        SearchEngine::Instrumentation.context[:bulk_silent] == true
+      end
+
+      # @return [IO] the appropriate output stream for progress logging
+      def io
+        silent? ? NULL_IO : $stdout
+      end
+
+      # Write a line to the progress output (suppressed in silent mode).
+      # @param args [Array] arguments forwarded to `IO#puts`
+      # @return [nil]
+      def puts(*args)
+        io.puts(*args)
+      end
+    end
+  end
+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.17'
+  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.17
+  version: 30.1.7.0
 platform: ruby
 authors:
 - Nikita Shkoda
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-04-06 00:00:00.000000000 Z
+date: 2026-05-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -159,6 +159,7 @@ files:
 - lib/search_engine/logging/cursor_guard.rb
 - lib/search_engine/logging/format_helpers.rb
 - lib/search_engine/logging/live_renderer.rb
+- lib/search_engine/logging/output.rb
 - lib/search_engine/logging/partition_progress.rb
 - lib/search_engine/logging/spinner.rb
 - lib/search_engine/logging/step_line.rb
@@ -177,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