Zum Inhalt springen
DuckDBDuckDBDuckDB
Deutsch

Prepared Statements

Ein Prepared Statement ist eine parametrisierte Abfrage. Die Abfrage wird mit Fragezeichen (?) oder Dollar-Symbolen ($1) vorbereitet, die die Parameter der Abfrage anzeigen. Anschließend können Werte an diese Parameter gebunden werden, wonach das Prepared Statement mit diesen Parametern ausgeführt werden kann. Eine einzelne Abfrage kann einmal vorbereitet und viele Male ausgeführt werden.

Prepared Statements sind nützlich, um:

  • Parameter einfach an Funktionen zu übergeben und dabei String-Konkatenation/SQL-Injection-Angriffe zu vermeiden.
  • Abfragen zu beschleunigen, die viele Male mit unterschiedlichen Parametern ausgeführt werden.

DuckDB unterstützt Prepared Statements in der C-API mit der Methode duckdb_prepare. Die Funktionsfamilie duckdb_bind wird verwendet, um Werte für die anschließende Ausführung des Prepared Statements mit duckdb_execute_prepared bereitzustellen. Wenn wir mit dem Prepared Statement fertig sind, kann es mit der Methode duckdb_destroy_prepare aufgeräumt werden.

Beispiel

duckdb_prepared_statement stmt;
duckdb_result result;
if (duckdb_prepare(con, "INSERT INTO integers VALUES ($1, $2)", &stmt) == DuckDBError) {
    // handle error
}


duckdb_bind_int32(stmt, 1, 42); // the parameter index starts counting at 1!
duckdb_bind_int32(stmt, 2, 43);
// NULL as second parameter means no result set is requested
duckdb_execute_prepared(stmt, NULL);
duckdb_destroy_prepare(&stmt);


// we can also query result sets using prepared statements
if (duckdb_prepare(con, "SELECT * FROM integers WHERE i = ?", &stmt) == DuckDBError) {
    // handle error
}
duckdb_bind_int32(stmt, 1, 42);
duckdb_execute_prepared(stmt, &result);


// do something with result


// clean up
duckdb_destroy_result(&result);
duckdb_destroy_prepare(&stmt);

Nach dem Aufruf von duckdb_prepare können die Parameter des Prepared Statements mit duckdb_nparams und duckdb_param_type inspiziert werden. Falls die Vorbereitung fehlschlägt, kann der Fehler über duckdb_prepare_error ermittelt werden.

Es ist nicht erforderlich, dass die Funktionsfamilie duckdb_bind genau dem Parametertyp des Prepared Statements entspricht. Die Werte werden bei Bedarf automatisch in den benötigten Wert gecastet. Beispielsweise funktioniert der Aufruf von duckdb_bind_int8 bei einem Parametertyp DUCKDB_TYPE_INTEGER wie erwartet.

Warnung Verwenden Sie keine Prepared Statements, um große Datenmengen in DuckDB einzufügen. Stattdessen wird empfohlen, den Appender zu verwenden.

API-Referenz im Überblick

duckdb_state duckdb_prepare(duckdb_connection connection, const char *query, duckdb_prepared_statement *out_prepared_statement);
void duckdb_destroy_prepare(duckdb_prepared_statement *prepared_statement);
const char *duckdb_prepare_error(duckdb_prepared_statement prepared_statement);
idx_t duckdb_nparams(duckdb_prepared_statement prepared_statement);
const char *duckdb_parameter_name(duckdb_prepared_statement prepared_statement, idx_t index);
duckdb_type duckdb_param_type(duckdb_prepared_statement prepared_statement, idx_t param_idx);
duckdb_logical_type duckdb_param_logical_type(duckdb_prepared_statement prepared_statement, idx_t param_idx);
duckdb_state duckdb_clear_bindings(duckdb_prepared_statement prepared_statement);
duckdb_statement_type duckdb_prepared_statement_type(duckdb_prepared_statement statement);
idx_t duckdb_prepared_statement_column_count(duckdb_prepared_statement prepared_statement);
const char *duckdb_prepared_statement_column_name(duckdb_prepared_statement prepared_statement, idx_t col_idx);
duckdb_logical_type duckdb_prepared_statement_column_logical_type(duckdb_prepared_statement prepared_statement, idx_t col_idx);
duckdb_type duckdb_prepared_statement_column_type(duckdb_prepared_statement prepared_statement, idx_t col_idx);

duckdb_prepare

Erzeugt ein Prepared-Statement-Objekt aus einer Abfrage.

Beachten Sie, dass das Prepared Statement nach dem Aufruf von duckdb_prepare immer mit duckdb_destroy_prepare zerstört werden sollte, auch wenn die Vorbereitung fehlschlägt.

Falls die Vorbereitung fehlschlägt, kann duckdb_prepare_error aufgerufen werden, um den Grund des Fehlers zu ermitteln.

Syntax
duckdb_state duckdb_prepare(
  duckdb_connection connection,
  const char *query,
  duckdb_prepared_statement *out_prepared_statement
);
Parameter
  • connection: Das Verbindungsobjekt
  • query: Die vorzubereitende SQL-Abfrage
  • out_prepared_statement: Das resultierende Prepared-Statement-Objekt
Rückgabewert

DuckDBSuccess bei Erfolg oder DuckDBError bei Fehler.


duckdb_destroy_prepare

Schließt das Prepared Statement und gibt den gesamten für das Statement allokierten Speicher frei.

Syntax
void duckdb_destroy_prepare(
  duckdb_prepared_statement *prepared_statement
);
Parameter
  • prepared_statement: Das zu zerstörende Prepared Statement.

duckdb_prepare_error

Gibt die mit dem angegebenen Prepared Statement verbundene Fehlermeldung zurück. Wenn das Prepared Statement keine Fehlermeldung hat, wird stattdessen nullptr zurückgegeben.

Die Fehlermeldung sollte nicht freigegeben werden. Sie wird freigegeben, wenn duckdb_destroy_prepare aufgerufen wird.

Syntax
const char *duckdb_prepare_error(
  duckdb_prepared_statement prepared_statement
);
Parameter
  • prepared_statement: Das Prepared Statement, von dem der Fehler ermittelt wird.
Rückgabewert

Die Fehlermeldung oder nullptr, wenn keine vorhanden ist.


duckdb_nparams

Gibt die Anzahl der Parameter zurück, die dem angegebenen Prepared Statement übergeben werden können.

Gibt 0 zurück, wenn die Abfrage nicht erfolgreich vorbereitet wurde.

Syntax
idx_t duckdb_nparams(
  duckdb_prepared_statement prepared_statement
);
Parameter
  • prepared_statement: Das Prepared Statement, für das die Anzahl der Parameter ermittelt wird.

duckdb_parameter_name

Gibt den Namen zurück, der zur Identifikation des Parameters verwendet wird. Die zurückgegebene Zeichenkette sollte mit duckdb_free freigegeben werden.

Gibt NULL zurück, wenn der Index außerhalb des gültigen Bereichs für das bereitgestellte Prepared Statement liegt.

Syntax
const char *duckdb_parameter_name(
  duckdb_prepared_statement prepared_statement,
  idx_t index
);
Parameter
  • prepared_statement: Das Prepared Statement, von dem der Parametername ermittelt wird.

duckdb_param_type

Gibt den Parametertyp für den Parameter am angegebenen Index zurück.

Gibt DUCKDB_TYPE_INVALID zurück, wenn der Parameterindex außerhalb des gültigen Bereichs liegt oder das Statement nicht erfolgreich vorbereitet wurde.

Syntax
duckdb_type duckdb_param_type(
  duckdb_prepared_statement prepared_statement,
  idx_t param_idx
);
Parameter
  • prepared_statement: Das Prepared Statement.
  • param_idx: Der Parameterindex.
Rückgabewert

Der Parametertyp


duckdb_param_logical_type

Gibt den logischen Typ für den Parameter am angegebenen Index zurück.

Gibt nullptr zurück, wenn der Parameterindex außerhalb des gültigen Bereichs liegt oder das Statement nicht erfolgreich vorbereitet wurde.

Der Rückgabetyp dieses Aufrufs sollte mit duckdb_destroy_logical_type zerstört werden.

Syntax
duckdb_logical_type duckdb_param_logical_type(
  duckdb_prepared_statement prepared_statement,
  idx_t param_idx
);
Parameter
  • prepared_statement: Das Prepared Statement.
  • param_idx: Der Parameterindex.
Rückgabewert

Der logische Typ des Parameters


duckdb_clear_bindings

Löscht die an das Prepared Statement gebundenen Parameter.

Syntax
duckdb_state duckdb_clear_bindings(
  duckdb_prepared_statement prepared_statement
);

duckdb_prepared_statement_type

Gibt den Statement-Typ des auszuführenden Statements zurück

Syntax
duckdb_statement_type duckdb_prepared_statement_type(
  duckdb_prepared_statement statement
);
Parameter
  • statement: Das Prepared Statement.
Rückgabewert

duckdb_statement_type-Wert oder DUCKDB_STATEMENT_TYPE_INVALID


duckdb_prepared_statement_column_count

Gibt die Anzahl der Spalten im Ergebnis des Prepared Statements zurück. Wenn einer der Spaltentypen ungültig ist, ist das Ergebnis 1.

Syntax
idx_t duckdb_prepared_statement_column_count(
  duckdb_prepared_statement prepared_statement
);
Parameter
  • prepared_statement: Das Prepared Statement.
Rückgabewert

Die Anzahl der Spalten im Ergebnis des Prepared Statements.


duckdb_prepared_statement_column_name

Gibt den Namen der angegebenen Spalte des Ergebnisses des prepared_statement zurück. Die zurückgegebene Zeichenkette sollte mit duckdb_free freigegeben werden.

Gibt nullptr zurück, wenn die Spalte außerhalb des gültigen Bereichs liegt.

Syntax
const char *duckdb_prepared_statement_column_name(
  duckdb_prepared_statement prepared_statement,
  idx_t col_idx
);
Parameter
  • prepared_statement: Das Prepared Statement.
  • col_idx: Der Spaltenindex.
Rückgabewert

Der Spaltenname der angegebenen Spalte.


duckdb_prepared_statement_column_logical_type

Gibt den Spaltentyp der angegebenen Spalte des Ergebnisses des prepared_statement zurück.

Gibt DUCKDB_TYPE_INVALID zurück, wenn die Spalte außerhalb des gültigen Bereichs liegt. Der Rückgabetyp dieses Aufrufs sollte mit duckdb_destroy_logical_type zerstört werden.

Syntax
duckdb_logical_type duckdb_prepared_statement_column_logical_type(
  duckdb_prepared_statement prepared_statement,
  idx_t col_idx
);
Parameter
  • prepared_statement: Das Prepared Statement, von dem der Spaltentyp geholt wird.
  • col_idx: Der Spaltenindex.
Rückgabewert

Der logische Typ der angegebenen Spalte.


duckdb_prepared_statement_column_type

Gibt den Spaltentyp der angegebenen Spalte des Ergebnisses des prepared_statement zurück.

Gibt DUCKDB_TYPE_INVALID zurück, wenn die Spalte außerhalb des gültigen Bereichs liegt.

Syntax
duckdb_type duckdb_prepared_statement_column_type(
  duckdb_prepared_statement prepared_statement,
  idx_t col_idx
);
Parameter
  • prepared_statement: Das Prepared Statement, von dem der Spaltentyp geholt wird.
  • col_idx: Der Spaltenindex.
Rückgabewert

Der Typ der angegebenen Spalte.


Dies ist eine inoffizielle Website und nicht mit DuckDB verbunden. Offizielle Seite:duckdb.org.duckdb.ubitools.com · Übersetzt und erstellt mit Astro und daisyUI