From 095036c9ab235e7288864635a07d410cce7c76b4 Mon Sep 17 00:00:00 2001 From: Alex Ghiculescu Date: Tue, 14 Jun 2022 10:25:11 -0500 Subject: [PATCH] Improve `where` chaining docs https://api.rubyonrails.org/classes/ActiveRecord/QueryMethods.html#method-i-where only discusses `where.not` in the "no argument" section. A `WhereChain` accepts `not`, `missing`, or `associated`, but you have to click through to https://api.rubyonrails.org/classes/ActiveRecord/QueryMethods/WhereChain.html to learn that. So this PR just updates the docs in https://api.rubyonrails.org/classes/ActiveRecord/QueryMethods.html#method-i-where to discuss all the chaining options. Co-authored-by: Jonathan Hefner --- .../active_record/relation/query_methods.rb | 24 +++++++++++++++---- 1 file changed, 19 insertions(+), 5 deletions(-) diff --git a/activerecord/lib/active_record/relation/query_methods.rb b/activerecord/lib/active_record/relation/query_methods.rb index 2ef642d61ca4..f6c97edd7a3a 100644 --- a/activerecord/lib/active_record/relation/query_methods.rb +++ b/activerecord/lib/active_record/relation/query_methods.rb @@ -10,10 +10,10 @@ module ActiveRecord module QueryMethods include ActiveModel::ForbiddenAttributesProtection - # WhereChain objects act as placeholder for queries in which #where does not have any parameter. - # In this case, #where must be chained with #not to return a new relation. + # WhereChain objects act as placeholder for queries in which +where+ does not have any parameter. + # In this case, +where+ can be chained to return a new relation. class WhereChain - def initialize(scope) + def initialize(scope) # :nodoc: @scope = scope end @@ -722,12 +722,26 @@ def left_outer_joins!(*args) # :nodoc: # === no argument # # If no argument is passed, #where returns a new instance of WhereChain, that - # can be chained with #not to return a new relation that negates the where clause. + # can be chained with WhereChain#not, WhereChain#missing, or WhereChain#associated. + # + # Chaining with WhereChain#not: # # User.where.not(name: "Jon") # # SELECT * FROM users WHERE name != 'Jon' # - # See WhereChain for more details on #not. + # Chaining with WhereChain#associated: + # + # Post.where.associated(:author) + # # SELECT "posts".* FROM "posts" + # # INNER JOIN "authors" ON "authors"."id" = "posts"."author_id" + # # WHERE "authors"."id" IS NOT NULL + # + # Chaining with WhereChain#missing: + # + # Post.where.missing(:author) + # # SELECT "posts".* FROM "posts" + # # LEFT OUTER JOIN "authors" ON "authors"."id" = "posts"."author_id" + # # WHERE "authors"."id" IS NULL # # === blank condition #