zanmato1984 commented on code in PR #45562: URL: https://github.com/apache/arrow/pull/45562#discussion_r1975043110
########## cpp/src/arrow/compute/kernels/pivot_internal.cc: ########## @@ -0,0 +1,126 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you 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 "arrow/compute/kernels/pivot_internal.h" + +#include <cstdint> + +#include "arrow/compute/exec.h" +#include "arrow/compute/kernels/codegen_internal.h" +#include "arrow/scalar.h" +#include "arrow/type_traits.h" +#include "arrow/util/checked_cast.h" +#include "arrow/visit_type_inline.h" + +namespace arrow::compute::internal { + +using ::arrow::util::span; + +struct BasePivotKeyMapper : public PivotWiderKeyMapper { + Status Init(const PivotWiderOptions* options) override { + if (options->key_names.size() > static_cast<size_t>(kMaxPivotKey) + 1) { + return Status::NotImplemented("Pivoting to more than ", + static_cast<size_t>(kMaxPivotKey) + 1, + " columns: got ", options->key_names.size()); + } + key_name_map_.reserve(options->key_names.size()); + PivotWiderKeyIndex index = 0; + for (const auto& key_name : options->key_names) { + bool inserted = + key_name_map_.try_emplace(std::string_view(key_name), index++).second; + if (!inserted) { + return Status::KeyError("Duplicate key name '", key_name, + "' in PivotWiderOptions"); + } + } + unexpected_key_behavior_ = options->unexpected_key_behavior; + return Status::OK(); + } + + protected: + Result<PivotWiderKeyIndex> KeyNotFound(std::string_view key_name) { + if (unexpected_key_behavior_ == PivotWiderOptions::kIgnore) { + return kNullPivotKey; + } Review Comment: ```suggestion } DCHECK_EQ(unexpected_key_behavior_, PivotWiderOptions::kRaise); ``` ########## cpp/src/arrow/compute/api_aggregate.h: ########## @@ -175,6 +175,88 @@ class ARROW_EXPORT TDigestOptions : public FunctionOptions { uint32_t min_count; }; +/// \brief Control Pivot kernel behavior +/// +/// These options apply to the "pivot_wider" and "hash_pivot_wider" functions. +/// +/// Constraints: +/// - The corresponding `Aggregate::target` must have two FieldRef elements; +/// the first one points to the pivot key column, the second points to the +/// pivoted data column. +/// - The pivot key column must be string-like; its values will be matched +/// against `key_names` in order to dispatch the pivoted data into the +/// output. +/// +/// "pivot_wider" example +/// --------------------- +/// +/// Assuming the following two input columns with types utf8 and int16 (respectively): +/// ``` +/// width | 11 +/// height | 13 +/// ``` +/// and the options `PivotWiderOptions(.key_names = {"height", "width"})` +/// +/// then the output will be a scalar with the type +/// `struct{"height": int16, "width": int16}` +/// and the value `{"height": 13, "width": 11}`. +/// +/// "hash_pivot_wider" example +/// -------------------------- +/// +/// Assuming the following input with schema +/// `{"group": int32, "key": utf8, "value": int16}`: +/// ``` +/// group | key | value +/// ----------------------------- +/// 1 | height | 11 +/// 1 | width | 12 +/// 2 | width | 13 +/// 3 | height | 14 +/// 3 | depth | 15 +/// ``` +/// and the following settings: +/// - a hash grouping key "group" +/// - Aggregate( +/// .function = "hash_pivot_wider", +/// .options = PivotWiderOptions(.key_names = {"height", "width"}), +/// .target = {"key", "value"}, +/// .name = {"properties"}) +/// +/// then the output will have the schema +/// `{"group": int32, "properties": struct{"height": int16, "width": int16}}` +/// and the following value: +/// ``` +/// group | properties +/// | height | width +/// ----------------------------- +/// 1 | 11 | 12 +/// 2 | null | 13 +/// 3 | 14 | null +/// ``` +class ARROW_EXPORT PivotWiderOptions : public FunctionOptions { Review Comment: Any reason why this is named `PivotWider`? Will `PivotWiden` or just `Pivot` be more appropriate? ########## cpp/src/arrow/compute/kernels/hash_aggregate.cc: ########## @@ -3319,9 +3324,401 @@ struct GroupedListFactory { HashAggregateKernel kernel; InputType argument_type; }; -} // namespace -namespace { +// ---------------------------------------------------------------------- +// Pivot implementation + +struct GroupedPivotAccumulator { + Status Init(ExecContext* ctx, std::shared_ptr<DataType> value_type, + const PivotWiderOptions* options) { + ctx_ = ctx; + value_type_ = std::move(value_type); + num_keys_ = static_cast<int>(options->key_names.size()); + num_groups_ = 0; + columns_.resize(num_keys_); + scratch_buffer_ = BufferBuilder(ctx_->memory_pool()); + return Status::OK(); + } + + Status Consume(span<const uint32_t> groups, span<const PivotWiderKeyIndex> keys, + const ArraySpan& values) { + // To dispatch the values into the right (group, key) coordinates, + // we first compute a vector of take indices for each output column. + // + // For each index #i, we set take_indices[keys[#i]][groups[#i]] = #i. + // Unpopulated take_indices entries are null. + // + // For example, assuming we get: + // groups | keys + // =================== + // 1 | 0 + // 3 | 1 + // 1 | 1 + // 0 | 1 + // + // We are going to compute: + // - take_indices[key = 0] = [null, 0, null, null] + // - take_indices[key = 1] = [3, 2, null, 2] Review Comment: ```suggestion // - take_indices[key = 1] = [3, 2, null, 1] ``` ########## cpp/src/arrow/compute/kernels/hash_aggregate.cc: ########## @@ -3456,6 +3853,18 @@ const FunctionDoc hash_one_doc{"Get one value from each group", const FunctionDoc hash_list_doc{"List all values in each group", ("Null values are also returned."), {"array", "group_id_array"}}; + +const FunctionDoc hash_pivot_doc{ + "Pivot values according to a pivot key column", + ("Output is a struct array with as many fields as `PivotWiderOptions.key_names`.\n" + "All output struct fields have the same type as `pivot_values`.\n" + "Each pivot key decides in which output field the corresponding pivot value\n" + "is emitted. If a pivot key doesn't appear in a given group, null is emitted.\n" + "If a pivot key appears twice in a given group, KeyError is raised.\n" Review Comment: Ditto, add description about "duplicate value". ########## cpp/src/arrow/compute/kernels/hash_aggregate.cc: ########## @@ -3319,9 +3324,401 @@ struct GroupedListFactory { HashAggregateKernel kernel; InputType argument_type; }; -} // namespace -namespace { +// ---------------------------------------------------------------------- +// Pivot implementation + +struct GroupedPivotAccumulator { + Status Init(ExecContext* ctx, std::shared_ptr<DataType> value_type, + const PivotWiderOptions* options) { + ctx_ = ctx; + value_type_ = std::move(value_type); + num_keys_ = static_cast<int>(options->key_names.size()); + num_groups_ = 0; + columns_.resize(num_keys_); + scratch_buffer_ = BufferBuilder(ctx_->memory_pool()); + return Status::OK(); + } + + Status Consume(span<const uint32_t> groups, span<const PivotWiderKeyIndex> keys, + const ArraySpan& values) { + // To dispatch the values into the right (group, key) coordinates, + // we first compute a vector of take indices for each output column. + // + // For each index #i, we set take_indices[keys[#i]][groups[#i]] = #i. + // Unpopulated take_indices entries are null. + // + // For example, assuming we get: + // groups | keys + // =================== + // 1 | 0 + // 3 | 1 + // 1 | 1 + // 0 | 1 + // + // We are going to compute: + // - take_indices[key = 0] = [null, 0, null, null] + // - take_indices[key = 1] = [3, 2, null, 2] + // + // Then each output column is computed by taking the values with the + // respective take_indices for the column's keys. + // + + DCHECK_EQ(groups.size(), keys.size()); + DCHECK_EQ(groups.size(), static_cast<size_t>(values.length)); + + std::shared_ptr<DataType> take_index_type; + std::vector<std::shared_ptr<Buffer>> take_indices(num_keys_); + std::vector<std::shared_ptr<Buffer>> take_bitmaps(num_keys_); + + // A generic lambda that computes the take indices with the desired integer width + auto compute_take_indices = [&](auto typed_index) { + ARROW_UNUSED(typed_index); + using TakeIndex = std::decay_t<decltype(typed_index)>; + take_index_type = CTypeTraits<TakeIndex>::type_singleton(); + + const int64_t take_indices_size = + bit_util::RoundUpToMultipleOf64(num_groups_ * sizeof(TakeIndex)); + const int64_t take_bitmap_size = + bit_util::RoundUpToMultipleOf64(bit_util::BytesForBits(num_groups_)); + const int64_t total_scratch_size = + num_keys_ * (take_indices_size + take_bitmap_size); + RETURN_NOT_OK(scratch_buffer_.Resize(total_scratch_size, /*shrink_to_fit=*/false)); + + // Slice the scratch space into individual buffers for each output column's + // take_indices array. + std::vector<TakeIndex*> take_indices_data(num_keys_); + std::vector<uint8_t*> take_bitmap_data(num_keys_); + int64_t offset = 0; + for (int i = 0; i < num_keys_; ++i) { + take_indices[i] = std::make_shared<MutableBuffer>( + scratch_buffer_.mutable_data() + offset, take_indices_size); + take_indices_data[i] = take_indices[i]->mutable_data_as<TakeIndex>(); + offset += take_indices_size; + take_bitmaps[i] = std::make_shared<MutableBuffer>( + scratch_buffer_.mutable_data() + offset, take_bitmap_size); + take_bitmap_data[i] = take_bitmaps[i]->mutable_data(); + memset(take_bitmap_data[i], 0, take_bitmap_size); + offset += take_bitmap_size; + } + DCHECK_LE(offset, scratch_buffer_.capacity()); + + // Populate the take_indices for each output column + for (int64_t i = 0; i < values.length; ++i) { + const PivotWiderKeyIndex key = keys[i]; + const uint32_t group = groups[i]; Review Comment: Can be moved into the following `if`? ########## cpp/src/arrow/compute/kernels/aggregate_pivot.cc: ########## @@ -0,0 +1,186 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you 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 "arrow/compute/api_aggregate.h" +#include "arrow/compute/kernels/aggregate_internal.h" +#include "arrow/compute/kernels/common_internal.h" +#include "arrow/compute/kernels/pivot_internal.h" +#include "arrow/scalar.h" +#include "arrow/util/bit_run_reader.h" +#include "arrow/util/logging.h" + +namespace arrow::compute::internal { +namespace { + +using arrow::internal::VisitSetBitRunsVoid; +using arrow::util::span; + +struct PivotImpl : public ScalarAggregator { + Status Init(const PivotWiderOptions& options, const std::vector<TypeHolder>& in_types) { + options_ = &options; + key_type_ = in_types[0].GetSharedPtr(); + auto value_type = in_types[1].GetSharedPtr(); + FieldVector fields; + fields.reserve(options_->key_names.size()); + values_.reserve(options_->key_names.size()); + for (const auto& key_name : options_->key_names) { + fields.push_back(field(key_name, value_type)); + values_.push_back(MakeNullScalar(value_type)); + } + out_type_ = struct_(std::move(fields)); + ARROW_ASSIGN_OR_RAISE(key_mapper_, PivotWiderKeyMapper::Make(*key_type_, options_)); + return Status::OK(); + } + + Status Consume(KernelContext*, const ExecSpan& batch) override { + DCHECK_EQ(batch.num_values(), 2); + if (batch[0].is_array()) { + ARROW_ASSIGN_OR_RAISE(span<const PivotWiderKeyIndex> keys, + key_mapper_->MapKeys(batch[0].array)); + if (batch[1].is_array()) { + // Array keys, array values + auto values = batch[1].array.ToArray(); + for (int64_t i = 0; i < batch.length; ++i) { + PivotWiderKeyIndex key = keys[i]; + if (key != kNullPivotKey && !values->IsNull(i)) { + if (ARROW_PREDICT_FALSE(values_[key]->is_valid)) { + return DuplicateValue(); + } + ARROW_ASSIGN_OR_RAISE(values_[key], values->GetScalar(i)); + DCHECK(values_[key]->is_valid); + } + } + } else { + // Array keys, scalar value + const Scalar* value = batch[1].scalar; + if (value->is_valid) { + for (int64_t i = 0; i < batch.length; ++i) { + PivotWiderKeyIndex key = keys[i]; + if (key != kNullPivotKey) { + if (ARROW_PREDICT_FALSE(values_[key]->is_valid)) { + return DuplicateValue(); + } + values_[key] = value->GetSharedPtr(); + } + } + } + } + } else { + ARROW_ASSIGN_OR_RAISE(PivotWiderKeyIndex key, + key_mapper_->MapKey(*batch[0].scalar)); + if (key != kNullPivotKey) { + if (batch[1].is_array()) { + // Scalar key, array values + auto values = batch[1].array.ToArray(); + for (int64_t i = 0; i < batch.length; ++i) { + if (!values->IsNull(i)) { + if (ARROW_PREDICT_FALSE(values_[key]->is_valid)) { + return DuplicateValue(); + } + ARROW_ASSIGN_OR_RAISE(values_[key], values->GetScalar(i)); + DCHECK(values_[key]->is_valid); + } + } + } else { + // Scalar key, scalar value + const Scalar* value = batch[1].scalar; + if (value->is_valid) { + if (batch.length > 1 || values_[key]->is_valid) { + return DuplicateValue(); + } + values_[key] = value->GetSharedPtr(); + } + } + } + } + return Status::OK(); + } + + Status MergeFrom(KernelContext*, KernelState&& src) override { + const auto& other_state = checked_cast<const PivotImpl&>(src); + for (int64_t key = 0; key < static_cast<int64_t>(values_.size()); ++key) { + if (other_state.values_[key]->is_valid) { + if (ARROW_PREDICT_FALSE(values_[key]->is_valid)) { + return DuplicateValue(); + } + values_[key] = other_state.values_[key]; + } + } + return Status::OK(); + } + + Status Finalize(KernelContext* ctx, Datum* out) override { + *out = std::make_shared<StructScalar>(std::move(values_), out_type_); + return Status::OK(); + } + + Status DuplicateValue() { + return Status::Invalid( + "Encountered more than one non-null value for the same pivot key"); + } + + std::shared_ptr<DataType> out_type() const { return out_type_; } + + std::shared_ptr<DataType> key_type_; + std::shared_ptr<DataType> out_type_; + const PivotWiderOptions* options_; + std::unique_ptr<PivotWiderKeyMapper> key_mapper_; + ScalarVector values_; +}; + +Result<std::unique_ptr<KernelState>> PivotInit(KernelContext* ctx, + const KernelInitArgs& args) { + const auto& options = checked_cast<const PivotWiderOptions&>(*args.options); + DCHECK_EQ(args.inputs.size(), 2); + DCHECK(is_base_binary_like(args.inputs[0].id())); + auto state = std::make_unique<PivotImpl>(); + RETURN_NOT_OK(state->Init(options, args.inputs)); + return state; +} + +Result<TypeHolder> ResolveOutputType(KernelContext* ctx, const std::vector<TypeHolder>&) { + return checked_cast<PivotImpl*>(ctx->state())->out_type(); +} + +const FunctionDoc pivot_doc{ + "Pivot values according to a pivot key column", + ("Output is a struct with as many fields as `PivotWiderOptions.key_names`.\n" + "All output struct fields have the same type as `pivot_values`.\n" + "Each pivot key decides in which output field the corresponding pivot value\n" + "is emitted. If a pivot key doesn't appear, null is emitted.\n" + "If a pivot key appears twice, KeyError is raised.\n" + "Behavior of unexpected pivot keys is controlled by PivotWiderOptions."), Review Comment: We may need to add some description about "duplicate values". -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
