diff --git a/cpp/src/arrow/CMakeLists.txt b/cpp/src/arrow/CMakeLists.txt index bcb8db401e77..e0931c19eff4 100644 --- a/cpp/src/arrow/CMakeLists.txt +++ b/cpp/src/arrow/CMakeLists.txt @@ -406,9 +406,9 @@ if(ARROW_COMPUTE) compute/exec/key_hash.cc compute/exec/key_map.cc compute/exec/map_node.cc + compute/exec/options.cc compute/exec/order_by_impl.cc compute/exec/partition_util.cc - compute/exec/options.cc compute/exec/project_node.cc compute/exec/query_context.cc compute/exec/sink_node.cc @@ -422,6 +422,7 @@ if(ARROW_COMPUTE) compute/function_internal.cc compute/kernel.cc compute/light_array.cc + compute/ordering.cc compute/registry.cc compute/kernels/aggregate_basic.cc compute/kernels/aggregate_mode.cc diff --git a/cpp/src/arrow/compute/api_vector.cc b/cpp/src/arrow/compute/api_vector.cc index ff1d6619905d..f7f346d8b58a 100644 --- a/cpp/src/arrow/compute/api_vector.cc +++ b/cpp/src/arrow/compute/api_vector.cc @@ -118,23 +118,6 @@ namespace compute { // ---------------------------------------------------------------------- // Function options -bool SortKey::Equals(const SortKey& other) const { - return target == other.target && order == other.order; -} -std::string SortKey::ToString() const { - std::stringstream ss; - ss << target.ToString() << ' '; - switch (order) { - case SortOrder::Ascending: - ss << "ASC"; - break; - case SortOrder::Descending: - ss << "DESC"; - break; - } - return ss.str(); -} - namespace internal { namespace { using ::arrow::internal::DataMember; diff --git a/cpp/src/arrow/compute/api_vector.h b/cpp/src/arrow/compute/api_vector.h index 365ca0a68455..cc65059ee93b 100644 --- a/cpp/src/arrow/compute/api_vector.h +++ b/cpp/src/arrow/compute/api_vector.h @@ -21,6 +21,7 @@ #include #include "arrow/compute/function.h" +#include "arrow/compute/ordering.h" #include "arrow/datum.h" #include "arrow/result.h" #include "arrow/type_fwd.h" @@ -79,37 +80,6 @@ class ARROW_EXPORT DictionaryEncodeOptions : public FunctionOptions { NullEncodingBehavior null_encoding_behavior = MASK; }; -enum class SortOrder { - /// Arrange values in increasing order - Ascending, - /// Arrange values in decreasing order - Descending, -}; - -enum class NullPlacement { - /// Place nulls and NaNs before any non-null values. - /// NaNs will come after nulls. - AtStart, - /// Place nulls and NaNs after any non-null values. - /// NaNs will come before nulls. - AtEnd, -}; - -/// \brief One sort key for PartitionNthIndices (TODO) and SortIndices -class ARROW_EXPORT SortKey : public util::EqualityComparable { - public: - explicit SortKey(FieldRef target, SortOrder order = SortOrder::Ascending) - : target(std::move(target)), order(order) {} - - bool Equals(const SortKey& other) const; - std::string ToString() const; - - /// A FieldRef targetting the sort column. - FieldRef target; - /// How to order by this sort key. - SortOrder order; -}; - class ARROW_EXPORT ArraySortOptions : public FunctionOptions { public: explicit ArraySortOptions(SortOrder order = SortOrder::Ascending, diff --git a/cpp/src/arrow/compute/exec/accumulation_queue.cc b/cpp/src/arrow/compute/exec/accumulation_queue.cc index 1ffc93a086bf..f8e0c74f6531 100644 --- a/cpp/src/arrow/compute/exec/accumulation_queue.cc +++ b/cpp/src/arrow/compute/exec/accumulation_queue.cc @@ -22,6 +22,7 @@ #include #include +#include "arrow/compute/exec.h" #include "arrow/util/logging.h" namespace arrow { @@ -73,6 +74,7 @@ class SequencingQueueImpl : public SequencingQueue { explicit SequencingQueueImpl(Processor* processor) : processor_(processor) {} Status InsertBatch(ExecBatch batch) override { + DCHECK_NE(::arrow::compute::kUnsequencedIndex, batch.index); std::unique_lock lk(mutex_); if (batch.index == next_index_) { return DeliverNextUnlocked(std::move(batch), std::move(lk)); @@ -122,6 +124,7 @@ class SerialSequencingQueueImpl : public SerialSequencingQueue { explicit SerialSequencingQueueImpl(Processor* processor) : processor_(processor) {} Status InsertBatch(ExecBatch batch) override { + DCHECK_NE(::arrow::compute::kUnsequencedIndex, batch.index); std::unique_lock lk(mutex_); queue_.push(std::move(batch)); if (queue_.top().index == next_index_ && !is_processing_) { diff --git a/cpp/src/arrow/compute/exec/asof_join_node.cc b/cpp/src/arrow/compute/exec/asof_join_node.cc index fe81f3c84ace..00a733be25e1 100644 --- a/cpp/src/arrow/compute/exec/asof_join_node.cc +++ b/cpp/src/arrow/compute/exec/asof_join_node.cc @@ -1150,8 +1150,8 @@ class AsofJoinNode : public ExecNode { if (result.ok()) { auto out_rb = *result; if (!out_rb) break; - ++batches_produced_; ExecBatch out_b(*out_rb); + out_b.index = batches_produced_++; Status st = output_->InputReceived(this, std::move(out_b)); if (!st.ok()) { EndFromProcessThread(std::move(st)); @@ -1491,6 +1491,7 @@ class AsofJoinNode : public ExecNode { } const char* kind_name() const override { return "AsofJoinNode"; } + const Ordering& ordering() const override { return ordering_; } Status InputReceived(ExecNode* input, ExecBatch batch) override { // Get the input @@ -1540,6 +1541,8 @@ class AsofJoinNode : public ExecNode { } private: + // Outputs from this node are always in ascending order according to the on key + const Ordering ordering_; std::vector indices_of_on_key_; std::vector> indices_of_by_key_; std::vector> key_hashers_; @@ -1573,6 +1576,7 @@ AsofJoinNode::AsofJoinNode(ExecPlan* plan, NodeVector inputs, bool must_hash, bool may_rehash) : ExecNode(plan, inputs, input_labels, /*output_schema=*/std::move(output_schema)), + ordering_({SortKey(indices_of_on_key[0])}), indices_of_on_key_(std::move(indices_of_on_key)), indices_of_by_key_(std::move(indices_of_by_key)), key_hashers_(std::move(key_hashers)), diff --git a/cpp/src/arrow/compute/exec/asof_join_node_test.cc b/cpp/src/arrow/compute/exec/asof_join_node_test.cc index 91735dbdfe60..b1d99b60f2c4 100644 --- a/cpp/src/arrow/compute/exec/asof_join_node_test.cc +++ b/cpp/src/arrow/compute/exec/asof_join_node_test.cc @@ -1314,6 +1314,43 @@ TEST(AsofJoinTest, BackpressureWithBatches) { /*fast_delay=*/0.01, /*slow_delay=*/0.1, /*noisy=*/false); } +template +void TestSequencing(BatchesMaker maker, int num_batches, int batch_size) { + auto l_schema = + schema({field("time", int32()), field("key", int32()), field("l_value", int32())}); + auto r_schema = + schema({field("time", int32()), field("key", int32()), field("r0_value", int32())}); + + auto make_shift = [&maker, num_batches, batch_size]( + const std::shared_ptr& schema, int shift) { + return maker({[](int row) -> int64_t { return row; }, + [num_batches](int row) -> int64_t { return row / num_batches; }, + [shift](int row) -> int64_t { return row * 10 + shift; }}, + schema, num_batches, batch_size); + }; + ASSERT_OK_AND_ASSIGN(auto l_batches, make_shift(l_schema, 0)); + ASSERT_OK_AND_ASSIGN(auto r_batches, make_shift(r_schema, 1)); + + compute::Declaration l_src = {"source", + SourceNodeOptions(l_schema, l_batches.gen(false, false))}; + compute::Declaration r_src = {"source", + SourceNodeOptions(r_schema, r_batches.gen(false, false))}; + + compute::Declaration asofjoin = { + "asofjoin", {l_src, r_src}, GetRepeatedOptions(2, "time", {"key"}, 1000)}; + + QueryOptions query_options; + query_options.use_threads = false; + ASSERT_OK_AND_ASSIGN(BatchesWithCommonSchema batches, + DeclarationToExecBatches(asofjoin, query_options)); + + AssertExecBatchesSequenced(batches.batches); +} + +TEST(AsofJoinTest, BatchSequencing) { + return TestSequencing(MakeIntegerBatches, /*num_batches=*/32, /*batch_size=*/1); +} + namespace { Result>> MakeIntegerBatchGenForTest( diff --git a/cpp/src/arrow/compute/exec/exec_plan.cc b/cpp/src/arrow/compute/exec/exec_plan.cc index 629460b75520..0b0c3934bf1a 100644 --- a/cpp/src/arrow/compute/exec/exec_plan.cc +++ b/cpp/src/arrow/compute/exec/exec_plan.cc @@ -437,6 +437,11 @@ ExecNode::ExecNode(ExecPlan* plan, NodeVector inputs, } } +const Ordering& ExecNode::ordering() const { + // The safest default is to assume a node destroys ordering + return Ordering::Unordered(); +} + Status ExecNode::Init() { return Status::OK(); } Status ExecNode::Validate() const { @@ -644,15 +649,19 @@ Future DeclarationToExecBatchesImpl( ExecContext exec_ctx(options.memory_pool, cpu_executor, options.function_registry); ARROW_ASSIGN_OR_RAISE(std::shared_ptr exec_plan, ExecPlan::Make(exec_ctx)); SinkNodeOptions sink_options(&sink_gen, &out_schema); - sink_options.sequence_delivery = options.sequence_output; + sink_options.sequence_output = options.sequence_output; Declaration with_sink = Declaration::Sequence({declaration, {"sink", sink_options}}); ARROW_RETURN_NOT_OK(with_sink.AddToPlan(exec_plan.get())); ARROW_RETURN_NOT_OK(exec_plan->Validate()); exec_plan->StartProducing(); auto collected_fut = CollectAsyncGenerator(sink_gen); - return AllFinished({exec_plan->finished(), Future<>(collected_fut)}) - .Then([collected_fut, exec_plan, - schema = std::move(out_schema)]() -> Result { + return exec_plan->finished().Then( + [collected_fut, exec_plan, + schema = std::move(out_schema)]() -> Result { + if (!collected_fut.is_finished()) { + return Status::Invalid( + "Plan finished but it did not emit the expected number of batches."); + } ARROW_ASSIGN_OR_RAISE(auto collected, collected_fut.result()); std::vector exec_batches = ::arrow::internal::MapVector( [](std::optional batch) { return batch.value_or(ExecBatch()); }, @@ -667,9 +676,9 @@ Future<> DeclarationToStatusImpl(Declaration declaration, QueryOptions options, ARROW_ASSIGN_OR_RAISE(std::shared_ptr exec_plan, ExecPlan::Make(exec_ctx)); ARROW_ASSIGN_OR_RAISE(ExecNode * last_node, declaration.AddToPlan(exec_plan.get())); if (!last_node->is_sink()) { - Declaration null_sink = - Declaration("consuming_sink", {last_node}, - ConsumingSinkNodeOptions(NullSinkNodeConsumer::Make())); + ConsumingSinkNodeOptions sink_options(NullSinkNodeConsumer::Make()); + sink_options.sequence_output = options.sequence_output; + Declaration null_sink = Declaration("consuming_sink", {last_node}, sink_options); ARROW_RETURN_NOT_OK(null_sink.AddToPlan(exec_plan.get())); } ARROW_RETURN_NOT_OK(exec_plan->Validate()); @@ -826,6 +835,20 @@ Result DeclarationToExecBatches( use_threads); } +Result DeclarationToExecBatches(Declaration declaration, + QueryOptions query_options) { + if (query_options.custom_cpu_executor != nullptr) { + return Status::Invalid("Cannot use synchronous methods with a custom CPU executor"); + } + return ::arrow::internal::RunSynchronously>( + [=, declaration = + std::move(declaration)](::arrow::internal::Executor* executor) mutable { + return DeclarationToExecBatchesImpl(std::move(declaration), query_options, + executor); + }, + query_options.use_threads); +} + Future<> DeclarationToStatusAsync(Declaration declaration, ExecContext exec_context) { return DeclarationToStatusImpl(std::move(declaration), QueryOptionsFromCustomExecContext(exec_context), @@ -858,6 +881,17 @@ Status DeclarationToStatus(Declaration declaration, bool use_threads, use_threads); } +Status DeclarationToStatus(Declaration declaration, QueryOptions query_options) { + if (query_options.custom_cpu_executor != nullptr) { + return Status::Invalid("Cannot use synchronous methods with a custom CPU executor"); + } + return ::arrow::internal::RunSynchronously>( + [=, declaration = std::move(declaration)](::arrow::internal::Executor* executor) { + return DeclarationToStatusImpl(std::move(declaration), query_options, executor); + }, + query_options.use_threads); +} + namespace { struct BatchConverter { ~BatchConverter() { diff --git a/cpp/src/arrow/compute/exec/exec_plan.h b/cpp/src/arrow/compute/exec/exec_plan.h index c2738945c27c..1f47515e3f1d 100644 --- a/cpp/src/arrow/compute/exec/exec_plan.h +++ b/cpp/src/arrow/compute/exec/exec_plan.h @@ -26,7 +26,9 @@ #include #include +#include "arrow/compute/api_vector.h" #include "arrow/compute/exec.h" +#include "arrow/compute/ordering.h" #include "arrow/compute/type_fwd.h" #include "arrow/type_fwd.h" #include "arrow/util/future.h" @@ -146,6 +148,49 @@ class ARROW_EXPORT ExecNode { virtual Status Validate() const; + /// \brief the ordering of the output batches + /// + /// This does not guarantee the batches will be emitted by this node + /// in order. Instead it guarantees that the batches will have their + /// ExecBatch::index property set in a way that respects this ordering. + /// + /// In other words, given the ordering {{"x", SortOrder::Ascending}} we + /// know that all values of x in a batch with index N will be less than + /// or equal to all values of x in a batch with index N+k (assuming k > 0). + /// Furthermore, we also know that values will be sorted within a batch. + /// Any row N will have a value of x that is less than the value for + /// any row N+k. + /// + /// Note that an ordering can be both Ordering::Unordered and Ordering::Implicit. + /// A node's output should be marked Ordering::Unordered if the order is + /// non-deterministic. For example, a hash-join has no predictable output order. + /// + /// If the ordering is Ordering::Implicit then there is a meaningful order but that + /// odering is not represented by any column in the data. The most common case for this + /// is when reading data from an in-memory table. The data has an implicit "row order" + /// which is not neccesarily represented in the data set. + /// + /// A filter or project node will not modify the ordering. Nothing needs to be done + /// other than ensure the index assigned to output batches is the same as the + /// input batch that was mapped. + /// + /// Other nodes may introduce order. For example, an order-by node will emit + /// a brand new ordering independent of the input ordering. + /// + /// Finally, as described above, such as a hash-join or aggregation may may + /// destroy ordering (although these nodes could also choose to establish a + /// new ordering based on the hash keys). + /// + /// Some nodes will require an ordering. For example, a fetch node or an + /// asof join node will only function if the input data is ordered (for fetch + /// it is enough to be implicitly ordered. For an asof join the ordering must + /// be explicit and compatible with the on key.) + /// + /// Nodes that maintain ordering should be careful to avoid introducing gaps + /// in the batch index. This may require emitting empty batches in order to + /// maintain continuity. + virtual const Ordering& ordering() const; + /// Upstream API: /// These functions are called by input nodes that want to inform this node /// about an updated condition (a new input batch or an impending @@ -422,8 +467,18 @@ struct ARROW_EXPORT QueryOptions { /// If the output has a meaningful order then sequence the output of the plan /// - /// If the output has no meaningful order then this option will be ignored. - bool sequence_output = false; + /// The default behavior (std::nullopt) will sequence output batches if there + /// is a meaningful ordering in the final node and will emit batches immediately + /// otherwise. + /// + /// If explicitly set to true then plan execution will fail if there is no + /// meaningful ordering. This can be useful to valdiate a query that should + /// be emitting ordered results. + /// + /// If explicitly set to false then batches will be emit immediately even if there + /// is a meaningful ordering. This could cause batches to be emit out of order but + /// may offer a small decrease to latency. + std::optional sequence_output = std::nullopt; /// \brief should the plan use multiple background threads for CPU-intensive work /// @@ -443,15 +498,13 @@ struct ARROW_EXPORT QueryOptions { /// \brief a memory pool to use for allocations /// - /// Must be null or remain valid for the duration of the plan. If this is null then - /// the arrow::default_memory_pool() will be used. - MemoryPool* memory_pool = NULLPTR; + /// Must remain valid for the duration of the plan. + MemoryPool* memory_pool = default_memory_pool(); /// \brief a function registry to use for the plan /// - /// Must be null or remain valid for the duration of the plan. If this is null then - /// defaults to arrow::compute::GetFunctionRegistry() - FunctionRegistry* function_registry = NULLPTR; + /// Must remain valid for the duration of the plan. + FunctionRegistry* function_registry = GetFunctionRegistry(); }; /// \brief Calculate the output schema of a declaration @@ -544,6 +597,9 @@ ARROW_EXPORT Result DeclarationToExecBatches( MemoryPool* memory_pool = default_memory_pool(), FunctionRegistry* function_registry = NULLPTR); +ARROW_EXPORT Result DeclarationToExecBatches( + Declaration declaration, QueryOptions query_options); + /// \brief Asynchronous version of \see DeclarationToExecBatches /// /// \see DeclarationToTableAsync for details on threading & execution @@ -614,6 +670,9 @@ ARROW_EXPORT Status DeclarationToStatus(Declaration declaration, bool use_thread MemoryPool* memory_pool = default_memory_pool(), FunctionRegistry* function_registry = NULLPTR); +ARROW_EXPORT Status DeclarationToStatus(Declaration declaration, + QueryOptions query_options); + /// \brief Asynchronous version of \see DeclarationToStatus /// /// This can be useful when the data are consumed as part of the plan itself, for diff --git a/cpp/src/arrow/compute/exec/fetch_node.cc b/cpp/src/arrow/compute/exec/fetch_node.cc index d78bdd581b20..1c4ec0aaded8 100644 --- a/cpp/src/arrow/compute/exec/fetch_node.cc +++ b/cpp/src/arrow/compute/exec/fetch_node.cc @@ -106,6 +106,8 @@ class FetchNode : public ExecNode, public TracedNode, util::SequencingQueue::Pro const char* kind_name() const override { return "FetchNode"; } + const Ordering& ordering() const override { return inputs_[0]->ordering(); } + Status InputFinished(ExecNode* input, int total_batches) override { DCHECK_EQ(input, inputs_[0]); EVENT_ON_CURRENT_SPAN("InputFinished", {{"batches.length", total_batches}}); @@ -122,6 +124,17 @@ class FetchNode : public ExecNode, public TracedNode, util::SequencingQueue::Pro return Status::OK(); } + Status Validate() const override { + ARROW_RETURN_NOT_OK(ExecNode::Validate()); + if (inputs_[0]->ordering().is_unordered()) { + return Status::Invalid( + "Fetch node's input has no meaningful ordering and so limit/offset will be " + "non-deterministic. Please establish order in some way (e.g. by inserting an " + "order_by node)"); + } + return Status::OK(); + } + Status StartProducing() override { NoteStartProducing(ToStringExtra()); return Status::OK(); diff --git a/cpp/src/arrow/compute/exec/fetch_node_test.cc b/cpp/src/arrow/compute/exec/fetch_node_test.cc index 24671035d6d6..53afe5b3d1d6 100644 --- a/cpp/src/arrow/compute/exec/fetch_node_test.cc +++ b/cpp/src/arrow/compute/exec/fetch_node_test.cc @@ -48,7 +48,6 @@ void CheckFetch(FetchNodeOptions options) { {"fetch", options}}); for (bool use_threads : {false, true}) { QueryOptions query_options; - query_options.sequence_output = true; query_options.use_threads = use_threads; ASSERT_OK_AND_ASSIGN(std::shared_ptr actual, DeclarationToTable(plan, query_options)); diff --git a/cpp/src/arrow/compute/exec/map_node.cc b/cpp/src/arrow/compute/exec/map_node.cc index 9166ad5c68eb..5bb1c0f36dd9 100644 --- a/cpp/src/arrow/compute/exec/map_node.cc +++ b/cpp/src/arrow/compute/exec/map_node.cc @@ -49,6 +49,10 @@ Status MapNode::InputFinished(ExecNode* input, int total_batches) { return Status::OK(); } +// Right now this assumes the map operation will always maintain ordering. This +// may change in the future but is true for the current map nodes (filter/project) +const Ordering& MapNode::ordering() const { return inputs_[0]->ordering(); } + Status MapNode::StartProducing() { NoteStartProducing(ToStringExtra()); return Status::OK(); @@ -68,8 +72,10 @@ Status MapNode::InputReceived(ExecNode* input, ExecBatch batch) { auto scope = TraceInputReceived(batch); DCHECK_EQ(input, inputs_[0]); compute::Expression guarantee = batch.guarantee; + int64_t index = batch.index; ARROW_ASSIGN_OR_RAISE(auto output_batch, ProcessBatch(std::move(batch))); output_batch.guarantee = guarantee; + output_batch.index = index; ARROW_RETURN_NOT_OK(output_->InputReceived(this, std::move(output_batch))); if (input_counter_.Increment()) { this->Finish(); diff --git a/cpp/src/arrow/compute/exec/map_node.h b/cpp/src/arrow/compute/exec/map_node.h index 5a866bdd9704..96f91f149daf 100644 --- a/cpp/src/arrow/compute/exec/map_node.h +++ b/cpp/src/arrow/compute/exec/map_node.h @@ -56,6 +56,8 @@ class ARROW_EXPORT MapNode : public ExecNode, public TracedNode { Status InputReceived(ExecNode* input, ExecBatch batch) override; + const Ordering& ordering() const override; + protected: Status StopProducingImpl() override; diff --git a/cpp/src/arrow/compute/exec/options.cc b/cpp/src/arrow/compute/exec/options.cc index 9e9da7ad8317..08064af58059 100644 --- a/cpp/src/arrow/compute/exec/options.cc +++ b/cpp/src/arrow/compute/exec/options.cc @@ -73,5 +73,29 @@ Result> SourceNodeOptions::FromRecordBatchRea return std::make_shared(std::move(schema), std::move(batch_gen)); } +namespace { +ExecBatchIteratorMaker VecToItMaker(std::vector batches) { + auto batches_ptr = std::make_shared>>(); + batches_ptr->reserve(batches.size()); + for (auto batch : batches) { + batches_ptr->push_back(std::make_shared(std::move(batch))); + } + return + [batches_ptr = std::move(batches_ptr)] { return MakeVectorIterator(*batches_ptr); }; +} +} // namespace + +ExecBatchSourceNodeOptions::ExecBatchSourceNodeOptions( + std::shared_ptr schema, std::vector batches, + ::arrow::internal::Executor* io_executor) + : SchemaSourceNodeOptions(std::move(schema), VecToItMaker(std::move(batches)), + io_executor) {} + +ExecBatchSourceNodeOptions::ExecBatchSourceNodeOptions(std::shared_ptr schema, + std::vector batches, + bool requires_io) + : SchemaSourceNodeOptions(std::move(schema), VecToItMaker(std::move(batches)), + requires_io) {} + } // namespace compute } // namespace arrow diff --git a/cpp/src/arrow/compute/exec/options.h b/cpp/src/arrow/compute/exec/options.h index bd2bbcb8e64a..bc37144a3cc7 100644 --- a/cpp/src/arrow/compute/exec/options.h +++ b/cpp/src/arrow/compute/exec/options.h @@ -111,8 +111,18 @@ template class ARROW_EXPORT SchemaSourceNodeOptions : public ExecNodeOptions { public: SchemaSourceNodeOptions(std::shared_ptr schema, ItMaker it_maker, - arrow::internal::Executor* io_executor = NULLPTR) - : schema(schema), it_maker(std::move(it_maker)), io_executor(io_executor) {} + arrow::internal::Executor* io_executor) + : schema(schema), + it_maker(std::move(it_maker)), + io_executor(io_executor), + requires_io(true) {} + + SchemaSourceNodeOptions(std::shared_ptr schema, ItMaker it_maker, + bool requires_io = false) + : schema(schema), + it_maker(std::move(it_maker)), + io_executor(NULLPTR), + requires_io(requires_io) {} /// \brief The schema of the record batches from the iterator std::shared_ptr schema; @@ -122,8 +132,13 @@ class ARROW_EXPORT SchemaSourceNodeOptions : public ExecNodeOptions { /// \brief The executor to use for scanning the iterator /// - /// Defaults to the default I/O executor. + /// Defaults to the default I/O executor. Only used if requires_io is true. + /// If requires_io is false then this MUST be nullptr. arrow::internal::Executor* io_executor; + + /// \brief If true then items will be fetched from the iterator on a dedicated I/O + /// thread to keep I/O off the CPU thread + bool requires_io; }; class ARROW_EXPORT RecordBatchReaderSourceNodeOptions : public ExecNodeOptions { @@ -152,7 +167,13 @@ using ExecBatchIteratorMaker = std::function /// \brief An extended Source node which accepts a schema and exec-batches class ARROW_EXPORT ExecBatchSourceNodeOptions : public SchemaSourceNodeOptions { + public: using SchemaSourceNodeOptions::SchemaSourceNodeOptions; + ExecBatchSourceNodeOptions(std::shared_ptr schema, + std::vector batches, + ::arrow::internal::Executor* io_executor); + ExecBatchSourceNodeOptions(std::shared_ptr schema, + std::vector batches, bool requires_io = false); }; using RecordBatchIteratorMaker = std::function>()>; @@ -253,29 +274,29 @@ struct ARROW_EXPORT BackpressureOptions { /// \brief Add a sink node which forwards to an AsyncGenerator /// /// Emitted batches will only be ordered if there is a meaningful ordering -/// and sequence_delivery is set to true. +/// and sequence_output is not set to false. class ARROW_EXPORT SinkNodeOptions : public ExecNodeOptions { public: explicit SinkNodeOptions(std::function>()>* generator, std::shared_ptr* schema, BackpressureOptions backpressure = {}, BackpressureMonitor** backpressure_monitor = NULLPTR, - bool sequence_delivery = false) + std::optional sequence_output = std::nullopt) : generator(generator), schema(schema), backpressure(backpressure), backpressure_monitor(backpressure_monitor), - sequence_delivery(false) {} + sequence_output(sequence_output) {} explicit SinkNodeOptions(std::function>()>* generator, BackpressureOptions backpressure = {}, BackpressureMonitor** backpressure_monitor = NULLPTR, - bool sequence_delivery = false) + std::optional sequence_output = std::nullopt) : generator(generator), schema(NULLPTR), backpressure(std::move(backpressure)), backpressure_monitor(backpressure_monitor), - sequence_delivery(false) {} + sequence_output(sequence_output) {} /// \brief A pointer to a generator of batches. /// @@ -299,8 +320,10 @@ class ARROW_EXPORT SinkNodeOptions : public ExecNodeOptions { /// the amount of data currently queued in the sink node. This is an optional utility /// and backpressure can be applied even if this is not used. BackpressureMonitor** backpressure_monitor; - /// \brief If true and there is a meaningful ordering then sequence delivered batches - bool sequence_delivery; + /// \brief Controls whether batches should be emitted immediately or sequenced in order + /// + /// \see QueryOptions for more details + std::optional sequence_output; }; /// \brief Control used by a SinkNodeConsumer to pause & resume @@ -346,8 +369,11 @@ class ARROW_EXPORT SinkNodeConsumer { class ARROW_EXPORT ConsumingSinkNodeOptions : public ExecNodeOptions { public: explicit ConsumingSinkNodeOptions(std::shared_ptr consumer, - std::vector names = {}) - : consumer(std::move(consumer)), names(std::move(names)) {} + std::vector names = {}, + std::optional sequence_output = std::nullopt) + : consumer(std::move(consumer)), + names(std::move(names)), + sequence_output(sequence_output) {} std::shared_ptr consumer; /// \brief Names to rename the sink's schema fields to @@ -355,7 +381,10 @@ class ARROW_EXPORT ConsumingSinkNodeOptions : public ExecNodeOptions { /// If specified then names must be provided for all fields. Currently, only a flat /// schema is supported (see ARROW-15901). std::vector names; - bool sequence_output = false; + /// \brief Controls whether batches should be emitted immediately or sequenced in order + /// + /// \see QueryOptions for more details + std::optional sequence_output; }; /// \brief Make a node which sorts rows passed through it @@ -575,11 +604,15 @@ class ARROW_EXPORT SelectKSinkNodeOptions : public SinkNodeOptions { /// a table pointer. class ARROW_EXPORT TableSinkNodeOptions : public ExecNodeOptions { public: - explicit TableSinkNodeOptions(std::shared_ptr
* output_table) - : output_table(output_table) {} + explicit TableSinkNodeOptions(std::shared_ptr
* output_table, + std::optional sequence_output = std::nullopt) + : output_table(output_table), sequence_output(sequence_output) {} std::shared_ptr
* output_table; - bool sequence_output = false; + /// \brief Controls whether batches should be emitted immediately or sequenced in order + /// + /// \see QueryOptions for more details + std::optional sequence_output; }; /// @} diff --git a/cpp/src/arrow/compute/exec/plan_test.cc b/cpp/src/arrow/compute/exec/plan_test.cc index 5b2af718df73..e0868ebf12e9 100644 --- a/cpp/src/arrow/compute/exec/plan_test.cc +++ b/cpp/src/arrow/compute/exec/plan_test.cc @@ -24,12 +24,14 @@ #include "arrow/compute/exec/exec_plan.h" #include "arrow/compute/exec/expression.h" #include "arrow/compute/exec/options.h" +#include "arrow/compute/exec/test_nodes.h" #include "arrow/compute/exec/test_util.h" #include "arrow/compute/exec/util.h" #include "arrow/io/util_internal.h" #include "arrow/record_batch.h" #include "arrow/table.h" #include "arrow/testing/future_util.h" +#include "arrow/testing/generator.h" #include "arrow/testing/gtest_util.h" #include "arrow/testing/matchers.h" #include "arrow/testing/random.h" @@ -277,6 +279,12 @@ void TestSourceSinkError( auto null_schema_options = OptionsType{no_schema, element_it_maker}; ASSERT_THAT(MakeExecNode(source_factory_name, plan.get(), {}, null_schema_options), Raises(StatusCode::Invalid, HasSubstr("not null"))); + + auto no_io_but_executor = OptionsType{exp_batches.schema, element_it_maker, + io::default_io_context().executor()}; + no_io_but_executor.requires_io = false; + ASSERT_THAT(MakeExecNode(source_factory_name, plan.get(), {}, no_io_but_executor), + Raises(StatusCode::Invalid, HasSubstr("io_executor was not nullptr"))); } template @@ -289,11 +297,19 @@ void TestSourceSink( auto element_it_maker = [&elements]() { return MakeVectorIterator(elements); }; - Declaration plan(source_factory_name, - OptionsType{exp_batches.schema, element_it_maker}); - ASSERT_OK_AND_ASSIGN(auto result, - DeclarationToExecBatches(std::move(plan), /*use_threads=*/false)); - AssertExecBatchesEqualIgnoringOrder(result.schema, result.batches, exp_batches.batches); + for (bool requires_io : {false, true}) { + for (bool use_threads : {false, true}) { + Declaration plan(source_factory_name, + OptionsType{exp_batches.schema, element_it_maker, requires_io}); + QueryOptions query_options; + query_options.use_threads = use_threads; + ASSERT_OK_AND_ASSIGN(auto result, + DeclarationToExecBatches(std::move(plan), query_options)); + // Should not need to ignore order since sink should sequence by implicit order + AssertExecBatchesEqual(result.schema, result.batches, exp_batches.batches); + AssertExecBatchesSequenced(result.batches); + } + } } void TestRecordBatchReaderSourceSink( @@ -588,6 +604,19 @@ TEST(ExecPlanExecution, SourceSinkError) { Finishes(Raises(StatusCode::Invalid, HasSubstr("Artificial")))); } +TEST(ExecPlanExecution, InvalidSequencing) { + auto basic_data = MakeBasicBatches(); + Declaration plan = Declaration::Sequence( + {{"source", SourceNodeOptions{basic_data.schema, basic_data.gen(false, false)}}, + {"aggregate", AggregateNodeOptions({}, {"i32"})}}); + + QueryOptions query_options; + ASSERT_OK(DeclarationToStatus(plan, query_options)); + query_options.sequence_output = true; + ASSERT_THAT(DeclarationToStatus(plan, query_options), + Raises(StatusCode::Invalid, HasSubstr("no meaningful ordering"))); +} + TEST(ExecPlanExecution, SourceConsumingSink) { for (bool slow : {false, true}) { SCOPED_TRACE(slow ? "slowed" : "unslowed"); @@ -952,6 +981,49 @@ TEST(ExecPlanExecution, SourceProjectSink) { AssertExecBatchesEqualIgnoringOrder(result.schema, result.batches, exp_batches); } +TEST(ExecPlanExecution, ProjectMaintainsOrder) { + RegisterTestNodes(); + constexpr int kRandomSeed = 42; + constexpr int64_t kRowsPerBatch = 1; + constexpr int kNumBatches = 16; + auto source_node = gen::Gen({{"x", gen::Step()}}) + ->FailOnError() + ->SourceNode(kRowsPerBatch, kNumBatches); + Declaration plan = + Declaration::Sequence({source_node, + {"jitter", JitterNodeOptions(kRandomSeed)}, + {"project", ProjectNodeOptions({field_ref("x")})}}); + + ASSERT_OK_AND_ASSIGN(BatchesWithCommonSchema batches, + DeclarationToExecBatches(std::move(plan))); + + AssertExecBatchesSequenced(batches.batches); +} + +TEST(ExecPlanExecution, FilterMaintainsOrder) { + RegisterTestNodes(); + constexpr int kRandomSeed = 42; + constexpr int64_t kRowsPerBatch = 1; + constexpr int kNumBatches = 16; + auto source_node = gen::Gen({{"x", gen::Step()}}) + ->FailOnError() + ->SourceNode(kRowsPerBatch, kNumBatches); + Declaration plan = Declaration::Sequence( + {source_node, + {"jitter", JitterNodeOptions(kRandomSeed)}, + {"filter", + // The filter x > 50 should result in a few empty batches + FilterNodeOptions({call("greater", {field_ref("x"), literal(50)})})}}); + + ASSERT_OK_AND_ASSIGN(BatchesWithCommonSchema batches, + DeclarationToExecBatches(std::move(plan))); + + // Sanity check that some filtering took place + ASSERT_EQ(0, batches.batches[0].length); + + AssertExecBatchesSequenced(batches.batches); +} + namespace { BatchesWithSchema MakeGroupableBatches(int multiplicity = 1) { diff --git a/cpp/src/arrow/compute/exec/sink_node.cc b/cpp/src/arrow/compute/exec/sink_node.cc index 6ad32c7adc64..34341a241e45 100644 --- a/cpp/src/arrow/compute/exec/sink_node.cc +++ b/cpp/src/arrow/compute/exec/sink_node.cc @@ -105,7 +105,8 @@ class SinkNode : public ExecNode, SinkNode(ExecPlan* plan, std::vector inputs, AsyncGenerator>* generator, std::shared_ptr* schema, BackpressureOptions backpressure, - BackpressureMonitor** backpressure_monitor_out, bool sequence_delivery) + BackpressureMonitor** backpressure_monitor_out, + std::optional sequence_output) : ExecNode(plan, std::move(inputs), {"collected"}, {}), TracedNode(this), backpressure_queue_(backpressure.resume_if_below, backpressure.pause_if_above), @@ -131,7 +132,11 @@ class SinkNode : public ExecNode, return batch; }); }; - if (sequence_delivery) { + + bool explicit_sequencing = sequence_output.has_value() && *sequence_output; + bool sequencing_disabled = sequence_output.has_value() && !*sequence_output; + if (explicit_sequencing || + (!sequencing_disabled && !inputs_[0]->ordering().is_unordered())) { sequencer_ = util::SerialSequencingQueue::Make(this); } } @@ -147,7 +152,7 @@ class SinkNode : public ExecNode, return plan->EmplaceNode(plan, std::move(inputs), sink_options.generator, sink_options.schema, sink_options.backpressure, sink_options.backpressure_monitor, - sink_options.sequence_delivery); + sink_options.sequence_output); } const char* kind_name() const override { return "SinkNode"; } @@ -177,10 +182,16 @@ class SinkNode : public ExecNode, } Status Validate() const override { + ARROW_RETURN_NOT_OK(ExecNode::Validate()); if (output_ != nullptr) { return Status::Invalid("Sink node '", label(), "' has an output"); } - return ExecNode::Validate(); + if (inputs_[0]->ordering().is_unordered() && !!sequencer_) { + return Status::Invalid("Sink node '", label(), + "' is configured to sequence output but there is no " + "meaningful ordering in the input"); + } + return Status::OK(); } void RecordBackpressureBytesUsed(const ExecBatch& batch) { @@ -284,12 +295,18 @@ class ConsumingSinkNode : public ExecNode, public: ConsumingSinkNode(ExecPlan* plan, std::vector inputs, std::shared_ptr consumer, - std::vector names, bool sequence_delivery) + std::vector names, std::optional sequence_output) : ExecNode(plan, std::move(inputs), {"to_consume"}, {}), TracedNode(this), consumer_(std::move(consumer)), names_(std::move(names)) { - if (sequence_delivery) { + bool explicit_sequencing = sequence_output.has_value() && *sequence_output; + bool sequencing_disabled = sequence_output.has_value() && !*sequence_output; + // If the user explicitly requests sequencing then we configure a sequencer_ even + // if the input isn't ordered. This will later lead to a validation failure (which is + // what the user is asking for in this case) + if (explicit_sequencing || + (!sequencing_disabled && !inputs_[0]->ordering().is_unordered())) { sequencer_ = util::SerialSequencingQueue::Make(this); } } @@ -331,6 +348,19 @@ class ConsumingSinkNode : public ExecNode, return Status::OK(); } + Status Validate() const override { + ARROW_RETURN_NOT_OK(ExecNode::Validate()); + if (output_ != nullptr) { + return Status::Invalid("Consuming sink node '", label(), "' has an output"); + } + if (inputs_[0]->ordering().is_unordered() && !!sequencer_) { + return Status::Invalid("Consuming sink node '", label(), + "' is configured to sequence output but there is no " + "meaningful ordering in the input"); + } + return Status::OK(); + } + // sink nodes have no outputs from which to feel backpressure [[noreturn]] static void NoOutputs() { Unreachable("no outputs; this should never be called"); @@ -417,7 +447,7 @@ struct OrderBySinkNode final : public SinkNode { AsyncGenerator>* generator) : SinkNode(plan, std::move(inputs), generator, /*schema=*/nullptr, /*backpressure=*/{}, - /*backpressure_monitor_out=*/nullptr, /*sequence_delivery=*/false), + /*backpressure_monitor_out=*/nullptr, /*sequence_output=*/false), impl_(std::move(impl)) {} const char* kind_name() const override { return "OrderBySinkNode"; } diff --git a/cpp/src/arrow/compute/exec/source_node.cc b/cpp/src/arrow/compute/exec/source_node.cc index ab74f98673f7..1730ee4e9304 100644 --- a/cpp/src/arrow/compute/exec/source_node.cc +++ b/cpp/src/arrow/compute/exec/source_node.cc @@ -52,10 +52,12 @@ namespace { struct SourceNode : ExecNode, public TracedNode { SourceNode(ExecPlan* plan, std::shared_ptr output_schema, - AsyncGenerator> generator) + AsyncGenerator> generator, + Ordering ordering = Ordering::Unordered()) : ExecNode(plan, {}, {}, std::move(output_schema)), TracedNode(this), - generator_(std::move(generator)) {} + generator_(std::move(generator)), + ordering_(ordering) {} static Result Make(ExecPlan* plan, std::vector inputs, const ExecNodeOptions& options) { @@ -76,6 +78,7 @@ struct SourceNode : ExecNode, public TracedNode { void SliceAndDeliverMorsel(const ExecBatch& morsel) { bool use_legacy_batching = plan_->query_context()->options().use_legacy_batching; int64_t morsel_length = static_cast(morsel.length); + int initial_batch_index = batch_count_; if (use_legacy_batching || morsel_length == 0) { // For various reasons (e.g. ARROW-13982) we pass empty batches // through @@ -86,8 +89,10 @@ struct SourceNode : ExecNode, public TracedNode { batch_count_ += num_batches; } plan_->query_context()->ScheduleTask( - [this, morsel_length, use_legacy_batching, morsel]() { + [this, morsel_length, use_legacy_batching, initial_batch_index, morsel, + has_ordering = !ordering_.is_unordered()]() { int64_t offset = 0; + int batch_index = initial_batch_index; do { int64_t batch_size = std::min(morsel_length - offset, ExecPlan::kMaxBatchSize); @@ -97,7 +102,11 @@ struct SourceNode : ExecNode, public TracedNode { batch_size = morsel_length; } ExecBatch batch = morsel.Slice(offset, batch_size); + if (has_ordering) { + batch.index = batch_index; + } offset += batch_size; + batch_index++; ARROW_RETURN_NOT_OK(output_->InputReceived(this, std::move(batch))); } while (offset < morsel.length); return Status::OK(); @@ -176,6 +185,8 @@ struct SourceNode : ExecNode, public TracedNode { return Status::OK(); } + const Ordering& ordering() const override { return ordering_; } + void PauseProducing(ExecNode* output, int32_t counter) override { std::lock_guard lg(mutex_); if (counter <= backpressure_counter_) { @@ -218,12 +229,14 @@ struct SourceNode : ExecNode, public TracedNode { bool stop_requested_{false}; bool started_ = false; int batch_count_{0}; - AsyncGenerator> generator_; + const AsyncGenerator> generator_; + const Ordering ordering_; }; struct TableSourceNode : public SourceNode { TableSourceNode(ExecPlan* plan, std::shared_ptr
table, int64_t batch_size) - : SourceNode(plan, table->schema(), TableGenerator(*table, batch_size)) {} + : SourceNode(plan, table->schema(), TableGenerator(*table, batch_size), + Ordering::Implicit()) {} static Result Make(ExecPlan* plan, std::vector inputs, const ExecNodeOptions& options) { @@ -274,7 +287,6 @@ struct TableSourceNode : public SourceNode { std::shared_ptr batch; std::vector exec_batches; - int index = 0; while (true) { auto batch_res = reader->Next(); if (batch_res.ok()) { @@ -284,7 +296,6 @@ struct TableSourceNode : public SourceNode { break; } exec_batches.emplace_back(*batch); - exec_batches[exec_batches.size() - 1].index = index++; } return exec_batches; } @@ -294,7 +305,7 @@ template struct SchemaSourceNode : public SourceNode { SchemaSourceNode(ExecPlan* plan, std::shared_ptr schema, arrow::AsyncGenerator> generator) - : SourceNode(plan, schema, generator) {} + : SourceNode(plan, schema, generator, Ordering::Implicit()) {} static Result Make(ExecPlan* plan, std::vector inputs, const ExecNodeOptions& options) { @@ -306,11 +317,20 @@ struct SchemaSourceNode : public SourceNode { auto it = it_maker(); - if (schema == NULLPTR) { + if (schema == nullptr) { return Status::Invalid(This::kKindName, " requires schema which is not null"); } - if (io_executor == NULLPTR) { - io_executor = io::internal::GetIOThreadPool(); + + if (cast_options.requires_io) { + if (io_executor == nullptr) { + io_executor = io::internal::GetIOThreadPool(); + } + } else { + if (io_executor != nullptr) { + return Status::Invalid( + This::kKindName, + " specified with requires_io=false but io_executor was not nullptr"); + } } ARROW_ASSIGN_OR_RAISE(auto generator, This::MakeGenerator(it, io_executor, schema)); @@ -356,6 +376,9 @@ struct RecordBatchReaderSourceNode : public SourceNode { }; Iterator> batch_it = MakeIteratorFromReader(reader); auto exec_batch_it = MakeMapIterator(to_exec_batch, std::move(batch_it)); + if (io_executor == nullptr) { + return MakeBlockingGenerator(std::move(exec_batch_it)); + } return MakeBackgroundGenerator(std::move(exec_batch_it), io_executor); } @@ -389,6 +412,9 @@ struct RecordBatchSourceNode return std::optional(ExecBatch(*batch)); }; auto exec_batch_it = MakeMapIterator(to_exec_batch, std::move(batch_it)); + if (io_executor == nullptr) { + return MakeBlockingGenerator(std::move(exec_batch_it)); + } return MakeBackgroundGenerator(std::move(exec_batch_it), io_executor); } @@ -419,6 +445,9 @@ struct ExecBatchSourceNode return batch == NULLPTR ? std::nullopt : std::optional(*batch); }; auto exec_batch_it = MakeMapIterator(to_exec_batch, std::move(batch_it)); + if (io_executor == nullptr) { + return MakeBlockingGenerator(std::move(exec_batch_it)); + } return MakeBackgroundGenerator(std::move(exec_batch_it), io_executor); } @@ -457,6 +486,9 @@ struct ArrayVectorSourceNode ExecBatch(std::move(datumvec), (*arrayvec)[0]->length())); }; auto exec_batch_it = MakeMapIterator(to_exec_batch, std::move(arrayvec_it)); + if (io_executor == nullptr) { + return MakeBlockingGenerator(std::move(exec_batch_it)); + } return MakeBackgroundGenerator(std::move(exec_batch_it), io_executor); } diff --git a/cpp/src/arrow/compute/exec/test_nodes.cc b/cpp/src/arrow/compute/exec/test_nodes.cc index 85e272dbbcb0..94a0df58c362 100644 --- a/cpp/src/arrow/compute/exec/test_nodes.cc +++ b/cpp/src/arrow/compute/exec/test_nodes.cc @@ -121,6 +121,8 @@ class JitterNode : public ExecNode { const char* kind_name() const override { return "JitterNode"; } + const Ordering& ordering() const override { return inputs_[0]->ordering(); } + Status StartProducing() override { return Status::OK(); } void PauseProducing(ExecNode* output, int32_t counter) override { diff --git a/cpp/src/arrow/compute/exec/test_nodes.h b/cpp/src/arrow/compute/exec/test_nodes.h index 3417e6dd4336..afe37f8c9f91 100644 --- a/cpp/src/arrow/compute/exec/test_nodes.h +++ b/cpp/src/arrow/compute/exec/test_nodes.h @@ -48,7 +48,7 @@ struct JitterNodeOptions : public ExecNodeOptions { /// The max amount to add to a node's "cost". int max_jitter_modifier; - JitterNodeOptions(random::SeedType seed, int max_jitter_modifier) + explicit JitterNodeOptions(random::SeedType seed, int max_jitter_modifier = 5) : seed(seed), max_jitter_modifier(max_jitter_modifier) {} static constexpr std::string_view kName = "jitter"; }; diff --git a/cpp/src/arrow/compute/exec/test_nodes_test.cc b/cpp/src/arrow/compute/exec/test_nodes_test.cc index cfc0637b2f7d..201c46c42f21 100644 --- a/cpp/src/arrow/compute/exec/test_nodes_test.cc +++ b/cpp/src/arrow/compute/exec/test_nodes_test.cc @@ -39,8 +39,10 @@ TEST(JitterNode, Basic) { Declaration plan = Declaration::Sequence({{"table_source", TableSourceNodeOptions(input)}, {"jitter", JitterNodeOptions(kTestSeed, kMaxJitterMod)}}); + QueryOptions query_options; + query_options.sequence_output = false; ASSERT_OK_AND_ASSIGN(BatchesWithCommonSchema batches_and_schema, - DeclarationToExecBatches(std::move(plan))); + DeclarationToExecBatches(std::move(plan), query_options)); ASSERT_EQ(kNumBatches, static_cast(batches_and_schema.batches.size())); int numOutOfPlace = 0; diff --git a/cpp/src/arrow/compute/exec/test_util.cc b/cpp/src/arrow/compute/exec/test_util.cc index a1487c9b3412..ddfc58426d1a 100644 --- a/cpp/src/arrow/compute/exec/test_util.cc +++ b/cpp/src/arrow/compute/exec/test_util.cc @@ -420,6 +420,21 @@ void AssertExecBatchesEqualIgnoringOrder(const std::shared_ptr& schema, AssertTablesEqualIgnoringOrder(exp_tab, act_tab); } +void AssertExecBatchesEqual(const std::shared_ptr& schema, + const std::vector& exp, + const std::vector& act) { + ASSERT_OK_AND_ASSIGN(auto exp_tab, TableFromExecBatches(schema, exp)); + ASSERT_OK_AND_ASSIGN(auto act_tab, TableFromExecBatches(schema, act)); + AssertTablesEqual(*exp_tab, *act_tab); +} + +void AssertExecBatchesSequenced(const std::vector& batches) { + int expected_index = 0; + for (const auto& batch : batches) { + ASSERT_EQ(expected_index++, batch.index); + } +} + template static const T& OptionsAs(const ExecNodeOptions& opts) { const auto& ptr = checked_cast(opts); diff --git a/cpp/src/arrow/compute/exec/test_util.h b/cpp/src/arrow/compute/exec/test_util.h index d10ed783eb91..7da3cba5aca7 100644 --- a/cpp/src/arrow/compute/exec/test_util.h +++ b/cpp/src/arrow/compute/exec/test_util.h @@ -166,6 +166,14 @@ void AssertExecBatchesEqualIgnoringOrder(const std::shared_ptr& schema, const std::vector& exp, const std::vector& act); +ARROW_TESTING_EXPORT +void AssertExecBatchesEqual(const std::shared_ptr& schema, + const std::vector& exp, + const std::vector& act); + +ARROW_TESTING_EXPORT void AssertExecBatchesSequenced( + const std::vector& batches); + ARROW_TESTING_EXPORT bool operator==(const Declaration&, const Declaration&); diff --git a/cpp/src/arrow/compute/exec_test.cc b/cpp/src/arrow/compute/exec_test.cc index 24da4a2e8dec..d661e5735fea 100644 --- a/cpp/src/arrow/compute/exec_test.cc +++ b/cpp/src/arrow/compute/exec_test.cc @@ -33,6 +33,7 @@ #include "arrow/compute/function.h" #include "arrow/compute/function_internal.h" #include "arrow/compute/kernel.h" +#include "arrow/compute/ordering.h" #include "arrow/compute/registry.h" #include "arrow/memory_pool.h" #include "arrow/record_batch.h" @@ -1395,6 +1396,35 @@ TEST_F(TestCallScalarFunctionScalarFunction, ExecCall) { TestCallScalarFunctionScalarFunction::DoTest(ExecFunctionCaller::Maker); } +TEST(Ordering, IsSuborderOf) { + Ordering a{{SortKey{3}, SortKey{1}, SortKey{7}}}; + Ordering b{{SortKey{3}, SortKey{1}}}; + Ordering c{{SortKey{1}, SortKey{7}}}; + Ordering d{{SortKey{1}, SortKey{7}}, NullPlacement::AtEnd}; + Ordering imp = Ordering::Implicit(); + Ordering unordered = Ordering::Unordered(); + + std::vector orderings = {a, b, c, d, imp, unordered}; + + auto CheckOrdering = [&](const Ordering& ordering, std::vector expected) { + for (std::size_t other_idx = 0; other_idx < orderings.size(); other_idx++) { + const auto& other = orderings[other_idx]; + if (expected[other_idx]) { + ASSERT_TRUE(ordering.IsSuborderOf(other)); + } else { + ASSERT_FALSE(ordering.IsSuborderOf(other)); + } + } + }; + + CheckOrdering(a, {true, false, false, false, false, false}); + CheckOrdering(b, {true, true, false, false, false, false}); + CheckOrdering(c, {false, false, true, false, false, false}); + CheckOrdering(d, {false, false, false, true, false, false}); + CheckOrdering(imp, {false, false, false, false, false, false}); + CheckOrdering(unordered, {true, true, true, true, true, true}); +} + } // namespace detail } // namespace compute } // namespace arrow diff --git a/cpp/src/arrow/compute/ordering.cc b/cpp/src/arrow/compute/ordering.cc new file mode 100644 index 000000000000..25ad6a5ca5f8 --- /dev/null +++ b/cpp/src/arrow/compute/ordering.cc @@ -0,0 +1,95 @@ +// 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 + +#include "arrow/compute/ordering.h" +#include "arrow/util/unreachable.h" + +namespace arrow { +namespace compute { + +bool SortKey::Equals(const SortKey& other) const { + return target == other.target && order == other.order; +} + +std::string SortKey::ToString() const { + std::stringstream ss; + ss << target.ToString() << ' '; + switch (order) { + case SortOrder::Ascending: + ss << "ASC"; + break; + case SortOrder::Descending: + ss << "DESC"; + break; + } + return ss.str(); +} + +bool Ordering::IsSuborderOf(const Ordering& other) const { + if (sort_keys_.empty()) { + // The implicit ordering is a subordering of nothing. The unordered ordering + // is a subordering of everything + return !is_implicit_; + } + if (null_placement_ != other.null_placement_) { + return false; + } + if (sort_keys_.size() > other.sort_keys_.size()) { + return false; + } + for (std::size_t key_idx = 0; key_idx < sort_keys_.size(); key_idx++) { + if (sort_keys_[key_idx] != other.sort_keys_[key_idx]) { + return false; + } + } + return true; +} + +bool Ordering::Equals(const Ordering& other) const { + return null_placement_ == other.null_placement_ && sort_keys_ == other.sort_keys_; +} + +std::string Ordering::ToString() const { + std::stringstream ss; + ss << "["; + bool first = true; + for (const auto& key : sort_keys_) { + if (first) { + first = false; + } else { + ss << ", "; + } + ss << key.ToString(); + } + ss << "]"; + switch (null_placement_) { + case NullPlacement::AtEnd: + ss << " nulls last"; + break; + case NullPlacement::AtStart: + ss << " nulls first"; + break; + default: + Unreachable(); + } + return ss.str(); +} + +} // namespace compute +} // namespace arrow diff --git a/cpp/src/arrow/compute/ordering.h b/cpp/src/arrow/compute/ordering.h new file mode 100644 index 000000000000..b4c38e610339 --- /dev/null +++ b/cpp/src/arrow/compute/ordering.h @@ -0,0 +1,120 @@ +// 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. + +#pragma once + +#include +#include + +#include "arrow/type.h" +#include "arrow/util/compare.h" +#include "arrow/util/visibility.h" + +namespace arrow { +namespace compute { + +enum class SortOrder { + /// Arrange values in increasing order + Ascending, + /// Arrange values in decreasing order + Descending, +}; + +enum class NullPlacement { + /// Place nulls and NaNs before any non-null values. + /// NaNs will come after nulls. + AtStart, + /// Place nulls and NaNs after any non-null values. + /// NaNs will come before nulls. + AtEnd, +}; + +/// \brief One sort key for PartitionNthIndices (TODO) and SortIndices +class ARROW_EXPORT SortKey : public util::EqualityComparable { + public: + explicit SortKey(FieldRef target, SortOrder order = SortOrder::Ascending) + : target(std::move(target)), order(order) {} + + bool Equals(const SortKey& other) const; + std::string ToString() const; + + /// A FieldRef targetting the sort column. + FieldRef target; + /// How to order by this sort key. + SortOrder order; +}; + +class ARROW_EXPORT Ordering : public util::EqualityComparable { + public: + Ordering(std::vector sort_keys, + NullPlacement null_placement = NullPlacement::AtStart) + : sort_keys_(std::move(sort_keys)), null_placement_(null_placement) {} + /// true if data ordered by other is also ordered by this + /// + /// For example, if data is ordered by [a, b, c] then it is also ordered + /// by [a, b] but not by [b, c] or [a, b, c, d]. + /// + /// [a, b].IsSuborderOf([a, b, c]) - true + /// [a, b, c].IsSuborderOf([a, b, c]) - true + /// [b, c].IsSuborderOf([a, b, c]) - false + /// [a, b, c, d].IsSuborderOf([a, b, c]) - false + /// + /// The implicit ordering is not a suborder of any other ordering and + /// no other ordering is a suborder of it. The implicit ordering is not a + /// suborder of itself. + /// + /// The unordered ordering is a suborder of all other orderings but no + /// other ordering is a suborder of it. The unordered ordering is a suborder + /// of itself. + /// + /// The unordered ordering is a suborder of the implicit ordering. + bool IsSuborderOf(const Ordering& other) const; + + bool Equals(const Ordering& other) const; + std::string ToString() const; + + bool is_implicit() const { return is_implicit_; } + bool is_unordered() const { return !is_implicit_ && sort_keys_.empty(); } + + std::vector sort_keys() { return sort_keys_; } + NullPlacement null_placement() { return null_placement_; } + + static const Ordering& Implicit() { + static const Ordering kImplicit(true); + return kImplicit; + } + + static const Ordering& Unordered() { + static const Ordering kUnordered(false); + // It is also possible to get an unordered ordering by passing in an empty vector + // using the normal constructor. This is ok and useful when ordering comes from user + // input. + return kUnordered; + } + + private: + explicit Ordering(bool is_implicit) + : null_placement_(NullPlacement::AtStart), is_implicit_(is_implicit) {} + /// Column key(s) to order by and how to order by these sort keys. + std::vector sort_keys_; + /// Whether nulls and NaNs are placed at the start or at the end + NullPlacement null_placement_; + bool is_implicit_ = false; +}; + +} // namespace compute +} // namespace arrow diff --git a/cpp/src/arrow/compute/registry.h b/cpp/src/arrow/compute/registry.h index e64a767271cd..a7eb4bcf346b 100644 --- a/cpp/src/arrow/compute/registry.h +++ b/cpp/src/arrow/compute/registry.h @@ -117,8 +117,5 @@ class ARROW_EXPORT FunctionRegistry { explicit FunctionRegistry(FunctionRegistryImpl* impl); }; -/// \brief Return the process-global function registry. -ARROW_EXPORT FunctionRegistry* GetFunctionRegistry(); - } // namespace compute } // namespace arrow diff --git a/cpp/src/arrow/compute/type_fwd.h b/cpp/src/arrow/compute/type_fwd.h index 827116e37bef..220460c460f4 100644 --- a/cpp/src/arrow/compute/type_fwd.h +++ b/cpp/src/arrow/compute/type_fwd.h @@ -31,6 +31,10 @@ class FunctionExecutor; class FunctionOptions; class FunctionRegistry; +/// \brief Return the process-global function registry. +// Defined in registry.cc +ARROW_EXPORT FunctionRegistry* GetFunctionRegistry(); + class CastOptions; struct ExecBatch; diff --git a/cpp/src/arrow/testing/generator.cc b/cpp/src/arrow/testing/generator.cc index a0d8968bb320..ad0984e4083b 100644 --- a/cpp/src/arrow/testing/generator.cc +++ b/cpp/src/arrow/testing/generator.cc @@ -28,6 +28,7 @@ #include "arrow/buffer.h" #include "arrow/builder.h" #include "arrow/compute/exec.h" +#include "arrow/compute/exec/options.h" #include "arrow/datum.h" #include "arrow/record_batch.h" #include "arrow/scalar.h" @@ -308,6 +309,15 @@ class DataGeneratorImpl : public DataGenerator, } return batches; } + + Result<::arrow::compute::Declaration> SourceNode(int64_t rows_per_batch, + int num_batches) override { + ARROW_ASSIGN_OR_RAISE(std::vector<::arrow::compute::ExecBatch> batches, + ExecBatches(rows_per_batch, num_batches)); + return ::arrow::compute::Declaration( + "exec_batch_source", + ::arrow::compute::ExecBatchSourceNodeOptions(schema_, std::move(batches))); + } #endif Result> Table(int64_t rows_per_chunk, @@ -365,6 +375,12 @@ class GTestDataGeneratorImpl : public GTestDataGenerator { EXPECT_OK_AND_ASSIGN(auto batches, target_->ExecBatches(rows_per_batch, num_batches)); return batches; } + ::arrow::compute::Declaration SourceNode(int64_t rows_per_batch, + int num_batches) override { + EXPECT_OK_AND_ASSIGN(auto source_node, + target_->SourceNode(rows_per_batch, num_batches)); + return source_node; + } #endif std::shared_ptr<::arrow::Table> Table(int64_t rows_per_chunk, int num_chunks) override { EXPECT_OK_AND_ASSIGN(auto table, target_->Table(rows_per_chunk, num_chunks)); diff --git a/cpp/src/arrow/testing/generator.h b/cpp/src/arrow/testing/generator.h index 06cbbcfbbda6..9f02df4505fe 100644 --- a/cpp/src/arrow/testing/generator.h +++ b/cpp/src/arrow/testing/generator.h @@ -256,6 +256,8 @@ class ARROW_TESTING_EXPORT GTestDataGenerator { virtual ::arrow::compute::ExecBatch ExecBatch(int64_t num_rows) = 0; virtual std::vector<::arrow::compute::ExecBatch> ExecBatches(int64_t rows_per_batch, int num_batches) = 0; + virtual ::arrow::compute::Declaration SourceNode(int64_t rows_per_batch, + int num_batches) = 0; #endif virtual std::shared_ptr<::arrow::Table> Table(int64_t rows_per_chunk, int num_chunks = 1) = 0; @@ -272,6 +274,8 @@ class ARROW_TESTING_EXPORT DataGenerator { virtual Result<::arrow::compute::ExecBatch> ExecBatch(int64_t num_rows) = 0; virtual Result> ExecBatches( int64_t rows_per_batch, int num_batches) = 0; + virtual Result<::arrow::compute::Declaration> SourceNode(int64_t rows_per_batch, + int num_batches) = 0; #endif virtual Result> Table(int64_t rows_per_chunk, int num_chunks = 1) = 0; diff --git a/cpp/src/arrow/util/async_generator.h b/cpp/src/arrow/util/async_generator.h index 5bef9c38246f..a06be707f2fb 100644 --- a/cpp/src/arrow/util/async_generator.h +++ b/cpp/src/arrow/util/async_generator.h @@ -1859,6 +1859,33 @@ static Result> MakeBackgroundGenerator( return BackgroundGenerator(std::move(iterator), io_executor, max_q, q_restart); } +/// \brief Create an AsyncGenerator by iterating over an Iterator synchronously +/// +/// This should only be used if you know the source iterator does not involve any +/// I/O (or other blocking calls). Otherwise a CPU thread will be blocked and, depending +/// on the complexity of the iterator, it may lead to deadlock. +/// +/// If you are not certain if there will be I/O then it is better to use +/// MakeBackgroundGenerator. If helpful you can think of this as the AsyncGenerator +/// equivalent of Future::MakeFinished +/// +/// It is impossible to call this in an async-reentrant manner since the returned +/// future will be completed by the time it is polled. +/// +/// This generator does not queue +template +static Result> MakeBlockingGenerator( + std::shared_ptr> iterator) { + return [it = std::move(iterator)]() mutable -> Future { + return Future::MakeFinished(it->Next()); + }; +} + +template +static Result> MakeBlockingGenerator(Iterator iterator) { + return MakeBlockingGenerator(std::make_shared>(std::move(iterator))); +} + /// \see MakeGeneratorIterator template class GeneratorIterator {