Active Record Relation

JoinOperation	=	Struct.new(:relation, :join_class, :on)
ASSOCIATION_METHODS	=	[:includes, :eager_load, :preload]
MULTI_VALUE_METHODS	=	[:select, :group, :order, :joins, :where, :having, :bind]
SINGLE_VALUE_METHODS	=	[:limit, :offset, :lock, :readonly, :from, :reorder, :reverse_order]

Attributes

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

Class Public methods

new(klass, table)

Source: show | on GitHub

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

  @implicit_readonly = nil
  @loaded            = false
  @default_scoped    = 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 = []
  @create_with_value = {}
end

Instance Public methods

==(other)

Source: show | on GitHub

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

any?()

Source: show | on GitHub

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

build(*args, &block)

create(*args, &block)

Source: show | on GitHub

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

create!(*args, &block)

Source: show | on GitHub

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

delete(id_or_array)

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 ids.

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])

Source: show | on GitHub

# File activerecord/lib/active_record/relation.rb, line 378
def delete(id_or_array)
  IdentityMap.remove_by_id(self.symbolized_base_class, id_or_array) if IdentityMap.enabled?
  where(primary_key => id_or_array).delete_all
end

delete_all(conditions = nil)

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'])
Post.where(:person_id => 5).where(:category => ['Something', 'Else']).delete_all

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.

Source: show | on GitHub

# File activerecord/lib/active_record/relation.rb, line 345
def delete_all(conditions = nil)
  IdentityMap.repository[symbolized_base_class] = {} if IdentityMap.enabled?
  if conditions
    where(conditions).delete_all
  else
    statement = arel.compile_delete
    affected = @klass.connection.delete(statement, 'SQL', bind_values)

    reset
    affected
  end
end

destroy(id)

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)

Source: show | on GitHub

# File activerecord/lib/active_record/relation.rb, line 318
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)

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")
Person.where(:age => 0..18).destroy_all

Source: show | on GitHub

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

eager_loading?()

Source: show | on GitHub

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

empty?()

Returns true if there are no records.

Source: show | on GitHub

# File activerecord/lib/active_record/relation.rb, line 146
def empty?
  return @records.empty? if loaded?

  c = count
  c.respond_to?(:zero?) ? c.zero? : c.empty?
end

initialize_copy(other)

Source: show | on GitHub

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

insert(values)

Source: show | on GitHub

# File activerecord/lib/active_record/relation.rb, line 36
def insert(values)
  primary_key_value = nil

  if primary_key && Hash === values
    primary_key_value = values[values.keys.find { |k|
      k.name == primary_key
    }]

    if !primary_key_value && connection.prefetch_primary_key?(klass.table_name)
      primary_key_value = connection.next_sequence_value(klass.sequence_name)
      values[klass.arel_table[klass.primary_key]] = primary_key_value
    end
  end

  im = arel.create_insert
  im.into @table

  conn = @klass.connection

  substitutes = values.sort_by { |arel_attr,_| arel_attr.name }
  binds       = substitutes.map do |arel_attr, value|
    [@klass.columns_hash[arel_attr.name], value]
  end

  substitutes.each_with_index do |tuple, i|
    tuple[1] = conn.substitute_at(binds[i][0], i)
  end

  if values.empty? # empty insert
    im.values = Arel.sql(connection.empty_insert_statement_value)
  else
    im.insert substitutes
  end

  conn.insert(
    im,
    'SQL',
    primary_key,
    primary_key_value,
    nil,
    binds)
end

inspect()

Source: show | on GitHub

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

joined_includes_values()

Joins that are also marked for preloading. In which case we should just eager load them. Note that this is a naive implementation because we could have strings and symbols which represent the same association, but that aren’t matched by this. Also, we could have nested hashes which partially match, e.g. { :a => :b } & { :a => [:b, :c] }

Source: show | on GitHub

# File activerecord/lib/active_record/relation.rb, line 422
def joined_includes_values
  @includes_values & @joins_values
end

many?()

Source: show | on GitHub

# File activerecord/lib/active_record/relation.rb, line 161
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)

This method is also aliased as build

Source: show | on GitHub

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

reload()

Source: show | on GitHub

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

reset()

Source: show | on GitHub

# File activerecord/lib/active_record/relation.rb, line 389
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)

Source: show | on GitHub

# File activerecord/lib/active_record/relation.rb, line 97
def respond_to?(method, include_private = false)
  arel.respond_to?(method, include_private)     ||
    Array.method_defined?(method)               ||
    @klass.respond_to?(method, include_private) ||
    super
end

scope_for_create()

Source: show | on GitHub

# File activerecord/lib/active_record/relation.rb, line 408
def scope_for_create
  @scope_for_create ||= where_values_hash.merge(create_with_value)
end

scoping()

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.

Source: show | on GitHub

# File activerecord/lib/active_record/relation.rb, line 179
def scoping
  @klass.send(:with_scope, self, :overwrite) { yield }
end

size()

Returns size of the records.

Source: show | on GitHub

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

to_a()

Source: show | on GitHub

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

  default_scoped = with_default_scope

  if default_scoped.equal?(self)
    @records = if @readonly_value.nil? && !@klass.locking_enabled?
      eager_loading? ? find_with_associations : @klass.find_by_sql(arel, @bind_values)
    else
      IdentityMap.without do
        eager_loading? ? find_with_associations : @klass.find_by_sql(arel, @bind_values)
      end
    end

    preload = @preload_values
    preload +=  @includes_values unless eager_loading?
    preload.each do |associations|
      ActiveRecord::Associations::Preloader.new(@records, associations).run
    end

    # @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
  else
    @records = default_scoped.to_a
  end

  @loaded = true
  @records
end

to_sql()

Source: show | on GitHub

# File activerecord/lib/active_record/relation.rb, line 396
def to_sql
  @to_sql ||= klass.connection.to_sql(arel)
end

update(id, attributes)

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)

Source: show | on GitHub

# File activerecord/lib/active_record/relation.rb, line 253
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 = {})

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

# Conditions from the current relation also works
Book.where('title LIKE ?', '%Rails%').update_all(:author => 'David')

# The same idea applies to limit and order
Book.where('title LIKE ?', '%Rails%').order(:created_at).limit(5).update_all(:author => 'David')

Source: show | on GitHub

# File activerecord/lib/active_record/relation.rb, line 214
def update_all(updates, conditions = nil, options = {})
  IdentityMap.repository[symbolized_base_class].clear if IdentityMap.enabled?
  if conditions || options.present?
    where(conditions).apply_finder_options(options.slice(:limit, :order)).update_all(updates)
  else
    stmt = Arel::UpdateManager.new(arel.engine)

    stmt.set Arel.sql(@klass.send(:sanitize_sql_for_assignment, updates))
    stmt.table(table)
    stmt.key = table[primary_key]

    if joins_values.any?
      @klass.connection.join_to_update(stmt, arel)
    else
      stmt.take(arel.limit)
      stmt.order(*arel.orders)
      stmt.wheres = arel.constraints
    end

    @klass.connection.update stmt, 'SQL', bind_values
  end
end

where_values_hash()

Source: show | on GitHub

# File activerecord/lib/active_record/relation.rb, line 400
def where_values_hash
  equalities = with_default_scope.where_values.grep(Arel::Nodes::Equality).find_all { |node|
    node.left.relation.name == table_name
  }

  Hash[equalities.map { |where| [where.left.name, where.right] }]
end

Instance Protected methods

method_missing(method, *args, &block)

Source: show | on GitHub

# File activerecord/lib/active_record/relation.rb, line 451
def method_missing(method, *args, &block)
  if Array.method_defined?(method)
    to_a.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

Class ActiveRecord::Relation < Object

Active Record Relation

Examples

Parameters

Example

Parameters

Examples

Parameters

Examples

Example

Parameters

Examples

Parameters

Examples