rails-contact 0.1.16 → 0.1.18

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a7f0cfd6a248a8763b84379dc244b151d7edc7328527586f0416d378f73e5ee
-  data.tar.gz: 6be4ad0ae1d604fdf9ae66c3f8649573c4d2688ce3b93000bac1723fd08e616c
+  metadata.gz: b0b84870f841f736094084fa2ae0c08805f5b54a30fa8960b95cc04f14998001
+  data.tar.gz: 830dfc497510913b838651a00f430d36919c35fca155b54424dae053d4feba60
 SHA512:
-  metadata.gz: c5b66c49e8c489d4565177a34ae71f210c1ccd8c4c36260aed0ef302e2a00ee766ac0c546f943c0f96bc2a843b3ba9c0a05b92518001487cae5a6f14de058714
-  data.tar.gz: e133e1d5768a619f4a33c7a5d5033351358a5a0490d1f387c52730406e1e5b30eead92ed25f48928f01beba7262ab476300dac959571cc5263d1d0ea7e29762f
+  metadata.gz: bab63c0475d073586b14a681c7822f6185b4437e077b5bf3583fc7fa1c68f0ee581a4e7248d6498e77d72e0721c41e8105c188c56dfdeda54071573b9c4b33df
+  data.tar.gz: d46deab8ed814b053834de5157f76ef089efdc3fb04d630a03dbf85375b8686a89f70ab706b956b57f31bdf2152d2fcb9cca6352bccdecef310dfa21b8558486

data/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 0.1.18
+
+- **The `city` filter is a multi-select.** `?city[]=Pune&city[]=Delhi` now
+  filters on several current cities at once, matching how `region` and
+  `csv_import_id` already behave. The database backend always handled an
+  array (`where(current_city: [...])`) — only the parameter permit was
+  scalar, which silently dropped every value but the last. Blank entries
+  (the hidden option a `<select multiple>` always submits) are stripped, and
+  an old single-value bookmark (`?city=Pune`) is coerced to a one-element
+  array, so no existing link changes meaning. The database backend now drops
+  blank entries from `city`/`region` itself as well, so a caller reaching it
+  directly gets "no filter" from an untouched multi-select instead of zero
+  rows.
+
+## 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/app/controllers/rails/contact/contacts_controller.rb

@@ -136,7 +136,6 @@ module Rails
         metadata_scalars << :sort if config.metadata_sorts.any?
 
         permitted = params.permit(
-          :city,
           :sync_eligible,
           :starred,
           :travel_date_start,
@@ -144,16 +143,17 @@ module Rails
           :contact_created_at_start,
           :contact_created_at_end,
           *metadata_scalars,
+          city: [],
           region: [],
           csv_import_id: [],
           **metadata_arrays.index_with { [] }
         )
 
-        ([ :region, :csv_import_id ] + metadata_arrays).each { |key| normalize_multi_select!(permitted, key) }
+        ([ :city, :region, :csv_import_id ] + metadata_arrays).each { |key| normalize_multi_select!(permitted, key) }
         permitted
       end
 
-      # region, csv_import_id and every configured :values metadata filter are
+      # city, region, csv_import_id and every configured :values metadata filter are
       # multi-selects: a <select multiple> submits param[] (an array) plus a
       # hidden param[]="" that Rails always sends, so the blank must be
       # stripped — otherwise IN ('', 'x') matches every blank-valued row.

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
@@ -60,8 +106,16 @@ module Rails
 
           def apply_filters(scope, filters)
             scoped = scope
-            scoped = scoped.where(current_city: filters["city"]) if filters["city"].present?
-            scoped = scoped.where(region_name: filters["region"]) if filters["region"].present?
+            # city and region are multi-selects: one value or many. Blanks are
+            # dropped here as well as in the controller — an untouched
+            # <select multiple> submits [""], and `where(col: [""])` would
+            # return nothing at all rather than "no city filter". A caller
+            # reaching the backend directly gets the same answer as one coming
+            # through filter_params.
+            %w[city region].zip(%i[current_city region_name]).each do |key, column|
+              values = Array(filters[key]).map(&:to_s).reject(&:blank?)
+              scoped = scoped.where(column => values) if values.any?
+            end
             scoped = scoped.where(starred: ActiveModel::Type::Boolean.new.cast(filters["starred"])) if filters["starred"].present?
             if filters["sync_eligible"].present?
               scoped = scoped.where(sync_eligible: ActiveModel::Type::Boolean.new.cast(filters["sync_eligible"]))

data/lib/rails/contact/version.rb

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

data/spec/controllers/contacts_controller_spec.rb

@@ -4,16 +4,26 @@ RSpec.describe Rails::Contact::ContactsController do
   let(:controller) { described_class.new }
 
   describe "private filter params" do
-    it "permits city/sync_eligible and coerces a scalar region to an array" do
+    # city joined region as a multi-select in 0.1.18, so a scalar from an old
+    # bookmark is coerced to a one-element array rather than kept as a string.
+    it "permits sync_eligible and coerces scalar city/region to arrays" do
       controller.params = ActionController::Parameters.new(city: "Delhi", region: "Europe", sync_eligible: "true", x: "1")
       permitted = controller.send(:filter_params)
-      expect(permitted.to_h).to eq({ "city" => "Delhi", "region" => [ "Europe" ], "sync_eligible" => "true" })
+      expect(permitted.to_h).to eq({ "city" => [ "Delhi" ], "region" => [ "Europe" ], "sync_eligible" => "true" })
     end
 
-    it "permits multi-select region[] and csv_import_id[] arrays" do
-      controller.params = ActionController::Parameters.new(region: [ "Europe", "Asia" ], csv_import_id: [ "5", "7" ])
+    it "permits multi-select city[], region[] and csv_import_id[] arrays" do
+      controller.params = ActionController::Parameters.new(city: [ "Pune", "Delhi" ], region: [ "Europe", "Asia" ], csv_import_id: [ "5", "7" ])
       permitted = controller.send(:filter_params)
-      expect(permitted.to_h).to eq({ "region" => [ "Europe", "Asia" ], "csv_import_id" => [ "5", "7" ] })
+      expect(permitted.to_h).to eq({ "city" => [ "Pune", "Delhi" ], "region" => [ "Europe", "Asia" ], "csv_import_id" => [ "5", "7" ] })
+    end
+
+    it "strips the blank a city multi-select submits, and drops it when only blanks arrive" do
+      controller.params = ActionController::Parameters.new(city: [ "", "Pune" ])
+      expect(controller.send(:filter_params).to_h).to eq({ "city" => [ "Pune" ] })
+
+      controller.params = ActionController::Parameters.new(city: [ "" ])
+      expect(controller.send(:filter_params).to_h).to eq({})
     end
 
     it "strips the hidden blank a <select multiple> submits" do

data/spec/search/database_backend_spec.rb

@@ -29,6 +29,28 @@ RSpec.describe Rails::Contact::Search::Backends::Database do
     end
   end
 
+  # City became a multi-select in 0.1.18. The backend always accepted an array
+  # here — what was missing was a permit that let one through.
+  describe "city filter (multi-select)" do
+    # Distinct from the factory default ("Delhi"), so alice/bob/carol above
+    # can't drift into these expectations.
+    let!(:pune)   { create(:rails_contact_contact, given_name: "Pia", current_city: "Pune") }
+    let!(:jaipur) { create(:rails_contact_contact, given_name: "Dev", current_city: "Jaipur") }
+    let!(:kochi)  { create(:rails_contact_contact, given_name: "Mira", current_city: "Kochi") }
+
+    it "matches contacts in every selected city (array -> IN)" do
+      expect(records("city" => [ "Pune", "Jaipur" ])).to match_array([ pune, jaipur ])
+    end
+
+    it "matches a single city exactly as before (scalar)" do
+      expect(records("city" => "Kochi")).to match_array([ kochi ])
+    end
+
+    it "applies no constraint when the selection is blank only" do
+      expect(records("city" => [ "" ]).count).to eq(Rails::Contact::Contact.count)
+    end
+  end
+
   describe "query sanitization" do
     def search_for(query)
       described_class.new.search(query, {}, page: 1, per_page: 25).records
@@ -46,4 +68,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.18
 platform: ruby
 authors:
 - Kshitiz Sinha