Команда 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, new_doc| resolved_doc }: функция, которая получает в качестве аргументов идентификатор, старый и новый документы и возвращает документ, который будет вставлен вместо конфликтного.
• ignore_write_hook: Если true, и если у пользователя есть разрешение на конфигурацию, игнорирует любой write hook, вставляя документ без изменений.

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

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

• 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 => nil}.

Операции записи 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 => nil,
            :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)