Ecto.Repo поведение

@callback delete(
  struct_or_changeset :: Ecto.Schema.t() | Ecto.Changeset.t(),
  opts :: Keyword.t()
) :: {:ok, Ecto.Schema.t()} | {:error, Ecto.Changeset.t()}

Удаляет структуру с использованием её первичного ключа.

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

Функция возвращает {:ok, struct}, если структура была успешно удалена, или {:error, changeset}, если произошла ошибка валидации или известная ошибка ограничения. По умолчанию ошибки ограничений вызывают исключение Ecto.ConstraintError, если только первым аргументом не передан changeset с объявленными в нём соответствующими ограничениями (см. Ecto.Changeset).

Параметры

• :returning — определяет, какие поля нужно вернуть. Принимает список полей, которые нужно вернуть из базы данных. Если указано true, возвращает все поля, включая помеченные как load_in_query: false. Если указано false, дополнительные поля не возвращаются. Всегда включает все поля в read_after_writes. Также принимает {:unsafe_fragment, fragment}, чтобы напрямую передать необработанное SQL-выражение в предложение RETURNING (без экранирования; используйте с осторожностью). Обратите внимание, что поля, возвращённые из базы данных, заменяют значения, переданные пользователем. Любое поле, не возвращённое базой данных, будет содержать исходное значение, переданное пользователем. Не все базы данных поддерживают этот параметр.

• :prefix — префикс, в котором выполняется запрос (например, путь схемы в Postgres или база данных в MySQL). Переопределяет префикс, заданный в запросе, и любой @schema_prefix, заданный в схеме.

• :stale_error_field — поле, в которое будут добавлены ошибки устаревших данных в возвращаемом changeset. Этот параметр позволяет избежать вызова Ecto.StaleEntryError.

• :stale_error_message — сообщение, добавляемое в настроенный :stale_error_field при возникновении ошибок устаревших данных; по умолчанию — "is stale".

• :allow_stale — не вызывает ошибку, если удаляемая запись устарела. По умолчанию — false. Это может произойти, если структура была удалена из базы данных до этого удаления или если правило либо триггер базы данных отклоняет операцию удаления.

Дополнительные параметры см. в разделе «Общие параметры» документации модуля.

Пример

post = MyRepo.get!(Post, 42)
case MyRepo.delete(post) do
  {:ok, struct}       -> # Deleted with success
  {:error, changeset} -> # Something went wrong
end

@callback delete!(
  struct_or_changeset :: Ecto.Schema.t() | Ecto.Changeset.t(),
  opts :: Keyword.t()
) :: Ecto.Schema.t()

То же, что и delete/2, но возвращает структуру или вызывает исключение, если changeset недействителен.

@callback insert(
  struct_or_changeset :: Ecto.Schema.t() | Ecto.Changeset.t(),
  opts :: Keyword.t()
) :: {:ok, Ecto.Schema.t()} | {:error, Ecto.Changeset.t()}

Вставляет структуру, определённую с помощью Ecto.Schema, или changeset.

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

Если передан changeset, изменения в нём объединяются с полями структуры, после чего всё отправляется в базу данных. Если требуется более одной операции с базой данных, они автоматически выполняются в транзакции.

Функция возвращает {:ok, struct}, если структура была успешно вставлена, или {:error, changeset}, если произошла ошибка валидации или известная ошибка ограничения.

Параметры

• :returning — определяет, какие поля нужно вернуть. Принимает список полей, которые нужно вернуть из базы данных. Если указано true, возвращает все поля, включая помеченные как load_in_query: false. Если указано false, дополнительные поля не возвращаются. Всегда включает все поля в read_after_writes, а также любой автоматически сгенерированный идентификатор. Также принимает {:unsafe_fragment, fragment}, чтобы напрямую передать необработанное SQL-выражение в предложение RETURNING (без экранирования; используйте с осторожностью). Обратите внимание, что поля, возвращённые из базы данных, заменяют значения, переданные пользователем. Любое поле, не возвращённое базой данных, будет содержать исходное значение, переданное пользователем. Не все базы данных поддерживают этот параметр, и он может быть недоступен при выполнении upsert. Подробнее см. в разделе «Upsert».

• :prefix — префикс, в котором выполняется запрос (например, путь схемы в Postgres или база данных в MySQL). Переопределяет префикс, заданный в запросе, и любой @schema_prefix, заданный в схемах. Кроме того, @schema_prefix родительской записи переопределяет все значения @schema_prefix по умолчанию, заданные в дочерних схемах связей.

• :on_conflict — может принимать одно из значений :raise (по умолчанию), :nothing, :replace_all, {:replace_all_except, fields}, {:replace, fields}, список ключевых слов с инструкциями обновления или запрос Ecto.Query для обновления. Подробнее см. в разделе «Upsert».

• :conflict_target — список имён столбцов для проверки конфликтов. Предполагается, что для этих столбцов созданы уникальные индексы, с которыми может возникнуть конфликт. Если параметр не указан, цель конфликта определяется базой данных. Также может принимать {:unsafe_fragment, binary_fragment}, чтобы передать в базу данных любое выражение без очистки; это полезно для частичных индексов или индексов с выражениями, например {:unsafe_fragment, "(coalesce(firstname, ""), coalesce(lastname, "")) WHERE middlename IS NULL"} для SQL-запроса ON CONFLICT (coalesce(firstname, ""), coalesce(lastname, "")) WHERE middlename IS NULL.

• :replace_changed — определяет, включать ли поля :conflict_target, когда :on_conflict равно :replace_all или {:replace_all_except, fields}. Если указано true, конфликтующие поля не обновляются, что позволяет использовать такие оптимизации, как HOT-обновления в PostgreSQL. По умолчанию — true.

• :stale_error_field — поле, в которое будут добавлены ошибки устаревших данных в возвращаемом changeset. Этот параметр позволяет избежать вызова Ecto.StaleEntryError.

• :stale_error_message — сообщение, добавляемое в настроенный :stale_error_field при возникновении ошибок устаревших данных; по умолчанию — "is stale".

• :allow_stale — не вызывает ошибку, если структуры устарели. По умолчанию — false. Это может произойти, если правила или триггеры базы данных отклоняют операцию вставки. Параметр распространяется на связи.

Дополнительные параметры см. в разделе «Общие параметры» документации модуля.

Примеры

Типичный пример — вызов MyRepo.insert/1 со структурой и обработка возвращаемого значения:

case MyRepo.insert(%Post{title: "Ecto is great"}) do
  {:ok, struct}       -> # Inserted with success
  {:error, changeset} -> # Something went wrong
end

Upsert

insert/2 поддерживает upsert (обновление или вставку) с помощью параметра :on_conflict. Параметр :on_conflict поддерживает следующие значения:

• :raise — вызывает ошибку при конфликте первичного ключа или уникального индекса

• :nothing — игнорирует ошибку при конфликте

• :replace_all — заменяет все значения существующей строки значениями из схемы/changeset, включая поля, явно не заданные в changeset, например идентификаторы и автоматически сгенерированные временные метки (inserted_at и updated_at). Не используйте этот параметр, если у вас есть автоинкрементные первичные ключи: они также будут заменены. Скорее всего, вам стоит вместо этого явно использовать {:replace_all_except, [:id]} или {:replace, fields}. Для этого параметра требуется схема. Поля, указанные в :conflict_target, будут проигнорированы, если только :replace_changed не настроен как false

• {:replace_all_except, fields} — то же, что и выше, но указанные поля не заменяются. Для этого параметра требуется схема

• {:replace, fields} — заменяет только определённые столбцы. Для этого параметра требуется :conflict_target

• список ключевых слов с инструкциями обновления — например, тот, который передаётся в update_all/3, например: [set: [title: "new title"]]

• запрос Ecto.Query, который будет использоваться как инструкция UPDATE, например, передаваемая в update_all/3. Как и в случае с update_all/3, автоматически сгенерированные значения, например временные метки, не обновляются автоматически. Если структура не найдена, будет вызвана ошибка Ecto.StaleEntryError.

В таких базах данных, как Postgres, upsert преобразуется в "ON CONFLICT", а в таких, как MySQL, — в "ON DUPLICATE KEY".

Например, предположим, что :title помечен в базе данных как уникальный столбец:

{:ok, inserted} = MyRepo.insert(%Post{title: "this is unique"})

Теперь можно вставить запись с тем же заголовком и ничего не делать при конфликте:

{:ok, ignored} = MyRepo.insert(%Post{title: "this is unique"}, on_conflict: :nothing)

Поскольку мы использовали on_conflict: :nothing, вместо ошибки получили {:ok, struct}. Однако возвращённая структура не отражает данные в базе данных. Если первичный ключ генерируется базой данных автоматически, первичный ключ в записи ignored будет равен nil, если вставка не произошла. Например, если используется первичный ключ по умолчанию (с именем :id и типом :id), то указанный выше ignored.id будет равен nil, если вставка не произошла.

Если идентификатор генерируется приложением (обычно так бывает для :binary_id) или если для :on_conflict передано другое значение, определить, произошла ли вставка или обновление, немного сложнее, так как база данных фактически не сообщает нам, что произошло. Давайте вставим запись с тем же заголовком, но при конфликте используем запрос для обновления столбца body:

# In Postgres (it requires the conflict target for updates):
on_conflict = [set: [body: "updated"]]
{:ok, updated} = MyRepo.insert(%Post{title: "this is unique"},
                               on_conflict: on_conflict, conflict_target: :title)

# In MySQL (conflict target is not supported):
on_conflict = [set: [title: "updated"]]
{:ok, updated} = MyRepo.insert(%Post{id: inserted.id, title: "updated"},
                               on_conflict: on_conflict)

В приведённых выше примерах, хотя функция и вернула :ok, мы не знаем, вставили ли мы новые данные или обновили только поля :on_conflict. Если произошло обновление, данные в структуре, скорее всего, не совпадают с данными в базе данных. Например, автоматически сгенерированные поля, такие как inserted_at, будут указывать на текущее время, а не на время фактической вставки структуры.

Если нужно гарантировать, что данные в возвращённой структуре соответствуют базе данных, есть три варианта:

• Использовать on_conflict: :replace_all, хотя это заменит все поля в базе данных значениями из структуры/changeset, включая автоматически сгенерированные поля, такие как inserted_at и updated_at:

  MyRepo.insert(%Post{title: "this is unique"},
                on_conflict: :replace_all, conflict_target: :title)

• Указать read_after_writes: true в схеме, чтобы выбрать поля, считываемые из базы данных после каждой операции. Либо передать returning: true в insert, чтобы считать все поля. (Обратите внимание: чтение из базы данных произойдёт, только если обновлено хотя бы одно поле.)

  MyRepo.insert(%Post{title: "this is unique"}, returning: true,
                on_conflict: on_conflict, conflict_target: :title)

• В качестве альтернативы можно повторно считать данные из базы данных отдельным запросом. Для этого варианта первичный ключ должен генерироваться базой данных:

  {:ok, updated} = MyRepo.insert(%Post{title: "this is unique"}, on_conflict: on_conflict)
  Repo.get(Post, updated.id)

Поскольку невозможно определить, актуальна ли структура, не рекомендуется одновременно вставлять структуру со связями и использовать параметр :on_conflict: Ecto не сможет правильно отслеживать состояние связи.

Расширенные сценарии upsert

Использование запроса Ecto.Query для :on_conflict позволяет задействовать более сложные возможности базы данных. Например, PostgreSQL поддерживает условные операции upsert, такие как DO UPDATE SET title = EXCLUDED.title, version = EXCLUDED.version WHERE EXCLUDED.version > post.version. Это означает, что заголовок и версия будут обновлены, только если версия предлагаемой строки выше версии существующей строки.

Ecto поддерживает такой сценарий следующим образом:

conflict_query =
  from(p in Post,
    update: [set: [
      title: fragment("EXCLUDED.title"),
      version: fragment("EXCLUDED.version")
      ]],
    where: fragment("EXCLUDED.version > ?", p.version)
  )

MyRepo.insert(
  %Post{id: 1, title: "Ecto Upserts (Dance Remix)", version: 2},
  conflict_target: [:id],
  on_conflict: conflict_query
)

@callback insert!(
  struct_or_changeset :: Ecto.Schema.t() | Ecto.Changeset.t(),
  opts :: Keyword.t()
) :: Ecto.Schema.t()

То же, что и insert/2, но возвращает структуру или вызывает исключение, если changeset недействителен.

@callback insert_all(
  schema_or_source :: binary() | {binary(), module()} | module(),
  entries_or_query ::
    [%{required(atom() | String.t()) => value} | Keyword.t(value)]
    | Ecto.Query.t(),
  opts :: Keyword.t()
) :: {non_neg_integer(), nil | [term()]}
when value: term() | Ecto.Query.t()

Вставляет все записи в репозиторий.

Первым аргументом ожидается модуль схемы (MyApp.User), источник ("users") или и то и другое ({"users", MyApp.User}). Второй аргумент — список вставляемых записей в виде списков ключевых слов или карт. Если первым аргументом указан модуль схемы, ключи записей — это имена полей в виде атомов. В противном случае ключами могут быть атомы или строки, представляющие имена столбцов в базовом хранилище данных. Значением должно быть соответствующее значение типа поля или, по желанию, запрос Ecto.Query, возвращающий одну запись с одним значением.

Функция возвращает кортеж, содержащий количество записей и результат, если он был возвращён, в качестве второго элемента. Если база данных не поддерживает RETURNING в инструкциях INSERT или результат не был выбран для возврата, второй элемент будет равен nil.

Если передан модуль схемы, записи будут корректно преобразованы перед отправкой в базу данных. Если тип первичного ключа схемы — :id или :binary_id, его обработка выполняется на уровне адаптера или хранилища. Однако ключи других типов и автоматически генерируемые значения, такие как Ecto.UUID и временные метки, не будут автоматически сгенерированы при использовании insert_all/3. Эти поля необходимо задавать явно. Это сделано намеренно: данная функция обеспечивает более прямой способ вставки данных в базу данных без дополнительных удобств insert/2. Это также согласуется с update_all/3, которая также не обрабатывает автоматически генерируемые значения.

Кроме того, использовать insert_all для вставки данных в несколько таблиц невозможно, поэтому связи не поддерживаются.

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

Параметры

• :returning — определяет, какие поля нужно вернуть. Если указано true, возвращаются все поля заданной схемы. Можно указать список полей: структура будет возвращена, но только с заданными полями. Или false, при котором ничего не возвращается (значение по умолчанию). Также принимает {:unsafe_fragment, fragment}, чтобы напрямую передать необработанное SQL-выражение в предложение RETURNING (без экранирования; используйте с осторожностью). Этот параметр поддерживается не всеми базами данных.

• :prefix — префикс, в котором выполняется запрос (например, путь схемы в Postgres или база данных в MySQL). Переопределяет префикс, заданный в запросе, и любой @schema_prefix, заданный в схеме.

• :on_conflict — может принимать одно из значений :raise (по умолчанию), :nothing, :replace_all, {:replace_all_except, fields}, {:replace, fields}, список ключевых слов с инструкциями обновления или запрос Ecto.Query для обновления. Подробнее см. в разделе «Upsert».

• :conflict_target — список имён столбцов для проверки конфликтов. Предполагается, что для этих столбцов созданы уникальные индексы, с которыми может возникнуть конфликт. Если параметр не указан, цель конфликта определяется базой данных. Также может принимать {:unsafe_fragment, binary_fragment}, чтобы передать в базу данных любое выражение без очистки; это полезно для частичных индексов или индексов с выражениями, например {:unsafe_fragment, "(coalesce(firstname, ''), coalesce(lastname, '')) WHERE middlename IS NULL"} для SQL-запроса ON CONFLICT (coalesce(firstname, ''), coalesce(lastname, '')) WHERE middlename IS NULL.

• :replace_changed — определяет, включать ли поля :conflict_target, когда :on_conflict равно :replace_all или {:replace_all_except, fields}. Если указано true, поля, заданные в качестве цели конфликта, не обновляются, что позволяет использовать такие оптимизации, как HOT-обновления в PostgreSQL. По умолчанию — true.

• :placeholders — карта с заполнителями. Эта возможность поддерживается не всеми базами данных. Подробнее см. в разделе «Заполнители».

Остальные параметры см. в разделе «Общие параметры» документации модуля.

Запрос-источник

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

Примеры

MyRepo.insert_all(Post, [[title: "My first post"], [title: "My second post"]])

MyRepo.insert_all(Post, [%{title: "My first post"}, %{title: "My second post"}])

query = from p in Post,
  join: c in assoc(p, :comments),
  select: %{
    author_id: p.author_id,
    posts: count(p.id, :distinct),
    interactions: sum(p.likes) + count(c.id)
  },
  group_by: p.author_id
MyRepo.insert_all(AuthorStats, query)

Upsert

insert_all/3 поддерживает upsert (обновление или вставку) с помощью параметра :on_conflict. Параметр :on_conflict поддерживает следующие значения:

• :raise — вызывает ошибку при конфликте первичного ключа или уникального индекса

• :nothing — игнорирует ошибку при конфликте

• :replace_all — заменяет все значения существующей строки значениями из схемы/changeset, включая поля, явно не заданные в changeset, например идентификаторы и автоматически сгенерированные временные метки (inserted_at и updated_at). Не используйте этот параметр, если у вас есть автоинкрементные первичные ключи: они также будут заменены. Скорее всего, вам стоит вместо этого явно использовать {:replace_all_except, [:id]} или {:replace, fields}. Для этого параметра требуется схема. Поля, указанные в :conflict_target, будут проигнорированы, если только :replace_changed не настроен как false

• {:replace_all_except, fields} — то же, что и выше, но указанные поля (и поля, заданные в качестве цели конфликта) не заменяются. Для этого параметра требуется схема

• {:replace, fields} — заменяет только определённые столбцы. Для этого параметра требуется :conflict_target. Как правило, следует убедиться, что заданные для замены поля не пересекаются с conflict_target, поскольку тогда базы данных смогут выполнять upsert эффективнее

• список ключевых слов с инструкциями обновления — например, тот, который передаётся в update_all/3, например: [set: [title: "new title"]]

• запрос Ecto.Query, который будет использоваться как инструкция UPDATE, например, передаваемая в update_all/3

В таких базах данных, как Postgres, upsert преобразуется в "ON CONFLICT", а в таких, как MySQL, — в "ON DUPLICATE KEY".

Возвращаемые значения

По умолчанию Postgres и MySQL возвращают количество записей, вставленных с помощью insert_all/3. Однако при указании параметра :on_conflict Postgres и MySQL возвращают разные результаты.

Postgres учитывает только затронутые строки и возвращает 0, если новая запись не была добавлена.

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

Также обратите внимание: если :on_conflict — это запрос, MySQL вернёт количество записей, для которых была предпринята попытка вставки, плюс количество записей, изменённых запросом UPDATE.

Заполнители

Передача карты в :placeholders позволяет отправлять меньше данных по сети, если во многих записях значение одного и того же поля совпадает. Чтобы использовать заполнитель, замените значение в каждой записи на {:placeholder, key}, где key — это ключ, используемый в карте параметра :placeholders. Например:

placeholders = %{blob: large_blob_of_text(...)}

entries = [
  %{title: "v1", body: {:placeholder, :blob}},
  %{title: "v2", body: {:placeholder, :blob}}
]

Repo.insert_all(Post, entries, placeholders: placeholders)

Обратите внимание:

• заполнители нельзя вкладывать в другие значения. Например, нельзя поместить заполнитель в массив. Вместо этого весь массив должен быть заполнителем

• ключ заполнителя можно использовать только со столбцами одного типа

• для заполнителей требуется база данных с поддержкой индексных параметров, поэтому в настоящее время они несовместимы с MySQL

@callback insert_or_update(changeset :: Ecto.Changeset.t(), opts :: Keyword.t()) ::
  {:ok, Ecto.Schema.t()} | {:error, Ecto.Changeset.t()}

Вставляет или обновляет changeset в зависимости от того, сохранена ли структура в базе данных.

Решение о вставке или обновлении принимается на основании поля Ecto.Schema.Metadata — :state. Ecto автоматически задаёт :state при загрузке или создании схемы.

Обратите внимание: для работы этой функции необходимо загрузить существующие структуры из базы данных. Поэтому следующий вариант не сработает, даже если структура существует:

struct = %Post{id: "existing_id", ...}
MyRepo.insert_or_update(changeset)
# => {:error, changeset} # id already exists

Параметры

• :prefix — префикс, в котором выполняется запрос (например, путь схемы в Postgres или база данных в MySQL). Переопределяет префикс, заданный в запросе, и любой @schema_prefix, заданный в схемах. Кроме того, @schema_prefix родительской записи переопределяет все значения @schema_prefix по умолчанию, заданные в дочерних схемах связей.
• :stale_error_field — поле, в которое будут добавлены ошибки устаревших данных в возвращаемом changeset. Этот параметр позволяет избежать вызова Ecto.StaleEntryError. Применяется только при обновлении.
• :stale_error_message — сообщение, добавляемое в настроенный :stale_error_field при возникновении ошибок устаревших данных; по умолчанию — "is stale". Применяется только при обновлении.
• :allow_stale — не вызывает ошибку, если структуры устарели. По умолчанию — false. Параметр распространяется на связи.

Дополнительные параметры см. в разделе «Общие параметры» документации модуля.

Пример

result =
  case MyRepo.get(Post, id) do
    nil  -> %Post{id: id} # Post not found, we build one
    post -> post          # Post exists, let's use it
  end
  |> Post.changeset(changes)
  |> MyRepo.insert_or_update()

case result do
  {:ok, struct}       -> # Inserted or updated with success
  {:error, changeset} -> # Something went wrong
end

@callback insert_or_update!(changeset :: Ecto.Changeset.t(), opts :: Keyword.t()) ::
  Ecto.Schema.t()

То же, что и insert_or_update/2, но возвращает структуру или вызывает исключение, если changeset недействителен.

@callback load(
  schema_or_map :: module() | map(),
  data :: map() | Keyword.t() | {list(), list()}
) :: Ecto.Schema.t() | map()

Загружает data в схему или карту.

Первым аргументом может быть модуль схемы или карта (типов). Первый аргумент определяет возвращаемое значение: соответственно структуру или карту.

Второй аргумент data указывает поля и значения, которые нужно загрузить. Это может быть карта, список ключевых слов или кортеж {fields, values}. Поля могут быть атомами или строками.

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

Для загрузки данных из источников, отличных от базы данных, используйте Ecto.embedded_load/3.

Примеры

iex> MyRepo.load(User, %{name: "Alice", age: 25})
%User{name: "Alice", age: 25}

iex> MyRepo.load(User, [name: "Alice", age: 25])
%User{name: "Alice", age: 25}

data также может иметь вид {fields, values}:

iex> MyRepo.load(User, {[:name, :age], ["Alice", 25]})
%User{name: "Alice", age: 25, ...}

Первым аргументом также может быть карта types:

iex> types = %{name: :string, age: :integer}
iex> MyRepo.load(types, %{name: "Alice", age: 25})
%{name: "Alice", age: 25}

Эта функция особенно полезна при разборе результатов необработанных запросов:

iex> result = Ecto.Adapters.SQL.query!(MyRepo, "SELECT * FROM users", [])
iex> Enum.map(result.rows, &MyRepo.load(User, {result.columns, &1}))
[%User{...}, ...]

@callback preload(structs_or_struct_or_nil, preloads :: term(), opts :: Keyword.t()) ::
  structs_or_struct_or_nil
when structs_or_struct_or_nil: [Ecto.Schema.t()] | Ecto.Schema.t() | nil

Предварительно загружает все связи для указанной структуры или структур.

Это похоже на Ecto.Query.preload/3, но позволяет предварительно загружать структуры после их получения из базы данных.

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

comment1 = TestRepo.preload(comment1, [author: [:permalink]])
TestRepo.preload([comment1, comment2], :author)

Если оба комментария связаны с одним автором, у первого комментария будет удалена вложенная связь :permalink, поскольку для второго комментария она не была предварительно загружена. Чтобы избежать этого, необходимо также предварительно загрузить вложенные связи.

Чтобы сбросить загруженные поля, см. Ecto.reset_fields/2.

Параметры

• :force — по умолчанию Ecto не загружает повторно уже загруженные связи. Если задать этому параметру значение true, все существующие связи будут отброшены и загружены заново.
• :in_parallel — определяет, следует ли выполнять предварительную загрузку параллельно. Это возможно, только если предварительно загружается более одной связи и репозиторий не находится в транзакции. По умолчанию — true.
• :prefix — префикс, из которого выполняется предварительная загрузка. По умолчанию запросы используют тот же префикс, что и первая структура в заданной коллекции. Этот параметр позволяет изменить префикс.
• :on_preloader_spawn — при параллельной предварительной загрузке эта функция будет вызвана в процессах, выполняющих загрузку. Это может быть полезно для передачи контекста трассировок.

Дополнительные параметры см. в разделе «Общие параметры» документации модуля.

Примеры

# Use a single atom to preload an association
posts = Repo.preload posts, :comments

# Use a list of atoms to preload multiple associations
posts = Repo.preload posts, [:comments, :authors]

# Use a keyword list to preload nested associations as well
posts = Repo.preload posts, [comments: [:replies, :likes], authors: []]

# You can mix atoms and keywords, but the atoms must come first
posts = Repo.preload posts, [:authors, comments: [:likes, replies: [:reactions]]]

# Use a keyword list to customize how associations are queried
posts = Repo.preload posts, [comments: from(c in Comment, order_by: c.published_at)]

# Use a two-element tuple for a custom query and nested association definition
query = from c in Comment, order_by: c.published_at
posts = Repo.preload posts, [comments: {query, [:replies, :likes]}]

# Use a function for custom preloading
posts = Repo.preload posts, [comments: fn post_ids -> fetch_comments_by_post_ids(post_ids) end]

Запрос, переданный в preload, также может выполнять предварительную загрузку собственных связей. Подробности см. в разделах «Запросы предварительной загрузки» и «Функции предварительной загрузки» документации Ecto.Query.preload/3.

@callback reload(
  struct_or_structs :: Ecto.Schema.t() | [Ecto.Schema.t()],
  opts :: Keyword.t()
) :: Ecto.Schema.t() | [Ecto.Schema.t() | nil] | nil

Повторно загружает указанную схему или список схем из базы данных.

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

Предварительно загруженные связи будут отброшены, и их потребуется загрузить заново.

Пример

MyRepo.reload(post)
%Post{}

MyRepo.reload([post1, post2])
[%Post{}, %Post{}]

MyRepo.reload([deleted_post, post1])
[nil, %Post{}]

@callback reload!(struct_or_structs, opts :: Keyword.t()) :: struct_or_structs
when struct_or_structs: Ecto.Schema.t() | [Ecto.Schema.t()]

Похожа на reload/2, но вызывает исключение, если что-либо не найдено.

При использовании со списками порядок элементов сохраняется.

Пример

MyRepo.reload!(post)
%Post{}

MyRepo.reload!([post1, post2])
[%Post{}, %Post{}]

@callback update(changeset :: Ecto.Changeset.t(), opts :: Keyword.t()) ::
  {:ok, Ecto.Schema.t()} | {:error, Ecto.Changeset.t()}

Обновляет changeset, используя его первичный ключ.

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

Если у структуры нет первичного ключа, будет вызвана ошибка Ecto.NoPrimaryKeyFieldError.

Если структуру не удастся найти, будет вызвана ошибка Ecto.StaleEntryError.

Возвращает {:ok, struct}, если структура успешно обновлена, или {:error, changeset}, если произошла ошибка валидации или известная ошибка ограничения.

Параметры

• :returning — определяет, какие поля нужно вернуть. Принимает список полей, которые нужно получить из базы данных. Если указано true, возвращаются все поля, в том числе помеченные как load_in_query: false. Если указано false, дополнительные поля не возвращаются. Все поля из read_after_writes будут включены в любом случае. Также принимает {:unsafe_fragment, fragment}, чтобы передать необработанное SQL-выражение напрямую в предложение RETURNING (оно не экранируется, используйте с осторожностью). Учтите, что значения, полученные из базы данных, перезаписывают переданные пользователем значения. Поля, не возвращённые базой данных, сохранят исходные значения, переданные пользователем. Не все базы данных поддерживают этот параметр.

• :force — по умолчанию, если в changeset нет изменений, update/2 ничего не делает. Если установить этот параметр в true, callbacks обновления будут выполняться всегда, даже при отсутствии изменений (включая временные метки).

• :prefix — префикс, для которого выполняется запрос (например, путь схемы в Postgres или база данных в MySQL). Он переопределяет префикс, заданный в запросе, а также любые значения @schema_prefix, заданные в схемах. Кроме того, @schema_prefix родительской записи переопределит все значения @schema_prefix по умолчанию, заданные в дочерних схемах для ассоциаций.

• :stale_error_field — поле, в которое будут добавлены ошибки устаревшей записи в возвращаемом changeset. Этот параметр можно использовать, чтобы избежать вызова ошибки Ecto.StaleEntryError.

• :stale_error_message — сообщение, добавляемое к настроенному :stale_error_field при возникновении ошибок устаревшей записи. По умолчанию — «is stale».

• :allow_stale — не вызывает ошибку, если запись устарела. По умолчанию — false. Такое может произойти, если структура была удалена из базы данных до обновления или если правило либо триггер в базе данных отклоняет операцию обновления. Этот параметр распространяется на ассоциации.

Дополнительные параметры см. в разделе «Общие параметры» документации модуля.

Пример

post = MyRepo.get!(Post, 42)
post = Ecto.Changeset.change(post, title: "New title")
case MyRepo.update(post) do
  {:ok, struct}       -> # Updated with success
  {:error, changeset} -> # Something went wrong
end

@callback update!(changeset :: Ecto.Changeset.t(), opts :: Keyword.t()) :: Ecto.Schema.t()

Работает так же, как update/2, но возвращает структуру или вызывает ошибку, если changeset недействителен.