Add Java Variant extraction support (#23069)

This PR contributes to NVIDIA/cudf-spark#15180

Adds cuDF Java bindings for the experimental cuDF Variant extraction APIs used to read typed values from Parquet Variant columns.

This exposes Java wrappers for:

- extracting a Variant field by path
- casting extracted Variant values to supported scalar types
- extracting and casting a field in one call

The implementation wraps the cuDF C++ APIs in `cudf/io/experimental/variant.hpp`, including `get_variant_field`, `cast_variant`, and `extract_variant_field`.

This is needed by Spark RAPIDS Variant support so expressions such as `try_variant_get` can call into cuDF through the normal cuDF Java.

## Supported Types

The current bindings support the Variant target types currently supported by the cuDF API:

- `STRING`
- `INT8`
- `INT16`
- `INT32`
- `INT64`

Other Spark Variant target types can be added later as cuDF support becomes available.

## Testing

Added `VariantUtilsTest` coverage for:

- field extraction by path
- casting Variant values to supported target types
- combined extract-and-cast behavior
- unsupported target type validation
- null argument validation

Authors:
  - Niranjan Artal (https://github.com/nartal1)
  - Nghia Truong (https://github.com/ttnghia)

Approvers:
  - Nghia Truong (https://github.com/ttnghia)

URL: #23069

Author: nartal1

java/src/main/java/ai/rapids/cudf/VariantUtils.java

@@ -0,0 +1,83 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package ai.rapids.cudf;
+
+import java.util.Arrays;
+import java.util.List;
+import java.util.Objects;
+
+/**
+ * Utility methods for cuDF's experimental Parquet Variant extraction APIs.
+ */
+public class VariantUtils {
+  static {
+    NativeDepsLoader.loadNativeDeps();
+  }
+
+  // Keep in sync with the target types accepted by cuDF Variant extraction/cast:
+  // cpp/include/cudf/io/experimental/variant.hpp and
+  // cpp/src/io/parquet/experimental/variant_extract.cu:is_variant_castable.
+  private static final List<DType> SUPPORTED_TYPES = Arrays.asList(
+      DType.STRING, DType.INT8, DType.INT16, DType.INT32, DType.INT64);
+
+  private VariantUtils() {}
+
+  private static void validateTargetType(DType targetType) {
+    Objects.requireNonNull(targetType, "targetType");
+    if (!SUPPORTED_TYPES.contains(targetType)) {
+      throw new IllegalArgumentException("unsupported Variant target type: " + targetType +
+          "; supported types are " + SUPPORTED_TYPES);
+    }
+  }
+
+  /**
+   * Extract raw Variant-encoded value bytes at {@code path} from a Variant struct column.
+   *
+   * @param variantStruct Variant materialization: STRUCT(metadata LIST&lt;UINT8&gt;,
+   *                      value LIST&lt;UINT8&gt;, optional shredded children...)
+   * @param path JSONPath-like path accepted by cuDF's Variant extractor. Paths are expected to
+   *             be ASCII object-field paths like {@code x}, {@code $.x}, or {@code $.x.y}.
+   * @return LIST&lt;UINT8&gt; column of raw encoded Variant values
+   */
+  public static ColumnVector getVariantFieldValue(ColumnView variantStruct, String path) {
+    Objects.requireNonNull(variantStruct, "variantStruct");
+    Objects.requireNonNull(path, "path");
+    return new ColumnVector(getVariantFieldValue(variantStruct.getNativeView(), path));
+  }
+
+  /**
+   * Decode raw Variant-encoded value bytes into {@code targetType}. Supported target types are
+   * {@link DType#STRING}, {@link DType#INT8}, {@link DType#INT16}, {@link DType#INT32}, and
+   * {@link DType#INT64}.
+   */
+  public static ColumnVector castVariantValue(ColumnView valueBytes, DType targetType) {
+    Objects.requireNonNull(valueBytes, "valueBytes");
+    validateTargetType(targetType);
+    return new ColumnVector(castVariantValue(
+        valueBytes.getNativeView(), targetType.getTypeId().getNativeId()));
+  }
+
+  /**
+   * Extract a Variant field and decode it into {@code targetType} in one native call.
+   * Supported target types are {@link DType#STRING}, {@link DType#INT8}, {@link DType#INT16},
+   * {@link DType#INT32}, and {@link DType#INT64}.
+   */
+  public static ColumnVector extractVariantField(
+      ColumnView variantStruct, String path, DType targetType) {
+    Objects.requireNonNull(variantStruct, "variantStruct");
+    Objects.requireNonNull(path, "path");
+    validateTargetType(targetType);
+    return new ColumnVector(extractVariantField(
+        variantStruct.getNativeView(), path, targetType.getTypeId().getNativeId()));
+  }
+
+  private static native long getVariantFieldValue(long variantStructHandle, String path);
+
+  private static native long castVariantValue(long valueBytesHandle, int cudfTypeId);
+
+  private static native long extractVariantField(
+      long variantStructHandle, String path, int cudfTypeId);
+}

java/src/main/native/CMakeLists.txt

@@ -1,6 +1,6 @@
 # =============================================================================
 # cmake-format: off
-# SPDX-FileCopyrightText: Copyright (c) 2019-2026, NVIDIA CORPORATION.
+# SPDX-FileCopyrightText: Copyright (c) 2019-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 # cmake-format: on
 # =============================================================================
@@ -179,6 +179,7 @@ add_library(
   src/RmmJni.cpp
   src/ScalarJni.cpp
   src/TableJni.cpp
+  src/VariantUtilsJni.cpp
   src/aggregation128_utils.cu
   src/check_nvcomp_output_sizes.cu
   src/maps_column_view.cu

java/src/main/native/src/VariantUtilsJni.cpp

@@ -0,0 +1,73 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include "cudf_jni_apis.hpp"
+
+#include <cudf/io/experimental/variant.hpp>
+#include <cudf/types.hpp>
+#include <cudf/utilities/default_stream.hpp>
+#include <cudf/utilities/memory_resource.hpp>
+
+extern "C" {
+
+JNIEXPORT jlong JNICALL Java_ai_rapids_cudf_VariantUtils_getVariantFieldValue(
+  JNIEnv* env, jclass, jlong variant_struct_handle, jstring j_path)
+{
+  JNI_NULL_CHECK(env, variant_struct_handle, "variant struct column is null", 0);
+  JNI_NULL_CHECK(env, j_path, "path is null", 0);
+  JNI_TRY
+  {
+    cudf::jni::auto_set_device(env);
+    auto const& variant_struct = *reinterpret_cast<cudf::column_view const*>(variant_struct_handle);
+    cudf::jni::native_jstring path(env, j_path);
+    return cudf::jni::release_as_jlong(
+      cudf::io::parquet::experimental::get_variant_field(variant_struct,
+                                                         path.get(),
+                                                         cudf::get_default_stream(),
+                                                         cudf::get_current_device_resource_ref()));
+  }
+  JNI_CATCH(env, 0);
+}
+
+JNIEXPORT jlong JNICALL Java_ai_rapids_cudf_VariantUtils_castVariantValue(JNIEnv* env,
+                                                                          jclass,
+                                                                          jlong value_bytes_handle,
+                                                                          jint cudf_type_id)
+{
+  JNI_NULL_CHECK(env, value_bytes_handle, "value bytes column is null", 0);
+  JNI_TRY
+  {
+    cudf::jni::auto_set_device(env);
+    auto const& value_bytes = *reinterpret_cast<cudf::column_view const*>(value_bytes_handle);
+    return cudf::jni::release_as_jlong(cudf::io::parquet::experimental::cast_variant(
+      value_bytes,
+      cudf::data_type{static_cast<cudf::type_id>(cudf_type_id)},
+      cudf::get_default_stream(),
+      cudf::get_current_device_resource_ref()));
+  }
+  JNI_CATCH(env, 0);
+}
+
+JNIEXPORT jlong JNICALL Java_ai_rapids_cudf_VariantUtils_extractVariantField(
+  JNIEnv* env, jclass, jlong variant_struct_handle, jstring j_path, jint cudf_type_id)
+{
+  JNI_NULL_CHECK(env, variant_struct_handle, "variant struct column is null", 0);
+  JNI_NULL_CHECK(env, j_path, "path is null", 0);
+  JNI_TRY
+  {
+    cudf::jni::auto_set_device(env);
+    auto const& variant_struct = *reinterpret_cast<cudf::column_view const*>(variant_struct_handle);
+    cudf::jni::native_jstring path(env, j_path);
+    return cudf::jni::release_as_jlong(cudf::io::parquet::experimental::extract_variant_field(
+      variant_struct,
+      path.get(),
+      cudf::data_type{static_cast<cudf::type_id>(cudf_type_id)},
+      cudf::get_default_stream(),
+      cudf::get_current_device_resource_ref()));
+  }
+  JNI_CATCH(env, 0);
+}
+
+}  // extern "C"