Appender

Der Appender eignet sich zum Laden großer Datenmengen in eine DuckDB-Datenbank. Er ist derzeit in den C-, C++-, Go-, Java- und Rust-APIs verfügbar. Der Appender ist an eine Verbindung gebunden und verwendet den Transaktionskontext dieser Verbindung. Ein Appender schreibt immer in genau eine Tabelle der Datenbankdatei.

In der C++-API funktioniert der Appender wie folgt:

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

Die Funktion AppendRow ist der einfachste Weg, Daten anzuhängen. Über rekursive Templates können Sie alle Werte einer Zeile in einem einzigen Aufruf übergeben:

appender.AppendRow(1, "Mark");

Zeilen lassen sich auch einzeln mit BeginRow, EndRow und Append aufbauen. Intern macht AppendRow dasselbe und hat daher dieselben Leistungseigenschaften.

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

Werte, die dem Appender übergeben werden, werden aus Leistungsgründen zwischengespeichert, bevor sie in das Datenbanksystem geschrieben werden. Während des Anhängens sind die Zeilen daher möglicherweise nicht sofort sichtbar. Der Cache wird automatisch geleert, wenn der Appender den Gültigkeitsbereich verlässt oder wenn appender.Close() aufgerufen wird. Der Cache lässt sich auch manuell mit appender.Flush() leeren. Nach Flush oder Close sind alle Daten im Datenbanksystem geschrieben.

Datum, Zeit und Zeitstempel

Zahlen und Zeichenketten sind weitgehend selbsterklärend; Datum, Zeit und Zeitstempel brauchen etwas Erklärung. Sie können direkt mit den Methoden von duckdb::Date, duckdb::Time oder duckdb::Timestamp angehängt werden. Alternativ geht das über den internen Typ duckdb::Value, das verursacht jedoch zusätzlichen Overhead und sollte nach Möglichkeit vermieden werden.

Ein kurzes Beispiel:

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)
);

Commit-Häufigkeit

Standardmäßig committet der Appender alle 204.800 Zeilen. Sie können das ändern, indem Sie explizit Transaktionen verwenden und Ihre AppendRow-Aufrufe mit BEGIN TRANSACTION und COMMIT umschließen.

Behandlung von Constraint-Verletzungen

Trifft der Appender auf einen PRIMARY KEY-Konflikt oder eine Verletzung eines UNIQUE-Constraints, schlägt er fehl und liefert den folgenden Fehler:

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

In diesem Fall schlägt der gesamte Append-Vorgang fehl, und es werden keine Zeilen eingefügt.

Appender-Unterstützung in anderen Clients

Der Appender ist auch in den folgenden Client-APIs verfügbar: