Class: ActiveRecord::Relation

### Home Classes Methods

### In Files

- lib/active_record/relation.rb

### Parent

Object

### Methods

- ::new
- #==
- #any?
- #build
- #create
- #create!
- #delete
- #delete_all
- #destroy
- #destroy_all
- #eager_loading?
- #empty?
- #initialize_copy
- #inspect
- #many?
- #method_missing
- #new
- #primary_key
- #reload
- #reset
- #respond_to?
- #scope_for_create
- #scoping
- #size
- #to_a
- #to_sql
- #update
- #update_all
- #where_values_hash

### Included Modules

- ActiveRecord::FinderMethods
- ActiveRecord::Calculations
- ActiveRecord::SpawnMethods
- ActiveRecord::QueryMethods

### Files

- README.rdoc

### Class/Module Index

Quicksearch

- ActiveRecord
- ActiveRecord::ActiveRecordError
- ActiveRecord::AdapterNotFound
- ActiveRecord::AdapterNotSpecified
- ActiveRecord::Aggregations
- ActiveRecord::Aggregations::ClassMethods
- ActiveRecord::AssociationPreload
- ActiveRecord::AssociationPreload::ClassMethods
- ActiveRecord::AssociationTypeMismatch
- ActiveRecord::Associations
- ActiveRecord::Associations::ClassMethods
- ActiveRecord::Associations::HasOneThroughAssociation
- ActiveRecord::Associations::ThroughAssociationScope
- ActiveRecord::AttributeAssignmentError
- ActiveRecord::AttributeMethods
- ActiveRecord::AttributeMethods::BeforeTypeCast
- ActiveRecord::AttributeMethods::ClassMethods
- ActiveRecord::AttributeMethods::Dirty
- ActiveRecord::AttributeMethods::PrimaryKey
- ActiveRecord::AttributeMethods::PrimaryKey::ClassMethods
- ActiveRecord::AttributeMethods::Query
- ActiveRecord::AttributeMethods::Read
- ActiveRecord::AttributeMethods::Read::ClassMethods
- ActiveRecord::AttributeMethods::TimeZoneConversion
- ActiveRecord::AttributeMethods::TimeZoneConversion::ClassMethods
- ActiveRecord::AttributeMethods::Write
- ActiveRecord::AttributeMethods::Write::ClassMethods
- ActiveRecord::AutosaveAssociation
- ActiveRecord::AutosaveAssociation::ClassMethods
- ActiveRecord::Base
- ActiveRecord::Calculations
- ActiveRecord::Callbacks
- ActiveRecord::Callbacks::ClassMethods
- ActiveRecord::ConfigurationError
- ActiveRecord::ConnectionAdapters
- ActiveRecord::ConnectionAdapters::AbstractAdapter
- ActiveRecord::ConnectionAdapters::Column
- ActiveRecord::ConnectionAdapters::Column::Format
- ActiveRecord::ConnectionAdapters::ConnectionHandler
- ActiveRecord::ConnectionAdapters::ConnectionManagement
- ActiveRecord::ConnectionAdapters::ConnectionPool
- ActiveRecord::ConnectionAdapters::DatabaseLimits
- ActiveRecord::ConnectionAdapters::DatabaseStatements
- ActiveRecord::ConnectionAdapters::MysqlAdapter
- ActiveRecord::ConnectionAdapters::PostgreSQLAdapter
- ActiveRecord::ConnectionAdapters::PostgreSQLColumn
- ActiveRecord::ConnectionAdapters::QueryCache
- ActiveRecord::ConnectionAdapters::Quoting
- ActiveRecord::ConnectionAdapters::SQLiteAdapter
- ActiveRecord::ConnectionAdapters::SQLiteAdapter::Version
- ActiveRecord::ConnectionAdapters::SchemaStatements
- ActiveRecord::ConnectionAdapters::Table
- ActiveRecord::ConnectionAdapters::TableDefinition
- ActiveRecord::ConnectionNotEstablished
- ActiveRecord::ConnectionTimeoutError
- ActiveRecord::CounterCache
- ActiveRecord::DangerousAttributeError
- ActiveRecord::DynamicFinderMatch
- ActiveRecord::DynamicScopeMatch
- ActiveRecord::FinderMethods
- ActiveRecord::Generators
- ActiveRecord::Generators::Migration
- ActiveRecord::Generators::MigrationGenerator
- ActiveRecord::Generators::ModelGenerator
- ActiveRecord::Generators::ObserverGenerator
- ActiveRecord::Generators::SessionMigrationGenerator
- ActiveRecord::InvalidForeignKey
- ActiveRecord::IrreversibleMigration
- ActiveRecord::Locking
- ActiveRecord::Locking::Optimistic
- ActiveRecord::Locking::Optimistic::ClassMethods
- ActiveRecord::Locking::Pessimistic
- ActiveRecord::LogSubscriber
- ActiveRecord::Migration
- ActiveRecord::MigrationProxy
- ActiveRecord::MultiparameterAssignmentErrors
- ActiveRecord::NamedScope
- ActiveRecord::NamedScope::ClassMethods
- ActiveRecord::NestedAttributes
- ActiveRecord::NestedAttributes::ClassMethods
- ActiveRecord::NestedAttributes::TooManyRecords
- ActiveRecord::Observer
- ActiveRecord::Persistence
- ActiveRecord::PredicateBuilder
- ActiveRecord::PreparedStatementInvalid
- ActiveRecord::QueryCache
- ActiveRecord::QueryCache::ClassMethods
- ActiveRecord::QueryMethods
- ActiveRecord::Railtie
- ActiveRecord::Railties
- ActiveRecord::Railties::ControllerRuntime
- ActiveRecord::Railties::ControllerRuntime::ClassMethods
- ActiveRecord::ReadOnlyRecord
- ActiveRecord::RecordInvalid
- ActiveRecord::RecordNotFound
- ActiveRecord::RecordNotSaved
- ActiveRecord::RecordNotUnique
- ActiveRecord::Reflection
- ActiveRecord::Reflection::ClassMethods
- ActiveRecord::Reflection::MacroReflection
- ActiveRecord::Relation
- ActiveRecord::Rollback
- ActiveRecord::Schema
- ActiveRecord::Serialization
- ActiveRecord::SerializationTypeMismatch
- ActiveRecord::SessionStore
- ActiveRecord::SessionStore::Session
- ActiveRecord::SessionStore::SqlBypass
- ActiveRecord::SpawnMethods
- ActiveRecord::StaleObjectError
- ActiveRecord::StatementInvalid
- ActiveRecord::TestFixtures
- ActiveRecord::TestFixtures::ClassMethods
- ActiveRecord::ThrowResult
- ActiveRecord::Timestamp
- ActiveRecord::Transactions
- ActiveRecord::Transactions::ClassMethods
- ActiveRecord::UnknownAttributeError
- ActiveRecord::Validations
- ActiveRecord::Validations::AssociatedValidator
- ActiveRecord::Validations::ClassMethods
- ActiveRecord::Validations::UniquenessValidator
- ActiveRecord::WrappedDatabaseException
- <
- Fixtures
- FixturesFileNotFound

No matching classes.

# ActiveRecord::Relation

# Active Record Relation

### Constants

ASSOCIATION_METHODS
JoinOperation
MULTI_VALUE_METHODS
SINGLE_VALUE_METHODS

### Attributes

extensions[RW]
klass[R]
loaded[R]
loaded?[R]
table[R]

### Public Class Methods

new(klass, table) click to toggle source

    # File lib/active_record/relation.rb, line 20
    def initialize(klass, table)
      @klass, @table = klass, table

      @implicit_readonly = nil
      @loaded            = false

      SINGLE_VALUE_METHODS.each {|v| instance_variable_set(:"@#{v}_value", nil)}
      (ASSOCIATION_METHODS + MULTI_VALUE_METHODS).each {|v| instance_variable_set(:"@#{v}_values", [])}
      @extensions = []
    end

### Public Instance Methods

==(other) click to toggle source

    # File lib/active_record/relation.rb, line 346
    def ==(other)
      case other
      when Relation
        other.to_sql == to_sql
      when Array
        to_a == other.to_a
      end
    end

any?() click to toggle source

    # File lib/active_record/relation.rb, line 93
    def any?
      if block_given?
        to_a.any? { |*block_args| yield(*block_args) }
      else
        !empty?
      end
    end

build(*args, &block) click to toggle source
Alias for: new
create(*args, &block) click to toggle source

    # File lib/active_record/relation.rb, line 41
    def create(*args, &block)
      scoping { @klass.create(*args, &block) }
    end

create!(*args, &block) click to toggle source

    # File lib/active_record/relation.rb, line 45
    def create!(*args, &block)
      scoping { @klass.create!(*args, &block) }
    end

delete(id_or_array) click to toggle source

Deletes the row with a primary key matching the `id` argument, using a SQL `DELETE` statement, and returns the number of rows deleted. Active Record objects are not instantiated, so the object’s callbacks are not executed, including any `:dependent` association options or Observer methods.

You can delete multiple rows at once by passing an Array of `id`s.

Note: Although it is often much faster than the alternative, `#destroy`, skipping callbacks might bypass business logic in your application that ensures referential integrity or performs other essential jobs.

#### Examples

    # Delete a single row
    Todo.delete(1)

    # Delete multiple rows
    Todo.delete([2,3,4])

    # File lib/active_record/relation.rb, line 296
    def delete(id_or_array)
      where(@klass.primary_key => id_or_array).delete_all
    end

delete_all(conditions = nil) click to toggle source

Deletes the records matching `conditions` without instantiating the records first, and hence not calling the `destroy` method nor invoking callbacks. This is a single SQL DELETE statement that goes straight to the database, much more efficient than `destroy_all`. Be careful with relations though, in particular `:dependent` rules defined on associations are not honored. Returns the number of rows affected.

#### Parameters

- `conditions` - Conditions are specified the same way as with `find` method.

#### Example

    Post.delete_all("person_id = 5 AND (category = 'Something' OR category = 'Else')")
    Post.delete_all(["person_id = ? AND (category = ? OR category = ?)", 5, 'Something', 'Else'])

Both calls delete the affected posts all at once with a single DELETE statement. If you need to destroy dependent associations or call your `before_*` or `after_destroy` callbacks, use the `destroy_all` method instead.

    # File lib/active_record/relation.rb, line 272
    def delete_all(conditions = nil)
      conditions ? where(conditions).delete_all : arel.delete.tap { reset }
    end

destroy(id) click to toggle source

Destroy an object (or multiple objects) that has the given id, the object is instantiated first, therefore all callbacks and filters are fired off before the object is deleted. This method is less efficient than ActiveRecord#delete but allows cleanup methods and other actions to be run.

This essentially finds the object (or multiple objects) with the given id, creates a new object from the attributes, and then calls destroy on it.

#### Parameters

- `id` - Can be either an Integer or an Array of Integers.

#### Examples

    # Destroy a single object
    Todo.destroy(1)

    # Destroy multiple objects
    todos = [1,2,3]
    Todo.destroy(todos)

    # File lib/active_record/relation.rb, line 246
    def destroy(id)
      if id.is_a?(Array)
        id.map { |one_id| destroy(one_id) }
      else
        find(id).destroy
      end
    end

destroy_all(conditions = nil) click to toggle source

Destroys the records matching `conditions` by instantiating each record and calling its `destroy` method. Each object’s callbacks are executed (including `:dependent` association options and `before_destroy`/`after_destroy` Observer methods). Returns the collection of objects that were destroyed; each will be frozen, to reflect that no changes should be made (since they can’t be persisted).

Note: Instantiation, callback execution, and deletion of each record can be time consuming when you’re removing many records at once. It generates at least one SQL `DELETE` query per record (or possibly more, to enforce your callbacks). If you want to delete many rows quickly, without concern for their associations or callbacks, use `delete_all` instead.

#### Parameters

- `conditions` - A string, array, or hash that specifies which records to destroy. If omitted, all records are destroyed. See the Conditions section in the introduction to ActiveRecord::Base for more information.

#### Examples

    Person.destroy_all("last_login < '2004-04-04'")
    Person.destroy_all(:status => "inactive")

    # File lib/active_record/relation.rb, line 219
    def destroy_all(conditions = nil)
      if conditions
        where(conditions).destroy_all
      else
        to_a.each {|object| object.destroy }.tap { reset }
      end
    end

eager_loading?() click to toggle source

    # File lib/active_record/relation.rb, line 342
    def eager_loading?
      @should_eager_load ||= (@eager_load_values.any? || (@includes_values.any? && references_eager_loaded_tables?))
    end

empty?() click to toggle source

Returns true if there are no records.

    # File lib/active_record/relation.rb, line 89
    def empty?
      loaded? ? @records.empty? : count.zero?
    end

initialize_copy(other) click to toggle source

    # File lib/active_record/relation.rb, line 35
    def initialize_copy(other)
      reset
    end

inspect() click to toggle source

    # File lib/active_record/relation.rb, line 355
    def inspect
      to_a.inspect
    end

many?() click to toggle source

    # File lib/active_record/relation.rb, line 101
    def many?
      if block_given?
        to_a.many? { |*block_args| yield(*block_args) }
      else
        @limit_value ? to_a.many? : size > 1
      end
    end

new(*args, &block) click to toggle source

    # File lib/active_record/relation.rb, line 31
    def new(*args, &block)
      scoping { @klass.new(*args, &block) }
    end

Also aliased as: build
primary_key() click to toggle source

    # File lib/active_record/relation.rb, line 313
    def primary_key
      @primary_key ||= table[@klass.primary_key]
    end

reload() click to toggle source

    # File lib/active_record/relation.rb, line 300
    def reload
      reset
      to_a # force reload
      self
    end

reset() click to toggle source

    # File lib/active_record/relation.rb, line 306
    def reset
      @first = @last = @to_sql = @order_clause = @scope_for_create = @arel = @loaded = nil
      @should_eager_load = @join_dependency = nil
      @records = []
      self
    end

respond_to?(method, include_private = false) click to toggle source

    # File lib/active_record/relation.rb, line 49
    def respond_to?(method, include_private = false)
      return true if arel.respond_to?(method, include_private) || Array.method_defined?(method) || @klass.respond_to?(method, include_private)

      if match = DynamicFinderMatch.match(method)
        return true if @klass.send(:all_attributes_exists?, match.attribute_names)
      elsif match = DynamicScopeMatch.match(method)
        return true if @klass.send(:all_attributes_exists?, match.attribute_names)
      else
        super
      end
    end

scope_for_create() click to toggle source

    # File lib/active_record/relation.rb, line 332
    def scope_for_create
      @scope_for_create ||= begin
        if @create_with_value
          @create_with_value.reverse_merge(where_values_hash)
        else
          where_values_hash
        end
      end
    end

scoping() click to toggle source

Scope all queries to the current scope.

#### Example

    Comment.where(:post_id => 1).scoping do
      Comment.first # SELECT * FROM comments WHERE post_id = 1
    end

Please check unscoped if you want to remove all previous scopes (including the default_scope) during the execution of a block.

    # File lib/active_record/relation.rb, line 119
    def scoping
      @klass.scoped_methods << self
      begin
        yield
      ensure
        @klass.scoped_methods.pop
      end
    end

size() click to toggle source

Returns size of the records.

    # File lib/active_record/relation.rb, line 84
    def size
      loaded? ? @records.length : count
    end

to_a() click to toggle source

    # File lib/active_record/relation.rb, line 61
    def to_a
      return @records if loaded?

      @records = eager_loading? ? find_with_associations : @klass.find_by_sql(arel.to_sql)

      preload = @preload_values
      preload +=  @includes_values unless eager_loading?
      preload.each {|associations| @klass.send(:preload_associations, @records, associations) }

      # @readonly_value is true only if set explicitly. @implicit_readonly is true if there
      # are JOINS and no explicit SELECT.
      readonly = @readonly_value.nil? ? @implicit_readonly : @readonly_value
      @records.each { |record| record.readonly! } if readonly

      @loaded = true
      @records
    end

to_sql() click to toggle source

    # File lib/active_record/relation.rb, line 317
    def to_sql
      @to_sql ||= arel.to_sql
    end

update(id, attributes) click to toggle source

Updates an object (or multiple objects) and saves it to the database, if validations pass. The resulting object is returned whether the object was saved successfully to the database or not.

#### Parameters

- `id` - This should be the id or an array of ids to be updated.

- `attributes` - This should be a hash of attributes or an array of hashes.

#### Examples

    # Updates one record
    Person.update(15, :user_name => 'Samuel', :group => 'expert')

    # Updates multiple records
    people = { 1 => { "first_name" => "David" }, 2 => { "first_name" => "Jeremy" } }
    Person.update(people.keys, people.values)

    # File lib/active_record/relation.rb, line 182
    def update(id, attributes)
      if id.is_a?(Array)
        idx = -1
        id.collect { |one_id| idx += 1; update(one_id, attributes[idx]) }
      else
        object = find(id)
        object.update_attributes(attributes)
        object
      end
    end

update_all(updates, conditions = nil, options = {}) click to toggle source

Updates all records with details given if they match a set of conditions supplied, limits and order can also be supplied. This method constructs a single SQL UPDATE statement and sends it straight to the database. It does not instantiate the involved models and it does not trigger Active Record callbacks or validations.

#### Parameters

- `updates` - A string, array, or hash representing the SET part of an SQL statement.

- `conditions` - A string, array, or hash representing the WHERE part of an SQL statement. See conditions in the intro.

- `options` - Additional options are `:limit` and `:order`, see the examples for usage.

#### Examples

    # Update all customers with the given attributes
    Customer.update_all :wants_email => true

    # Update all books with 'Rails' in their title
    Book.update_all "author = 'David'", "title LIKE '%Rails%'"

    # Update all avatars migrated more than a week ago
    Avatar.update_all ['migrated_at = ?', Time.now.utc], ['migrated_at > ?', 1.week.ago]

    # Update all books that match conditions, but limit it to 5 ordered by date
    Book.update_all "author = 'David'", "title LIKE '%Rails%'", :order => 'created_at', :limit => 5

    # File lib/active_record/relation.rb, line 153
    def update_all(updates, conditions = nil, options = {})
      if conditions || options.present?
        where(conditions).apply_finder_options(options.slice(:limit, :order)).update_all(updates)
      else
        # Apply limit and order only if they're both present
        if @limit_value.present? == @order_values.present?
          arel.update(Arel::SqlLiteral.new(@klass.send(:sanitize_sql_for_assignment, updates)))
        else
          except(:limit, :order).update_all(updates)
        end
      end
    end

where_values_hash() click to toggle source

    # File lib/active_record/relation.rb, line 321
    def where_values_hash
      Hash[@where_values.find_all { |w|
        w.respond_to?(:operator) && w.operator == :== && w.left.relation.name == table_name
      }.map { |where|
        [
          where.left.name,
          where.right.respond_to?(:value) ? where.right.value : where.right
        ]
      }]
    end

### Protected Instance Methods

method_missing(method, *args, &block) click to toggle source

    # File lib/active_record/relation.rb, line 361
    def method_missing(method, *args, &block)
      if Array.method_defined?(method)
        to_a.send(method, *args, &block)
      elsif @klass.scopes[method]
        merge(@klass.send(method, *args, &block))
      elsif @klass.respond_to?(method)
        scoping { @klass.send(method, *args, &block) }
      elsif arel.respond_to?(method)
        arel.send(method, *args, &block)
      else
        super
      end
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.