noiseless 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c023b22c96a7186d99210b2a4420fa6661e3be195522cf86dbe9191d5301acfa
-  data.tar.gz: ef2f26a7f11bad65b6a604f08641d398e9da90e637af8bbd3f9a1750e8119589
+  metadata.gz: 195219b6de1210cb1f888a5a322e41c624403b7cab4f07cbd700ca9f5f573196
+  data.tar.gz: b92048b781e491ae6c8f0d9114dbf4a4094ba04b7e06bf8394c3a6164e18521a
 SHA512:
-  metadata.gz: 272b9ffa8aa20f2719018ca2abbac572640f997742fdbc79c413432b1d35ee97501dd6ea1475ffa02e67d04987cd31595f27c12df824c1c21832acc4f1de875a
-  data.tar.gz: 00be400acc534f50c40138e57e4c93118ba6829e14e72ebb7a18df546310168b4aaab9e2e421cfb950c6ad6d9b8dc5bcc68b70d38b071fedb9d35fa04c17854c
+  metadata.gz: afc592e3f9e505ff2272845eb4b8cddaae23543400fe83b1c11c70895fd0b8a537e670c1cc78103df93999f72f51cc0cdb8c008772a59e1e881df024e5a9cf24
+  data.tar.gz: 7b4a4113ea30314fbed156161dfa031344881ba17f422ac233cd5a92b91f2b63ff4f7e07282e3a993e98bf42d48d87813b8c4e3aea23ece3365695a1779b382e

data/README.md

@@ -114,6 +114,51 @@ end
 
 For best performance, run independent searches concurrently within a single `Async` block rather than creating separate `Sync` blocks per search.
 
+### Loading Database Records
+
+Search classes return search results by default. To load database records, configure
+the record model explicitly and request `response_type: :records`:
+
+```ruby
+class Company::Search < Noiseless::Model
+  index_name 'companies'
+  record_class 'Company' # A Class is also accepted; strings resolve lazily.
+end
+
+records = Company::Search.search_sync(response_type: :records) do |s|
+  s.match(:name, 'tech')
+end
+records.to_a # Company records in search relevance order
+
+# The instance API supports the same option.
+Company::Search.new.match(:name, 'tech').execute_sync(response_type: :records)
+```
+
+`record_class` is inherited and does not change the default response type. Index
+names are not used to infer record classes: aliases and versioned indexes need
+not match table names. Requesting `:records` without a model supporting `.where`
+raises `ArgumentError`, even when the search has no hits. Records missing from
+the database are omitted; search totals still describe backend hits.
+
+### Pagination and Multi-model Search
+
+The paginator executes lazily and waits for its response when results or totals
+are accessed. Multi-search also waits and returns a `MultiSearchResponse`, not
+an `Async::Task`. Both work inside an existing async context.
+
+```ruby
+page = Company::Search.page(2).per(10)
+page.to_a
+page.total_count
+
+response = Noiseless.multi_search(models: [Company::Search, Product::Search]) do |s|
+  s.match(:name, 'tech')
+  s.limit(10)
+end
+response.results_for_model(Company::Search)
+response.records_for_model(Company::Search) # Uses its configured record_class.
+```
+
 ### Advanced Queries
 
 ```ruby
@@ -179,6 +224,15 @@ end
 
 ### Running Tests Locally
 
+Run the pagination, multi-search, and record-loading unit tests without services:
+
+```bash
+bundle exec ruby -Itest -Ilib -e 'ARGV.each { require_relative it }' \
+  test/{search_pagination,multi_search,record_response,active_record_response,postgresql_search_contract,query_contract}_test.rb
+```
+
+For the full integration suite:
+
 ```bash
 docker compose up -d postgres elasticsearch opensearch typesense
 bin/test

data/lib/noiseless/adapter.rb

@@ -227,12 +227,7 @@ module Noiseless
     end
 
     def build_pagination_hash(paginate_node)
-      return { from: 0, size: 20 } unless paginate_node
-
-      {
-        from: (paginate_node.page - 1) * paginate_node.per_page,
-        size: paginate_node.per_page
-      }
+      Pagination.query_options(paginate_node)
     end
 
     # Parses a backend HTTP response, raising when the backend reported an error.

data/lib/noiseless/adapters/execution_modules/postgresql_execution.rb

@@ -189,9 +189,8 @@ module Noiseless
         # Helper methods
 
         def resolve_model(indexes, model_class = nil)
-          # The standard Model#execute path passes the Noiseless::Model search
-          # class here; only an ActiveRecord model can back a PG search, so
-          # fall through to index-name resolution for anything else.
+          # Respect explicit search-class mappings, including aliased indexes.
+          model_class = RecordClassResolver.resolve(model_class)
           return model_class if active_record_model?(model_class)
 
           index_name = indexes&.first

data/lib/noiseless/adapters/postgresql.rb

@@ -61,7 +61,7 @@ module Noiseless
             raw_response,
             model_class: model_class,
             response_type: response_type,
-            query_hash: build_pagination_from_ast(ast_node)
+            query_hash: build_pagination_hash(ast_node.paginate)
           )
         end
       end
@@ -156,16 +156,6 @@ module Noiseless
         Rails.logger.error("Failed to detect PostgreSQL extensions: #{e.message}")
         []
       end
-
-      def build_pagination_from_ast(ast_node)
-        paginate = ast_node.paginate
-        return { from: 0, size: 20 } unless paginate
-
-        {
-          from: (paginate.page - 1) * paginate.per_page,
-          size: paginate.per_page
-        }
-      end
     end
   end
 end

data/lib/noiseless/bulk_importer.rb

@@ -157,11 +157,7 @@ module Noiseless
     end
 
     def index_name
-      @index_name ||= if model_class.respond_to?(:search_index)
-                        Array(model_class.search_index).first
-                      else
-                        model_class.name.demodulize.underscore.pluralize
-                      end
+      @index_name ||= QueryBuilder.indexes_for(model_class).first
     end
 
     def recreate_index

data/lib/noiseless/document_manager.rb

@@ -70,11 +70,7 @@ module Noiseless
     end
 
     def index_name
-      @index_name ||= if model_instance.class.respond_to?(:search_index)
-                        Array(model_instance.class.search_index).first
-                      else
-                        model_instance.class.name.demodulize.underscore.pluralize
-                      end
+      @index_name ||= QueryBuilder.indexes_for(model_instance.class).first
     end
 
     def supports_dirty_tracking?

data/lib/noiseless/model.rb

@@ -3,6 +3,25 @@
 module Noiseless
   class Model
     extend DSL::ClassMethods
+    extend QueryDelegation
+
+    delegate_query_methods :match, :multi_match, :filter, :range, :sort, :limit, :offset, :paginate,
+                           :aggregation, :geo_distance, :indexes, :remove_duplicates, :facet_sample_slope, :pinned_hits,
+                           to: :@builder
+
+    # Explicit mapping: index names may be aliases, not record class names.
+    # String names are resolved on read so Rails can reload the record class.
+    def self.record_class(value = nil)
+      unless value.nil?
+        raise ArgumentError, "record_class must be a Class or a class name String" unless value.is_a?(Class) || value.is_a?(String)
+
+        return @record_class = value
+      end
+
+      configured = @record_class
+      configured ||= superclass.record_class unless self == Model
+      configured.is_a?(String) ? configured.constantize : configured
+    end
 
     def initialize
       @builder = QueryBuilder.new(self.class)
@@ -23,77 +42,6 @@ module Noiseless
       end
     end
 
-    # Instance methods that delegate to the query builder
-    def match(field, value, **)
-      @builder.match(field, value, **)
-      self
-    end
-
-    def multi_match(query, fields, **)
-      @builder.multi_match(query, fields, **)
-      self
-    end
-
-    def filter(field, value, **)
-      @builder.filter(field, value, **)
-      self
-    end
-
-    def range(field, gte: nil, lte: nil, gt: nil, lt: nil)
-      @builder.range(field, gte: gte, lte: lte, gt: gt, lt: lt)
-      self
-    end
-
-    def sort(field, direction = :asc, **)
-      @builder.sort(field, direction, **)
-      self
-    end
-
-    def limit(size)
-      @builder.limit(size)
-      self
-    end
-
-    def offset(from)
-      @builder.offset(from)
-      self
-    end
-
-    def paginate(**)
-      @builder.paginate(**)
-      self
-    end
-
-    def aggregation(name, type, **)
-      @builder.aggregation(name, type, **)
-      self
-    end
-
-    def geo_distance(field, lat:, lon:, distance:, **)
-      @builder.geo_distance(field, lat: lat, lon: lon, distance: distance, **)
-      self
-    end
-
-    def indexes(names)
-      @builder.indexes(names)
-      self
-    end
-
-    def remove_duplicates(value: true)
-      @builder.remove_duplicates(value: value)
-      self
-    end
-
-    def facet_sample_slope(value)
-      @builder.facet_sample_slope(value)
-      self
-    end
-
-    def pinned_hits(value)
-      @builder.pinned_hits(value)
-      self
-    end
-
     def execute(connection: nil, response_type: nil)
       client = Noiseless.connections.client(connection || self.class.connection)
       ast = @builder.to_ast

data/lib/noiseless/model_registry.rb

@@ -17,7 +17,7 @@ module Noiseless
       }
 
       # Index models by their search index names
-      index_names = Array(model_class.search_index || default_index_name(model_class))
+      index_names = QueryBuilder.indexes_for(model_class)
       index_names.each do |index_name|
         @models_by_index[index_name.to_sym] ||= []
         @models_by_index[index_name.to_sym] << model_class
@@ -67,11 +67,5 @@ module Noiseless
       @models.clear
       @models_by_index.clear
     end
-
-    private
-
-    def default_index_name(model_class)
-      model_class.name.demodulize.underscore.pluralize
-    end
   end
 end

data/lib/noiseless/multi_search.rb

@@ -2,72 +2,28 @@
 
 module Noiseless
   class MultiSearch
+    extend QueryDelegation
+
+    delegate_query_methods :match, :multi_match, :filter, :sort, :limit, :offset, :aggregation,
+                           :geo_distance, :remove_duplicates, :facet_sample_slope, :pinned_hits,
+                           to: :@builder
+
     def initialize(models: nil, indexes: nil, connection: nil)
       @models = resolve_models(models)
       @indexes = resolve_indexes(indexes)
       @connection = connection || Noiseless.config.default_connection
-      @builder = QueryBuilder.new(nil)
+      @builder = QueryBuilder.new(nil).indexes(@indexes)
     end
 
     def search(&block)
       yield(@builder) if block
 
       client = Noiseless.connections.client(@connection)
-      ast = @builder.to_ast
-
-      # Override indexes in AST with our multi-model indexes
-      ast_with_indexes = AST::Root.new(
-        indexes: @indexes,
-        bool: ast.bool,
-        sort: ast.sort,
-        paginate: ast.paginate,
-        vector: ast.vector,
-        collapse: ast.collapse,
-        search_after: ast.search_after,
-        aggregations: ast.aggregations,
-        hybrid: ast.hybrid,
-        pipeline: ast.pipeline,
-        image_query: ast.image_query,
-        conversation: ast.conversation,
-        joins: ast.joins,
-        remove_duplicates: ast.remove_duplicates,
-        facet_sample_slope: ast.facet_sample_slope,
-        pinned_hits: ast.pinned_hits
-      )
-
-      raw_response = client.search(ast_with_indexes)
-      MultiSearchResponse.new(raw_response, @models, @indexes)
-    end
-
-    # Delegate query building methods to the internal builder
-    def match(field, value, **)
-      @builder.match(field, value, **)
-      self
-    end
-
-    def multi_match(query, fields, **)
-      @builder.multi_match(query, fields, **)
-      self
-    end
-
-    def filter(field, value, **)
-      @builder.filter(field, value, **)
-      self
-    end
-
-    def sort(field, direction = :asc, **)
-      @builder.sort(field, direction, **)
-      self
-    end
-
-    def limit(size)
-      @builder.limit(size)
-      self
-    end
-
-    def offset(from)
-      @builder.offset(from)
-      self
+      ast = @builder.indexes(@indexes).to_ast
+      response = Sync { client.search(ast, response_type: :results).wait }
+      MultiSearchResponse.new(response.response, @models, @indexes).tap do |result|
+        result.include_pagination_info(Pagination.query_options(ast.paginate))
+      end
     end
 
     def paginate(page, per_page)
@@ -75,31 +31,6 @@ module Noiseless
       self
     end
 
-    def aggregation(name, type, **)
-      @builder.aggregation(name, type, **)
-      self
-    end
-
-    def geo_distance(field, lat:, lon:, distance:, **)
-      @builder.geo_distance(field, lat: lat, lon: lon, distance: distance, **)
-      self
-    end
-
-    def remove_duplicates(value: true)
-      @builder.remove_duplicates(value: value)
-      self
-    end
-
-    def facet_sample_slope(value)
-      @builder.facet_sample_slope(value)
-      self
-    end
-
-    def pinned_hits(value)
-      @builder.pinned_hits(value)
-      self
-    end
-
     private
 
     def resolve_models(models)
@@ -125,9 +56,7 @@ module Noiseless
     def resolve_indexes(indexes)
       case indexes
       when nil
-        @models.flat_map do |model|
-          Array(model.search_index || default_index_name(model))
-        end.uniq
+        @models.flat_map { |model| QueryBuilder.indexes_for(model) }.uniq
       when Array
         indexes.map(&:to_s)
       when String, Symbol
@@ -136,10 +65,6 @@ module Noiseless
         []
       end
     end
-
-    def default_index_name(model_class)
-      model_class.name.demodulize.underscore.pluralize
-    end
   end
 
   # Multi-search response class
@@ -149,6 +74,10 @@ module Noiseless
       @models = models
       @indexes = indexes
       @results_by_model = nil
+      @models_by_index = {}
+      models.each do |model|
+        QueryBuilder.indexes_for(model).each { |index| @models_by_index[index] ||= model }
+      end
     end
 
     def each(&)
@@ -203,17 +132,8 @@ module Noiseless
     end
 
     def determine_model_class(hit)
-      index_name = hit["_index"]
-
-      # First, try to find models registered for this specific index
-      models_for_index = Noiseless.registry.models_for_index(index_name)
-      return models_for_index.first if models_for_index.size == 1
-
-      # If multiple models or none found, try to infer from index name
-      @models.find do |model|
-        model_indexes = Array(model.search_index || default_index_name(model))
-        model_indexes.include?(index_name)
-      end
+      # Only group into requested models, using the same index rules as search.
+      @models_by_index[hit["_index"]]
     end
 
     def load_records_by_model
@@ -221,22 +141,14 @@ module Noiseless
 
       results_by_model.each do |model_key, model_hits|
         model_class = @models.find { |m| m.name.to_sym == model_key }
-        next unless model_class.respond_to?(:where)
-
-        ids = model_hits.map { |hit| hit["_id"] }
-        records_by_id = model_class.where(id: ids).index_by { it.id.to_s }
-
-        # Sort by search relevance
-        sorted_records = model_hits.filter_map { |hit| records_by_id[hit["_id"].to_s] }
+        record_class = RecordClassResolver.resolve(model_class)
+        next unless record_class.respond_to?(:where)
 
-        records[model_key] = sorted_records
+        raw = { "hits" => { "hits" => model_hits, "total" => model_hits.size } }
+        records[model_key] = Response::Records.new(raw, record_class).to_a
       end
 
       records
     end
-
-    def default_index_name(model_class)
-      model_class.name.demodulize.underscore.pluralize
-    end
   end
 end

data/lib/noiseless/pagination.rb

@@ -5,6 +5,12 @@ module Noiseless
     DEFAULT_PER_PAGE = 20
     MAX_PER_PAGE = 100
 
+    def self.query_options(paginate)
+      return { from: 0, size: DEFAULT_PER_PAGE } unless paginate
+
+      { from: (paginate.page - 1) * paginate.per_page, size: paginate.per_page }
+    end
+
     # Simple paginated array wrapper - no external dependencies
     class PaginatedArray < Array
       attr_accessor :current_page, :per_page, :total_count
@@ -131,6 +137,10 @@ module Noiseless
     # Search paginator - builds and executes paginated queries
     class SearchPaginator
       include Enumerable
+      extend QueryDelegation
+
+      delegate_query_methods :match, :multi_match, :filter, :sort, :aggregation, :geo_distance, :vector,
+                             to: :@query_builder
 
       def initialize(model_class, page: 1, per_page: nil)
         @model_class = model_class
@@ -213,42 +223,6 @@ module Noiseless
         @results.to_a
       end
 
-      # Query building delegation
-      def match(field, value, **)
-        @query_builder.match(field, value, **)
-        self
-      end
-
-      def multi_match(query, fields, **)
-        @query_builder.multi_match(query, fields, **)
-        self
-      end
-
-      def filter(field, value, **)
-        @query_builder.filter(field, value, **)
-        self
-      end
-
-      def sort(field, direction = :asc, **)
-        @query_builder.sort(field, direction, **)
-        self
-      end
-
-      def aggregation(name, type, **)
-        @query_builder.aggregation(name, type, **)
-        self
-      end
-
-      def geo_distance(field, lat:, lon:, distance:, **)
-        @query_builder.geo_distance(field, lat: lat, lon: lon, distance: distance, **)
-        self
-      end
-
-      def vector(field, embedding, **)
-        @query_builder.vector(field, embedding, **)
-        self
-      end
-
       # Response access
       def results
         execute_search unless @executed
@@ -312,7 +286,7 @@ module Noiseless
 
         client = Noiseless.connections.client(@model_class.connection)
         ast = @query_builder.to_ast
-        @results = client.search(ast, model_class: @model_class)
+        @results = Sync { client.search(ast, model_class: @model_class).wait }
         @total_count = @results.total
         @executed = true
       end

data/lib/noiseless/query_builder.rb

@@ -2,9 +2,19 @@
 
 module Noiseless
   class QueryBuilder
+    def self.indexes_for(model)
+      # Multi-search starts without a model and supplies its own indexes.
+      return [] if model.nil?
+
+      return Array(model.search_index) if model.respond_to?(:search_index) && model.search_index&.any?
+      return [model.index_name] if model.respond_to?(:index_name) && model.index_name
+
+      [model.name.demodulize.underscore.pluralize]
+    end
+
     def initialize(model)
       @model        = model
-      @indexes      = determine_indexes(model)
+      @indexes      = self.class.indexes_for(model)
       @nodes        = []
       @aggregations = []
       @collapse     = nil
@@ -270,16 +280,5 @@ module Noiseless
         raise ArgumentError, "pinned_hits must be a String, Hash, or Array of [id, position]"
       end
     end
-
-    def determine_indexes(model)
-      # Check for search_index (plural array) first
-      return Array(model.search_index) if model.respond_to?(:search_index) && model.search_index&.any?
-
-      # Check for index_name (singular string) next
-      return [model.index_name] if model.respond_to?(:index_name) && model.index_name
-
-      # Fallback to pluralized model name
-      [model.name.demodulize.underscore.pluralize]
-    end
   end
 end

data/lib/noiseless/query_delegation.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Noiseless
+  module QueryDelegation
+    # Unlike ordinary delegation, fluent query methods return their wrapper.
+    def delegate_query_methods(*names, to:)
+      names.each do |name|
+        define_method(name) do |*args, **options, &block|
+          instance_variable_get(to).public_send(name, *args, **options, &block)
+          self
+        end
+      end
+    end
+  end
+end

data/lib/noiseless/record_class_resolver.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Noiseless
+  module RecordClassResolver
+    # Search definitions and database models are different kinds of classes.
+    # Only a Noiseless::Model uses the explicit record_class mapping.
+    def self.resolve(model_class)
+      if model_class.is_a?(Class) && model_class <= Model
+        model_class.record_class
+      else
+        model_class
+      end
+    end
+  end
+end

data/lib/noiseless/response/records.rb

@@ -4,7 +4,12 @@ module Noiseless
   module Response
     class Records < Base
       def initialize(raw_response, model_class)
-        super
+        record_class = RecordClassResolver.resolve(model_class)
+        unless record_class.respond_to?(:where)
+          raise ArgumentError, "#{model_class || 'nil'} cannot load records; configure record_class on your Noiseless::Model search class"
+        end
+
+        super(raw_response, record_class)
         @records = nil
         @record_hit_map = nil
       end
@@ -62,7 +67,7 @@ module Noiseless
       end
 
       def load_records
-        return [] if hits.empty? || !model_class.respond_to?(:where)
+        return [] if hits.empty?
 
         # Extract IDs from hits
         ids = hits.map { |hit| hit["_id"] }

data/lib/noiseless/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Noiseless
-  VERSION = "0.8.0"
+  VERSION = "0.9.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: noiseless
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Abdelkader Boudih
@@ -291,7 +291,9 @@ files:
 - lib/noiseless/multi_search.rb
 - lib/noiseless/pagination.rb
 - lib/noiseless/query_builder.rb
+- lib/noiseless/query_delegation.rb
 - lib/noiseless/railtie.rb
+- lib/noiseless/record_class_resolver.rb
 - lib/noiseless/response.rb
 - lib/noiseless/response/aggregations.rb
 - lib/noiseless/response/empty.rb