Skip to content
Merged
Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
36abb36
WIP: speculative reader
TomAugspurger May 28, 2026
f6e7eca
Merge remote-tracking branch 'upstream/main' into tom/libcudf-specula…
TomAugspurger Jun 5, 2026
ab0fdd0
test edge cases
TomAugspurger Jun 5, 2026
30dc151
better error messages
TomAugspurger Jun 5, 2026
79ba978
expand C++ tests
TomAugspurger Jun 5, 2026
8aca3e3
Merge remote-tracking branch 'upstream/main' into tom/libcudf-specula…
TomAugspurger Jun 5, 2026
c5a5890
formatting
TomAugspurger Jun 5, 2026
f0f2348
test fix
TomAugspurger Jun 5, 2026
00bd441
Remove metadata_size_hint parameter
TomAugspurger Jun 8, 2026
08b47b8
remove
TomAugspurger Jun 8, 2026
a8e201b
newlines
TomAugspurger Jun 8, 2026
cd0a5db
minimize diff
TomAugspurger Jun 8, 2026
c567b10
More simplfification
TomAugspurger Jun 8, 2026
b9ec4dd
Fixup
TomAugspurger Jun 8, 2026
836ce36
Test error messages
TomAugspurger Jun 8, 2026
864769d
PR review
TomAugspurger Jun 8, 2026
9d3d2c6
Merge remote-tracking branch 'upstream/main' into tom/libcudf-specula…
TomAugspurger Jun 9, 2026
1b04e99
Update cpp/include/cudf/io/config_utils.hpp
TomAugspurger Jun 9, 2026
89c3f9e
Round 1 of reviews
TomAugspurger Jun 10, 2026
4c1638a
revamp tests
TomAugspurger Jun 10, 2026
d4eaa8e
Merge remote-tracking branch 'upstream/main' into tom/libcudf-specula…
TomAugspurger Jun 10, 2026
2705e4e
exact equality check
TomAugspurger Jun 10, 2026
f3e2cc2
simpler fast/slow path
TomAugspurger Jun 10, 2026
37537fb
Remove accidental includes
TomAugspurger Jun 10, 2026
a81ed97
Merge remote-tracking branch 'upstream/main' into tom/libcudf-specula…
TomAugspurger Jun 12, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 18 additions & 1 deletion cpp/include/cudf/io/config_utils.hpp
Original file line number Diff line number Diff line change
@@ -1,11 +1,13 @@
/*
* SPDX-FileCopyrightText: Copyright (c) 2024-2025, NVIDIA CORPORATION.
* SPDX-FileCopyrightText: Copyright (c) 2024-2026, NVIDIA CORPORATION.
* SPDX-License-Identifier: Apache-2.0
*/
#pragma once

#include <cudf/utilities/export.hpp>

#include <cstddef>

namespace CUDF_EXPORT cudf {
namespace io {
//! `KvikIO`
Expand Down Expand Up @@ -67,5 +69,20 @@ namespace integrated_memory_optimization {

/** @} */ // end of group
} // namespace integrated_memory_optimization

//! Parquet
namespace parquet_integration {
Comment thread
TomAugspurger marked this conversation as resolved.
Resolved

/**
* @brief Returns the speculative Parquet metadata read size in bytes.
*
* Controlled by the `LIBCUDF_PARQUET_METADATA_SIZE_HINT` environment variable.
* Defaults to 64 KiB.
*
* @return Number of bytes to speculatively read from the end of the source.
*/
Comment thread
TomAugspurger marked this conversation as resolved.
Resolved
[[nodiscard]] std::size_t metadata_size_hint();
Comment thread
TomAugspurger marked this conversation as resolved.
Resolved

} // namespace parquet_integration
} // namespace io
} // namespace CUDF_EXPORT cudf
26 changes: 26 additions & 0 deletions cpp/include/cudf/io/detail/parquet.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@

#include <rmm/cuda_stream_view.hpp>

#include <cstddef>
Comment thread
mhaseeb123 marked this conversation as resolved.
Resolved
#include <string>
#include <vector>

Expand Down Expand Up @@ -255,6 +256,19 @@ class writer {
*/
parquet_metadata read_parquet_metadata(host_span<std::unique_ptr<datasource> const> sources);

/**
* @brief Reads metadata of parquet dataset.
*
* @param sources Dataset sources to read from
* @param metadata_size_hint Number of bytes to speculatively read from the end of each source
* when locating and reading footer metadata
*
* @return parquet_metadata with parquet schema, number of rows, number of row groups and key-value
* metadata.
*/
parquet_metadata read_parquet_metadata(host_span<std::unique_ptr<datasource> const> sources,
std::size_t metadata_size_hint);

/**
* @brief Constructs FileMetaData objects from parquet dataset
*
Expand All @@ -265,6 +279,18 @@ parquet_metadata read_parquet_metadata(host_span<std::unique_ptr<datasource> con
std::vector<parquet::FileMetaData> read_parquet_footers(
host_span<std::unique_ptr<datasource> const> sources);

/**
* @brief Constructs FileMetaData objects from parquet dataset
*
* @param sources Input `datasource` objects to read the dataset from
* @param metadata_size_hint Number of bytes to speculatively read from the end of each source
* when locating and reading footer metadata
*
* @return List of FileMetaData objects, one per parquet source
*/
std::vector<parquet::FileMetaData> read_parquet_footers(
host_span<std::unique_ptr<datasource> const> sources, std::size_t metadata_size_hint);

} // namespace parquet::detail
} // namespace io
} // namespace CUDF_EXPORT cudf
5 changes: 4 additions & 1 deletion cpp/include/cudf/io/parquet_io_utils.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@

#include <functional>
#include <future>
#include <optional>
#include <tuple>
#include <vector>

Expand All @@ -40,10 +41,12 @@ using cudf::io::text::byte_range_info;
* @ingroup io_utils
*
* @param datasource Input data source
* @param metadata_size_hint Optional number of bytes to speculatively read from the end of the
* source when locating and reading the footer metadata. If not set, uses libcudf runtime config.
* @return Host buffer containing footer bytes
*/
[[nodiscard]] std::unique_ptr<cudf::io::datasource::buffer> fetch_footer_to_host(
cudf::io::datasource& datasource);
cudf::io::datasource& datasource, std::optional<size_t> metadata_size_hint = std::nullopt);

/**
* @brief Fetches host buffers of Parquet footer bytes from multiple input data sources
Expand Down
30 changes: 30 additions & 0 deletions cpp/include/cudf/io/parquet_metadata.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@
#include <cudf/io/types.hpp>
#include <cudf/utilities/export.hpp>

#include <cstddef>
#include <string_view>
#include <vector>

Expand Down Expand Up @@ -282,6 +283,20 @@ class parquet_metadata {
*/
parquet_metadata read_parquet_metadata(source_info const& src_info);

/**
* @brief Reads metadata of parquet dataset
*
* @ingroup io_readers
*
* @param src_info Dataset source information
* @param metadata_size_hint Number of bytes to speculatively read from the end of each source
* when locating and reading footer metadata
*
* @return parquet_metadata with parquet schema, number of rows, number of row groups and key-value
* metadata
*/
parquet_metadata read_parquet_metadata(source_info const& src_info, std::size_t metadata_size_hint);

/**
* @brief Constructs FileMetaData objects from parquet dataset
*
Expand All @@ -294,6 +309,21 @@ parquet_metadata read_parquet_metadata(source_info const& src_info);
std::vector<parquet::FileMetaData> read_parquet_footers(
cudf::host_span<std::unique_ptr<cudf::io::datasource> const> sources);

/**
* @brief Constructs FileMetaData objects from parquet dataset
*
* @ingroup io_readers
*
* @param sources Input `datasource` objects to read the dataset from
* @param metadata_size_hint Number of bytes to speculatively read from the end of each source
* when locating and reading footer metadata
*
* @return List of FileMetaData objects, one per parquet source
*/
std::vector<parquet::FileMetaData> read_parquet_footers(
cudf::host_span<std::unique_ptr<cudf::io::datasource> const> sources,
std::size_t metadata_size_hint);

/** @} */ // end of group
} // namespace io
} // namespace CUDF_EXPORT cudf
15 changes: 15 additions & 0 deletions cpp/src/io/functions.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -660,13 +660,28 @@ parquet_metadata read_parquet_metadata(source_info const& src_info)
return detail_parquet::read_parquet_metadata(datasources);
}

parquet_metadata read_parquet_metadata(source_info const& src_info, std::size_t metadata_size_hint)
{
CUDF_FUNC_RANGE();

auto datasources = make_datasources(src_info);
return detail_parquet::read_parquet_metadata(datasources, metadata_size_hint);
}

std::vector<parquet::FileMetaData> read_parquet_footers(
host_span<std::unique_ptr<cudf::io::datasource> const> sources)
{
CUDF_FUNC_RANGE();
return detail_parquet::read_parquet_footers(sources);
}

std::vector<parquet::FileMetaData> read_parquet_footers(
host_span<std::unique_ptr<cudf::io::datasource> const> sources, std::size_t metadata_size_hint)
{
CUDF_FUNC_RANGE();
return detail_parquet::read_parquet_footers(sources, metadata_size_hint);
}

/**
* @copydoc cudf::io::merge_row_group_metadata
*/
Expand Down
85 changes: 63 additions & 22 deletions cpp/src/io/parquet/io_utils/parquet_io_utils.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@
#include <cudf/detail/utilities/cuda_memcpy.hpp>
#include <cudf/detail/utilities/host_worker_pool.hpp>
#include <cudf/detail/utilities/integer_utils.hpp>
#include <cudf/io/config_utils.hpp>
#include <cudf/io/datasource.hpp>
#include <cudf/io/parquet.hpp>
#include <cudf/io/parquet_io_utils.hpp>
Expand All @@ -22,12 +23,15 @@
#include <cuda/iterator>
#include <cuda/std/tuple>

#include <algorithm>
#include <cstring>
#include <functional>
#include <mutex>
#include <numeric>
#include <stdexcept>
#include <tuple>
#include <type_traits>
#include <vector>

/**
* @file parquet_io_utils.cpp
Expand Down Expand Up @@ -80,29 +84,68 @@ auto dispatch_fetch_tasks(std::size_t num_sources, Task fetch_task)
return results;
}

[[nodiscard]] std::unique_ptr<cudf::io::datasource::buffer> fetch_footer_buffer(
cudf::io::datasource& datasource, size_t metadata_size_hint)
{
constexpr auto header_len = sizeof(file_header_s);
Comment thread
TomAugspurger marked this conversation as resolved.
Resolved
constexpr auto ender_len = sizeof(file_ender_s);
size_t const len = datasource.size();
CUDF_EXPECTS(len > header_len + ender_len, "Incorrect data source");
Comment thread
TomAugspurger marked this conversation as resolved.
Resolved

auto const speculative_read_size =
std::min(len, std::max(metadata_size_hint, static_cast<size_t>(ender_len)));
Comment thread
TomAugspurger marked this conversation as resolved.
Resolved
auto const speculative_read_offset = len - speculative_read_size;

auto speculative_buffer = datasource.host_read(speculative_read_offset, speculative_read_size);
CUDF_EXPECTS(speculative_buffer->size() >= ender_len,
"Failed to read Parquet footer ender bytes");
Comment thread
TomAugspurger marked this conversation as resolved.
Resolved

file_ender_s ender{};
std::memcpy(
&ender, speculative_buffer->data() + speculative_buffer->size() - ender_len, ender_len);

if (speculative_read_offset == 0) {
file_header_s header{};
std::memcpy(&header, speculative_buffer->data(), header_len);
CUDF_EXPECTS(header.magic == detail::parquet_magic, "Corrupted header");
}

CUDF_EXPECTS(ender.magic == detail::parquet_magic, "Corrupted footer");
CUDF_EXPECTS(ender.footer_len != 0 && ender.footer_len <= (len - header_len - ender_len),
"Incorrect footer length");

auto const footer_offset = len - ender.footer_len - ender_len;
if (footer_offset >= speculative_read_offset) {
auto const footer_start_offset = footer_offset - speculative_read_offset;
CUDF_EXPECTS(footer_start_offset + ender.footer_len <= speculative_buffer->size(),
"Speculative metadata read did not include the full footer bytes");
std::vector<uint8_t> footer_bytes(ender.footer_len);
std::memcpy(
footer_bytes.data(), speculative_buffer->data() + footer_start_offset, ender.footer_len);
return cudf::io::datasource::buffer::create(std::move(footer_bytes));
}

// Footer starts before the speculative read range. Read the missing prefix, then stitch.
auto const missing_prefix_size = speculative_read_offset - footer_offset;
auto missing_prefix = datasource.host_read(footer_offset, missing_prefix_size);
std::vector<uint8_t> footer_bytes(ender.footer_len);
std::memcpy(footer_bytes.data(), missing_prefix->data(), missing_prefix_size);
auto const footer_suffix_size = ender.footer_len - missing_prefix_size;
std::memcpy(
footer_bytes.data() + missing_prefix_size, speculative_buffer->data(), footer_suffix_size);
return cudf::io::datasource::buffer::create(std::move(footer_bytes));
}

/**
* @copydoc cudf::io::parquet::fetch_footers_to_host
*/
std::vector<std::unique_ptr<cudf::io::datasource::buffer>> fetch_footers_to_host_impl(
cudf::host_span<std::reference_wrapper<cudf::io::datasource> const> datasources)
{
auto const metadata_size_hint = cudf::io::parquet_integration::metadata_size_hint();
// Helper to fetch footer from a datasource
auto const fetch_footer = [](cudf::io::datasource& datasource) {
constexpr auto header_len = sizeof(file_header_s);
constexpr auto ender_len = sizeof(file_ender_s);
size_t const len = datasource.size();
CUDF_EXPECTS(len > header_len + ender_len, "Incorrect data source");

auto header_buffer = datasource.host_read(0, header_len);
auto const header = reinterpret_cast<file_header_s const*>(header_buffer->data());
auto ender_buffer = datasource.host_read(len - ender_len, ender_len);
auto const ender = reinterpret_cast<file_ender_s const*>(ender_buffer->data());
CUDF_EXPECTS(header->magic == detail::parquet_magic, "Corrupted header");
CUDF_EXPECTS(ender->magic == detail::parquet_magic, "Corrupted footer");
CUDF_EXPECTS(ender->footer_len != 0 && ender->footer_len <= (len - header_len - ender_len),
"Incorrect footer length");

return datasource.host_read(len - ender->footer_len - ender_len, ender->footer_len);
auto const fetch_footer = [metadata_size_hint](cudf::io::datasource& datasource) {
return fetch_footer_buffer(datasource, metadata_size_hint);
};

return dispatch_fetch_tasks(datasources.size(), [&](std::size_t source_idx) {
Expand Down Expand Up @@ -335,14 +378,12 @@ fetch_byte_ranges_to_device_async_impl(

} // namespace

std::unique_ptr<cudf::io::datasource::buffer> fetch_footer_to_host(cudf::io::datasource& datasource)
std::unique_ptr<cudf::io::datasource::buffer> fetch_footer_to_host(
cudf::io::datasource& datasource, std::optional<size_t> metadata_size_hint)
{
CUDF_FUNC_RANGE();

// Wrap the input into an array and delegate to the multi-source implementation
std::array<std::reference_wrapper<cudf::io::datasource>, 1> datasources{std::ref(datasource)};
auto footer_buffers = fetch_footers_to_host_impl({datasources.data(), datasources.size()});
return std::move(footer_buffers.front());
return fetch_footer_buffer(
datasource, metadata_size_hint.value_or(cudf::io::parquet_integration::metadata_size_hint()));
}

std::vector<std::unique_ptr<cudf::io::datasource::buffer>> fetch_footers_to_host(
Expand Down
21 changes: 18 additions & 3 deletions cpp/src/io/parquet/reader_impl.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@
#include <cudf/detail/structs/utilities.hpp>
#include <cudf/detail/transform.hpp>
#include <cudf/detail/utilities/stream_pool.hpp>
#include <cudf/io/config_utils.hpp>
#include <cudf/io/parquet_schema.hpp>
#include <cudf/null_mask.hpp>
#include <cudf/stream_compaction.hpp>
Expand Down Expand Up @@ -1099,6 +1100,13 @@ parquet_column_schema walk_schema(aggregate_reader_metadata const* mt, int idx)
} // namespace

parquet_metadata read_parquet_metadata(host_span<std::unique_ptr<datasource> const> sources)
{
return cudf::io::parquet::detail::read_parquet_metadata(
sources, cudf::io::parquet_integration::metadata_size_hint());
}

parquet_metadata read_parquet_metadata(host_span<std::unique_ptr<datasource> const> sources,
std::size_t metadata_size_hint)
{
// Do not use arrow schema when only reading the parquet footer metadata.
constexpr auto use_arrow_schema = false;
Expand All @@ -1110,8 +1118,8 @@ parquet_metadata read_parquet_metadata(host_span<std::unique_ptr<datasource> con
constexpr auto read_page_indexes = false;

// Open and parse the source dataset metadata
auto metadata =
aggregate_reader_metadata(sources, use_arrow_schema, has_column_projection, read_page_indexes);
auto metadata = aggregate_reader_metadata(
sources, use_arrow_schema, has_column_projection, read_page_indexes, metadata_size_hint);

return parquet_metadata{parquet_schema{walk_schema(&metadata, 0)},
metadata.get_num_rows(),
Expand All @@ -1124,6 +1132,13 @@ parquet_metadata read_parquet_metadata(host_span<std::unique_ptr<datasource> con

std::vector<parquet::FileMetaData> read_parquet_footers(
host_span<std::unique_ptr<datasource> const> sources)
{
return cudf::io::parquet::detail::read_parquet_footers(
sources, cudf::io::parquet_integration::metadata_size_hint());
}

std::vector<parquet::FileMetaData> read_parquet_footers(
host_span<std::unique_ptr<datasource> const> sources, std::size_t metadata_size_hint)
{
// Do not use arrow schema when only reading the parquet metadata.
constexpr auto use_arrow_schema = false;
Expand All @@ -1136,7 +1151,7 @@ std::vector<parquet::FileMetaData> read_parquet_footers(

// Parse the source dataset metadata
return aggregate_reader_metadata(
sources, use_arrow_schema, has_column_projection, read_page_indexes)
sources, use_arrow_schema, has_column_projection, read_page_indexes, metadata_size_hint)
.get_parquet_metadatas();
}

Expand Down
Loading
Loading