Команда ReQL: insert

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

table.insert(object | [object1, object2, ...][, durability="hard", return_changes=False, conflict="error", ignore_write_hook=False]) → object

Описание

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

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

• 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": Обновить поля старого документа полями из нового.
  • lambda id, old_doc, newdoc: resolved_doc: функция, которая получает id, старый и новый документы в качестве аргументов и возвращает документ, который будет вставлен вместо конфликтующего.
• ignore_write_hook: Если True, и если у пользователя есть разрешение конфигурации, игнорирует любой 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: если return_changes установлено на True, это будет массив объектов, по одному на каждый объект, затронутый операцией insert. Каждый объект будет иметь два ключа: {"new_val": <new value>, "old_val": None}.

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

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

r.table("posts").insert({
    "id": 1,
    "title": "Lorem ipsum",
    "content": "Dolor sit amet"
}).run(conn)

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

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

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

r.table("posts").insert({
    "title": "Lorem ipsum",
    "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([
    {"id": "william", "email": "william@rethinkdb.com"},
    {"id": "lara", "email": "lara@rethinkdb.com"}
]).run(conn)

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

r.table("users").insert(
    {"id": "william", "email": "william@rethinkdb.com"},
    conflict="replace"
).run(conn)

Пример: Копирование документов из posts в posts_backup.

r.table("posts_backup").insert( r.table("posts") ).run(conn)

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

r.table("posts").insert(
    {"title": "Lorem ipsum", "content": "Dolor sit amet"},
    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": None,
            "new_val": {
                "id": "dd782b64-70a7-43e4-b65e-dd14ae61d947",
                "title": "Lorem ipsum",
                "content": "Dolor sit amet"
            }
        }
    ]
}

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

# assume new_memos is a list of memo documents to insert
r.table('memos').insert(new_memos, conflict=
    lambda id, old_doc, new_doc: new_doc.merge({content: old_doc['content'] + "\n" + new_doc['content']})
).run(conn)