Module: ActiveRecord::FinderMethods

### Home Classes Methods

### In Files

- lib/active_record/relation/finder_methods.rb

### Methods

- #all
- #apply_join_dependency
- #construct_join_dependency_for_association_find
- #construct_limited_ids_condition
- #construct_relation_for_association_calculations
- #construct_relation_for_association_find
- #exists?
- #find
- #find_by_attributes
- #find_first
- #find_last
- #find_one
- #find_or_instantiator_by_attributes
- #find_some
- #find_with_associations
- #find_with_ids
- #first
- #first!
- #last
- #last!
- #using_limitable_reflections?

### Files

- README.rdoc

### Class/Module Index

Quicksearch

- ActiveRecord
- ActiveRecord::ActiveRecordError
- ActiveRecord::AdapterNotFound
- ActiveRecord::AdapterNotSpecified
- ActiveRecord::Aggregations
- ActiveRecord::Aggregations::ClassMethods
- ActiveRecord::AssociationTypeMismatch
- ActiveRecord::Associations
- ActiveRecord::Associations::ClassMethods
- ActiveRecord::AttributeAssignment
- ActiveRecord::AttributeAssignment::ClassMethods
- ActiveRecord::AttributeAssignmentError
- ActiveRecord::AttributeMethods
- ActiveRecord::AttributeMethods::BeforeTypeCast
- ActiveRecord::AttributeMethods::ClassMethods
- ActiveRecord::AttributeMethods::DeprecatedUnderscoreRead
- ActiveRecord::AttributeMethods::DeprecatedUnderscoreRead::ClassMethods
- ActiveRecord::AttributeMethods::Dirty
- ActiveRecord::AttributeMethods::PrimaryKey
- ActiveRecord::AttributeMethods::PrimaryKey::ClassMethods
- ActiveRecord::AttributeMethods::Query
- ActiveRecord::AttributeMethods::Read
- ActiveRecord::AttributeMethods::Read::ClassMethods
- ActiveRecord::AttributeMethods::Serialization
- ActiveRecord::AttributeMethods::Serialization::Attribute
- ActiveRecord::AttributeMethods::Serialization::ClassMethods
- ActiveRecord::AttributeMethods::TimeZoneConversion
- ActiveRecord::AttributeMethods::TimeZoneConversion::ClassMethods
- ActiveRecord::AttributeMethods::Write
- ActiveRecord::AttributeMethods::Write::ClassMethods
- ActiveRecord::AutosaveAssociation
- ActiveRecord::AutosaveAssociation::ClassMethods
- ActiveRecord::Base
- ActiveRecord::Batches
- ActiveRecord::Calculations
- ActiveRecord::Callbacks
- ActiveRecord::Coders
- ActiveRecord::ConfigurationError
- ActiveRecord::ConnectionAdapters
- ActiveRecord::ConnectionAdapters::AbstractAdapter
- ActiveRecord::ConnectionAdapters::AbstractMysqlAdapter
- ActiveRecord::ConnectionAdapters::ConnectionHandler
- ActiveRecord::ConnectionAdapters::ConnectionManagement
- ActiveRecord::ConnectionAdapters::ConnectionPool
- ActiveRecord::ConnectionAdapters::DatabaseLimits
- ActiveRecord::ConnectionAdapters::DatabaseStatements
- ActiveRecord::ConnectionAdapters::Mysql2Adapter
- ActiveRecord::ConnectionAdapters::MysqlAdapter
- ActiveRecord::ConnectionAdapters::MysqlAdapter::StatementPool
- ActiveRecord::ConnectionAdapters::PostgreSQLAdapter
- ActiveRecord::ConnectionAdapters::PostgreSQLAdapter::StatementPool
- ActiveRecord::ConnectionAdapters::PostgreSQLAdapter::TableDefinition
- ActiveRecord::ConnectionAdapters::PostgreSQLAdapter::Utils
- ActiveRecord::ConnectionAdapters::PostgreSQLColumn
- ActiveRecord::ConnectionAdapters::QueryCache
- ActiveRecord::ConnectionAdapters::Quoting
- ActiveRecord::ConnectionAdapters::SQLiteAdapter
- ActiveRecord::ConnectionAdapters::SQLiteAdapter::ExplainPrettyPrinter
- ActiveRecord::ConnectionAdapters::SQLiteAdapter::StatementPool
- ActiveRecord::ConnectionAdapters::SQLiteAdapter::Version
- ActiveRecord::ConnectionAdapters::SchemaCache
- ActiveRecord::ConnectionAdapters::SchemaStatements
- ActiveRecord::ConnectionAdapters::StatementPool
- ActiveRecord::ConnectionAdapters::Table
- ActiveRecord::ConnectionAdapters::TableDefinition
- ActiveRecord::ConnectionNotEstablished
- ActiveRecord::ConnectionTimeoutError
- ActiveRecord::CounterCache
- ActiveRecord::DangerousAttributeError
- ActiveRecord::Delegation
- ActiveRecord::DynamicFinderMatch
- ActiveRecord::DynamicMatchers
- ActiveRecord::DynamicScopeMatch
- ActiveRecord::Explain
- ActiveRecord::FinderMethods
- ActiveRecord::Fixtures
- ActiveRecord::Fixtures::File
- ActiveRecord::Generators
- ActiveRecord::Generators::Migration
- ActiveRecord::Generators::MigrationGenerator
- ActiveRecord::Generators::ModelGenerator
- ActiveRecord::Generators::ObserverGenerator
- ActiveRecord::Generators::SessionMigrationGenerator
- ActiveRecord::IdentityMap
- ActiveRecord::IdentityMap::Middleware
- ActiveRecord::Inheritance
- ActiveRecord::Inheritance::ClassMethods
- ActiveRecord::Integration
- ActiveRecord::InvalidForeignKey
- ActiveRecord::IrreversibleMigration
- ActiveRecord::Locking
- ActiveRecord::Locking::Optimistic
- ActiveRecord::Locking::Optimistic::ClassMethods
- ActiveRecord::Locking::Pessimistic
- ActiveRecord::LogSubscriber
- ActiveRecord::Migration
- ActiveRecord::Migration::CommandRecorder
- ActiveRecord::MigrationProxy
- ActiveRecord::ModelSchema
- ActiveRecord::ModelSchema::ClassMethods
- ActiveRecord::MultiparameterAssignmentErrors
- ActiveRecord::NestedAttributes
- ActiveRecord::NestedAttributes::ClassMethods
- ActiveRecord::NestedAttributes::TooManyRecords
- ActiveRecord::Observer
- ActiveRecord::Persistence
- ActiveRecord::Persistence::ClassMethods
- ActiveRecord::PreparedStatementInvalid
- ActiveRecord::QueryCache
- ActiveRecord::QueryCache::ClassMethods
- ActiveRecord::QueryMethods
- ActiveRecord::Querying
- ActiveRecord::Railtie
- ActiveRecord::Railties
- ActiveRecord::Railties::ControllerRuntime
- ActiveRecord::Railties::ControllerRuntime::ClassMethods
- ActiveRecord::ReadOnlyRecord
- ActiveRecord::ReadonlyAttributes
- ActiveRecord::ReadonlyAttributes::ClassMethods
- ActiveRecord::RecordInvalid
- ActiveRecord::RecordNotFound
- ActiveRecord::RecordNotSaved
- ActiveRecord::RecordNotUnique
- ActiveRecord::Reflection
- ActiveRecord::Reflection::ClassMethods
- ActiveRecord::Reflection::MacroReflection
- ActiveRecord::Result
- ActiveRecord::Rollback
- ActiveRecord::Sanitization
- ActiveRecord::Sanitization::ClassMethods
- ActiveRecord::Schema
- ActiveRecord::Scoping
- ActiveRecord::Scoping::ClassMethods
- ActiveRecord::Scoping::Default
- ActiveRecord::Scoping::Default::ClassMethods
- ActiveRecord::Scoping::Named
- ActiveRecord::Scoping::Named::ClassMethods
- ActiveRecord::Serialization
- ActiveRecord::SerializationTypeMismatch
- ActiveRecord::SessionStore
- ActiveRecord::SessionStore::Session
- ActiveRecord::SessionStore::SqlBypass
- ActiveRecord::SpawnMethods
- ActiveRecord::StaleObjectError
- ActiveRecord::StatementInvalid
- ActiveRecord::Store
- ActiveRecord::Store::ClassMethods
- ActiveRecord::TestFixtures
- ActiveRecord::TestFixtures::ClassMethods
- ActiveRecord::ThrowResult
- ActiveRecord::Timestamp
- ActiveRecord::Transactions
- ActiveRecord::Transactions::ClassMethods
- ActiveRecord::Translation
- ActiveRecord::UnknownAttributeError
- ActiveRecord::UnknownPrimaryKey
- ActiveRecord::Validations
- ActiveRecord::Validations::AssociatedValidator
- ActiveRecord::Validations::ClassMethods
- ActiveRecord::Validations::UniquenessValidator
- ActiveRecord::WrappedDatabaseException
- Mysql
- Mysql::Result
- Mysql::Stmt
- Mysql::Time
- ArJdbcMySQL
- ArJdbcMySQL::Error

No matching classes.

# ActiveRecord::FinderMethods

### Public Instance Methods

all(*args) click to toggle source

A convenience wrapper for `find(:all, *args)`. You can pass in all the same arguments to this method as you can to `find(:all)`.

    # File lib/active_record/relation/finder_methods.rb, line 158
    def all(*args)
      args.any? ? apply_finder_options(args.first).to_a : to_a
    end

exists?(id = false) click to toggle source

Returns true if a record exists in the table that matches the `id` or conditions given, or false otherwise. The argument can take five 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 `['color = ?', 'red']`).

- Hash - Finds the record that matches these `find`-style conditions (such as `{:color => 'red'}`).

- No args - Returns false if the table 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\''`.

#### Examples

    Person.exists?(5)
    Person.exists?('5')
    Person.exists?(:name => "David")
    Person.exists?(['name LIKE ?', "%#{query}%"])
    Person.exists?

    # File lib/active_record/relation/finder_methods.rb, line 187
    def exists?(id = false)
      id = id.id if ActiveRecord::Base === id
      return false if id.nil?

      join_dependency = construct_join_dependency_for_association_find
      relation = construct_relation_for_association_find(join_dependency)
      relation = relation.except(:select, :order).select("1 AS one").limit(1)

      case id
      when Array, Hash
        relation = relation.where(id)
      else
        relation = relation.where(table[primary_key].eq(id)) if id
      end

      connection.select_value(relation, "#{name} Exists") ? true : false
    rescue ThrowResult
      false
    end

find(*args) click to toggle source

Find operates with four different retrieval approaches:

- 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 no record can be found for all of the listed ids, then RecordNotFound will be raised.

- Find first - This will return the first record matched by the options used. These options can either be specific conditions or merely an order. If no record can be matched, `nil` is returned. Use `Model.find(:first, *args)` or its shortcut `Model.first(*args)`.

- Find last - This will return the last record matched by the options used. These options can either be specific conditions or merely an order. If no record can be matched, `nil` is returned. Use `Model.find(:last, *args)` or its shortcut `Model.last(*args)`.

- Find all - This will return all the records matched by the options used. If no records are found, an empty array is returned. Use `Model.find(:all, *args)` or its shortcut `Model.all(*args)`.

All approaches accept an options hash as their last parameter.

#### Options

- `:conditions` - An SQL fragment like "administrator = 1", `["user_name = ?", username]`, or `["user_name = :user_name", { :user_name => user_name }]`. See conditions in the intro.

- `:order` - An SQL fragment like "created_at DESC, name".

- `:group` - An attribute name by which the result should be grouped. Uses the `GROUP BY` SQL-clause.

- `:having` - Combined with `:group` this can be used to filter the records that a `GROUP BY` returns. Uses the `HAVING` SQL-clause.

- `:limit` - An integer determining the limit on the number of rows that should be returned.

- `:offset` - An integer determining the offset from where the rows should be fetched. So at 5, it would skip rows 0 through 4.

- `:joins` - Either an SQL fragment for additional joins like "LEFT JOIN comments ON comments.post_id = id" (rarely needed), named associations in the same form used for the `:include` option, which will perform an `INNER JOIN` on the associated table(s), or an array containing a mixture of both strings and named associations. If the value is a string, then the records will be returned read-only since they will have attributes that do not correspond to the table's columns. Pass `:readonly => false` to override.

- `:include` - Names associations that should be loaded alongside. The symbols named refer to already defined associations. See eager loading under Associations.

- `:select` - By default, this is "*" as in "SELECT * FROM", but can be changed if you, for example, want to do a join but not include the joined columns. Takes a string with the SELECT SQL fragment (e.g. "id, name").

- `:from` - By default, this is the table name of the class, but can be changed to an alternate table name (or even the name of a database view).

- `:readonly` - Mark the returned records read-only so they cannot be saved or updated.

- `:lock` - An SQL fragment like "FOR UPDATE" or "LOCK IN SHARE MODE". `:lock => true` gives connection's default exclusive lock, usually "FOR UPDATE".

#### Examples

    # find by id
    Person.find(1)       # returns the object for ID = 1
    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 that returned records may not be in the same order as the ids you provide since database rows are unordered. Give an explicit `:order` to ensure the results are sorted.

#### Examples

    # find first
    Person.first # returns the first object fetched by SELECT * FROM people
    Person.where(["user_name = ?", user_name]).first
    Person.where(["user_name = :u", { :u => user_name }]).first
    Person.order("created_on DESC").offset(5).first

    # find last
    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

    # find all
    Person.all # returns an array of objects for all the rows fetched by SELECT * FROM people
    Person.where(["category IN (?)", categories]).limit(50).all
    Person.where({ :friends => ["Bob", "Steve", "Fred"] }).all
    Person.offset(10).limit(10).all
    Person.includes([:account, :friends]).all
    Person.group("category").all

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

    # File lib/active_record/relation/finder_methods.rb, line 95
    def find(*args)
      return to_a.find { |*block_args| yield(*block_args) } if block_given?

      options = args.extract_options!

      if options.present?
        apply_finder_options(options).find(*args)
      else
        case args.first
        when :first, :last, :all
          send(args.first)
        else
          find_with_ids(*args)
        end
      end
    end

first(*args) click to toggle source

A convenience wrapper for `find(:first, *args)`. You can pass in all the same arguments to this method as you can to `find(:first)`.

    # File lib/active_record/relation/finder_methods.rb, line 114
    def first(*args)
      if args.any?
        if args.first.kind_of?(Integer) || (loaded? && !args.first.kind_of?(Hash))
          limit(*args).to_a
        else
          apply_finder_options(args.first).first
        end
      else
        find_first
      end
    end

first!() click to toggle source

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

    # File lib/active_record/relation/finder_methods.rb, line 128
    def first!
      first or raise RecordNotFound
    end

last(*args) click to toggle source

A convenience wrapper for `find(:last, *args)`. You can pass in all the same arguments to this method as you can to `find(:last)`.

    # File lib/active_record/relation/finder_methods.rb, line 134
    def last(*args)
      if args.any?
        if args.first.kind_of?(Integer) || (loaded? && !args.first.kind_of?(Hash))
          if order_values.empty? && primary_key
            order("#{quoted_table_name}.#{quoted_primary_key} DESC").limit(*args).reverse
          else
            to_a.last(*args)
          end
        else
          apply_finder_options(args.first).last
        end
      else
        find_last
      end
    end

last!() click to toggle source

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

    # File lib/active_record/relation/finder_methods.rb, line 152
    def last!
      last or raise RecordNotFound
    end

### Protected Instance Methods

apply_join_dependency(relation, join_dependency) click to toggle source

    # File lib/active_record/relation/finder_methods.rb, line 235
    def apply_join_dependency(relation, join_dependency)
      join_dependency.join_associations.each do |association|
        relation = association.join_relation(relation)
      end

      limitable_reflections = using_limitable_reflections?(join_dependency.reflections)

      if !limitable_reflections && relation.limit_value
        limited_id_condition = construct_limited_ids_condition(relation.except(:select))
        relation = relation.where(limited_id_condition)
      end

      relation = relation.except(:limit, :offset) unless limitable_reflections

      relation
    end

construct_join_dependency_for_association_find() click to toggle source

    # File lib/active_record/relation/finder_methods.rb, line 218
    def construct_join_dependency_for_association_find
      including = (@eager_load_values + @includes_values).uniq
      ActiveRecord::Associations::JoinDependency.new(@klass, including, [])
    end

construct_limited_ids_condition(relation) click to toggle source

    # File lib/active_record/relation/finder_methods.rb, line 252
    def construct_limited_ids_condition(relation)
      orders = relation.order_values.map { |val| val.presence }.compact
      values = @klass.connection.distinct("#{@klass.connection.quote_table_name table_name}.#{primary_key}", orders)

      relation = relation.dup.select(values)
      relation.uniq_value = nil

      id_rows = @klass.connection.select_all(relation.arel, 'SQL', relation.bind_values)
      ids_array = id_rows.map {|row| row[primary_key]}

      ids_array.empty? ? raise(ThrowResult) : table[primary_key].in(ids_array)
    end

construct_relation_for_association_calculations() click to toggle source

    # File lib/active_record/relation/finder_methods.rb, line 223
    def construct_relation_for_association_calculations
      including = (@eager_load_values + @includes_values).uniq
      join_dependency = ActiveRecord::Associations::JoinDependency.new(@klass, including, arel.froms.first)
      relation = except(:includes, :eager_load, :preload)
      apply_join_dependency(relation, join_dependency)
    end

construct_relation_for_association_find(join_dependency) click to toggle source

    # File lib/active_record/relation/finder_methods.rb, line 230
    def construct_relation_for_association_find(join_dependency)
      relation = except(:includes, :eager_load, :preload, :select).select(join_dependency.columns)
      apply_join_dependency(relation, join_dependency)
    end

find_by_attributes(match, attributes, *args) click to toggle source

    # File lib/active_record/relation/finder_methods.rb, line 265
    def find_by_attributes(match, attributes, *args)
      conditions = Hash[attributes.map {|a| [a, args[attributes.index(a)]]}]
      result = where(conditions).send(match.finder)

      if match.bang? && result.nil?
        raise RecordNotFound, "Couldn't find #{@klass.name} with #{conditions.to_a.collect {|p| p.join(' = ')}.join(', ')}"
      else
        yield(result) if block_given?
        result
      end
    end

find_first() click to toggle source

    # File lib/active_record/relation/finder_methods.rb, line 377
    def find_first
      if loaded?
        @records.first
      else
        @first ||= limit(1).to_a[0]
      end
    end

find_last() click to toggle source

    # File lib/active_record/relation/finder_methods.rb, line 385
    def find_last
      if loaded?
        @records.last
      else
        @last ||=
          if offset_value || limit_value
            to_a.last
          else
            reverse_order.limit(1).to_a[0]
          end
      end
    end

find_one(id) click to toggle source

    # File lib/active_record/relation/finder_methods.rb, line 322
    def find_one(id)
      id = id.id if ActiveRecord::Base === id

      if IdentityMap.enabled? && where_values.blank? &&
        limit_value.blank? && order_values.blank? &&
        includes_values.blank? && preload_values.blank? &&
        readonly_value.nil? && joins_values.blank? &&
        !@klass.locking_enabled? &&
        record = IdentityMap.get(@klass, id)
        return record
      end

      column = columns_hash[primary_key]

      substitute = connection.substitute_at(column, @bind_values.length)
      relation = where(table[primary_key].eq(substitute))
      relation.bind_values = [[column, id]]
      record = relation.first

      unless record
        conditions = arel.where_sql
        conditions = " [#{conditions}]" if conditions
        raise RecordNotFound, "Couldn't find #{@klass.name} with #{primary_key}=#{id}#{conditions}"
      end

      record
    end

find_or_instantiator_by_attributes(match, attributes, *args) click to toggle source

    # File lib/active_record/relation/finder_methods.rb, line 277
    def find_or_instantiator_by_attributes(match, attributes, *args)
      options = args.size > 1 && args.last(2).all?{ |a| a.is_a?(Hash) } ? args.extract_options! : {}
      protected_attributes_for_create, unprotected_attributes_for_create = {}, {}
      args.each_with_index do |arg, i|
        if arg.is_a?(Hash)
          protected_attributes_for_create = args[i].with_indifferent_access
        else
          unprotected_attributes_for_create[attributes[i]] = args[i]
        end
      end

      conditions = (protected_attributes_for_create.merge(unprotected_attributes_for_create)).slice(*attributes).symbolize_keys

      record = where(conditions).first

      unless record
        record = @klass.new(protected_attributes_for_create, options) do |r|
          r.assign_attributes(unprotected_attributes_for_create, :without_protection => true)
        end
        yield(record) if block_given?
        record.send(match.save_method) if match.save_record?
      end

      record
    end

find_some(ids) click to toggle source

    # File lib/active_record/relation/finder_methods.rb, line 350
    def find_some(ids)
      result = where(table[primary_key].in(ids)).all

      expected_size =
        if @limit_value && ids.size > @limit_value
          @limit_value
        else
          ids.size
        end

      # 11 ids with limit 3, offset 9 should give 2 results.
      if @offset_value && (ids.size - @offset_value < expected_size)
        expected_size = ids.size - @offset_value
      end

      if result.size == expected_size
        result
      else
        conditions = arel.where_sql
        conditions = " [#{conditions}]" if conditions

        error = "Couldn't find all #{@klass.name.pluralize} with IDs "
        error << "(#{ids.join(", ")})#{conditions} (found #{result.size} results, but was looking for #{expected_size})"
        raise RecordNotFound, error
      end
    end

find_with_associations() click to toggle source

    # File lib/active_record/relation/finder_methods.rb, line 209
    def find_with_associations
      join_dependency = construct_join_dependency_for_association_find
      relation = construct_relation_for_association_find(join_dependency)
      rows = connection.select_all(relation, 'SQL', relation.bind_values.dup)
      join_dependency.instantiate(rows)
    rescue ThrowResult
      []
    end

find_with_ids(*ids) click to toggle source

    # File lib/active_record/relation/finder_methods.rb, line 303
    def find_with_ids(*ids)
      return to_a.find { |*block_args| yield(*block_args) } if block_given?

      expects_array = ids.first.kind_of?(Array)
      return ids.first if expects_array && ids.first.empty?

      ids = ids.flatten.compact.uniq

      case ids.size
      when 0
        raise RecordNotFound, "Couldn't find #{@klass.name} without an ID"
      when 1
        result = find_one(ids.first)
        expects_array ? [ result ] : result
      else
        find_some(ids)
      end
    end

using_limitable_reflections?(reflections) click to toggle source

    # File lib/active_record/relation/finder_methods.rb, line 398
    def using_limitable_reflections?(reflections)
      reflections.none? { |r| r.collection? }
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.