VariantUtils#

public class VariantUtils#

Utility methods for cuDF’s experimental Parquet Variant extraction APIs.

Method Summary

`castVariantValue(ColumnView valueBytes, DType targetType)`	Decode raw Variant-encoded value bytes into targetType.
`castVariantValueWithStatus(ColumnView valueBytes, DType targetType)`	Decode raw Variant values and return a per-row operation status.
`castVariantValueWithStatus(ColumnView valueBytes, DType targetType, ColumnView priorStatus)`	Decode raw Variant values while propagating status from an earlier raw extraction.
`extractVariantField(ColumnView variantStruct, String path, DType targetType)`	Extract a Variant field and decode it into targetType in one native call.
`extractVariantFieldWithStatus(ColumnView variantStruct, String path, DType targetType)`	Extract and decode a Variant field and return a per-row operation status.
`getVariantFieldValue(ColumnView variantStruct, String path)`	Extract raw Variant-encoded value bytes at path from a Variant struct column.
`getVariantFieldValueWithStatus(ColumnView variantStruct, String path)`	Extract raw Variant-encoded value bytes and return a per-row operation status.
`getVariantTypeId(ColumnView valueBytes)`	Return the logical type ID of each raw Variant-encoded value.

Static Methods

public static ColumnVector getVariantFieldValue( ColumnView variantStruct, String path )#

Extract raw Variant-encoded value bytes at path from a Variant struct column.

Parameters:

variantStruct – Variant materialization: STRUCT(metadata LIST<UINT8>, value LIST<UINT8>, optional shredded children…)
path – JSONPath-like path accepted by cuDF’s Variant extractor. Object-field steps use dot notation and zero-based array-index steps use bracket notation, for example x, $.x.y, $[0], or $.a[0].b. Missing fields, out-of-bounds indices, and container mismatches produce null rows. Wildcards, negative indices, and quoted names inside brackets are not supported.

Returns:

LIST<UINT8> column of raw encoded Variant values

public static VariantOperationResult getVariantFieldValueWithStatus( ColumnView variantStruct, String path )#

Extract raw Variant-encoded value bytes and return a per-row operation status.

The value result has the same behavior as getVariantFieldValue(ColumnView, String). A terminal encoded Variant null remains a valid raw value and has VariantOperationStatus.VARIANT_NULL status. Other statuses distinguish SQL-null rows, missing paths, and malformed encodings.

Parameters:

variantStruct – Variant materialization
path – JSONPath-like path accepted by cuDF’s Variant extractor

Returns:

owning value and status columns

public static ColumnVector getVariantTypeId(ColumnView valueBytes)#

Return the logical type ID of each raw Variant-encoded value.

The input must be a LIST<UINT8> column. The result is a UINT8 column containing the IDs defined by VariantLogicalType. A result row is null when the input row is null, the value blob is empty, or its header is unrecognized. An encoded Variant null is represented by a valid VariantLogicalType.NULL_VALUE row. Only the header byte is inspected, so a recognized header is classified even if the remaining payload is truncated. Timestamp logical IDs distinguish timezone-adjusted from NTZ encodings, but do not distinguish microsecond from nanosecond units.

This API mirrors an experimental libcudf API and is subject to change.

Parameters:: valueBytes – LIST<UINT8> column of raw Variant-encoded values
Returns:: owning UINT8 column of logical type IDs

public static ColumnVector castVariantValue( ColumnView valueBytes, DType targetType )#

Decode raw Variant-encoded value bytes into targetType.

Supported target types are DType.STRING, DType.INT8, DType.INT16, DType.INT32, DType.INT64, DType.FLOAT32, DType.FLOAT64, DType.BOOL8, DType.TIMESTAMP_MICROSECONDS, DType.TIMESTAMP_NANOSECONDS, and decimal types created with DType.create(DType.DTypeEnum, int) using DType.DTypeEnum.DECIMAL32, DType.DTypeEnum.DECIMAL64, or DType.DTypeEnum.DECIMAL128. Except for the timestamp encodings described below, non-decimal decoding requires the encoded physical type to exactly match targetType; no numeric conversions are performed. Any encoded decimal width can be decoded to any supported decimal width. Decimal values are rescaled to the target scale, truncating toward zero when fractional digits are discarded. Input nulls, encoded Variant nulls, physical-type mismatches, malformed values, and decimal overflows produce null output rows.

The target decimal scale uses cuDF’s base-10 exponent convention: scale -2 represents hundredths, while scale 2 represents hundreds. Overflow is checked against the target’s integer storage width; no declared decimal precision is enforced.

Timestamp targets accept both timezone-adjusted and NTZ encodings of the same unit and preserve the signed 64-bit payload unchanged. No timezone or unit conversion is performed. Mismatched units and truncated timestamp payloads produce null rows.

public static VariantOperationResult castVariantValueWithStatus( ColumnView valueBytes, DType targetType )#

Decode raw Variant values and return a per-row operation status.

The status distinguishes successful decoding, SQL-null input, encoded Variant null, physical-type mismatch, malformed input, and decimal overflow (VariantOperationStatus.OVERFLOW). The status column is initialized to VariantOperationStatus.SUCCESS before the native cast.

Supported target types and decoding semantics match castVariantValue(ColumnView, DType).

Parameters:

valueBytes – LIST<UINT8> column of raw Variant-encoded values
targetType – decoded output type

Returns:

owning value and status columns

public static VariantOperationResult castVariantValueWithStatus( ColumnView valueBytes, DType targetType, ColumnView priorStatus )#

Decode raw Variant values while propagating status from an earlier raw extraction.

The incoming status is copied before the native call and is never modified. Rows whose incoming status is not VariantOperationStatus.SUCCESS are not decoded; their status is propagated and their value is null.

Supported target types and decoding semantics match castVariantValue(ColumnView, DType).

Parameters:

valueBytes – LIST<UINT8> column of raw Variant-encoded values
targetType – decoded output type
priorStatus – UINT8 status column aligned with valueBytes, with no validity buffer (an all-valid mask is also rejected)

Returns:

owning value and final status columns

public static ColumnVector extractVariantField( ColumnView variantStruct, String path, DType targetType )#

Extract a Variant field and decode it into targetType in one native call.

Supported target types are DType.STRING, DType.INT8, DType.INT16, DType.INT32, DType.INT64, DType.FLOAT32, DType.FLOAT64, and DType.BOOL8, DType.TIMESTAMP_MICROSECONDS, DType.TIMESTAMP_NANOSECONDS, plus decimal types created with DType.create(DType.DTypeEnum, int) using DType.DTypeEnum.DECIMAL32, DType.DTypeEnum.DECIMAL64, or DType.DTypeEnum.DECIMAL128. Except for the timestamp encodings described below, non-decimal decoding requires the encoded physical type to exactly match targetType; no numeric conversions are performed. Any encoded decimal width can be decoded to any supported decimal width. Decimal values are rescaled to the target scale, truncating toward zero when fractional digits are discarded. Missing fields, input nulls, encoded Variant nulls, physical-type mismatches, malformed values, and decimal overflows produce null output rows.

Parameters:

variantStruct – Variant materialization: STRUCT(metadata LIST<UINT8>, value LIST<UINT8>, optional shredded children…)
path – JSONPath-like path accepted by cuDF’s Variant extractor. Object-field steps use dot notation and zero-based array-index steps use bracket notation, for example x, $.x.y, $[0], or $.a[0].b. Missing fields, out-of-bounds indices, and container mismatches produce null rows. Wildcards, negative indices, and quoted names inside brackets are not supported.
targetType – decoded output type

public static VariantOperationResult extractVariantFieldWithStatus( ColumnView variantStruct, String path, DType targetType )#

Extract and decode a Variant field and return a per-row operation status.

The value column has the same target type and row order as extractVariantField(ColumnView, String, DType). Status values distinguish successful extraction and decoding from SQL-null input, missing paths, encoded Variant null, physical-type mismatch, malformed input, and decimal overflow (VariantOperationStatus.OVERFLOW).

Parameters:

variantStruct – Variant materialization
path – JSONPath-like path accepted by cuDF’s Variant extractor
targetType – decoded output type

Returns:

owning value and status columns