Select Parquet columns by field ID

cpp/include/cudf/io/parquet.hpp

@@ -67,11 +67,14 @@ class parquet_reader_options_builder;
 class parquet_reader_options {
   source_info _source;
 
+  // Column selection options. At most one of these may be set at a time.
+
   // Path in schema of column names to read; `nullopt` is all
   std::optional<std::vector<std::string>> _column_names;
-  // Indices of top-level columns to read; `nullopt` is all (cannot be used alongside
-  // `_column_names`)
+  // Indices of top-level columns to read; `nullopt` is all
   std::optional<std::vector<cudf::size_type>> _column_indices;
+  // Parquet field IDs of columns/fields to read; `nullopt` is all
+  std::optional<std::vector<int32_t>> _column_field_ids;
 
   // List of individual row groups to read (ignored if empty)
   std::vector<std::vector<size_type>> _row_groups;
@@ -258,6 +261,13 @@ class parquet_reader_options {
    */
   [[nodiscard]] auto const& get_column_indices() const { return _column_indices; }
 
+  /**
+   * @brief Returns Parquet field IDs of columns/fields to be read, if set.
+   *
+   * @return Parquet field IDs of columns/fields to be read; `nullopt` if the option is not set
+   */
+  [[nodiscard]] auto const& get_column_field_ids() const { return _column_field_ids; }
+
   /**
    * @brief Returns list of individual row groups to be read.
    *
@@ -386,6 +396,8 @@ class parquet_reader_options {
   {
     CUDF_EXPECTS(not _column_indices.has_value(),
                  "Cannot select columns by indices and names simultaneously");
+    CUDF_EXPECTS(not _column_field_ids.has_value(),
+                 "Cannot select columns by field IDs and names simultaneously");
     _column_names = std::move(column_names);
   }
 
@@ -404,9 +416,26 @@ class parquet_reader_options {
   {
     CUDF_EXPECTS(not _column_names.has_value(),
                  "Cannot select columns by indices and names simultaneously");
+    CUDF_EXPECTS(not _column_field_ids.has_value(),
+                 "Cannot select columns by field IDs and indices simultaneously");
     _column_indices = std::move(col_indices);
   }
 
+  /**
+   * @brief Sets the Parquet field IDs of columns/fields to be read from all input sources.
+   *
+   * @param column_field_ids A vector of Parquet field IDs to attempt to read from each input
+   * source.
+   */
+  void set_column_field_ids(std::vector<int32_t> column_field_ids)
+  {
+    CUDF_EXPECTS(not _column_names.has_value(),
+                 "Cannot select columns by field IDs and names simultaneously");
+    CUDF_EXPECTS(not _column_indices.has_value(),
+                 "Cannot select columns by field IDs and indices simultaneously");
+    _column_field_ids = std::move(column_field_ids);
+  }
+
   /**
    * @brief Specifies which row groups to read from each input source.
    *
@@ -647,6 +676,19 @@ class parquet_reader_options_builder {
     return *this;
   }
 
+  /**
+   * @brief Sets the Parquet field IDs of columns/fields to be read from all input sources.
+   *
+   * @param column_field_ids A vector of Parquet field IDs to attempt to read from each input
+   * source.
+   * @return this for chaining
+   */
+  parquet_reader_options_builder& column_field_ids(std::vector<int32_t> column_field_ids)
+  {
+    options.set_column_field_ids(std::move(column_field_ids));
+    return *this;
+  }
+
   /**
    * @copydoc parquet_reader_options::set_row_groups
    * @return this for chaining

cpp/src/io/parquet/column_path_helpers.cpp

@@ -1,19 +1,37 @@
 /*
- * SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION.
+ * SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
  * SPDX-License-Identifier: Apache-2.0
  */
 
 #include "column_path_helpers.hpp"
 
+#include <cudf/io/parquet_schema.hpp>
+
 #include <algorithm>
 #include <cctype>
 #include <cstddef>
 #include <functional>
+#include <numeric>
 #include <string>
 #include <string_view>
+#include <utility>
+#include <vector>
 
 namespace cudf::io::parquet::detail {
 
+std::string column_path_from_index(std::span<SchemaElement const> schema_tree, int schema_idx)
+{
+  std::vector<std::string> path;
+  for (auto idx = schema_idx; idx > 0; idx = schema_tree[idx].parent_idx) {
+    path.push_back(schema_tree[idx].name);
+  }
+
+  return std::accumulate(
+    path.rbegin() + 1, path.rend(), path.back(), [](auto path_so_far, auto const& elem_name) {
+      return std::move(path_so_far) + "." + elem_name;
+    });
+}
+
 std::string normalize_column_path(std::string_view col_path, bool case_sensitive_names)
 {
   if (case_sensitive_names) { return std::string{col_path}; }

cpp/src/io/parquet/column_path_helpers.hpp

@@ -1,18 +1,31 @@
 /*
- * SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION.
+ * SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
  * SPDX-License-Identifier: Apache-2.0
  */
 
 #pragma once
 
+#include <cudf/io/parquet_schema.hpp>
+
 #include <cstddef>
+#include <span>
 #include <string>
 #include <string_view>
 #include <unordered_map>
 #include <unordered_set>
 
 namespace cudf::io::parquet::detail {
 
+/**
+ * @brief Gets the dot-separated path for a schema element.
+ *
+ * @param schema_tree The schema tree describing the file structure
+ * @param schema_idx Index of the schema element
+ * @return Dot-separated schema path from the root child to the schema element
+ */
+[[nodiscard]] std::string column_path_from_index(std::span<SchemaElement const> schema_tree,
+                                                 int schema_idx);
+
 /**
  * @brief Returns a normalized (lowercased) column name or path when case-insensitive matching is
  * enabled

cpp/src/io/parquet/experimental/hybrid_scan_helpers.cpp

@@ -266,24 +266,12 @@ std::tuple<std::vector<input_column_info>,
 aggregate_reader_metadata::select_payload_columns(
   std::optional<std::vector<std::string>> const& payload_column_names,
   std::optional<std::vector<std::string>> const& filter_column_names,
-  bool include_index,
-  bool strings_to_categorical,
-  bool ignore_missing_columns,
-  type_id timestamp_type_id,
-  type_id decimal_type_id,
-  bool case_sensitive_names)
+  parquet::detail::column_selection_options const& selection_options)
 {
   // If neither payload nor filter columns are specified, select all columns
   if (not payload_column_names.has_value() and not filter_column_names.has_value()) {
     // Call the base `select_columns()` method without specifying any columns
-    return select_columns({},
-                          {},
-                          include_index,
-                          strings_to_categorical,
-                          ignore_missing_columns,
-                          timestamp_type_id,
-                          decimal_type_id,
-                          case_sensitive_names);
+    return select_columns({}, {}, selection_options);
   }
 
   std::vector<std::string> valid_payload_columns;
@@ -302,7 +290,7 @@ aggregate_reader_metadata::select_payload_columns(
     // Remove filter columns from the provided payload column names
     if (filter_column_names.has_value() and not filter_column_names->empty()) {
       auto const filter_columns_set =
-        construct_filter_columns_set(*filter_column_names, case_sensitive_names);
+        construct_filter_columns_set(*filter_column_names, selection_options.case_sensitive_names);
       // Remove a payload column name if it is also present in the hash set
       valid_payload_columns.erase(
         std::remove_if(valid_payload_columns.begin(),
@@ -311,20 +299,13 @@ aggregate_reader_metadata::select_payload_columns(
         valid_payload_columns.end());
     }
     // Call the base `select_columns()` method with valid payload columns
-    return select_columns(valid_payload_columns,
-                          {},
-                          include_index,
-                          strings_to_categorical,
-                          ignore_missing_columns,
-                          timestamp_type_id,
-                          decimal_type_id,
-                          case_sensitive_names);
+    return select_columns(valid_payload_columns, {}, selection_options);
   }
 
   // Else if only filter columns are specified, select all columns that do not appear in the
   // filter expression
   auto const filter_columns_set =
-    construct_filter_columns_set(*filter_column_names, case_sensitive_names);
+    construct_filter_columns_set(*filter_column_names, selection_options.case_sensitive_names);
 
   std::function<void(std::string, int)> add_column_path = [&](std::string path_till_now,
                                                               int schema_idx) {
@@ -341,14 +322,7 @@ aggregate_reader_metadata::select_payload_columns(
     }
   }
 
-  return select_columns(valid_payload_columns,
-                        {},
-                        include_index,
-                        strings_to_categorical,
-                        ignore_missing_columns,
-                        timestamp_type_id,
-                        decimal_type_id,
-                        case_sensitive_names);
+  return select_columns(valid_payload_columns, {}, selection_options);
 }
 
 std::vector<std::vector<cudf::size_type>>

cpp/src/io/parquet/experimental/hybrid_scan_helpers.hpp

@@ -158,12 +158,7 @@ class aggregate_reader_metadata : public aggregate_reader_metadata_base {
    *
    * @param payload_column_names List of paths of select payload column names, if any
    * @param filter_column_names List of paths of column names present only in filter, if any
-   * @param include_index Whether to always include the PANDAS index column(s)
-   * @param strings_to_categorical Type conversion parameter
-   * @param ignore_missing_columns Whether to ignore non-existent columns
-   * @param timestamp_type_id Type conversion parameter
-   * @param decimal_type_id Type conversion parameter
-   * @param case_sensitive_names Boolean indicating if column names are case sensitive
+   * @param selection_options Bundled column selection options
    *
    * @return input column information, output column buffers, list of output column schema
    * indices
@@ -172,12 +167,7 @@ class aggregate_reader_metadata : public aggregate_reader_metadata_base {
     tuple<std::vector<input_column_info>, std::vector<inline_column_buffer>, std::vector<size_type>>
     select_payload_columns(std::optional<std::vector<std::string>> const& payload_column_names,
                            std::optional<std::vector<std::string>> const& filter_column_names,
-                           bool include_index,
-                           bool strings_to_categorical,
-                           bool ignore_missing_columns,
-                           type_id timestamp_type_id,
-                           type_id decimal_type_id,
-                           bool case_sensitive_names);
+                           parquet::detail::column_selection_options const& selection_options);
 
   /**
    * @brief Filters row groups such that only the row groups that start within the byte range