Struct DuckDbVectorRawReader<T>
Points to data for a column within a result chunk from DuckDB, and gives read access to it.
Inherited Members
Namespace: Mallard
Assembly: Mallard.dll
Syntax
public readonly ref struct DuckDbVectorRawReader<T> : IDuckDbVector<T>, IDuckDbVector where T : unmanaged, allows ref structType Parameters
| Name | Description | ||||||
|---|---|---|---|---|---|---|---|
| T | The .NET type for the element type of the vector, which must be layout-compatible with the storage type used by DuckDB. The precise list of types allowed are:
|
Remarks
DuckDB, a column-oriented database, calls this grouping of data a "vector". This type only supports reading from a DuckDB vector; writing to a vector (for the purposes of modifying the database) requires a different shape of API to enforce safety.
This "raw" version of the reader passes the data to the user directly from the native memory loaded by the DuckDB library. It does not perform any other translation (to other .NET types).
Elements can be accessed one by one through Call AsSpan<T>(in DuckDbVectorRawReader<T>) to obtain the
This "raw" data may be difficult to consume, particularly for elements that are higher-level like Decimal or nested ones like List. Results that are easier to consume can be produced by the non-raw DuckDbVectorReader<T> instead, at the expense of some efficiency.
In theory, any type can be retrieved and converted in the most efficient manner by generating source code that reads the raw data through this reader. But source generation may be overkill and complicated for many applications.
The reader is a "ref struct" because internally it holds and accesses pointers to native memory for the vector from DuckDB, and so its scope (lifetime) must be carefully controlled. Non-trivial instances are only accessible from within a processing function for a chunk conforiming to DuckDbChunkReadingFunc<TState, TReturn>.
Properties
| Edit this page View SourceColumnInfo
Information about the column that this vector is part of.
Declaration
public DuckDbColumnInfo ColumnInfo { get; }Property Value
| Type | Description |
|---|---|
| DuckDbColumnInfo |
this[int]
Same as GetItem(int): retrieve a valid element of this vector.
Declaration
public T this[int index] { get; }Parameters
| Type | Name | Description |
|---|---|---|
| int | index | The index of the element in this vector. |
Property Value
| Type | Description |
|---|---|
| T | The desired element of this vector. |
Exceptions
| Type | Condition |
|---|---|
| IndexOutOfRangeException | The index is out of range for the vector. |
| InvalidOperationException | The requested element is invalid. |
Length
The length (number of rows) inherited from the result chunk this vector is part of.
Declaration
public int Length { get; }Property Value
| Type | Description |
|---|---|
| int |
ValidityMask
The variable-length bit mask indicating which elements in the vector are valid (not null).
Declaration
public ReadOnlySpan<ulong> ValidityMask { get; }Property Value
| Type | Description |
|---|---|
| ReadOnlySpan<ulong> |
Remarks
For element index i and validity mask m (the return value from this method),
the following expression indicates if the element is valid:
m.Length == 0 || (m[i / 64] & (1u % 64)) != 0Methods
| Edit this page View SourceGetItem(int)
Retrieve a valid element of this vector.
Declaration
public T GetItem(int index)Parameters
| Type | Name | Description |
|---|---|---|
| int | index | The index of the element to select. |
Returns
| Type | Description |
|---|---|
| T | The desired element of this vector. |
Remarks
For the purposes of this method, an element that is missing in the DuckDB vector but is materialized as an instance of Nullable<T> is considered "valid", i.e. this method will not throw an exception.
(Otherwise, there would be no point
in substituting a nullable value type for T. Consistency would
argue that nullable reference types be treated the same way, but in .NET, reference
nullability are only compiler-driven annotations and not part of the run-time type
system, so an implementation of this interface generally cannot detect whether
T is U or U? for reference types U.
So, if T is a reference type, this method throws an exception
if the source element in the DuckDB vector is missing.)
Clients that want to basically assume all the elements of the vector are valid would call this method.
Exceptions
| Type | Condition |
|---|---|
| IndexOutOfRangeException | The index is out of range for the vector. |
| InvalidOperationException | The requested element is invalid. |
GetItemOrDefault(int)
Retrieve an element of this vector, returning the default value if it is invalid.
Declaration
public T GetItemOrDefault(int index)Parameters
| Type | Name | Description |
|---|---|---|
| int | index | The index of the element to select. |
Returns
| Type | Description |
|---|---|
| T | The desired element of this vector. |
Remarks
The "default" value refers to the default-initialized value of a variable of
tyoe T.
Exceptions
| Type | Condition |
|---|---|
| IndexOutOfRangeException | The index is out of range for the vector. |
IsItemValid(int)
Return whether an element of this vector is valid (not null).
Declaration
public bool IsItemValid(int index)Parameters
| Type | Name | Description |
|---|---|---|
| int | index | The index of the element of the vector. |
Returns
| Type | Description |
|---|---|
| bool | True if valid (non-null), false if invalid (null). |
Exceptions
| Type | Condition |
|---|---|
| IndexOutOfRangeException | The index is out of range for the vector. |
TryGetItem(int, out T)
Retrieve an element of this vector, or report that it is invalid.
Declaration
public bool TryGetItem(int index, out T item)Parameters
| Type | Name | Description |
|---|---|---|
| int | index | The index of the element in this vector. |
| T | item | The item that is to be read out. Set to the element type's default value when the element is invalid. |
Returns
| Type | Description |
|---|---|
| bool | Whether the element is valid. |
Exceptions
| Type | Condition |
|---|---|
| IndexOutOfRangeException | The index is out of range for the vector. |
ValidateParamType(DuckDbValueKind)
Validate that the .NET type is correct for interpreting the raw data array obtained from DuckDB.
Declaration
public static bool ValidateParamType(DuckDbValueKind valueKind)Parameters
| Type | Name | Description |
|---|---|---|
| DuckDbValueKind | valueKind | The basic type of the DuckDB data array desired to be accessed. |
Returns
| Type | Description |
|---|---|
| bool | True if the .NET type is correct; false if incorrect or
the |