Команда ReQL: replace

Синтаксис команды

table.replace(object | function[, :durability => "hard", :return_changes => false, :non_atomic => false, :ignore_write_hook => false]) → object
selection.replace(object | function[, :durability => "hard", :return_changes => false, :non_atomic => false, :ignore_write_hook => false]) → object
singleSelection.replace(object | function[, :durability => "hard", :return_changes => false, :non_atomic => false, :ignore_write_hook => false]) → object

Описание

Заменяет документы в таблице. Принимает JSON-документ или выражение ReQL и заменяет исходный документ новым. Новый документ должен иметь тот же первичный ключ, что и исходный документ.

Команда replace может использоваться для вставки и удаления документов. Если у «заменяемого» документа есть первичный ключ, которого нет в таблице, документ будет вставлен; если существующий документ заменяется на nil, документ будет удалён. Поскольку операции update и replace выполняются атомарно, это позволяет атомарно вставлять и удалять документы.

Необязательные аргументы:

• durability: возможные значения hard и soft. Этот параметр переопределит настройку надёжности таблицы или запроса (установленная в run). В режиме мягкой надёжности RethinkDB подтвердит запись сразу после её получения, но до того, как запись будет записана на диск.
• return_changes:
  • true: вернуть changes массив, состоящий из old_val/new_val объектов, описывающих внесенные изменения, включая только документы, которые были фактически обновлены.
  • false: не возвращать changes массив (по умолчанию).
  • "always": вести себя как true, но включать все документы, которые команда пыталась обновить, независимо от того, было ли обновление успешным. (Это было поведением true до версии 2.0.)
• non_atomic: если установлено значение true, выполняет замену и распределяет результат репликам не атомарным образом. Этот флаг необходим для выполнения недетерминированных обновлений, таких как те, которые требуют чтения данных из другой таблицы.
• ignore_write_hook: Если true, и если у пользователя есть право config, игнорирует любой write hook при выполнении замены.

Replace возвращает объект, содержащий следующие атрибуты:

• replaced: количество документов, которые были заменены.
• unchanged: количество документов, которые должны были быть изменены, за исключением того, что новое значение было таким же, как старое.
• inserted: количество добавленных новых документов. Документ считается вставленным, если его первичный ключ не существовал в таблице на момент операции replace.
• deleted: количество удаленных документов при замене на nil.
• errors: количество ошибок, возникших при выполнении замены.
• first_error: Если возникли ошибки, содержит текст первой ошибки.
• skipped: 0 для операции replace.
• changes: если return_changes установлено в значение true, это будет массив объектов, по одному для каждого объекта, затронутого операцией replace. Каждый объект будет иметь два ключа: {:new_val => <new value>, :old_val => <old value>}.

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

Пример: Замените документ с первичным ключом 1.

r.table("posts").get(1).replace({
    :id => 1,
    :title => "Lorem ipsum",
    :content => "Aleas jacta est",
    :status => "draft"
}).run(conn)

Пример: Удалите поле status из всех записей.

r.table("posts").replace{ |post|
    post.without("status")
}.run(conn)

Пример: Удалите все поля, которые не являются id, title или content.

r.table("posts").replace{ |post|
    post.pluck("id", "title", "content")
}.run(conn)

Пример: Замените документ с первичным ключом 1 с использованием мягкой надёжности.

r.table("posts").get(1).replace({
    :id => 1,
    :title => "Lorem ipsum",
    :content => "Aleas jacta est",
    :status => "draft"
}, :durability => "soft").run(conn)

Пример: Замените документ с первичным ключом 1 и верните значения документа до и после операции замены.

r.table("posts").get(1).replace({
    :id => 1,
    :title => "Lorem ipsum",
    :content => "Aleas jacta est",
    :status => "published"
}, :return_changes => true).run(conn)

Результат будет содержать поле changes:

{
    :deleted => 0,
    :errors => 0,
    :inserted => 0,
    :changes => [
        {
            :new_val => {
                :id => 1,
                :title => "Lorem ipsum"
                :content => "Aleas jacta est",
                :status => "published",
            },
            :old_val => {
                :id => 1,
                :title => "Lorem ipsum"
                :content => "TODO",
                :status => "draft",
                :author => "William",
            }
        }
    ],
    :replaced => 1,
    :skipped => 0,
    :unchanged => 0
}