Skip to content

Commit

Permalink
Improve where chaining docs
Browse files Browse the repository at this point in the history
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 <jonathan@hefner.pro>
  • Loading branch information
ghiculescu and jonathanhefner committed Jun 14, 2022
1 parent 89a964d commit 095036c
Showing 1 changed file with 19 additions and 5 deletions.
24 changes: 19 additions & 5 deletions activerecord/lib/active_record/relation/query_methods.rb
Expand Up @@ -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

Expand Down Expand Up @@ -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
#
Expand Down

0 comments on commit 095036c

Please sign in to comment.