rails-contact 0.1.18 → 0.1.19

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0b84870f841f736094084fa2ae0c08805f5b54a30fa8960b95cc04f14998001
-  data.tar.gz: 830dfc497510913b838651a00f430d36919c35fca155b54424dae053d4feba60
+  metadata.gz: f986b7426ce2b99924283ea2343ef48ed1f6f4c50c6e2763ba50f03be99b9a93
+  data.tar.gz: 8f04a3f04fdb7d9bb6921efa14df565be9b82029c03c522da8ac6b111e70e3f9
 SHA512:
-  metadata.gz: bab63c0475d073586b14a681c7822f6185b4437e077b5bf3583fc7fa1c68f0ee581a4e7248d6498e77d72e0721c41e8105c188c56dfdeda54071573b9c4b33df
-  data.tar.gz: d46deab8ed814b053834de5157f76ef089efdc3fb04d630a03dbf85375b8686a89f70ab706b956b57f31bdf2152d2fcb9cca6352bccdecef310dfa21b8558486
+  metadata.gz: 7426fa7a4faf079dba58377b115f5b612463f55c7ab66aef7f4eec65fbb8b258c84dc91c148d63bd9b76e59bc08387b8df34052f4226ee066cde9eeba1eec916
+  data.tar.gz: 916da6b6432f11a44c8b260964f81feaa5092b2da83d4a5c9433d25c786d4e57d19d1b6f402a1c2ddaf043a8a8dbb69ea0da7308d82016323393d398e0a7b072

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.1.19
+
+- **Result counts are exact again, and bounded.** 0.1.17 replaced large exact
+  counts with the PostgreSQL planner's row estimate, which the index then
+  printed as if it were a count: a filtered list of 364 contacts reported
+  "Showing 1-25 of 1,005" across 41 pages, most of them empty, and host apps
+  reading `total_count` sized outbound campaigns off the same guess. Estimates
+  are worst exactly where they matter - a value the last `ANALYZE` has not
+  sampled (a freshly imported batch) falls back to `rows / n_distinct`.
+  `count_for` now runs `COUNT(*)` over the matching rows capped at
+  `MAX_EXACT_COUNT + 1` (10,000), with `ORDER BY` and eager-loading stripped
+  from the subquery so the database stops scanning at the `LIMIT` - the
+  full-table pass the estimate existed to avoid never happens, and every
+  realistic filtered list gets a true number. Past the cap,
+  `Search::Result#count_capped?` is true, `total_count` is the cap, and the
+  new `contact_count_label` helper renders it as "10,000+". `@count_capped` is
+  exposed to views alongside `@total_count`.
+
 ## 0.1.18
 
 - **The `city` filter is a multi-select.** `?city[]=Pune&city[]=Delhi` now

data/app/controllers/rails/contact/contacts_controller.rb

@@ -17,6 +17,9 @@ module Rails
         ).call
         @contacts = result.records
         @total_count = result.total_count
+        # A capped count is a floor, not a total — the pager and any audience
+        # panel built on @total_count must render it as "N+".
+        @count_capped = result.count_capped?
         @page = result.page
         @per_page = result.per_page
         @total_pages = result.total_pages

data/app/helpers/rails/contact/application_helper.rb

@@ -5,6 +5,13 @@ module Rails
         [ contact.given_name, contact.family_name ].map { |part| part.to_s.first.to_s.upcase }.join
       end
 
+      # A count the backend stopped at its cap is a floor, not a total, so it
+      # renders as "10,000+". Rendering it plain reads as an exact number and
+      # is how a guessed 1,005 once sized a WhatsApp broadcast.
+      def contact_count_label(count, capped = false)
+        "#{number_with_delimiter(count.to_i)}#{'+' if capped}"
+      end
+
       def contact_chip(value)
         value.presence || "-"
       end

data/app/views/rails/contact/_index_pagination.html.erb

@@ -4,7 +4,7 @@
       <% start_i = (@page - 1) * @per_page + 1 %>
       <% end_i = [ @page * @per_page, @total_count ].min %>
       Showing <span class="font-medium text-gray-900"><%= start_i %>–<%= end_i %></span>
-      of <span class="font-medium text-gray-900"><%= number_with_delimiter(@total_count) %></span>
+      of <span class="font-medium text-gray-900"><%= contact_count_label(@total_count, @count_capped) %></span>
       <% if @per_page.present? && @per_page > 0 %>
         <span class="text-gray-500">(<%= @per_page %> per page)</span>
       <% end %>

data/lib/rails/contact/search/backends/database.rb

@@ -22,9 +22,12 @@ module Rails
             scope = apply_filters(scope, filters)
             scope = apply_query(scope, query) if query.present?
 
+            total_count, count_capped = count_for(scope)
+
             Search::Result.new(
               records: scope.offset(offset).limit(per_page).to_a,
-              total_count: count_for(scope),
+              total_count: total_count,
+              count_capped: count_capped,
               page: page,
               per_page: per_page
             )
@@ -65,33 +68,33 @@ module Rails
           end
 
           # Exact COUNT(*) walks every matching row and was one of the two
-          # full-table passes behind 40-second index pages. On PostgreSQL,
-          # large counts come from the planner's row estimate instead —
-          # milliseconds regardless of table size. Small results (under
-          # APPROX_COUNT_THRESHOLD) still count exactly: cheap to do, and
-          # operators expect precise numbers on short lists. Estimates are
-          # for pager display only — never feed them into arithmetic.
-          APPROX_COUNT_THRESHOLD = 1_000
-
+          # full-table passes behind 40-second index pages; the planner
+          # estimate that replaced it then printed guesses as counts — a sheet
+          # of 364 contacts read "1,005 · Page 1 / 41", and the same number
+          # sized a WhatsApp broadcast. So count exactly, but bounded:
+          # COUNT(*) over the matching rows capped at MAX_EXACT_COUNT + 1 lets
+          # the database stop scanning at the LIMIT, so no view pays a
+          # full-table pass, while every realistic filtered list gets a true
+          # number. Past the cap the caller is told so and shows "10,000+".
+          MAX_EXACT_COUNT = 10_000
+
+          # Returns [count, capped]. count never exceeds MAX_EXACT_COUNT.
           def count_for(scoped)
-            return scoped.count unless postgres?(scoped)
-
-            estimate = planner_estimate(scoped)
-            return scoped.count if estimate.nil? || estimate < APPROX_COUNT_THRESHOLD
+            total = scoped.klass.unscoped.from(bounded_scope(scoped), :bounded_count).count
 
-            estimate
+            [ [ total, MAX_EXACT_COUNT ].min, total > MAX_EXACT_COUNT ]
           end
 
-          # EXPLAIN (FORMAT JSON) without ANALYZE executes nothing; the
-          # relation's own to_sql carries its bound values inlined, so there
-          # is no injection surface beyond what the scope already is.
-          # Estimates track table statistics, so they are only as fresh as
-          # the last ANALYZE.
-          def planner_estimate(scoped)
-            plan = scoped.klass.connection.select_value("EXPLAIN (FORMAT JSON) #{scoped.to_sql}")
-            JSON.parse(plan.to_s).dig(0, "Plan", "Plan Rows")
-          rescue ActiveRecord::StatementInvalid, JSON::ParserError
-            nil
+          # ORDER BY is stripped rather than kept: recent_first orders by
+          # updated_at and a metadata sort is a CASE expression — either one
+          # makes the planner sort the whole matching set before it can honour
+          # the LIMIT, which is the full pass this is here to avoid. SELECT 1
+          # keeps it a bare row scan, and eager-loading has no bearing on how
+          # many rows match.
+          def bounded_scope(scoped)
+            scoped.except(:order, :includes, :eager_load, :preload)
+                  .select("1")
+                  .limit(MAX_EXACT_COUNT + 1)
           end
 
           # Escape LIKE metacharacters (% _ \) so a user typing "%" can't widen

data/lib/rails/contact/search/result.rb

@@ -1,7 +1,14 @@
 module Rails
   module Contact
     module Search
-      Result = Struct.new(:records, :total_count, :page, :per_page, keyword_init: true) do
+      Result = Struct.new(:records, :total_count, :page, :per_page, :count_capped, keyword_init: true) do
+        # True when the backend stopped counting at its cap, so total_count is
+        # a floor ("10,000+") rather than the whole set. Views must say so —
+        # a capped number rendered plain reads as an exact count.
+        def count_capped?
+          !!count_capped
+        end
+
         def total_pages
           return 0 if total_count.zero? || per_page.zero?
 

data/lib/rails/contact/version.rb

@@ -1,5 +1,5 @@
 module Rails
   module Contact
-    VERSION = "0.1.18"
+    VERSION = "0.1.19"
   end
 end

data/spec/helpers/application_helper_spec.rb

@@ -6,6 +6,11 @@ RSpec.describe Rails::Contact::ApplicationHelper, type: :helper do
     expect(helper.contact_initials(contact)).to eq("AS")
   end
 
+  it "renders an exact count plainly and a capped one as a floor" do
+    expect(helper.contact_count_label(1_005)).to eq("1,005")
+    expect(helper.contact_count_label(10_000, true)).to eq("10,000+")
+  end
+
   it "returns fallback chip for blank values" do
     expect(helper.contact_chip(nil)).to eq("-")
     expect(helper.contact_chip("x")).to eq("x")

data/spec/search/database_backend_spec.rb

@@ -129,50 +129,49 @@ RSpec.describe Rails::Contact::Search::Backends::Database do
   describe "result counting" do
     let(:backend) { described_class.new }
 
-    it "counts exactly on non-PostgreSQL adapters" do
-      result = backend.search("", {}, page: 1, per_page: 25)
-      expect(result.total_count).to eq(Rails::Contact::Contact.count)
+    def result(filters = {}, per_page: 25)
+      backend.search("", filters, page: 1, per_page: per_page)
     end
 
-    context "when the adapter reports PostgreSQL" do
-      before { allow(backend).to receive(:postgres?).and_return(true) }
-
-      it "uses the planner estimate at or above the threshold" do
-        allow(backend).to receive(:planner_estimate).and_return(50_000)
+    it "counts a filtered scope exactly" do
+      # The production bug: a sheet holding one contact reported four figures
+      # because the count was a planner estimate, not a count.
+      expect(result({ "csv_import_id" => [ "imp_1" ] }).total_count).to eq(1)
+    end
 
-        expect(backend.search("", {}, page: 1, per_page: 25).total_count).to eq(50_000)
-      end
+    it "counts the unfiltered scope exactly" do
+      expect(result.total_count).to eq(Rails::Contact::Contact.count)
+    end
 
-      it "counts exactly below the threshold" do
-        allow(backend).to receive(:planner_estimate).and_return(5)
+    it "reports pages from the real count" do
+      expect(result({}, per_page: 2).total_pages).to eq(2)
+    end
 
-        expect(backend.search("", {}, page: 1, per_page: 25).total_count)
-          .to eq(Rails::Contact::Contact.count)
-      end
+    it "counts the same under a metadata sort" do
+      # ORDER BY is stripped inside the count subquery so the LIMIT can
+      # short-circuit; stripping it must not change the answer.
+      config = Rails::Contact.configuration
+      original = config.metadata_sorts
+      config.metadata_sorts = { "score" => { key: "score" } }
 
-      it "falls back to an exact count when the planner call fails" do
-        # No stub on planner_estimate: on this SQLite harness the real
-        # EXPLAIN (FORMAT JSON) raises and the rescue returns nil.
-        expect(backend.search("", {}, page: 1, per_page: 25).total_count)
-          .to eq(Rails::Contact::Contact.count)
-      end
+      expect(result({ "sort" => "score" }).total_count).to eq(3)
+    ensure
+      config.metadata_sorts = original
     end
 
-    describe "#planner_estimate" do
-      let(:scope) { Rails::Contact::Contact.all }
-
-      it "reads Plan Rows from EXPLAIN (FORMAT JSON)" do
-        allow(scope.klass.connection).to receive(:select_value)
-          .with(/\AEXPLAIN \(FORMAT JSON\)/)
-          .and_return('[{"Plan": {"Plan Rows": 123456}}]')
+    context "when more rows match than the cap" do
+      before { stub_const("#{described_class}::MAX_EXACT_COUNT", 2) }
 
-        expect(backend.send(:planner_estimate, scope)).to eq(123_456)
+      it "clamps the count to the cap and flags it" do
+        expect(result.total_count).to eq(2)
+        expect(result.count_capped?).to be(true)
       end
 
-      it "returns nil on malformed planner output" do
-        allow(scope.klass.connection).to receive(:select_value).and_return("not json")
+      it "does not flag a set that exactly fills the cap" do
+        carol.destroy!
 
-        expect(backend.send(:planner_estimate, scope)).to be_nil
+        expect(result.total_count).to eq(2)
+        expect(result.count_capped?).to be(false)
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-contact
 version: !ruby/object:Gem::Version
-  version: 0.1.18
+  version: 0.1.19
 platform: ruby
 authors:
 - Kshitiz Sinha