Команда 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 может использоваться для вставки и удаления документов. Если у «заменённого» документа есть первичный ключ, которого нет в таблице, документ будет вставлен; если существующий документ заменён на None, документ будет удалён. Поскольку 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: количество удалённых документов при замене с None.
• errors: количество ошибок, возникших при выполнении замены.
• first_error: Если возникли ошибки, содержит текст первой ошибки.
• skipped: 0 для операции replace.
• changes: если return_changes установлено в True, это будет массив объектов, по одному для каждого объекта, затронутого операцией replace.

Операции записи 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(lambda post:
    post.without("status")
).run(conn)

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

r.table("posts").replace(lambda 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
}