From 9ad6610318a4a4963db7112aad7c29c26a3f7383 Mon Sep 17 00:00:00 2001 From: Prateek Gaur Date: Thu, 12 Nov 2026 19:21:15 +0000 Subject: [PATCH 1/3] [C++][Parquet] Sample whole vectors across the page for the ALP preset The first sampling level now takes 8 vectors spread evenly over each 131,072-value window of a page and 32 values at stratified pseudo-random positions across each vector, after the ALP paper's 8 vectors and 32 values. The chunk, interval and prefix rules are gone. --- cpp/src/arrow/util/alp/alp_compression.cc | 5 +- .../arrow/util/alp/alp_compression_internal.h | 2 +- .../arrow/util/alp/alp_constants_internal.h | 20 +-- cpp/src/arrow/util/alp/alp_sampler.cc | 124 ++++++++--------- cpp/src/arrow/util/alp/alp_sampler_internal.h | 30 +++-- cpp/src/arrow/util/alp/alp_test.cc | 125 ++++++++++++++++++ 6 files changed, 213 insertions(+), 93 deletions(-) diff --git a/cpp/src/arrow/util/alp/alp_compression.cc b/cpp/src/arrow/util/alp/alp_compression.cc index 3ba243c7dd4f..54c53ce9b706 100644 --- a/cpp/src/arrow/util/alp/alp_compression.cc +++ b/cpp/src/arrow/util/alp/alp_compression.cc @@ -306,10 +306,11 @@ AlpEncodingPreset AlpCompression::MakePreset( template std::vector AlpCompression::CreateSample(std::span inputs) { - // Pick an equidistant stride so the sample count is capped at kSamplesPerChunk. + // Pick an equidistant stride so the sample count is capped at + // kSearchSamplesPerVector. const int32_t idx_increments = std::max( 1, static_cast(std::ceil(static_cast(inputs.size()) / - AlpSamplingOptions::kSamplesPerChunk))); + AlpSamplingOptions::kSearchSamplesPerVector))); const size_t increment = static_cast(idx_increments); std::vector sample; sample.reserve((inputs.size() + increment - 1) / increment); diff --git a/cpp/src/arrow/util/alp/alp_compression_internal.h b/cpp/src/arrow/util/alp/alp_compression_internal.h index 99464785f2e2..20ad2c4a66be 100644 --- a/cpp/src/arrow/util/alp/alp_compression_internal.h +++ b/cpp/src/arrow/util/alp/alp_compression_internal.h @@ -66,7 +66,7 @@ class ARROW_EXPORT AlpCompression { /// Creates an encoding preset from the collected samples. /// - /// Each element is one strided sample from a sampling chunk. + /// Each element is the sample of one vector and casts one vote. static AlpEncodingPreset MakePreset(const std::vector>& samples); /// Decompresses a view into caller-provided outputs and reusable scratch space. diff --git a/cpp/src/arrow/util/alp/alp_constants_internal.h b/cpp/src/arrow/util/alp/alp_constants_internal.h index 53e64d38727f..f6c8b166cc50 100644 --- a/cpp/src/arrow/util/alp/alp_constants_internal.h +++ b/cpp/src/arrow/util/alp/alp_constants_internal.h @@ -60,22 +60,24 @@ static_assert(sizeof(AlpFormatConstants::PositionType) == 2); // Sampling and parameter-search tuning struct AlpSamplingOptions { - /// Input elements per sampling chunk. - static constexpr int64_t kChunkSize = 4096; + /// Values per sampling window: 128 vectors, the power of two nearest the ALP + /// paper's row group of 100 vectors (section 4, "Sampling Parameters"). + static constexpr int64_t kSampleWindowSize = 131072; - /// Elements per sampling interval. - static constexpr int64_t kIntervalSize = 122880; + /// Vectors sampled from each window. The ALP paper samples 8 per row group. + static constexpr int64_t kSampledVectors = 8; - /// Samples collected per chunk. - static constexpr int64_t kSamplesPerChunk = 256; + /// Values sampled from each sampled vector. The ALP paper uses 32. + static constexpr int64_t kSamplesPerVector = 32; - /// Chunks sampled per interval. - static constexpr int64_t kSampleChunksPerInterval = 8; + /// Values sampled from a vector when choosing among preset combinations. + static constexpr int64_t kSearchSamplesPerVector = 256; /// Consecutive non-improving combinations before an early exit. static constexpr uint8_t kEarlyExitThreshold = 4; - /// Maximum exponent-factor combinations retained in a preset. + /// Maximum exponent-factor combinations retained in a preset. The ALP paper + /// keeps 5. static constexpr uint8_t kMaxCombinations = 5; static_assert(kMaxCombinations > kEarlyExitThreshold, diff --git a/cpp/src/arrow/util/alp/alp_sampler.cc b/cpp/src/arrow/util/alp/alp_sampler.cc index f1f2ddc9d1b2..4c6e6ab5e555 100644 --- a/cpp/src/arrow/util/alp/alp_sampler.cc +++ b/cpp/src/arrow/util/alp/alp_sampler.cc @@ -18,6 +18,7 @@ #include "arrow/util/alp/alp_sampler_internal.h" #include +#include #include #include @@ -30,95 +31,82 @@ namespace arrow::util::alp { namespace { -struct AlpSamplingParameters { - /// Prefix length examined in the chunk. - int64_t values_to_examine; - /// Stride between sampled values. - int64_t sample_stride; -}; - -// The interval holds 30 4096-element chunks. Round up the jump so about eight -// chunks per interval are sampled instead of ten under integer truncation. -constexpr int64_t kSampledChunkStride = bit_util::CeilDiv( - bit_util::CeilDiv(AlpSamplingOptions::kIntervalSize, AlpSamplingOptions::kChunkSize), - AlpSamplingOptions::kSampleChunksPerInterval); -static_assert(kSampledChunkStride > 0, "sample jump must be positive"); - -// Caps the lookup window and chooses a stride that yields at most one sample per -// kSamplesPerChunk values. -AlpSamplingParameters GetSamplingParameters(int64_t chunk_size) { - const int64_t values_to_examine = - std::min(chunk_size, static_cast(AlpFormatConstants::kDefaultVectorSize)); - const int64_t sample_stride = std::max( - 1, bit_util::CeilDiv(values_to_examine, AlpSamplingOptions::kSamplesPerChunk)); - return AlpSamplingParameters{values_to_examine, sample_stride}; -} - -bool ShouldSkipChunk(const int64_t chunk_index, const int64_t sampled_chunk_count, - const int64_t chunk_size) { - if ((chunk_index % kSampledChunkStride) != 0) { - return true; +// splitmix64, a small fixed-seed generator: the same input always yields the same +// sample. +class SampleRng { + public: + explicit SampleRng(uint64_t seed) : state_(0x9E3779B97F4A7C15ULL ^ seed) {} + + uint64_t Next() { + uint64_t z = (state_ += 0x9E3779B97F4A7C15ULL); + z = (z ^ (z >> 30)) * 0xBF58476D1CE4E5B9ULL; + z = (z ^ (z >> 27)) * 0x94D049BB133111EBULL; + return z ^ (z >> 31); } - // Skip short chunks unless nothing has been sampled yet: for inputs shorter - // than a full sample window, a short chunk is the only sample available. - return chunk_size < AlpSamplingOptions::kSamplesPerChunk && sampled_chunk_count != 0; -} + private: + uint64_t state_; +}; } // namespace -template -void AlpSampler::AddSample(std::span input) { - const int64_t input_size = static_cast(input.size()); - for (int64_t i = 0; i < input_size; i += AlpSamplingOptions::kChunkSize) { - const int64_t elements = std::min(input_size - i, AlpSamplingOptions::kChunkSize); - AddSampleChunk({input.data() + i, static_cast(elements)}); +std::vector GetSampledVectorOffsets(int64_t num_values) { + constexpr int64_t kVectorSize = AlpFormatConstants::kDefaultVectorSize; + constexpr int64_t kWindowSize = AlpSamplingOptions::kSampleWindowSize; + static_assert(kWindowSize % kVectorSize == 0, "windows must hold whole vectors"); + + std::vector offsets; + for (int64_t window = 0; window < num_values; window += kWindowSize) { + const int64_t num_vectors = + bit_util::CeilDiv(std::min(kWindowSize, num_values - window), kVectorSize); + const int64_t num_sampled = + std::min(num_vectors, AlpSamplingOptions::kSampledVectors); + for (int64_t i = 0; i < num_sampled; ++i) { + offsets.push_back(window + i * num_vectors / num_sampled * kVectorSize); + } } + return offsets; } template -void AlpSampler::AddSampleChunk(std::span input) { - if (input.empty()) { - return; - } - +void AlpSampler::AddSample(std::span input) { const int64_t input_size = static_cast(input.size()); - const bool should_skip = - ShouldSkipChunk(chunks_processed_, chunks_sampled_, input_size); - - chunks_processed_ += 1; values_processed_ += input_size; - if (should_skip) { - return; + for (const int64_t offset : GetSampledVectorOffsets(input_size)) { + const int64_t length = + std::min(AlpFormatConstants::kDefaultVectorSize, input_size - offset); + AddVectorSample( + input.subspan(static_cast(offset), static_cast(length)), offset); } +} - const AlpSamplingParameters sampling_params = GetSamplingParameters(input_size); - const int64_t sample_count = - bit_util::CeilDiv(sampling_params.values_to_examine, sampling_params.sample_stride); - ARROW_CHECK_LE(sample_count, AlpSamplingOptions::kSamplesPerChunk) - << "ALP sampler produced too many values for one chunk: " << sample_count << " > " - << AlpSamplingOptions::kSamplesPerChunk; - - std::vector chunk_sample; - chunk_sample.reserve(static_cast(sample_count)); - for (int64_t i = 0; i < sampling_params.values_to_examine; - i += sampling_params.sample_stride) { - chunk_sample.push_back(input[static_cast(i)]); +template +void AlpSampler::AddVectorSample(std::span vector, int64_t offset) { + const size_t stride = static_cast(bit_util::CeilDiv( + static_cast(vector.size()), AlpSamplingOptions::kSamplesPerVector)); + + // One value from each run of `stride` values, at a pseudo-random position within + // the run, so the sample covers the whole vector without lining up with data + // that repeats with a period dividing the stride. + SampleRng rng(static_cast(offset) * 0xD1B54A32D192ED03ULL); + std::vector sample; + sample.reserve(static_cast(AlpSamplingOptions::kSamplesPerVector)); + for (size_t i = 0; i < vector.size(); i += stride) { + const size_t run = std::min(stride, vector.size() - i); + sample.push_back(vector[i + static_cast(rng.Next() % run)]); } - sampled_values_count_ += static_cast(chunk_sample.size()); - - chunk_samples_.push_back(std::move(chunk_sample)); - chunks_sampled_++; + sampled_values_count_ += static_cast(sample.size()); + vector_samples_.push_back(std::move(sample)); } template AlpEncodingPreset AlpSampler::MakePreset() const { - ARROW_LOG(DEBUG) << "AlpSampler create preset: chunksSampled=" << chunks_sampled_ << "/" - << chunks_processed_ << " total" + ARROW_LOG(DEBUG) << "AlpSampler create preset: vectorsSampled=" + << vector_samples_.size() << ", valuesSampled=" << sampled_values_count_ << "/" << values_processed_ << " total"; - AlpEncodingPreset preset = AlpCompression::MakePreset(chunk_samples_); + AlpEncodingPreset preset = AlpCompression::MakePreset(vector_samples_); ARROW_LOG(DEBUG) << "AlpSampler preset: " << preset.combinations.size() << " exponent/factor combinations" diff --git a/cpp/src/arrow/util/alp/alp_sampler_internal.h b/cpp/src/arrow/util/alp/alp_sampler_internal.h index b7e428e965f2..3544a1cec28a 100644 --- a/cpp/src/arrow/util/alp/alp_sampler_internal.h +++ b/cpp/src/arrow/util/alp/alp_sampler_internal.h @@ -19,6 +19,7 @@ #pragma once +#include #include #include @@ -27,10 +28,17 @@ namespace arrow::util::alp { +/// Returns the offsets of the vectors AlpSampler samples from an input of +/// `num_values` values. Each window of AlpSamplingOptions::kSampleWindowSize +/// values, or the whole input if shorter, contributes up to +/// AlpSamplingOptions::kSampledVectors vectors of +/// AlpFormatConstants::kDefaultVectorSize values spaced evenly across it. +ARROW_EXPORT std::vector GetSampledVectorOffsets(int64_t num_values); + /// Collects samples and builds an ALP encoding preset. /// -/// Input is split into fixed-size chunks. Each sampled chunk contributes one -/// strided sample. Call AddSample() one or more times, then MakePreset(). +/// Each AddSample() call samples the vectors given by GetSampledVectorOffsets(). +/// Call AddSample() one or more times, then MakePreset(). template class ARROW_EXPORT AlpSampler { public: @@ -45,20 +53,16 @@ class ARROW_EXPORT AlpSampler { AlpEncodingPreset MakePreset() const; private: - /// Adds one sampling chunk. Only the first - /// AlpFormatConstants::kDefaultVectorSize elements are examined. - void AddSampleChunk(std::span input); + /// Adds a sample of at most AlpSamplingOptions::kSamplesPerVector values of the + /// vector at `offset` in the input. + void AddVectorSample(std::span vector, int64_t offset); - /// Number of chunks that have contributed a sample. - int64_t chunks_sampled_{0}; - /// Number of chunks processed. - int64_t chunks_processed_{0}; - /// Number of values processed. + /// Number of values passed to AddSample(). int64_t values_processed_{0}; - /// Number of values retained in chunk_samples_. + /// Number of values retained in vector_samples_. int64_t sampled_values_count_{0}; - /// One strided sample per sampled chunk. MakePreset() only reads these. - std::vector> chunk_samples_; + /// The sample of each sampled vector. MakePreset() only reads these. + std::vector> vector_samples_; }; } // namespace arrow::util::alp diff --git a/cpp/src/arrow/util/alp/alp_test.cc b/cpp/src/arrow/util/alp/alp_test.cc index ede13b1082d1..3f4509423424 100644 --- a/cpp/src/arrow/util/alp/alp_test.cc +++ b/cpp/src/arrow/util/alp/alp_test.cc @@ -15,6 +15,7 @@ // specific language governing permissions and limitations // under the License. +#include #include #include #include @@ -22,6 +23,7 @@ #include #include #include +#include #include #include #include @@ -826,6 +828,129 @@ TYPED_TEST(AlpSamplerTest, KeepsSeveralCombinations) { EXPECT_TRUE(IsBitwiseEqual(output, tenths)); } +// The sampled vectors are spread evenly across each window of kSampleWindowSize +// values, and across a shorter input as a whole. An input shorter than one vector, +// or a short trailing vector, is sampled like a full one. +TEST(AlpSamplerTest, SampledVectorOffsets) { + using ::testing::ElementsAreArray; + constexpr int64_t kVector = AlpFormatConstants::kDefaultVectorSize; + static_assert(AlpSamplingOptions::kSampleWindowSize == 128 * kVector); + // Offsets of the vectors with the given indices. + auto at = [](std::vector indices) { + for (int64_t& index : indices) { + index *= kVector; + } + return indices; + }; + auto stride16 = [](int64_t first) { + std::vector indices; + for (int64_t i = 0; i < 8; ++i) { + indices.push_back(first + 16 * i); + } + return indices; + }; + + EXPECT_THAT(GetSampledVectorOffsets(0), ::testing::IsEmpty()); + EXPECT_THAT(GetSampledVectorOffsets(5), ElementsAreArray(at({0}))); + EXPECT_THAT(GetSampledVectorOffsets(kVector), ElementsAreArray(at({0}))); + EXPECT_THAT(GetSampledVectorOffsets(kVector + 1), ElementsAreArray(at({0, 1}))); + EXPECT_THAT(GetSampledVectorOffsets(7 * kVector), + ElementsAreArray(at({0, 1, 2, 3, 4, 5, 6}))); + EXPECT_THAT(GetSampledVectorOffsets(8 * kVector), + ElementsAreArray(at({0, 1, 2, 3, 4, 5, 6, 7}))); + // 20,000 values: 20 vectors, the last one short. + EXPECT_THAT(GetSampledVectorOffsets(20000), + ElementsAreArray(at({0, 2, 5, 7, 10, 12, 15, 17}))); + // A full window samples every 16th vector. + EXPECT_THAT(GetSampledVectorOffsets(128 * kVector), ElementsAreArray(at(stride16(0)))); + + std::vector two_windows = stride16(0); + two_windows.push_back(128); + EXPECT_THAT(GetSampledVectorOffsets(129 * kVector), ElementsAreArray(at(two_windows))); + + two_windows = stride16(0); + for (const int64_t index : stride16(128)) { + two_windows.push_back(index); + } + EXPECT_THAT(GetSampledVectorOffsets(256 * kVector), ElementsAreArray(at(two_windows))); + + // The third window holds 44 vectors and samples 8 of them spread across it. + std::vector three_windows = two_windows; + for (const int64_t index : {0, 5, 11, 16, 22, 27, 33, 38}) { + three_windows.push_back(256 + index); + } + EXPECT_THAT(GetSampledVectorOffsets(300 * kVector), + ElementsAreArray(at(three_windows))); +} + +// The same input always gives the same preset. +TYPED_TEST(AlpSamplerTest, PresetIsDeterministic) { + constexpr int64_t kVector = AlpFormatConstants::kDefaultVectorSize; + std::vector data(20000); + for (size_t i = 0; i < data.size(); ++i) { + // Each vector uses a different number of decimal digits. + const int64_t digits = static_cast(i) / kVector % 3; + data[i] = static_cast(static_cast(i % 997) / + std::pow(10.0, static_cast(digits))); + } + + AlpSampler first, second; + first.AddSample(data); + second.AddSample(data); + const AlpEncodingPreset preset = first.MakePreset(); + EXPECT_GT(preset.combinations.size(), 1); + EXPECT_EQ(second.MakePreset().combinations, preset.combinations); +} + +// Data that repeats with a period dividing the sampling stride must not hide from +// the sample. Here every 32nd value is an integer and the rest are quarters, so a +// sample of every 32nd value would see only integers. +TYPED_TEST(AlpSamplerTest, SampleDoesNotAlignWithPeriodicData) { + std::vector data(20000); + for (size_t i = 0; i < data.size(); ++i) { + data[i] = static_cast(static_cast(i % 500) / 4.0); + } + AlpSampler sampler; + sampler.AddSample(data); + + const auto vector = + std::span(data).first(AlpFormatConstants::kDefaultVectorSize); + EXPECT_EQ(AlpCompression::Compress(vector, sampler.MakePreset()) + .alp_info() + .num_exceptions(), + 0); +} + +// Values late in the input must reach the preset: a preset built from the whole +// input encodes its tail at least as compactly as the tail's own preset does. +TYPED_TEST(AlpSamplerTest, SamplesAcrossTheWholeInput) { + constexpr int64_t kVector = AlpFormatConstants::kDefaultVectorSize; + // Only the first vector has one decimal digit; the rest have three. + std::vector data(15000); + for (size_t i = 0; i < data.size(); ++i) { + data[i] = static_cast(i) < kVector + ? static_cast(static_cast(i % 100) / 10.0) + : static_cast(static_cast(i % 1000) / 1000.0); + } + const auto head = std::span(data).first(kVector); + const auto tail = std::span(data).subspan(8 * kVector, kVector); + + ASSERT_OK_AND_ASSIGN(const AlpEncodingPreset whole, + AlpCodec::MakePreset(data)); + ASSERT_OK_AND_ASSIGN(const AlpEncodingPreset tail_only, + AlpCodec::MakePreset(tail)); + ASSERT_OK_AND_ASSIGN(const AlpEncodingPreset head_only, + AlpCodec::MakePreset(head)); + + const int64_t tail_size = + AlpCompression::Compress(tail, tail_only).GetDataStoredSize(); + EXPECT_LE(AlpCompression::Compress(tail, whole).GetDataStoredSize(), + tail_size); + // The head's preset alone is a poor fit, so the comparison above is meaningful. + EXPECT_GT(AlpCompression::Compress(tail, head_only).GetDataStoredSize(), + tail_size); +} + // Corrupted Data Handling Tests // // Decoding invalid or corrupted data must return a status, never crash. From facf7011adf0d5758854fa9e571f98dbc7533d26 Mon Sep 17 00:00:00 2001 From: Prateek Gaur Date: Thu, 12 Nov 2026 19:23:08 +0000 Subject: [PATCH 2/3] [C++][Parquet] Try every ALP preset combination for each vector The per-vector search no longer stops after four candidates that do not improve on the best one. A preset holds at most five candidates, so the stop never saved any work, and the output is unchanged. --- cpp/src/arrow/util/alp/alp_compression.cc | 20 +++++-------------- .../arrow/util/alp/alp_constants_internal.h | 6 ------ cpp/src/arrow/util/alp/alp_test.cc | 18 +++++++++++++++++ 3 files changed, 23 insertions(+), 21 deletions(-) diff --git a/cpp/src/arrow/util/alp/alp_compression.cc b/cpp/src/arrow/util/alp/alp_compression.cc index 54c53ce9b706..e65711fb9ae8 100644 --- a/cpp/src/arrow/util/alp/alp_compression.cc +++ b/cpp/src/arrow/util/alp/alp_compression.cc @@ -336,9 +336,9 @@ AlpExponentAndFactor AlpCompression::FindBestExponentAndFactor( AlpExponentAndFactor best_exponent_and_factor; int64_t best_total_bits = std::numeric_limits::max(); - int64_t worse_total_bits_counter = 0; - // Try each candidate combination to find the one which minimizes compression size. + // Try every candidate combination, at most kMaxCombinations, and keep the one + // which minimizes compression size. Ties keep the earlier, more frequent one. // penalize_exceptions=false because this is second-level sampling: the preset // already filtered out bad combinations during first-level sampling, so we // just pick whichever pre-vetted combination compresses this vector best. @@ -347,20 +347,10 @@ AlpExponentAndFactor AlpCompression::FindBestExponentAndFactor( EstimateCompressedSizeBits(sample, exponent_and_factor, /*penalize_exceptions=*/false) .value_or(std::numeric_limits::max()); - - // If current compression size is worse or equal than current best combination. - if (estimated_compression_size >= best_total_bits) { - worse_total_bits_counter += 1; - // Early exit strategy. - if (worse_total_bits_counter == AlpSamplingOptions::kEarlyExitThreshold) { - break; - } - continue; + if (estimated_compression_size < best_total_bits) { + best_total_bits = estimated_compression_size; + best_exponent_and_factor = exponent_and_factor; } - // Otherwise replace the best and continue trying with next combination. - best_total_bits = estimated_compression_size; - best_exponent_and_factor = exponent_and_factor; - worse_total_bits_counter = 0; } return best_exponent_and_factor; } diff --git a/cpp/src/arrow/util/alp/alp_constants_internal.h b/cpp/src/arrow/util/alp/alp_constants_internal.h index f6c8b166cc50..114b3a0345c7 100644 --- a/cpp/src/arrow/util/alp/alp_constants_internal.h +++ b/cpp/src/arrow/util/alp/alp_constants_internal.h @@ -73,15 +73,9 @@ struct AlpSamplingOptions { /// Values sampled from a vector when choosing among preset combinations. static constexpr int64_t kSearchSamplesPerVector = 256; - /// Consecutive non-improving combinations before an early exit. - static constexpr uint8_t kEarlyExitThreshold = 4; - /// Maximum exponent-factor combinations retained in a preset. The ALP paper /// keeps 5. static constexpr uint8_t kMaxCombinations = 5; - - static_assert(kMaxCombinations > kEarlyExitThreshold, - "early exit requires at least one additional candidate"); }; // Power-of-ten constants diff --git a/cpp/src/arrow/util/alp/alp_test.cc b/cpp/src/arrow/util/alp/alp_test.cc index 3f4509423424..97bebdce4838 100644 --- a/cpp/src/arrow/util/alp/alp_test.cc +++ b/cpp/src/arrow/util/alp/alp_test.cc @@ -326,6 +326,24 @@ TYPED_TEST(AlpVectorTest, PicksBestCombination) { EXPECT_TRUE(IsBitwiseEqual(output, input)); } +// The search tries every candidate in the preset, so the best one is found even +// when it comes after several worse ones. +TYPED_TEST(AlpVectorTest, SearchesEveryCombination) { + std::vector input(1024); + for (size_t i = 0; i < input.size(); ++i) { + input[i] = static_cast(i) * static_cast(0.1); + } + + const AlpEncodingPreset preset{ + {AlpExponentAndFactor{2, 0}, AlpExponentAndFactor{3, 0}, AlpExponentAndFactor{4, 0}, + AlpExponentAndFactor{0, 0}, AlpExponentAndFactor{1, 0}}, + 0}; + const auto encoded = AlpCompression::Compress(input, preset); + + EXPECT_EQ(encoded.alp_info().exponent(), 1); + EXPECT_EQ(encoded.alp_info().factor(), 0); +} + // A wide random range plus a few extremes, so values land on both sides of the // ALP window and the exception path gets used. TYPED_TEST(AlpVectorTest, RandomAndExtremes) { From f9cf5f3277b8ff806f8d0dff1acaaadff669be50 Mon Sep 17 00:00:00 2001 From: Prateek Gaur Date: Thu, 12 Nov 2026 20:13:02 +0000 Subject: [PATCH 3/3] [C++][Parquet] Write a page as PLAIN when ALP would make it larger The ALP encoder now flushes a page of values as PLAIN when its ALP encoding would be larger, and the column writer records each page's encoding in its header and the column chunk's encoding stats. Readers already decode per page, and empty pages stay ALP. --- cpp/src/parquet/arrow/arrow_encoding_test.cc | 169 ++++++++++++++--- cpp/src/parquet/column_writer.cc | 33 +++- cpp/src/parquet/column_writer_test.cc | 69 +++++++ cpp/src/parquet/encoder.cc | 22 ++- cpp/src/parquet/encoding.h | 6 + cpp/src/parquet/encoding_test.cc | 183 +++++++++++++++++-- 6 files changed, 425 insertions(+), 57 deletions(-) diff --git a/cpp/src/parquet/arrow/arrow_encoding_test.cc b/cpp/src/parquet/arrow/arrow_encoding_test.cc index 0cd4d2a37cab..456ae7bcc86a 100644 --- a/cpp/src/parquet/arrow/arrow_encoding_test.cc +++ b/cpp/src/parquet/arrow/arrow_encoding_test.cc @@ -79,6 +79,36 @@ void AssertAlpEncodingUsed(const std::shared_ptr& metadata, } } +// Assert that every data page of `column_index` was written with `encoding`. +void AssertDataPageEncoding(const std::shared_ptr& metadata, + int column_index, Encoding::type encoding) { + ASSERT_GE(column_index, 0); + for (int rg = 0; rg < metadata->num_row_groups(); ++rg) { + const auto row_group = metadata->RowGroup(rg); + const auto column_chunk = row_group->ColumnChunk(column_index); + for (const PageEncodingStats& stats : column_chunk->encoding_stats()) { + if (stats.page_type == PageType::DATA_PAGE) { + ASSERT_EQ(encoding, stats.encoding) + << "column " << column_index << " row group " << rg; + } + } + } +} + +// Number of data pages of `column_index` in row group `rg` with `encoding`. +int32_t CountDataPages(const std::shared_ptr& metadata, int rg, + int column_index, Encoding::type encoding) { + const auto row_group = metadata->RowGroup(rg); + const auto column_chunk = row_group->ColumnChunk(column_index); + int32_t count = 0; + for (const PageEncodingStats& stats : column_chunk->encoding_stats()) { + if (stats.page_type == PageType::DATA_PAGE && stats.encoding == encoding) { + count += stats.count; + } + } + return count; +} + // Write `table` with `writer_props` and read it straight back. Optionally hands // back the file metadata. void WriteAndReadBack(const std::shared_ptr& table, int64_t row_group_size, @@ -283,15 +313,23 @@ TEST_F(TestArrowReadAlpEncoding, ReferenceColumnsCoverCornerCases) { class ParquetAlpEncodingTest : public ::testing::Test { public: + static std::shared_ptr AlpWriterProperties( + int64_t max_rows_per_page = kDefaultMaxRowsPerPage) { + return WriterProperties::Builder() + .disable_dictionary() + ->encoding(Encoding::ALP) + ->max_rows_per_page(max_rows_per_page) + ->build(); + } + // Round-trip `table` through a file whose only value column is ALP-encoded, and - // check the encoding really was used. A non-positive `row_group_size` writes one + // check that every data page was written with `expected`: ALP, or PLAIN for + // inputs that ALP would make larger. A non-positive `row_group_size` writes one // row group. void TestAlpRoundTrip(const std::shared_ptr
& table, int64_t row_group_size = 0, - std::shared_ptr
* result = nullptr) { - auto writer_props = WriterProperties::Builder() - .disable_dictionary() - ->encoding(Encoding::ALP) - ->build(); + std::shared_ptr
* result = nullptr, + Encoding::type expected = Encoding::ALP) { + auto writer_props = AlpWriterProperties(); if (row_group_size <= 0) { row_group_size = table->num_rows(); } @@ -299,7 +337,11 @@ class ParquetAlpEncodingTest : public ::testing::Test { std::shared_ptr
round_tripped; std::shared_ptr metadata; WriteAndReadBack(table, row_group_size, &round_tripped, writer_props, &metadata); - ASSERT_NO_FATAL_FAILURE(AssertAlpEncodingUsed(metadata, /*column_index=*/0)); + if (expected == Encoding::ALP) { + ASSERT_NO_FATAL_FAILURE(AssertAlpEncodingUsed(metadata, /*column_index=*/0)); + } + ASSERT_NO_FATAL_FAILURE( + AssertDataPageEncoding(metadata, /*column_index=*/0, expected)); ASSERT_NO_FATAL_FAILURE(::arrow::AssertTablesEqual(*table, *round_tripped)); if (result != nullptr) { @@ -311,21 +353,39 @@ class ParquetAlpEncodingTest : public ::testing::Test { template void TestValuesRoundTrip(const std::vector& values, int64_t row_group_size = 0, - std::shared_ptr
* result = nullptr) { + std::shared_ptr
* result = nullptr, + Encoding::type expected = Encoding::ALP) { std::shared_ptr<::arrow::Array> array; ::arrow::ArrayFromVector(values, &array); - TestAlpRoundTrip(SingleColumnTable(array), row_group_size, result); + TestAlpRoundTrip(SingleColumnTable(array), row_group_size, result, + expected); } - // Round-trip a single-column table of random values. + // Round-trip a single-column table of random values in [min, max] rounded to + // multiples of 0.25, which ALP compresses for both float and double. template void TestRandomRoundTrip(int64_t num_values, typename ArrowType::c_type min, typename ArrowType::c_type max, int64_t row_group_size = 0, int32_t seed = 42) { - ::arrow::random::RandomArrayGenerator rag(seed); - TestAlpRoundTrip( - SingleColumnTable(rag.Numeric(num_values, min, max)), - row_group_size); + using c_type = typename ArrowType::c_type; + std::mt19937 rng(seed); + std::uniform_real_distribution dist(min, max); + std::vector values(num_values); + for (auto& value : values) { + value = static_cast(std::round(dist(rng) * 4.0) / 4.0); + } + TestValuesRoundTrip(values, row_group_size); + } + + // Appends 1,000 multiples of 0.25 to `values`. A handful of special values alone + // would be smaller as PLAIN; with the decimals the page stays ALP and the + // special values travel as its exceptions. + template + static std::vector WithDecimals(std::vector values) { + for (int i = 0; i < 1000; ++i) { + values.push_back(static_cast(static_cast(i * 37 % 997) / 4.0)); + } + return values; } template @@ -358,11 +418,16 @@ TEST_F(ParquetAlpEncodingTest, MixedTypesWithFloatDouble) { ::arrow::field("value_f", ::arrow::float32()), ::arrow::field("value_d", ::arrow::float64()), ::arrow::field("name", ::arrow::utf8())}); - auto table = ::arrow::TableFromJSON(schema, {R"([[1, 1.5, 1.125, "a"], - [2, 2.5, 2.250, "b"], - [3, 3.5, 3.375, "c"], - [4, 4.5, 4.500, "d"], - [5, 5.5, 5.625, "e"]])"}); + // Twenty copies of five rows, enough values for the ALP pages to be smaller than + // PLAIN ones. + const std::string rows = R"([[1, 1.5, 1.125, "a"], + [2, 2.5, 2.250, "b"], + [3, 3.5, 3.375, "c"], + [4, 4.5, 4.500, "d"], + [5, 5.5, 5.625, "e"]])"; + ASSERT_OK_AND_ASSIGN(auto table, + ::arrow::TableFromJSON(schema, std::vector(20, rows)) + ->CombineChunks()); auto writer_props = WriterProperties::Builder() .disable_dictionary() ->encoding("value_f", Encoding::ALP) @@ -401,6 +466,59 @@ TEST_F(ParquetAlpEncodingTest, DecimalLikeValues) { TestValuesRoundTrip<::arrow::DoubleType>(values); } +// Values with full-precision mantissas, like the measured doubles of scientific +// datasets, have no decimal form; ALP would store each one as an exception and +// be larger than PLAIN, so every page is written as PLAIN. +TEST_F(ParquetAlpEncodingTest, IncompressibleValuesWritePlainPages) { + std::mt19937_64 rng(42); + std::uniform_real_distribution dist(-1.0, 1.0); + std::vector values(100000); + for (auto& value : values) { + value = dist(rng); + } + std::shared_ptr<::arrow::Array> array; + ::arrow::ArrayFromVector<::arrow::DoubleType>(values, &array); + const auto table = SingleColumnTable<::arrow::DoubleType>(array); + + std::shared_ptr
result; + std::shared_ptr metadata; + WriteAndReadBack(table, table->num_rows(), &result, AlpWriterProperties(), &metadata); + ASSERT_EQ(0, CountDataPages(metadata, 0, 0, Encoding::ALP)); + ASSERT_EQ(5, CountDataPages(metadata, 0, 0, Encoding::PLAIN)); + ASSERT_THAT(metadata->RowGroup(0)->ColumnChunk(0)->encodings(), + ::testing::Not(::testing::Contains(Encoding::ALP))); + ASSERT_NO_FATAL_FAILURE(::arrow::AssertTablesEqual(*table, *result)); +} + +// Pages alternate between decimal values, which ALP compresses, and +// full-precision values, which it cannot. The column chunk mixes ALP and PLAIN +// pages, lists both encodings, and reads back as written. +TEST_F(ParquetAlpEncodingTest, MixedAlpAndPlainPages) { + constexpr int64_t kPageSize = 20000; + constexpr int kNumPages = 6; + std::mt19937_64 rng(42); + std::uniform_real_distribution dist(-1.0, 1.0); + std::vector values(kPageSize * kNumPages); + for (size_t i = 0; i < values.size(); ++i) { + const bool decimal_page = (i / kPageSize) % 2 == 0; + values[i] = decimal_page ? static_cast(i % 1000) / 100.0 : dist(rng); + } + std::shared_ptr<::arrow::Array> array; + ::arrow::ArrayFromVector<::arrow::DoubleType>(values, &array); + const auto table = SingleColumnTable<::arrow::DoubleType>(array); + + std::shared_ptr
result; + std::shared_ptr metadata; + WriteAndReadBack(table, table->num_rows(), &result, AlpWriterProperties(kPageSize), + &metadata); + ASSERT_EQ(1, metadata->num_row_groups()); + ASSERT_EQ(kNumPages / 2, CountDataPages(metadata, 0, 0, Encoding::ALP)); + ASSERT_EQ(kNumPages / 2, CountDataPages(metadata, 0, 0, Encoding::PLAIN)); + ASSERT_THAT(metadata->RowGroup(0)->ColumnChunk(0)->encodings(), + ::testing::IsSupersetOf({Encoding::ALP, Encoding::PLAIN})); + ASSERT_NO_FATAL_FAILURE(::arrow::AssertTablesEqual(*table, *result)); +} + TEST_F(ParquetAlpEncodingTest, SpecialFloatValues) { // TableFromJSON cannot express infinities or NaN. const std::vector values = {1.0, @@ -411,7 +529,7 @@ TEST_F(ParquetAlpEncodingTest, SpecialFloatValues) { -0.0, 2.5, 3.5}; - TestValuesRoundTrip<::arrow::DoubleType>(values); + TestValuesRoundTrip<::arrow::DoubleType>(WithDecimals(values)); } TEST_F(ParquetAlpEncodingTest, DoubleWithNulls) { @@ -445,7 +563,7 @@ TEST_F(ParquetAlpEncodingTest, DoubleAtEncodedIntegerBounds) { 1.25, 2.5, 3.75}; - TestValuesRoundTrip<::arrow::DoubleType>(values); + TestValuesRoundTrip<::arrow::DoubleType>(WithDecimals(values)); } TEST_F(ParquetAlpEncodingTest, FloatAtEncodedIntegerBounds) { @@ -466,11 +584,11 @@ TEST_F(ParquetAlpEncodingTest, FloatAtEncodedIntegerBounds) { 1.25f, 2.5f, 3.75f}; - TestValuesRoundTrip<::arrow::FloatType>(values); + TestValuesRoundTrip<::arrow::FloatType>(WithDecimals(values)); } -// Every value is an exception: no exponent/factor pair encodes anything, so each -// vector carries num_elements exceptions and the page is larger than PLAIN. (The +// Every value is an exception: no exponent/factor pair encodes anything, so ALP +// would be larger than PLAIN and every page is written as PLAIN. (The // 32768-exception count boundary is covered in arrow/util/alp/alp_test.cc; the // writer here uses 1024-element vectors.) TEST_F(ParquetAlpEncodingTest, AllExceptionsColumn) { @@ -478,7 +596,8 @@ TEST_F(ParquetAlpEncodingTest, AllExceptionsColumn) { const std::vector values(70000, std::numeric_limits::quiet_NaN()); std::shared_ptr
result; - TestValuesRoundTrip<::arrow::DoubleType>(values, /*row_group_size=*/0, &result); + TestValuesRoundTrip<::arrow::DoubleType>(values, /*row_group_size=*/0, &result, + Encoding::PLAIN); // Array equality treats NaN as equal, so compare the payloads instead. const uint64_t expected_bits = std::bit_cast(values[0]); diff --git a/cpp/src/parquet/column_writer.cc b/cpp/src/parquet/column_writer.cc index c899f5a9847a..af28c025593c 100644 --- a/cpp/src/parquet/column_writer.cc +++ b/cpp/src/parquet/column_writer.cc @@ -786,6 +786,9 @@ class ColumnWriterImpl { protected: virtual std::shared_ptr GetValuesBuffer() = 0; + // Encoding of the buffer returned by the most recent GetValuesBuffer() + virtual Encoding::type GetValuesEncoding() const = 0; + // Serializes Dictionary Page if enabled virtual void WriteDictionaryPage() = 0; @@ -813,10 +816,10 @@ class ColumnWriterImpl { void BuildDataPageV1(int64_t definition_levels_rle_size, int64_t repetition_levels_rle_size, int64_t uncompressed_size, - const std::shared_ptr& values); + const std::shared_ptr& values, Encoding::type encoding); void BuildDataPageV2(int64_t definition_levels_rle_size, int64_t repetition_levels_rle_size, int64_t uncompressed_size, - const std::shared_ptr& values); + const std::shared_ptr& values, Encoding::type encoding); // Serializes Data Pages void WriteDataPage(const DataPage& page) { @@ -967,6 +970,7 @@ void ColumnWriterImpl::AddDataPage() { int64_t repetition_levels_rle_size = 0; std::shared_ptr values = GetValuesBuffer(); + const Encoding::type encoding = GetValuesEncoding(); bool is_v1_data_page = properties_->data_page_version() == ParquetDataPageVersion::V1; if (descr_->max_definition_level() > 0) { @@ -986,10 +990,10 @@ void ColumnWriterImpl::AddDataPage() { if (is_v1_data_page) { BuildDataPageV1(definition_levels_rle_size, repetition_levels_rle_size, - uncompressed_size, values); + uncompressed_size, values, encoding); } else { BuildDataPageV2(definition_levels_rle_size, repetition_levels_rle_size, - uncompressed_size, values); + uncompressed_size, values, encoding); } // Re-initialize the sinks for next Page. @@ -1003,7 +1007,8 @@ void ColumnWriterImpl::AddDataPage() { void ColumnWriterImpl::BuildDataPageV1(int64_t definition_levels_rle_size, int64_t repetition_levels_rle_size, int64_t uncompressed_size, - const std::shared_ptr& values) { + const std::shared_ptr& values, + Encoding::type encoding) { auto uncompressed_data = values; if (definition_levels_rle_size > 0 || repetition_levels_rle_size > 0) { // Underlying buffer only keeps growing. Resize to a smaller size does not reallocate. @@ -1036,14 +1041,14 @@ void ColumnWriterImpl::BuildDataPageV1(int64_t definition_levels_rle_size, auto compressed_data_copy, compressed_data->CopySlice(0, compressed_data->size(), allocator_)); std::unique_ptr page_ptr = std::make_unique( - compressed_data_copy, num_values, encoding_, Encoding::RLE, Encoding::RLE, + compressed_data_copy, num_values, encoding, Encoding::RLE, Encoding::RLE, uncompressed_size, std::move(page_stats), first_row_index, std::move(page_size_stats)); total_compressed_bytes_ += page_ptr->size() + sizeof(format::PageHeader); data_pages_.push_back(std::move(page_ptr)); } else { // Eagerly write pages - DataPageV1 page(compressed_data, num_values, encoding_, Encoding::RLE, Encoding::RLE, + DataPageV1 page(compressed_data, num_values, encoding, Encoding::RLE, Encoding::RLE, uncompressed_size, std::move(page_stats), first_row_index, std::move(page_size_stats)); WriteDataPage(page); @@ -1053,7 +1058,8 @@ void ColumnWriterImpl::BuildDataPageV1(int64_t definition_levels_rle_size, void ColumnWriterImpl::BuildDataPageV2(int64_t definition_levels_rle_size, int64_t repetition_levels_rle_size, int64_t uncompressed_size, - const std::shared_ptr& values) { + const std::shared_ptr& values, + Encoding::type encoding) { // Compress the values if needed. Repetition and definition levels are uncompressed in // V2. bool page_is_compressed = false; @@ -1096,13 +1102,13 @@ void ColumnWriterImpl::BuildDataPageV2(int64_t definition_levels_rle_size, // if dictionary encoding has fallen back to PLAIN if (has_dictionary_ && !fallback_) { // Save pages until end of dictionary encoding std::unique_ptr page_ptr = std::make_unique( - combined, num_values, null_count, num_rows, encoding_, def_levels_byte_length, + combined, num_values, null_count, num_rows, encoding, def_levels_byte_length, rep_levels_byte_length, uncompressed_size, page_is_compressed, std::move(page_stats), first_row_index, std::move(page_size_stats)); total_compressed_bytes_ += page_ptr->size() + sizeof(format::PageHeader); data_pages_.push_back(std::move(page_ptr)); } else { - DataPageV2 page(combined, num_values, null_count, num_rows, encoding_, + DataPageV2 page(combined, num_values, null_count, num_rows, encoding, def_levels_byte_length, rep_levels_byte_length, uncompressed_size, page_is_compressed, std::move(page_stats), first_row_index, std::move(page_size_stats)); @@ -1532,6 +1538,13 @@ class TypedColumnWriterImpl : public ColumnWriterImpl, return current_encoder_->FlushValues(); } + // Dictionary index pages carry the configured index encoding. Other encoders + // may write a page in an encoding other than their own, so ask them. + Encoding::type GetValuesEncoding() const override { + return current_dict_encoder_ != nullptr ? encoding_ + : current_encoder_->flushed_encoding(); + } + // Internal function to handle direct writing of ::arrow::DictionaryArray, // since the standard logic concerning dictionary size limits and fallback to // plain encoding is circumvented diff --git a/cpp/src/parquet/column_writer_test.cc b/cpp/src/parquet/column_writer_test.cc index b1f8b4e3be38..97122d7d2f97 100644 --- a/cpp/src/parquet/column_writer_test.cc +++ b/cpp/src/parquet/column_writer_test.cc @@ -18,6 +18,7 @@ #include #include #include +#include #include #include @@ -191,6 +192,11 @@ class TestPrimitiveWriter : public PrimitiveTypedTest { this->SetUpSchema(Repetition::OPTIONAL); this->descr_ = this->schema_.Column(0); this->GenerateData(SMALL_SIZE); + // Multiples of 0.25 keep the page in ALP. + for (int i = 0; i < SMALL_SIZE; ++i) { + this->values_[i] = + static_cast(static_cast(i * 37 % 997) / 4.0); + } // The nulls come first, so the values the writer consumes are the leading // SMALL_SIZE - num_nulls entries of `values_`. @@ -208,6 +214,9 @@ class TestPrimitiveWriter : public PrimitiveTypedTest { writer->Close(); ASSERT_EQ(SMALL_SIZE, this->metadata_num_values()); + ASSERT_THAT(this->metadata_encodings(), ::testing::Contains(Encoding::ALP)); + ASSERT_THAT(this->metadata_encodings(), + ::testing::Not(::testing::Contains(Encoding::PLAIN))); this->ReadColumn(); const int64_t num_expected = SMALL_SIZE - num_nulls; @@ -2621,5 +2630,65 @@ TEST_F(TestDoubleValuesWriter, AlpAllNullDataPageV2) { this->TestAlpOptionalDataPageV2(/*num_nulls=*/SMALL_SIZE); } +// A page whose ALP encoding would be larger than PLAIN is written as PLAIN, and its +// page header says so. Here decimal pages, which ALP compresses, alternate with +// pages of full-precision values, which it cannot. +TEST(TestAlpColumnWriter, PageHeadersRecordEachPageEncoding) { + constexpr int kPageSize = 20000; + constexpr int kNumPages = 4; + std::mt19937_64 rng(42); + std::uniform_real_distribution dist(-1.0, 1.0); + std::vector values(kPageSize * kNumPages); + for (size_t i = 0; i < values.size(); ++i) { + values[i] = + (i / kPageSize) % 2 == 0 ? static_cast(i % 1000) / 100.0 : dist(rng); + } + + auto schema = std::static_pointer_cast( + GroupNode::Make("schema", Repetition::REQUIRED, + {PrimitiveNode::Make("x", Repetition::REQUIRED, Type::DOUBLE)})); + for (const auto data_page_version : + {ParquetDataPageVersion::V1, ParquetDataPageVersion::V2}) { + SCOPED_TRACE(static_cast(data_page_version)); + auto properties = WriterProperties::Builder() + .disable_dictionary() + ->encoding(Encoding::ALP) + ->max_rows_per_page(kPageSize) + ->data_page_version(data_page_version) + ->build(); + auto sink = CreateOutputStream(); + auto file_writer = ParquetFileWriter::Open(sink, schema, properties); + auto col_writer = + static_cast(file_writer->AppendRowGroup()->NextColumn()); + col_writer->WriteBatch(static_cast(values.size()), nullptr, nullptr, + values.data()); + file_writer->Close(); + ASSERT_OK_AND_ASSIGN(auto buffer, sink->Finish()); + + auto file_reader = ParquetFileReader::Open( + std::make_shared<::arrow::io::BufferReader>(buffer), default_reader_properties()); + auto page_reader = file_reader->RowGroup(0)->GetColumnPageReader(0); + std::vector page_encodings; + while (auto page = page_reader->NextPage()) { + page_encodings.push_back(static_cast(*page).encoding()); + } + EXPECT_THAT(page_encodings, ::testing::ElementsAre(Encoding::ALP, Encoding::PLAIN, + Encoding::ALP, Encoding::PLAIN)); + + auto column_reader = + std::static_pointer_cast(file_reader->RowGroup(0)->Column(0)); + std::vector read_back(values.size()); + int64_t total_read = 0; + while (column_reader->HasNext()) { + int64_t values_read = 0; + column_reader->ReadBatch(static_cast(values.size()) - total_read, nullptr, + nullptr, read_back.data() + total_read, &values_read); + total_read += values_read; + } + ASSERT_EQ(static_cast(values.size()), total_read); + EXPECT_EQ(values, read_back); + } +} + } // namespace test } // namespace parquet diff --git a/cpp/src/parquet/encoder.cc b/cpp/src/parquet/encoder.cc index 30341bbe25e1..89ea3dc61eeb 100644 --- a/cpp/src/parquet/encoder.cc +++ b/cpp/src/parquet/encoder.cc @@ -1002,12 +1002,12 @@ class ByteStreamSplitEncoder : public ByteStreamSplitEncoderBase class AlpEncoder : public EncoderImpl, virtual public TypedEncoder { public: @@ -1047,12 +1047,21 @@ class AlpEncoder : public EncoderImpl, virtual public TypedEncoder { kVectorSize, {compressed_buffer->mutable_data(), static_cast(max_comp_size)})); + if (num_elements > 0 && compressed_size > sink_.length()) { + flushed_encoding_ = Encoding::PLAIN; + std::shared_ptr plain_buffer; + PARQUET_THROW_NOT_OK(sink_.Finish(&plain_buffer)); + return plain_buffer; + } + PARQUET_THROW_NOT_OK(compressed_buffer->Resize(compressed_size)); sink_.Reset(); - + flushed_encoding_ = Encoding::ALP; return compressed_buffer; } + Encoding::type flushed_encoding() const override { return flushed_encoding_; } + void Put(const T* buffer, int num_values) override { if (num_values > 0) { PARQUET_THROW_NOT_OK(sink_.Append(reinterpret_cast(buffer), @@ -1087,6 +1096,7 @@ class AlpEncoder : public EncoderImpl, virtual public TypedEncoder { private: ::arrow::BufferBuilder sink_; + Encoding::type flushed_encoding_{Encoding::ALP}; }; // ---------------------------------------------------------------------- diff --git a/cpp/src/parquet/encoding.h b/cpp/src/parquet/encoding.h index 157d67264c56..721966dad22e 100644 --- a/cpp/src/parquet/encoding.h +++ b/cpp/src/parquet/encoding.h @@ -162,6 +162,12 @@ class Encoder { virtual std::shared_ptr FlushValues() = 0; virtual Encoding::type encoding() const = 0; + /// The encoding of the buffer returned by the most recent FlushValues(). + /// + /// This is encoding() unless the encoder wrote that page in another encoding, + /// as the ALP encoder does with PLAIN for a page that ALP would make larger. + virtual Encoding::type flushed_encoding() const { return encoding(); } + virtual void Put(const ::arrow::Array& values) = 0; // Report the number of bytes written to the encoder since the last report. diff --git a/cpp/src/parquet/encoding_test.cc b/cpp/src/parquet/encoding_test.cc index 672e55a900dc..7953b29ba633 100644 --- a/cpp/src/parquet/encoding_test.cc +++ b/cpp/src/parquet/encoding_test.cc @@ -19,10 +19,13 @@ #include #include +#include #include #include #include #include +#include +#include #include #include #include @@ -2867,19 +2870,34 @@ class TestAlpEncoding : public TestEncodingBase { using c_type = typename Type::c_type; static constexpr int TYPE = Type::type_num; + // Random multiples of 0.25, which ALP compresses for both float and double, so + // the round-trip tests exercise ALP pages. + void InitData(int nvalues, int repeats) override { + std::mt19937 rng(nvalues); + std::uniform_int_distribution dist(-40000, 40000); + InitDataWith(nvalues, repeats, [&](int) { + return static_cast(static_cast(dist(rng)) / 4.0); + }); + } + void CheckRoundtrip() override { - CheckRoundtripWithValues(std::span(draws_, num_values_)); + CheckRoundtripWithValues(std::span(draws_, num_values_), expected_encoding_); } - void CheckRoundtripWithValues(std::span values) { + // Round-trips `values` as one page. A page ALP would make larger is flushed as + // PLAIN, so its encoding is checked against `expected` when given. + void CheckRoundtripWithValues(std::span values, + std::optional expected = Encoding::ALP) { auto encoder = MakeTypedEncoder(Encoding::ALP, /*use_dictionary=*/false, descr_.get()); - auto decoder = MakeTypedDecoder(Encoding::ALP, descr_.get()); const auto num_values = static_cast(values.size()); std::vector output(values.size()); encoder->Put(values.data(), num_values); encode_buffer_ = encoder->FlushValues(); + ASSERT_NO_FATAL_FAILURE( + CheckFlushedEncoding(*encoder, values.size_bytes(), expected)); + auto decoder = MakeTypedDecoder(encoder->flushed_encoding(), descr_.get()); decoder->SetData(num_values, encode_buffer_->data(), static_cast(encode_buffer_->size())); @@ -2892,7 +2910,6 @@ class TestAlpEncoding : public TestEncodingBase { int64_t valid_bits_offset) override { auto encoder = MakeTypedEncoder(Encoding::ALP, /*use_dictionary=*/false, descr_.get()); - auto decoder = MakeTypedDecoder(Encoding::ALP, descr_.get()); int null_count = 0; for (auto i = 0; i < num_values_; i++) { @@ -2903,6 +2920,9 @@ class TestAlpEncoding : public TestEncodingBase { encoder->PutSpaced(draws_, num_values_, valid_bits, valid_bits_offset); encode_buffer_ = encoder->FlushValues(); + ASSERT_NO_FATAL_FAILURE(CheckFlushedEncoding( + *encoder, (num_values_ - null_count) * sizeof(c_type), expected_encoding_)); + auto decoder = MakeTypedDecoder(encoder->flushed_encoding(), descr_.get()); // In production, SetData gets the level count (nulls included). decoder->SetData(num_values_, encode_buffer_->data(), @@ -2910,7 +2930,10 @@ class TestAlpEncoding : public TestEncodingBase { auto values_decoded = decoder->DecodeSpaced(decode_buf_, num_values_, null_count, valid_bits, valid_bits_offset); ASSERT_EQ(num_values_, values_decoded); - ASSERT_EQ(0, decoder->values_left()); + // The PLAIN decoder counts only the values it read, not the nulls. + if (encoder->flushed_encoding() == Encoding::ALP) { + ASSERT_EQ(0, decoder->values_left()); + } for (int j = 0; j < num_values_; ++j) { if (bit_util::GetBit(valid_bits, valid_bits_offset + j)) { @@ -2919,6 +2942,20 @@ class TestAlpEncoding : public TestEncodingBase { } } + // A PLAIN page holds exactly the values, and an ALP page is never larger. + void CheckFlushedEncoding(const TypedEncoder& encoder, size_t plain_size, + std::optional expected) { + if (encoder.flushed_encoding() == Encoding::PLAIN) { + ASSERT_EQ(plain_size, static_cast(encode_buffer_->size())); + } else { + ASSERT_EQ(Encoding::ALP, encoder.flushed_encoding()); + ASSERT_LE(static_cast(encode_buffer_->size()), plain_size); + } + if (expected.has_value()) { + ASSERT_EQ(*expected, encoder.flushed_encoding()); + } + } + // Same as InitData, but the values come from `fill(i)`. template void InitDataWith(int nvalues, int repeats, const Fill& fill) { @@ -2938,13 +2975,16 @@ class TestAlpEncoding : public TestEncodingBase { } } + // Expected encoding of every round-trip page; nullopt accepts either. + std::optional expected_encoding_ = Encoding::ALP; + void ExecuteSpecialValues(int nvalues, int repeats) { InitDataWith(nvalues, repeats, [](int i) { if (i % 20 == 0) return std::numeric_limits::quiet_NaN(); if (i % 20 == 5) return std::numeric_limits::infinity(); if (i % 20 == 10) return -std::numeric_limits::infinity(); if (i % 20 == 15) return static_cast(-0.0); - return static_cast(i) * static_cast(0.123); + return static_cast(static_cast(i * 37 % 997) / 4.0); }); CheckRoundtrip(); } @@ -2963,9 +3003,12 @@ using AlpEncodedTypes = ::testing::Types; TYPED_TEST_SUITE(TestAlpEncoding, AlpEncodedTypes); TYPED_TEST(TestAlpEncoding, BasicRoundTrip) { + // A page of a few values may be smaller as PLAIN, because of the ALP headers. + this->expected_encoding_ = std::nullopt; for (int values = 1; values < 32; ++values) { ASSERT_NO_FATAL_FAILURE(this->Execute(values, 1)); } + this->expected_encoding_ = Encoding::ALP; for (int values : {1023, 1024, 1025, 2048, 3000}) { ASSERT_NO_FATAL_FAILURE(this->Execute(values, 1)); @@ -2973,13 +3016,15 @@ TYPED_TEST(TestAlpEncoding, BasicRoundTrip) { } TYPED_TEST(TestAlpEncoding, BatchedDecode) { - // Read the page in many small batches. + // Read the page in many small batches. Decimal values keep the page in ALP. using c_type = typename TypeParam::c_type; - this->InitData(2000, 1); + this->InitDataWith(2000, 1, + [](int i) { return static_cast(100.0 + i * 0.01); }); auto encoder = MakeTypedEncoder(Encoding::ALP, /*use_dictionary=*/false, this->descr_.get()); encoder->Put(this->draws_, this->num_values_); auto buffer = encoder->FlushValues(); + ASSERT_EQ(Encoding::ALP, encoder->flushed_encoding()); const std::vector> batch_plans = { {2000}, {1999, 1}, {1, 1999}, {1, 7, 100, 1892}, {1024, 976}, {500, 500, 500, 500}}; @@ -3006,10 +3051,13 @@ TYPED_TEST(TestAlpEncoding, BatchedDecode) { TYPED_TEST(TestAlpEncoding, ReusesEncoderAcrossFlushes) { using c_type = typename TypeParam::c_type; auto encoder = MakeTypedEncoder(Encoding::ALP, false, this->descr_.get()); - auto decoder = MakeTypedDecoder(Encoding::ALP, this->descr_.get()); + std::vector quarters(1100); + for (size_t i = 0; i < quarters.size(); ++i) { + quarters[i] = static_cast(1.25 * static_cast(i % 3 + 1)); + } const std::vector> pages = { - {static_cast(1.25), static_cast(2.5), static_cast(3.75)}, + quarters, // Two vectors, so a bad offset table would be caught. std::vector(1500, static_cast(7.5)), }; @@ -3017,6 +3065,8 @@ TYPED_TEST(TestAlpEncoding, ReusesEncoderAcrossFlushes) { for (const auto& page : pages) { encoder->Put(page.data(), static_cast(page.size())); auto buffer = encoder->FlushValues(); + ASSERT_EQ(Encoding::ALP, encoder->flushed_encoding()); + auto decoder = MakeTypedDecoder(Encoding::ALP, this->descr_.get()); std::vector output(page.size()); decoder->SetData(static_cast(page.size()), buffer->data(), @@ -3027,13 +3077,59 @@ TYPED_TEST(TestAlpEncoding, ReusesEncoderAcrossFlushes) { } } +// Encodes `values` as one page with `encoder` and checks that it decodes back. +template +std::shared_ptr EncodeAlpPage(TypedEncoder* encoder, + const ColumnDescriptor* descr, + const std::vector& values) { + encoder->Put(values.data(), static_cast(values.size())); + std::shared_ptr buffer = encoder->FlushValues(); + + auto decoder = MakeTypedDecoder(encoder->flushed_encoding(), descr); + std::vector output(values.size()); + decoder->SetData(static_cast(values.size()), buffer->data(), + static_cast(buffer->size())); + EXPECT_EQ(static_cast(values.size()), + decoder->Decode(output.data(), static_cast(values.size()))); + EXPECT_EQ(0, std::memcmp(values.data(), output.data(), + values.size() * sizeof(typename Type::c_type))); + return buffer; +} + +// Round trip across page sizes, through one encoder per column chunk, on values +// whose precision changes partway through. +TYPED_TEST(TestAlpEncoding, RoundTripAcrossPageSizes) { + using c_type = typename TypeParam::c_type; + constexpr int kNumValues = 120000; + std::vector values(kNumValues); + for (int i = 0; i < kNumValues; ++i) { + const double scale = std::pow(10.0, (i / 3000) % 4); + values[i] = static_cast(static_cast(i % 977) / scale); + } + for (const int page_size : {1000, 1024, 20000, 50000, kNumValues}) { + SCOPED_TRACE(page_size); + auto encoder = MakeTypedEncoder(Encoding::ALP, false, this->descr_.get()); + for (int start = 0; start < kNumValues; start += page_size) { + const int end = std::min(kNumValues, start + page_size); + EncodeAlpPage( + encoder.get(), this->descr_.get(), + std::vector(values.begin() + start, values.begin() + end)); + } + } +} + TYPED_TEST(TestAlpEncoding, RoundTripWithRepeats) { ASSERT_NO_FATAL_FAILURE(this->Execute(100, 10)); } TYPED_TEST(TestAlpEncoding, SpecialValues) { - // NaN, Inf, -Inf and -0.0 are all ALP exceptions. + // NaN, Inf, -Inf and -0.0 are all ALP exceptions. With one value in five an + // exception, a page of 100 floats may be smaller as PLAIN. + this->expected_encoding_ = sizeof(typename TypeParam::c_type) == 4 + ? std::nullopt + : std::optional(Encoding::ALP); ASSERT_NO_FATAL_FAILURE(this->ExecuteSpecialValues(100, 1)); + this->expected_encoding_ = Encoding::ALP; ASSERT_NO_FATAL_FAILURE(this->ExecuteSpecialValues(1024, 1)); ASSERT_NO_FATAL_FAILURE(this->ExecuteSpecialValues(2000, 1)); } @@ -3047,7 +3143,12 @@ TYPED_TEST(TestAlpEncoding, DecimalPatterns) { TYPED_TEST(TestAlpEncoding, SpacedRoundTrip) { for (double null_prob : {0.0, 0.1, 0.5, 0.9}) { + // About ten values remain at the highest null probability, few enough that + // the page may be smaller as PLAIN. + this->expected_encoding_ = + null_prob < 0.9 ? std::optional(Encoding::ALP) : std::nullopt; ASSERT_NO_FATAL_FAILURE(this->ExecuteSpaced(100, 1, 0, null_prob)); + this->expected_encoding_ = Encoding::ALP; ASSERT_NO_FATAL_FAILURE(this->ExecuteSpaced(1024, 1, 0, null_prob)); ASSERT_NO_FATAL_FAILURE(this->ExecuteSpaced(2000, 1, 0, null_prob)); } @@ -3079,7 +3180,9 @@ TYPED_TEST(TestAlpEncoding, RandomData) { ASSERT_NO_THROW(encoder->Put(*arr)); auto buffer = encoder->FlushValues(); - auto decoder = MakeTypedDecoder(Encoding::ALP, this->descr_.get()); + // Values this far apart have no common decimal scale, so the page is PLAIN. + ASSERT_EQ(Encoding::PLAIN, encoder->flushed_encoding()); + auto decoder = MakeTypedDecoder(Encoding::PLAIN, this->descr_.get()); decoder->SetData(static_cast(arr->length()), buffer->data(), static_cast(buffer->size())); @@ -3109,6 +3212,7 @@ TYPED_TEST(TestAlpEncoding, ConstantValues) { TYPED_TEST(TestAlpEncoding, EmptyInput) { auto encoder = MakeTypedEncoder(Encoding::ALP, false, this->descr_.get()); auto buffer = encoder->FlushValues(); + ASSERT_EQ(Encoding::ALP, encoder->flushed_encoding()); ASSERT_GT(buffer->size(), 0); auto decoder = MakeTypedDecoder(Encoding::ALP, this->descr_.get()); @@ -3118,16 +3222,60 @@ TYPED_TEST(TestAlpEncoding, EmptyInput) { } TYPED_TEST(TestAlpEncoding, AllExceptions) { - // All values are exceptions. Nothing is bit-packed. + // All values are exceptions, so ALP would be larger and the page is PLAIN. using c_type = typename TypeParam::c_type; const std::vector data(100, std::numeric_limits::quiet_NaN()); - this->CheckRoundtripWithValues(data); + this->CheckRoundtripWithValues(data, Encoding::PLAIN); +} + +// Exceptions mixed into decimal values keep the page in ALP. +TYPED_TEST(TestAlpEncoding, SomeExceptions) { + using c_type = typename TypeParam::c_type; + std::vector data(2000); + for (size_t i = 0; i < data.size(); ++i) { + data[i] = i % 50 == 0 ? std::numeric_limits::quiet_NaN() + : static_cast(static_cast(i % 397) / 8.0); + } + + this->CheckRoundtripWithValues(data, Encoding::ALP); +} + +// Values with full-precision mantissas have no decimal form, so ALP stores them +// as exceptions and would be larger than PLAIN. The page is written as PLAIN, and +// its bytes are the values themselves. +TYPED_TEST(TestAlpEncoding, FallsBackToPlainWhenLarger) { + using c_type = typename TypeParam::c_type; + std::mt19937_64 rng(42); + std::uniform_real_distribution dist(-1.0, 1.0); + std::vector values(20000); + for (auto& value : values) { + value = static_cast(dist(rng)); + } + + auto encoder = MakeTypedEncoder(Encoding::ALP, false, this->descr_.get()); + const auto buffer = EncodeAlpPage(encoder.get(), this->descr_.get(), values); + ASSERT_EQ(Encoding::PLAIN, encoder->flushed_encoding()); + ASSERT_EQ(values.size() * sizeof(c_type), static_cast(buffer->size())); + ASSERT_EQ(0, std::memcmp(values.data(), buffer->data(), buffer->size())); + + // The next page is decimal, so it goes back to ALP. + std::vector decimals(20000); + for (size_t i = 0; i < decimals.size(); ++i) { + decimals[i] = static_cast(static_cast(i % 1000) / 100.0); + } + EncodeAlpPage(encoder.get(), this->descr_.get(), decimals); + ASSERT_EQ(Encoding::ALP, encoder->flushed_encoding()); } TYPED_TEST(TestAlpEncoding, BoundaryValues) { using c_type = typename TypeParam::c_type; - const std::vector data = { + // Boundary values are exceptions; the decimals around them keep the page in ALP. + std::vector data(1000); + for (size_t i = 0; i < data.size(); ++i) { + data[i] = static_cast(static_cast(i % 97) / 4.0); + } + const std::vector boundaries = { std::numeric_limits::max(), std::numeric_limits::min(), std::numeric_limits::lowest(), @@ -3138,8 +3286,11 @@ TYPED_TEST(TestAlpEncoding, BoundaryValues) { static_cast(1.0), static_cast(-1.0), }; + for (size_t i = 0; i < boundaries.size(); ++i) { + data[i * 97] = boundaries[i]; + } - this->CheckRoundtripWithValues(data); + this->CheckRoundtripWithValues(data, Encoding::ALP); } TEST(AlpEncodeDecode, InvalidDataTypes) {