Команда ReQL: replace

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

table.replace(object | function) → object
selection.replace(object | function) → object
singleSelection.replace(object | function) → object

Описание

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

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

Вы можете передать следующие параметры с помощью optArg:

• 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, и если у пользователя есть разрешение на конфигурацию, игнорирует любой 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(
    r.hashMap("id", 1).with("title", "Lorem ipsum")
     .with("content", "Aleas jacta est")
     .with("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(
    r.hashMap("id", 1)
     .with("title", "Lorem ipsum")
     .with("content", "Aleas jacta est")
     .with("status", "draft")
).optArg("durability", "soft").run(conn);

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

r.table("posts").get(1).replace(
    r.hashMap("id", 1)
     .with("title", "Lorem ipsum")
     .with("content", "Aleas jacta est")
     .with("status", "published")
).optArg("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
}