Methods
A
C
E
F
L
O
S
T
U
Constants
ONE_AS_ONE = "1 AS one"
 
Instance Public methods
exists?(conditions = :none)

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 always false.

  • 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?
    # File activerecord/lib/active_record/relation/finder_methods.rb
300     def exists?(conditions = :none)
301       if Base === conditions
302         raise ArgumentError, <<-MSG.squish
303           You are passing an instance of ActiveRecord::Base to `exists?`.
304           Please pass the id of the object by calling `.id`.
305         MSG
306       end
307 
308       return false if !conditions || limit_value == 0
309 
310       if eager_loading?
311         relation = apply_join_dependency(eager_loading: false)
312         return relation.exists?(conditions)
313       end
314 
315       relation = construct_relation_for_exists(conditions)
316 
317       skip_query_cache_if_necessary { connection.select_one(relation.arel, "#{name} Exists?") } ? true : false
318     end
fifth()

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
    # File activerecord/lib/active_record/relation/finder_methods.rb
214 def fifth
215   find_nth 4
216 end
fifth!()

Same as fifth but raises ActiveRecord::RecordNotFound if no record is found.

    # File activerecord/lib/active_record/relation/finder_methods.rb
220 def fifth!
221   fifth || raise_record_not_found_exception!
222 end
find(*args)

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.
   # File activerecord/lib/active_record/relation/finder_methods.rb
67 def find(*args)
68   return super if block_given?
69   find_with_ids(*args)
70 end
find_by(arg, *args)

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
   # File activerecord/lib/active_record/relation/finder_methods.rb
80 def find_by(arg, *args)
81   where(arg, *args).take
82 end
find_by!(arg, *args)

Like find_by, except that if no record is found, raises an ActiveRecord::RecordNotFound error.

   # File activerecord/lib/active_record/relation/finder_methods.rb
86 def find_by!(arg, *args)
87   where(arg, *args).take!
88 end
first(limit = nil)

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
    # File activerecord/lib/active_record/relation/finder_methods.rb
116 def first(limit = nil)
117   if limit
118     find_nth_with_limit(0, limit)
119   else
120     find_nth 0
121   end
122 end
first!()

Same as first but raises ActiveRecord::RecordNotFound if no record is found. Note that first! accepts no arguments.

    # File activerecord/lib/active_record/relation/finder_methods.rb
126 def first!
127   first || raise_record_not_found_exception!
128 end
forty_two()

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
    # File activerecord/lib/active_record/relation/finder_methods.rb
230 def forty_two
231   find_nth 41
232 end
forty_two!()

Same as forty_two but raises ActiveRecord::RecordNotFound if no record is found.

    # File activerecord/lib/active_record/relation/finder_methods.rb
236 def forty_two!
237   forty_two || raise_record_not_found_exception!
238 end
fourth()

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
    # File activerecord/lib/active_record/relation/finder_methods.rb
198 def fourth
199   find_nth 3
200 end
fourth!()

Same as fourth but raises ActiveRecord::RecordNotFound if no record is found.

    # File activerecord/lib/active_record/relation/finder_methods.rb
204 def fourth!
205   fourth || raise_record_not_found_exception!
206 end
last(limit = nil)

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>]
    # File activerecord/lib/active_record/relation/finder_methods.rb
145 def last(limit = nil)
146   return find_last(limit) if loaded? || has_limit_or_offset?
147 
148   result = ordered_relation.limit(limit)
149   result = result.reverse_order!
150 
151   limit ? result.reverse : result.first
152 end
last!()

Same as last but raises ActiveRecord::RecordNotFound if no record is found. Note that last! accepts no arguments.

    # File activerecord/lib/active_record/relation/finder_methods.rb
156 def last!
157   last || raise_record_not_found_exception!
158 end
second()

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
    # File activerecord/lib/active_record/relation/finder_methods.rb
166 def second
167   find_nth 1
168 end
second!()

Same as second but raises ActiveRecord::RecordNotFound if no record is found.

    # File activerecord/lib/active_record/relation/finder_methods.rb
172 def second!
173   second || raise_record_not_found_exception!
174 end
second_to_last()

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
    # File activerecord/lib/active_record/relation/finder_methods.rb
262 def second_to_last
263   find_nth_from_last 2
264 end
second_to_last!()

Same as second_to_last but raises ActiveRecord::RecordNotFound if no record is found.

    # File activerecord/lib/active_record/relation/finder_methods.rb
268 def second_to_last!
269   second_to_last || raise_record_not_found_exception!
270 end
take(limit = nil)

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
   # File activerecord/lib/active_record/relation/finder_methods.rb
97 def take(limit = nil)
98   limit ? find_take_with_limit(limit) : find_take
99 end
take!()

Same as take but raises ActiveRecord::RecordNotFound if no record is found. Note that take! accepts no arguments.

    # File activerecord/lib/active_record/relation/finder_methods.rb
103 def take!
104   take || raise_record_not_found_exception!
105 end
third()

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
    # File activerecord/lib/active_record/relation/finder_methods.rb
182 def third
183   find_nth 2
184 end
third!()

Same as third but raises ActiveRecord::RecordNotFound if no record is found.

    # File activerecord/lib/active_record/relation/finder_methods.rb
188 def third!
189   third || raise_record_not_found_exception!
190 end
third_to_last()

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
    # File activerecord/lib/active_record/relation/finder_methods.rb
246 def third_to_last
247   find_nth_from_last 3
248 end
third_to_last!()

Same as third_to_last but raises ActiveRecord::RecordNotFound if no record is found.

    # File activerecord/lib/active_record/relation/finder_methods.rb
252 def third_to_last!
253   third_to_last || raise_record_not_found_exception!
254 end
Instance Private methods
apply_join_dependency(eager_loading: group_values.empty?)
    # File activerecord/lib/active_record/relation/finder_methods.rb
373 def apply_join_dependency(eager_loading: group_values.empty?)
374   join_dependency = construct_join_dependency(
375     eager_load_values + includes_values, Arel::Nodes::OuterJoin
376   )
377   relation = except(:includes, :eager_load, :preload).joins!(join_dependency)
378 
379   if eager_loading && !using_limitable_reflections?(join_dependency.reflections)
380     if has_limit_or_offset?
381       limited_ids = limited_ids_for(relation)
382       limited_ids.empty? ? relation.none! : relation.where!(primary_key => limited_ids)
383     end
384     relation.limit_value = relation.offset_value = nil
385   end
386 
387   if block_given?
388     yield relation, join_dependency
389   else
390     relation
391   end
392 end
construct_relation_for_exists(conditions)
    # File activerecord/lib/active_record/relation/finder_methods.rb
354 def construct_relation_for_exists(conditions)
355   conditions = sanitize_forbidden_attributes(conditions)
356 
357   if distinct_value && offset_value
358     relation = except(:order).limit!(1)
359   else
360     relation = except(:select, :distinct, :order)._select!(ONE_AS_ONE).limit!(1)
361   end
362 
363   case conditions
364   when Array, Hash
365     relation.where!(conditions) unless conditions.empty?
366   else
367     relation.where!(primary_key => conditions) unless conditions == :none
368   end
369 
370   relation
371 end
find_last(limit)
    # File activerecord/lib/active_record/relation/finder_methods.rb
540 def find_last(limit)
541   limit ? records.last(limit) : records.last
542 end
find_nth(index)
    # File activerecord/lib/active_record/relation/finder_methods.rb
503 def find_nth(index)
504   @offsets[offset_index + index] ||= find_nth_with_limit(index, 1).first
505 end
find_nth_from_last(index)
    # File activerecord/lib/active_record/relation/finder_methods.rb
526 def find_nth_from_last(index)
527   if loaded?
528     records[-index]
529   else
530     relation = ordered_relation
531 
532     if equal?(relation) || has_limit_or_offset?
533       relation.records[-index]
534     else
535       relation.last(index)[-index]
536     end
537   end
538 end
find_nth_with_limit(index, limit)
    # File activerecord/lib/active_record/relation/finder_methods.rb
507 def find_nth_with_limit(index, limit)
508   if loaded?
509     records[index, limit] || []
510   else
511     relation = ordered_relation
512 
513     if limit_value
514       limit = [limit_value - index, limit].min
515     end
516 
517     if limit > 0
518       relation = relation.offset(offset_index + index) unless index.zero?
519       relation.limit(limit).to_a
520     else
521       []
522     end
523   end
524 end
find_one(id)
    # File activerecord/lib/active_record/relation/finder_methods.rb
432       def find_one(id)
433         if ActiveRecord::Base === id
434           raise ArgumentError, <<-MSG.squish
435             You are passing an instance of ActiveRecord::Base to `find`.
436             Please pass the id of the object by calling `.id`.
437           MSG
438         end
439 
440         relation = where(primary_key => id)
441         record = relation.take
442 
443         raise_record_not_found_exception!(id, 0, 1) unless record
444 
445         record
446       end
find_some(ids)
    # File activerecord/lib/active_record/relation/finder_methods.rb
448 def find_some(ids)
449   return find_some_ordered(ids) unless order_values.present?
450 
451   result = where(primary_key => ids).to_a
452 
453   expected_size =
454     if limit_value && ids.size > limit_value
455       limit_value
456     else
457       ids.size
458     end
459 
460   # 11 ids with limit 3, offset 9 should give 2 results.
461   if offset_value && (ids.size - offset_value < expected_size)
462     expected_size = ids.size - offset_value
463   end
464 
465   if result.size == expected_size
466     result
467   else
468     raise_record_not_found_exception!(ids, result.size, expected_size)
469   end
470 end
find_some_ordered(ids)
    # File activerecord/lib/active_record/relation/finder_methods.rb
472 def find_some_ordered(ids)
473   ids = ids.slice(offset_value || 0, limit_value || ids.size) || []
474 
475   result = except(:limit, :offset).where(primary_key => ids).records
476 
477   if result.size == ids.size
478     pk_type = @klass.type_for_attribute(primary_key)
479 
480     records_by_id = result.index_by(&:id)
481     ids.map { |id| records_by_id.fetch(pk_type.cast(id)) }
482   else
483     raise_record_not_found_exception!(ids, result.size, ids.size)
484   end
485 end
find_take()
    # File activerecord/lib/active_record/relation/finder_methods.rb
487 def find_take
488   if loaded?
489     records.first
490   else
491     @take ||= limit(1).records.first
492   end
493 end
find_take_with_limit(limit)
    # File activerecord/lib/active_record/relation/finder_methods.rb
495 def find_take_with_limit(limit)
496   if loaded?
497     records.take(limit)
498   else
499     limit(limit).to_a
500   end
501 end
find_with_ids(*ids)
    # File activerecord/lib/active_record/relation/finder_methods.rb
410 def find_with_ids(*ids)
411   raise UnknownPrimaryKey.new(@klass) if primary_key.nil?
412 
413   expects_array = ids.first.kind_of?(Array)
414   return [] if expects_array && ids.first.empty?
415 
416   ids = ids.flatten.compact.uniq
417 
418   model_name = @klass.name
419 
420   case ids.size
421   when 0
422     error_message = "Couldn't find #{model_name} without an ID"
423     raise RecordNotFound.new(error_message, model_name, primary_key)
424   when 1
425     result = find_one(ids.first)
426     expects_array ? [ result ] : result
427   else
428     find_some(ids)
429   end
430 end
limited_ids_for(relation)
    # File activerecord/lib/active_record/relation/finder_methods.rb
394 def limited_ids_for(relation)
395   values = @klass.connection.columns_for_distinct(
396     connection.visitor.compile(arel_attribute(primary_key)),
397     relation.order_values
398   )
399 
400   relation = relation.except(:select).select(values).distinct!
401 
402   id_rows = skip_query_cache_if_necessary { @klass.connection.select_all(relation.arel, "SQL") }
403   id_rows.map { |row| row[primary_key] }
404 end
offset_index()
    # File activerecord/lib/active_record/relation/finder_methods.rb
350 def offset_index
351   offset_value || 0
352 end
ordered_relation()
    # File activerecord/lib/active_record/relation/finder_methods.rb
544 def ordered_relation
545   if order_values.empty? && (implicit_order_column || primary_key)
546     order(arel_attribute(implicit_order_column || primary_key).asc)
547   else
548     self
549   end
550 end
using_limitable_reflections?(reflections)
    # File activerecord/lib/active_record/relation/finder_methods.rb
406 def using_limitable_reflections?(reflections)
407   reflections.none?(&:collection?)
408 end