diff options
| -rw-r--r-- | activerecord/lib/active_record/relation/query_methods.rb | 14 | ||||
| -rw-r--r-- | railties/guides/source/active_record_querying.textile | 24 |
2 files changed, 31 insertions, 7 deletions
diff --git a/activerecord/lib/active_record/relation/query_methods.rb b/activerecord/lib/active_record/relation/query_methods.rb index 6a28d7b155..b6d762c2e2 100644 --- a/activerecord/lib/active_record/relation/query_methods.rb +++ b/activerecord/lib/active_record/relation/query_methods.rb @@ -201,26 +201,26 @@ module ActiveRecord # # The returned NullRelation inherits from Relation and implements the # Null Object pattern so it is an object with defined null behavior: - # it always returns an empty array of records and avoids any database query. + # it always returns an empty array of records and does not query the database. # # Any subsequent condition chained to the returned relation will continue # generating an empty relation and will not fire any query to the database. # - # Used in cases where is needed a method or a scope that could return zero - # results but the response has to be chainable. + # This is useful in scenarios where you need a chainable response to a method + # or a scope that could return zero results. # # For example: # # @posts = current_user.visible_posts.where(:name => params[:name]) - # # => the visible_post method response has to be a chainable Relation + # # => the visible_posts method is expected to return a chainable Relation # # def visible_posts # case role - # if 'Country Manager' + # when 'Country Manager' # Post.where(:country => country) - # if 'Reviewer' + # when 'Reviewer' # Post.published - # if 'Bad User' + # when 'Bad User' # Post.none # => returning [] instead breaks the previous code # end # end diff --git a/railties/guides/source/active_record_querying.textile b/railties/guides/source/active_record_querying.textile index 3b4f2befda..21bbc64255 100644 --- a/railties/guides/source/active_record_querying.textile +++ b/railties/guides/source/active_record_querying.textile @@ -608,6 +608,30 @@ SELECT * FROM clients WHERE orders_count > 10 ORDER BY clients.id DESC This method accepts *no* arguments. +h3. Null Relation + +The +none+ method returns a chainable relation with no records. Any subsequent conditions chained to the returned relation will continue generating empty relations. This is useful in scenarios where you need a chainable response to a method or a scope that could return zero results. + +<ruby> +Post.none # returns an empty Relation and fires no queries. +</ruby> + +<ruby> +# The visible_posts method below is expected to return a Relation. +@posts = current_user.visible_posts.where(:name => params[:name]) + +def visible_posts + case role + when 'Country Manager' + Post.where(:country => country) + when 'Reviewer' + Post.published + when 'Bad User' + Post.none # => returning [] or nil breaks the caller code in this case + end +end +</ruby> + h3. Readonly Objects Active Record provides +readonly+ method on a relation to explicitly disallow modification of any of the returned objects. Any attempt to alter a readonly record will not succeed, raising an +ActiveRecord::ReadOnlyRecord+ exception. |