This is an automated email from the ASF dual-hosted git repository.
etseidl pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow-rs.git
The following commit(s) were added to refs/heads/main by this push:
new b1a907736a doc(parquet): Distinguish difference between `ColumnOrder`
and `SortOrder` (#10573)
b1a907736a is described below
commit b1a907736a49d858edc51c1b6201bbf96554d81e
Author: Ed Seidl <[email protected]>
AuthorDate: Fri Aug 7 07:06:10 2026 -0700
doc(parquet): Distinguish difference between `ColumnOrder` and `SortOrder`
(#10573)
# Which issue does this PR close?
- Closes #10548.
# Rationale for this change
See issue
# What changes are included in this PR?
Document the relationship between the `ColumnOrder` and `SortOrder`
enums used in the parquet crate.
# Are these changes tested?
N/A documentation only
# Are there any user-facing changes?
No
---
parquet/src/basic.rs | 18 ++++++++++++++++--
1 file changed, 16 insertions(+), 2 deletions(-)
diff --git a/parquet/src/basic.rs b/parquet/src/basic.rs
index a2a6ed011b..4458af160d 100644
--- a/parquet/src/basic.rs
+++ b/parquet/src/basic.rs
@@ -974,8 +974,7 @@ union BloomFilterCompression {
/// order, and a sort order should be considered when comparing values with
statistics
/// min/max.
///
-/// See reference in
-/// <https://github.com/apache/arrow/blob/main/cpp/src/parquet/types.h>
+/// See [`ColumnOrder`] for more information.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[allow(non_camel_case_types)]
pub enum SortOrder {
@@ -1004,8 +1003,23 @@ impl SortOrder {
/// Column order that specifies what method was used to aggregate min/max
values for
/// statistics.
///
+/// Prior to version 2.4.0, Parquet used signed comparisons when computing min
and max
+/// values for statistics. This caused problems for UTF8 encoded strings, so
the
+/// [`ColumnOrder`] union was added, initially with a single variant
`TYPE_ORDER`. The
+/// sort order for columns was then defined based on the logical or physical
type of
+/// the column, and could use either signed comparison, unsigned comparison,
or for some
+/// types be left undefined. Since then several new `ColumnOrder`s have been
added to the
+/// specification.
+///
+/// In this crate, the `ColumnOrder` found in the footer is represented by
this enum. To
+/// convey what actual sort order to use, this crate maps the `ColumnOrder`
along with the
+/// physical and logical type to a [`SortOrder`]. It is this [`SortOrder`]
that is used
+/// internally when deciding how to compute the min/max statistics.
+///
/// If column order is undefined, then it is the legacy behaviour and all
values should
/// be compared as signed values/bytes.
+///
+/// [`ColumnOrder`]:
https://github.com/apache/parquet-format/blob/2076361bb64e2de9ca6a8d06eda025a6fa4e9df6/src/main/thrift/parquet.thrift#L1103
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[allow(non_camel_case_types)]
pub enum ColumnOrder {
