Module: ActiveRecord::FinderMethods
- Included in:
- Relation
- Defined in:
- lib/active_record/relation/finder_methods.rb
Constant Summary collapse
- ONE_AS_ONE =
"1 AS one"
Instance Method Summary collapse
-
#exists?(conditions = :none) ⇒ Boolean
Returns true if a record exists in the table that matches the
id
or conditions given, or false otherwise. -
#fifth ⇒ Object
Find the fifth record.
-
#fifth! ⇒ Object
Same as #fifth but raises ActiveRecord::RecordNotFound if no record is found.
-
#find(*args) ⇒ Object
Find by id - This can either be a specific id (1), a list of ids (1, 5, 6), or an array of ids ([5, 6, 10]).
-
#find_by(arg, *args) ⇒ Object
Finds the first record matching the specified conditions.
-
#find_by!(arg, *args) ⇒ Object
Like #find_by, except that if no record is found, raises an ActiveRecord::RecordNotFound error.
-
#first(limit = nil) ⇒ Object
Find the first record (or first N records if a parameter is supplied).
-
#first! ⇒ Object
Same as #first but raises ActiveRecord::RecordNotFound if no record is found.
-
#forty_two ⇒ Object
Find the forty-second record.
-
#forty_two! ⇒ Object
Same as #forty_two but raises ActiveRecord::RecordNotFound if no record is found.
-
#fourth ⇒ Object
Find the fourth record.
-
#fourth! ⇒ Object
Same as #fourth but raises ActiveRecord::RecordNotFound if no record is found.
-
#last(limit = nil) ⇒ Object
Find the last record (or last N records if a parameter is supplied).
-
#last! ⇒ Object
Same as #last but raises ActiveRecord::RecordNotFound if no record is found.
-
#raise_record_not_found_exception!(ids = nil, result_size = nil, expected_size = nil, key = primary_key, not_found_ids = nil) ⇒ Object
This method is called whenever no records are found with either a single id or multiple ids and raises an ActiveRecord::RecordNotFound exception.
-
#second ⇒ Object
Find the second record.
-
#second! ⇒ Object
Same as #second but raises ActiveRecord::RecordNotFound if no record is found.
-
#second_to_last ⇒ Object
Find the second-to-last record.
-
#second_to_last! ⇒ Object
Same as #second_to_last but raises ActiveRecord::RecordNotFound if no record is found.
-
#take(limit = nil) ⇒ Object
Gives a record (or N records if a parameter is supplied) without any implied order.
-
#take! ⇒ Object
Same as #take but raises ActiveRecord::RecordNotFound if no record is found.
-
#third ⇒ Object
Find the third record.
-
#third! ⇒ Object
Same as #third but raises ActiveRecord::RecordNotFound if no record is found.
-
#third_to_last ⇒ Object
Find the third-to-last record.
-
#third_to_last! ⇒ Object
Same as #third_to_last but raises ActiveRecord::RecordNotFound if no record is found.
Instance Method Details
#exists?(conditions = :none) ⇒ Boolean
Returns true if a record exists in the table that matches the id
or conditions given, or false otherwise. The argument can take six forms:
-
Integer - Finds the record with this primary key.
-
String - Finds the record with a primary key corresponding to this string (such as
'5'
). -
Array - Finds the record that matches these
find
-style conditions (such as['name LIKE ?', "%#{query}%"]
). -
Hash - Finds the record that matches these
find
-style conditions (such as{name: 'David'}
). -
false
- Returns alwaysfalse
. -
No args - Returns
false
if the relation is empty,true
otherwise.
For more information about specifying conditions as a hash or array, see the Conditions section in the introduction to ActiveRecord::Base.
Note: You can’t pass in a condition as a string (like name = 'Jamie'
), since it would be sanitized and then queried against the primary key column, like id = 'name = \'Jamie\''
.
Person.exists?(5)
Person.exists?('5')
Person.exists?(['name LIKE ?', "%#{query}%"])
Person.exists?(id: [1, 4, 8])
Person.exists?(name: 'David')
Person.exists?(false)
Person.exists?
Person.where(name: 'Spartacus', rating: 4).exists?
300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 |
# File 'lib/active_record/relation/finder_methods.rb', line 300 def exists?(conditions = :none) if Base === conditions raise ArgumentError, <<-MSG.squish You are passing an instance of ActiveRecord::Base to `exists?`. Please pass the id of the object by calling `.id`. MSG end return false if !conditions || limit_value == 0 if eager_loading? relation = apply_join_dependency(eager_loading: false) return relation.exists?(conditions) end relation = construct_relation_for_exists(conditions) skip_query_cache_if_necessary { connection.select_one(relation.arel, "#{name} Exists?") } ? true : false end |
#fifth ⇒ Object
Find the fifth record. If no order is defined it will order by primary key.
Person.fifth # returns the fifth object fetched by SELECT * FROM people
Person.offset(3).fifth # returns the fifth object from OFFSET 3 (which is OFFSET 7)
Person.where(["user_name = :u", { u: user_name }]).fifth
214 215 216 |
# File 'lib/active_record/relation/finder_methods.rb', line 214 def fifth find_nth 4 end |
#fifth! ⇒ Object
Same as #fifth but raises ActiveRecord::RecordNotFound if no record is found.
220 221 222 |
# File 'lib/active_record/relation/finder_methods.rb', line 220 def fifth! fifth || raise_record_not_found_exception! end |
#find(*args) ⇒ Object
Find by id - This can either be a specific id (1), a list of ids (1, 5, 6), or an array of ids ([5, 6, 10]). If one or more records cannot be found for the requested ids, then ActiveRecord::RecordNotFound will be raised. If the primary key is an integer, find by id coerces its arguments by using to_i
.
Person.find(1) # returns the object for ID = 1
Person.find("1") # returns the object for ID = 1
Person.find("31-sarah") # returns the object for ID = 31
Person.find(1, 2, 6) # returns an array for objects with IDs in (1, 2, 6)
Person.find([7, 17]) # returns an array for objects with IDs in (7, 17)
Person.find([1]) # returns an array for the object with ID = 1
Person.where("administrator = 1").order("created_on DESC").find(1)
NOTE: The returned records are in the same order as the ids you provide. If you want the results to be sorted by database, you can use ActiveRecord::QueryMethods#where method and provide an explicit ActiveRecord::QueryMethods#order option. But ActiveRecord::QueryMethods#where method doesn’t raise ActiveRecord::RecordNotFound.
Find with lock
Example for find with a lock: Imagine two concurrent transactions: each will read person.visits == 2
, add 1 to it, and save, resulting in two saves of person.visits = 3
. By locking the row, the second transaction has to wait until the first is finished; we get the expected person.visits == 4
.
Person.transaction do
person = Person.lock(true).find(1)
person.visits += 1
person.save!
end
Variations of #find
Person.where(name: 'Spartacus', rating: 4)
# returns a chainable list (which can be empty).
Person.find_by(name: 'Spartacus', rating: 4)
# returns the first item or nil.
Person.find_or_initialize_by(name: 'Spartacus', rating: 4)
# returns the first item or returns a new instance (requires you call .save to persist against the database).
Person.find_or_create_by(name: 'Spartacus', rating: 4)
# returns the first item or creates it and returns it.
Alternatives for #find
Person.where(name: 'Spartacus', rating: 4).exists?(conditions = :none)
# returns a boolean indicating if any record with the given conditions exist.
Person.where(name: 'Spartacus', rating: 4).select("field1, field2, field3")
# returns a chainable list of instances with only the mentioned fields.
Person.where(name: 'Spartacus', rating: 4).ids
# returns an Array of ids.
Person.where(name: 'Spartacus', rating: 4).pluck(:field1, :field2)
# returns an Array of the required fields.
67 68 69 70 |
# File 'lib/active_record/relation/finder_methods.rb', line 67 def find(*args) return super if block_given? find_with_ids(*args) end |
#find_by(arg, *args) ⇒ Object
Finds the first record matching the specified conditions. There is no implied ordering so if order matters, you should specify it yourself.
If no record is found, returns nil
.
Post.find_by name: 'Spartacus', rating: 4
Post.find_by "published_at < ?", 2.weeks.ago
80 81 82 |
# File 'lib/active_record/relation/finder_methods.rb', line 80 def find_by(arg, *args) where(arg, *args).take end |
#find_by!(arg, *args) ⇒ Object
Like #find_by, except that if no record is found, raises an ActiveRecord::RecordNotFound error.
86 87 88 |
# File 'lib/active_record/relation/finder_methods.rb', line 86 def find_by!(arg, *args) where(arg, *args).take! end |
#first(limit = nil) ⇒ Object
Find the first record (or first N records if a parameter is supplied). If no order is defined it will order by primary key.
Person.first # returns the first object fetched by SELECT * FROM people ORDER BY people.id LIMIT 1
Person.where(["user_name = ?", user_name]).first
Person.where(["user_name = :u", { u: user_name }]).first
Person.order("created_on DESC").offset(5).first
Person.first(3) # returns the first three objects fetched by SELECT * FROM people ORDER BY people.id LIMIT 3
116 117 118 119 120 121 122 |
# File 'lib/active_record/relation/finder_methods.rb', line 116 def first(limit = nil) if limit find_nth_with_limit(0, limit) else find_nth 0 end end |
#first! ⇒ Object
Same as #first but raises ActiveRecord::RecordNotFound if no record is found. Note that #first! accepts no arguments.
126 127 128 |
# File 'lib/active_record/relation/finder_methods.rb', line 126 def first! first || raise_record_not_found_exception! end |
#forty_two ⇒ Object
Find the forty-second record. Also known as accessing “the reddit”. If no order is defined it will order by primary key.
Person.forty_two # returns the forty-second object fetched by SELECT * FROM people
Person.offset(3).forty_two # returns the forty-second object from OFFSET 3 (which is OFFSET 44)
Person.where(["user_name = :u", { u: user_name }]).forty_two
230 231 232 |
# File 'lib/active_record/relation/finder_methods.rb', line 230 def forty_two find_nth 41 end |
#forty_two! ⇒ Object
Same as #forty_two but raises ActiveRecord::RecordNotFound if no record is found.
236 237 238 |
# File 'lib/active_record/relation/finder_methods.rb', line 236 def forty_two! forty_two || raise_record_not_found_exception! end |
#fourth ⇒ Object
Find the fourth record. If no order is defined it will order by primary key.
Person.fourth # returns the fourth object fetched by SELECT * FROM people
Person.offset(3).fourth # returns the fourth object from OFFSET 3 (which is OFFSET 6)
Person.where(["user_name = :u", { u: user_name }]).fourth
198 199 200 |
# File 'lib/active_record/relation/finder_methods.rb', line 198 def fourth find_nth 3 end |
#fourth! ⇒ Object
Same as #fourth but raises ActiveRecord::RecordNotFound if no record is found.
204 205 206 |
# File 'lib/active_record/relation/finder_methods.rb', line 204 def fourth! fourth || raise_record_not_found_exception! end |
#last(limit = nil) ⇒ Object
Find the last record (or last N records if a parameter is supplied). If no order is defined it will order by primary key.
Person.last # returns the last object fetched by SELECT * FROM people
Person.where(["user_name = ?", user_name]).last
Person.order("created_on DESC").offset(5).last
Person.last(3) # returns the last three objects fetched by SELECT * FROM people.
Take note that in that last case, the results are sorted in ascending order:
[#<Person id:2>, #<Person id:3>, #<Person id:4>]
and not:
[#<Person id:4>, #<Person id:3>, #<Person id:2>]
145 146 147 148 149 150 151 152 |
# File 'lib/active_record/relation/finder_methods.rb', line 145 def last(limit = nil) return find_last(limit) if loaded? || has_limit_or_offset? result = ordered_relation.limit(limit) result = result.reverse_order! limit ? result.reverse : result.first end |
#last! ⇒ Object
Same as #last but raises ActiveRecord::RecordNotFound if no record is found. Note that #last! accepts no arguments.
156 157 158 |
# File 'lib/active_record/relation/finder_methods.rb', line 156 def last! last || raise_record_not_found_exception! end |
#raise_record_not_found_exception!(ids = nil, result_size = nil, expected_size = nil, key = primary_key, not_found_ids = nil) ⇒ Object
This method is called whenever no records are found with either a single id or multiple ids and raises an ActiveRecord::RecordNotFound exception.
The error message is different depending on whether a single id or multiple ids are provided. If multiple ids are provided, then the number of results obtained should be provided in the result_size
argument and the expected number of results should be provided in the expected_size
argument.
328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 |
# File 'lib/active_record/relation/finder_methods.rb', line 328 def raise_record_not_found_exception!(ids = nil, result_size = nil, expected_size = nil, key = primary_key, not_found_ids = nil) # :nodoc: conditions = arel.where_sql(@klass) conditions = " [#{conditions}]" if conditions name = @klass.name if ids.nil? error = +"Couldn't find #{name}" error << " with#{conditions}" if conditions raise RecordNotFound.new(error, name, key) elsif Array(ids).size == 1 error = "Couldn't find #{name} with '#{key}'=#{ids}#{conditions}" raise RecordNotFound.new(error, name, key, ids) else error = +"Couldn't find all #{name.pluralize} with '#{key}': " error << "(#{ids.join(", ")})#{conditions} (found #{result_size} results, but was looking for #{expected_size})." error << " Couldn't find #{name.pluralize(not_found_ids.size)} with #{key.to_s.pluralize(not_found_ids.size)} #{not_found_ids.join(', ')}." if not_found_ids raise RecordNotFound.new(error, name, key, ids) end end |
#second ⇒ Object
Find the second record. If no order is defined it will order by primary key.
Person.second # returns the second object fetched by SELECT * FROM people
Person.offset(3).second # returns the second object from OFFSET 3 (which is OFFSET 4)
Person.where(["user_name = :u", { u: user_name }]).second
166 167 168 |
# File 'lib/active_record/relation/finder_methods.rb', line 166 def second find_nth 1 end |
#second! ⇒ Object
Same as #second but raises ActiveRecord::RecordNotFound if no record is found.
172 173 174 |
# File 'lib/active_record/relation/finder_methods.rb', line 172 def second! second || raise_record_not_found_exception! end |
#second_to_last ⇒ Object
Find the second-to-last record. If no order is defined it will order by primary key.
Person.second_to_last # returns the second-to-last object fetched by SELECT * FROM people
Person.offset(3).second_to_last # returns the second-to-last object from OFFSET 3
Person.where(["user_name = :u", { u: user_name }]).second_to_last
262 263 264 |
# File 'lib/active_record/relation/finder_methods.rb', line 262 def second_to_last find_nth_from_last 2 end |
#second_to_last! ⇒ Object
Same as #second_to_last but raises ActiveRecord::RecordNotFound if no record is found.
268 269 270 |
# File 'lib/active_record/relation/finder_methods.rb', line 268 def second_to_last! second_to_last || raise_record_not_found_exception! end |
#take(limit = nil) ⇒ Object
Gives a record (or N records if a parameter is supplied) without any implied order. The order will depend on the database implementation. If an order is supplied it will be respected.
Person.take # returns an object fetched by SELECT * FROM people LIMIT 1
Person.take(5) # returns 5 objects fetched by SELECT * FROM people LIMIT 5
Person.where(["name LIKE '%?'", name]).take
97 98 99 |
# File 'lib/active_record/relation/finder_methods.rb', line 97 def take(limit = nil) limit ? find_take_with_limit(limit) : find_take end |
#take! ⇒ Object
Same as #take but raises ActiveRecord::RecordNotFound if no record is found. Note that #take! accepts no arguments.
103 104 105 |
# File 'lib/active_record/relation/finder_methods.rb', line 103 def take! take || raise_record_not_found_exception! end |
#third ⇒ Object
Find the third record. If no order is defined it will order by primary key.
Person.third # returns the third object fetched by SELECT * FROM people
Person.offset(3).third # returns the third object from OFFSET 3 (which is OFFSET 5)
Person.where(["user_name = :u", { u: user_name }]).third
182 183 184 |
# File 'lib/active_record/relation/finder_methods.rb', line 182 def third find_nth 2 end |
#third! ⇒ Object
Same as #third but raises ActiveRecord::RecordNotFound if no record is found.
188 189 190 |
# File 'lib/active_record/relation/finder_methods.rb', line 188 def third! third || raise_record_not_found_exception! end |
#third_to_last ⇒ Object
Find the third-to-last record. If no order is defined it will order by primary key.
Person.third_to_last # returns the third-to-last object fetched by SELECT * FROM people
Person.offset(3).third_to_last # returns the third-to-last object from OFFSET 3
Person.where(["user_name = :u", { u: user_name }]).third_to_last
246 247 248 |
# File 'lib/active_record/relation/finder_methods.rb', line 246 def third_to_last find_nth_from_last 3 end |
#third_to_last! ⇒ Object
Same as #third_to_last but raises ActiveRecord::RecordNotFound if no record is found.
252 253 254 |
# File 'lib/active_record/relation/finder_methods.rb', line 252 def third_to_last! third_to_last || raise_record_not_found_exception! end |