rails-contact 0.1.16 → 0.1.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a7f0cfd6a248a8763b84379dc244b151d7edc7328527586f0416d378f73e5ee
-  data.tar.gz: 6be4ad0ae1d604fdf9ae66c3f8649573c4d2688ce3b93000bac1723fd08e616c
+  metadata.gz: 47e4ae3ee8279318a713c01eabbc5e85416f1f9847351aaf4fd56e3fe2ea51e1
+  data.tar.gz: c06b8d14fe450aa764ce09216db49c8a0a2877842099d0571cd965f2ff88ddd7
 SHA512:
-  metadata.gz: c5b66c49e8c489d4565177a34ae71f210c1ccd8c4c36260aed0ef302e2a00ee766ac0c546f943c0f96bc2a843b3ba9c0a05b92518001487cae5a6f14de058714
-  data.tar.gz: e133e1d5768a619f4a33c7a5d5033351358a5a0490d1f387c52730406e1e5b30eead92ed25f48928f01beba7262ab476300dac959571cc5263d1d0ea7e29762f
+  metadata.gz: ace1203d3ff1d490b519b14175088dc483ac71780bf1186a233ef6e31a522927df60d6d95c8ee25ea9f6074d53a7a4887ae9b8cc8af9aab67119269e3eec3f85
+  data.tar.gz: ad9e1d740f6cd540a3528accaa1cf3e35d898df89da18312916ee3ba23b79cd6c93ab28a347eff56fa39335bbe464b3e69343a16c930c521bde8926646a2d712

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.1.17
+
+- **Database backend free-text search is now prefix search.** `q` matches
+  `LOWER(col) LIKE 'q%'` instead of `'%q%'`, so a plain btree
+  (`text_pattern_ops` on PostgreSQL) can serve every arm — the substring form
+  could use no index and forced a full scan of a 3-way-joined, `DISTINCT`ed
+  row set on multi-million-row tables. Match arms (given/family name, company,
+  job title, email, phone, label) run as a `UNION` of id-subqueries rather
+  than one `OR`, letting the planner drive each arm from its own index. Phone
+  input matches with and without the e164 `+`, so typing bare digits still
+  works. Trade-off: mid-string fragments no longer match ("`ave`" no longer
+  finds "Dave") — matching how operators actually hunt (start of a name,
+  email, or number).
+- **Large result counts use the PostgreSQL planner estimate.** Exact
+  `COUNT(*)` walks every matching row on every page load; results at or above
+  1,000 rows now take the row estimate from `EXPLAIN (FORMAT JSON)`
+  (milliseconds at any table size), while smaller results keep exact counts.
+  Non-PostgreSQL adapters and planner failures fall back to exact counting.
+  Estimates are display-only — never feed `total_count` into arithmetic.
+
 ## 0.1.16
 
 - **New metadata filter type `:exclude`** — hides rows whose metadata key equals a configured value, e.g. `{ key: "authenticity", type: :exclude, value: "test", default: :on }`. With `default: :on` the filter applies even when the request param is absent (first page load, bookmarks) and an explicit false-y value (`"0"`) switches it off — built for default-on "hide test data" checkboxes. Rows missing the key always pass, so unclassified legacy data is never hidden.

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

@@ -14,40 +14,86 @@ module Rails
 
           def search(query, filters, page:, per_page:)
             query = sanitize_query(query)
-            # Metadata sort cannot combine with free-text search: the search
-            # branch below runs SELECT DISTINCT, and PostgreSQL rejects ORDER BY
-            # expressions that are not in the select list. Searching means
-            # hunting a specific contact anyway, so q results keep recency order.
+            # Free-text search keeps recency order: searching means hunting a
+            # specific contact, so a metadata sort would only bury the match.
             filters = filters.except("sort") if query.present?
             offset = (page - 1) * per_page
             scope = Contact.includes(:emails, :phones, :labels).recent_first
             scope = apply_filters(scope, filters)
+            scope = apply_query(scope, query) if query.present?
 
-            if query.blank?
-              total = scope.count
-              records = scope.offset(offset).limit(per_page).to_a
-              return Search::Result.new(records: records, total_count: total, page: page, per_page: per_page)
-            end
-
-            wildcard = "%#{query.downcase}%"
-            filtered = scope.left_joins(:emails, :phones, :labels).where(
-              "LOWER(rails_contact_contacts.given_name) LIKE :q OR "\
-              "LOWER(rails_contact_contacts.family_name) LIKE :q OR "\
-              "LOWER(COALESCE(rails_contact_contacts.metadata->>'company', '')) LIKE :q OR "\
-              "LOWER(COALESCE(rails_contact_contacts.metadata->>'job_title', '')) LIKE :q OR "\
-              "LOWER(rails_contact_contact_emails.value) LIKE :q OR "\
-              "rails_contact_contact_phones.e164 LIKE :raw OR "\
-              "LOWER(rails_contact_labels.name) LIKE :q",
-              q: wildcard,
-              raw: "%#{query}%"
-            ).distinct
-            total = filtered.count(:id)
-            records = filtered.offset(offset).limit(per_page).to_a
-            Search::Result.new(records: records, total_count: total, page: page, per_page: per_page)
+            Search::Result.new(
+              records: scope.offset(offset).limit(per_page).to_a,
+              total_count: count_for(scope),
+              page: page,
+              per_page: per_page
+            )
           end
 
           private
 
+          # Prefix search, deliberately: LOWER(col) LIKE 'q%' is served by a
+          # plain btree (text_pattern_ops on PostgreSQL), where the previous
+          # '%q%' substring form could use no index at all and forced a full
+          # scan of a 3-way-joined, DISTINCTed row set on a multi-million-row
+          # table.
+          #
+          # Each match arm lives in its own subquery UNIONed by id rather than
+          # OR'd into one WHERE: an OR mixing table columns and EXISTS probes
+          # can never use a bitmap-index combination, but a UNION of id-sets
+          # lets the planner drive every arm from its own index and semi-join
+          # the small result against the ordered contact scan. Phone numbers
+          # are probed with and without the e164 '+' so typing bare digits
+          # still matches.
+          def apply_query(scoped, query)
+            prefix = "#{query.downcase}%"
+            scoped.where(
+              "rails_contact_contacts.id IN (" \
+              "SELECT c.id FROM rails_contact_contacts c WHERE LOWER(c.given_name) LIKE :q " \
+              "UNION SELECT c.id FROM rails_contact_contacts c WHERE LOWER(c.family_name) LIKE :q " \
+              "UNION SELECT c.id FROM rails_contact_contacts c WHERE LOWER(COALESCE(c.metadata->>'company', '')) LIKE :q " \
+              "UNION SELECT c.id FROM rails_contact_contacts c WHERE LOWER(COALESCE(c.metadata->>'job_title', '')) LIKE :q " \
+              "UNION SELECT e.contact_id FROM rails_contact_contact_emails e WHERE LOWER(e.value) LIKE :q " \
+              "UNION SELECT p.contact_id FROM rails_contact_contact_phones p WHERE p.e164 LIKE :raw OR p.e164 LIKE :plus_raw " \
+              "UNION SELECT cl.contact_id FROM rails_contact_contact_labels cl " \
+              "JOIN rails_contact_labels l ON l.id = cl.label_id WHERE LOWER(l.name) LIKE :q" \
+              ")",
+              q: prefix,
+              raw: "#{query}%",
+              plus_raw: "+#{query}%"
+            )
+          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
+
+          def count_for(scoped)
+            return scoped.count unless postgres?(scoped)
+
+            estimate = planner_estimate(scoped)
+            return scoped.count if estimate.nil? || estimate < APPROX_COUNT_THRESHOLD
+
+            estimate
+          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
+          end
+
           # Escape LIKE metacharacters (% _ \) so a user typing "%" can't widen
           # the match to every row, and cap length to keep the pattern bounded.
           # The backend builds raw "%…%" LIKE patterns, so this guard belongs

data/lib/rails/contact/version.rb

@@ -1,5 +1,5 @@
 module Rails
   module Contact
-    VERSION = "0.1.16"
+    VERSION = "0.1.17"
   end
 end

data/spec/search/database_backend_spec.rb

@@ -46,4 +46,112 @@ RSpec.describe Rails::Contact::Search::Backends::Database do
       expect { search_for("a" * 1000) }.not_to raise_error
     end
   end
+
+  describe "prefix search arms" do
+    let!(:dave) do
+      create(:rails_contact_contact,
+             given_name: "Dave", family_name: "Sharma",
+             metadata: { "company" => "Acme Travels", "job_title" => "Planner" }.to_json).tap do |c|
+        c.emails.create!(value: "Dave@Example.com")
+        c.phones.create!(value: "+91 98123 45670", e164: "+919812345670")
+        c.labels = [ Rails::Contact::Label.find_or_create_by!(name: "vip-club") ]
+      end
+    end
+
+    def search_for(query)
+      described_class.new.search(query, {}, page: 1, per_page: 25).records
+    end
+
+    it "matches a given-name prefix case-insensitively" do
+      expect(search_for("dav")).to include(dave)
+    end
+
+    it "matches a family-name prefix" do
+      expect(search_for("sha")).to include(dave)
+    end
+
+    it "no longer matches a mid-string fragment (the index-serveable trade)" do
+      expect(search_for("ave")).not_to include(dave)
+    end
+
+    it "matches an email prefix" do
+      expect(search_for("dave@ex")).to include(dave)
+    end
+
+    it "matches bare digits against the +-prefixed e164" do
+      expect(search_for("91981")).to include(dave)
+    end
+
+    it "matches the full plus-form phone prefix" do
+      expect(search_for("+91981")).to include(dave)
+    end
+
+    it "matches a company prefix" do
+      expect(search_for("acme")).to include(dave)
+    end
+
+    it "matches a job-title prefix" do
+      expect(search_for("plan")).to include(dave)
+    end
+
+    it "matches a label prefix" do
+      expect(search_for("vip")).to include(dave)
+    end
+
+    it "does not duplicate a contact matched by several arms" do
+      # "dave" hits both the given_name and email arms; UNION dedupes ids.
+      expect(search_for("dave").count(dave)).to eq(1)
+    end
+  end
+
+  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)
+    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)
+
+        expect(backend.search("", {}, page: 1, per_page: 25).total_count).to eq(50_000)
+      end
+
+      it "counts exactly below the threshold" do
+        allow(backend).to receive(:planner_estimate).and_return(5)
+
+        expect(backend.search("", {}, page: 1, per_page: 25).total_count)
+          .to eq(Rails::Contact::Contact.count)
+      end
+
+      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
+    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}}]')
+
+        expect(backend.send(:planner_estimate, scope)).to eq(123_456)
+      end
+
+      it "returns nil on malformed planner output" do
+        allow(scope.klass.connection).to receive(:select_value).and_return("not json")
+
+        expect(backend.send(:planner_estimate, scope)).to be_nil
+      end
+    end
+  end
 end

metadata

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