Data Chunks

Data Chunks stellen einen horizontalen Ausschnitt einer Tabelle dar. Sie enthalten eine Anzahl von Vektoren, die jeweils bis zu VECTOR_SIZE Zeilen aufnehmen können. Die Vektorgröße kann über die Funktion duckdb_vector_size ermittelt werden und ist konfigurierbar, beträgt aber üblicherweise 2048.

Data Chunks und Vektoren sind das, was DuckDB intern zum Speichern und Darstellen von Daten verwendet. Deshalb ist die Data-Chunk-Schnittstelle der effizienteste Weg, mit DuckDB zu interagieren. Beachten Sie jedoch, dass die korrekte Nutzung der Data-Chunk-API Kenntnisse über das interne Vektorformat von DuckDB voraussetzt.

Data Chunks können auf zwei Arten verwendet werden:

• Daten lesen: Data Chunks können über die Methode duckdb_fetch_chunk aus Abfrageergebnissen bezogen werden oder als Eingabe einer benutzerdefinierten Funktion dienen. In diesem Fall können die Vektor-Methoden verwendet werden, um einzelne Werte zu lesen.
• Daten schreiben: Data Chunks können mit duckdb_create_data_chunk erzeugt werden. Der Data Chunk kann anschließend mit Werten gefüllt und in duckdb_append_data_chunk verwendet werden, um Daten in die Datenbank zu schreiben.

Die primäre Art, mit Data Chunks zu arbeiten, besteht darin, die internen Vektoren des Data Chunks über die Methode duckdb_data_chunk_get_vector zu holen. Anschließend können die Vektor-Methoden verwendet werden, um aus den einzelnen Vektoren zu lesen oder in sie zu schreiben.

API-Referenz im Überblick

duckdb_data_chunk duckdb_create_data_chunk(duckdb_logical_type *types, idx_t column_count);
void duckdb_destroy_data_chunk(duckdb_data_chunk *chunk);
void duckdb_data_chunk_reset(duckdb_data_chunk chunk);
idx_t duckdb_data_chunk_get_column_count(duckdb_data_chunk chunk);
duckdb_vector duckdb_data_chunk_get_vector(duckdb_data_chunk chunk, idx_t col_idx);
idx_t duckdb_data_chunk_get_size(duckdb_data_chunk chunk);
void duckdb_data_chunk_set_size(duckdb_data_chunk chunk, idx_t size);

duckdb_create_data_chunk

Erzeugt einen leeren Data Chunk mit den angegebenen Spaltentypen. Das Ergebnis muss mit duckdb_destroy_data_chunk zerstört werden.

Syntax

duckdb_data_chunk duckdb_create_data_chunk(
  duckdb_logical_type *types,
  idx_t column_count
);

Parameter

• types: Ein Array von Spaltentypen. Spaltentypen dürfen keine ANY- und INVALID-Typen enthalten.
• column_count: Die Anzahl der Spalten.

Rückgabewert

Der Data Chunk.

duckdb_destroy_data_chunk

Zerstört den Data Chunk und gibt den gesamten für diesen Chunk allokierten Speicher frei.

Syntax

void duckdb_destroy_data_chunk(
  duckdb_data_chunk *chunk
);

Parameter

• chunk: Der zu zerstörende Data Chunk.

duckdb_data_chunk_reset

Setzt einen Data Chunk zurück, indem die Validity-Masks geleert und die Kardinalität des Data Chunks auf 0 gesetzt wird. Nach dem Aufruf dieser Methode müssen Sie duckdb_vector_get_validity und duckdb_vector_get_data aufrufen, um aktuelle Daten- und Validity-Zeiger zu erhalten.

Syntax

void duckdb_data_chunk_reset(
  duckdb_data_chunk chunk
);

Parameter

• chunk: Der zurückzusetzende Data Chunk.

duckdb_data_chunk_get_column_count

Ermittelt die Anzahl der Spalten in einem Data Chunk.

Syntax

idx_t duckdb_data_chunk_get_column_count(
  duckdb_data_chunk chunk
);

Parameter

• chunk: Der Data Chunk, aus dem die Daten gelesen werden

Rückgabewert

Die Anzahl der Spalten im Data Chunk

duckdb_data_chunk_get_vector

Ermittelt den Vektor am angegebenen Spaltenindex im Data Chunk.

Der Zeiger auf den Vektor bleibt gültig, solange der Chunk lebt. Er muss NICHT zerstört werden.

Syntax

duckdb_vector duckdb_data_chunk_get_vector(
  duckdb_data_chunk chunk,
  idx_t col_idx
);

Parameter

• chunk: Der Data Chunk, aus dem die Daten gelesen werden

Rückgabewert

Der Vektor

duckdb_data_chunk_get_size

Ermittelt die aktuelle Anzahl der Tupel in einem Data Chunk.

Syntax

idx_t duckdb_data_chunk_get_size(
  duckdb_data_chunk chunk
);

Parameter

• chunk: Der Data Chunk, aus dem die Daten gelesen werden

Rückgabewert

Die Anzahl der Tupel im Data Chunk

duckdb_data_chunk_set_size

Setzt die aktuelle Anzahl der Tupel in einem Data Chunk.

Syntax

void duckdb_data_chunk_set_size(
  duckdb_data_chunk chunk,
  idx_t size
);

Parameter

• chunk: Der Data Chunk, in dem die Größe gesetzt wird
• size: Die Anzahl der Tupel im Data Chunk