Команда ReQL: replace

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

table.replace(object | function[, {durability: "hard", returnChanges: false, nonAtomic: false, ignoreWriteHook: false}]) → object
selection.replace(object | function[, {durability: "hard", returnChanges: false, nonAtomic: false, ignoreWriteHook: false}]) → object
singleSelection.replace(object | function[, {durability: "hard", returnChanges: false, nonAtomic: false, ignoreWriteHook: false}]) → object

Описание

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

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

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

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

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

• replaced: количество документов, которые были заменены.
• unchanged: количество документов, которые были бы изменены, за исключением случаев, когда новое значение было таким же, как старое.
• inserted: количество новых добавленных документов. Документ считается вставленным, если его первичный ключ не существовал в таблице во время операции replace.
• deleted: количество удалённых документов при замене с null.
• errors: количество ошибок, возникших при выполнении замены.
• first_error: Если возникли ошибки, содержит текст первой ошибки.
• skipped: 0 для операции замены.
• changes: если returnChanges установлено в 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, callback)

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

r.table("posts").replace(function(post) {
    return post.without("status")
}).run(conn, callback)

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

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

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

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

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

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

Результат будет иметь два поля old_val и new_val.

{
    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
}