Methods

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 where-style conditions (such as ['name LIKE ?', "%#{query}%"]).

  • Hash - Finds the record that matches these where-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?
πŸ“ Source code
# File activerecord/lib/active_record/relation/finder_methods.rb, line 357
    def exists?(conditions = :none)
      return false if @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)
      return false if relation.where_clause.contradiction?

      skip_query_cache_if_necessary do
        with_connection do |c|
          c.select_rows(relation.arel, "#{model.name} Exists?").size == 1
        end
      end
    end
πŸ”Ž See on GitHub

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
πŸ“ Source code
# File activerecord/lib/active_record/relation/finder_methods.rb, line 271
    def fifth
      find_nth 4
    end
πŸ”Ž See on GitHub

fifth!()

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

πŸ“ Source code
# File activerecord/lib/active_record/relation/finder_methods.rb, line 277
    def fifth!
      fifth || raise_record_not_found_exception!
    end
πŸ”Ž See on GitHub

find(*args)

Find by id - This can either be a specific id (ID), a list of ids (ID, ID, ID), or an array of ids ([ID, ID, ID]). β€˜ID` refers to an β€œidentifier”. For models with a single-column primary key, `ID` will be a single value, and for models with a composite primary key, it will be an array of values. 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), or with composite primary key [7, 17]
Person.find([1])        # returns an array for the object with ID = 1
Person.where("administrator = 1").order("created_on DESC").find(1)

Find a record for a composite primary key model

TravelRoute.primary_key = [:origin, :destination]

TravelRoute.find(["Ottawa", "London"])
=> #<TravelRoute origin: "Ottawa", destination: "London">

TravelRoute.find([["Paris", "Montreal"]])
=> [#<TravelRoute origin: "Paris", destination: "Montreal">]

TravelRoute.find(["New York", "Las Vegas"], ["New York", "Portland"])
=> [
     #<TravelRoute origin: "New York", destination: "Las Vegas">,
     #<TravelRoute origin: "New York", destination: "Portland">
   ]

TravelRoute.find([["Berlin", "London"], ["Barcelona", "Lisbon"]])
=> [
     #<TravelRoute origin: "Berlin", destination: "London">,
     #<TravelRoute origin: "Barcelona", destination: "Lisbon">
   ]

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.

Edge Cases

Person.find(37)          # raises ActiveRecord::RecordNotFound exception if the record with the given ID does not exist.
Person.find([37])        # raises ActiveRecord::RecordNotFound exception if the record with the given ID in the input array does not exist.
Person.find(nil)         # raises ActiveRecord::RecordNotFound exception if the argument is nil.
Person.find([])          # returns an empty array if the argument is an empty array.
Person.find              # raises ActiveRecord::RecordNotFound exception if the argument is not provided.
πŸ“ Source code
# File activerecord/lib/active_record/relation/finder_methods.rb, line 98
    def find(*args)
      return super if block_given?
      find_with_ids(*args)
    end
πŸ”Ž See on GitHub

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
πŸ“ Source code
# File activerecord/lib/active_record/relation/finder_methods.rb, line 111
    def find_by(arg, *args)
      where(arg, *args).take
    end
πŸ”Ž See on GitHub

find_by!(arg, *args)

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

πŸ“ Source code
# File activerecord/lib/active_record/relation/finder_methods.rb, line 117
    def find_by!(arg, *args)
      where(arg, *args).take!
    end
πŸ”Ž See on GitHub

find_sole_by(arg, *args)

Finds the sole matching record. Raises ActiveRecord::RecordNotFound if no record is found. Raises ActiveRecord::SoleRecordExceeded if more than one record is found.

Product.find_sole_by(["price = %?", price])
πŸ“ Source code
# File activerecord/lib/active_record/relation/finder_methods.rb, line 160
    def find_sole_by(arg, *args)
      where(arg, *args).sole
    end
πŸ”Ž See on GitHub

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
πŸ“ Source code
# File activerecord/lib/active_record/relation/finder_methods.rb, line 173
    def first(limit = nil)
      if limit
        find_nth_with_limit(0, limit)
      else
        find_nth 0
      end
    end
πŸ”Ž See on GitHub

first!()

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

πŸ“ Source code
# File activerecord/lib/active_record/relation/finder_methods.rb, line 183
    def first!
      first || raise_record_not_found_exception!
    end
πŸ”Ž See on GitHub

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
πŸ“ Source code
# File activerecord/lib/active_record/relation/finder_methods.rb, line 287
    def forty_two
      find_nth 41
    end
πŸ”Ž See on GitHub

forty_two!()

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

πŸ“ Source code
# File activerecord/lib/active_record/relation/finder_methods.rb, line 293
    def forty_two!
      forty_two || raise_record_not_found_exception!
    end
πŸ”Ž See on GitHub

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
πŸ“ Source code
# File activerecord/lib/active_record/relation/finder_methods.rb, line 255
    def fourth
      find_nth 3
    end
πŸ”Ž See on GitHub

fourth!()

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

πŸ“ Source code
# File activerecord/lib/active_record/relation/finder_methods.rb, line 261
    def fourth!
      fourth || raise_record_not_found_exception!
    end
πŸ”Ž See on GitHub

include?(record)

Returns true if the relation contains the given record or false otherwise.

No query is performed if the relation is loaded; the given record is compared to the records in memory. If the relation is unloaded, an efficient existence query is performed, as in exists?.

Also aliased as: member?
πŸ“ Source code
# File activerecord/lib/active_record/relation/finder_methods.rb, line 389
    def include?(record)
      # The existing implementation relies on receiving an Active Record instance as the input parameter named record.
      # Any non-Active Record object passed to this implementation is guaranteed to return `false`.
      return false unless record.is_a?(model)

      if loaded? || offset_value || limit_value || having_clause.any?
        records.include?(record)
      else
        id = if record.class.composite_primary_key?
          record.class.primary_key.zip(record.id).to_h
        else
          record.id
        end

        exists?(id)
      end
    end
πŸ”Ž See on GitHub

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>]
πŸ“ Source code
# File activerecord/lib/active_record/relation/finder_methods.rb, line 202
    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
πŸ”Ž See on GitHub

last!()

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

πŸ“ Source code
# File activerecord/lib/active_record/relation/finder_methods.rb, line 213
    def last!
      last || raise_record_not_found_exception!
    end
πŸ”Ž See on GitHub

member?(record)

Alias for: include?

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
πŸ“ Source code
# File activerecord/lib/active_record/relation/finder_methods.rb, line 223
    def second
      find_nth 1
    end
πŸ”Ž See on GitHub

second!()

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

πŸ“ Source code
# File activerecord/lib/active_record/relation/finder_methods.rb, line 229
    def second!
      second || raise_record_not_found_exception!
    end
πŸ”Ž See on GitHub

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
πŸ“ Source code
# File activerecord/lib/active_record/relation/finder_methods.rb, line 319
    def second_to_last
      find_nth_from_last 2
    end
πŸ”Ž See on GitHub

second_to_last!()

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

πŸ“ Source code
# File activerecord/lib/active_record/relation/finder_methods.rb, line 325
    def second_to_last!
      second_to_last || raise_record_not_found_exception!
    end
πŸ”Ž See on GitHub

sole()

Finds the sole matching record. Raises ActiveRecord::RecordNotFound if no record is found. Raises ActiveRecord::SoleRecordExceeded if more than one record is found.

Product.where(["price = %?", price]).sole
πŸ“ Source code
# File activerecord/lib/active_record/relation/finder_methods.rb, line 143
    def sole
      found, undesired = first(2)

      if found.nil?
        raise_record_not_found_exception!
      elsif undesired.nil?
        found
      else
        raise ActiveRecord::SoleRecordExceeded.new(model)
      end
    end
πŸ”Ž See on GitHub

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
πŸ“ Source code
# File activerecord/lib/active_record/relation/finder_methods.rb, line 128
    def take(limit = nil)
      limit ? find_take_with_limit(limit) : find_take
    end
πŸ”Ž See on GitHub

take!()

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

πŸ“ Source code
# File activerecord/lib/active_record/relation/finder_methods.rb, line 134
    def take!
      take || raise_record_not_found_exception!
    end
πŸ”Ž See on GitHub

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
πŸ“ Source code
# File activerecord/lib/active_record/relation/finder_methods.rb, line 239
    def third
      find_nth 2
    end
πŸ”Ž See on GitHub

third!()

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

πŸ“ Source code
# File activerecord/lib/active_record/relation/finder_methods.rb, line 245
    def third!
      third || raise_record_not_found_exception!
    end
πŸ”Ž See on GitHub

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
πŸ“ Source code
# File activerecord/lib/active_record/relation/finder_methods.rb, line 303
    def third_to_last
      find_nth_from_last 3
    end
πŸ”Ž See on GitHub

third_to_last!()

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

πŸ“ Source code
# File activerecord/lib/active_record/relation/finder_methods.rb, line 309
    def third_to_last!
      third_to_last || raise_record_not_found_exception!
    end
πŸ”Ž See on GitHub