Add an example to inspect parquet files and dump row group and page level metadata information

ci/run_cudf_examples.sh

@@ -9,36 +9,40 @@ trap "EXITCODE=1" ERR
 # Support customizing the examples' install location
 cd "${INSTALL_PREFIX:-${CONDA_PREFIX:-/usr}}/bin/examples/libcudf/" || exit
 
-cd basic || exit
+pushd basic || exit
 compute-sanitizer --tool memcheck basic_example
-cd ..
+popd || exit
 
-cd nested_types || exit
+pushd nested_types || exit
 compute-sanitizer --tool memcheck deduplication
-cd ..
+popd || exit
 
-cd strings || exit
+pushd strings || exit
 compute-sanitizer --tool memcheck custom_optimized names.csv
 compute-sanitizer --tool memcheck custom_prealloc names.csv
 compute-sanitizer --tool memcheck custom_with_malloc names.csv
-cd ..
+popd || exit
 
-cd string_transformers || exit
+pushd string_transformers || exit
 compute-sanitizer --tool memcheck compute_checksum_jit info.csv output.csv
 compute-sanitizer --tool memcheck extract_email_jit info.csv output.csv
 compute-sanitizer --tool memcheck extract_email_precompiled info.csv output.csv
 compute-sanitizer --tool memcheck format_phone_jit info.csv output.csv
 compute-sanitizer --tool memcheck format_phone_precompiled info.csv output.csv
 compute-sanitizer --tool memcheck localize_phone_jit info.csv output.csv
 compute-sanitizer --tool memcheck localize_phone_precompiled info.csv output.csv
-cd ..
+popd || exit
 
-cd parquet_io || exit
+pushd parquet_io || exit
 compute-sanitizer --tool memcheck parquet_io example.parquet
 compute-sanitizer --tool memcheck parquet_io example.parquet output.parquet DELTA_BINARY_PACKED ZSTD TRUE
 
 compute-sanitizer --tool memcheck parquet_io_multithreaded example.parquet
 compute-sanitizer --tool memcheck parquet_io_multithreaded example.parquet 4 DEVICE_BUFFER 2 2
-cd ..
+popd || exit
+
+pushd parquet_inspect || exit
+compute-sanitizer --tool memcheck parquet_inspect example.parquet
+popd || exit
 
 exit ${EXITCODE}

cpp/examples/build.sh

@@ -61,5 +61,6 @@ build_example basic
 build_example strings
 build_example string_transforms
 build_example nested_types
+build_example parquet_inspect
 build_example parquet_io
 build_example billion_rows

cpp/examples/parquet_inspect/CMakeLists.txt

@@ -0,0 +1,42 @@
+# Copyright (c) 2024-2025, NVIDIA CORPORATION.
+
+cmake_minimum_required(VERSION 3.30.4 FATAL_ERROR)
+
+include(../set_cuda_architecture.cmake)
+
+# initialize cuda architecture
+rapids_cuda_init_architectures(parquet_inspect)
+
+project(
+  parquet_inspect
+  VERSION 0.0.1
+  LANGUAGES CXX CUDA
+)
+
+include(../fetch_dependencies.cmake)
+
+include(rapids-cmake)
+rapids_cmake_build_type("Release")
+
+# For now, disable CMake's automatic module scanning for C++ files. There is an sccache bug in the
+# version RAPIDS uses in CI that causes it to handle the resulting -M* flags incorrectly with
+# gcc>=14. We can remove this once we upgrade to a newer sccache version.
+set(CMAKE_CXX_SCAN_FOR_MODULES OFF)
+
+add_library(parquet_inspect_utils OBJECT parquet_inspect_utils.cpp)
+target_compile_features(parquet_inspect_utils PRIVATE cxx_std_20)
+target_link_libraries(parquet_inspect_utils PRIVATE cudf::cudf)
+
+# Build and install parquet_inspect
+add_executable(parquet_inspect parquet_inspect.cpp)
+target_link_libraries(
+  parquet_inspect PRIVATE cudf::cudf $<BUILD_LOCAL_INTERFACE:nvtx3::nvtx3-cpp>
+                          $<TARGET_OBJECTS:parquet_inspect_utils>
+)
+target_compile_features(parquet_inspect PRIVATE cxx_std_20)
+install(TARGETS parquet_inspect DESTINATION bin/examples/libcudf/parquet_inspect)
+
+# Install the example.parquet file
+install(FILES ${CMAKE_CURRENT_LIST_DIR}/example.parquet
+        DESTINATION bin/examples/libcudf/parquet_inspect
+)

cpp/examples/parquet_inspect/parquet_inspect.cpp

@@ -0,0 +1,106 @@
+/*
+ * Copyright (c) 2025, NVIDIA CORPORATION.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include "parquet_inspect_utils.hpp"
+
+#include <cudf/io/parquet_schema.hpp>
+#include <cudf/io/types.hpp>
+
+#include <rmm/cuda_stream_view.hpp>
+
+#include <filesystem>
+#include <iostream>
+#include <string>
+
+/**
+ * @file parquet_inspect.cpp
+ * @brief Inspects a parquet file and writes two parquet files containing row group and page
+ * metadata respectively.
+ */
+
+namespace {
+
+/**
+ * @brief Function to print example usage and argument information.
+ */
+void print_usage()
+{
+  std::cout << "\nUsage: parquet_inspect <input parquet file> <output path>\n\n";
+}
+
+}  // namespace
+
+/**
+ * @brief Main for parquet_inspect examples
+ *
+ * Command line parameters:
+ * 1. parquet input file name (default: "example.parquet")
+ * 2. parquet output path (default: "$pwd")
+ *
+ * Example invocation from directory `cudf/cpp/examples/parquet_inspect`:
+ * ./build/parquet_inspect example.parquet ./
+ */
+int main(int argc, char const** argv)
+{
+  std::string input_filepath                          = "example.parquet";
+  std::string output_path                             = std::filesystem::current_path().string();
+  std::optional<cudf::io::statistics_freq> page_stats = std::nullopt;
+
+  switch (argc) {
+    case 3: output_path = argv[2]; [[fallthrough]];
+    case 2:  // Check if instead of input_paths, the first argument is `-h` or `--help`
+    {
+      auto const arg = std::string{argv[1]};
+      if (arg == "-h" or arg == "--help") {
+        print_usage();
+        return 0;
+      } else if (arg != "-h" and arg != "--help") {
+        input_filepath = std::filesystem::absolute(arg).string();
+        break;
+      }
+      [[fallthrough]];
+    }
+    default: print_usage(); throw std::runtime_error("Invalid arguments");
+  }
+
+  CUDF_EXPECTS(
+    std::filesystem::exists(input_filepath) and std::filesystem::is_regular_file(input_filepath),
+    "Input file '" + input_filepath + "' does not exist or is not a regular file.",
+    std::invalid_argument);
+
+  auto const filename = std::filesystem::path(input_filepath).stem().string();
+
+  auto const stream = cudf::get_default_stream();
+  auto const mr     = create_memory_resource(true);
+  cudf::set_current_device_resource(mr.get());
+
+  // Read parquet footer metadata
+  auto [metadata, has_page_index] = read_parquet_file_metadata(input_filepath);
+
+  // Write row group metadata
+  auto output_filepath = output_path + "/" + filename + ".rowgroups.parquet";
+  write_rowgroup_metadata(metadata, output_filepath, stream);
+
+  // Write page metadata
+  if (has_page_index) {
+    auto output_filepath = output_path + "/" + filename + ".pages.parquet";
+    write_page_metadata(metadata, output_filepath, stream);
+  }
+
+  stream.synchronize();
+
+  return 0;
+}