Команда ReQL: insert

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

table.insert(object | [object1, object2, ...]) → object

Описание

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

• durability: возможные значения — hard и soft. Этот параметр переопределит настройку устойчивости таблицы или запроса (установленную в run). В режиме мягкой устойчивости RethinkDB подтвердит запись сразу после ее получения и кэширования, но до того, как запись будет записана на диск.
• return_changes:
  • true: вернуть массив changes, состоящий из объектов old_val/new_val, описывающих внесенные изменения, включая только документы, которые фактически были обновлены.
  • false: не возвращать массив changes (по умолчанию).
  • "always": вести себя как true, но включать все документы, которые команда пыталась обновить, независимо от того, было ли обновление успешным. (Это было поведение true до версии 2.0.)
• conflict: Определение обработки вставки документов с тем же первичным ключом, что и у существующих записей. Существует три встроенных метода: "error", "replace" или "update"; альтернативно, вы можете предоставить функцию разрешения конфликтов.
  • "error": Не вставлять новый документ и записывать конфликт как ошибку. Это значение по умолчанию.
  • "replace": Заменить старый документ целиком новым.
  • "update": Обновить поля старого документа полями нового.
  • (id, oldDoc, newDoc) -> resolvedDoc: функция, которая принимает в качестве аргументов id, старый и новый документы и возвращает документ, который будет вставлен вместо конфликтующего.
• ignore_write_hook: Если true, и если у пользователя есть разрешение config, игнорирует любой write hook, вставляя документ без изменений.

Если return_changes установлено на true или "always", массив changes будет следовать тому же порядку, что и вставляемые документы. У документов в массиве changes, для которых возникла ошибка (например, конфликт ключей), будет третье поле error, содержащее объяснение ошибки.

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

• inserted: количество успешно вставленных документов.
• replaced: количество обновленных документов, когда conflict установлено на "replace" или "update".
• unchanged: количество документов, поля которых идентичны полям существующих документов с тем же первичным ключом, когда conflict установлено на "replace" или "update".
• errors: количество ошибок, возникших при выполнении операции вставки.
• first_error: Если возникли ошибки, содержит текст первой ошибки.
• deleted и skipped: 0 для операции вставки.
• generated_keys: список сгенерированных первичных ключей для вставленных документов, первичные ключи которых не были указаны (до 100 000).
• warnings: если поле generated_keys обрезано, вы получите предупреждение «Слишком много сгенерированных ключей (<X>), массив усечен до 100000.».
• changes: если returnChanges установлено на true, это будет массив объектов, по одному для каждого объекта, затронутого операцией insert. Каждый объект будет иметь два ключа: {new_val: <new value>, old_val: null}.

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

Пример: Вставить документ в таблицу posts.

r.table("posts").insert(
    r.hashMap("id", 1)
     .with("title", "Lorem ipsum")
     .with("content", "Dolor sit amet")
).run(conn);

Результат будет:

{
    "deleted": 0,
    "errors": 0,
    "inserted": 1,
    "replaced": 0,
    "skipped": 0,
    "unchanged": 0
}

Пример: Вставить документ без определения первичного ключа в таблицу posts, где первичный ключ — id.

r.table("posts").insert(
    r.hashMap("title", "Lorem ipsum")
     .with("content", "Dolor sit amet")
).run(conn);

RethinkDB сгенерирует первичный ключ и вернёт его в generated_keys.

{
    "deleted": 0,
    "errors": 0,
    "generated_keys": [
        "dd782b64-70a7-43e4-b65e-dd14ae61d947"
    ],
    "inserted": 1,
    "replaced": 0,
    "skipped": 0,
    "unchanged": 0
}

Извлечь только что вставленный документ с помощью:

r.table("posts").get("dd782b64-70a7-43e4-b65e-dd14ae61d947").run(conn);

И вы получите:

{
    "id": "dd782b64-70a7-43e4-b65e-dd14ae61d947",
    "title": "Lorem ipsum",
    "content": "Dolor sit amet",
}

Пример: Вставить несколько документов в таблицу users.

r.table("users").insert(r.array(
    r.hashMap("id", "william").with("email", "william@rethinkdb.com"),
    r.hashMap("id", "lara").with("email", "lara@rethinkdb.com")
)).run(conn);

Пример: Вставить документ в таблицу users, заменяя документ, если он уже существует.

r.table("users").insert(
    r.hashMap("id", "william").with("email", "william@rethinkdb.com")
).optArg("conflict", "replace").run(conn);

Пример: Скопировать документы из posts в postsBackup.

r.table("postsBackup").insert(r.table("posts")).run(conn);

Пример: Получить копию вставленного документа (с его сгенерированным первичным ключом).

r.table("posts").insert(
    r.hashMap("title", "Lorem ipsum")
     .with("content", "Dolor sit amet")
).optArg("return_changes", true).run(conn);

Результат будет

{
    "deleted": 0,
    "errors": 0,
    "generated_keys": [
        "dd782b64-70a7-43e4-b65e-dd14ae61d947"
    ],
    "inserted": 1,
    "replaced": 0,
    "skipped": 0,
    "unchanged": 0,
    "changes": [
        {
            "old_val": null,
            "new_val": {
                "id": "dd782b64-70a7-43e4-b65e-dd14ae61d947",
                "title": "Lorem ipsum",
                "content": "Dolor sit amet"
            }
        }
    ]
}

Пример: Предоставление функции разрешения конфликтов, которая конкатенирует содержимое заметок в случае конфликта.

// assume newMemos is a list of memo documents to insert
r.table("memos").insert(new_memos).optArg("conflict",
    (id, old_doc, new_doc) -> new_doc.merge(
        r.hashMap(content, old_doc.g("content").add("\n")
                  .add(new_doc.g("content")))
    )
).run(conn);