feat(native): Add cuDF session property provider

[pramodsatya]

Description

This change makes CUDF configurations in Velox configurable as Presto session properties by leveraging the session property provider from the native sidecar plugin. This eliminates the need to restart workers when updating CUDF configurations - they can now be applied dynamically via session properties on a per-query basis.

Implementation details:

1. Added CudfSessionProperties class that exposes cuDF configurations as Presto session properties
2. Modified sidecar session properties endpoint to return cuDF configuration properties when Presto C++ worker has cuDF enabled (is built with CMake flag PRESTO_ENABLE_CUDF=ON)

Depends on #27253.
Depends on facebookincubator/velox#16535.

Motivation and Context

CUDF configuration previously required:

1. Setting configuration files before starting workers
2. Restarting workers to apply new configurations
3. No per-query configuration flexibility

This approach made it difficult to:

• A/B test different GPU acceleration strategies
• Dynamically tune performance for different query patterns
• Update GPU memory allocation without downtime

By exposing these as Presto session properties, developers and operators can now:

• Configure GPU behavior on a per-query basis using SET SESSION
• Enable/disable CPU fallback dynamically
• Tune GPU memory and performance parameters without worker restarts

Impact

Public API Changes:

• CUDF session properties available on coordinator with native sidecar plugin
• No breaking changes to existing APIs

Compatibility:

• Fully backward compatible, existing CUDF configurations via config files still work
• Session properties take precedence when both are set
• No impact for non-GPU workloads

Test Plan

1. Unit Tests:

   • C++ unit tests for CudfSessionProperties class

2. Integration Tests:

• Added comprehensive end-to-end tests in TestCudfSidecarPlugin that validates:
  • CUDF session properties are registered and available
  • CUDF properties can be set via SET SESSION commands
  • CUDF session property is mapped to the right Velox CudfConfig during query execution
  • Non-CUDF session properties are properly excluded with sidecar

3. CI Testing:

   • Added excludes pattern to prevent CUDF tests from breaking CI/CD

4. Manual Testing:

   • Verified SHOW SESSION correctly displays all CUDF session properties

Contributor checklist

• Submission complies with contributing guide and commit standards
• PR description addresses the issue accurately
• Code follows Presto style and conventions
• Tests added and passing
• CI passes (with CUDF tests excluded from standard runs)
• No new external dependencies added

Release Notes

== RELEASE NOTES ==

Prestissimo (Native Execution) Changes
* Add support for configuring CUDF configs as Presto session properties.

Summary by Sourcery

Expose cuDF GPU configuration as native session properties and route the sidecar session property endpoint through a pluggable session-properties provider, with optional cuDF-specific implementation when GPU support is enabled.

New Features:

• Introduce a generic C++ SessionPropertiesProvider abstraction to manage and serialize session properties for native workers.
• Add CudfSessionProperties to surface cuDF GPU configuration as Presto session properties via the native sidecar when PRESTO_ENABLE_CUDF is enabled.
• Expose cuDF-specific session properties to the coordinator through the sidecar plugin and validate their behavior with a new Java integration test.

Enhancements:

• Refactor existing native SessionProperties to reuse the shared SessionPropertiesProvider base and relocate it under a dedicated properties/session module.
• Add a common boolToString utility for consistent boolean-to-string conversion across session property initialization.

Build:

• Restructure CMake to build session properties as a dedicated module, conditionally linking a cuDF-specific session properties library into the native server when GPU support is enabled and wiring up corresponding unit test targets.

CI:

• Exclude cuDF Java tests from the default prestocpp Linux build-and-unit-test workflow to keep CI stable when GPU support is unavailable.

Tests:

• Add C++ unit tests for CudfSessionProperties and move SessionProperties tests under the new properties/session test suite.
• Extend native Hive query runner utilities and add a Java TestCudfSidecarPlugin integration test to verify registration and filtering of cuDF session properties.

[sourcery-ai]

Reviewer's Guide

Refactors native session property handling into a reusable provider framework, relocates session property code into a dedicated module, and adds cuDF-specific session properties that are surfaced via the native sidecar endpoint when GPU support is enabled, along with tests and CI wiring.

Sequence diagram for sidecar sessionProperties endpoint with optional cuDF support

sequenceDiagram
  actor JavaCoordinator
  participant SidecarPlugin
  participant NativeWorker
  participant PrestoServer
  participant SessionProps as SessionPropertiesProvider

  JavaCoordinator->>SidecarPlugin: request session properties
  SidecarPlugin->>NativeWorker: HTTP GET /v1/sessionProperties
  NativeWorker->>PrestoServer: dispatch request

  alt PRESTO_ENABLE_CUDF defined
    PrestoServer->>SessionProps: CudfSessionProperties::instance()
  else
    PrestoServer->>SessionProps: SessionProperties::instance()
  end

  SessionProps-->>PrestoServer: serialize()
  PrestoServer-->>NativeWorker: JSON session properties
  NativeWorker-->>SidecarPlugin: HTTP 200 OK
  SidecarPlugin-->>JavaCoordinator: native session properties metadata

Loading

Class diagram for session properties provider framework and cuDF session properties

classDiagram
  class SessionProperty {
    -protocol_SessionPropertyMetadata metadata_
    -optional_string veloxConfig_
    -string value_
    +SessionProperty(name, description, typeSignature, hidden, veloxConfig, defaultValue)
    +protocol_SessionPropertyMetadata getMetadata()
    +optional_string getVeloxConfig()
    +string getValue()
    +void updateValue(value)
    +bool operator==(other)
  }

  class SessionPropertiesProvider {
    <<abstract>>
    -unordered_map_string_SessionPropertyPtr sessionProperties_
    +~SessionPropertiesProvider()
    +string toVeloxConfig(name) const
    +json serialize() const
    +bool hasVeloxConfig(key)
    +void updateSessionPropertyValue(key, value)
    #void addSessionProperty(name, description, type, isHidden, veloxConfig, defaultValue)
  }

  class SessionProperties {
    <<singleton>>
    +static SessionProperties* instance()
    +SessionProperties()
    +bool useVeloxGeospatialJoin() const
  }

  class CudfSessionProperties {
    <<singleton>>
    +static CudfSessionProperties* instance()
    +CudfSessionProperties()
    +static const char* kCudfEnabled
    +static const char* kCudfDebugEnabled
    +static const char* kCudfMemoryResource
    +static const char* kCudfMemoryPercent
    +static const char* kCudfFunctionNamePrefix
    +static const char* kCudfAstExpressionEnabled
    +static const char* kCudfAstExpressionPriority
    +static const char* kCudfJitExpressionEnabled
    +static const char* kCudfJitExpressionPriority
    +static const char* kCudfAllowCpuFallback
    +static const char* kCudfLogFallback
  }

  class CudfConfig {
    <<external>>
    +static CudfConfig& getInstance()
    +bool enabled
    +bool debugEnabled
    +string memoryResource
    +int memoryPercent
    +string functionNamePrefix
    +bool astExpressionEnabled
    +int astExpressionPriority
    +bool jitExpressionEnabled
    +int jitExpressionPriority
    +bool allowCpuFallback
    +bool logFallback
  }

  SessionPropertiesProvider o--> SessionProperty
  SessionProperties --|> SessionPropertiesProvider
  CudfSessionProperties --|> SessionPropertiesProvider
  CudfSessionProperties ..> CudfConfig

Loading

File-Level Changes

Change	Details	Files
Introduce a reusable SessionPropertiesProvider base and migrate existing native session properties to it.	Extract SessionProperty and session management logic into a new SessionPropertiesProvider base class with shared add/serialize/toVeloxConfig/update APIs. Update SessionProperties to inherit from SessionPropertiesProvider and move the implementation into the new properties/session module. Ensure serialized session property type signatures are consistently lowercased and boolean defaults use a shared boolToString helper.	presto-native-execution/presto_cpp/main/properties/session/SessionPropertiesProvider.h presto-native-execution/presto_cpp/main/properties/session/SessionPropertiesProvider.cpp presto-native-execution/presto_cpp/main/properties/session/SessionProperties.h presto-native-execution/presto_cpp/main/properties/session/SessionProperties.cpp presto-native-execution/presto_cpp/main/common/Utils.h presto-native-execution/presto_cpp/main/common/Utils.cpp
Add cuDF-specific session properties and wire them into the sidecar session properties endpoint when cuDF is enabled.	Define CudfSessionProperties as a SessionPropertiesProvider subclass that initializes all cuDF-related session properties from CudfConfig, including velox config mappings and type metadata. Switch the sidecar /v1/session-properties endpoint to serialize CudfSessionProperties when PRESTO_ENABLE_CUDF is enabled, falling back to SessionProperties otherwise. Add C++ tests to validate cuDF session property initialization, metadata, default values, and velox config name mapping.	presto-native-execution/presto_cpp/main/properties/session/CudfSessionProperties.h presto-native-execution/presto_cpp/main/properties/session/CudfSessionProperties.cpp presto-native-execution/presto_cpp/main/PrestoServer.cpp presto-native-execution/presto_cpp/main/properties/session/tests/CudfSessionPropertiesTest.cpp
Restructure CMake and test wiring to support the new session properties modules and cuDF variants.	Replace the old presto_session_properties library with a properties submodule that builds presto_session_properties by default and presto_cudf_session_properties when cuDF is enabled. Update presto_server_lib linkage to conditionally link against presto_cudf_session_properties when PRESTO_ENABLE_CUDF is ON, otherwise link against presto_session_properties. Move SessionPropertiesTest into the new properties/session/tests target and add a separate cuDF session properties test executable when cuDF is enabled.	presto-native-execution/presto_cpp/main/CMakeLists.txt presto-native-execution/presto_cpp/main/properties/CMakeLists.txt presto-native-execution/presto_cpp/main/properties/session/CMakeLists.txt presto-native-execution/presto_cpp/main/properties/session/tests/CMakeLists.txt presto-native-execution/presto_cpp/main/properties/session/tests/SessionPropertiesTest.cpp presto-native-execution/presto_cpp/main/tests/CMakeLists.txt
Ensure native-side Java tests discover cuDF sidecar behavior while excluding them from default CI runs.	Add a dedicated TestCudfSidecarPlugin Java test that boots a native-backed query runner with the sidecar enabled, installs the NativeSidecarPlugin, and verifies cuDF session properties can be discovered, set via SET SESSION, and that non-cuDF properties are excluded. Extend the native query runner builder with an addExtraProperties helper to merge arbitrary extra properties for tests. Adjust the GitHub Actions native Java test discovery to skip cuDF tests by path so they do not run in standard CI workflows.	presto-native-tests/src/test/java/com/facebook/presto/nativetests/cudf/TestCudfSidecarPlugin.java presto-native-execution/src/test/java/com/facebook/presto/nativeworker/PrestoNativeQueryRunnerUtils.java .github/workflows/prestocpp-linux-build-and-unit-test.yml
Update native code includes to reference the relocated session properties module.	Switch includes from the old SessionProperties header path to the new properties/session/SessionProperties.h in native server, planner, and query config sources. Remove the old SessionPropertiesTest target from the main tests CMake in favor of the relocated test target.	presto-native-execution/presto_cpp/main/PrestoServer.cpp presto-native-execution/presto_cpp/main/PrestoToVeloxQueryConfig.cpp presto-native-execution/presto_cpp/main/QueryContextManager.cpp presto-native-execution/presto_cpp/main/types/PrestoToVeloxQueryPlan.cpp presto-native-execution/presto_cpp/main/tests/PrestoToVeloxQueryConfigTest.cpp presto-native-execution/presto_cpp/main/tests/CMakeLists.txt

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've found 2 issues, and left some high level feedback:

• In PrestoServer::registerSidecarEndpoints, when PRESTO_ENABLE_CUDF is set you completely replace the native SessionProperties with CudfSessionProperties; consider merging/combining the two so the sidecar exposes both standard native and cuDF session properties instead of dropping the former when GPUs are enabled.
• The CMake setup builds CudfSessionProperties.cpp into both presto_session_properties and presto_cudf_session_properties, and the CUDF tests link both libraries; this likely produces duplicate symbol/ODR issues, so it would be cleaner to have CudfSessionProperties compiled into exactly one library and have the other target depend on it rather than re-listing the same sources.
• CudfSessionProperties defines kCudfTopNBatchSize but never registers it in the constructor or validates it in tests, which makes the constant dead and potentially misleading; either wire it up as an actual session property or remove it until it is going to be used.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- In PrestoServer::registerSidecarEndpoints, when PRESTO_ENABLE_CUDF is set you completely replace the native SessionProperties with CudfSessionProperties; consider merging/combining the two so the sidecar exposes both standard native and cuDF session properties instead of dropping the former when GPUs are enabled.
- The CMake setup builds CudfSessionProperties.cpp into both presto_session_properties and presto_cudf_session_properties, and the CUDF tests link both libraries; this likely produces duplicate symbol/ODR issues, so it would be cleaner to have CudfSessionProperties compiled into exactly one library and have the other target depend on it rather than re-listing the same sources.
- CudfSessionProperties defines kCudfTopNBatchSize but never registers it in the constructor or validates it in tests, which makes the constant dead and potentially misleading; either wire it up as an actual session property or remove it until it is going to be used.

## Individual Comments

### Comment 1
<location path="presto-native-execution/presto_cpp/main/properties/session/CudfSessionProperties.h" line_range="65-72" />
<code_context>
+  /// Log reasons for CPU fallback
+  static constexpr const char* kCudfLogFallback = "cudf_log_fallback";
+
+  /// Batch size used by cuDF TopN operator before merging partial results
+  static constexpr const char* kCudfTopNBatchSize = "cudf_topn_batch_size";
+
+  /// Get singleton instance
</code_context>
<issue_to_address>
**suggestion (bug_risk):** kCudfTopNBatchSize is declared but not initialized in CudfSessionProperties, which may indicate a missing property registration.

This constant is defined but never registered via addSessionProperty in the CudfSessionProperties constructor. If TopN batch size should be session-configurable, please hook it up there like the other properties. If not, consider removing it to avoid implying a configurable setting that doesn’t exist.

```suggestion
  /// Log reasons for CPU fallback
  static constexpr const char* kCudfLogFallback = "cudf_log_fallback";

  /// Get singleton instance
  static CudfSessionProperties* instance();
```
</issue_to_address>

### Comment 2
<location path="presto-native-execution/presto_cpp/main/properties/session/tests/CudfSessionPropertiesTest.cpp" line_range="63-70" />
<code_context>
+  const auto sessionProps = CudfSessionProperties::instance();
+  const auto& serialized = sessionProps->serialize();
+
+  // Helper to find property value by name
+  auto findPropertyValue = [&serialized](const std::string& name) {
+    for (const auto& prop : serialized) {
+      if (prop["name"] == name) {
+        return prop["defaultValue"].get<std::string>();
+      }
+    }
+    return std::string();
+  };
+
</code_context>
<issue_to_address>
**suggestion (testing):** Tighten `defaultValuesMatchConfig` to assert properties exist before comparing default values

In `defaultValuesMatchConfig`, `findPropertyValue` returns an empty string when a property is missing, so failures appear as default mismatches rather than clearly indicating a missing/misnamed property. Adding an explicit assertion (e.g., `ASSERT_FALSE(result.empty())`) for expected properties would make test failures clearly signal that the property wasn’t found.

Suggested implementation:

```cpp
#include <optional>

#include "presto_cpp/main/properties/session/CudfSessionProperties.h"
#include "velox/experimental/cudf/CudfConfig.h"

```

```cpp
  const auto sessionProps = CudfSessionProperties::instance();
  const auto& serialized = sessionProps->serialize();

  // Helper to find property value by name
  auto findPropertyValue =
      [&serialized](const std::string& name) -> std::optional<std::string> {
        for (const auto& prop : serialized) {
          if (prop["name"] == name) {
            return prop["defaultValue"].get<std::string>();
          }
        }
        return std::nullopt;
      };

```

To fully implement the suggestion “assert properties exist before comparing default values”, you should update the code *inside* `defaultValuesMatchConfig` wherever `findPropertyValue` is used. For each expected property:

1. Replace direct uses like:
   ```c++
   const auto actualDefault = findPropertyValue(expectedName);
   EXPECT_EQ(expectedDefault, actualDefault);
   ```
   with:
   ```c++
   const auto actualDefault = findPropertyValue(expectedName);
   ASSERT_TRUE(actualDefault.has_value())
       << "Property " << expectedName << " not found in session properties";
   EXPECT_EQ(expectedDefault, *actualDefault);
   ```
2. Ensure this pattern is applied for every expected property the test checks, so a missing/misnamed property causes the `ASSERT_TRUE` to fire with a clear “not found” message instead of being reported as a value mismatch.
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[pramodsatya]

@majetideepak, could you help review this change? This is 1/3 changes for cuDF sidecar support and adds cuDF session property provider. cuDF functions and plan validation will be added in subsequent PRs (ref: #27164)

[pramodsatya]

@sourcery-ai review.

[sourcery-ai]

Hey - I've found 1 issue, and left some high level feedback:

• The CudfSessionPropertiesTest.propertiesInitialized test asserts serialized.size() == 11, which will make the test fragile when adding or removing CUDF session properties; consider checking only for the presence of the expected property names (as you already do) and dropping the hard-coded count.
• SessionPropertiesProvider.cpp is compiled into both presto_session_properties and presto_cudf_session_properties; to avoid duplicate compilation and potential ODR/linking surprises, consider factoring it into a separate common library that both targets link against instead of compiling the same source into two libraries.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The `CudfSessionPropertiesTest.propertiesInitialized` test asserts `serialized.size() == 11`, which will make the test fragile when adding or removing CUDF session properties; consider checking only for the presence of the expected property names (as you already do) and dropping the hard-coded count.
- `SessionPropertiesProvider.cpp` is compiled into both `presto_session_properties` and `presto_cudf_session_properties`; to avoid duplicate compilation and potential ODR/linking surprises, consider factoring it into a separate common library that both targets link against instead of compiling the same source into two libraries.

## Individual Comments

### Comment 1
<location path="presto-native-execution/presto_cpp/main/PrestoServer.cpp" line_range="79-83" />
<code_context>
 #include "velox/serializers/UnsafeRowSerializer.h"

 #ifdef PRESTO_ENABLE_CUDF
+#include "presto_cpp/main/properties/session/CudfSessionProperties.h"
 #include "velox/experimental/cudf/CudfConfig.h"
 #include "velox/experimental/cudf/exec/ToCudf.h"
 #endif
</code_context>
<issue_to_address>
**issue (bug_risk):** Sidecar /v1/native/session/properties now returns only cuDF properties when cuDF is enabled, dropping the existing native session properties.

With PRESTO_ENABLE_CUDF enabled, this endpoint now serializes only `CudfSessionProperties` instead of the full `SessionProperties`, so `/v1/native/session/properties` no longer returns the complete native worker properties. If callers rely on the full set, this is a behavioral regression.

Please either merge both `SessionProperties` and `CudfSessionProperties` into one response, or keep the original payload here and surface cuDF session properties via a separate or aggregating provider, so enabling cuDF doesn’t change the existing API contract unexpectedly.
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}