search-engine-for-typesense 30.1.6.17 → 30.1.6.18

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1bd17994c46590322f8d32265bf5f1a5ae91be3b911a120c48730ba6339fb9e3
-  data.tar.gz: e7d9785f65c500ddffaef1898b8620c13142ade4f737d6b93f7f1b88a31ee582
+  metadata.gz: 01b787168b6ef3694f27552da317fa390eaee171bf0734d94725b4527a883968
+  data.tar.gz: 28b30b42639215b992ce6b152bd9c076dc5dc221f6c9a18be5f2355aa7c63865
 SHA512:
-  metadata.gz: 744c09d6abd7bce828543b0cd11bb354d94cdff2c17a89d690efd25948993901341c0177890e07256e0b1a9e376925f6ed790c1b5ad64f629e68a99dca9b6ad9
-  data.tar.gz: aee5a996ae1f5075533786e58347e0771737ecc8278cd25b380df7b8c21b6ea917e052a9ad34216eab7f6a2b8a80c90e6701241843eb9698572f1adc9fd201c1
+  metadata.gz: f5229d42405c66d0811102f31654631d8654bd52bdd55605f12f6baf446c2d61428d95a3f6a0c56a05b6dc4b404a68d3772ee13d4a1ca6a1739efd3de2f93390
+  data.tar.gz: faf42770cec8639077c6efae5e0f1599d1d9eabba0b3fdab23149a5a334ba3a3f50cc1156940bbb8b373f95b695f3e70457370687a774e39c0d2934b9f4cc07a

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/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/version.rb

@@ -3,5 +3,5 @@
 module SearchEngine
   # Current gem version.
   # @return [String]
-  VERSION = '30.1.6.17'
+  VERSION = '30.1.6.18'
 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.6.18
 platform: ruby
 authors:
 - Nikita Shkoda
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-04-06 00:00:00.000000000 Z
+date: 2026-04-27 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