make_taggable 1.2.1 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 99cb64f83f0cef74cc21f3fc09a341e62db5a2248b8c88ef5d720de4b9446abb
-  data.tar.gz: c3c08be5a20df6100567523555be2394dc32665770f6c65226e0fe91b3be5652
+  metadata.gz: 7b11d21dbd46411b5b827d1b70cb44bcb641259804a32fa221597e56e02aa906
+  data.tar.gz: 3ebf2e595313e19cc88e28ab7541c40bae5fd1c702a09b8f60873fb68605bfcd
 SHA512:
-  metadata.gz: ad8701479ff9565786acebff64af05fe5aaa88eddbcfc660f88778e4ca885a0d26438677754cfa3072dd54e3eef6374ebed4f1e4de6a70fe911824050cb0b19e
-  data.tar.gz: 47804d66800ff4df491f3b7037ba5e82c131fbaf4c9eb8442a650ed6ecbf1772483d2ae2237c5437cb8ffefca831d107744a3ffacb2c517cb65a161063bc6d0e
+  metadata.gz: 543f460b5117fd847d6f2ed9a7bc694aece6306b3268912710c058cf6bb48275932d1a06ee0adf867492c175ca858cf84794db4238e52b8bad4f2f8ff71fdbc2
+  data.tar.gz: 9983b5c3084235e612097a52bda93c4bd48799e4c29a8c30b354d2ad8d24bc07db2ec99d4077956e193dfa5c175e21198f3238d912882a7015887d72438ea1a2

data/CHANGELOG.md

@@ -5,6 +5,38 @@ All notable changes to this project are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.3.0] - 2026-08-23
+
+### Changed
+
+- **`tagged_with` no longer joins the taggings table.** It tests for each tag with an `EXISTS`
+  subquery instead, which is what stops a record being returned once per matching tagging. A tag
+  applied in two contexts, or a `:wild` pattern matching two of a record's tags, returned that
+  record twice; `.count` disagreed with the number of records, and pagination pages ran short.
+
+  The consequence for callers is that a `taggings` column is no longer in scope on the relation, so
+  `tagged_with("x").order("taggings.created_at")` or a `group` on a taggings column now needs an
+  explicit `.joins(:taggings)`. See [docs/querying.md](docs/querying.md).
+
+  Matching a dozen tags now produces a dozen correlated subqueries rather than a dozen joins.
+  `:match_all` is unchanged and keeps its join.
+
+### Fixed
+
+- `tagged_with(..., any: true)` forced `SELECT taggable_models.*` onto the relation. That made
+  `.count` emit `COUNT("table".*)`, which no adapter accepts, and left a caller's own `select`
+  appended after the star rather than replacing it -- so every column came back regardless, and the
+  relation could not be used inside a `merge`. The strategy filters with an `EXISTS` subquery and
+  joins nothing, so Active Record's default select list was already right.
+
+- `:order_by_matching_tag_count` raised on the default all-tags path, and the expression behind it
+  was invalid SQL that would have ordered nothing even where it parsed. Both strategies now share
+  the correlated count the `:any` path has always used, so the option orders correctly on either.
+  It still has no effect alongside `:match_all`.
+
+- `tagged_with(..., exclude: true)` ignored `:start_at` and `:end_at`, excluding records on the
+  strength of taggings from outside the window entirely.
+
 ## [1.2.1] - 2026-08-23
 
 ### Fixed

data/docs/querying.md

@@ -30,9 +30,9 @@ empty relation rather than every record — worth knowing when the tags come fro
 | `:wild` | Match tags *containing* the given text, i.e. `%sci%` |
 | `:on` | Restrict to one context. Honoured by every option, `:exclude` included |
 | `:owned_by` | Restrict to tags applied by one tagger |
-| `:order_by_matching_tag_count` | With `:any`, order by how many tags matched, most first |
-| `:start_at` | Only tags applied after this time |
-| `:end_at` | Only tags applied before this time |
+| `:order_by_matching_tag_count` | Order by how many matching taggings a record has, most first. No effect with `:match_all` |
+| `:start_at` | Only tags applied after this time. Honoured by every option, `:exclude` included |
+| `:end_at` | Only tags applied before this time. Honoured by every option, `:exclude` included |
 
 An empty tag list means "nothing matches" for the matching options and "nothing is ruled out" for
 `:exclude`, so the two always partition the scope between them:
@@ -162,10 +162,25 @@ MakeTaggable::Tag.for_context(:skills) # used in this context, on any model
 query time. If you set `MakeTaggable.tags_counter = false` that counter is not maintained and both
 scopes will be wrong.
 
+## Grouping and ordering by tagging columns
+
+`tagged_with` does not join the taggings table, so a `taggings` column is not in scope on the
+relation it returns. Join it yourself when you need one:
+
+```ruby
+Book.tagged_with("sci-fi").joins(:taggings).group("taggings.context").count
+Book.tagged_with("sci-fi").joins(:taggings).order("taggings.created_at desc")
+```
+
+Note that joining reintroduces one row per tagging, which is exactly what `tagged_with` avoids on
+its own — add `.distinct` if you want records back rather than matches.
+
 ## Performance notes
 
-- `tagged_with` with several tags and no `:any` adds one join per tag. Matching a dozen tags in a
-  single call generates a dozen joins; prefer `any: true` where the semantics allow it.
+- `tagged_with` tests for each tag with an `EXISTS` subquery, one per tag, and joins nothing. That
+  is what stops a record being returned once per matching tagging. Matching a dozen tags produces a
+  dozen correlated subqueries rather than a dozen joins, which most planners handle better, but it
+  is still worth reaching for `any: true` where the semantics allow it.
 - `:order_by_matching_tag_count` adds a correlated subquery to the `ORDER BY`. It is fine for a
   page of results and expensive across a whole table.
 - `all_tag_counts` joins the taggables to count them. Reach for `all_tags` when the counts are not

data/lib/make_taggable/taggable/core.rb

@@ -123,8 +123,8 @@ module MakeTaggable::Taggable
       # @option options [TrueClass, FalseClass] :exclude match records carrying none of the tags
       # @option options [TrueClass, FalseClass] :match_all match records carrying only these tags
       # @option options [TrueClass, FalseClass] :wild match tags containing the given text
-      # @option options [TrueClass, FalseClass] :order_by_matching_tag_count with `:any`, order by
-      #   how many tags matched, most first
+      # @option options [TrueClass, FalseClass] :order_by_matching_tag_count order by how many
+      #   matching taggings a record has, most first. No effect alongside `:match_all`
       # @option options [ActiveRecord::Base] :owned_by only tags applied by this tagger
       # @option options [Symbol, String] :on only tags applied in this context
       # @option options [Time, Date] :start_at only tags applied after this time

data/lib/make_taggable/taggable/tagged_with_query/all_tags_query.rb

@@ -11,63 +11,72 @@ module MakeTaggable::Taggable::TaggedWithQuery
     # @return [ActiveRecord::Relation]
     #
     def build
-      taggable_model.joins(each_tag_in_list)
+      taggable_model.joins(match_all_join)
+        .where(carries_every_tag)
         .group(by_taggable)
         .having(tags_that_matches_count)
-        .order(order_conditions)
+        .order(Arel.sql(order_conditions))
         .readonly(false)
     end
 
     private
 
-    def each_tag_in_list
-      arel_join = taggable_arel_table
-
-      tag_list.each do |tag|
-        tagging_alias = tagging_arel_table.alias(tagging_alias(tag))
-        arel_join = arel_join
-          .join(tagging_alias)
-          .on(on_conditions(tag, tagging_alias))
-      end
-
-      if options[:match_all].present?
-        arel_join = arel_join
-          .join(tagging_arel_table, Arel::Nodes::OuterJoin)
-          .on(
-            match_all_on_conditions
-          )
-      end
+    # One EXISTS test per tag, rather than one join per tag.
+    #
+    # A join multiplies the result: a record is returned once for every tagging
+    # that satisfies it, so a tag applied in two contexts, or a wild pattern
+    # matching two of a record's tags, returned that record twice. EXISTS asks
+    # the question the query is actually asking -- does this record carry the
+    # tag -- and answers it once.
+    def carries_every_tag
+      tag_list.map { |tag| taggings_for(tag).exists }.inject(:and)
+    end
 
-      arel_join.join_sources
+    def taggings_for(tag)
+      tagging_arel_table
+        .project(Arel.star)
+        .where(tag_conditions(tag))
     end
 
-    def on_conditions(tag, tagging_alias)
-      on_condition = tagging_alias[:taggable_id].eq(taggable_arel_table[taggable_model.primary_key])
-        .and(tagging_alias[:taggable_type].eq(taggable_model.base_class.name))
+    def tag_conditions(tag)
+      condition = tagging_arel_table[:taggable_id].eq(taggable_arel_table[taggable_model.primary_key])
+        .and(tagging_arel_table[:taggable_type].eq(taggable_model.base_class.name))
         .and(
-          tagging_alias[:tag_id].in(
+          tagging_arel_table[:tag_id].in(
             tag_arel_table.project(tag_arel_table[:id]).where(tag_match_type(tag))
           )
         )
 
       if options[:start_at].present?
-        on_condition = on_condition.and(tagging_alias[:created_at].gteq(options[:start_at]))
+        condition = condition.and(tagging_arel_table[:created_at].gteq(options[:start_at]))
       end
 
       if options[:end_at].present?
-        on_condition = on_condition.and(tagging_alias[:created_at].lteq(options[:end_at]))
+        condition = condition.and(tagging_arel_table[:created_at].lteq(options[:end_at]))
       end
 
       if options[:on].present?
-        on_condition = on_condition.and(tagging_alias[:context].eq(options[:on]))
+        condition = condition.and(tagging_arel_table[:context].eq(options[:on]))
       end
 
       if (owner = options[:owned_by]).present?
-        on_condition = on_condition.and(tagging_alias[:tagger_id].eq(owner.id))
-          .and(tagging_alias[:tagger_type].eq(owner.class.base_class.to_s))
+        condition = condition.and(tagging_arel_table[:tagger_id].eq(owner.id))
+          .and(tagging_arel_table[:tagger_type].eq(owner.class.base_class.to_s))
       end
 
-      on_condition
+      condition
+    end
+
+    # :match_all keeps its outer join. It counts a record's taggings and compares
+    # that to the number of tags matched, so it needs them joined -- and the
+    # GROUP BY it already carries collapses the duplicates a join would cause.
+    def match_all_join
+      return [] unless options[:match_all].present?
+
+      taggable_arel_table
+        .join(tagging_arel_table, Arel::Nodes::OuterJoin)
+        .on(match_all_on_conditions)
+        .join_sources
     end
 
     def match_all_on_conditions
@@ -107,15 +116,17 @@ module MakeTaggable::Taggable::TaggedWithQuery
 
     def order_conditions
       order_by = []
-      order_by << tagging_arel_table.project(tagging_arel_table[Arel.star].count.as("taggings_count")).order("taggings_count DESC").to_sql if options[:order_by_matching_tag_count].present? && options[:match_all].blank?
+
+      # The old expression here counted every tagging in the table, correlated
+      # to nothing, and asked for COUNT(taggings.*) while doing it -- invalid
+      # SQL that ordered nothing even where it parsed. The shared correlated
+      # count is what the :any strategy has always used.
+      if options[:order_by_matching_tag_count].present? && options[:match_all].blank?
+        order_by << matching_tag_count_order
+      end
 
       order_by << options[:order] if options[:order].present?
       order_by.join(", ")
     end
-
-    def tagging_alias(tag)
-      alias_base_name = taggable_model.base_class.name.downcase
-      adjust_taggings_alias("#{alias_base_name[0..11]}_taggings_#{MakeTaggable::Utils.sha_prefix(tag)}")
-    end
   end
 end

data/lib/make_taggable/taggable/tagged_with_query/any_tags_query.rb

@@ -11,55 +11,26 @@ module MakeTaggable::Taggable::TaggedWithQuery
     # @return [ActiveRecord::Relation]
     #
     def build
-      taggable_model.select(all_fields)
-        .where(model_has_at_least_one_tag)
+      # No select of our own. This strategy filters with an EXISTS subquery and
+      # joins nothing, so Active Record's default select list is already right.
+      # Forcing `taggable_models.*` made COUNT() invalid and left a caller's own
+      # select appended after the star rather than replacing it.
+      taggable_model
+        .where(model_has_matching_taggings)
         .order(Arel.sql(order_conditions))
         .readonly(false)
     end
 
     private
 
-    def all_fields
-      taggable_arel_table[Arel.star]
-    end
-
-    def model_has_at_least_one_tag
-      tagging_arel_table.project(Arel.star).where(at_least_one_tag).exists
-    end
-
-    def at_least_one_tag
-      exists_contition = tagging_arel_table[:taggable_id].eq(taggable_arel_table[taggable_model.primary_key])
-        .and(tagging_arel_table[:taggable_type].eq(taggable_model.base_class.name))
-        .and(
-          tagging_arel_table[:tag_id].in(
-            tag_arel_table.project(tag_arel_table[:id]).where(tags_match_type)
-          )
-        )
-
-      if options[:start_at].present?
-        exists_contition = exists_contition.and(tagging_arel_table[:created_at].gteq(options[:start_at]))
-      end
-
-      if options[:end_at].present?
-        exists_contition = exists_contition.and(tagging_arel_table[:created_at].lteq(options[:end_at]))
-      end
-
-      if options[:on].present?
-        exists_contition = exists_contition.and(tagging_arel_table[:context].eq(options[:on]))
-      end
-
-      if (owner = options[:owned_by]).present?
-        exists_contition = exists_contition.and(tagging_arel_table[:tagger_id].eq(owner.id))
-          .and(tagging_arel_table[:tagger_type].eq(owner.class.base_class.to_s))
-      end
-
-      exists_contition
+    def model_has_matching_taggings
+      tagging_arel_table.project(Arel.star).where(matching_taggings).exists
     end
 
     def order_conditions
       order_by = []
       if options[:order_by_matching_tag_count].present?
-        order_by << "(SELECT count(*) FROM #{tagging_model.table_name} WHERE #{at_least_one_tag.to_sql}) desc"
+        order_by << matching_tag_count_order
       end
 
       order_by << options[:order] if options[:order].present?

data/lib/make_taggable/taggable/tagged_with_query/exclude_tags_query.rb

@@ -24,20 +24,27 @@ module MakeTaggable::Taggable::TaggedWithQuery
         .and(tagging_arel_table[:taggable_type].eq(taggable_model.base_class.name))
         .and(tags_match_type)
 
-      # Without this the subquery gathers taggings from every context, so a
-      # record tagged in one context is excluded from a query about another.
+      # Every option below narrows which taggings count as "carrying the tag".
+      # Left off, the subquery gathers taggings from other contexts and other
+      # times, and excludes records on the strength of them.
       if options[:on].present?
         on_condition = on_condition.and(tagging_arel_table[:context].eq(options[:on]))
       end
 
+      if options[:start_at].present?
+        on_condition = on_condition.and(tagging_arel_table[:created_at].gteq(options[:start_at]))
+      end
+
+      if options[:end_at].present?
+        on_condition = on_condition.and(tagging_arel_table[:created_at].lteq(options[:end_at]))
+      end
+
       taggable_arel_table[taggable_model.primary_key].not_in(
         tagging_arel_table
           .project(tagging_arel_table[:taggable_id])
           .join(tag_arel_table)
           .on(on_condition)
       )
-
-      # FIXME: missing time scope, this is also missing in the original implementation
     end
 
     def owning_to_tagger

data/lib/make_taggable/taggable/tagged_with_query/query_base.rb

@@ -61,6 +61,46 @@ module MakeTaggable::Taggable::TaggedWithQuery
       end
     end
 
+    # A condition selecting the taggings that tie a row of the taggable table to
+    # one of the tags being matched, narrowed by whichever of :on, :owned_by,
+    # :start_at and :end_at were given.
+    #
+    # It correlates to the taggable table, so it only means anything inside a
+    # subquery -- an EXISTS test, or a COUNT used for ordering.
+    def matching_taggings
+      condition = tagging_arel_table[:taggable_id].eq(taggable_arel_table[taggable_model.primary_key])
+        .and(tagging_arel_table[:taggable_type].eq(taggable_model.base_class.name))
+        .and(
+          tagging_arel_table[:tag_id].in(
+            tag_arel_table.project(tag_arel_table[:id]).where(tags_match_type)
+          )
+        )
+
+      if options[:start_at].present?
+        condition = condition.and(tagging_arel_table[:created_at].gteq(options[:start_at]))
+      end
+
+      if options[:end_at].present?
+        condition = condition.and(tagging_arel_table[:created_at].lteq(options[:end_at]))
+      end
+
+      if options[:on].present?
+        condition = condition.and(tagging_arel_table[:context].eq(options[:on]))
+      end
+
+      if (owner = options[:owned_by]).present?
+        condition = condition.and(tagging_arel_table[:tagger_id].eq(owner.id))
+          .and(tagging_arel_table[:tagger_type].eq(owner.class.base_class.to_s))
+      end
+
+      condition
+    end
+
+    # Orders by how many of the matched taggings a row has, most first.
+    def matching_tag_count_order
+      "(SELECT count(*) FROM #{tagging_model.table_name} WHERE #{matching_taggings.to_sql}) desc"
+    end
+
     def escaped_tag(tag)
       tag = tag.downcase unless MakeTaggable.strict_case_match
       MakeTaggable::Utils.escape_like(tag)

data/lib/make_taggable/version.rb

@@ -6,5 +6,5 @@ module MakeTaggable
   #
   # @return [String]
   #
-  VERSION = "1.2.1"
+  VERSION = "1.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: make_taggable
 version: !ruby/object:Gem::Version
-  version: 1.2.1
+  version: 1.3.0
 platform: ruby
 authors:
 - Matthew Kennedy