Class VelocityResult

Namespace

Datafication.Storage.Velocity

Assembly

Datafication.Storage.Velocity.dll

Represents a lazy evaluation result from VelocityDataBlock query operations. Enables efficient row counting and streaming without full data materialization.

public sealed class VelocityResult

Inheritance

object

VelocityResult

Examples

// Efficient counting without full materialization
var result = vdb.Where("Country", "USA").AsResult();
int count = result.RowCount;  // Uses SIMD PopCount, no data materialization

// Explicit materialization when needed
DataBlock data = result.ToDataBlock();

// Chained operations
var filtered = result.Where("Age", 25, ComparisonOperator.GreaterThan);

Remarks

VelocityResult provides deferred execution for query operations, allowing efficient operations like counting rows without materializing the full dataset. This is particularly useful for large datasets where full materialization would be expensive.

The result maintains a reference to the source VelocityDataBlock and stores row indices using optimized storage (bitmask for high selectivity, sparse list for low).

Lifecycle: VelocityResult does NOT dispose the source VelocityDataBlock. The source must outlive all VelocityResult instances. Row indices are computed at AsResult() time (snapshot semantics).

Properties

Columns

Gets the column names in this result, including any computed columns.

public IReadOnlyList<string> Columns { get; }

Property Value

IReadOnlyList<string>

DeferredOperationNames

Gets the names of deferred operations that will execute on ToDataBlock().

public IReadOnlyList<string> DeferredOperationNames { get; }

Property Value

IReadOnlyList<string>

HasColumnProjection

Gets whether this result has column projection applied.

public bool HasColumnProjection { get; }

Property Value

bool

HasComputedColumns

Gets whether this result has computed columns from window functions.

public bool HasComputedColumns { get; }

Property Value

bool

HasDeferredOperations

Gets whether this result has deferred operations that will execute on ToDataBlock().

public bool HasDeferredOperations { get; }

Property Value

bool

Remarks

Deferred operations include Sort, Compute, Head, and Tail. These operations are stored but not executed until ToDataBlock() is called. This allows accurate RowCount calculation while deferring the actual data transformation.

IsEmpty

Gets whether this result is empty (no matching rows).

public bool IsEmpty { get; }

Property Value

bool

RowCount

Gets the number of rows in this result without full materialization. Uses SIMD PopCount for bitmask storage, providing O(n/64) performance.

public int RowCount { get; }

Property Value

int

Remarks

This property is highly optimized for performance:

• For bitmask storage: Uses SIMD POPCNT instruction for ~10GB/s throughput
• For sparse storage: Returns the list count directly (O(1))
• For all-rows: Returns the source row count (O(1))

The result is cached after first computation.

When Head or Tail limits are present, RowCount returns min(baseCount, limit). Sort and Compute operations don't affect RowCount - they only transform data.

Schema

Gets the schema of this result, including any computed columns.

public DataSchema Schema { get; }

Property Value

DataSchema

Methods

EnumerateColumn<T>(string)

Enumerates values from a single column without full materialization.

public IEnumerable<T?> EnumerateColumn<T>(string columnName)

Parameters

columnName string

The name of the column to enumerate.

Returns

IEnumerable<T>

An enumerable of column values.

Type Parameters

T

The expected type of the column values.

EnumerateRows()

Enumerates rows without full materialization. Memory usage is O(1) per row, regardless of result set size.

public IEnumerable<VelocityDataRow> EnumerateRows()

Returns

IEnumerable<VelocityDataRow>

An enumerable of VelocityDataRow objects.

Head(int)

Takes the first N rows from this result.

public VelocityResult Head(int count)

Parameters

count int

The number of rows to take.

Returns

VelocityResult

A new VelocityResult with at most count rows.

Select(params string[])

Projects specific columns from this result.

public VelocityResult Select(params string[] columnNames)

Parameters

columnNames string[]

The columns to select.

Returns

VelocityResult

A new VelocityResult with the column projection applied.

Tail(int)

Takes the last N rows from this result.

public VelocityResult Tail(int count)

Parameters

count int

The number of rows to take.

Returns

VelocityResult

A new VelocityResult with at most count rows from the end.

ToDataBlock()

Materializes this result into a DataBlock.

public DataBlock ToDataBlock()

Returns

DataBlock

A DataBlock containing the result data.

Remarks

This method triggers full materialization of the result set. For large result sets, consider using EnumerateRows() for streaming.

When deferred operations are present (Sort, Compute, Head, Tail), they are executed in the following order:

1. Materialize base rows from DFC
2. Execute deferred Sort operations
3. Apply Head/Tail limits
4. Execute deferred Compute operations

Where(string, object, ComparisonOperator)

Applies an additional Where filter to this result.

public VelocityResult Where(string columnName, object value, ComparisonOperator op = ComparisonOperator.Equals)

Parameters

columnName string

The column to filter on.

value object

The value to compare against.

op ComparisonOperator

The comparison operator (default: Equals).

Returns

VelocityResult

A new VelocityResult with the additional filter applied.