Zum Inhalt springen
DuckDBDuckDBDuckDB
Deutsch

Abfrage

Die Methode duckdb_query ermöglicht es, SQL-Abfragen in DuckDB aus C auszuführen. Diese Methode nimmt zwei Parameter entgegen: eine (null-terminierte) SQL-Abfragezeichenkette und einen duckdb_result-Ergebniszeiger. Der Ergebniszeiger darf NULL sein, wenn die Anwendung nicht am Resultset interessiert ist oder die Abfrage kein Ergebnis erzeugt. Nachdem das Ergebnis verarbeitet wurde, sollte die Methode duckdb_destroy_result verwendet werden, um das Ergebnis aufzuräumen.

Elemente können mit verschiedenen Methoden aus dem Objekt duckdb_result extrahiert werden. duckdb_column_count kann verwendet werden, um die Anzahl der Spalten zu ermitteln. duckdb_column_name und duckdb_column_type können verwendet werden, um Namen und Typen einzelner Spalten zu ermitteln.

Beispiel

duckdb_state state;
duckdb_result result;


// create a table
state = duckdb_query(con, "CREATE TABLE integers (i INTEGER, j INTEGER);", NULL);
if (state == DuckDBError) {
    // handle error
}
// insert three rows into the table
state = duckdb_query(con, "INSERT INTO integers VALUES (3, 4), (5, 6), (7, NULL);", NULL);
if (state == DuckDBError) {
    // handle error
}
// query rows again
state = duckdb_query(con, "SELECT * FROM integers", &result);
if (state == DuckDBError) {
    // handle error
}
// handle the result
// ...


// destroy the result after we are done with it
duckdb_destroy_result(&result);

Wertextraktion

Werte können entweder mit der Funktion duckdb_fetch_chunk oder mit den Convenience-Funktionen duckdb_value extrahiert werden. Die Funktion duckdb_fetch_chunk liefert Ihnen Data Chunks direkt im nativen Array-Format von DuckDB und kann daher sehr schnell sein. Die Funktionen duckdb_value führen Bounds- und Typprüfungen durch und casten Werte automatisch in den gewünschten Typ. Das macht sie bequemer und einfacher zu verwenden, auf Kosten einer langsameren Ausführung.

Weitere Informationen finden Sie auf der Seite Typen.

Für optimale Leistung verwenden Sie duckdb_fetch_chunk, um Daten aus dem Abfrageergebnis zu extrahieren. Die Funktionen duckdb_value führen interne Typprüfungen, Bounds-Prüfungen und Casts durch, was sie langsamer macht.

duckdb_fetch_chunk

Nachfolgend ein End-to-End-Beispiel, das das obige Ergebnis mit der Funktion duckdb_fetch_chunk im CSV-Format ausgibt. Beachten Sie, dass die Funktion NICHT generisch ist: Wir müssen genau wissen, welche Typen die Ergebnisspalten haben.

duckdb_database db;
duckdb_connection con;
duckdb_open(nullptr, &db);
duckdb_connect(db, &con);


duckdb_result res;
duckdb_query(con, "CREATE TABLE integers (i INTEGER, j INTEGER);", NULL);
duckdb_query(con, "INSERT INTO integers VALUES (3, 4), (5, 6), (7, NULL);", NULL);
duckdb_query(con, "SELECT * FROM integers;", &res);


// iterate until result is exhausted
while (true) {
    duckdb_data_chunk result = duckdb_fetch_chunk(res);
    if (!result) {
        // result is exhausted
        break;
    }
    // get the number of rows from the data chunk
    idx_t row_count = duckdb_data_chunk_get_size(result);
    // get the first column
    duckdb_vector col1 = duckdb_data_chunk_get_vector(result, 0);
    int32_t *col1_data = (int32_t *) duckdb_vector_get_data(col1);
    uint64_t *col1_validity = duckdb_vector_get_validity(col1);


    // get the second column
    duckdb_vector col2 = duckdb_data_chunk_get_vector(result, 1);
    int32_t *col2_data = (int32_t *) duckdb_vector_get_data(col2);
    uint64_t *col2_validity = duckdb_vector_get_validity(col2);


    // iterate over the rows
    for (idx_t row = 0; row < row_count; row++) {
        if (duckdb_validity_row_is_valid(col1_validity, row)) {
            printf("%d", col1_data[row]);
        } else {
            printf("NULL");
        }
        printf(",");
        if (duckdb_validity_row_is_valid(col2_validity, row)) {
            printf("%d", col2_data[row]);
        } else {
            printf("NULL");
        }
        printf("\n");
    }
    duckdb_destroy_data_chunk(&result);
}
// clean-up
duckdb_destroy_result(&res);
duckdb_disconnect(&con);
duckdb_close(&db);

Dies gibt das folgende Ergebnis aus:

3,4
5,6
7,NULL

duckdb_value

Veraltet Die Funktionen duckdb_value sind veraltet und zur Entfernung in einer zukünftigen Version vorgesehen.

Nachfolgend ein Beispiel, das das obige Ergebnis mit der Funktion duckdb_value_varchar im CSV-Format ausgibt. Beachten Sie, dass die Funktion generisch ist: Wir müssen die Typen der einzelnen Ergebnisspalten nicht kennen.

// print the above result to CSV format using `duckdb_value_varchar`
idx_t row_count = duckdb_row_count(&result);
idx_t column_count = duckdb_column_count(&result);
for (idx_t row = 0; row < row_count; row++) {
    for (idx_t col = 0; col < column_count; col++) {
        if (col > 0) printf(",");
        auto str_val = duckdb_value_varchar(&result, col, row);
        printf("%s", str_val);
        duckdb_free(str_val);
   }
   printf("\n");
}

API-Referenz im Überblick

duckdb_state duckdb_query(duckdb_connection connection, const char *query, duckdb_result *out_result);
void duckdb_destroy_result(duckdb_result *result);
const char *duckdb_column_name(duckdb_result *result, idx_t col);
duckdb_type duckdb_column_type(duckdb_result *result, idx_t col);
duckdb_statement_type duckdb_result_statement_type(duckdb_result result);
duckdb_logical_type duckdb_column_logical_type(duckdb_result *result, idx_t col);
duckdb_arrow_options duckdb_result_get_arrow_options(duckdb_result *result);
idx_t duckdb_column_count(duckdb_result *result);
idx_t duckdb_row_count(duckdb_result *result);
idx_t duckdb_rows_changed(duckdb_result *result);
void *duckdb_column_data(duckdb_result *result, idx_t col);
bool *duckdb_nullmask_data(duckdb_result *result, idx_t col);
const char *duckdb_result_error(duckdb_result *result);
duckdb_error_type duckdb_result_error_type(duckdb_result *result);

duckdb_query

Führt eine SQL-Abfrage innerhalb einer Verbindung aus und speichert das vollständige (materialisierte) Ergebnis im Zeiger out_result. Wenn die Abfrage nicht ausgeführt werden kann, wird DuckDBError zurückgegeben und die Fehlermeldung kann durch Aufruf von duckdb_result_error ermittelt werden.

Beachten Sie, dass nach dem Ausführen von duckdb_query duckdb_destroy_result für das Ergebnisobjekt aufgerufen werden muss, auch wenn die Abfrage fehlschlägt, da der im Ergebnis gespeicherte Fehler sonst nicht korrekt freigegeben wird.

Syntax
duckdb_state duckdb_query(
  duckdb_connection connection,
  const char *query,
  duckdb_result *out_result
);
Parameter
  • connection: Die Verbindung, in der die Abfrage ausgeführt wird.
  • query: Die auszuführende SQL-Abfrage.
  • out_result: Das Abfrageergebnis.
Rückgabewert

DuckDBSuccess bei Erfolg oder DuckDBError bei Fehler.


duckdb_destroy_result

Schließt das Ergebnis und gibt den gesamten für dieses Ergebnis allokierten Speicher frei.

Syntax
void duckdb_destroy_result(
  duckdb_result *result
);
Parameter
  • result: Das zu zerstörende Ergebnis.

duckdb_column_name

Gibt den Spaltennamen der angegebenen Spalte zurück. Das Ergebnis muss nicht freigegeben werden; die Spaltennamen werden automatisch zerstört, wenn das Ergebnis zerstört wird.

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

Syntax
const char *duckdb_column_name(
  duckdb_result *result,
  idx_t col
);
Parameter
  • result: Das Ergebnisobjekt, von dem der Spaltenname geholt wird.
  • col: Der Spaltenindex.
Rückgabewert

Der Spaltenname der angegebenen Spalte.


duckdb_column_type

Gibt den Spaltentyp der angegebenen Spalte zurück.

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

Syntax
duckdb_type duckdb_column_type(
  duckdb_result *result,
  idx_t col
);
Parameter
  • result: Das Ergebnisobjekt, von dem der Spaltentyp geholt wird.
  • col: Der Spaltenindex.
Rückgabewert

Der Spaltentyp der angegebenen Spalte.


duckdb_result_statement_type

Gibt den Statement-Typ des ausgeführten Statements zurück

Syntax
duckdb_statement_type duckdb_result_statement_type(
  duckdb_result result
);
Parameter
  • result: Das Ergebnisobjekt, von dem der Statement-Typ geholt wird.
Rückgabewert

duckdb_statement_type-Wert oder DUCKDB_STATEMENT_TYPE_INVALID


duckdb_column_logical_type

Gibt den logischen Spaltentyp der angegebenen Spalte zurück.

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

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

Syntax
duckdb_logical_type duckdb_column_logical_type(
  duckdb_result *result,
  idx_t col
);
Parameter
  • result: Das Ergebnisobjekt, von dem der Spaltentyp geholt wird.
  • col: Der Spaltenindex.
Rückgabewert

Der logische Spaltentyp der angegebenen Spalte.


duckdb_result_get_arrow_options

Gibt die mit dem angegebenen Ergebnis verbundenen Arrow-Optionen zurück. Diese Optionen definieren, wie die Arrow-Arrays/das Schema erzeugt werden sollen.

Syntax
duckdb_arrow_options duckdb_result_get_arrow_options(
  duckdb_result *result
);
Parameter
  • result: Das Ergebnisobjekt, von dem die Arrow-Optionen geholt werden.
Rückgabewert

Die mit dem angegebenen Ergebnis verbundenen Arrow-Optionen. Dies muss mit duckdb_destroy_arrow_options zerstört werden.


duckdb_column_count

Gibt die Anzahl der im Ergebnisobjekt vorhandenen Spalten zurück.

Syntax
idx_t duckdb_column_count(
  duckdb_result *result
);
Parameter
  • result: Das Ergebnisobjekt.
Rückgabewert

Die Anzahl der im Ergebnisobjekt vorhandenen Spalten.


duckdb_row_count

Warnung Hinweis zur Veraltung. Diese Methode ist zur Entfernung in einer zukünftigen Version vorgesehen.

Gibt die Anzahl der im Ergebnisobjekt vorhandenen Zeilen zurück.

Syntax
idx_t duckdb_row_count(
  duckdb_result *result
);
Parameter
  • result: Das Ergebnisobjekt.
Rückgabewert

Die Anzahl der im Ergebnisobjekt vorhandenen Zeilen.


duckdb_rows_changed

Gibt die Anzahl der durch die im Ergebnis gespeicherte Abfrage geänderten Zeilen zurück. Dies ist nur für INSERT/UPDATE/DELETE- Abfragen relevant. Bei anderen Abfragen ist rows_changed 0.

Syntax
idx_t duckdb_rows_changed(
  duckdb_result *result
);
Parameter
  • result: Das Ergebnisobjekt.
Rückgabewert

Die Anzahl der geänderten Zeilen.


duckdb_column_data

Veraltet Diese Methode ist veraltet. Verwenden Sie stattdessen bevorzugt duckdb_result_get_chunk.

Gibt die Daten einer bestimmten Spalte eines Ergebnisses im spaltenorientierten Format zurück.

Die Funktion gibt ein dichtes Array zurück, das die Ergebnisdaten enthält. Der genaue im Array gespeicherte Typ hängt vom entsprechenden duckdb_type ab (wie von duckdb_column_type bereitgestellt). Den genauen Typ, über den auf die Daten zugegriffen werden sollte, finden Sie in den Kommentaren im Typen-Abschnitt oder im Enum DUCKDB_TYPE.

Beispielsweise kann auf Zeilen einer Spalte vom Typ DUCKDB_TYPE_INTEGER wie folgt zugegriffen werden:

int32_t *data = (int32_t *) duckdb_column_data(&result, 0);
printf("Data for row %d: %d\n", row, data[row]);
Syntax
void *duckdb_column_data(
  duckdb_result *result,
  idx_t col
);
Parameter
  • result: Das Ergebnisobjekt, von dem die Spaltendaten geholt werden.
  • col: Der Spaltenindex.
Rückgabewert

Die Spaltendaten der angegebenen Spalte.


duckdb_nullmask_data

Veraltet Diese Methode ist veraltet. Verwenden Sie stattdessen bevorzugt duckdb_result_get_chunk.

Gibt die Nullmask einer bestimmten Spalte eines Ergebnisses im spaltenorientierten Format zurück. Die Nullmask zeigt für jede Zeile an, ob die entsprechende Zeile NULL ist. Wenn eine Zeile NULL ist, sind die Werte im von duckdb_column_data bereitgestellten Array undefiniert.

int32_t *data = (int32_t *) duckdb_column_data(&result, 0);
bool *nullmask = duckdb_nullmask_data(&result, 0);
if (nullmask[row]) {
    printf("Data for row %d: NULL\n", row);
} else {
    printf("Data for row %d: %d\n", row, data[row]);
}
Syntax
bool *duckdb_nullmask_data(
  duckdb_result *result,
  idx_t col
);
Parameter
  • result: Das Ergebnisobjekt, von dem die Nullmask geholt wird.
  • col: Der Spaltenindex.
Rückgabewert

Die Nullmask der angegebenen Spalte.


duckdb_result_error

Gibt die im Ergebnis enthaltene Fehlermeldung zurück. Der Fehler wird nur gesetzt, wenn duckdb_query DuckDBError zurückgibt.

Das Ergebnis dieser Funktion darf nicht freigegeben werden. Es wird aufgeräumt, wenn duckdb_destroy_result aufgerufen wird.

Syntax
const char *duckdb_result_error(
  duckdb_result *result
);
Parameter
  • result: Das Ergebnisobjekt, von dem der Fehler geholt wird.
Rückgabewert

Der Fehler des Ergebnisses.


duckdb_result_error_type

Gibt den im Ergebnis enthaltenen Fehler-Typ zurück. Der Fehler wird nur gesetzt, wenn duckdb_query DuckDBError zurückgibt.

Syntax
duckdb_error_type duckdb_result_error_type(
  duckdb_result *result
);
Parameter
  • result: Das Ergebnisobjekt, von dem der Fehler geholt wird.
Rückgabewert

Der Fehler-Typ des Ergebnisses.


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