Приложение

Приложение может использоваться для загрузки больших объёмов данных в базу данных DuckDB. Оно в настоящее время доступно в API C, C++, Go, Java и Rust. Приложение привязано к соединению и использует контекст транзакции этого соединения при добавлении данных. Приложение всегда добавляет данные в одну таблицу в файле базы данных.

В C++ API, приложение работает следующим образом:

DuckDB db;
Connection con(db);
// create the table
con.Query("CREATE TABLE people (id INTEGER, name VARCHAR)");
// initialize the appender
Appender appender(con, "people");

Функция AppendRow является наиболее простым способом добавления данных. Она использует рекурсивные шаблоны, позволяющие поместить все значения одной строки в один вызов функции, как показано ниже:

appender.AppendRow(1, "Mark");

Строки также можно индивидуально создавать, используя методы BeginRow, EndRow и Append. Это делается внутри AppendRow, и поэтому обладает теми же характеристиками производительности.

appender.BeginRow();
appender.Append<int32_t>(2);
appender.Append<string>("Hannes");
appender.EndRow();

Все значения, добавленные в приложение, кэшируются перед вставкой в систему базы данных по соображениям производительности. Это означает, что во время добавления данные в системе могут быть не сразу видны. Кэш автоматически очищается, когда приложение выходит из области видимости или когда вызывается appender.Close(). Кэш также можно очистить вручную, используя метод appender.Flush(). После вызова Flush или Close все данные были записаны в систему базы данных.

Дата, время и метки времени

Хотя числа и строки довольно понятны, даты, времена и метки времени требуют некоторого объяснения. Их можно непосредственно добавить, используя методы, предоставленные duckdb::Date, duckdb::Time или duckdb::Timestamp. Их также можно добавить, используя внутренний тип duckdb::Value, однако это добавляет некоторые дополнительные накладные расходы и следует избегать, если это возможно.

Ниже приведен краткий пример:

con.Query("CREATE TABLE dates (d DATE, t TIME, ts TIMESTAMP)");
Appender appender(con, "dates");

// construct the values using the Date/Time/Timestamp types
// (this is the most efficient approach)
appender.AppendRow(
    Date::FromDate(1992, 1, 1),
    Time::FromTime(1, 1, 1, 0),
    Timestamp::FromDatetime(Date::FromDate(1992, 1, 1), Time::FromTime(1, 1, 1, 0))
);
// construct duckdb::Value objects
appender.AppendRow(
    Value::DATE(1992, 1, 1),
    Value::TIME(1, 1, 1, 0),
    Value::TIMESTAMP(1992, 1, 1, 1, 1, 1, 0)
);

Частота коммитов

По умолчанию приложение выполняет коммит каждые 204 800 строк. Вы можете изменить это, явно используя транзакции и окружая ваши партии вызовов AppendRow операторами BEGIN TRANSACTION и COMMIT.

Обработка нарушений ограничений

Если приложение сталкивается с конфликтом PRIMARY KEY или нарушением ограничения UNIQUE, оно завершается ошибкой:

Constraint Error: PRIMARY KEY or UNIQUE constraint violated: duplicate key "..."

В этом случае вся операция добавления данных завершается неудачей, и ни одна строка не вставляется.

Поддержка приложения в других клиентах

Приложение также доступно в следующих API клиентов: