Vektoren

Vektoren stellen einen horizontalen Ausschnitt einer Spalte dar. Sie halten eine Anzahl von Werten eines bestimmten Typs, ähnlich einem Array. Vektoren sind die zentrale Datendarstellung in DuckDB. Vektoren werden typischerweise in Datenchunks gespeichert.

Die Schnittstellen für Vektoren und Datenchunks sind der effizienteste Weg, mit DuckDB zu interagieren, und ermöglichen die höchste Leistung. Die Schnittstellen sind jedoch auch schwierig zu verwenden, und bei ihrer Nutzung ist Vorsicht geboten.

Vektorformat

Vektoren sind Arrays eines bestimmten Datentyps. Der logische Typ eines Vektors kann mit duckdb_vector_get_column_type ermittelt werden. Die Type-ID des logischen Typs kann anschließend mit duckdb_get_type_id ermittelt werden.

Vektoren selbst haben keine Größen. Stattdessen hat der übergeordnete Datenchunk eine Größe (die über duckdb_data_chunk_get_size ermittelt werden kann). Alle Vektoren, die zu einem Datenchunk gehören, haben dieselbe Größe.

Primitive Typen

Für primitive Typen kann das zugrunde liegende Array mit der Methode duckdb_vector_get_data ermittelt werden. Das Array kann anschließend mit dem richtigen nativen Typ angesprochen werden. Nachfolgend eine Tabelle mit der Abbildung von duckdb_type auf den nativen Typ des Arrays.

duckdb_type	NativeType
DUCKDB_TYPE_BOOLEAN	bool
DUCKDB_TYPE_TINYINT	int8_t
DUCKDB_TYPE_SMALLINT	int16_t
DUCKDB_TYPE_INTEGER	int32_t
DUCKDB_TYPE_BIGINT	int64_t
DUCKDB_TYPE_UTINYINT	uint8_t
DUCKDB_TYPE_USMALLINT	uint16_t
DUCKDB_TYPE_UINTEGER	uint32_t
DUCKDB_TYPE_UBIGINT	uint64_t
DUCKDB_TYPE_FLOAT	float
DUCKDB_TYPE_DOUBLE	double
DUCKDB_TYPE_TIMESTAMP	duckdb_timestamp
DUCKDB_TYPE_DATE	duckdb_date
DUCKDB_TYPE_TIME	duckdb_time
DUCKDB_TYPE_INTERVAL	duckdb_interval
DUCKDB_TYPE_HUGEINT	duckdb_hugeint
DUCKDB_TYPE_UHUGEINT	duckdb_uhugeint
DUCKDB_TYPE_VARCHAR	duckdb_string_t
DUCKDB_TYPE_BLOB	duckdb_string_t
DUCKDB_TYPE_TIMESTAMP_S	duckdb_timestamp
DUCKDB_TYPE_TIMESTAMP_MS	duckdb_timestamp
DUCKDB_TYPE_TIMESTAMP_NS	duckdb_timestamp
DUCKDB_TYPE_UUID	duckdb_hugeint
DUCKDB_TYPE_TIME_TZ	duckdb_time_tz
DUCKDB_TYPE_TIMESTAMP_TZ	duckdb_timestamp

NULL-Werte

Jeder Wert in einem Vektor kann NULL sein. Wenn ein Wert NULL ist, sind die Werte im primären Array an diesem Index undefiniert (und können uninitialisiert sein). Die Gültigkeitsmaske ist eine Bitmaske aus uint64_t-Elementen. Für jeweils 64 Werte im Vektor existiert ein uint64_t-Element (aufgerundet). In der Gültigkeitsmaske ist das Bit auf 1 gesetzt, wenn der Wert gültig ist, oder auf 0, wenn der Wert ungültig ist (d. h. NULL).

Die Bits der Bitmaske können direkt gelesen werden, oder die langsamere Hilfsmethode duckdb_validity_row_is_valid kann verwendet werden, um zu prüfen, ob ein Wert NULL ist.

duckdb_vector_get_validity gibt einen Zeiger auf die Gültigkeitsmaske zurück. Beachten Sie, dass diese Funktion möglicherweise nullptr zurückgibt, wenn alle Werte in einem Vektor gültig sind; in diesem Fall muss die Gültigkeitsmaske nicht geprüft werden.

Zeichenketten

Zeichenkettenwerte werden als duckdb_string_t gespeichert. Das ist eine besondere Struktur, die die Zeichenkette inline speichert (wenn sie kurz ist, d. h. <= 12 bytes) oder einen Zeiger auf die Zeichendaten, wenn sie länger als 12 Bytes ist.

typedef struct {
  union {
    struct {
      uint32_t length;
      char prefix[4];
      char *ptr;
    } pointer;
    struct {
      uint32_t length;
      char inlined[12];
    } inlined;
  } value;
} duckdb_string_t;

Die Länge kann entweder direkt gelesen werden, oder duckdb_string_is_inlined kann verwendet werden, um zu prüfen, ob eine Zeichenkette inline gespeichert ist.

Dezimalzahlen

Dezimalzahlen werden intern als Ganzzahlwerte gespeichert. Der genaue native Typ hängt von der width des Dezimaltyps ab, wie in der folgenden Tabelle gezeigt:

Breite	NativeType
<= 4	int16_t
<= 9	int32_t
<= 18	int64_t
<= 38	duckdb_hugeint

duckdb_decimal_internal_type kann verwendet werden, um den internen Typ der Dezimalzahl zu ermitteln.

Dezimalzahlen werden als Ganzzahlwerte gespeichert, multipliziert mit 10^scale. Die Skala einer Dezimalzahl kann mit duckdb_decimal_scale ermittelt werden. Zum Beispiel wird ein Dezimalwert von 10.5 mit dem Typ DECIMAL(8, 3) intern als int32_t-Wert 10500 gespeichert. Um den korrekten Dezimalwert zu erhalten, muss der Wert durch die entsprechende Zehnerpotenz geteilt werden.

Enums

Enums werden intern als vorzeichenlose Ganzzahlwerte gespeichert. Der genaue native Typ hängt von der Größe des Enum-Wörterbuchs ab, wie in der folgenden Tabelle gezeigt:

Wörterbuchgröße	NativeType
<= 255	uint8_t
<= 65535	uint16_t
<= 4294967295	uint32_t

duckdb_enum_internal_type kann verwendet werden, um den internen Typ des Enums zu ermitteln.

Um den tatsächlichen Zeichenkettenwert des Enums zu erhalten, muss die Funktion duckdb_enum_dictionary_value verwendet werden, um den Enum-Wert zu ermitteln, der zum gegebenen Wörterbucheintrag gehört. Beachten Sie, dass das Enum-Wörterbuch für die gesamte Spalte gleich ist – und daher nur einmal aufgebaut werden muss.

Structs

Structs sind verschachtelte Typen, die beliebig viele Kindtypen enthalten. Stellen Sie sie sich wie ein struct in C vor. Der Weg, Struct-Daten über Vektoren anzusprechen, besteht darin, die Kindvektoren rekursiv mit der Methode duckdb_struct_vector_get_child anzusprechen.

Der Struct-Vektor selbst hat keine Daten (d. h. Sie sollten die Methode duckdb_vector_get_data nicht auf dem Struct verwenden). Allerdings hat der Struct-Vektor selbst eine Gültigkeitsmaske. Der Grund dafür ist, dass die Kindelemente eines Structs NULL sein können, der Struct selbst aber ebenfalls NULL sein kann.

Listen

Listen sind verschachtelte Typen, die einen einzelnen Kindtyp enthalten, der x-mal pro Zeile wiederholt wird. Stellen Sie sie sich wie ein Array variabler Länge in C vor. Der Weg, Listendaten über Vektoren anzusprechen, besteht darin, den Kindvektor mit der Methode duckdb_list_vector_get_child anzusprechen.

duckdb_vector_get_data muss verwendet werden, um die Offsets und Längen der Listen als duckdb_list_entry zu erhalten, die anschließend auf den Kindvektor angewendet werden können.

typedef struct {
  uint64_t offset;
  uint64_t length;
} duckdb_list_entry;

Beachten Sie, dass sowohl die Listeneinträge selbst als auch alle in den Listen gespeicherten Kinder ebenfalls NULL sein können. Das muss erneut über die Gültigkeitsmaske geprüft werden.

Arrays

Arrays sind verschachtelte Typen, die einen einzelnen Kindtyp enthalten, der genau array_size-mal pro Zeile wiederholt wird. Stellen Sie sie sich wie ein Array fester Größe in C vor. Arrays funktionieren genau wie Listen, außer dass Länge und Offset jedes Eintrags fest sind. Die feste Array-Größe kann mit duckdb_array_type_array_size ermittelt werden. Die Daten für den Eintrag n liegen dann bei offset = n * array_size und haben immer length = array_size.

Beachten Sie, dass Arrays wie Listen dennoch NULL sein können, was über die Gültigkeitsmaske geprüft werden muss.

Beispiele

Nachfolgend mehrere vollständige End-to-End-Beispiele, wie mit Vektoren interagiert wird.

Beispiel: Einen int64-Vektor mit NULL-Werten lesen

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

duckdb_result res;
duckdb_query(con, "SELECT CASE WHEN i%2=0 THEN NULL ELSE i END res_col FROM range(10) t(i)", &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 res_col = duckdb_data_chunk_get_vector(result, 0);
  // get the native array and the validity mask of the vector
  int64_t *vector_data = (int64_t *) duckdb_vector_get_data(res_col);
  uint64_t *vector_validity = duckdb_vector_get_validity(res_col);
  // iterate over the rows
  for (idx_t row = 0; row < row_count; row++) {
    if (duckdb_validity_row_is_valid(vector_validity, row)) {
      printf("%lld\n", vector_data[row]);
    } else {
      printf("NULL\n");
    }
  }
  duckdb_destroy_data_chunk(&result);
}
// clean-up
duckdb_destroy_result(&res);
duckdb_disconnect(&con);
duckdb_close(&db);

Beispiel: Einen Zeichenkettenvektor lesen

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

duckdb_result res;
duckdb_query(con, "SELECT CASE WHEN i%2=0 THEN CONCAT('short_', i) ELSE CONCAT('longstringprefix', i) END FROM range(10) t(i)", &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 res_col = duckdb_data_chunk_get_vector(result, 0);
  // get the native array and the validity mask of the vector
  duckdb_string_t *vector_data = (duckdb_string_t *) duckdb_vector_get_data(res_col);
  uint64_t *vector_validity = duckdb_vector_get_validity(res_col);
  // iterate over the rows
  for (idx_t row = 0; row < row_count; row++) {
    if (duckdb_validity_row_is_valid(vector_validity, row)) {
      duckdb_string_t str = vector_data[row];
      if (duckdb_string_is_inlined(str)) {
        // use inlined string
        printf("%.*s\n", str.value.inlined.length, str.value.inlined.inlined);
      } else {
        // follow string pointer
        printf("%.*s\n", str.value.pointer.length, str.value.pointer.ptr);
      }
    } else {
      printf("NULL\n");
    }
  }
  duckdb_destroy_data_chunk(&result);
}
// clean-up
duckdb_destroy_result(&res);
duckdb_disconnect(&con);
duckdb_close(&db);

Beispiel: Einen Struct-Vektor lesen

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

duckdb_result res;
duckdb_query(con, "SELECT CASE WHEN i%5=0 THEN NULL ELSE {'col1': i, 'col2': CASE WHEN i%2=0 THEN NULL ELSE 100 + i * 42 END} END FROM range(10) t(i)", &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 struct column
  duckdb_vector struct_col = duckdb_data_chunk_get_vector(result, 0);
  uint64_t *struct_validity = duckdb_vector_get_validity(struct_col);
  // get the child columns of the struct
  duckdb_vector col1_vector = duckdb_struct_vector_get_child(struct_col, 0);
  int64_t *col1_data = (int64_t *) duckdb_vector_get_data(col1_vector);
  uint64_t *col1_validity = duckdb_vector_get_validity(col1_vector);

  duckdb_vector col2_vector = duckdb_struct_vector_get_child(struct_col, 1);
  int64_t *col2_data = (int64_t *) duckdb_vector_get_data(col2_vector);
  uint64_t *col2_validity = duckdb_vector_get_validity(col2_vector);

  // iterate over the rows
  for (idx_t row = 0; row < row_count; row++) {
    if (!duckdb_validity_row_is_valid(struct_validity, row)) {
      // entire struct is NULL
      printf("NULL\n");
      continue;
    }
    // read col1
    printf("{'col1': ");
    if (!duckdb_validity_row_is_valid(col1_validity, row)) {
      // col1 is NULL
      printf("NULL");
    } else {
      printf("%lld", col1_data[row]);
    }
    printf(", 'col2': ");
    if (!duckdb_validity_row_is_valid(col2_validity, row)) {
      // col2 is NULL
      printf("NULL");
    } else {
      printf("%lld", col2_data[row]);
    }
    printf("}\n");
  }
  duckdb_destroy_data_chunk(&result);
}
// clean-up
duckdb_destroy_result(&res);
duckdb_disconnect(&con);
duckdb_close(&db);

Beispiel: Einen Listenvektor lesen

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

duckdb_result res;
duckdb_query(con, "SELECT CASE WHEN i % 5 = 0 THEN NULL WHEN i % 2 = 0 THEN [i, i + 1] ELSE [i * 42, NULL, i * 84] END FROM range(10) t(i)", &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 list column
  duckdb_vector list_col = duckdb_data_chunk_get_vector(result, 0);
  duckdb_list_entry *list_data = (duckdb_list_entry *) duckdb_vector_get_data(list_col);
  uint64_t *list_validity = duckdb_vector_get_validity(list_col);
  // get the child column of the list
  duckdb_vector list_child = duckdb_list_vector_get_child(list_col);
  int64_t *child_data = (int64_t *) duckdb_vector_get_data(list_child);
  uint64_t *child_validity = duckdb_vector_get_validity(list_child);

  // iterate over the rows
  for (idx_t row = 0; row < row_count; row++) {
    if (!duckdb_validity_row_is_valid(list_validity, row)) {
      // entire list is NULL
      printf("NULL\n");
      continue;
    }
    // read the list offsets for this row
    duckdb_list_entry list = list_data[row];
    printf("[");
    for (idx_t child_idx = list.offset; child_idx < list.offset + list.length; child_idx++) {
      if (child_idx > list.offset) {
        printf(", ");
      }
      if (!duckdb_validity_row_is_valid(child_validity, child_idx)) {
        // col1 is NULL
        printf("NULL");
      } else {
        printf("%lld", child_data[child_idx]);
      }
    }
    printf("]\n");
  }
  duckdb_destroy_data_chunk(&result);
}
// clean-up
duckdb_destroy_result(&res);
duckdb_disconnect(&con);
duckdb_close(&db);

API-Referenz im Überblick

duckdb_vector duckdb_create_vector(duckdb_logical_type type, idx_t capacity);
void duckdb_destroy_vector(duckdb_vector *vector);
duckdb_logical_type duckdb_vector_get_column_type(duckdb_vector vector);
void *duckdb_vector_get_data(duckdb_vector vector);
uint64_t *duckdb_vector_get_validity(duckdb_vector vector);
void duckdb_vector_ensure_validity_writable(duckdb_vector vector);
void duckdb_vector_assign_string_element(duckdb_vector vector, idx_t index, const char *str);
void duckdb_vector_assign_string_element_len(duckdb_vector vector, idx_t index, const char *str, idx_t str_len);
duckdb_vector duckdb_list_vector_get_child(duckdb_vector vector);
idx_t duckdb_list_vector_get_size(duckdb_vector vector);
duckdb_state duckdb_list_vector_set_size(duckdb_vector vector, idx_t size);
duckdb_state duckdb_list_vector_reserve(duckdb_vector vector, idx_t required_capacity);
duckdb_vector duckdb_struct_vector_get_child(duckdb_vector vector, idx_t index);
duckdb_vector duckdb_array_vector_get_child(duckdb_vector vector);
void duckdb_slice_vector(duckdb_vector vector, duckdb_selection_vector sel, idx_t len);
void duckdb_vector_copy_sel(duckdb_vector src, duckdb_vector dst, duckdb_selection_vector sel, idx_t src_count, idx_t src_offset, idx_t dst_offset);
void duckdb_vector_reference_value(duckdb_vector vector, duckdb_value value);
void duckdb_vector_reference_vector(duckdb_vector to_vector, duckdb_vector from_vector);

Funktionen der Gültigkeitsmaske

bool duckdb_validity_row_is_valid(uint64_t *validity, idx_t row);
void duckdb_validity_set_row_validity(uint64_t *validity, idx_t row, bool valid);
void duckdb_validity_set_row_invalid(uint64_t *validity, idx_t row);
void duckdb_validity_set_row_valid(uint64_t *validity, idx_t row);

duckdb_create_vector

Erzeugt einen flachen Vektor. Muss mit duckdb_destroy_vector zerstört werden.

Syntax

duckdb_vector duckdb_create_vector(
  duckdb_logical_type type,
  idx_t capacity
);

Parameter

• type: Der logische Typ des Vektors.
• capacity: Die Kapazität des Vektors.

Rückgabewert

Der Vektor.

duckdb_destroy_vector

Zerstört den Vektor und gibt seinen Speicher frei.

Syntax

void duckdb_destroy_vector(
  duckdb_vector *vector
);

Parameter

• vector: Ein Zeiger auf den Vektor.

duckdb_vector_get_column_type

Ermittelt den Spaltentyp des angegebenen Vektors.

Das Ergebnis muss mit duckdb_destroy_logical_type zerstört werden.

Syntax

duckdb_logical_type duckdb_vector_get_column_type(
  duckdb_vector vector
);

Parameter

• vector: Der Vektor, aus dem die Daten gelesen werden

Rückgabewert

Der Typ des Vektors

duckdb_vector_get_data

Ermittelt den Datenzeiger des Vektors.

Der Datenzeiger kann verwendet werden, um Werte aus dem Vektor zu lesen oder in den Vektor zu schreiben. Wie Werte gelesen oder geschrieben werden, hängt vom Typ des Vektors ab.

Syntax

void *duckdb_vector_get_data(
  duckdb_vector vector
);

Parameter

• vector: Der Vektor, aus dem die Daten gelesen werden

Rückgabewert

Der Datenzeiger

duckdb_vector_get_validity

Ermittelt den Zeiger auf die Gültigkeitsmaske des angegebenen Vektors.

Wenn alle Werte gültig sind, KANN diese Funktion NULL zurückgeben!

Die Gültigkeitsmaske ist ein Bitset, das die Null-Eigenschaft innerhalb des Datenchunks kennzeichnet. Es ist eine Folge von uint64_t-Werten, wobei jeder uint64_t-Wert die Gültigkeit für 64 Tupel enthält. Das Bit ist auf 1 gesetzt, wenn der Wert gültig ist (d. h. nicht NULL), oder auf 0, wenn der Wert ungültig ist (d. h. NULL).

Die Gültigkeit eines bestimmten Werts kann so ermittelt werden:

idx_t entry_idx = row_idx / 64; idx_t idx_in_entry = row_idx % 64; bool is_valid = validity_mask[entry_idx] & (1 << idx_in_entry);

Alternativ kann die (langsamere) Funktion duckdb_validity_row_is_valid verwendet werden.

Syntax

uint64_t *duckdb_vector_get_validity(
  duckdb_vector vector
);

Parameter

• vector: Der Vektor, aus dem die Daten gelesen werden

Rückgabewert

Der Zeiger auf die Gültigkeitsmaske, oder NULL, wenn keine Gültigkeitsmaske vorhanden ist

duckdb_vector_ensure_validity_writable

Stellt sicher, dass die Gültigkeitsmaske durch Allokation schreibbar ist.

Nachdem diese Funktion aufgerufen wurde, gibt duckdb_vector_get_validity IMMER einen Wert ungleich NULL zurück. So können NULL-Werte in den Vektor geschrieben werden, unabhängig davon, ob zuvor eine Gültigkeitsmaske vorhanden war.

Syntax

void duckdb_vector_ensure_validity_writable(
  duckdb_vector vector
);

Parameter

• vector: Der zu ändernde Vektor

duckdb_vector_assign_string_element

Weist dem Vektor an der angegebenen Position ein Zeichenkettenelement zu.

Syntax

void duckdb_vector_assign_string_element(
  duckdb_vector vector,
  idx_t index,
  const char *str
);

Parameter

• vector: Der zu ändernde Vektor
• index: Die Zeilenposition im Vektor, der die Zeichenkette zugewiesen wird
• str: Die null-terminierte Zeichenkette

duckdb_vector_assign_string_element_len

Weist dem Vektor an der angegebenen Position ein Zeichenkettenelement zu. Sie können diese Funktion auch verwenden, um BLOBs zuzuweisen.

Syntax

void duckdb_vector_assign_string_element_len(
  duckdb_vector vector,
  idx_t index,
  const char *str,
  idx_t str_len
);

Parameter

• vector: Der zu ändernde Vektor
• index: Die Zeilenposition im Vektor, der die Zeichenkette zugewiesen wird
• str: Die Zeichenkette
• str_len: Die Länge der Zeichenkette (in Bytes)

duckdb_list_vector_get_child

Ermittelt den Kindvektor eines Listenvektors.

Der resultierende Vektor ist gültig, solange der Elternvektor gültig ist.

Syntax

duckdb_vector duckdb_list_vector_get_child(
  duckdb_vector vector
);

Parameter

• vector: Der Vektor

Rückgabewert

Der Kindvektor

duckdb_list_vector_get_size

Gibt die Größe des Kindvektors der Liste zurück.

Syntax

idx_t duckdb_list_vector_get_size(
  duckdb_vector vector
);

Parameter

• vector: Der Vektor

Rückgabewert

Die Größe der Kindliste

duckdb_list_vector_set_size

Setzt die Gesamtgröße des zugrunde liegenden Kindvektors eines Listenvektors.

Syntax

duckdb_state duckdb_list_vector_set_size(
  duckdb_vector vector,
  idx_t size
);

Parameter

• vector: Der Listenvektor.
• size: Die Größe der Kindliste.

Rückgabewert

Der DuckDB-Status. Gibt DuckDBError zurück, wenn der Vektor nullptr ist.

duckdb_list_vector_reserve

Setzt die Gesamtkapazität des zugrunde liegenden Kindvektors einer Liste.

Nach dem Aufruf dieser Methode müssen Sie duckdb_vector_get_validity und duckdb_vector_get_data aufrufen, um die aktuellen Daten- und Gültigkeitszeiger zu erhalten

Syntax

duckdb_state duckdb_list_vector_reserve(
  duckdb_vector vector,
  idx_t required_capacity
);

Parameter

• vector: Der Listenvektor.
• required_capacity: die insgesamt zu reservierende Kapazität.

Rückgabewert

Der DuckDB-Status. Gibt DuckDBError zurück, wenn der Vektor nullptr ist.

duckdb_struct_vector_get_child

Ermittelt den Kindvektor eines Struct-Vektors. Der resultierende Vektor ist gültig, solange der Elternvektor gültig ist.

Syntax

duckdb_vector duckdb_struct_vector_get_child(
  duckdb_vector vector,
  idx_t index
);

Parameter

• vector: Der Vektor
• index: Der Kindindex

Rückgabewert

Der Kindvektor

duckdb_array_vector_get_child

Ermittelt den Kindvektor eines Array-Vektors. Der resultierende Vektor ist gültig, solange der Elternvektor gültig ist. Der resultierende Vektor hat die Größe des Elternvektors multipliziert mit der Array-Größe.

Syntax

duckdb_vector duckdb_array_vector_get_child(
  duckdb_vector vector
);

Parameter

• vector: Der Vektor

Rückgabewert

Der Kindvektor

duckdb_slice_vector

Schneidet einen Vektor mit einem Selektionsvektor. Die Länge des Selektionsvektors muss kleiner oder gleich der Länge des Vektors sein. Macht den Vektor zu einem Dictionary-Vektor.

Syntax

void duckdb_slice_vector(
  duckdb_vector vector,
  duckdb_selection_vector sel,
  idx_t len
);

Parameter

• vector: Der zu schneidende Vektor.
• sel: Der Selektionsvektor.
• len: Die Länge des Selektionsvektors.

duckdb_vector_copy_sel

Kopiert den Quellvektor nach dst mit einem Selektionsvektor, der angibt, welche Indizes kopiert werden.

Syntax

void duckdb_vector_copy_sel(
  duckdb_vector src,
  duckdb_vector dst,
  duckdb_selection_vector sel,
  idx_t src_count,
  idx_t src_offset,
  idx_t dst_offset
);

Parameter

• src: Der Vektor, aus dem kopiert wird.
• dst: Der Vektor, in den kopiert wird.
• sel: Der Selektionsvektor. Die Länge des Selektionsvektors sollte nicht größer sein als die Länge des src- Vektors
• src_count: Die Anzahl der aus dem Selektionsvektor zu kopierenden Einträge. Das ist die effektive Länge des Selektionsvektors ab Index 0
• src_offset: Der Offset im Selektionsvektor, ab dem kopiert wird (wichtig: tatsächliche Anzahl kopierter Elemente = src_count - src_offset).
• dst_offset: Der Offset im Zielvektor, ab dem kopiert wird.

duckdb_vector_reference_value

Kopiert den Wert von value nach vector.

Syntax

void duckdb_vector_reference_value(
  duckdb_vector vector,
  duckdb_value value
);

Parameter

• vector: Der empfangende Vektor.
• value: Der in den Vektor zu kopierende Wert.

duckdb_vector_reference_vector

Ändert to_vector so, dass er from_vector referenziert. Danach teilen sich die Vektoren den Besitz der Daten.

Syntax

void duckdb_vector_reference_vector(
  duckdb_vector to_vector,
  duckdb_vector from_vector
);

Parameter

• to_vector: Der empfangende Vektor.
• from_vector: Der zu referenzierende Vektor.

duckdb_validity_row_is_valid

Gibt zurück, ob eine Zeile in der gegebenen Gültigkeitsmaske gültig ist (d. h. nicht NULL).

Syntax

bool duckdb_validity_row_is_valid(
  uint64_t *validity,
  idx_t row
);

Parameter

• validity: Die Gültigkeitsmaske, wie über duckdb_vector_get_validity ermittelt
• row: Der Zeilenindex

Rückgabewert

true, wenn die Zeile gültig ist, sonst false

duckdb_validity_set_row_validity

Setzt in einer Gültigkeitsmaske eine bestimmte Zeile auf gültig oder ungültig.

Beachten Sie, dass duckdb_vector_ensure_validity_writable aufgerufen werden sollte, bevor duckdb_vector_get_validity aufgerufen wird, um sicherzustellen, dass eine Gültigkeitsmaske zum Schreiben vorhanden ist.

Syntax

void duckdb_validity_set_row_validity(
  uint64_t *validity,
  idx_t row,
  bool valid
);

Parameter

• validity: Die Gültigkeitsmaske, wie über duckdb_vector_get_validity ermittelt.
• row: Der Zeilenindex
• valid: Ob die Zeile auf gültig oder ungültig gesetzt werden soll

duckdb_validity_set_row_invalid

Setzt in einer Gültigkeitsmaske eine bestimmte Zeile auf ungültig.

Entspricht duckdb_validity_set_row_validity mit valid auf false.

Syntax

void duckdb_validity_set_row_invalid(
  uint64_t *validity,
  idx_t row
);

Parameter

• validity: Die Gültigkeitsmaske
• row: Der Zeilenindex

duckdb_validity_set_row_valid

Setzt in einer Gültigkeitsmaske eine bestimmte Zeile auf gültig.

Entspricht duckdb_validity_set_row_validity mit valid auf true.

Syntax

void duckdb_validity_set_row_valid(
  uint64_t *validity,
  idx_t row
);

Parameter

• validity: Die Gültigkeitsmaske
• row: Der Zeilenindex