Команда ReQL: insert

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

table.insert(object | [object1, object2, ...][, {durability: "hard", returnChanges: false, conflict: "error", ignoreWriteHook: false}]) → object

Описание

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

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

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

Если returnChanges установлено на 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: если returnChanges установлено на true, это будет массив объектов, по одному на каждый объект, затронутый операцией insert. Каждый объект будет иметь два ключа: {new_val: <new value>, old_val: null}.

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

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

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

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

{
    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, callback)

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, callback)

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

{
    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, callback)

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

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

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

r.table("postsBackup").insert(r.table("posts")).run(conn, callback)

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

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

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

{
    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(newMemos, {conflict: function(id, oldDoc, newDoc) {
    return newDoc.merge(
        {content: oldDoc('content').add("\n").add(newDoc('content'))}
    );
}}).run(conn, callback)