Struct DuckDbVectorReader<T>

General-purpose reader of a column of data within a result chunk from DuckDB.

Implements

IDuckDbVector<T>

IDuckDbVector

Inherited Members

ValueType.Equals(object)

ValueType.GetHashCode()

ValueType.ToString()

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Namespace: Mallard

Assembly: Mallard.dll

Syntax

public readonly ref struct DuckDbVectorReader<T> : IDuckDbVector<T>, IDuckDbVector

Type Parameters

Name	Description
T

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 reader internally uses indirect calls to read, and convert if necessary, the data in DuckDB's native formats, to the desired .NET type.

This reader is thus slower than DuckDbVectorRawReader<T>, but the results are easier for clients to consume. For simple types, the run-time overhead should be small, while for complex types (such as lists or even enumerations), considerable manual work is necessary to consume them through "raw" methods that the run-time overhead may be acceptable.)

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

ColumnInfo

Information about the column that this vector is part of.

Declaration

public DuckDbColumnInfo ColumnInfo { get; }

Property Value

Type	Description
DuckDbColumnInfo

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)) != 0

Methods

GetItem(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.

Implements

IDuckDbVector<T>

IDuckDbVector