11/* *
22 * SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
3- * reserved. SPDX-License-Identifier: Apache-2.0
3+ * SPDX-License-Identifier: Apache-2.0
44 */
55
66#pragma once
@@ -60,7 +60,7 @@ struct order_key {
6060};
6161
6262/* *
63- * @brief Order-based partitioning scheme for sorted/range-partitioned data.
63+ * @brief A valid ordering description for sorted/range-partitioned data.
6464 *
6565 * Data is partitioned by value ranges based on predetermined boundaries.
6666 * For N partitions, there are N-1 boundary rows:
@@ -78,17 +78,17 @@ struct order_key {
7878 * half-open key range (partition keys do not straddle chunk interiors). When false,
7979 * a chunk may contain keys spanning multiple partitions.
8080 */
81- struct order_scheme {
81+ struct ordering {
8282 std::vector<order_key> keys; // /< Sort keys (column, order, null_order per entry).
8383 std::shared_ptr<table_chunk> boundaries; // /< N-1 boundary rows for N partitions.
8484 // / See struct-level note on `strict_boundaries` semantics.
8585 bool strict_boundaries{false };
8686
87- // / @brief Default constructor. Produces an invalid (empty) scheme .
88- order_scheme () = default ;
87+ // / @brief Default constructor. Produces an invalid (empty) ordering .
88+ ordering () = default ;
8989
9090 /* *
91- * @brief Construct a validated order_scheme .
91+ * @brief Construct a validated ordering .
9292 *
9393 * @param keys Non-empty sort keys; size must equal `boundaries->shape().second`.
9494 * @param boundaries Non-null, device-resident boundary table (N-1 rows for N
@@ -97,36 +97,67 @@ struct order_scheme {
9797 * @throws std::invalid_argument if `keys` is empty, `boundaries` is null or not
9898 * device-resident, or `keys.size() != boundaries->shape().second`.
9999 */
100- order_scheme (std::vector<order_key> keys,
101- std::shared_ptr<table_chunk> boundaries,
102- bool strict_boundaries = false );
100+ ordering (std::vector<order_key> keys,
101+ std::shared_ptr<table_chunk> boundaries,
102+ bool strict_boundaries = false );
103103
104104 /* *
105- * @brief Return a new order_scheme with updated key column indices, sharing
106- * boundaries.
107- *
108- * The new key count must match the existing boundary column count.
105+ * @brief Return a new ordering with updated key column indices, sharing
106+ * boundary rows.
109107 *
110108 * @param new_keys Replacement sort keys; size must equal
111109 * `boundaries->shape().second`.
112- * @return A new order_scheme with `new_keys` and the same `boundaries` and
113- * `strict_boundaries`.
114- * @throws std::invalid_argument if `new_keys` is empty or size mismatches boundaries.
110+ * @return A new ordering with `new_keys` and the same boundaries and
111+ * strictness.
112+ * @throws std::invalid_argument if `new_keys` is empty or size mismatches
113+ * boundaries.
115114 */
116- [[nodiscard]] order_scheme with_keys (std::vector<order_key> new_keys) const ;
115+ [[nodiscard]] ordering with_keys (std::vector<order_key> new_keys) const ;
117116
118117 /* *
119- * @brief Check whether boundary values are aligned with another scheme .
118+ * @brief Check whether boundary values are aligned with another ordering .
120119 *
121- * @param other The order_scheme to compare against.
120+ * @param other The ordering to compare against.
122121 * @param br Buffer resource used for temporary allocations during comparison.
123- * @return True when both schemes have matching boundary values and strict_boundaries
124- * attributes, and the schemes are otherwise compatible (same order and null_order).
122+ * @return True when both orderings have matching boundary values and
123+ * strict_boundaries attributes, and are otherwise compatible (same order and
124+ * null_order).
125125 */
126- [[nodiscard]] bool boundaries_aligned_with (order_scheme const & other,
126+ [[nodiscard]] bool boundaries_aligned_with (ordering const & other,
127127 rapidsmpf::BufferResource& br) const ;
128128};
129129
130+ /* *
131+ * @brief Order-based partitioning scheme for sorted/range-partitioned data.
132+ *
133+ * An order_scheme advertises that the same stream is sorted/range-partitioned
134+ * with respect to any individual ordering it contains. Consumers are
135+ * responsible for selecting the ordering that is relevant to a particular
136+ * operation.
137+ */
138+ struct order_scheme {
139+ std::vector<ordering> orderings; // /< Ordering descriptions valid for the stream.
140+
141+ // / @brief Default constructor. Produces an invalid (empty) scheme.
142+ order_scheme () = default ;
143+
144+ /* *
145+ * @brief Construct a validated single-ordering order_scheme.
146+ *
147+ * See `ordering` for parameter semantics.
148+ */
149+ order_scheme (std::vector<order_key> keys,
150+ std::shared_ptr<table_chunk> boundaries,
151+ bool strict_boundaries = false );
152+
153+ /* *
154+ * @brief Construct a validated multi-ordering order_scheme.
155+ *
156+ * @param orderings Non-empty sequence of orderings valid for the stream.
157+ */
158+ explicit order_scheme (std::vector<ordering> orderings);
159+ };
160+
130161/* *
131162 * @brief Partitioning specification for a single hierarchical level.
132163 *
@@ -180,7 +211,7 @@ struct partitioning_spec {
180211
181212 /* *
182213 * @brief Create a spec for order/range partitioning.
183- * @param o The order scheme to use. `o.keys ` must be non-empty; otherwise
214+ * @param o The order scheme to use. `o.orderings ` must be non-empty; otherwise
184215 * throws `std::invalid_argument`.
185216 * @return A partitioning_spec with type ORDER.
186217 */
0 commit comments