модуль ActiveRecord::QueryMethods

# File activerecord/lib/active_record/relation/query_methods.rb, line 726
def create_with(value)
  spawn.create_with!(value)
end

Устанавливает атрибуты, которые будут использоваться при создании новых записей из объекта отношения.

users = User.where(name: 'Oscar')
users.new.name # => 'Oscar'

users = users.create_with(name: 'DHH')
users.new.name # => 'DHH'

Вы можете передать nil в create_with для сброса атрибутов:

users = users.create_with(nil)
users.new.name # => 'Oscar'

# File activerecord/lib/active_record/relation/query_methods.rb, line 776
def distinct(value = true)
  spawn.distinct!(value)
end

Указывает, должны ли записи быть уникальными или нет. Например:

User.select(:name)
# => Might return two records with the same name

User.select(:name).distinct
# => Returns 1 record per distinct name

User.select(:name).distinct.distinct(false)
# => You can also remove the uniqueness

# File activerecord/lib/active_record/relation/query_methods.rb, line 163
def eager_load(*args)
  check_if_method_has_arguments!(:eager_load, args)
  spawn.eager_load!(*args)
end

Принудительно загружает данные, выполняя LEFT OUTER JOIN по args:

User.eager_load(:posts)
=> SELECT "users"."id" AS t0_r0, "users"."name" AS t0_r1, ...
FROM "users" LEFT OUTER JOIN "posts" ON "posts"."user_id" =
"users"."id"

# File activerecord/lib/active_record/relation/query_methods.rb, line 824
def extending(*modules, &block)
  if modules.any? || block
    spawn.extending!(*modules, &block)
  else
    self
  end
end

Используется для расширения области видимости дополнительными методами, либо через модуль, либо через предоставленный блок.

Возвращаемый объект — это отношение, которое можно дополнительно расширить.

Использование модуля

module Pagination
  def page(number)
    # pagination code goes here
  end
end

scope = Model.all.extending(Pagination)
scope.page(params[:page])

Вы также можете передать список модулей:

scope = Model.all.extending(Pagination, SomethingElse)

Использование блока

scope = Model.all.extending do
  def page(number)
    # pagination code goes here
  end
end
scope.page(params[:page])

Вы также можете использовать блок и список модулей:

scope = Model.all.extending(Pagination) do
  def per_page(number)
    # pagination code goes here
  end
end

# File activerecord/lib/active_record/relation/query_methods.rb, line 754
def from(value, subquery_name = nil)
  spawn.from!(value, subquery_name)
end

Указывает таблицу, из которой будут извлекаться записи. Например:

Topic.select('title').from('posts')
# => SELECT title FROM posts

Может принимать другие объекты отношения. Например:

Topic.select('title').from(Topic.approved)
# => SELECT title FROM (SELECT * FROM topics WHERE approved = 't') subquery

Topic.select('a.title').from(Topic.approved, :a)
# => SELECT a.title FROM (SELECT * FROM topics WHERE approved = 't') a

# File activerecord/lib/active_record/relation/query_methods.rb, line 286
def group(*args)
  check_if_method_has_arguments!(:group, args)
  spawn.group!(*args)
end

Позволяет указать атрибут группировки:

User.group(:name)
=> SELECT "users".* FROM "users" GROUP BY name

Возвращает массив с уникальными записями на основе атрибута group:

User.select([:id, :name])
=> [#<User id: 1, name: "Oscar">, #<User id: 2, name: "Oscar">, #<User id: 3, name: "Foo">

User.group(:name)
=> [#<User id: 3, name: "Foo", ...>, #<User id: 2, name: "Oscar", ...>]

User.group('name AS grouped_name, age')
=> [#<User id: 3, name: "Foo", age: 21, ...>, #<User id: 2, name: "Oscar", age: 21, ...>, #<User id: 5, name: "Foo", age: 23, ...>]

Поддерживается передача массива атрибутов для группировки.

User.select([:id, :first_name]).group(:id, :first_name).first(3)
=> [#<User id: 1, first_name: "Bill">, #<User id: 2, first_name: "Earl">, #<User id: 3, first_name: "Beto">]

# File activerecord/lib/active_record/relation/query_methods.rb, line 604
def having(opts, *rest)
  opts.blank? ? self : spawn.having!(opts, *rest)
end

Позволяет указать предложение HAVING. Обратите внимание, что вы не можете использовать HAVING без указания предложения GROUP.

Order.having('SUM(price) > 30').group('user_id')

# File activerecord/lib/active_record/relation/query_methods.rb, line 144
def includes(*args)
  check_if_method_has_arguments!(:includes, args)
  spawn.includes!(*args)
end

Указывает отношения, которые следует включить в результат. Например:

users = User.includes(:address)
users.each do |user|
  user.address.city
end

позволяет получить доступ к атрибуту address модели User без выполнения дополнительного запроса. Это часто приводит к улучшению производительности по сравнению с простым join.

Вы также можете указать несколько отношений, например:

users = User.includes(:address, :friends)

Загрузка вложенных отношений возможна с помощью Hash:

users = User.includes(:address, friends: [:address, :followers])

условия

Если вам нужно добавить условия к включённым моделям, вам нужно явно указать их. Например:

User.includes(:posts).where('posts.name = ?', 'example')

Вызовет ошибку, но это сработает:

User.includes(:posts).where('posts.name = ?', 'example').references(:posts)

Обратите внимание, что includes работает с именами ассоциаций, в то время как references требует фактического имени таблицы.

# File activerecord/lib/active_record/relation/query_methods.rb, line 428
def joins(*args)
  check_if_method_has_arguments!(:joins, args)
  spawn.joins!(*args)
end

Выполняет присоединение к args:

User.joins(:posts)
=> SELECT "users".* FROM "users" INNER JOIN "posts" ON "posts"."user_id" = "users"."id"

Вы можете использовать строки для настройки своих присоединений:

User.joins("LEFT JOIN bookmarks ON bookmarks.bookmarkable_type = 'Post' AND bookmarks.user_id = users.id")
=> SELECT "users".* FROM "users" LEFT JOIN bookmarks ON bookmarks.bookmarkable_type = 'Post' AND bookmarks.user_id = users.id

# File activerecord/lib/active_record/relation/query_methods.rb, line 620
def limit(value)
  spawn.limit!(value)
end

Устанавливает ограничение на количество извлекаемых записей.

User.limit(10) # generated SQL has 'LIMIT 10'

User.limit(10).limit(20) # generated SQL has 'LIMIT 20'

# File activerecord/lib/active_record/relation/query_methods.rb, line 647
def lock(locks = true)
  spawn.lock!(locks)
end

Устанавливает параметры блокировки (по умолчанию true). Для получения более подробной информации о блокировке см. ActiveRecord::Locking.

# File activerecord/lib/active_record/relation/query_methods.rb, line 690
def none
  where("1=0").extending!(NullRelation)
end

Возвращает цепное отношение с нулём записей.

Возвращаемое отношение реализует шаблон «Нулевой объект». Это объект с определённым поведением при нулевом значении и всегда возвращает пустой массив записей без запроса к базе данных.

Любое последующее условие, присоединённое к возвращённому отношению, будет продолжать генерировать пустое отношение и не будет выполнять ни одного запроса к базе данных.

Используется в тех случаях, когда метод или область видимости могут вернуть нуль записей, но результат должен быть цепким.

Например:

@posts = current_user.visible_posts.where(name: params[:name])
# => the visible_posts method is expected to return a chainable Relation

def visible_posts
  case role
  when 'Country Manager'
    Post.where(country: country)
  when 'Reviewer'
    Post.published
  when 'Bad User'
    Post.none # It can't be chained if [] is returned.
  end
end

# File activerecord/lib/active_record/relation/query_methods.rb, line 636
def offset(value)
  spawn.offset!(value)
end

Указывает количество строк, которые следует пропустить, прежде чем вернуть строки.

User.offset(10) # generated SQL has "OFFSET 10"

Следует использовать с order.

User.offset(10).order("name ASC")

# File activerecord/lib/active_record/relation/query_methods.rb, line 317
def order(*args)
  check_if_method_has_arguments!(:order, args)
  spawn.order!(*args)
end

Позволяет указать атрибут сортировки:

User.order(:name)
=> SELECT "users".* FROM "users" ORDER BY "users"."name" ASC

User.order(email: :desc)
=> SELECT "users".* FROM "users" ORDER BY "users"."email" DESC

User.order(:name, email: :desc)
=> SELECT "users".* FROM "users" ORDER BY "users"."name" ASC, "users"."email" DESC

User.order('name')
=> SELECT "users".* FROM "users" ORDER BY name

User.order('name DESC')
=> SELECT "users".* FROM "users" ORDER BY name DESC

User.order('name DESC, email')
=> SELECT "users".* FROM "users" ORDER BY name DESC, email

# File activerecord/lib/active_record/relation/query_methods.rb, line 177
def preload(*args)
  check_if_method_has_arguments!(:preload, args)
  spawn.preload!(*args)
end

Позволяет предварительно загрузить args, так же как и includes:

User.preload(:posts)
=> SELECT "posts".* FROM "posts" WHERE "posts"."user_id" IN (1, 2, 3)

# File activerecord/lib/active_record/relation/query_methods.rb, line 704
def readonly(value = true)
  spawn.readonly!(value)
end

Устанавливает атрибуты только для чтения для возвращаемого отношения. Если значение true (по умолчанию), попытка обновить запись приведет к ошибке.

users = User.readonly
users.first.save
=> ActiveRecord::ReadOnlyRecord: ActiveRecord::ReadOnlyRecord

# File activerecord/lib/active_record/relation/query_methods.rb, line 197
def references(*table_names)
  check_if_method_has_arguments!(:references, table_names)
  spawn.references!(*table_names)
end

Используется для указания, что указанные table_names ссылаются на строку SQL и, следовательно, должны быть подключены к любому запросу, а не загружаться отдельно. Этот метод работает только в сочетании с includes. Подробности см. в includes.

User.includes(:posts).where("posts.name = 'foo'")
# => Doesn't JOIN the posts table, resulting in an error.

User.includes(:posts).where("posts.name = 'foo'").references(:posts)
# => Query now knows the string references posts, so adds a JOIN

# File activerecord/lib/active_record/relation/query_methods.rb, line 338
def reorder(*args)
  check_if_method_has_arguments!(:reorder, args)
  spawn.reorder!(*args)
end

Заменяет любое существующее упорядочение, определённое в отношении, указанным упорядочением.

User.order('email DESC').reorder('id ASC') # generated SQL has 'ORDER BY id ASC'

Последующие вызовы order для того же отношения будут добавляться. Например:

User.order('email DESC').reorder('id ASC').order('name ASC')

генерирует запрос с 'ORDER BY id ASC, name ASC'.

# File activerecord/lib/active_record/relation/query_methods.rb, line 845
def reverse_order
  spawn.reverse_order!
end

Инвертирует существующее предложение order в отношении.

User.order('name ASC').reverse_order # generated SQL has 'ORDER BY name DESC'

# File activerecord/lib/active_record/relation/query_methods.rb, line 596
def rewhere(conditions)
  unscope(where: conditions.keys).where(conditions)
end

Позволяет изменить ранее заданное условие where для заданного атрибута вместо добавления к этому условию.

Post.where(trashed: true).where(trashed: false)                       # => WHERE `trashed` = 1 AND `trashed` = 0
Post.where(trashed: true).rewhere(trashed: false)                     # => WHERE `trashed` = 0
Post.where(active: true).where(trashed: true).rewhere(trashed: false) # => WHERE `active` = 1 AND `trashed` = 0

Это сокращённая запись для unscope(where: conditions.keys).where(conditions). Обратите внимание, что в отличие от reorder, мы отключаем только именованные условия — а не всё утверждение where.

# File activerecord/lib/active_record/relation/query_methods.rb, line 249
def select(*fields)
  if block_given?
    to_a.select { |*block_args| yield(*block_args) }
  else
    raise ArgumentError, 'Call this with at least one field' if fields.empty?
    spawn._select!(*fields)
  end
end

Работает двумя уникальными способами.

Во-первых: принимает блок, поэтому может быть использован так же, как Array#select.

Model.all.select { |m| m.field == value }

Это создаст массив объектов из базы данных для области видимости, преобразуя их в массив и итерируя по ним с помощью Array#select.

Во-вторых: изменяет оператор SELECT для запроса так, чтобы извлекались только определённые поля:

Model.select(:field)
# => [#<Model id: nil, field: "value">]

Хотя на примере кажется, что этот метод возвращает массив, на самом деле он возвращает объект отношения и к нему можно добавлять другие методы запроса, такие как другие методы в ActiveRecord::QueryMethods.

Аргумент метода также может быть массивом полей.

Model.select(:field, :other_field, :and_one_more)
# => [#<Model id: nil, field: "value", other_field: "value", and_one_more: "value">]

Можно также использовать одну или несколько строк, которые будут использоваться без изменений как поля SELECT.

Model.select('field AS field_one', 'other_field AS field_two')
# => [#<Model id: nil, field: "value", other_field: "value">]

Если был указан псевдоним, он будет доступен из полученных объектов:

Model.select('field AS field_one').first.field_one
# => "value"

Доступ к атрибутам объекта, которые не имеют полей, полученных методом select, кроме id вызовет ActiveModel::MissingAttributeError:

Model.select(:field).first.other_field
# => ActiveModel::MissingAttributeError: missing attribute: other_field

# File activerecord/lib/active_record/relation/query_methods.rb, line 388
def unscope(*args)
  check_if_method_has_arguments!(:unscope, args)
  spawn.unscope!(*args)
end

Удаляет нежелательное отношение, которое уже определено в цепочке отношений. Это полезно при передаче цепочек отношений и желании изменить отношения без перестройки всей цепочки.

User.order('email DESC').unscope(:order) == User.all

Аргументы метода — символы, соответствующие именам методов, которые нужно отменить. Действительные аргументы указаны в VALID_UNSCOPING_VALUES. Метод также может быть вызван с несколькими аргументами. Например:

User.order('email DESC').select('id').where(name: "John")
    .unscope(:order, :select, :where) == User.all

Кроме того, можно передать хэш в качестве аргумента, чтобы отменить конкретные значения :where. Это делается путём передачи хэша с единственной парой ключ-значение. Ключ должен быть :where, а значение — значение where, которое нужно отменить. Например:

User.where(name: "John", active: true).unscope(where: :name)
    == User.where(active: true)

Этот метод похож на except, но в отличие от except, он сохраняется при объединениях:

User.order('email').merge(User.except(:order))
    == User.order('email')

User.order('email').merge(User.unscope(:order))
    == User.all

Это означает, что он может использоваться в определениях ассоциаций:

has_many :comments, -> { unscope where: :trashed }

# File activerecord/lib/active_record/relation/query_methods.rb, line 568
def where(opts = :chain, *rest)
  if opts == :chain
    WhereChain.new(spawn)
  elsif opts.blank?
    self
  else
    spawn.where!(opts, *rest)
  end
end

Возвращает новое отношение, которое является результатом фильтрации текущего отношения в соответствии с условиями в аргументах.

where принимает условия в нескольких форматах. В примерах ниже представлен пример SQL; фактический сгенерированный запрос может отличаться в зависимости от адаптера базы данных.

строка

Одиночная строка без дополнительных аргументов передаётся в конструктор запроса как фрагмент SQL и используется в условии where запроса.

Client.where("orders_count = '2'")
# SELECT * from clients where orders_count = '2';

Обратите внимание, что создание собственной строки из пользовательского ввода может сделать ваше приложение уязвимым к инъекциям, если это не сделано должным образом. В качестве альтернативы рекомендуется использовать один из следующих методов.

массив

Если передаётся массив, то первый элемент массива обрабатывается как шаблон, а остальные элементы вставляются в шаблон для генерации условия. Active Record заботится о построении запроса, чтобы избежать атак с помощью инъекций, и преобразует тип ruby в тип базы данных при необходимости. Элементы вставляются в строку в том порядке, в котором они появляются.

User.where(["name = ? and email = ?", "Joe", "joe@example.com"])
# SELECT * FROM users WHERE name = 'Joe' AND email = 'joe@example.com';

В качестве альтернативы можно использовать именованные плейсхолдеры в шаблоне и передать хэш как второй элемент массива. Имена в шаблоне заменяются соответствующими значениями из хэша.

User.where(["name = :name and email = :email", { name: "Joe", email: "joe@example.com" }])
# SELECT * FROM users WHERE name = 'Joe' AND email = 'joe@example.com';

Это может сделать код более удобочитаемым в сложных запросах.

Наконец, можно использовать escapes в стиле sprintf в шаблоне. Это работает немного иначе, чем предыдущие методы; вы несете ответственность за то, чтобы значения в шаблоне были правильно обрамлены кавычками. Значения передаются соединителю для обработки кавычек, но вызов должен гарантировать, что они заключены в кавычки в результирующем SQL. После обработки кавычек значения вставляются с помощью тех же escapes, что и метод Ruby core Kernel::sprintf.

User.where(["name = '%s' and email = '%s'", "Joe", "joe@example.com"])
# SELECT * FROM users WHERE name = 'Joe' AND email = 'joe@example.com';

Если where вызывается с несколькими аргументами, они обрабатываются как элементы одного массива.

User.where("name = :name and email = :email", { name: "Joe", email: "joe@example.com" })
# SELECT * FROM users WHERE name = 'Joe' AND email = 'joe@example.com';

При использовании строк для указания условий можно использовать любой оператор, доступный в базе данных. Хотя это обеспечивает наибольшую гибкость, вы также можете непреднамеренно внести зависимости от базовой базы данных. Если ваш код предназначен для общего использования, протестируйте его с несколькими базами данных.

хэш

where также примет условие в формате хэш, в котором ключи — поля, а значения — значения для поиска.

Поля могут быть символами или строками. Значения могут быть одиночными значениями, массивами или диапазонами.

User.where({ name: "Joe", email: "joe@example.com" })
# SELECT * FROM users WHERE name = 'Joe' AND email = 'joe@example.com'

User.where({ name: ["Alice", "Bob"]})
# SELECT * FROM users WHERE name IN ('Alice', 'Bob')

User.where({ created_at: (Time.now.midnight - 1.day)..Time.now.midnight })
# SELECT * FROM users WHERE (created_at BETWEEN '2012-06-09 07:00:00.000000' AND '2012-06-10 07:00:00.000000')

В случае отношения belongs_to можно использовать ключ ассоциации для указания модели, если в качестве значения используется объект ActiveRecord.

author = Author.find(1)

# The following queries will be equivalent:
Post.where(author: author)
Post.where(author_id: author)

Это также работает с полиморфными отношениями belongs_to:

treasure = Treasure.create(name: 'gold coins')
treasure.price_estimates << PriceEstimate.create(price: 125)

# The following queries will be equivalent:
PriceEstimate.where(estimate_of: treasure)
PriceEstimate.where(estimate_of_type: 'Treasure', estimate_of_id: treasure)

Соединения

Если отношение является результатом соединения, вы можете создать условие, которое использует любые таблицы в соединении. Для строчных и массивов условий используйте имя таблицы в условии.

User.joins(:posts).where("posts.created_at < ?", Time.now)

Для условий хэша можно либо использовать имя таблицы в ключе, либо использовать подхэш.

User.joins(:posts).where({ "posts.published" => true })
User.joins(:posts).where({ posts: { published: true } })

без аргумента

Если не передаётся аргумент, where возвращает новый экземпляр WhereChain, который можно объединить с not для возвращения нового отношения, которое отрицает условие where.

User.where.not(name: "Jon")
# SELECT * FROM users WHERE name != 'Jon'

См. WhereChain для получения более подробной информации о not.

пустое условие

Если условие — любой пустой объект, то where — это операция без действия и возвращает текущее отношение.