Class DuckDbResult

Grants access to the results of a SQL execution by DuckDB.

Inheritance

object

DuckDbResult

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Mallard

Assembly: Mallard.dll

Syntax

public sealed class DuckDbResult : IDisposable

Remarks

The results are always presented in chunks by DuckDB. Each chunk can be requested in succession (allowing streaming queries).

Since retrieving a chunk advances the internal state of this result object, i.e. mutating that state, methods in this class that do that may not be called from multiple threads simultaneously. Any attempt to do so will cause exceptions.

Properties

ColumnCount

The number of columns present in the result.

Declaration

public int ColumnCount { get; }

Property Value

Type	Description
int

TypeMappingFlags

Overridden compatibility flags for mapping DuckDB types to .NET types.

Declaration

public DuckDbTypeMappingFlags TypeMappingFlags { get; }

Property Value

Type	Description
DuckDbTypeMappingFlags

Methods

Dispose()

Disposes (closes) this result object.

Declaration

public void Dispose()

Remarks

Native resources for holding the results in DuckDB will be released.

This method does nothing if the object has already been disposed.

Exceptions

Type	Condition
InvalidOperationException	Another thread is using this object, and the object not be disposed concurrently.

FetchNextChunk()

Retrieve the next chunk of results from the present query in DuckDB.

Declaration

public DuckDbResultChunk? FetchNextChunk()

Returns

Type	Description
DuckDbResultChunk	Object containing the next chunk, or null if there are no more chunks.

Remarks

This method may not be called simultaneously from multiple threads.

Nevertheless, the processing of the contents of chunks may still be parallelized. Have one thread/task call this method repeatedly to obtain individual chunk objects. Then, each such object may be passed to a different thread/task, to process its contents via ProcessContents<TState, TResult>(TState, DuckDbChunkReadingFunc<TState, TResult>).

~DuckDbResult()

Destructor which will dispose if it has not yet been already.

Declaration

protected ~DuckDbResult()

GetColumnInfo(int)

Get information about a column in the results.

Declaration

public DuckDbColumnInfo GetColumnInfo(int columnIndex)

Parameters

Type	Name	Description
int	columnIndex	The index of the column, between 0 (inclusive) to ColumnCount (exclusive).

Returns

Type	Description
DuckDbColumnInfo

GetColumnName(int)

Get the name of a column in the results.

Declaration

public string GetColumnName(int columnIndex)

Parameters

Type	Name	Description
int	columnIndex	The index of the column, between 0 (inclusive) to ColumnCount (exclusive).

Returns

Type	Description
string	The name of the column, or Empty if it has no name.

ProcessAllChunks<TState, TReturn>(TState, DuckDbChunkReadingFunc<TState, TReturn>)

Process all the following chunks of results from the present query in DuckDB, with a caller-specified function.

Declaration

public TReturn? ProcessAllChunks<TState, TReturn>(TState state, DuckDbChunkReadingFunc<TState, TReturn> function) where TState : allows ref struct

Parameters

Type	Name	Description
TState	state	The state object or structure to pass into function.
DuckDbChunkReadingFunc<TState, TReturn>	function	The caller-specified function that receives the results from the next chunk and may do any processing on it.

Returns

Type	Description
TReturn	The return value is whatever function returns for the last chunk (if successful). If there are no more chunks, this argument is set to the default value for its type.

Type Parameters

Name	Description
TState	Type of arbitrary state to pass into the caller-specified function.
TReturn	The type of value returned by the caller-specified function.

Remarks

This method offers fast, direct access to the native memory backing the DuckDB vectors (columns) of the results. However, to make these operations safe (allowing no dangling pointers), this library must be able to bound the scope of access. Thus, the code to consume the vectors' data must be encapsulated in a function that this method invokes.

The chunks processed by this method are discarded afterwards. To work with the results again, the query must be re-executed anew.

This method is equivalent to calling ProcessNextChunk<TState, TReturn>(TState, DuckDbChunkReadingFunc<TState, TReturn>, out TReturn) in a loop until that method returns false.

The return values of function for every chunk except the last are discarded. To communicate information between successive invocations of function, pass in either a reference type, or a "ref struct" containing managed pointers, for TState so that function can modify the referents. Or, of course, the code for function could also be written to close over individual variables from its surrounding scope.

This method may not be called from multiple threads simultaneously.

ProcessAllChunks<TState, TReturn>(TState, DuckDbChunkReadingFunc<TState, TReturn>, Func<TReturn, TReturn, TReturn>, TReturn)

Process all the following chunks of results from the present query in DuckDB, by invocating a caller-specified function on each, and accumulate return values across invocations.

Declaration

public TReturn ProcessAllChunks<TState, TReturn>(TState state, DuckDbChunkReadingFunc<TState, TReturn> function, Func<TReturn, TReturn, TReturn> accumulate, TReturn seed) where TState : allows ref struct

Parameters

Type	Name	Description
TState	state	The state object or structure to pass into function.
DuckDbChunkReadingFunc<TState, TReturn>	function	The caller-specified function that receives the results from the next chunk and may do any processing on it.
Func<TReturn, TReturn, TReturn>	accumulate	The function to accumulate (or aggregate, or "reduce") the return values from successive invocations of function. The first argument is the previous accumulated value; the second argument is the return value from the next chunk. For the first invocation, the first argument is seed.
TReturn	seed	The initial value for the accumulation of return values from function.

Returns

Type	Description
TReturn	The accumulated value of the return values from the chunks.

Type Parameters

Name	Description
TState	Type of arbitrary state to pass into the caller-specified function.
TReturn	The type of value returned by the caller-specified function.

Remarks

This method offers fast, direct access to the native memory backing the DuckDB vectors (columns) of the results. However, to make these operations safe (allowing no dangling pointers), this library must be able to bound the scope of access. Thus, the code to consume the vectors' data must be encapsulated in a function that this method invokes.

The chunks processed by this method are discarded afterwards. To work with the results again, the query must be re-executed anew.

This method is equivalent to calling ProcessNextChunk<TState, TReturn>(TState, DuckDbChunkReadingFunc<TState, TReturn>, out TReturn) in a loop until that method returns false.

This method may not be called from multiple threads simultaneously.

ProcessNextChunk<TState, TReturn>(TState, DuckDbChunkReadingFunc<TState, TReturn>, out TReturn)

Process the next chunk of results from the present query in DuckDB, with a caller-specified function.

Declaration

public bool ProcessNextChunk<TState, TReturn>(TState state, DuckDbChunkReadingFunc<TState, TReturn> function, out TReturn result) where TState : allows ref struct

Parameters

Type	Name	Description
TState	state	The state object or structure to pass into function.
DuckDbChunkReadingFunc<TState, TReturn>	function	The caller-specified function that receives the results from the next chunk and may do any processing on it.
TReturn	result	On return, set to the whatever function returns. If there is no next chunk, this argument is set to the default value for its type.

Returns

Type	Description
bool	True when a chunk has been successfully processed. False when there are no more chunks.

Type Parameters

Name	Description
TState	Type of arbitrary state to pass into the caller-specified function.
TReturn	The type of value returned by the caller-specified function.

Remarks

This method offers fast, direct access to the native memory backing the DuckDB vectors (columns) of the results. However, to make these operations safe (allowing no dangling pointers), this library must be able to bound the scope of access. Thus, the code to consume the vectors' data must be encapsulated in a function that this method invokes.

A chunk processed by this method is discarded immediately afterwards (even if function fails with an exception). To work with the same chunk again, the query must be re-executed anew.

Alternatively, use the method FetchNextChunk() instead which returns the next chunk as a standalone object, that can be processed over and over again.

This method can be called continually, until it returns false, to process all chunks of the result.

This method may not be called from multiple threads simultaneously. Although there is potential for multiple threads to process the contents of distinct chunks in parallel, getting (fetching) successive chunks is not parallelizable, and the API shape of this method does not allow segregating the two concerns. Use the chunk objects DuckDbResultChunk from FetchNextChunk() instead if multi-thread processing is desired.

Implements

IDisposable