From bb184c2ef1d3dba40d89095d96bf938ee79880de Mon Sep 17 00:00:00 2001 From: Matthew Ball Date: Fri, 13 Nov 2026 15:17:26 -0800 Subject: [PATCH 01/16] feat(engine): columnar operator contract and Arrow batch paths The foundation for a columnar Arrow wire: an operator-side contract for consuming and producing Arrow batches directly, the Arrow helpers it needs, and the first two operators that implement it (the specialized filter and the Arrow file scan). Nothing is wired into the messaging layer yet, so no operator receives columnar batches at runtime; these are the capabilities the wire will drive. Contract (ColumnarOperatorExecutor): - ColumnarOperatorExecutor is a trait with processColumnarBatch(arrowIpcBytes, port) that returns a ColumnarResult. An operator mixes it in to declare it can consume an Arrow batch without decoding each row to a Tuple. - ColumnarResult is the sealed outcome of consuming one batch: Emit(root) (emit this Arrow result, caller serializes and closes the root), EmitRows(iterator) (emit row-shaped output, e.g. a join), Consumed (consumed with nothing to emit now, a blocking operator accumulating state), and Unsupported (not handled, caller falls back to the row path). - SourceOperatorExecutor gains produceColumnarBatch(), defaulting to None, so a source whose data is already columnar can hand out Arrow roots instead of going through produceTuple; the caller owns and closes each root. ArrowUtils helpers: - serializeRoot writes a VectorSchemaRoot to Arrow IPC stream bytes without closing it; deserializeRootFold reads one IPC batch, applies a function to the live root, and closes the reader (the function must copy out what it keeps). - selectRows copies the rows a boolean keep-mask selects into a new compacted root; selectionOf returns just the surviving row indices (a selection vector) without copying any cell, and gather materializes the rows a selection vector names into a new root, so a consumer that only needs a count or an aggregate reads indices and never materializes. - projectionIndices resolves column names to their Arrow field indices by exact name; getCell reads one cell as the Texera value for an attribute type, returning null on a conversion failure to match the row path's lenient decode. SpecializedFilterOpExec columnar path: - The operator now also mixes in ColumnarOperatorExecutor while keeping its row path (the per-tuple OR over predicates) unchanged. columnarMask builds a boolean survivor mask for a single numeric predicate (Float8Vector or IntVector) read straight from the Arrow vector, and returns None for any other predicate or column shape so the caller falls back to rows. - processColumnarBatch deserializes the batch and returns Emit(selectRows(mask)) when the mask applies, else Unsupported. columnarSelection returns the survivor indices without compacting, and columnarMatchCount is the fused filter-then-count that reports the survivor count with no batch materialized. A per-operator RootAllocator backs these and is freed in close(). ArrowSourceOpExec columnar produce: - produceColumnarBatch hands each already-Arrow file batch out as a VectorSchemaRoot, moving the loaded batch's vectors into an independent root via a zero-copy TransferPair so the caller can serialize and close it while the reader loads the next batch. It returns None (the row path) when offset or limit is set. --- .../executor/ColumnarOperatorExecutor.scala | 52 +++++++++ .../executor/SourceOperatorExecutor.scala | 10 ++ .../apache/texera/amber/util/ArrowUtils.scala | 108 ++++++++++++++++++ .../filter/SpecializedFilterOpExec.scala | 90 ++++++++++++++- .../source/scan/arrow/ArrowSourceOpExec.scala | 32 +++++- 5 files changed, 290 insertions(+), 2 deletions(-) create mode 100644 common/workflow-core/src/main/scala/org/apache/texera/amber/core/executor/ColumnarOperatorExecutor.scala diff --git a/common/workflow-core/src/main/scala/org/apache/texera/amber/core/executor/ColumnarOperatorExecutor.scala b/common/workflow-core/src/main/scala/org/apache/texera/amber/core/executor/ColumnarOperatorExecutor.scala new file mode 100644 index 00000000000..853004b32e1 --- /dev/null +++ b/common/workflow-core/src/main/scala/org/apache/texera/amber/core/executor/ColumnarOperatorExecutor.scala @@ -0,0 +1,52 @@ +/* + * 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. + */ + +package org.apache.texera.amber.core.executor + +import org.apache.arrow.vector.VectorSchemaRoot +import org.apache.texera.amber.core.tuple.TupleLike +import org.apache.texera.amber.core.workflow.PortIdentity + +/** + * Outcome of consuming one Arrow batch: + * - Emit: consumed, emit this Arrow result batch downstream (caller serializes and closes the root). + * - EmitRows: consumed, emit these row outputs (e.g. a join whose output is row-shaped); + * the caller ships them, still columnar on the wire if enabled. + * - Consumed: consumed, nothing to emit now (a blocking operator accumulating state). + * - Unsupported: not handled, caller falls back to the row path (decode + processTuple). + */ +sealed trait ColumnarResult +object ColumnarResult { + final case class Emit(root: VectorSchemaRoot) extends ColumnarResult + final case class EmitRows(rows: Iterator[(TupleLike, Option[PortIdentity])]) + extends ColumnarResult + case object Consumed extends ColumnarResult + case object Unsupported extends ColumnarResult +} + +/** + * An operator that can consume an Arrow columnar batch directly (no per-row + * Tuple decode). Given the incoming batch as Arrow IPC bytes and the input + * port it arrived on, returns a ColumnarResult telling the caller whether it + * emitted a batch/rows, consumed the batch with no output, or could not handle + * it (fall back to the row path). + */ +trait ColumnarOperatorExecutor { + def processColumnarBatch(arrowIpcBytes: Array[Byte], port: Int): ColumnarResult +} diff --git a/common/workflow-core/src/main/scala/org/apache/texera/amber/core/executor/SourceOperatorExecutor.scala b/common/workflow-core/src/main/scala/org/apache/texera/amber/core/executor/SourceOperatorExecutor.scala index 633314679a4..99f8f6d9b8d 100644 --- a/common/workflow-core/src/main/scala/org/apache/texera/amber/core/executor/SourceOperatorExecutor.scala +++ b/common/workflow-core/src/main/scala/org/apache/texera/amber/core/executor/SourceOperatorExecutor.scala @@ -19,6 +19,7 @@ package org.apache.texera.amber.core.executor +import org.apache.arrow.vector.VectorSchemaRoot import org.apache.texera.amber.core.tuple.{Tuple, TupleLike} import org.apache.texera.amber.core.workflow.PortIdentity @@ -35,6 +36,15 @@ trait SourceOperatorExecutor extends OperatorExecutor { def produceTuple(): Iterator[TupleLike] + /** + * Source operators whose data is already columnar (e.g. an Arrow file) can + * override this to hand out Arrow batches directly, skipping the per-row Tuple + * decode. The default returns None, meaning this source has no native columnar + * path and the engine uses produceTuple. The caller owns and closes each + * returned root. Honored only when the columnar wire is enabled. + */ + def produceColumnarBatch(): Option[Iterator[VectorSchemaRoot]] = None + override def onFinishMultiPort(port: Int): Iterator[(TupleLike, Option[PortIdentity])] = { // We assume there is only one input port for source operators. The current assumption // makes produceTuple to be invoked on each input port finish. diff --git a/common/workflow-core/src/main/scala/org/apache/texera/amber/util/ArrowUtils.scala b/common/workflow-core/src/main/scala/org/apache/texera/amber/util/ArrowUtils.scala index d8bcca13d84..24a55a23d08 100644 --- a/common/workflow-core/src/main/scala/org/apache/texera/amber/util/ArrowUtils.scala +++ b/common/workflow-core/src/main/scala/org/apache/texera/amber/util/ArrowUtils.scala @@ -38,7 +38,10 @@ import org.apache.arrow.vector.{ VarCharVector, VectorSchemaRoot } +import org.apache.arrow.vector.ipc.{ArrowStreamReader, ArrowStreamWriter} +import java.io.{ByteArrayInputStream, ByteArrayOutputStream} +import java.nio.channels.Channels import java.nio.charset.StandardCharsets import java.sql.Timestamp import java.time.temporal.ChronoUnit @@ -55,6 +58,111 @@ object ArrowUtils extends LazyLogging { implicit def bool2int(b: Boolean): Int = if (b) 1 else 0 + // Serialize a VectorSchemaRoot to Arrow IPC stream bytes. Does not close root. + def serializeRoot(root: VectorSchemaRoot): Array[Byte] = { + val out = new ByteArrayOutputStream() + val writer = new ArrowStreamWriter(root, null, Channels.newChannel(out)) + try { writer.start(); writer.writeBatch(); writer.end() } + finally writer.close() + out.toByteArray + } + + // Read one Arrow IPC batch, apply `f` to the live root, then close the reader. + // `f` must copy anything it needs out (the root is freed on return). + def deserializeRootFold[T](bytes: Array[Byte], allocator: BufferAllocator)( + f: VectorSchemaRoot => T + ): T = { + val reader = new ArrowStreamReader(new ByteArrayInputStream(bytes), allocator) + try { + reader.loadNextBatch() + f(reader.getVectorSchemaRoot) + } finally reader.close() + } + + // Copy the rows of `src` where keep(i) is true into a new independent root. + def selectRows( + src: VectorSchemaRoot, + keep: Array[Boolean], + allocator: BufferAllocator + ): VectorSchemaRoot = { + val dest = VectorSchemaRoot.create(src.getSchema, allocator) + val srcVecs = src.getFieldVectors + val destVecs = dest.getFieldVectors + var destIdx = 0 + var i = 0 + val n = src.getRowCount + while (i < n) { + if (keep(i)) { + var c = 0 + while (c < srcVecs.size) { + destVecs.get(c).copyFromSafe(i, destIdx, srcVecs.get(c)); c += 1 + } + destIdx += 1 + } + i += 1 + } + dest.setRowCount(destIdx) + dest + } + + // Selection vector: the indices of `src`'s rows where keep(i) is true, in order. + // Records which rows passed without copying any cell (unlike selectRows). A + // consumer that only needs a count or an aggregate reads the indices and never + // materializes; a consumer that needs contiguous rows calls `gather`. + def selectionOf(keep: Array[Boolean], rowCount: Int): Array[Int] = { + val sel = new Array[Int](rowCount) + var n = 0 + var i = 0 + while (i < rowCount) { if (keep(i)) { sel(n) = i; n += 1 }; i += 1 } + if (n == rowCount) sel else java.util.Arrays.copyOf(sel, n) + } + + // Materialize the rows named by a selection vector into a new compacted root + // (the deferred copy). Inverse endpoint of selectionOf for consumers that need + // contiguous Arrow columns (e.g. shipping to the wire). + def gather( + src: VectorSchemaRoot, + selection: Array[Int], + allocator: BufferAllocator + ): VectorSchemaRoot = { + val dest = VectorSchemaRoot.create(src.getSchema, allocator) + val srcVecs = src.getFieldVectors + val destVecs = dest.getFieldVectors + var di = 0 + while (di < selection.length) { + val i = selection(di) + var c = 0 + while (c < srcVecs.size) { destVecs.get(c).copyFromSafe(i, di, srcVecs.get(c)); c += 1 } + di += 1 + } + dest.setRowCount(selection.length) + dest + } + + // Resolve the column indices of `names` in an Arrow batch, by exact name. + def projectionIndices(root: VectorSchemaRoot, names: Seq[String]): Array[Int] = { + val fields = root.getSchema.getFields + names.map { name => + var idx = -1 + var k = 0 + while (k < fields.size && idx < 0) { if (fields.get(k).getName == name) idx = k; k += 1 } + if (idx < 0) throw new IllegalArgumentException(s"column '$name' not found in Arrow batch") + idx + }.toArray + } + + // Read one cell as the Texera value for `attrType`, returning null on any + // conversion failure (matches the row path's lenient decode). + def getCell(vector: FieldVector, rowIndex: Int, attrType: AttributeType): AnyRef = { + val raw = vector.getObject(rowIndex) + try { + attrType match { + case AttributeType.TIMESTAMP => wallClockOf(raw, vector.getField.getType) + case _ => AttributeTypeUtils.parseField(raw, attrType).asInstanceOf[AnyRef] + } + } catch { case _: Exception => null } + } + /** * Reads a row of the given Arrow Vectors into a Texera.Tuple * e.g., diff --git a/common/workflow-operator/src/main/scala/org/apache/texera/amber/operator/filter/SpecializedFilterOpExec.scala b/common/workflow-operator/src/main/scala/org/apache/texera/amber/operator/filter/SpecializedFilterOpExec.scala index 30f1d955865..32643cd73bc 100644 --- a/common/workflow-operator/src/main/scala/org/apache/texera/amber/operator/filter/SpecializedFilterOpExec.scala +++ b/common/workflow-operator/src/main/scala/org/apache/texera/amber/operator/filter/SpecializedFilterOpExec.scala @@ -19,11 +19,99 @@ package org.apache.texera.amber.operator.filter +import org.apache.arrow.memory.RootAllocator +import org.apache.arrow.vector.{Float8Vector, IntVector, VectorSchemaRoot} +import org.apache.texera.amber.core.executor.{ColumnarOperatorExecutor, ColumnarResult} import org.apache.texera.amber.core.tuple.Tuple +import org.apache.texera.amber.util.ArrowUtils import org.apache.texera.amber.util.JSONUtils.objectMapper -class SpecializedFilterOpExec(descString: String) extends FilterOpExec { +class SpecializedFilterOpExec(descString: String) + extends FilterOpExec + with ColumnarOperatorExecutor { private val desc: SpecializedFilterOpDesc = objectMapper.readValue(descString, classOf[SpecializedFilterOpDesc]) + // Row path: OR over predicates, per tuple. setFilterFunc((tuple: Tuple) => desc.predicates.exists(_.evaluate(tuple))) + + private def cmpOf(c: ComparisonType): Int => Boolean = + c match { + case ComparisonType.GREATER_THAN => (r: Int) => r > 0 + case ComparisonType.GREATER_THAN_OR_EQUAL_TO => (r: Int) => r >= 0 + case ComparisonType.LESS_THAN => (r: Int) => r < 0 + case ComparisonType.LESS_THAN_OR_EQUAL_TO => (r: Int) => r <= 0 + case ComparisonType.EQUAL_TO => (r: Int) => r == 0 + case ComparisonType.NOT_EQUAL_TO => (r: Int) => r != 0 + case _ => null + } + + // Native-Arrow path: consume the Arrow batch directly, no per-tuple decode. + @transient private var columnarAllocator: RootAllocator = _ + + // Keep mask for a single supported numeric predicate over the batch, or None if + // the predicate/column shape is not vectorizable (caller falls back to the row + // path). Shared by the emit path and the selection-vector path. + private def columnarMask(root: VectorSchemaRoot): Option[Array[Boolean]] = { + if (desc.predicates.size != 1) return None + val p = desc.predicates.head + val cmp = cmpOf(p.condition) + if (cmp == null) return None + val c = + try p.value.toDouble + catch { case _: NumberFormatException => return None } + val fields = root.getSchema.getFields + var fieldIdx = -1 + var k = 0 + while (k < fields.size && fieldIdx < 0) { + if (fields.get(k).getName == p.attribute) fieldIdx = k + k += 1 + } + if (fieldIdx < 0) return None + val n = root.getRowCount + val mask = new Array[Boolean](n) + root.getVector(fieldIdx) match { + case v: Float8Vector => + var i = 0 + while (i < n) { + mask(i) = !v.isNull(i) && cmp(java.lang.Double.compare(v.get(i), c)); i += 1 + } + Some(mask) + case v: IntVector => + var i = 0 + while (i < n) { + mask(i) = !v.isNull(i) && cmp(java.lang.Double.compare(v.get(i).toDouble, c)); i += 1 + } + Some(mask) + case _ => None // non-numeric column: fall back to the row path + } + } + + override def processColumnarBatch(arrowIpcBytes: Array[Byte], port: Int): ColumnarResult = { + if (columnarAllocator == null) columnarAllocator = new RootAllocator() + ArrowUtils.deserializeRootFold(arrowIpcBytes, columnarAllocator) { root => + columnarMask(root) match { + case Some(mask) => ColumnarResult.Emit(ArrowUtils.selectRows(root, mask, columnarAllocator)) + case None => ColumnarResult.Unsupported + } + } + } + + // Selection-vector path: the indices of surviving rows, computed without + // compacting or copying the batch. None when the predicate is not vectorizable. + // For a fused consumer (count/aggregate) that reads the indices instead of a + // materialized batch. + def columnarSelection(arrowIpcBytes: Array[Byte], port: Int): Option[Array[Int]] = { + if (columnarAllocator == null) columnarAllocator = new RootAllocator() + ArrowUtils.deserializeRootFold(arrowIpcBytes, columnarAllocator) { root => + columnarMask(root).map(mask => ArrowUtils.selectionOf(mask, root.getRowCount)) + } + } + + // Fused filter -> count: number of surviving rows, no batch materialized. + def columnarMatchCount(arrowIpcBytes: Array[Byte], port: Int): Option[Long] = + columnarSelection(arrowIpcBytes, port).map(_.length.toLong) + + override def close(): Unit = { + if (columnarAllocator != null) columnarAllocator.close() + } } diff --git a/common/workflow-operator/src/main/scala/org/apache/texera/amber/operator/source/scan/arrow/ArrowSourceOpExec.scala b/common/workflow-operator/src/main/scala/org/apache/texera/amber/operator/source/scan/arrow/ArrowSourceOpExec.scala index 03e5a212385..a92e0b7d052 100644 --- a/common/workflow-operator/src/main/scala/org/apache/texera/amber/operator/source/scan/arrow/ArrowSourceOpExec.scala +++ b/common/workflow-operator/src/main/scala/org/apache/texera/amber/operator/source/scan/arrow/ArrowSourceOpExec.scala @@ -25,11 +25,12 @@ import org.apache.texera.amber.core.tuple.TupleLike import org.apache.texera.amber.util.ArrowUtils import org.apache.texera.amber.util.JSONUtils.objectMapper import org.apache.arrow.memory.RootAllocator -import org.apache.arrow.vector.VectorSchemaRoot +import org.apache.arrow.vector.{FieldVector, VectorSchemaRoot} import org.apache.arrow.vector.ipc.ArrowFileReader import java.net.URI import java.nio.file.{Files, StandardOpenOption} +import scala.jdk.CollectionConverters._ class ArrowSourceOpExec( descString: String @@ -57,6 +58,35 @@ class ArrowSourceOpExec( } } + // Columnar produce: the file is already Arrow batches, so hand each one out + // directly (no per-row Tuple decode, no text parse). Each loaded batch's vectors + // are moved into an independent root via zero-copy TransferPair so the caller can + // serialize and close it while the reader loads the next batch. Falls back to the + // row path (None) when offset/limit are set. + override def produceColumnarBatch(): Option[Iterator[VectorSchemaRoot]] = { + if (desc.offset.exists(_ > 0) || desc.limit.isDefined) return None + (reader, root, allocator) match { + case (Some(arrowReader), Some(srcRoot), Some(alloc)) => + Some(new Iterator[VectorSchemaRoot] { + private var loaded = arrowReader.loadNextBatch() + override def hasNext: Boolean = loaded + override def next(): VectorSchemaRoot = { + val rowCount = srcRoot.getRowCount + val moved = srcRoot.getFieldVectors.asScala.map { v => + val pair = v.getTransferPair(alloc) + pair.transfer() + pair.getTo.asInstanceOf[FieldVector] + }.toList + val out = new VectorSchemaRoot(moved.asJava) + out.setRowCount(rowCount) + loaded = arrowReader.loadNextBatch() + out + } + }) + case _ => None + } + } + override def produceTuple(): Iterator[TupleLike] = { val rowIterator = new Iterator[TupleLike] { private var currentIndex = 0 From 8c039faf4f2e5345a1f9cd282c901dceb01a478f Mon Sep 17 00:00:00 2001 From: Matthew Ball Date: Fri, 13 Nov 2026 15:37:08 -0800 Subject: [PATCH 02/16] feat(engine): opt-in columnar wire for data batches Adds the wire that carries a data batch between workers as Arrow IPC bytes (a ColumnarFrame) instead of decoded Tuples (a DataFrame), behind an off-by-default flag. When enabled, every operator's output goes out as Arrow and is decoded back at the receiver, so the format is transparent to the row path; the payoff is on cross-worker links, where one Arrow IPC block replaces per-tuple serialization. Consuming the Arrow batch without decoding (for a ColumnarOperatorExecutor) is a later optimization; this lands the transport and keeps results identical with the flag on or off. Flag: - ApplicationConfig.enableColumnarWire reads network-buffering.enable-columnar-wire, defaulting to false (override NETWORK_BUFFERING_ENABLE_COLUMNAR_WIRE). Off by default, so the default wire is DataFrame and unchanged. Payload: - ColumnarFrame(arrowIpcBytes, rowCount, schema) is a new DataPayload. It carries a batch as an Arrow IPC stream plus the row count and Texera schema that describe it without decoding. inMemSize is the byte length. Send side (NetworkOutputBuffer): - The buffer takes a `columnar` flag (defaulting to ApplicationConfig.enableColumnarWire). On flush, when columnar is on it serializes the buffered tuples to Arrow once (all tuples on a link share the schema) and sends a ColumnarFrame; otherwise it sends a DataFrame as before. An empty flush still sends nothing. Receive side: - DataProcessor.processDataPayload handles ColumnarFrame by decoding the Arrow bytes back to tuples and running the identical batch path as DataFrame; the shared startInputBatch helper carries the common state-transition, initBatch, and first-tuple step for both. A columnar batch bound for a Python worker is decoded back to tuples in PythonProxyClient.sendData and handed over as a Data batch, so the Python path is unaffected. ArrowUtils: - serializeTuples(schema, tuples) writes a tuple batch to Arrow IPC stream bytes; deserializeTuples(bytes) reads them back to tuples. These are the ColumnarFrame encode/decode endpoints. Tests: - ArrowUtilsSpec covers the serializeTuples/deserializeTuples round-trip over a multi-row batch of every field type (including a null row and an empty batch), the payload contract the wire depends on. - NetworkOutputBufferColumnarSeamSpec checks the buffer emits a ColumnarFrame (carrying the same rows, row count, and schema) when the flag is on and a DataFrame when off, on both the manual and the size-triggered flush, and nothing on an empty flush. - SelectionVectorFilterSpec checks the specialized filter's native-Arrow path (selection vector, fused filter-count, and the compacting Emit path) against the row path as the source of truth. --- .../pythonworker/PythonProxyClient.scala | 8 ++ .../partitioners/Partitioner.scala | 20 ++- .../architecture/worker/DataProcessor.scala | 43 +++++-- .../common/ambermessage/DataPayload.scala | 15 ++- .../NetworkOutputBufferColumnarSeamSpec.scala | 119 ++++++++++++++++++ .../src/main/resources/application.conf | 8 ++ .../common/config/ApplicationConfig.scala | 4 + .../apache/texera/amber/util/ArrowUtils.scala | 26 ++++ .../texera/amber/util/ArrowUtilsSpec.scala | 61 +++++++++ .../filter/SelectionVectorFilterSpec.scala | 111 ++++++++++++++++ 10 files changed, 398 insertions(+), 17 deletions(-) create mode 100644 amber/src/test/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/NetworkOutputBufferColumnarSeamSpec.scala create mode 100644 common/workflow-operator/src/test/scala/org/apache/texera/amber/operator/filter/SelectionVectorFilterSpec.scala diff --git a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/pythonworker/PythonProxyClient.scala b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/pythonworker/PythonProxyClient.scala index d3ea86cdd4a..ddd8927c4f1 100644 --- a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/pythonworker/PythonProxyClient.scala +++ b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/pythonworker/PythonProxyClient.scala @@ -124,6 +124,14 @@ class PythonProxyClient(portNumberPromise: Promise[Int], val actorId: ActorVirtu dataPayload match { case DataFrame(frame) => writeArrowStream(mutable.Queue(ArraySeq.unsafeWrapArray(frame): _*), from, "Data") + case ColumnarFrame(arrowIpcBytes, _, _) => + // A columnar-wire batch headed to a Python worker: decode it back to tuples + // and hand it over as a Data batch, same as a DataFrame. + writeArrowStream( + mutable.Queue(ArraySeq.unsafeWrapArray(ArrowUtils.deserializeTuples(arrowIpcBytes)): _*), + from, + "Data" + ) case StateFrame(state, loopCounter, loopStartId) => // The Arrow wire format for states IS the State row (content + // loop_counter + loop_start_id), so the envelope rides its own diff --git a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/Partitioner.scala b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/Partitioner.scala index 620eb936512..6f129ced8a1 100644 --- a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/Partitioner.scala +++ b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/Partitioner.scala @@ -24,7 +24,8 @@ import org.apache.texera.amber.core.state.State import org.apache.texera.amber.core.tuple.Tuple import org.apache.texera.amber.core.virtualidentity.ActorVirtualIdentity import org.apache.texera.amber.engine.architecture.messaginglayer.NetworkOutputGateway -import org.apache.texera.amber.engine.common.ambermessage.{DataFrame, StateFrame} +import org.apache.texera.amber.engine.common.ambermessage.{ColumnarFrame, DataFrame, StateFrame} +import org.apache.texera.amber.util.ArrowUtils import scala.collection.mutable.ArrayBuffer @@ -37,7 +38,10 @@ trait Partitioner extends Serializable { class NetworkOutputBuffer( val to: ActorVirtualIdentity, val dataOutputPort: NetworkOutputGateway, - val batchSize: Int = ApplicationConfig.defaultDataTransferBatchSize + val batchSize: Int = ApplicationConfig.defaultDataTransferBatchSize, + // Columnar wire (opt-in): flush as ColumnarFrame (Arrow IPC) instead of + // DataFrame. Off by default, so the default wire is unchanged. + val columnar: Boolean = ApplicationConfig.enableColumnarWire ) { var buffer = new ArrayBuffer[Tuple]() @@ -57,7 +61,17 @@ class NetworkOutputBuffer( def flush(): Unit = { if (buffer.nonEmpty) { - dataOutputPort.sendTo(to, DataFrame(buffer.toArray)) + val batch = buffer.toArray + if (columnar) { + // Serialize the batch to Arrow once; all tuples on a link share the schema. + val schema = batch(0).getSchema + dataOutputPort.sendTo( + to, + ColumnarFrame(ArrowUtils.serializeTuples(schema, batch), batch.length, schema) + ) + } else { + dataOutputPort.sendTo(to, DataFrame(batch)) + } buffer = new ArrayBuffer[Tuple]() } } diff --git a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/worker/DataProcessor.scala b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/worker/DataProcessor.scala index 0bfce2d04b9..1c1f1122009 100644 --- a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/worker/DataProcessor.scala +++ b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/worker/DataProcessor.scala @@ -59,6 +59,7 @@ import org.apache.texera.amber.engine.common.ambermessage._ import org.apache.texera.amber.engine.common.statetransition.WorkerStateManager import org.apache.texera.amber.engine.common.virtualidentity.util.COORDINATOR import org.apache.texera.amber.error.ErrorUtils.{mkConsoleMessage, mkPrintConsoleMessage, safely} +import org.apache.texera.amber.util.ArrowUtils import java.util.concurrent.LinkedBlockingQueue @@ -114,6 +115,28 @@ class DataProcessor( * process currentInputTuple through executor logic. * this function is only called by the DP thread. */ + // Start processing one data batch: announce the worker is running, load the + // batch, and process its first tuple (the DP loop drains the rest). Shared by the + // DataFrame and ColumnarFrame input paths. + private[this] def startInputBatch( + channelId: ChannelIdentity, + tuples: Array[Tuple] + ): Unit = { + stateManager.conditionalTransitTo( + READY, + RUNNING, + () => { + val (state, stateVersion) = stateManager.getStateWithVersion + asyncRPCClient.coordinatorInterface.workerStateUpdated( + WorkerStateUpdatedRequest(state, stateVersion), + asyncRPCClient.mkContext(COORDINATOR) + ) + } + ) + inputManager.initBatch(channelId, tuples) + processInputTuple(inputManager.getNextTuple) + } + private[this] def processInputTuple(tuple: Tuple): Unit = { try { val portIdentity: PortIdentity = @@ -243,19 +266,13 @@ class DataProcessor( val portId = this.inputGateway.getChannel(channelId).getPortId dataPayload match { case DataFrame(tuples) => - stateManager.conditionalTransitTo( - READY, - RUNNING, - () => { - val (state, stateVersion) = stateManager.getStateWithVersion - asyncRPCClient.coordinatorInterface.workerStateUpdated( - WorkerStateUpdatedRequest(state, stateVersion), - asyncRPCClient.mkContext(COORDINATOR) - ) - } - ) - inputManager.initBatch(channelId, tuples) - processInputTuple(inputManager.getNextTuple) + startInputBatch(channelId, tuples) + case ColumnarFrame(arrowIpcBytes, _, _) => + // Columnar wire: the batch arrived as Arrow IPC bytes. Decode it back to + // tuples and process it exactly as a DataFrame, so every operator handles + // it transparently. (Consuming the Arrow batch directly for a + // ColumnarOperatorExecutor is a follow-up optimization.) + startInputBatch(channelId, ArrowUtils.deserializeTuples(arrowIpcBytes)) case StateFrame(state, loopCounter, loopStartId) => processInputState(state, portId.id, loopCounter, loopStartId) } diff --git a/amber/src/main/scala/org/apache/texera/amber/engine/common/ambermessage/DataPayload.scala b/amber/src/main/scala/org/apache/texera/amber/engine/common/ambermessage/DataPayload.scala index b8ac640ad53..bc767c38b1a 100644 --- a/amber/src/main/scala/org/apache/texera/amber/engine/common/ambermessage/DataPayload.scala +++ b/amber/src/main/scala/org/apache/texera/amber/engine/common/ambermessage/DataPayload.scala @@ -20,7 +20,7 @@ package org.apache.texera.amber.engine.common.ambermessage import org.apache.texera.amber.core.state.State -import org.apache.texera.amber.core.tuple.Tuple +import org.apache.texera.amber.core.tuple.{Schema, Tuple} sealed trait DataPayload extends WorkflowFIFOMessagePayload {} @@ -37,6 +37,19 @@ sealed trait DataPayload extends WorkflowFIFOMessagePayload {} final case class StateFrame(frame: State, loopCounter: Long = 0L, loopStartId: String = "") extends DataPayload +/** + * A batch of rows carried over the wire as Arrow IPC stream bytes (the columnar + * wire format), instead of as decoded `Tuple`s in a `DataFrame`. `rowCount` and + * the Texera `schema` describe the batch without decoding it. The receiver either + * consumes the bytes directly (a `ColumnarOperatorExecutor`) or decodes them back + * to tuples (`ArrowUtils.deserializeTuples`). Produced only when the columnar wire + * is enabled; off by default, so the default wire stays `DataFrame`. + */ +final case class ColumnarFrame(arrowIpcBytes: Array[Byte], rowCount: Int, schema: Schema) + extends DataPayload { + val inMemSize: Long = arrowIpcBytes.length.toLong +} + final case class DataFrame(frame: Array[Tuple]) extends DataPayload { val inMemSize: Long = { frame.map(_.inMemSize).sum diff --git a/amber/src/test/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/NetworkOutputBufferColumnarSeamSpec.scala b/amber/src/test/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/NetworkOutputBufferColumnarSeamSpec.scala new file mode 100644 index 00000000000..4dbe15d7de1 --- /dev/null +++ b/amber/src/test/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/NetworkOutputBufferColumnarSeamSpec.scala @@ -0,0 +1,119 @@ +/* + * 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. + */ + +package org.apache.texera.amber.engine.architecture.sendsemantics.partitioners + +import org.apache.texera.amber.core.tuple.{Attribute, AttributeType, Schema, Tuple} +import org.apache.texera.amber.core.virtualidentity.ActorVirtualIdentity +import org.apache.texera.amber.engine.architecture.messaginglayer.NetworkOutputGateway +import org.apache.texera.amber.engine.common.ambermessage.{ + ColumnarFrame, + DataFrame, + WorkflowFIFOMessage +} +import org.apache.texera.amber.util.ArrowUtils +import org.scalatest.flatspec.AnyFlatSpec + +import scala.collection.mutable.ArrayBuffer + +/** + * The columnar-wire switch on NetworkOutputBuffer. + * + * A NetworkOutputBuffer chooses, on flush, how to put a batch on the wire: as row + * objects (DataFrame) or as an Arrow columnar block (ColumnarFrame). The choice is + * the constructor flag `columnar`; flush() reads exactly that flag. These tests + * verify the buffer honors the flag on both the manual and the size-triggered + * flush, carries the row count and schema on the columnar frame, and that a + * columnar frame's bytes decode back to the very rows that were buffered. + */ +class NetworkOutputBufferColumnarSeamSpec extends AnyFlatSpec { + + private val sender: ActorVirtualIdentity = ActorVirtualIdentity("sender") + private val receiver: ActorVirtualIdentity = ActorVirtualIdentity("receiver") + private val vAttr: Attribute = new Attribute("v", AttributeType.INTEGER) + private val schema: Schema = Schema().add(vAttr) + private def tuple(v: Int): Tuple = Tuple.builder(schema).add(vAttr, v).build() + + private def fixture( + columnar: Boolean, + batchSize: Int = 1000 + ): (NetworkOutputBuffer, ArrayBuffer[WorkflowFIFOMessage]) = { + val sent = ArrayBuffer[WorkflowFIFOMessage]() + val gateway = new NetworkOutputGateway(sender, m => { sent += m; () }) + val buffer = new NetworkOutputBuffer(receiver, gateway, batchSize, columnar) + (buffer, sent) + } + + it should "emit a ColumnarFrame carrying the same rows when columnar is on" in { + val (buffer, sent) = fixture(columnar = true) + buffer.addTuple(tuple(1)) + buffer.addTuple(tuple(2)) + buffer.addTuple(tuple(3)) + buffer.flush() + + assert(sent.size == 1) + sent.head.payload match { + case cf: ColumnarFrame => + assert(cf.rowCount == 3) + assert(cf.schema == schema) + // The Arrow bytes decode back to exactly the buffered rows, in order. + val back = ArrowUtils.deserializeTuples(cf.arrowIpcBytes) + assert(back.map(_.getField[Any]("v")).toList == List(1, 2, 3)) + case other => fail(s"expected a ColumnarFrame, got: $other") + } + } + + it should "emit a DataFrame (rows) when columnar is off" in { + val (buffer, sent) = fixture(columnar = false) + buffer.addTuple(tuple(10)) + buffer.addTuple(tuple(20)) + buffer.flush() + + assert(sent.size == 1) + sent.head.payload match { + case df: DataFrame => + assert(df.frame.map(_.getField[Any]("v")).toList == List(10, 20)) + case other => fail(s"expected a DataFrame, got: $other") + } + } + + it should "send nothing when flushed empty, either way" in { + val (on, onSent) = fixture(columnar = true) + on.flush() + assert(onSent.isEmpty) + val (off, offSent) = fixture(columnar = false) + off.flush() + assert(offSent.isEmpty) + } + + it should "honor the flag on the size-triggered auto-flush" in { + val (on, onSent) = fixture(columnar = true, batchSize = 2) + on.addTuple(tuple(1)) + assert(onSent.isEmpty) + on.addTuple(tuple(2)) + assert(onSent.size == 1) + assert(onSent.head.payload.isInstanceOf[ColumnarFrame]) + + val (off, offSent) = fixture(columnar = false, batchSize = 2) + off.addTuple(tuple(1)) + off.addTuple(tuple(2)) + assert(offSent.size == 1) + assert(offSent.head.payload.isInstanceOf[DataFrame]) + } +} diff --git a/common/config/src/main/resources/application.conf b/common/config/src/main/resources/application.conf index d5f7ffed2e7..03993092b26 100644 --- a/common/config/src/main/resources/application.conf +++ b/common/config/src/main/resources/application.conf @@ -53,6 +53,14 @@ network-buffering { adaptive-buffering-timeout-ms = 500 adaptive-buffering-timeout-ms = ${?NETWORK_BUFFERING_ADAPTIVE_BUFFERING_TIMEOUT_MS} + + # Columnar wire (MVP, opt-in): when true, a worker flushes each data batch to + # downstream as Arrow IPC bytes (ColumnarFrame) instead of decoded tuples + # (DataFrame). The receiver consumes the Arrow batch directly if its operator + # implements ColumnarOperatorExecutor, else decodes it back to tuples. Off by + # default; the default wire stays DataFrame. + enable-columnar-wire = false + enable-columnar-wire = ${?NETWORK_BUFFERING_ENABLE_COLUMNAR_WIRE} } reconfiguration { diff --git a/common/config/src/main/scala/org/apache/texera/common/config/ApplicationConfig.scala b/common/config/src/main/scala/org/apache/texera/common/config/ApplicationConfig.scala index dea1e169d6a..47ff363ad99 100644 --- a/common/config/src/main/scala/org/apache/texera/common/config/ApplicationConfig.scala +++ b/common/config/src/main/scala/org/apache/texera/common/config/ApplicationConfig.scala @@ -66,6 +66,10 @@ object ApplicationConfig { getConfSource.getBoolean("network-buffering.enable-adaptive-buffering") val adaptiveBufferingTimeoutMs: Int = getConfSource.getInt("network-buffering.adaptive-buffering-timeout-ms") + // Columnar wire (opt-in): flush data batches as Arrow IPC (ColumnarFrame) rather + // than decoded tuples (DataFrame). Off by default. + val enableColumnarWire: Boolean = + getConfSource.getBoolean("network-buffering.enable-columnar-wire") // Reconfiguration val enableTransactionalReconfiguration: Boolean = diff --git a/common/workflow-core/src/main/scala/org/apache/texera/amber/util/ArrowUtils.scala b/common/workflow-core/src/main/scala/org/apache/texera/amber/util/ArrowUtils.scala index 24a55a23d08..6902c21f848 100644 --- a/common/workflow-core/src/main/scala/org/apache/texera/amber/util/ArrowUtils.scala +++ b/common/workflow-core/src/main/scala/org/apache/texera/amber/util/ArrowUtils.scala @@ -79,6 +79,32 @@ object ArrowUtils extends LazyLogging { } finally reader.close() } + // Serialize a batch of tuples to Arrow IPC stream bytes (columnar wire format). + def serializeTuples(schema: Schema, tuples: Array[Tuple]): Array[Byte] = { + val root = VectorSchemaRoot.create(fromTexeraSchema(schema), allocator) + try { + var i = 0 + while (i < tuples.length) { setTexeraTuple(tuples(i), i, root); i += 1 } + root.setRowCount(tuples.length) + serializeRoot(root) + } finally root.close() + } + + // Inverse of serializeTuples: decode Arrow IPC stream bytes back to tuples. + def deserializeTuples(bytes: Array[Byte]): Array[Tuple] = { + val reader = new ArrowStreamReader(new ByteArrayInputStream(bytes), allocator) + try { + val out = scala.collection.mutable.ArrayBuffer[Tuple]() + val root = reader.getVectorSchemaRoot + while (reader.loadNextBatch()) { + val n = root.getRowCount + var i = 0 + while (i < n) { out += getTexeraTuple(i, root); i += 1 } + } + out.toArray + } finally reader.close() + } + // Copy the rows of `src` where keep(i) is true into a new independent root. def selectRows( src: VectorSchemaRoot, diff --git a/common/workflow-core/src/test/scala/org/apache/texera/amber/util/ArrowUtilsSpec.scala b/common/workflow-core/src/test/scala/org/apache/texera/amber/util/ArrowUtilsSpec.scala index 6ce294e2a0b..7bd5c631f76 100644 --- a/common/workflow-core/src/test/scala/org/apache/texera/amber/util/ArrowUtilsSpec.scala +++ b/common/workflow-core/src/test/scala/org/apache/texera/amber/util/ArrowUtilsSpec.scala @@ -369,6 +369,67 @@ class ArrowUtilsSpec extends AnyFlatSpec with Matchers { } } + // ----- serializeTuples / deserializeTuples (the columnar wire round-trip) ----- + + "serializeTuples and deserializeTuples" should "round-trip a multi-row batch of every type" in { + // This is the columnar-wire payload contract: a NetworkOutputBuffer serializes a + // batch of tuples to Arrow IPC bytes, and the receiver decodes them back to the + // identical tuples, so the wire is transparent to the row path. + val rows = Array( + Tuple + .builder(tupleSchema) + .addSequentially( + Array[Any]( + Int.box(42), + Long.box(7L), + Double.box(3.14), + Boolean.box(true), + new Timestamp(10000L), + "hello", + Array[Byte](1, 2, 3) + ) + ) + .build(), + Tuple + .builder(tupleSchema) + .addSequentially(Array[Any](null, null, null, null, null, null, null)) + .build(), + Tuple + .builder(tupleSchema) + .addSequentially( + Array[Any]( + Int.box(-1), + Long.box(0L), + Double.box(-2.5), + Boolean.box(false), + new Timestamp(0L), + "", + Array[Byte]() + ) + ) + .build() + ) + + val back = ArrowUtils.deserializeTuples(ArrowUtils.serializeTuples(tupleSchema, rows)) + back.length shouldBe rows.length + back.zip(rows).foreach { + case (got, expected) => + tupleSchema.getAttributes.foreach { attribute => + val name = attribute.getName + (got.getField[AnyRef](name), expected.getField[AnyRef](name)) match { + case (g: Array[Byte], e: Array[Byte]) => g shouldBe e + case (g, e) => g shouldBe e + } + } + } + } + + it should "round-trip an empty batch" in { + ArrowUtils.deserializeTuples( + ArrowUtils.serializeTuples(tupleSchema, Array.empty[Tuple]) + ) shouldBe empty + } + // A Timestamp reaches past 2262, where counting microseconds through // nanoseconds overflowed, and before 1970. Both come back to the microsecond. it should "round-trip a timestamp either side of the nanosecond range" in { diff --git a/common/workflow-operator/src/test/scala/org/apache/texera/amber/operator/filter/SelectionVectorFilterSpec.scala b/common/workflow-operator/src/test/scala/org/apache/texera/amber/operator/filter/SelectionVectorFilterSpec.scala new file mode 100644 index 00000000000..516df12879c --- /dev/null +++ b/common/workflow-operator/src/test/scala/org/apache/texera/amber/operator/filter/SelectionVectorFilterSpec.scala @@ -0,0 +1,111 @@ +/* + * 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. + */ + +package org.apache.texera.amber.operator.filter + +import org.apache.texera.amber.core.executor.ColumnarResult +import org.apache.texera.amber.core.tuple.{Attribute, AttributeType, Schema, Tuple} +import org.apache.texera.amber.util.ArrowUtils +import org.apache.texera.amber.util.JSONUtils.objectMapper +import org.scalatest.flatspec.AnyFlatSpec + +import scala.util.Random + +/** + * The specialized filter's native-Arrow path. + * + * The selection vector (surviving row indices, no compaction) must name exactly + * the rows the row path keeps, the fused filter->count must equal the row path's + * survivor count without materializing a batch, and the compacting Emit path must + * return the same rows. All three are checked against the row path (filterFunc) as + * the source of truth. + */ +class SelectionVectorFilterSpec extends AnyFlatSpec { + + private def execFor(preds: (String, ComparisonType, String)*): SpecializedFilterOpExec = { + val desc = new SpecializedFilterOpDesc() + desc.predicates = preds.map { case (a, c, v) => new FilterPredicate(a, c, v) }.toList + new SpecializedFilterOpExec(objectMapper.writeValueAsString(desc)) + } + + private val schema: Schema = Schema().add(new Attribute("v", AttributeType.INTEGER)) + + private def batch(seed: Int, n: Int): Array[Tuple] = { + val rng = new Random(seed) + (0 until n).map { i => + val v: Any = if (i % 11 == 0) null else Int.box(rng.nextInt(100)) + Tuple.builder(schema).add(schema.getAttribute("v"), v).build() + }.toArray + } + + "selection vector" should "name exactly the rows the row path keeps" in { + val rows = batch(1, 2000) + val bytes = ArrowUtils.serializeTuples(schema, rows) + val exec = execFor(("v", ComparisonType.GREATER_THAN, "50")) + exec.open() + + val expectedIdx = rows.indices.filter(i => exec.filterFunc(rows(i))).toArray + + val sel = exec.columnarSelection(bytes, 0) + assert(sel.isDefined, "expected a vectorized selection") + assert(sel.get.toSeq == expectedIdx.toSeq, "selection indices must match row-path survivors") + exec.close() + } + + "fused filter -> count" should "equal the row-path count without materializing" in { + val rows = batch(2, 3000) + val bytes = ArrowUtils.serializeTuples(schema, rows) + val exec = execFor(("v", ComparisonType.LESS_THAN_OR_EQUAL_TO, "40")) + exec.open() + + val expected = rows.count(exec.filterFunc).toLong + assert(exec.columnarMatchCount(bytes, 0).contains(expected)) + exec.close() + } + + "the compact Emit path" should "still return the same surviving rows" in { + val rows = batch(3, 2500) + val bytes = ArrowUtils.serializeTuples(schema, rows) + val exec = execFor(("v", ComparisonType.GREATER_THAN, "10")) + exec.open() + + val expected = rows.count(exec.filterFunc) + exec.processColumnarBatch(bytes, 0) match { + case ColumnarResult.Emit(root) => + assert(root.getRowCount == expected) + root.close() + case other => fail(s"expected Emit, got $other") + } + exec.close() + } + + "gather from a selection" should "yield the same rows as the row path" in { + val rows = batch(4, 1500) + val bytes = ArrowUtils.serializeTuples(schema, rows) + val exec = execFor(("v", ComparisonType.GREATER_THAN, "70")) + exec.open() + + val sel = exec.columnarSelection(bytes, 0).get + val decoded = ArrowUtils.deserializeTuples(bytes) + val gathered = sel.map(i => decoded(i).getField[Any]("v")).toSeq + val expected = rows.filter(exec.filterFunc).map(_.getField[Any]("v")).toSeq + assert(gathered == expected) + exec.close() + } +} From 73a94505246f5debcd4317b9c231031e26dd3874 Mon Sep 17 00:00:00 2001 From: Matthew Ball Date: Fri, 13 Nov 2026 15:56:35 -0800 Subject: [PATCH 03/16] feat(aggregate): native-Arrow accumulate for the aggregate operator AggregateOpExec can now consume an Arrow columnar batch directly, accumulating each group's partial result by reading the group-key and aggregated cells straight from their Arrow vectors instead of decoding a Tuple per row. The accumulation itself is shared with the row path, so a grouped aggregate produces the identical result whether its input arrives as rows or as a columnar batch. Value-based accumulation (DistributedAggregation): - DistributedAggregation now accumulates one already-extracted value via iterateValue(partial, value), and carries an extract(tuple) that pulls the single cell an aggregation reads from a tuple (null for COUNT(*)). The row path's iterate(partial, tuple) is derived as iterateValue(partial, extract(tuple)), so accumulation is defined once and both paths use it. init, merge, and finalAgg are unchanged. - AggregationOperation's six functions (sum, count, average, min, max, concat) are rewritten to this shape: each supplies iterateValue (the per-value logic) and extract (tuple.getField of its attribute, or null for COUNT(*)). count keeps its captured countAllRows flag, so COUNT(*) counts every row and COUNT(column) counts non-null values. average reads a value numerically via a value-based helper (a timestamp counts as its epoch milliseconds, any other value through its string form, null skipped), matching the previous tuple-based reading. Columnar accumulate (AggregateOpExec): - The operator mixes in ColumnarOperatorExecutor. processColumnarBatch deserializes the batch and runs accumulateRoot, which resolves once per batch the source-column index and Texera type of each group-by key and each aggregation's input column (index -1 for COUNT(*)), then for each row builds the group key and feeds each aggregation its cell value through iterateValue. It is a blocking operator, so it emits nothing per batch (ColumnarResult.Consumed); results are produced at onFinish via the existing path. A per-operator RootAllocator backs the decode and is freed in close(). Tests: - AggregateOpSpec adds a columnar-vs-row check: a grouped SUM/COUNT/AVERAGE/MIN/MAX over rows including a null value gives the same per-group result through processColumnarBatch as through processTuple. - DistributedAggregationSpec is updated to the new constructor (iterateValue + extract) and asserts iterate is derived from them (the row path equals the value path). --- .../operator/aggregate/AggregateOpExec.scala | 83 ++++++++++++++++++- .../aggregate/AggregationOperation.scala | 71 ++++++++-------- .../aggregate/DistributedAggregation.scala | 15 +++- .../operator/aggregate/AggregateOpSpec.scala | 56 +++++++++++++ .../DistributedAggregationSpec.scala | 29 +++++-- 5 files changed, 203 insertions(+), 51 deletions(-) diff --git a/common/workflow-operator/src/main/scala/org/apache/texera/amber/operator/aggregate/AggregateOpExec.scala b/common/workflow-operator/src/main/scala/org/apache/texera/amber/operator/aggregate/AggregateOpExec.scala index 3c26709116f..16871ff8870 100644 --- a/common/workflow-operator/src/main/scala/org/apache/texera/amber/operator/aggregate/AggregateOpExec.scala +++ b/common/workflow-operator/src/main/scala/org/apache/texera/amber/operator/aggregate/AggregateOpExec.scala @@ -19,8 +19,15 @@ package org.apache.texera.amber.operator.aggregate -import org.apache.texera.amber.core.executor.OperatorExecutor -import org.apache.texera.amber.core.tuple.{Tuple, TupleLike} +import org.apache.arrow.memory.RootAllocator +import org.apache.arrow.vector.VectorSchemaRoot +import org.apache.texera.amber.core.executor.{ + ColumnarOperatorExecutor, + ColumnarResult, + OperatorExecutor +} +import org.apache.texera.amber.core.tuple.{AttributeType, Schema, Tuple, TupleLike} +import org.apache.texera.amber.util.ArrowUtils import org.apache.texera.amber.util.JSONUtils.objectMapper import scala.collection.mutable @@ -28,7 +35,7 @@ import scala.collection.mutable /** * AggregateOpExec performs aggregation operations on input tuples, optionally grouping them by specified keys. */ -class AggregateOpExec(descString: String) extends OperatorExecutor { +class AggregateOpExec(descString: String) extends OperatorExecutor with ColumnarOperatorExecutor { private val desc: AggregateOpDesc = objectMapper.readValue(descString, classOf[AggregateOpDesc]) private var keyedPartialAggregates: mutable.HashMap[List[Object], List[Object]] = _ private var distributedAggregations: List[DistributedAggregation[Object]] = _ @@ -41,6 +48,7 @@ class AggregateOpExec(descString: String) extends OperatorExecutor { override def close(): Unit = { keyedPartialAggregates.clear() distributedAggregations = null + if (columnarAllocator != null) { columnarAllocator.close(); columnarAllocator = null } } override def processTuple(tuple: Tuple, port: Int): Iterator[TupleLike] = { @@ -78,6 +86,75 @@ class AggregateOpExec(descString: String) extends OperatorExecutor { } + // ---- Native-Arrow path: accumulate an Arrow batch by reading only the group + // keys and aggregated cells per row (no projected Tuple), feeding the same + // per-value accumulation (iterateValue) the row path uses. Blocking operator, so + // it emits nothing per batch (Consumed); results are produced at onFinish. + @transient private var columnarAllocator: RootAllocator = _ + // Per-batch resolution: the source-column index and Texera type of each group-by + // key, and of each aggregation's input column (index -1 for COUNT(*), which reads + // no column). + @transient private var colGroupIndices: Array[Int] = _ + @transient private var colGroupTypes: Array[AttributeType] = _ + @transient private var colAggIndices: Array[Int] = _ + @transient private var colAggTypes: Array[AttributeType] = _ + + private def aggInputType(agg: AggregationOperation, full: Schema): AttributeType = + if ( + agg.aggFunction == AggregationFunction.COUNT && + (agg.attribute == null || agg.attribute.trim.isEmpty) + ) null + else full.getAttribute(agg.attribute).getType + + // Accumulate one Arrow batch into the group state, reading each group key and + // aggregated value straight from its Arrow vector. Mirrors processTuple's + // accumulation exactly, feeding each aggregation the already-extracted value via + // iterateValue. Blocking operator, so it emits nothing now (Consumed). Does not + // close `root`. + private def accumulateRoot(root: VectorSchemaRoot): ColumnarResult = { + if (distributedAggregations == null || colGroupIndices == null) { + val full = ArrowUtils.toTexeraSchema(root.getSchema) + if (distributedAggregations == null) { + distributedAggregations = + desc.aggregations.map(agg => agg.getAggFunc(aggInputType(agg, full))) + } + colGroupIndices = ArrowUtils.projectionIndices(root, desc.groupByKeys) + colGroupTypes = desc.groupByKeys.map(full.getAttribute(_).getType).toArray + colAggIndices = desc.aggregations.map { agg => + if (agg.attribute == null || agg.attribute.trim.isEmpty) -1 + else ArrowUtils.projectionIndices(root, Seq(agg.attribute))(0) + }.toArray + colAggTypes = desc.aggregations.map(agg => aggInputType(agg, full)).toArray + } + val vectors = root.getFieldVectors + val n = root.getRowCount + val numGroups = colGroupIndices.length + var i = 0 + while (i < n) { + val key = + (0 until numGroups) + .map(g => ArrowUtils.getCell(vectors.get(colGroupIndices(g)), i, colGroupTypes(g))) + .toList + val partials = + keyedPartialAggregates.getOrElseUpdate(key, distributedAggregations.map(_.init())) + val updated = distributedAggregations.zip(partials).zipWithIndex.map { + case ((aggregation, partial), j) => + val idx = colAggIndices(j) + val value: Object = + if (idx < 0) null else ArrowUtils.getCell(vectors.get(idx), i, colAggTypes(j)) + aggregation.iterateValue(partial, value) + } + keyedPartialAggregates(key) = updated + i += 1 + } + ColumnarResult.Consumed + } + + override def processColumnarBatch(arrowIpcBytes: Array[Byte], port: Int): ColumnarResult = { + if (columnarAllocator == null) columnarAllocator = new RootAllocator() + ArrowUtils.deserializeRootFold(arrowIpcBytes, columnarAllocator)(accumulateRoot) + } + override def onFinish(port: Int): Iterator[TupleLike] = { // Finalize aggregation for all keys and produce the result keyedPartialAggregates.iterator.map { diff --git a/common/workflow-operator/src/main/scala/org/apache/texera/amber/operator/aggregate/AggregationOperation.scala b/common/workflow-operator/src/main/scala/org/apache/texera/amber/operator/aggregate/AggregationOperation.scala index 67146e81af2..e4899345ea3 100644 --- a/common/workflow-operator/src/main/scala/org/apache/texera/amber/operator/aggregate/AggregationOperation.scala +++ b/common/workflow-operator/src/main/scala/org/apache/texera/amber/operator/aggregate/AggregationOperation.scala @@ -21,7 +21,7 @@ package org.apache.texera.amber.operator.aggregate import com.fasterxml.jackson.annotation.{JsonIgnore, JsonProperty, JsonPropertyDescription} import com.kjetland.jackson.jsonSchema.annotations.{JsonSchemaInject, JsonSchemaTitle} -import org.apache.texera.amber.core.tuple.{Attribute, AttributeType, AttributeTypeUtils, Tuple} +import org.apache.texera.amber.core.tuple.{Attribute, AttributeType, AttributeTypeUtils} import org.apache.texera.amber.operator.metadata.annotations.AutofillAttributeName import javax.validation.constraints.NotNull @@ -146,12 +146,10 @@ class AggregationOperation { } new DistributedAggregation[Object]( () => AttributeTypeUtils.zeroValue(attributeType), - (partial, tuple) => { - val value = tuple.getField[Object](attribute) - AttributeTypeUtils.add(partial, value, attributeType) - }, + (partial, value) => AttributeTypeUtils.add(partial, value, attributeType), (partial1, partial2) => AttributeTypeUtils.add(partial1, partial2, attributeType), - partial => partial + partial => partial, + tuple => tuple.getField[Object](attribute) ) } @@ -161,24 +159,19 @@ class AggregationOperation { val countAllRows = attribute == null || attribute.trim.isEmpty new DistributedAggregation[Integer]( () => 0, - (partial, tuple) => - partial + (if (countAllRows || tuple.getField(attribute) != null) 1 else 0), + (partial, value) => partial + (if (countAllRows || value != null) 1 else 0), (partial1, partial2) => partial1 + partial2, - partial => partial + partial => partial, + tuple => if (countAllRows) null else tuple.getField(attribute) ) } private def concatAgg(): DistributedAggregation[String] = { new DistributedAggregation[String]( () => "", - (partial, tuple) => { - if (partial == "") { - if (tuple.getField(attribute) != null) tuple.getField(attribute).toString else "" - } else { - partial + "," + (if (tuple.getField(attribute) != null) - tuple.getField(attribute).toString - else "") - } + (partial, value) => { + val s = if (value != null) value.toString else "" + if (partial == "") s else partial + "," + s }, (partial1, partial2) => { if (partial1 != "" && partial2 != "") { @@ -187,7 +180,8 @@ class AggregationOperation { partial1 + partial2 } }, - partial => partial + partial => partial, + tuple => tuple.getField[Object](attribute) ) } @@ -204,15 +198,15 @@ class AggregationOperation { } new DistributedAggregation[Object]( () => AttributeTypeUtils.maxValue(attributeType), - (partial, tuple) => { - val value = tuple.getField[Object](attribute) + (partial, value) => { val comp = AttributeTypeUtils.compare(value, partial, attributeType) if (value != null && comp < 0) value else partial }, (partial1, partial2) => if (AttributeTypeUtils.compare(partial1, partial2, attributeType) < 0) partial1 else partial2, - partial => if (partial == AttributeTypeUtils.maxValue(attributeType)) null else partial + partial => if (partial == AttributeTypeUtils.maxValue(attributeType)) null else partial, + tuple => tuple.getField[Object](attribute) ) } @@ -229,36 +223,36 @@ class AggregationOperation { } new DistributedAggregation[Object]( () => AttributeTypeUtils.minValue(attributeType), - (partial, tuple) => { - val value = tuple.getField[Object](attribute) + (partial, value) => { val comp = AttributeTypeUtils.compare(value, partial, attributeType) if (value != null && comp > 0) value else partial }, (partial1, partial2) => if (AttributeTypeUtils.compare(partial1, partial2, attributeType) > 0) partial1 else partial2, - partial => if (partial == AttributeTypeUtils.minValue(attributeType)) null else partial + partial => if (partial == AttributeTypeUtils.minValue(attributeType)) null else partial, + tuple => tuple.getField[Object](attribute) ) } - private def getNumericalValue(tuple: Tuple): Option[Double] = { - val value: Object = tuple.getField(attribute) - if (value == null) - return None - - if (tuple.getSchema.getAttribute(attribute).getType == AttributeType.TIMESTAMP) - Option(AttributeTypeUtils.parseTimestamp(value.toString).getTime.toDouble) - else Option(value.toString.toDouble) - } + // Numerical reading of one already-extracted value. A timestamp counts as its + // epoch milliseconds; any other value parses through its string form. null (an + // absent value) is None, so it is skipped by the average. + private def numericalValue(value: Object): Option[Double] = + value match { + case null => None + case ts: java.sql.Timestamp => Option(ts.getTime.toDouble) + case other => Option(other.toString.toDouble) + } private def averageAgg(): DistributedAggregation[AveragePartialObj] = { new DistributedAggregation[AveragePartialObj]( () => AveragePartialObj(0, 0), - (partial, tuple) => { - val value = getNumericalValue(tuple) + (partial, value) => { + val num = numericalValue(value) AveragePartialObj( - partial.sum + (if (value.isDefined) value.get else 0), - partial.count + (if (value.isDefined) 1 else 0) + partial.sum + num.getOrElse(0d), + partial.count + (if (num.isDefined) 1 else 0) ) }, (partial1, partial2) => @@ -266,7 +260,8 @@ class AggregationOperation { partial => { val ret: java.lang.Double = if (partial.count == 0d) null else partial.sum / partial.count ret - } + }, + tuple => tuple.getField[Object](attribute) ) } } diff --git a/common/workflow-operator/src/main/scala/org/apache/texera/amber/operator/aggregate/DistributedAggregation.scala b/common/workflow-operator/src/main/scala/org/apache/texera/amber/operator/aggregate/DistributedAggregation.scala index eab33e430be..55f063c02ee 100644 --- a/common/workflow-operator/src/main/scala/org/apache/texera/amber/operator/aggregate/DistributedAggregation.scala +++ b/common/workflow-operator/src/main/scala/org/apache/texera/amber/operator/aggregate/DistributedAggregation.scala @@ -43,10 +43,17 @@ import org.apache.texera.amber.core.tuple.Tuple case class DistributedAggregation[P <: AnyRef]( // () => PartialObject init: () => P, - // PartialObject + Tuple => PartialObject - iterate: (P, Tuple) => P, + // PartialObject + inputValue => PartialObject. The value is the one cell this + // aggregation reads (already extracted), or null for COUNT(*). Both the row path + // (via `iterate`) and the columnar path feed this, so accumulation is defined once. + iterateValue: (P, Object) => P, // PartialObject + PartialObject => PartialObject merge: (P, P) => P, // PartialObject => Tuple with one column, later be combined into FinalObject - finalAgg: (P) => Object -) + finalAgg: (P) => Object, + // Pull the one value this aggregation reads out of a tuple (null for COUNT(*)). + extract: Tuple => Object +) { + // Row path: extract the value this aggregation reads, then accumulate it. + def iterate(partial: P, tuple: Tuple): P = iterateValue(partial, extract(tuple)) +} diff --git a/common/workflow-operator/src/test/scala/org/apache/texera/amber/operator/aggregate/AggregateOpSpec.scala b/common/workflow-operator/src/test/scala/org/apache/texera/amber/operator/aggregate/AggregateOpSpec.scala index 9bd4e476e27..52fa9a757f5 100644 --- a/common/workflow-operator/src/test/scala/org/apache/texera/amber/operator/aggregate/AggregateOpSpec.scala +++ b/common/workflow-operator/src/test/scala/org/apache/texera/amber/operator/aggregate/AggregateOpSpec.scala @@ -20,6 +20,7 @@ package org.apache.texera.amber.operator.aggregate import org.apache.texera.amber.core.tuple.{Attribute, AttributeType, Schema, Tuple} +import org.apache.texera.amber.util.ArrowUtils import org.apache.texera.amber.util.JSONUtils.objectMapper import org.scalatest.funsuite.AnyFunSuite @@ -710,4 +711,59 @@ class AggregateOpSpec extends AnyFunSuite { // 3, not 13: the first run's partial sum for "NY" must have been dropped. assert(results.head.getFields(1).asInstanceOf[Number].intValue() == 3) } + + test("AggregateOpExec columnar accumulate matches the row path (grouped SUM/COUNT/AVG/MIN/MAX)") { + // The native-Arrow accumulate (processColumnarBatch) must produce the same + // grouped result as feeding the same rows through processTuple, so enabling the + // columnar wire never changes an aggregate's output. + val schema = makeSchema( + "city" -> AttributeType.STRING, + "sales" -> AttributeType.INTEGER + ) + val rows = Seq( + makeTuple(schema, "NY", 10), + makeTuple(schema, "SF", 20), + makeTuple(schema, "NY", 5), + makeTuple(schema, "SF", 7), + makeTuple(schema, "NY", null) // a null value: counted by COUNT(*) only, skipped by the rest + ) + + val desc = new AggregateOpDesc() + desc.aggregations = List( + makeAggregationOp(AggregationFunction.SUM, "sales", "sum_sales"), + makeAggregationOp(AggregationFunction.COUNT, "", "n_rows"), + makeAggregationOp(AggregationFunction.AVERAGE, "sales", "avg_sales"), + makeAggregationOp(AggregationFunction.MIN, "sales", "min_sales"), + makeAggregationOp(AggregationFunction.MAX, "sales", "max_sales") + ) + desc.groupByKeys = List("city") + val descJson = objectMapper.writeValueAsString(desc) + + def resultsOf(feed: AggregateOpExec => Unit): Map[String, List[Any]] = { + val exec = new AggregateOpExec(descJson) + exec.open() + feed(exec) + val out = exec + .onFinish(0) + .toList + .map { t => + val f = t.getFields + f(0).asInstanceOf[String] -> f.drop(1).toList + } + .toMap + exec.close() + out + } + + val rowResult = resultsOf(exec => rows.foreach(exec.processTuple(_, 0))) + val colResult = + resultsOf(exec => + exec.processColumnarBatch(ArrowUtils.serializeTuples(schema, rows.toArray), 0) + ) + + assert(colResult.keySet == rowResult.keySet) + colResult.keys.foreach { city => + assert(colResult(city) == rowResult(city), s"group $city differs") + } + } } diff --git a/common/workflow-operator/src/test/scala/org/apache/texera/amber/operator/aggregate/DistributedAggregationSpec.scala b/common/workflow-operator/src/test/scala/org/apache/texera/amber/operator/aggregate/DistributedAggregationSpec.scala index 4a6cd7db97f..fedef169da7 100644 --- a/common/workflow-operator/src/test/scala/org/apache/texera/amber/operator/aggregate/DistributedAggregationSpec.scala +++ b/common/workflow-operator/src/test/scala/org/apache/texera/amber/operator/aggregate/DistributedAggregationSpec.scala @@ -36,33 +36,50 @@ class DistributedAggregationSpec extends AnyFlatSpec { // Partial = (sum, count) private val avgAggregation = DistributedAggregation[(Long, Long)]( init = () => (0L, 0L), - iterate = (partial, t) => (partial._1 + t.getField[Integer]("v").longValue(), partial._2 + 1L), + iterateValue = + (partial, v) => (partial._1 + v.asInstanceOf[Integer].longValue(), partial._2 + 1L), merge = (a, b) => (a._1 + b._1, a._2 + b._2), finalAgg = partial => if (partial._2 == 0L) java.lang.Double.valueOf(0.0d) - else java.lang.Double.valueOf(partial._1.toDouble / partial._2.toDouble) + else java.lang.Double.valueOf(partial._1.toDouble / partial._2.toDouble), + extract = t => t.getField[Integer]("v") ) // --------------------------------------------------------------------------- // Case-class shape // --------------------------------------------------------------------------- - "DistributedAggregation" should "expose all four function members" in { + "DistributedAggregation" should "expose all function members" in { assert(avgAggregation.init != null) - assert(avgAggregation.iterate != null) + assert(avgAggregation.iterateValue != null) assert(avgAggregation.merge != null) assert(avgAggregation.finalAgg != null) + assert(avgAggregation.extract != null) } it should "be a case class (equality on same function refs)" in { val sameInit = avgAggregation.init - val sameIter = avgAggregation.iterate + val sameIterValue = avgAggregation.iterateValue val sameMerge = avgAggregation.merge val sameFinal = avgAggregation.finalAgg - val copy = DistributedAggregation[(Long, Long)](sameInit, sameIter, sameMerge, sameFinal) + val sameExtract = avgAggregation.extract + val copy = + DistributedAggregation[(Long, Long)]( + sameInit, + sameIterValue, + sameMerge, + sameFinal, + sameExtract + ) assert(copy == avgAggregation) } + it should "derive iterate from extract + iterateValue (row path equals value path)" in { + val viaTuple = avgAggregation.iterate(avgAggregation.init(), tup(9)) + val viaValue = avgAggregation.iterateValue(avgAggregation.init(), Integer.valueOf(9)) + assert(viaTuple == viaValue) + } + // --------------------------------------------------------------------------- // init — produces a fresh partial each call // --------------------------------------------------------------------------- From 28ee435f37e32ba341caaf5d30337085d9856767 Mon Sep 17 00:00:00 2001 From: Matthew Ball Date: Fri, 13 Nov 2026 18:15:27 -0800 Subject: [PATCH 04/16] perf(wire): faster Arrow-to-tuple decode, and a columnar-wire benchmark Adds a benchmark that measures the columnar wire against the row wire on the real Pekko/Kryo stack, and speeds up the Arrow-to-tuple decode it exercises. Decode (ArrowUtils): - getTexeraTuple gains an overload that takes the already-resolved Texera schema, and the no-schema overload delegates to it. deserializeTuples now resolves the Texera schema, the field-vector array, and each column's attribute type once per stream and builds each row with a plain index loop (getCell per column into a fresh Array, then the Tuple constructor), instead of rebuilding the schema and allocating a Scala collection per row. Benchmark (ColumnarWireBenchSpec): - Serializes batches through the configured Pekko serialization (SerializationExtension on an ActorSystem built from AmberRuntime.pekkoConfig), so the row path is a real Kryo DataFrame round-trip and the columnar path is ArrowUtils.serializeTuples wrapped in a ColumnarFrame. For narrow-numeric, wide-mixed, and string-heavy workloads at 2k/20k/100k rows it reports sender encode time, receiver decode time, and serialized payload size for each path. - A second scenario measures the decisive case: a vectorized receiver (a SpecializedFilterOpExec) that reads the Arrow columns directly via processColumnarBatch, against the row path that deserializes the DataFrame and runs the predicate per tuple. - It is skipped unless run with -Dcolumnar.bench=true, so it does not run in CI. Findings (this machine, JDK 17, median of 7): the columnar wire has a smaller payload (about 0.45x-0.91x) and a cheaper encode (about 0.5x at 100k rows), but decoding Arrow back to tuples is far more expensive than Kryo rehydrating a DataFrame (roughly 40x-68x), so a receiver that decodes to rows is a net loss. A receiver that vectorizes instead wins clearly: the filter's processColumnarBatch is about 0.13x the row path's receive+process at 100k rows (around 7x faster). So the columnar wire pays off only when the receiver consumes columns natively; routing a ColumnarFrame to a ColumnarOperatorExecutor's processColumnarBatch in the worker (instead of always decoding) is the next step. --- .../partitioners/ColumnarWireBenchSpec.scala | 308 ++++++++++++++++++ .../apache/texera/amber/util/ArrowUtils.scala | 27 +- 2 files changed, 334 insertions(+), 1 deletion(-) create mode 100644 amber/src/test/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/ColumnarWireBenchSpec.scala diff --git a/amber/src/test/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/ColumnarWireBenchSpec.scala b/amber/src/test/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/ColumnarWireBenchSpec.scala new file mode 100644 index 00000000000..43c994c398d --- /dev/null +++ b/amber/src/test/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/ColumnarWireBenchSpec.scala @@ -0,0 +1,308 @@ +/* + * 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. + */ + +package org.apache.texera.amber.engine.architecture.sendsemantics.partitioners + +import org.apache.pekko.actor.ActorSystem +import org.apache.pekko.serialization.SerializationExtension +import org.apache.pekko.testkit.TestKit +import org.apache.texera.amber.core.tuple.{Attribute, AttributeType, Schema, Tuple} +import org.apache.texera.amber.engine.common.AmberRuntime +import org.apache.texera.amber.engine.common.ambermessage.{ColumnarFrame, DataFrame} +import org.apache.texera.amber.util.ArrowUtils +import org.scalatest.BeforeAndAfterAll +import org.scalatest.flatspec.AnyFlatSpecLike + +import java.sql.Timestamp +import scala.util.Random + +/** + * Measures the per-batch wire cost of the two data-batch formats a cross-worker + * link can use: the row path (a DataFrame of Tuples, serialized by the real + * Pekko/Kryo stack) versus the columnar path (an Arrow IPC ColumnarFrame). For + * each format it reports sender cost (encode), receiver cost (decode), and the + * serialized payload size, so the numbers reflect what actually crosses the wire. + * + * This is a benchmark, not an assertion of a speedup (same-JVM links never + * serialize, so the columnar wire's payoff is specifically on cross-worker links; + * these numbers isolate that serialize/deserialize/size tradeoff). Run with: + * WorkflowExecutionService/testOnly *ColumnarWireBenchSpec + */ +class ColumnarWireBenchSpec + extends TestKit(ActorSystem("ColumnarWireBench", AmberRuntime.pekkoConfig)) + with AnyFlatSpecLike + with BeforeAndAfterAll { + + private val serde = SerializationExtension(system) + + private val rng = new Random(42) + + // ---- workloads ----------------------------------------------------------- + + private def narrowNumeric(n: Int): (Schema, Array[Tuple]) = { + val schema = Schema( + List(new Attribute("a", AttributeType.INTEGER), new Attribute("b", AttributeType.DOUBLE)) + ) + val rows = Array.tabulate(n) { _ => + Tuple + .builder(schema) + .addSequentially(Array[Any](Int.box(rng.nextInt()), Double.box(rng.nextDouble()))) + .build() + } + (schema, rows) + } + + private def wideMixed(n: Int): (Schema, Array[Tuple]) = { + val schema = Schema( + List( + new Attribute("i", AttributeType.INTEGER), + new Attribute("l", AttributeType.LONG), + new Attribute("d", AttributeType.DOUBLE), + new Attribute("b", AttributeType.BOOLEAN), + new Attribute("t", AttributeType.TIMESTAMP), + new Attribute("s", AttributeType.STRING) + ) + ) + val rows = Array.tabulate(n) { i => + Tuple + .builder(schema) + .addSequentially( + Array[Any]( + Int.box(rng.nextInt()), + Long.box(rng.nextLong()), + Double.box(rng.nextDouble()), + Boolean.box(i % 2 == 0), + new Timestamp(1_600_000_000_000L + i), + s"row-$i-${rng.alphanumeric.take(8).mkString}" + ) + ) + .build() + } + (schema, rows) + } + + private def stringHeavy(n: Int): (Schema, Array[Tuple]) = { + val schema = Schema( + List(new Attribute("s1", AttributeType.STRING), new Attribute("s2", AttributeType.STRING)) + ) + val rows = Array.tabulate(n) { _ => + Tuple + .builder(schema) + .addSequentially( + Array[Any](rng.alphanumeric.take(32).mkString, rng.alphanumeric.take(32).mkString) + ) + .build() + } + (schema, rows) + } + + // ---- timing -------------------------------------------------------------- + + private def median(xs: Seq[Double]): Double = { + val s = xs.sorted + s(s.length / 2) + } + + private def timeMs(body: => Unit): Double = { + val t0 = System.nanoTime() + body + (System.nanoTime() - t0) / 1e6 + } + + private val warmups = 3 + private val trials = 7 + + private case class Result( + rowEncMs: Double, + colEncMs: Double, + rowDecMs: Double, + colDecMs: Double, + rowBytes: Int, + colBytes: Int + ) + + private def measure(schema: Schema, rows: Array[Tuple]): Result = { + // Row path: Pekko/Kryo over the DataFrame of tuples. + def rowEncode(): Array[Byte] = serde.serialize(DataFrame(rows)).get + def rowDecode(bytes: Array[Byte]): AnyRef = + serde.deserialize(bytes, classOf[DataFrame]).get + + // Columnar path: Arrow-serialize the batch (as NetworkOutputBuffer does), then + // Pekko/Kryo over the resulting ColumnarFrame (which just wraps the bytes). + def colEncode(): Array[Byte] = { + val arrow = ArrowUtils.serializeTuples(schema, rows) + serde.serialize(ColumnarFrame(arrow, rows.length, schema)).get + } + def colDecode(bytes: Array[Byte]): AnyRef = { + val cf = serde.deserialize(bytes, classOf[ColumnarFrame]).get + ArrowUtils.deserializeTuples(cf.arrowIpcBytes) + } + + for (_ <- 0 until warmups) { rowDecode(rowEncode()); colDecode(colEncode()) } + + val rowWire = rowEncode() + val colWire = colEncode() + val rowEnc = median((0 until trials).map(_ => timeMs(rowEncode()))) + val colEnc = median((0 until trials).map(_ => timeMs(colEncode()))) + val rowDec = median((0 until trials).map(_ => timeMs(rowDecode(rowWire)))) + val colDec = median((0 until trials).map(_ => timeMs(colDecode(colWire)))) + Result(rowEnc, colEnc, rowDec, colDec, rowWire.length, colWire.length) + } + + private def pct(col: Double, row: Double): String = f"${col / row}%.2fx" + + // A benchmark, not a correctness gate: skipped unless -Dcolumnar.bench=true, so it + // does not slow CI. Run it with: + // sbt -Dcolumnar.bench=true "WorkflowExecutionService/testOnly *ColumnarWireBenchSpec" + private def benchEnabled: Boolean = sys.props.get("columnar.bench").contains("true") + + "columnar wire" should "report encode/decode/size vs the row wire" in { + assume(benchEnabled, "set -Dcolumnar.bench=true to run the wire benchmark") + val workloads: Seq[(String, Int => (Schema, Array[Tuple]))] = Seq( + "narrowNumeric" -> narrowNumeric, + "wideMixed" -> wideMixed, + "stringHeavy" -> stringHeavy + ) + val sizes = Seq(2000, 20000, 100000) + + println( + "\n================ Columnar wire vs row wire (median of %d) ================".format(trials) + ) + println( + "%-14s %8s | %10s %10s %6s | %10s %10s %6s | %10s %10s %6s" + .format( + "workload", + "rows", + "rowEnc ms", + "colEnc ms", + "enc", + "rowDec ms", + "colDec ms", + "dec", + "rowKB", + "colKB", + "size" + ) + ) + for ((name, build) <- workloads; n <- sizes) { + val (schema, rows) = build(n) + val r = measure(schema, rows) + println( + "%-14s %8d | %10.2f %10.2f %6s | %10.2f %10.2f %6s | %10.1f %10.1f %6s" + .format( + name, + n, + r.rowEncMs, + r.colEncMs, + pct(r.colEncMs, r.rowEncMs), + r.rowDecMs, + r.colDecMs, + pct(r.colDecMs, r.rowDecMs), + r.rowBytes / 1024.0, + r.colBytes / 1024.0, + pct(r.colBytes.toDouble, r.rowBytes.toDouble) + ) + ) + } + println("(enc/dec/size columns are columnar / row; < 1.00x means columnar is cheaper)\n") + succeed + } + + // The decisive case: a receiver that can VECTORIZE (a filter) skips the + // decode-to-tuples entirely and reads the Arrow columns directly via + // processColumnarBatch. This compares the full receive+process cost of the two + // paths for a filter edge: + // row path: Kryo-deserialize the DataFrame, then run the per-tuple predicate. + // col path: Kryo-deserialize the ColumnarFrame, then processColumnarBatch + // (reads the Arrow column, builds the survivor mask, no tuple decode). + "a vectorized receiver (filter)" should "show whether columnar beats row end to end" in { + assume(benchEnabled, "set -Dcolumnar.bench=true to run the wire benchmark") + import org.apache.texera.amber.operator.filter.{ + ComparisonType, + FilterPredicate, + SpecializedFilterOpExec, + SpecializedFilterOpDesc + } + import org.apache.texera.amber.util.JSONUtils.{objectMapper => om} + + val schema = + Schema( + List(new Attribute("v", AttributeType.INTEGER), new Attribute("w", AttributeType.DOUBLE)) + ) + + def filterExec(): SpecializedFilterOpExec = { + val d = new SpecializedFilterOpDesc() + d.predicates = List(new FilterPredicate("v", ComparisonType.GREATER_THAN, "0")) + val e = new SpecializedFilterOpExec(om.writeValueAsString(d)) + e.open() + e + } + + println("\n========= Filter receive+process: columnar(vectorized) vs row =========") + println("%-10s | %12s %14s %8s".format("rows", "row recv ms", "col recv ms", "col/row")) + for (n <- Seq(2000, 20000, 100000)) { + val rows = Array.tabulate(n)(_ => + Tuple + .builder(schema) + .addSequentially( + Array[Any](Int.box(rng.nextInt(200) - 100), Double.box(rng.nextDouble())) + ) + .build() + ) + val rowWire = serde.serialize(DataFrame(rows)).get + val colWire = + serde.serialize(ColumnarFrame(ArrowUtils.serializeTuples(schema, rows), n, schema)).get + + val rowExec = filterExec() + val colExec = filterExec() + + // Row receive: deserialize the batch, then run the predicate per tuple. + def rowRecv(): Int = { + val df = serde.deserialize(rowWire, classOf[DataFrame]).get + var kept = 0 + val fr = df.frame + var i = 0 + while (i < fr.length) { if (rowExec.filterFunc(fr(i))) kept += 1; i += 1 } + kept + } + // Columnar receive: deserialize the frame, then vectorized filter (no decode). + def colRecv(): Int = { + val cf = serde.deserialize(colWire, classOf[ColumnarFrame]).get + colExec.processColumnarBatch(cf.arrowIpcBytes, 0) match { + case org.apache.texera.amber.core.executor.ColumnarResult.Emit(root) => + val c = root.getRowCount; root.close(); c + case _ => 0 + } + } + + for (_ <- 0 until warmups) { rowRecv(); colRecv() } + val rowMs = median((0 until trials).map(_ => timeMs(rowRecv()))) + val colMs = median((0 until trials).map(_ => timeMs(colRecv()))) + println("%-10d | %12.2f %14.2f %8s".format(n, rowMs, colMs, pct(colMs, rowMs))) + rowExec.close(); colExec.close() + } + println("(col/row < 1.00x means the vectorized columnar receiver is faster)\n") + succeed + } + + override def afterAll(): Unit = { + TestKit.shutdownActorSystem(system) + super.afterAll() + } +} diff --git a/common/workflow-core/src/main/scala/org/apache/texera/amber/util/ArrowUtils.scala b/common/workflow-core/src/main/scala/org/apache/texera/amber/util/ArrowUtils.scala index 6902c21f848..2317816353e 100644 --- a/common/workflow-core/src/main/scala/org/apache/texera/amber/util/ArrowUtils.scala +++ b/common/workflow-core/src/main/scala/org/apache/texera/amber/util/ArrowUtils.scala @@ -96,10 +96,35 @@ object ArrowUtils extends LazyLogging { try { val out = scala.collection.mutable.ArrayBuffer[Tuple]() val root = reader.getVectorSchemaRoot + // Resolved once per stream and reused per row: the Texera schema, the field + // vectors as a plain array, and each column's attribute type. Rebuilding these + // per row (an Arrow-to-Texera schema conversion plus collection allocation) was + // the dominant decode cost. + var schema: Schema = null + var vecs: Array[FieldVector] = null + var types: Array[AttributeType] = null + var numCols = 0 while (reader.loadNextBatch()) { + if (schema == null) { + schema = toTexeraSchema(root.getSchema) + val fv = root.getFieldVectors + numCols = fv.size + vecs = new Array[FieldVector](numCols) + types = new Array[AttributeType](numCols) + var c = 0 + while (c < numCols) { + vecs(c) = fv.get(c); types(c) = schema.getAttributes(c).getType; c += 1 + } + } val n = root.getRowCount var i = 0 - while (i < n) { out += getTexeraTuple(i, root); i += 1 } + while (i < n) { + val values = new Array[Any](numCols) + var c = 0 + while (c < numCols) { values(c) = getCell(vecs(c), i, types(c)); c += 1 } + out += Tuple(schema, values) + i += 1 + } } out.toArray } finally reader.close() From 9b7735c75c2e748a1208bb438f587e657f6aeffc Mon Sep 17 00:00:00 2001 From: Matthew Ball Date: Fri, 13 Nov 2026 22:05:22 -0800 Subject: [PATCH 05/16] feat(engine): vectorized receive for columnar-wire batches Routes an incoming Arrow columnar batch to a ColumnarOperatorExecutor's processColumnarBatch in the worker, so a columnar-capable operator consumes the Arrow columns directly instead of the batch always being decoded back to tuples first. The benchmark showed decoding Arrow to tuples is the columnar wire's dominant cost, far more than Kryo rehydrating a DataFrame, so the wire only pays off when the receiver reads columns natively; this is the path that realizes that win. Worker routing (DataProcessor): - A ColumnarFrame now goes through processColumnarFrame. When the executor is a ColumnarOperatorExecutor, the worker transitions to RUNNING, binds the executor's state references, and hands it the Arrow IPC bytes via processColumnarBatch, then routes the ColumnarResult: Emit(root) is materialized to output tuples (the existing output path is tuple-based) and the root is freed; EmitRows installs the returned rows as the output; Consumed emits nothing now (a blocking operator that accumulated the batch); Unsupported, or any non-columnar executor, falls back to decoding the batch to tuples and processing it as a DataFrame. The READY->RUNNING transition is factored out of startInputBatch into transitToRunning, shared by both paths. For a natively consumed batch the per-tuple input manager is left empty (there is no per-tuple input to drain), so the DP loop drains only the output iterator. - StatisticsManager gains a batched increaseInputStatistics(portId, count, size) so the columnar path reports a whole batch's row count and serialized size in one call rather than once per tuple; the single-tuple overload delegates to it. Root-to-tuples decode (ArrowUtils): - tuplesOfRoot decodes an already-open VectorSchemaRoot to tuples (the Emit output path's root-to-rows step). Like deserializeTuples it resolves the Texera schema, the field vectors, and each column's type once and reads each row with a plain index loop, but it works over a live root without closing it. Tests: - DataProcessorSpec adds the four routing outcomes plus the non-columnar case, driving real ColumnarFrames through processDataPayload with fake executors: Emit (a pass-through filter) emits the batch's rows and never calls processTuple; EmitRows emits the returned rows; Consumed emits nothing and still counts the batch's input statistics; Unsupported and a plain row-only executor both decode the frame and run it through processTuple per row. - ArrowUtilsSpec asserts tuplesOfRoot decodes a live root to the same tuples deserializeTuples produces from the IPC bytes. --- .../architecture/worker/DataProcessor.scala | 84 ++++++++- .../worker/managers/StatisticsManager.scala | 16 +- .../worker/DataProcessorSpec.scala | 161 +++++++++++++++++- .../apache/texera/amber/util/ArrowUtils.scala | 27 +++ .../texera/amber/util/ArrowUtilsSpec.scala | 44 +++++ 5 files changed, 319 insertions(+), 13 deletions(-) diff --git a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/worker/DataProcessor.scala b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/worker/DataProcessor.scala index 1c1f1122009..bbda40707f0 100644 --- a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/worker/DataProcessor.scala +++ b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/worker/DataProcessor.scala @@ -21,7 +21,11 @@ package org.apache.texera.amber.engine.architecture.worker import com.softwaremill.macwire.wire import io.grpc.MethodDescriptor -import org.apache.texera.amber.core.executor.OperatorExecutor +import org.apache.texera.amber.core.executor.{ + ColumnarOperatorExecutor, + ColumnarResult, + OperatorExecutor +} import org.apache.texera.amber.core.state.State import org.apache.texera.amber.core.tuple._ import org.apache.texera.amber.core.virtualidentity.{ @@ -122,6 +126,14 @@ class DataProcessor( channelId: ChannelIdentity, tuples: Array[Tuple] ): Unit = { + transitToRunning() + inputManager.initBatch(channelId, tuples) + processInputTuple(inputManager.getNextTuple) + } + + // Announce the worker is running (READY -> RUNNING, once). Shared by the row and + // columnar input paths. + private[this] def transitToRunning(): Unit = { stateManager.conditionalTransitTo( READY, RUNNING, @@ -133,8 +145,62 @@ class DataProcessor( ) } ) - inputManager.initBatch(channelId, tuples) - processInputTuple(inputManager.getNextTuple) + } + + // Columnar wire: an Arrow batch arrived. If the executor can consume Arrow + // columns directly (a ColumnarOperatorExecutor), hand it the batch and route the + // result; otherwise, or if the executor declines the batch (Unsupported), decode + // to tuples and process it exactly as a DataFrame. + private[this] def processColumnarFrame( + channelId: ChannelIdentity, + portId: PortIdentity, + arrowIpcBytes: Array[Byte], + rowCount: Int + ): Unit = { + val columnarExecutor = executor match { + case c: ColumnarOperatorExecutor => c + case _ => null + } + if (columnarExecutor == null) { + startInputBatch(channelId, ArrowUtils.deserializeTuples(arrowIpcBytes)) + return + } + transitToRunning() + inputManager.currentChannelId = channelId + // The executor sees data: bind its loop variables first (parity with the row path). + bindStateReferences() + try { + columnarExecutor.processColumnarBatch(arrowIpcBytes, portId.id) match { + case ColumnarResult.Unsupported => + // The executor declined this batch: fall back to the row path. + startInputBatch(channelId, ArrowUtils.deserializeTuples(arrowIpcBytes)) + case consumed => + // Consumed natively: no per-tuple input remains for the DP loop to drain. + // Report the whole batch's input statistics in one call. + inputManager.initBatch(channelId, Array.empty) + statisticsManager.increaseInputStatistics( + portId, + rowCount.toLong, + arrowIpcBytes.length.toLong + ) + consumed match { + case ColumnarResult.EmitRows(rows) => + outputManager.outputIterator.setTupleOutput(rows) + case ColumnarResult.Emit(root) => + // Materialize the emitted Arrow batch to output tuples (the existing + // output path is tuple-based), then free the root. + val tuples = + try ArrowUtils.tuplesOfRoot(root) + finally root.close() + outputManager.outputIterator.setTupleOutput( + tuples.iterator.map(t => (t: TupleLike, None: Option[PortIdentity])) + ) + case _ => // Consumed: a blocking operator accumulated the batch, nothing to emit now + } + } + } catch safely { + case e => handleExecutorException(e) + } } private[this] def processInputTuple(tuple: Tuple): Unit = { @@ -267,12 +333,12 @@ class DataProcessor( dataPayload match { case DataFrame(tuples) => startInputBatch(channelId, tuples) - case ColumnarFrame(arrowIpcBytes, _, _) => - // Columnar wire: the batch arrived as Arrow IPC bytes. Decode it back to - // tuples and process it exactly as a DataFrame, so every operator handles - // it transparently. (Consuming the Arrow batch directly for a - // ColumnarOperatorExecutor is a follow-up optimization.) - startInputBatch(channelId, ArrowUtils.deserializeTuples(arrowIpcBytes)) + case ColumnarFrame(arrowIpcBytes, rowCount, _) => + // Columnar wire: the batch arrived as Arrow IPC bytes. A + // ColumnarOperatorExecutor consumes the Arrow columns directly (no per-row + // decode); any other operator, or one that declines the batch, decodes it + // back to tuples and processes it exactly as a DataFrame. + processColumnarFrame(channelId, portId, arrowIpcBytes, rowCount) case StateFrame(state, loopCounter, loopStartId) => processInputState(state, portId.id, loopCounter, loopStartId) } diff --git a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/worker/managers/StatisticsManager.scala b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/worker/managers/StatisticsManager.scala index ab46e17654c..c71e55c788b 100644 --- a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/worker/managers/StatisticsManager.scala +++ b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/worker/managers/StatisticsManager.scala @@ -81,11 +81,21 @@ class StatisticsManager { * @param portId the port identity * @param size the size of the tuple */ - def increaseInputStatistics(portId: PortIdentity, size: Long): Unit = { + def increaseInputStatistics(portId: PortIdentity, size: Long): Unit = + increaseInputStatistics(portId, 1L, size) + + /** + * Increases the input statistics for a given port by a whole batch at once: + * `count` tuples totalling `size` bytes. The columnar-wire path consumes an + * Arrow batch without a per-tuple loop, so it reports the batch's row count and + * serialized size in one call rather than once per tuple. + */ + def increaseInputStatistics(portId: PortIdentity, count: Long, size: Long): Unit = { + require(count >= 0, "Tuple count must be non-negative") require(size >= 0, "Tuple size must be non-negative") inputStatistics.updateWith(portId) { - case Some((count, totalSize)) => Some((count + 1, totalSize + size)) - case None => Some((1L, size)) + case Some((c, totalSize)) => Some((c + count, totalSize + size)) + case None => Some((count, size)) } } diff --git a/amber/src/test/scala/org/apache/texera/amber/engine/architecture/worker/DataProcessorSpec.scala b/amber/src/test/scala/org/apache/texera/amber/engine/architecture/worker/DataProcessorSpec.scala index c48e9594208..f0aeeb9d6cc 100644 --- a/amber/src/test/scala/org/apache/texera/amber/engine/architecture/worker/DataProcessorSpec.scala +++ b/amber/src/test/scala/org/apache/texera/amber/engine/architecture/worker/DataProcessorSpec.scala @@ -20,7 +20,14 @@ package org.apache.texera.amber.engine.architecture.worker import com.fasterxml.jackson.annotation.JsonProperty -import org.apache.texera.amber.core.executor.{ExecFactory, OpExecWithClassName, OperatorExecutor} +import org.apache.arrow.memory.RootAllocator +import org.apache.texera.amber.core.executor.{ + ColumnarOperatorExecutor, + ColumnarResult, + ExecFactory, + OpExecWithClassName, + OperatorExecutor +} import org.apache.texera.amber.core.state.{State, StateReferencing} import org.apache.texera.amber.core.tuple.{AttributeType, Schema, Tuple, TupleLike} import org.apache.texera.amber.core.virtualidentity._ @@ -52,10 +59,12 @@ import org.apache.texera.amber.engine.architecture.worker.WorkflowWorker.{ } import org.apache.texera.amber.engine.architecture.worker.statistics.WorkerState.READY import org.apache.texera.amber.engine.common.ambermessage.{ + ColumnarFrame, DataFrame, StateFrame, WorkflowFIFOMessage } +import org.apache.texera.amber.util.ArrowUtils import org.apache.texera.amber.engine.common.rpc.AsyncRPCClient.ControlInvocation import org.apache.texera.amber.engine.common.storage.SequentialRecordStorage import org.apache.texera.amber.engine.common.virtualidentity.util.COORDINATOR @@ -745,10 +754,160 @@ class DataProcessorSpec extends AnyFlatSpec with MockFactory with Matchers with dp.pauseManager.isPaused shouldBe false } + // --------------------------------------------------------------------------- + // Columnar wire: routing a ColumnarFrame to a ColumnarOperatorExecutor + // --------------------------------------------------------------------------- + + // A batchSize-1 OneToOne partitioner flushes every output tuple immediately as a + // DataFrame (columnar wire is off by default), so what the operator emits is + // observable through the output handler without an explicit flush. + private def columnarSetup( + exec: OperatorExecutor + ): (DataProcessor, ArrayBuffer[WorkflowFIFOMessage]) = { + val dp = mkDataProcessor + val sent = ArrayBuffer[WorkflowFIFOMessage]() + (outputHandler.apply _) + .expects(*) + .onCall { (m: Either[MainThreadDelegateMessage, WorkflowFIFOMessage]) => + m.foreach(sent += _); () + } + .anyNumberOfTimes() + (adaptiveBatchingMonitor.startAdaptiveBatching _).expects().anyNumberOfTimes() + dp.executor = exec + dp.stateManager.transitTo(READY) + dp.inputManager.addPort(inputPortId, schema, List.empty, List.empty) + dp.inputGateway.getChannel(senderChannel).setPortId(inputPortId) + dp.outputManager.addPort(outputPortId, schema, None) + dp.outputManager.addPartitionerWithPartitioning( + PhysicalLink(testOpId, outputPortId, upstreamOpId, inputPortId), + OneToOnePartitioning(1, Seq(ChannelIdentity(testWorkerId, senderWorkerId, isControl = false))) + ) + (dp, sent) + } + + private val columnarBatch: Array[Tuple] = tuples.take(5) + private def columnarFrame: ColumnarFrame = + ColumnarFrame( + ArrowUtils.serializeTuples(schema, columnarBatch), + columnarBatch.length, + schema + ) + + "data processor" should "route a ColumnarFrame to a ColumnarOperatorExecutor and emit its Arrow result" in { + val exec = new DataProcessorSpec.EmitAllColumnarExec + val (dp, sent) = columnarSetup(exec) + dp.processDataPayload(senderChannel, columnarFrame) + drain(dp) + // Emit(root): the emitted Arrow batch is materialized to output tuples. The + // executor consumed the batch natively, so processTuple was never called. + assert(tuplesSent(sent) == columnarBatch.toList) + assert(exec.processTupleCalls == 0) + assert(exec.columnarCalls == 1) + assert(dp.statisticsManager.getInputTupleCount == columnarBatch.length.toLong) + exec.close() + } + + "data processor" should "emit the rows a ColumnarOperatorExecutor returns via EmitRows" in { + val rows = columnarBatch.toList.map(t => (t: TupleLike, None: Option[PortIdentity])) + val exec = new DataProcessorSpec.EmitRowsColumnarExec(rows.iterator) + val (dp, sent) = columnarSetup(exec) + dp.processDataPayload(senderChannel, columnarFrame) + drain(dp) + assert(tuplesSent(sent) == columnarBatch.toList) + assert(exec.processTupleCalls == 0) + } + + "data processor" should "emit nothing for a blocking ColumnarOperatorExecutor that returns Consumed" in { + val exec = new DataProcessorSpec.ConsumedColumnarExec + val (dp, sent) = columnarSetup(exec) + dp.processDataPayload(senderChannel, columnarFrame) + drain(dp) + // Consumed: the batch was accumulated, nothing emitted now, and the row path + // (processTuple) was not taken. Input statistics still count the whole batch. + assert(tuplesSent(sent).isEmpty) + assert(exec.processTupleCalls == 0) + assert(exec.columnarCalls == 1) + assert(dp.statisticsManager.getInputTupleCount == columnarBatch.length.toLong) + } + + "data processor" should "fall back to the row path when a ColumnarOperatorExecutor returns Unsupported" in { + val exec = new DataProcessorSpec.UnsupportedColumnarExec + val (dp, sent) = columnarSetup(exec) + dp.processDataPayload(senderChannel, columnarFrame) + drain(dp) + // Unsupported: the frame is decoded to tuples and processed tuple by tuple, so + // the echoing processTuple sees every row and emits it. + assert(tuplesSent(sent) == columnarBatch.toList) + assert(exec.processTupleCalls == columnarBatch.length) + assert(exec.columnarCalls == 1) + } + + "data processor" should "decode a ColumnarFrame to tuples for a non-columnar operator" in { + val exec = new DataProcessorSpec.RowOnlyExec + val (dp, sent) = columnarSetup(exec) + dp.processDataPayload(senderChannel, columnarFrame) + drain(dp) + // A plain OperatorExecutor cannot consume Arrow, so the frame is decoded and + // processed through the row path. + assert(tuplesSent(sent) == columnarBatch.toList) + assert(exec.processTupleCalls == columnarBatch.length) + } + } object DataProcessorSpec { + /** Echoes each input tuple, counting the row-path calls. Base for the columnar fakes. */ + class EchoingExec extends OperatorExecutor { + var processTupleCalls = 0 + override def processTuple(tuple: Tuple, port: Int): Iterator[TupleLike] = { + processTupleCalls += 1 + Iterator.single(tuple) + } + } + + /** Consumes the Arrow batch and emits every row back (a pass-through filter). */ + class EmitAllColumnarExec extends EchoingExec with ColumnarOperatorExecutor { + var columnarCalls = 0 + private val alloc = new RootAllocator() + override def processColumnarBatch(arrowIpcBytes: Array[Byte], port: Int): ColumnarResult = { + columnarCalls += 1 + ArrowUtils.deserializeRootFold(arrowIpcBytes, alloc) { root => + ColumnarResult.Emit(ArrowUtils.selectRows(root, Array.fill(root.getRowCount)(true), alloc)) + } + } + override def close(): Unit = alloc.close() + } + + /** Returns the given rows directly (a join-shaped output). */ + class EmitRowsColumnarExec(rows: Iterator[(TupleLike, Option[PortIdentity])]) + extends EchoingExec + with ColumnarOperatorExecutor { + override def processColumnarBatch(arrowIpcBytes: Array[Byte], port: Int): ColumnarResult = + ColumnarResult.EmitRows(rows) + } + + /** Accumulates with no per-batch output (a blocking operator). */ + class ConsumedColumnarExec extends EchoingExec with ColumnarOperatorExecutor { + var columnarCalls = 0 + override def processColumnarBatch(arrowIpcBytes: Array[Byte], port: Int): ColumnarResult = { + columnarCalls += 1 + ColumnarResult.Consumed + } + } + + /** Declines every batch, forcing the row fallback. */ + class UnsupportedColumnarExec extends EchoingExec with ColumnarOperatorExecutor { + var columnarCalls = 0 + override def processColumnarBatch(arrowIpcBytes: Array[Byte], port: Int): ColumnarResult = { + columnarCalls += 1 + ColumnarResult.Unsupported + } + } + + /** A plain operator with no columnar path. */ + class RowOnlyExec extends EchoingExec + /** A descString whose `limit` refers to the loop variable `n`. */ val limitReferringToN = """{"limit":0,"stateReferences":{"/limit":"n"}}""" diff --git a/common/workflow-core/src/main/scala/org/apache/texera/amber/util/ArrowUtils.scala b/common/workflow-core/src/main/scala/org/apache/texera/amber/util/ArrowUtils.scala index 2317816353e..ccd04c7e4f7 100644 --- a/common/workflow-core/src/main/scala/org/apache/texera/amber/util/ArrowUtils.scala +++ b/common/workflow-core/src/main/scala/org/apache/texera/amber/util/ArrowUtils.scala @@ -130,6 +130,33 @@ object ArrowUtils extends LazyLogging { } finally reader.close() } + // Decode a live Arrow root to tuples. Like deserializeTuples but over an + // already-open root (the Emit output path's root-to-rows step); does not close + // the root. Resolves the schema, field vectors, and column types once, then + // reads each row with a plain index loop. + def tuplesOfRoot(root: VectorSchemaRoot): Array[Tuple] = { + val schema = toTexeraSchema(root.getSchema) + val fv = root.getFieldVectors + val numCols = fv.size + val vecs = new Array[FieldVector](numCols) + val types = new Array[AttributeType](numCols) + var c0 = 0 + while (c0 < numCols) { + vecs(c0) = fv.get(c0); types(c0) = schema.getAttributes(c0).getType; c0 += 1 + } + val n = root.getRowCount + val out = new Array[Tuple](n) + var i = 0 + while (i < n) { + val values = new Array[Any](numCols) + var c = 0 + while (c < numCols) { values(c) = getCell(vecs(c), i, types(c)); c += 1 } + out(i) = Tuple(schema, values) + i += 1 + } + out + } + // Copy the rows of `src` where keep(i) is true into a new independent root. def selectRows( src: VectorSchemaRoot, diff --git a/common/workflow-core/src/test/scala/org/apache/texera/amber/util/ArrowUtilsSpec.scala b/common/workflow-core/src/test/scala/org/apache/texera/amber/util/ArrowUtilsSpec.scala index 7bd5c631f76..d86f2eb893c 100644 --- a/common/workflow-core/src/test/scala/org/apache/texera/amber/util/ArrowUtilsSpec.scala +++ b/common/workflow-core/src/test/scala/org/apache/texera/amber/util/ArrowUtilsSpec.scala @@ -430,6 +430,50 @@ class ArrowUtilsSpec extends AnyFlatSpec with Matchers { ) shouldBe empty } + // tuplesOfRoot decodes a live root (the Emit output path's root-to-rows step), + // and must produce the same tuples deserializeTuples produces from the IPC bytes. + "tuplesOfRoot" should "decode a live root to the same tuples as deserializeTuples" in { + val rows = Array( + Tuple + .builder(tupleSchema) + .addSequentially( + Array[Any]( + Int.box(1), + Long.box(2L), + Double.box(3.0), + Boolean.box(true), + new Timestamp(123L), + "a", + Array[Byte](9) + ) + ) + .build(), + Tuple + .builder(tupleSchema) + .addSequentially(Array[Any](null, null, null, null, null, null, null)) + .build() + ) + val bytes = ArrowUtils.serializeTuples(tupleSchema, rows) + val allocator = new RootAllocator() + try { + val fromRoot = ArrowUtils.deserializeRootFold(bytes, allocator)(ArrowUtils.tuplesOfRoot) + val fromBytes = ArrowUtils.deserializeTuples(bytes) + fromRoot.length shouldBe rows.length + fromRoot.zip(fromBytes).foreach { + case (got, expected) => + tupleSchema.getAttributes.foreach { attribute => + ( + got.getField[AnyRef](attribute.getName), + expected.getField[AnyRef](attribute.getName) + ) match { + case (g: Array[Byte], e: Array[Byte]) => g shouldBe e + case (g, e) => g shouldBe e + } + } + } + } finally allocator.close() + } + // A Timestamp reaches past 2262, where counting microseconds through // nanoseconds overflowed, and before 1970. Both come back to the microsecond. it should "round-trip a timestamp either side of the nanosecond range" in { From 1a169f2c24b868f353f2b2a2aabdb64af1a371d7 Mon Sep 17 00:00:00 2001 From: Matthew Ball Date: Fri, 13 Nov 2026 23:00:57 -0800 Subject: [PATCH 06/16] feat(engine): columnar output without the round-trip on one-to-one edges When a ColumnarOperatorExecutor emits an Arrow result batch, the worker can now ship it straight downstream as a ColumnarFrame instead of decoding it to tuples and letting the network buffer re-encode those tuples back to Arrow. This removes the columns-to-rows-to-columns round-trip that otherwise gave back the vectorized-receive win at the output boundary. It is the first step of the per-edge columnar design (phase 1): eligibility is limited to the edges where shipping the whole batch to a single receiver is correct, and every other case falls back to the existing row output path unchanged. Output fast path (OutputManager): - tryEmitColumnarBatch(root, outputPortId) resolves the output port, checks eligibility, and on success serializes the root once and sends the resulting ColumnarFrame through each receiver's NetworkOutputBuffer, returning (portId, serializedByteCount) so the caller records output statistics; it returns None (caller falls back) when not eligible. It does not close the root (the caller owns it). An edge is eligible only when the port needs no storage, every partitioner on the port is one-to-one (a single receiver gets the whole batch), and the receiver buffers are in columnar mode. Hash/range/round-robin shuffles need per-row partitioning (a later phase) and broadcast/storage are deferred, so those return None. The emitted Arrow schema must equal the declared output-port schema, otherwise it falls back so the row path's enforceSchema can adjust it. - setColumnarOutput(enabled) flips the columnar flag on every current edge. This is a provisional phase-1 switch; phase 2 replaces it with a per-edge decision from the planner (local vs cross-node, and whether the receiver consumes columns). Network buffer (NetworkOutputBuffer): - sendColumnarFrame(frame) ships an already-serialized Arrow batch straight to the receiver, flushing any buffered tuples first so the batch keeps its place in the FIFO stream. Its columnar flag becomes a var so the output manager can set it per edge. Worker routing (DataProcessor): - The Emit(root) case now tries tryEmitColumnarBatch first and records the batch's output statistics in one call; only when the edge is not eligible does it materialize the root to tuples through the row output path. The root is freed in a finally either way. Batched statistics (StatisticsManager): - increaseOutputStatistics(portId, count, size) mirrors the batched input overload, so the columnar output path counts a whole batch's rows and serialized bytes in one call rather than once per tuple; the single-tuple overload delegates to it. Tests: - OutputManagerSpec covers tryEmitColumnarBatch: a one-to-one columnar edge ships a single ColumnarFrame that decodes back to the input rows; a hash-shuffle edge is declined (returns None, sends nothing); and an edge with columnar output off is declined. - NetworkOutputBufferColumnarSeamSpec covers sendColumnarFrame flushing buffered rows before the prebuilt frame, in order. - DataProcessorSpec adds the eligible-edge case (Emit goes out as one ColumnarFrame, no tuple round-trip, processTuple never runs, output statistics count the batch) and keeps the not-columnar case as the row-output fallback. --- .../messaginglayer/OutputManager.scala | 57 +++++++++++++- .../partitioners/Partitioner.scala | 13 +++- .../architecture/worker/DataProcessor.scala | 24 ++++-- .../worker/managers/StatisticsManager.scala | 16 +++- .../messaginglayer/OutputManagerSpec.scala | 76 +++++++++++++++++++ .../NetworkOutputBufferColumnarSeamSpec.scala | 20 +++++ .../worker/DataProcessorSpec.scala | 22 +++++- 7 files changed, 213 insertions(+), 15 deletions(-) diff --git a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManager.scala b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManager.scala index b15e8992546..8447fd37471 100644 --- a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManager.scala +++ b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManager.scala @@ -37,7 +37,9 @@ import org.apache.texera.amber.engine.architecture.worker.managers.{ PortStorageWriterTerminateSignal } import org.apache.texera.amber.engine.common.AmberLogging -import org.apache.texera.amber.util.VirtualIdentityUtils +import org.apache.texera.amber.engine.common.ambermessage.ColumnarFrame +import org.apache.texera.amber.util.{ArrowUtils, VirtualIdentityUtils} +import org.apache.arrow.vector.VectorSchemaRoot import java.net.URI import scala.collection.mutable @@ -168,6 +170,59 @@ class OutputManager( } } + /** + * Columnar output fast path (no round-trip): ship an operator's Arrow result batch + * straight downstream without decoding it to tuples and re-encoding it. Eligible only + * when the output port needs no storage and every edge on it is one-to-one (a single + * receiver gets the whole batch) with its buffer in columnar mode; hash/range/ + * round-robin shuffles need per-row partitioning (a later phase) and broadcast/storage + * are deferred, so those fall back to the row path. The root is serialized once and the + * same bytes are sent to each one-to-one receiver. Does NOT close `root` (caller owns it). + * + * @return Some((portId, serializedByteCount)) if it shipped the batch (caller records + * output statistics), or None if the port is not eligible (caller falls back). + */ + /** + * Provisional (phase 1): turn the columnar output path on or off for every current + * edge. Phase 2 replaces this blanket switch with a per-edge decision made by the + * planner (local vs cross-node, and whether the receiver consumes columns). + */ + def setColumnarOutput(enabled: Boolean): Unit = + networkOutputBuffers.values.foreach(_.columnar = enabled) + + def tryEmitColumnarBatch( + root: VectorSchemaRoot, + outputPortId: Option[PortIdentity] + ): Option[(PortIdentity, Long)] = { + if (outputPortId.isEmpty && ports.size != 1) return None + val portId = outputPortId.getOrElse(ports.head._1) + val links = partitioners.filter(_._1.fromPortId == portId).toSeq + val eligible = + links.nonEmpty && + !outputPortResultWriterThreads.contains(portId) && + links.forall(_._2.isInstanceOf[OneToOnePartitioner]) && + links.forall { + case (link, partitioner) => + partitioner.allReceivers.forall(r => + networkOutputBuffers.get((link, r)).exists(_.columnar) + ) + } + if (!eligible) return None + val schema = getPort(portId).schema + // The executor's Arrow schema must match the declared output port schema; if not, + // fall back so the row path's enforceSchema can adjust it. + if (ArrowUtils.toTexeraSchema(root.getSchema) != schema) return None + val bytes = ArrowUtils.serializeRoot(root) + val frame = ColumnarFrame(bytes, root.getRowCount, schema) + links.foreach { + case (link, partitioner) => + partitioner.allReceivers.foreach(r => + networkOutputBuffers((link, r)).sendColumnarFrame(frame) + ) + } + Some((portId, bytes.length.toLong)) + } + /** * Flushes the network output buffers based on the specified set of physical links. * diff --git a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/Partitioner.scala b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/Partitioner.scala index 6f129ced8a1..f1316f29965 100644 --- a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/Partitioner.scala +++ b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/Partitioner.scala @@ -40,8 +40,9 @@ class NetworkOutputBuffer( val dataOutputPort: NetworkOutputGateway, val batchSize: Int = ApplicationConfig.defaultDataTransferBatchSize, // Columnar wire (opt-in): flush as ColumnarFrame (Arrow IPC) instead of - // DataFrame. Off by default, so the default wire is unchanged. - val columnar: Boolean = ApplicationConfig.enableColumnarWire + // DataFrame. Off by default, so the default wire is unchanged. A var so the + // output manager can set it per edge (phase 2's planner decides this per link). + var columnar: Boolean = ApplicationConfig.enableColumnarWire ) { var buffer = new ArrayBuffer[Tuple]() @@ -59,6 +60,14 @@ class NetworkOutputBuffer( flush() } + // Columnar fast path: ship an already-serialized Arrow batch straight to the + // receiver, skipping the per-tuple accumulate/re-encode. Any tuples already + // buffered are flushed first so the batch keeps its place in the FIFO stream. + def sendColumnarFrame(frame: ColumnarFrame): Unit = { + flush() + dataOutputPort.sendTo(to, frame) + } + def flush(): Unit = { if (buffer.nonEmpty) { val batch = buffer.toArray diff --git a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/worker/DataProcessor.scala b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/worker/DataProcessor.scala index bbda40707f0..031caf20bc7 100644 --- a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/worker/DataProcessor.scala +++ b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/worker/DataProcessor.scala @@ -187,14 +187,22 @@ class DataProcessor( case ColumnarResult.EmitRows(rows) => outputManager.outputIterator.setTupleOutput(rows) case ColumnarResult.Emit(root) => - // Materialize the emitted Arrow batch to output tuples (the existing - // output path is tuple-based), then free the root. - val tuples = - try ArrowUtils.tuplesOfRoot(root) - finally root.close() - outputManager.outputIterator.setTupleOutput( - tuples.iterator.map(t => (t: TupleLike, None: Option[PortIdentity])) - ) + try { + val rowCount = root.getRowCount + // No round-trip: on an eligible (one-to-one, no-storage, columnar) + // edge, ship the Arrow batch straight downstream. Otherwise + // materialize it to output tuples (the row output path) and let the + // network buffer handle it. + outputManager.tryEmitColumnarBatch(root, None) match { + case Some((portId, byteCount)) => + statisticsManager.increaseOutputStatistics(portId, rowCount.toLong, byteCount) + case None => + val tuples = ArrowUtils.tuplesOfRoot(root) + outputManager.outputIterator.setTupleOutput( + tuples.iterator.map(t => (t: TupleLike, None: Option[PortIdentity])) + ) + } + } finally root.close() case _ => // Consumed: a blocking operator accumulated the batch, nothing to emit now } } diff --git a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/worker/managers/StatisticsManager.scala b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/worker/managers/StatisticsManager.scala index c71e55c788b..ce7cb2c8ff7 100644 --- a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/worker/managers/StatisticsManager.scala +++ b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/worker/managers/StatisticsManager.scala @@ -104,11 +104,21 @@ class StatisticsManager { * @param portId the port identity * @param size the size of the tuple */ - def increaseOutputStatistics(portId: PortIdentity, size: Long): Unit = { + def increaseOutputStatistics(portId: PortIdentity, size: Long): Unit = + increaseOutputStatistics(portId, 1L, size) + + /** + * Increases the output statistics for a given port by a whole batch at once: + * `count` tuples totalling `size` bytes. The columnar-wire output fast path ships + * an Arrow batch without a per-tuple loop, so it reports the batch's row count and + * serialized size in one call rather than once per tuple. + */ + def increaseOutputStatistics(portId: PortIdentity, count: Long, size: Long): Unit = { + require(count >= 0, "Tuple count must be non-negative") require(size >= 0, "Tuple size must be non-negative") outputStatistics.updateWith(portId) { - case Some((count, totalSize)) => Some((count + 1, totalSize + size)) - case None => Some((1L, size)) + case Some((c, totalSize)) => Some((c + count, totalSize + size)) + case None => Some((count, size)) } } diff --git a/amber/src/test/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManagerSpec.scala b/amber/src/test/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManagerSpec.scala index 943dd98ab63..a6c827fb923 100644 --- a/amber/src/test/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManagerSpec.scala +++ b/amber/src/test/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManagerSpec.scala @@ -49,9 +49,13 @@ import org.apache.texera.amber.engine.architecture.messaginglayer.OutputManager. toPartitioner } import org.apache.texera.amber.engine.common.ambermessage._ +import org.apache.texera.amber.util.ArrowUtils +import org.apache.arrow.memory.RootAllocator import org.scalamock.scalatest.MockFactory import org.scalatest.flatspec.AnyFlatSpec +import scala.collection.mutable.ArrayBuffer + class OutputManagerSpec extends AnyFlatSpec with MockFactory { private val mockHandler = mock[WorkflowFIFOMessage => Unit] @@ -377,6 +381,78 @@ class OutputManagerSpec extends AnyFlatSpec with MockFactory { outputManager.closeOutputStorageWriterIfNeeded(PortIdentity(998)) } + // -- tryEmitColumnarBatch (phase 1: no-round-trip columnar output) -------- + + private def capturingOutputManager(): (OutputManager, ArrayBuffer[WorkflowFIFOMessage]) = { + val sent = ArrayBuffer[WorkflowFIFOMessage]() + val om = + new OutputManager(identifier, new NetworkOutputGateway(identifier, m => { sent += m; () })) + (om, sent) + } + + private def emitThrough( + om: OutputManager, + rows: Array[Tuple] + ): Option[(PortIdentity, Long)] = { + val alloc = new RootAllocator() + try { + ArrowUtils.deserializeRootFold(ArrowUtils.serializeTuples(schema, rows), alloc)(root => + om.tryEmitColumnarBatch(root, None) + ) + } finally alloc.close() + } + + "tryEmitColumnarBatch" should "ship a one-to-one columnar edge as a single ColumnarFrame" in { + val (om, sent) = capturingOutputManager() + val portId = PortIdentity(20) + om.addPort(portId, schema, None) + om.addPartitionerWithPartitioning( + PhysicalLink(physicalOpId(), portId, physicalOpId(), portId), + OneToOnePartitioning(1000, Seq(channelTo(ActorVirtualIdentity("o2o-col-rec")))) + ) + om.setColumnarOutput(true) + + val rows = Array(sampleTuple(), sampleTuple(), sampleTuple()) + val result = emitThrough(om, rows) + + assert(result.exists(_._1 == portId)) + assert(sent.size == 1) + val cf = sent.head.payload.asInstanceOf[ColumnarFrame] + assert(cf.rowCount == 3) + assert(ArrowUtils.deserializeTuples(cf.arrowIpcBytes).toList == rows.toList) + } + + it should "decline a hash-shuffle edge (it needs per-row partitioning)" in { + val (om, sent) = capturingOutputManager() + val portId = PortIdentity(21) + om.addPort(portId, schema, None) + om.addPartitionerWithPartitioning( + PhysicalLink(physicalOpId(), portId, physicalOpId(), portId), + HashBasedShufflePartitioning( + 1000, + Seq(channelTo(ActorVirtualIdentity("hash-rec"))), + Seq("field1") + ) + ) + om.setColumnarOutput(true) + + assert(emitThrough(om, Array(sampleTuple())).isEmpty) + assert(sent.isEmpty) + } + + it should "decline when columnar output is off" in { + val (om, sent) = capturingOutputManager() + val portId = PortIdentity(22) + om.addPort(portId, schema, None) + om.addPartitionerWithPartitioning( + PhysicalLink(physicalOpId(), portId, physicalOpId(), portId), + OneToOnePartitioning(1000, Seq(channelTo(ActorVirtualIdentity("off-rec")))) + ) + // Columnar output left off. + assert(emitThrough(om, Array(sampleTuple())).isEmpty) + assert(sent.isEmpty) + } + "getSingleOutputPortIdentity" should "return the sole port when exactly one is present" in { val outputManager: OutputManager = wire[OutputManager] val portId = PortIdentity(13) diff --git a/amber/src/test/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/NetworkOutputBufferColumnarSeamSpec.scala b/amber/src/test/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/NetworkOutputBufferColumnarSeamSpec.scala index 4dbe15d7de1..112b76aca60 100644 --- a/amber/src/test/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/NetworkOutputBufferColumnarSeamSpec.scala +++ b/amber/src/test/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/NetworkOutputBufferColumnarSeamSpec.scala @@ -102,6 +102,26 @@ class NetworkOutputBufferColumnarSeamSpec extends AnyFlatSpec { assert(offSent.isEmpty) } + it should "ship a prebuilt ColumnarFrame after flushing buffered rows, in order" in { + // sendColumnarFrame is the no-round-trip output path: a prebuilt Arrow batch is + // sent straight through, but anything already buffered must flush first so FIFO + // order holds. + val (buffer, sent) = fixture(columnar = true) + buffer.addTuple(tuple(1)) + val frame = + ColumnarFrame(ArrowUtils.serializeTuples(schema, Array(tuple(2), tuple(3))), 2, schema) + buffer.sendColumnarFrame(frame) + + assert(sent.size == 2) + val flushed = sent.head.payload.asInstanceOf[ColumnarFrame] + assert( + ArrowUtils.deserializeTuples(flushed.arrowIpcBytes).map(_.getField[Any]("v")).toList == List( + 1 + ) + ) + assert(sent(1).payload eq frame) + } + it should "honor the flag on the size-triggered auto-flush" in { val (on, onSent) = fixture(columnar = true, batchSize = 2) on.addTuple(tuple(1)) diff --git a/amber/src/test/scala/org/apache/texera/amber/engine/architecture/worker/DataProcessorSpec.scala b/amber/src/test/scala/org/apache/texera/amber/engine/architecture/worker/DataProcessorSpec.scala index f0aeeb9d6cc..a40052bb095 100644 --- a/amber/src/test/scala/org/apache/texera/amber/engine/architecture/worker/DataProcessorSpec.scala +++ b/amber/src/test/scala/org/apache/texera/amber/engine/architecture/worker/DataProcessorSpec.scala @@ -793,9 +793,10 @@ class DataProcessorSpec extends AnyFlatSpec with MockFactory with Matchers with schema ) - "data processor" should "route a ColumnarFrame to a ColumnarOperatorExecutor and emit its Arrow result" in { + "data processor" should "materialize an Emit result to tuples when the output edge is not columnar" in { val exec = new DataProcessorSpec.EmitAllColumnarExec val (dp, sent) = columnarSetup(exec) + // Columnar output is off by default, so the Emit falls back to the row output path. dp.processDataPayload(senderChannel, columnarFrame) drain(dp) // Emit(root): the emitted Arrow batch is materialized to output tuples. The @@ -807,6 +808,25 @@ class DataProcessorSpec extends AnyFlatSpec with MockFactory with Matchers with exec.close() } + "data processor" should "ship an Emit result downstream as a ColumnarFrame with no round-trip on an eligible edge" in { + val exec = new DataProcessorSpec.EmitAllColumnarExec + val (dp, sent) = columnarSetup(exec) + // One-to-one edge, no storage: enable columnar output so the fast path applies. + dp.outputManager.setColumnarOutput(true) + dp.processDataPayload(senderChannel, columnarFrame) + drain(dp) + // The batch goes out as a single ColumnarFrame (not decoded to tuples and + // re-encoded), decoding back to the input rows, and processTuple never ran. + val frames = sent.map(_.payload).collect { case cf: ColumnarFrame => cf } + assert(frames.size == 1) + assert(frames.head.rowCount == columnarBatch.length) + assert(ArrowUtils.deserializeTuples(frames.head.arrowIpcBytes).toList == columnarBatch.toList) + assert(tuplesSent(sent).isEmpty) + assert(exec.processTupleCalls == 0) + assert(dp.statisticsManager.getOutputTupleCount == columnarBatch.length.toLong) + exec.close() + } + "data processor" should "emit the rows a ColumnarOperatorExecutor returns via EmitRows" in { val rows = columnarBatch.toList.map(t => (t: TupleLike, None: Option[PortIdentity])) val exec = new DataProcessorSpec.EmitRowsColumnarExec(rows.iterator) From ad8fe4f8fa1ca880d0dcfc0ad424e234c784adb9 Mon Sep 17 00:00:00 2001 From: Matthew Ball Date: Fri, 13 Nov 2026 23:27:12 -0800 Subject: [PATCH 07/16] feat(engine): decide the columnar wire per edge from the downstream operator The columnar wire is no longer a single global flag that flips every edge at once. The planner now decides it per link, and an edge ships Arrow only when the downstream operator can consume columns natively. This stops the worst case of the blanket switch, shipping Arrow to a row-only operator that then pays a per-tuple decode, and is the capability half of the per-edge design (phase 2). Locality (a same-JVM link gains nothing from serializing) is a later refinement; worker placement is not modeled at planning time and actor refs resolve lazily, so this change keeps that axis out. Operator capability (PhysicalOp): - isColumnarCapable resolves, by name and without loading or instantiating the class, whether the operator's executor mixes in ColumnarOperatorExecutor. Any lookup miss (a code-based or unknown executor) is not capable. This auto-discovers every columnar operator (filter, aggregate, and future ones) with no per-operator registration. Planner decision (ResourceAllocator, LinkConfig): - allocate sets LinkConfig.columnar = ApplicationConfig.enableColumnarWire && the downstream operator isColumnarCapable, for each link. The global flag is now a master switch folded into the per-edge decision rather than a second source of truth. Threading to the sender (proto + handlers): - AddPartitioningRequest gains a columnar bool. LinkWorkersHandler fills it from the link's LinkConfig; the worker's AddPartitioningHandler passes it to OutputManager.addPartitionerWithPartitioning, which constructs that edge's NetworkOutputBuffers in columnar mode. NetworkOutputBuffer.columnar now defaults to false (the planner is the authority) instead of reading ApplicationConfig.enableColumnarWire itself. Tests: - PhysicalOpSpec: isColumnarCapable holds for an executor that implements ColumnarOperatorExecutor, and not for a plain executor, a code-based executor, or an unresolvable class name. - OutputManagerSpec: addPartitionerWithPartitioning builds columnar buffers when told to (a flushed batch goes out as a ColumnarFrame) and row buffers by default (a DataFrame). - The AddPartitioningRequest constructions in WorkerSpec, LoggingSpec, and ArrowFlightActorBench pass columnar = false for the new field. --- .../amber/bench/ArrowFlightActorBench.scala | 3 +- .../architecture/rpc/controlcommands.proto | 4 +++ .../promisehandlers/LinkWorkersHandler.scala | 2 +- .../messaginglayer/OutputManager.scala | 8 +++-- .../scheduling/config/LinkConfig.scala | 5 +++- .../resourcePolicies/ResourceAllocator.scala | 10 ++++++- .../partitioners/Partitioner.scala | 9 +++--- .../AddPartitioningHandler.scala | 2 +- .../messaginglayer/OutputManagerSpec.scala | 28 +++++++++++++++++ .../architecture/worker/WorkerSpec.scala | 2 +- .../engine/faulttolerance/LoggingSpec.scala | 2 +- .../amber/core/workflow/PhysicalOp.scala | 26 +++++++++++++++- .../amber/core/workflow/PhysicalOpSpec.scala | 30 ++++++++++++++++++- 13 files changed, 116 insertions(+), 15 deletions(-) diff --git a/amber/src/bench/scala/org/apache/texera/amber/bench/ArrowFlightActorBench.scala b/amber/src/bench/scala/org/apache/texera/amber/bench/ArrowFlightActorBench.scala index 602f4f08415..002a41936e1 100644 --- a/amber/src/bench/scala/org/apache/texera/amber/bench/ArrowFlightActorBench.scala +++ b/amber/src/bench/scala/org/apache/texera/amber/bench/ArrowFlightActorBench.scala @@ -331,7 +331,8 @@ object ArrowFlightActorBench { // batch_size = cfg.batchSize keeps the Python-side partitioning // buffer aligned with our send size — one Java DataFrame in maps // to exactly one Python DataFrame out. - OneToOnePartitioning(batchSize = cfg.batchSize, channels = Seq(dataChannelOut)) + OneToOnePartitioning(batchSize = cfg.batchSize, channels = Seq(dataChannelOut)), + columnar = false ), ctx, 4L diff --git a/amber/src/main/protobuf/org/apache/texera/amber/engine/architecture/rpc/controlcommands.proto b/amber/src/main/protobuf/org/apache/texera/amber/engine/architecture/rpc/controlcommands.proto index e60b7cd74f6..ecca229c54d 100644 --- a/amber/src/main/protobuf/org/apache/texera/amber/engine/architecture/rpc/controlcommands.proto +++ b/amber/src/main/protobuf/org/apache/texera/amber/engine/architecture/rpc/controlcommands.proto @@ -235,6 +235,10 @@ message AddInputChannelRequest { message AddPartitioningRequest { core.PhysicalLink tag = 1 [(scalapb.field).no_box = true]; sendsemantics.Partitioning partitioning = 2 [(scalapb.field).no_box = true]; + // Per-edge columnar-wire decision from the planner: ship this link's batches as + // Arrow (ColumnarFrame) rather than rows. True only when the downstream operator + // consumes columns natively and the columnar wire is enabled. + bool columnar = 3; } message AssignPortRequest { diff --git a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/coordinator/promisehandlers/LinkWorkersHandler.scala b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/coordinator/promisehandlers/LinkWorkersHandler.scala index 4df3c495224..cd8f924c30c 100644 --- a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/coordinator/promisehandlers/LinkWorkersHandler.scala +++ b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/coordinator/promisehandlers/LinkWorkersHandler.scala @@ -49,7 +49,7 @@ trait LinkWorkersHandler { linkExecution.initChannelExecution(channelId) Seq( workerInterface.addPartitioning( - AddPartitioningRequest(msg.link, linkConfig.partitioning), + AddPartitioningRequest(msg.link, linkConfig.partitioning, linkConfig.columnar), mkContext(channelId.fromWorkerId) ), workerInterface.addInputChannel( diff --git a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManager.scala b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManager.scala index 8447fd37471..21a4aab5769 100644 --- a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManager.scala +++ b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManager.scala @@ -136,12 +136,16 @@ class OutputManager( */ def addPartitionerWithPartitioning( link: PhysicalLink, - partitioning: Partitioning + partitioning: Partitioning, + // Per-edge columnar-wire decision from the planner: ship this edge's batches as + // Arrow (ColumnarFrame) rather than rows. Defaults off so the row wire is unchanged. + columnar: Boolean = false ): Unit = { val partitioner = toPartitioner(partitioning, actorId) partitioners.update(link, partitioner) partitioner.allReceivers.foreach(receiver => { - val buffer = new NetworkOutputBuffer(receiver, outputGateway, getBatchSize(partitioning)) + val buffer = + new NetworkOutputBuffer(receiver, outputGateway, getBatchSize(partitioning), columnar) networkOutputBuffers.update((link, receiver), buffer) outputGateway.addOutputChannel(ChannelIdentity(actorId, receiver, isControl = false)) }) diff --git a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/scheduling/config/LinkConfig.scala b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/scheduling/config/LinkConfig.scala index ef92afef593..7c72c3a580a 100644 --- a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/scheduling/config/LinkConfig.scala +++ b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/scheduling/config/LinkConfig.scala @@ -94,5 +94,8 @@ case object LinkConfig { case class LinkConfig( channelConfigs: List[ChannelConfig], - partitioning: Partitioning + partitioning: Partitioning, + // Per-edge columnar-wire decision: ship this link's batches as Arrow when the + // downstream operator consumes columns natively and the columnar wire is enabled. + columnar: Boolean = false ) diff --git a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/scheduling/resourcePolicies/ResourceAllocator.scala b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/scheduling/resourcePolicies/ResourceAllocator.scala index 346fc195e6c..9b4083c1c74 100644 --- a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/scheduling/resourcePolicies/ResourceAllocator.scala +++ b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/scheduling/resourcePolicies/ResourceAllocator.scala @@ -19,6 +19,7 @@ package org.apache.texera.amber.engine.architecture.scheduling.resourcePolicies +import org.apache.texera.common.config.ApplicationConfig import org.apache.texera.amber.core.virtualidentity.PhysicalOpIdentity import org.apache.texera.amber.core.workflow._ import org.apache.texera.amber.engine.architecture.scheduling.Region @@ -89,7 +90,14 @@ class DefaultResourceAllocator( operatorConfigs(physicalLink.toOpId).workerConfigs.map(_.workerId), linkPartitionInfos(physicalLink), workflowSettings.dataTransferBatchSize - ) + ), + // Per-edge columnar-wire decision: enabled only when the wire is on and the + // downstream operator consumes columns natively (otherwise shipping Arrow + // would force a costly per-tuple decode on the receiver). Locality (same-JVM + // links gain nothing) is a later refinement. + columnar = + ApplicationConfig.enableColumnarWire && + physicalPlan.getOperator(physicalLink.toOpId).isColumnarCapable ) }.toMap diff --git a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/Partitioner.scala b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/Partitioner.scala index f1316f29965..9e09e829a84 100644 --- a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/Partitioner.scala +++ b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/Partitioner.scala @@ -39,10 +39,11 @@ class NetworkOutputBuffer( val to: ActorVirtualIdentity, val dataOutputPort: NetworkOutputGateway, val batchSize: Int = ApplicationConfig.defaultDataTransferBatchSize, - // Columnar wire (opt-in): flush as ColumnarFrame (Arrow IPC) instead of - // DataFrame. Off by default, so the default wire is unchanged. A var so the - // output manager can set it per edge (phase 2's planner decides this per link). - var columnar: Boolean = ApplicationConfig.enableColumnarWire + // Columnar wire: flush as ColumnarFrame (Arrow IPC) instead of DataFrame. The + // planner decides this per edge (it folds in ApplicationConfig.enableColumnarWire + // and the downstream operator's columnar capability) and passes it in; off by + // default so the row wire is unchanged. A var so the output manager can set it. + var columnar: Boolean = false ) { var buffer = new ArrayBuffer[Tuple]() diff --git a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/worker/promisehandlers/AddPartitioningHandler.scala b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/worker/promisehandlers/AddPartitioningHandler.scala index c2da82214bd..6d45d9f8bd1 100644 --- a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/worker/promisehandlers/AddPartitioningHandler.scala +++ b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/worker/promisehandlers/AddPartitioningHandler.scala @@ -40,7 +40,7 @@ trait AddPartitioningHandler { ctx: AsyncRPCContext ): Future[EmptyReturn] = { dp.stateManager.assertState(READY, RUNNING, PAUSED) - dp.outputManager.addPartitionerWithPartitioning(msg.tag, msg.partitioning) + dp.outputManager.addPartitionerWithPartitioning(msg.tag, msg.partitioning, msg.columnar) EmptyReturn() } diff --git a/amber/src/test/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManagerSpec.scala b/amber/src/test/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManagerSpec.scala index a6c827fb923..9de08a254e7 100644 --- a/amber/src/test/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManagerSpec.scala +++ b/amber/src/test/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManagerSpec.scala @@ -453,6 +453,34 @@ class OutputManagerSpec extends AnyFlatSpec with MockFactory { assert(sent.isEmpty) } + "addPartitionerWithPartitioning" should "make the edge's buffers columnar when told to" in { + val (om, sent) = capturingOutputManager() + val portId = PortIdentity(23) + om.addPort(portId, schema, None) + om.addPartitionerWithPartitioning( + PhysicalLink(physicalOpId(), portId, physicalOpId(), portId), + // batchSize 1 so the single tuple auto-flushes. + OneToOnePartitioning(1, Seq(channelTo(ActorVirtualIdentity("col-edge-rec")))), + columnar = true + ) + om.passTupleToDownstream(sampleTuple(), Some(portId)) + assert(sent.size == 1) + assert(sent.head.payload.isInstanceOf[ColumnarFrame]) + } + + it should "keep the edge's buffers on rows by default" in { + val (om, sent) = capturingOutputManager() + val portId = PortIdentity(24) + om.addPort(portId, schema, None) + om.addPartitionerWithPartitioning( + PhysicalLink(physicalOpId(), portId, physicalOpId(), portId), + OneToOnePartitioning(1, Seq(channelTo(ActorVirtualIdentity("row-edge-rec")))) + ) + om.passTupleToDownstream(sampleTuple(), Some(portId)) + assert(sent.size == 1) + assert(sent.head.payload.isInstanceOf[DataFrame]) + } + "getSingleOutputPortIdentity" should "return the sole port when exactly one is present" in { val outputManager: OutputManager = wire[OutputManager] val portId = PortIdentity(13) diff --git a/amber/src/test/scala/org/apache/texera/amber/engine/architecture/worker/WorkerSpec.scala b/amber/src/test/scala/org/apache/texera/amber/engine/architecture/worker/WorkerSpec.scala index 96929eab9a2..7a89a1b92ba 100644 --- a/amber/src/test/scala/org/apache/texera/amber/engine/architecture/worker/WorkerSpec.scala +++ b/amber/src/test/scala/org/apache/texera/amber/engine/architecture/worker/WorkerSpec.scala @@ -167,7 +167,7 @@ class WorkerSpec ) val invocation = AsyncRPCClient.ControlInvocation( METHOD_ADD_PARTITIONING, - AddPartitioningRequest(mockLink, mockPolicy), + AddPartitioningRequest(mockLink, mockPolicy, columnar = false), AsyncRPCContext(COORDINATOR, identifier1), 0 ) diff --git a/amber/src/test/scala/org/apache/texera/amber/engine/faulttolerance/LoggingSpec.scala b/amber/src/test/scala/org/apache/texera/amber/engine/faulttolerance/LoggingSpec.scala index e090642f3c3..5ba1943062f 100644 --- a/amber/src/test/scala/org/apache/texera/amber/engine/faulttolerance/LoggingSpec.scala +++ b/amber/src/test/scala/org/apache/texera/amber/engine/faulttolerance/LoggingSpec.scala @@ -85,7 +85,7 @@ class LoggingSpec ), ControlInvocation( METHOD_ADD_PARTITIONING, - AddPartitioningRequest(mockLink, mockPolicy), + AddPartitioningRequest(mockLink, mockPolicy, columnar = false), AsyncRPCContext(COORDINATOR, identifier1), 0 ), diff --git a/common/workflow-core/src/main/scala/org/apache/texera/amber/core/workflow/PhysicalOp.scala b/common/workflow-core/src/main/scala/org/apache/texera/amber/core/workflow/PhysicalOp.scala index 9c57359f114..337615da51f 100644 --- a/common/workflow-core/src/main/scala/org/apache/texera/amber/core/workflow/PhysicalOp.scala +++ b/common/workflow-core/src/main/scala/org/apache/texera/amber/core/workflow/PhysicalOp.scala @@ -21,7 +21,12 @@ package org.apache.texera.amber.core.workflow import com.fasterxml.jackson.annotation.{JsonIgnore, JsonIgnoreProperties} import com.typesafe.scalalogging.LazyLogging -import org.apache.texera.amber.core.executor.{OpExecInitInfo, OpExecWithCode} +import org.apache.texera.amber.core.executor.{ + ColumnarOperatorExecutor, + OpExecInitInfo, + OpExecWithClassName, + OpExecWithCode +} import org.apache.texera.amber.core.tuple.Schema import org.apache.texera.amber.core.virtualidentity.{ ExecutionIdentity, @@ -270,6 +275,25 @@ case class PhysicalOp( } } + /** + * Whether this operator's executor can consume an Arrow columnar batch directly, + * i.e. its class mixes in ColumnarOperatorExecutor. Resolved by name without loading + * (initializing) or instantiating the class; any lookup failure (e.g. a code-based or + * unknown executor) is treated as not capable. The planner uses this to decide, per + * edge, whether to ship columns to this operator. + */ + @JsonIgnore + def isColumnarCapable: Boolean = { + opExecInitInfo match { + case OpExecWithClassName(className, _) => + try { + val cls = Class.forName(className, false, getClass.getClassLoader) + classOf[ColumnarOperatorExecutor].isAssignableFrom(cls) + } catch { case _: Throwable => false } + case _ => false + } + } + /** * creates a copy with the location preference information */ diff --git a/common/workflow-core/src/test/scala/org/apache/texera/amber/core/workflow/PhysicalOpSpec.scala b/common/workflow-core/src/test/scala/org/apache/texera/amber/core/workflow/PhysicalOpSpec.scala index 3cfbbdad4f6..3d1bbc98fc1 100644 --- a/common/workflow-core/src/test/scala/org/apache/texera/amber/core/workflow/PhysicalOpSpec.scala +++ b/common/workflow-core/src/test/scala/org/apache/texera/amber/core/workflow/PhysicalOpSpec.scala @@ -19,7 +19,7 @@ package org.apache.texera.amber.core.workflow -import org.apache.texera.amber.core.executor.{OpExecInitInfo, OpExecWithCode} +import org.apache.texera.amber.core.executor.{OpExecInitInfo, OpExecWithClassName, OpExecWithCode} import org.apache.texera.amber.core.tuple.{Attribute, AttributeType, Schema} import org.apache.texera.amber.core.virtualidentity.{ ExecutionIdentity, @@ -142,6 +142,21 @@ class PhysicalOpSpec extends AnyFlatSpec { assert(!newOp("p").isPythonBased) } + "PhysicalOp.isColumnarCapable" should "hold only for executors that mix in ColumnarOperatorExecutor" in { + def withClass(cls: Class[_]): PhysicalOp = + newOp("cc").copy(opExecInitInfo = OpExecWithClassName(cls.getName, "{}")) + // A class that implements the columnar contract is capable; a plain executor is not. + assert(withClass(classOf[PhysicalOpSpec.CapableExec]).isColumnarCapable) + assert(!withClass(classOf[PhysicalOpSpec.PlainExec]).isColumnarCapable) + // A code-based executor and an unresolvable class name are both not capable. + assert(!newOp("cc").copy(opExecInitInfo = OpExecWithCode("code", "python")).isColumnarCapable) + assert( + !newOp("cc") + .copy(opExecInitInfo = OpExecWithClassName("no.such.Class", "{}")) + .isColumnarCapable + ) + } + "PhysicalOp.getCode" should "return the code or reject executors without code" in { val op = newOp("c").copy(opExecInitInfo = OpExecWithCode("print(1)", "python")) assert(op.getCode == "print(1)") @@ -249,3 +264,16 @@ class PhysicalOpSpec extends AnyFlatSpec { assert(op.propagateSchema.func(schemas) == schemas) } } + +object PhysicalOpSpec { + // Resolved by name in the isColumnarCapable test; must be top-level (not inner) + // so Class.forName can find them. + class CapableExec extends org.apache.texera.amber.core.executor.ColumnarOperatorExecutor { + override def processColumnarBatch( + arrowIpcBytes: Array[Byte], + port: Int + ): org.apache.texera.amber.core.executor.ColumnarResult = + org.apache.texera.amber.core.executor.ColumnarResult.Unsupported + } + class PlainExec +} From bf28cb5376cc2599c835241e61de7a3e7a77c11d Mon Sep 17 00:00:00 2001 From: Matthew Ball Date: Sat, 14 Nov 2026 02:40:16 -0800 Subject: [PATCH 08/16] feat(engine): columnar shuffle, partition an Arrow batch without decoding rows A shuffle edge on the columnar wire no longer decodes the whole batch to tuples to route it. The columnar output path now partitions an Arrow batch in place: it assigns each row a bucket through the same getBucketIndex the row path uses, reading only the columns the partitioner needs, then gathers each bucket's rows in Arrow and sends one ColumnarFrame per non-empty bucket. Bucket assignment is identical to the row path by construction, so a hash shuffle feeding a join routes rows to exactly the workers the row path would. This completes the columnar wire for hash, range, round-robin, and broadcast edges (one-to-one was already handled); only the key columns are decoded, and the payload stays columnar end to end. Partitioner capability hooks: - Partitioner gains columnarSplits (false for one-to-one and broadcast, which send the whole batch to each receiver; true for hash/range/round-robin, which split it), bucketKeyColumns (the columns getBucketIndex reads: the hash keys, or the first range attribute; empty for round-robin), and requiresFullTuple (true only for a hash with no key columns, which hashes the whole tuple). HashBasedShufflePartitioner, RangeBasedShufflePartitioner, OneToOnePartitioner, and BroadcastPartitioner override these; the defaults cover round-robin. Columnar partitioning (OutputManager): - tryEmitColumnarBatch now accepts any partitioner (it previously required one-to-one). For each eligible link it calls emitColumnarToLink: a non-splitting partitioner serializes the root once and sends it to each receiver; a splitting partitioner builds a partial tuple of just the key columns per row (the full tuple only when requiresFullTuple), calls getBucketIndex to assign the bucket, gathers each bucket's rows into a new Arrow root (ArrowUtils.gather), serializes it, and sends it to that bucket's receiver. A per-manager RootAllocator backs the gathered roots; each is freed right after it is serialized, so its outstanding memory returns to zero. The method returns the total serialized bytes put on the wire for the port's output statistics; eligibility is unchanged (no storage, every edge in columnar mode, schema matches the output port). Tests: - OutputManagerSpec adds differential checks that the columnar shuffle routes rows to the same receivers the row-path partitioner would, for hash, range, and round-robin (which also checks the round-robin counter advances in step), with no row lost or duplicated, and that broadcast sends the whole batch to every receiver. The obsolete "decline a hash-shuffle edge" case (hash now shuffles columnar) is removed; the one-to-one and columnar-off cases remain. --- .../messaginglayer/OutputManager.scala | 97 +++++++++++++++---- .../partitioners/BroadcastPartitioner.scala | 3 + .../HashBasedShufflePartitioner.scala | 4 + .../partitioners/OneToOnePartitioner.scala | 3 + .../partitioners/Partitioner.scala | 19 ++++ .../RangeBasedShufflePartitioner.scala | 2 + .../messaginglayer/OutputManagerSpec.scala | 95 +++++++++++++++--- 7 files changed, 187 insertions(+), 36 deletions(-) diff --git a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManager.scala b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManager.scala index 21a4aab5769..d395ab6f1f9 100644 --- a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManager.scala +++ b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManager.scala @@ -39,6 +39,7 @@ import org.apache.texera.amber.engine.architecture.worker.managers.{ import org.apache.texera.amber.engine.common.AmberLogging import org.apache.texera.amber.engine.common.ambermessage.ColumnarFrame import org.apache.texera.amber.util.{ArrowUtils, VirtualIdentityUtils} +import org.apache.arrow.memory.{BufferAllocator, RootAllocator} import org.apache.arrow.vector.VectorSchemaRoot import java.net.URI @@ -174,18 +175,6 @@ class OutputManager( } } - /** - * Columnar output fast path (no round-trip): ship an operator's Arrow result batch - * straight downstream without decoding it to tuples and re-encoding it. Eligible only - * when the output port needs no storage and every edge on it is one-to-one (a single - * receiver gets the whole batch) with its buffer in columnar mode; hash/range/ - * round-robin shuffles need per-row partitioning (a later phase) and broadcast/storage - * are deferred, so those fall back to the row path. The root is serialized once and the - * same bytes are sent to each one-to-one receiver. Does NOT close `root` (caller owns it). - * - * @return Some((portId, serializedByteCount)) if it shipped the batch (caller records - * output statistics), or None if the port is not eligible (caller falls back). - */ /** * Provisional (phase 1): turn the columnar output path on or off for every current * edge. Phase 2 replaces this blanket switch with a per-edge decision made by the @@ -194,6 +183,24 @@ class OutputManager( def setColumnarOutput(enabled: Boolean): Unit = networkOutputBuffers.values.foreach(_.columnar = enabled) + // Backs the per-bucket roots the columnar shuffle materializes; each is freed right + // after it is serialized, so this allocator's outstanding bytes return to zero. + private lazy val columnarAllocator: BufferAllocator = new RootAllocator() + + /** + * Columnar output path (no round-trip): ship an operator's Arrow result batch straight + * downstream without decoding it to tuples and re-encoding it. Eligible only when the + * output port needs no storage and every edge on it is in columnar mode. A + * non-splitting edge (one-to-one, broadcast) sends the whole batch, serialized once, to + * each receiver. A splitting edge (hash/range/round-robin) assigns each row a bucket + * through the same getBucketIndex the row path uses (reading only the key columns into a + * partial tuple), gathers each bucket's rows in Arrow, and sends one ColumnarFrame per + * non-empty bucket. Bucket assignment is therefore identical to the row path. Does NOT + * close `root` (caller owns it). + * + * @return Some((portId, totalSerializedByteCount)) if it shipped the batch (caller + * records output statistics), or None if the port is not eligible (fall back). + */ def tryEmitColumnarBatch( root: VectorSchemaRoot, outputPortId: Option[PortIdentity] @@ -204,7 +211,6 @@ class OutputManager( val eligible = links.nonEmpty && !outputPortResultWriterThreads.contains(portId) && - links.forall(_._2.isInstanceOf[OneToOnePartitioner]) && links.forall { case (link, partitioner) => partitioner.allReceivers.forall(r => @@ -216,15 +222,64 @@ class OutputManager( // The executor's Arrow schema must match the declared output port schema; if not, // fall back so the row path's enforceSchema can adjust it. if (ArrowUtils.toTexeraSchema(root.getSchema) != schema) return None - val bytes = ArrowUtils.serializeRoot(root) - val frame = ColumnarFrame(bytes, root.getRowCount, schema) - links.foreach { - case (link, partitioner) => - partitioner.allReceivers.foreach(r => - networkOutputBuffers((link, r)).sendColumnarFrame(frame) - ) + Some((portId, links.map { case (link, p) => emitColumnarToLink(root, schema, link, p) }.sum)) + } + + // Ship `root` to one link's receivers in Arrow, splitting per bucket if the partitioner + // splits. Returns the total serialized bytes put on the wire for this link. + private def emitColumnarToLink( + root: VectorSchemaRoot, + schema: Schema, + link: PhysicalLink, + partitioner: Partitioner + ): Long = { + val receivers = partitioner.allReceivers + if (!partitioner.columnarSplits) { + // One-to-one / broadcast: the whole batch goes to each receiver; serialize once. + val bytes = ArrowUtils.serializeRoot(root) + val frame = ColumnarFrame(bytes, root.getRowCount, schema) + receivers.foreach(r => networkOutputBuffers((link, r)).sendColumnarFrame(frame)) + bytes.length.toLong + } else { + // Splitting shuffle: assign each row a bucket, then gather and send per bucket. + val n = root.getRowCount + val rowsPerBucket = Array.fill(receivers.length)(new mutable.ArrayBuffer[Int]()) + // Build only the columns getBucketIndex needs into a partial tuple per row. + val keyCols = + if (partitioner.requiresFullTuple) schema.getAttributes.map(_.getName) + else partitioner.bucketKeyColumns + val keySchema = Schema(keyCols.map(schema.getAttribute).toList) + val keyIdx = + if (keyCols.isEmpty) Array.empty[Int] else ArrowUtils.projectionIndices(root, keyCols) + val keyTypes = keyCols.map(schema.getAttribute(_).getType).toArray + val vectors = root.getFieldVectors + var i = 0 + while (i < n) { + val keyValues = new Array[Any](keyIdx.length) + var c = 0 + while (c < keyIdx.length) { + keyValues(c) = ArrowUtils.getCell(vectors.get(keyIdx(c)), i, keyTypes(c)); c += 1 + } + partitioner.getBucketIndex(Tuple(keySchema, keyValues)).foreach(b => rowsPerBucket(b) += i) + i += 1 + } + var bytes = 0L + var b = 0 + while (b < receivers.length) { + val rows = rowsPerBucket(b) + if (rows.nonEmpty) { + val bucketRoot = ArrowUtils.gather(root, rows.toArray, columnarAllocator) + try { + val frameBytes = ArrowUtils.serializeRoot(bucketRoot) + networkOutputBuffers((link, receivers(b))) + .sendColumnarFrame(ColumnarFrame(frameBytes, rows.length, schema)) + bytes += frameBytes.length.toLong + } finally bucketRoot.close() + } + b += 1 + } + bytes } - Some((portId, bytes.length.toLong)) } /** diff --git a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/BroadcastPartitioner.scala b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/BroadcastPartitioner.scala index 71de92ced60..35c7f757327 100644 --- a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/BroadcastPartitioner.scala +++ b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/BroadcastPartitioner.scala @@ -32,4 +32,7 @@ case class BroadcastPartitioner(partitioning: BroadcastPartitioning) extends Par } override def allReceivers: Seq[ActorVirtualIdentity] = receivers + + // The whole batch goes to every receiver; no per-row split. + override def columnarSplits: Boolean = false } diff --git a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/HashBasedShufflePartitioner.scala b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/HashBasedShufflePartitioner.scala index 7025a4bd2cf..b745f9de137 100644 --- a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/HashBasedShufflePartitioner.scala +++ b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/HashBasedShufflePartitioner.scala @@ -38,4 +38,8 @@ case class HashBasedShufflePartitioner(partitioning: HashBasedShufflePartitionin } override def allReceivers: Seq[ActorVirtualIdentity] = receivers + + // Hash reads the key columns (or the whole tuple when no keys are named). + override def bucketKeyColumns: Seq[String] = partitioning.hashAttributeNames + override def requiresFullTuple: Boolean = partitioning.hashAttributeNames.isEmpty } diff --git a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/OneToOnePartitioner.scala b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/OneToOnePartitioner.scala index f1360f8be4a..41d4b020d81 100644 --- a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/OneToOnePartitioner.scala +++ b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/OneToOnePartitioner.scala @@ -30,4 +30,7 @@ case class OneToOnePartitioner(partitioning: OneToOnePartitioning, actorId: Acto override def allReceivers: Seq[ActorVirtualIdentity] = Seq(partitioning.channels.filter(_.fromWorkerId == actorId).head.toWorkerId) + + // The whole batch goes to the single receiver; no per-row split. + override def columnarSplits: Boolean = false } diff --git a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/Partitioner.scala b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/Partitioner.scala index 9e09e829a84..7dfce654257 100644 --- a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/Partitioner.scala +++ b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/Partitioner.scala @@ -33,6 +33,25 @@ trait Partitioner extends Serializable { def getBucketIndex(tuple: Tuple): Iterator[Int] def allReceivers: Seq[ActorVirtualIdentity] + + // ---- Columnar-shuffle support (phase 3) ------------------------------------- + // These let the columnar output path assign buckets by reading only the columns a + // partitioner needs, then scatter whole rows in Arrow, without decoding every row + // to a Tuple. Bucket assignment still goes through getBucketIndex, so it is + // identical to the row path by construction. + + // Whether this partitioner splits a batch across receivers (hash/range/round-robin) + // or sends the whole batch to each receiver (one-to-one, broadcast). + def columnarSplits: Boolean = true + + // The columns getBucketIndex reads from a tuple (hash/range keys). Empty when the + // bucket does not depend on the row's data (round-robin). The columnar path builds a + // partial tuple of just these columns per row to assign the bucket. + def bucketKeyColumns: Seq[String] = Seq.empty + + // When true, the bucket depends on the whole row (e.g. hash with no key columns, which + // hashes the entire tuple), so the columnar path must build the full tuple per row. + def requiresFullTuple: Boolean = false } class NetworkOutputBuffer( diff --git a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/RangeBasedShufflePartitioner.scala b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/RangeBasedShufflePartitioner.scala index 9b8aae263f1..95a305abe9e 100644 --- a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/RangeBasedShufflePartitioner.scala +++ b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/RangeBasedShufflePartitioner.scala @@ -56,4 +56,6 @@ case class RangeBasedShufflePartitioner(partitioning: RangeBasedShufflePartition override def allReceivers: Seq[ActorVirtualIdentity] = receivers + // Range partitions on the first range attribute only. + override def bucketKeyColumns: Seq[String] = Seq(partitioning.rangeAttributeNames.head) } diff --git a/amber/src/test/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManagerSpec.scala b/amber/src/test/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManagerSpec.scala index 9de08a254e7..26fbda10d09 100644 --- a/amber/src/test/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManagerSpec.scala +++ b/amber/src/test/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManagerSpec.scala @@ -402,6 +402,47 @@ class OutputManagerSpec extends AnyFlatSpec with MockFactory { } finally alloc.close() } + private def rowWith(v: Int): Tuple = TupleLike(v, 2, 3, 4, "5", 9.8).enforceSchema(schema) + + // Emit a batch columnar through a fresh OutputManager carrying `partitioning`, then + // return, per receiver, the rows that receiver actually got (decoded from the Arrow + // frames put on the wire). + private def columnarShuffle( + portId: PortIdentity, + partitioning: Partitioning, + rows: Array[Tuple] + ): Map[ActorVirtualIdentity, List[Tuple]] = { + val (om, sent) = capturingOutputManager() + om.addPort(portId, schema, None) + om.addPartitionerWithPartitioning( + PhysicalLink(physicalOpId(), portId, physicalOpId(), portId), + partitioning, + columnar = true + ) + emitThrough(om, rows) + sent + .groupBy(_.channelId.toWorkerId) + .map { + case (receiver, msgs) => + receiver -> msgs + .flatMap(m => + ArrowUtils.deserializeTuples(m.payload.asInstanceOf[ColumnarFrame].arrowIpcBytes) + ) + .toList + } + } + + // Per receiver, the rows the row-path partitioner would assign, in order. + private def rowPathBuckets( + partitioner: org.apache.texera.amber.engine.architecture.sendsemantics.partitioners.Partitioner, + receivers: Seq[ActorVirtualIdentity], + rows: Array[Tuple] + ): Map[ActorVirtualIdentity, List[Tuple]] = + rows.toList + .flatMap(t => partitioner.getBucketIndex(t).map(b => receivers(b) -> t)) + .groupBy(_._1) + .map { case (r, pairs) => r -> pairs.map(_._2) } + "tryEmitColumnarBatch" should "ship a one-to-one columnar edge as a single ColumnarFrame" in { val (om, sent) = capturingOutputManager() val portId = PortIdentity(20) @@ -422,22 +463,46 @@ class OutputManagerSpec extends AnyFlatSpec with MockFactory { assert(ArrowUtils.deserializeTuples(cf.arrowIpcBytes).toList == rows.toList) } - it should "decline a hash-shuffle edge (it needs per-row partitioning)" in { - val (om, sent) = capturingOutputManager() - val portId = PortIdentity(21) - om.addPort(portId, schema, None) - om.addPartitionerWithPartitioning( - PhysicalLink(physicalOpId(), portId, physicalOpId(), portId), - HashBasedShufflePartitioning( - 1000, - Seq(channelTo(ActorVirtualIdentity("hash-rec"))), - Seq("field1") - ) - ) - om.setColumnarOutput(true) + it should "hash-shuffle rows to the same buckets the row partitioner would" in { + val receivers = (0 until 3).map(i => ActorVirtualIdentity(s"hash-r$i")) + val partitioning = + HashBasedShufflePartitioning(1000, receivers.map(channelTo), Seq("field1")) + val rows = (0 until 50).map(rowWith).toArray + val got = columnarShuffle(PortIdentity(30), partitioning, rows) + val expected = rowPathBuckets(HashBasedShufflePartitioner(partitioning), receivers, rows) + // No row lost or duplicated, and each receiver gets exactly the row-path bucket. + assert(got.values.map(_.size).sum == rows.length) + receivers.foreach(r => assert(got.getOrElse(r, Nil) == expected.getOrElse(r, Nil))) + } - assert(emitThrough(om, Array(sampleTuple())).isEmpty) - assert(sent.isEmpty) + it should "range-shuffle rows to the same buckets the row partitioner would" in { + val receivers = (0 until 3).map(i => ActorVirtualIdentity(s"range-r$i")) + val partitioning = + RangeBasedShufflePartitioning(1000, receivers.map(channelTo), Seq("field1"), 0, 49) + val rows = (0 until 50).map(rowWith).toArray + val got = columnarShuffle(PortIdentity(31), partitioning, rows) + val expected = rowPathBuckets(RangeBasedShufflePartitioner(partitioning), receivers, rows) + assert(got.values.map(_.size).sum == rows.length) + receivers.foreach(r => assert(got.getOrElse(r, Nil) == expected.getOrElse(r, Nil))) + } + + it should "round-robin rows to the same buckets the row partitioner would (counter parity)" in { + val receivers = (0 until 3).map(i => ActorVirtualIdentity(s"rr-r$i")) + val partitioning = RoundRobinPartitioning(1000, receivers.map(channelTo)) + val rows = (0 until 10).map(rowWith).toArray + val got = columnarShuffle(PortIdentity(32), partitioning, rows) + // A fresh row-path partitioner advances the same counter over the same row order. + val expected = rowPathBuckets(RoundRobinPartitioner(partitioning), receivers, rows) + assert(got.values.map(_.size).sum == rows.length) + receivers.foreach(r => assert(got.getOrElse(r, Nil) == expected.getOrElse(r, Nil))) + } + + it should "broadcast the whole batch to every receiver" in { + val receivers = (0 until 3).map(i => ActorVirtualIdentity(s"bc-r$i")) + val partitioning = BroadcastPartitioning(1000, receivers.map(channelTo)) + val rows = (0 until 5).map(rowWith).toArray + val got = columnarShuffle(PortIdentity(33), partitioning, rows) + receivers.foreach(r => assert(got.getOrElse(r, Nil) == rows.toList)) } it should "decline when columnar output is off" in { From 5535198bdfa4ce3eaf512c824d9ebb5a3d11c727 Mon Sep 17 00:00:00 2001 From: Matthew Ball Date: Sat, 14 Nov 2026 04:18:43 -0800 Subject: [PATCH 09/16] feat(projection): native-Arrow column projection for the projection operator ProjectionOpExec can now project an Arrow columnar batch directly, so a projection no longer breaks a columnar region: it keeps the batch columnar instead of decoding every tuple and rebuilding it. Because projection only selects, reorders, and renames columns, each output column is produced by moving its source column's Arrow buffers into the output root under the alias (an Arrow transfer, not a per-cell copy) rather than reading and rewriting values. The operator mixes in ColumnarOperatorExecutor, so the planner's per-edge decision (added earlier) now also routes columns through projections. Columnar projection (ProjectionOpExec): - processColumnarBatch resolves the same (source column -> output alias) pairs that the row path's project() derives, honoring drop mode (keep every column whose lowercased name is not in the drop set) and select mode (the descriptor's attribute units). It builds the output schema from the alias names and the source column types, creates the output root from that schema, and for each output column moves the source vector's buffers into it via Arrow makeTransferPair, renamed to the alias. The result is Emit(outRoot), which the columnar output path ships downstream with no round-trip. - It falls back to the row path (ColumnarResult.Unsupported) for the shapes a single per-column move cannot express or that the row path treats as errors: an empty selection, a source column feeding more than one output (its buffers cannot be moved twice), a duplicated output alias (the row path raises on this), or a source column that does not resolve. A per-operator RootAllocator backs the output roots and is freed in close(). Tests: - ProjectionOpExecSpec adds a columnar-vs-row check that projecting with reorder and rename over a multi-row batch yields, through processColumnarBatch, the same schema and values as processTuple; a drop-mode columnar check; and a check that a duplicate alias makes processColumnarBatch return Unsupported (so the row path raises the error as before). --- .../projection/ProjectionOpExec.scala | 65 +++++++++++++++- .../projection/ProjectionOpExecSpec.scala | 76 +++++++++++++++++++ 2 files changed, 139 insertions(+), 2 deletions(-) diff --git a/common/workflow-operator/src/main/scala/org/apache/texera/amber/operator/projection/ProjectionOpExec.scala b/common/workflow-operator/src/main/scala/org/apache/texera/amber/operator/projection/ProjectionOpExec.scala index b0512cc826a..6b4da6cc32e 100644 --- a/common/workflow-operator/src/main/scala/org/apache/texera/amber/operator/projection/ProjectionOpExec.scala +++ b/common/workflow-operator/src/main/scala/org/apache/texera/amber/operator/projection/ProjectionOpExec.scala @@ -20,15 +20,20 @@ package org.apache.texera.amber.operator.projection import com.google.common.base.Preconditions -import org.apache.texera.amber.core.tuple.{Tuple, TupleLike} +import org.apache.arrow.memory.RootAllocator +import org.apache.arrow.vector.VectorSchemaRoot +import org.apache.texera.amber.core.executor.{ColumnarOperatorExecutor, ColumnarResult} +import org.apache.texera.amber.core.tuple.{Attribute, Schema, Tuple, TupleLike} import org.apache.texera.amber.operator.map.MapOpExec +import org.apache.texera.amber.util.ArrowUtils import org.apache.texera.amber.util.JSONUtils.objectMapper import scala.collection.mutable class ProjectionOpExec( descString: String -) extends MapOpExec { +) extends MapOpExec + with ColumnarOperatorExecutor { val desc: ProjectionOpDesc = objectMapper.readValue(descString, classOf[ProjectionOpDesc]) setMapFunc(project) @@ -66,4 +71,60 @@ class ProjectionOpExec( TupleLike(fields.toSeq: _*) } + // ---- Native-Arrow path: project columns straight on the Arrow batch, no per-tuple + // decode. Each output column takes its source column's buffers by an Arrow transfer + // (a move, not a per-cell copy), renamed to the alias. Falls back to the row path + // (Unsupported) for the shapes a single column move cannot express: a source column + // used by more than one output, a duplicated output name, or an unresolved column. + @transient private var columnarAllocator: RootAllocator = _ + + override def processColumnarBatch(arrowIpcBytes: Array[Byte], port: Int): ColumnarResult = { + if (columnarAllocator == null) columnarAllocator = new RootAllocator() + ArrowUtils.deserializeRootFold(arrowIpcBytes, columnarAllocator)(projectRoot) + } + + // Resolve the (sourceColumn -> outputAlias) pairs exactly as project() does, then move + // each source column into a fresh output root under its alias. + private def projectRoot(root: VectorSchemaRoot): ColumnarResult = { + val inSchema = ArrowUtils.toTexeraSchema(root.getSchema) + val units: List[(String, String)] = + if (desc.isDrop) { + val dropped = desc.attributes.map(_.getOriginalAttribute.toLowerCase).toSet + inSchema.getAttributeNames.filterNot(n => dropped.contains(n.toLowerCase)).map(n => (n, n)) + } else { + desc.attributes.map(u => (u.getOriginalAttribute, u.getAlias)) + } + val originals = units.map(_._1) + val aliases = units.map(_._2) + // A source column used twice cannot be moved twice; a duplicated alias is an error + // the row path raises. Let the row path handle both. + if ( + units.isEmpty || originals.distinct.size != originals.size || + aliases.distinct.size != aliases.size + ) { + return ColumnarResult.Unsupported + } + val outSchema = + try Schema(units.map { + case (orig, alias) => new Attribute(alias, inSchema.getAttribute(orig).getType) + }) + catch { case _: Exception => return ColumnarResult.Unsupported } + val srcIdx = + try ArrowUtils.projectionIndices(root, originals) + catch { case _: Exception => return ColumnarResult.Unsupported } + val outRoot = VectorSchemaRoot.create(ArrowUtils.fromTexeraSchema(outSchema), columnarAllocator) + var j = 0 + while (j < units.size) { + // Move the source column's buffers into the output column (same Arrow type), renamed. + root.getVector(srcIdx(j)).makeTransferPair(outRoot.getVector(j)).transfer() + j += 1 + } + outRoot.setRowCount(root.getRowCount) + ColumnarResult.Emit(outRoot) + } + + override def close(): Unit = { + if (columnarAllocator != null) { columnarAllocator.close(); columnarAllocator = null } + } + } diff --git a/common/workflow-operator/src/test/scala/org/apache/texera/amber/operator/projection/ProjectionOpExecSpec.scala b/common/workflow-operator/src/test/scala/org/apache/texera/amber/operator/projection/ProjectionOpExecSpec.scala index 1d8ee9717bb..cf793cf4cd2 100644 --- a/common/workflow-operator/src/test/scala/org/apache/texera/amber/operator/projection/ProjectionOpExecSpec.scala +++ b/common/workflow-operator/src/test/scala/org/apache/texera/amber/operator/projection/ProjectionOpExecSpec.scala @@ -19,8 +19,10 @@ package org.apache.texera.amber.operator.projection +import org.apache.texera.amber.core.executor.ColumnarResult import org.apache.texera.amber.core.tuple._ import org.apache.texera.amber.core.workflow.PortIdentity +import org.apache.texera.amber.util.ArrowUtils import org.apache.texera.amber.util.JSONUtils.objectMapper import org.scalatest.BeforeAndAfter import org.scalatest.flatspec.AnyFlatSpec @@ -273,4 +275,78 @@ class ProjectionOpExecSpec extends AnyFlatSpec with BeforeAndAfter { val output = projectionOpExec.processTuple(tuple, 0).next().asInstanceOf[MapTupleLike] assert(output.fieldMappings == Map("field1" -> "hello", "field3" -> true)) } + + // ---- Native-Arrow path (columnar projection) ---- + + private val tuple2: Tuple = Tuple + .builder(tupleSchema) + .add(new Attribute("field1", AttributeType.STRING), "world") + .add(new Attribute("field2", AttributeType.INTEGER), 2) + .add(new Attribute("field3", AttributeType.BOOLEAN), false) + .build() + + // Run the batch through processColumnarBatch and decode the emitted Arrow result. + private def columnarProject(exec: ProjectionOpExec, rows: Array[Tuple]): Array[Tuple] = + exec.processColumnarBatch(ArrowUtils.serializeTuples(tupleSchema, rows), 0) match { + case ColumnarResult.Emit(root) => + try ArrowUtils.tuplesOfRoot(root) + finally root.close() + case other => fail(s"expected Emit, got: $other") + } + + it should "project and rename columns on an Arrow batch identically to the row path" in { + opDesc.isDrop = false + opDesc.attributes = List(new AttributeUnit("field2", "f2"), new AttributeUnit("field1", "f1")) + val outputSchema = Schema() + .add(new Attribute("f2", AttributeType.INTEGER)) + .add(new Attribute("f1", AttributeType.STRING)) + val exec = new ProjectionOpExec(objectMapper.writeValueAsString(opDesc)) + exec.open() + + val rows = Array(tuple, tuple2) + val rowOut = rows.map( + exec.processTuple(_, 0).next().asInstanceOf[SchemaEnforceable].enforceSchema(outputSchema) + ) + val colOut = columnarProject(exec, rows) + + assert(colOut.length == rows.length) + colOut.zip(rowOut).foreach { + case (c, r) => + assert(c.getSchema == outputSchema) + assert(c.getField[Any]("f1") == r.getField[Any]("f1")) + assert(c.getField[Any]("f2") == r.getField[Any]("f2")) + } + exec.close() + } + + it should "drop columns on an Arrow batch identically to the row path" in { + opDesc.isDrop = true + opDesc.attributes = List(new AttributeUnit("field2", "")) + val outputSchema = Schema() + .add(new Attribute("field1", AttributeType.STRING)) + .add(new Attribute("field3", AttributeType.BOOLEAN)) + val exec = new ProjectionOpExec(objectMapper.writeValueAsString(opDesc)) + exec.open() + + val colOut = columnarProject(exec, Array(tuple, tuple2)) + assert(colOut.length == 2) + assert(colOut.head.getSchema == outputSchema) + assert(colOut.head.getField[String]("field1") == "hello") + assert(colOut.head.getField[Boolean]("field3")) + assert(colOut(1).getField[String]("field1") == "world") + assert(!colOut(1).getField[Boolean]("field3")) + exec.close() + } + + it should "fall back to the row path (Unsupported) on a duplicate alias" in { + opDesc.isDrop = false + opDesc.attributes = List(new AttributeUnit("field1", "f"), new AttributeUnit("field2", "f")) + val exec = new ProjectionOpExec(objectMapper.writeValueAsString(opDesc)) + exec.open() + assert( + exec.processColumnarBatch(ArrowUtils.serializeTuples(tupleSchema, Array(tuple)), 0) == + ColumnarResult.Unsupported + ) + exec.close() + } } From a892fd6f2a2e786eae35d5912338a5286dd0312e Mon Sep 17 00:00:00 2001 From: Matthew Ball Date: Sat, 14 Nov 2026 04:29:50 -0800 Subject: [PATCH 10/16] test(bench): end-to-end columnar-region vs row benchmark over a serialized pipeline Adds a benchmark that measures a whole columnar region, project -> filter -> aggregate, against the row path for the same pipeline, with each operator on its own worker so the batch crosses a serialized edge between them. It exercises the real operators (ProjectionOpExec, SpecializedFilterOpExec, AggregateOpExec) and the real Pekko/Kryo serialization, so the numbers reflect a cross-worker (cross-node) region, which is where the columnar wire is meant to pay off, rather than the per-edge microbenchmark alone. ColumnarPipelineBenchSpec: - The row path serializes a DataFrame on each of the three edges (source->project, project->filter, filter->aggregate) and runs each operator tuple-at-a-time: project maps and re-enforces each tuple, filter runs the predicate per tuple, aggregate accumulates per tuple. The source->project edge carries the full wide rows (two string payload columns the projection then drops), as a real source edge would. - The columnar path serializes an Arrow ColumnarFrame on each edge and runs each operator's processColumnarBatch, staying columnar across all three hops: projection moves columns, filter emits the surviving rows, aggregate accumulates straight off the Arrow vectors. - Both reset the aggregate via open() per run, warm up, and report the median of several trials for 2k/20k/100k source rows. It is skipped unless run with -Dcolumnar.bench=true, so it does not run in CI. Findings (this machine, JDK 17, median of 7): the columnar region runs end to end in about 0.21x the row path at 2k rows, 0.06x at 20k, and 0.05x at 100k (roughly 5x, 16x, and 19x faster), the gap widening with batch size. This matches the per-edge microbenchmark and the vectorized-operator speedups the literature reports: once a run of operators consumes columns natively, keeping the batch in Arrow across serialized edges avoids both the per-tuple Kryo round-trip and the per-tuple operator work that dominate the row path. --- .../ColumnarPipelineBenchSpec.scala | 224 ++++++++++++++++++ 1 file changed, 224 insertions(+) create mode 100644 amber/src/test/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/ColumnarPipelineBenchSpec.scala diff --git a/amber/src/test/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/ColumnarPipelineBenchSpec.scala b/amber/src/test/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/ColumnarPipelineBenchSpec.scala new file mode 100644 index 00000000000..f4c2273ca2c --- /dev/null +++ b/amber/src/test/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/ColumnarPipelineBenchSpec.scala @@ -0,0 +1,224 @@ +/* + * 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. + */ + +package org.apache.texera.amber.engine.architecture.sendsemantics.partitioners + +import org.apache.pekko.actor.ActorSystem +import org.apache.pekko.serialization.SerializationExtension +import org.apache.pekko.testkit.TestKit +import org.apache.texera.amber.core.executor.ColumnarResult +import org.apache.texera.amber.core.tuple.{ + Attribute, + AttributeType, + Schema, + SchemaEnforceable, + Tuple +} +import org.apache.texera.amber.engine.common.AmberRuntime +import org.apache.texera.amber.engine.common.ambermessage.{ColumnarFrame, DataFrame} +import org.apache.texera.amber.operator.aggregate.{ + AggregateOpDesc, + AggregateOpExec, + AggregationFunction, + AggregationOperation +} +import org.apache.texera.amber.operator.filter.{ + ComparisonType, + FilterPredicate, + SpecializedFilterOpDesc, + SpecializedFilterOpExec +} +import org.apache.texera.amber.operator.projection.{ + AttributeUnit, + ProjectionOpDesc, + ProjectionOpExec +} +import org.apache.texera.amber.util.ArrowUtils +import org.apache.texera.amber.util.JSONUtils.{objectMapper => om} +import org.scalatest.BeforeAndAfterAll +import org.scalatest.flatspec.AnyFlatSpecLike + +import scala.util.Random + +/** + * End-to-end cost of a columnar region vs the row path for a realistic three-operator + * pipeline, project -> filter -> aggregate, with each operator on its own worker so the + * batch crosses a serialized edge between them. The row path serializes a DataFrame and + * runs each operator tuple-at-a-time; the columnar path serializes an Arrow ColumnarFrame + * and runs each operator's processColumnarBatch (no per-tuple decode), staying columnar + * across all three hops. Serialization uses the real Pekko/Kryo stack, so these numbers + * reflect a cross-worker (cross-node) region, which is where the columnar wire is meant to + * pay off. Run with: + * sbt -Dcolumnar.bench=true "WorkflowExecutionService/testOnly *ColumnarPipelineBenchSpec" + */ +class ColumnarPipelineBenchSpec + extends TestKit(ActorSystem("ColumnarPipelineBench", AmberRuntime.pekkoConfig)) + with AnyFlatSpecLike + with BeforeAndAfterAll { + + private val serde = SerializationExtension(system) + private val rng = new Random(7) + + // Source schema: a shuffle/group key, a numeric filter column, and two string payload + // columns the projection drops (so the row path pays to carry them to the projection). + private val srcSchema: Schema = Schema( + List( + new Attribute("key", AttributeType.INTEGER), + new Attribute("v", AttributeType.DOUBLE), + new Attribute("p1", AttributeType.STRING), + new Attribute("p2", AttributeType.STRING) + ) + ) + // After the projection: only the key and the numeric column remain. + private val projSchema: Schema = + Schema( + List(new Attribute("key", AttributeType.INTEGER), new Attribute("v", AttributeType.DOUBLE)) + ) + + private def sourceRows(n: Int): Array[Tuple] = + Array.tabulate(n) { _ => + Tuple + .builder(srcSchema) + .addSequentially( + Array[Any]( + Int.box(rng.nextInt(100)), + Double.box(rng.nextDouble() * 2 - 1), // roughly half pass v > 0 + rng.alphanumeric.take(16).mkString, + rng.alphanumeric.take(16).mkString + ) + ) + .build() + } + + // ---- operators (one instance each; aggregate is reset per run via open()) ---------- + + private val projExec: ProjectionOpExec = { + val d = new ProjectionOpDesc() + d.isDrop = false + d.attributes = List(new AttributeUnit("key", "key"), new AttributeUnit("v", "v")) + val e = new ProjectionOpExec(om.writeValueAsString(d)); e.open(); e + } + + private val filterExec: SpecializedFilterOpExec = { + val d = new SpecializedFilterOpDesc() + d.predicates = List(new FilterPredicate("v", ComparisonType.GREATER_THAN, "0")) + val e = new SpecializedFilterOpExec(om.writeValueAsString(d)); e.open(); e + } + + private val aggJson: String = { + val d = new AggregateOpDesc() + val sum = new AggregationOperation() + sum.aggFunction = AggregationFunction.SUM + sum.attribute = "v" + sum.resultAttribute = "sum_v" + d.aggregations = List(sum) + d.groupByKeys = List("key") + om.writeValueAsString(d) + } + private val aggExec: AggregateOpExec = new AggregateOpExec(aggJson) + + // ---- timing helpers --------------------------------------------------------------- + + private def median(xs: Seq[Double]): Double = { val s = xs.sorted; s(s.length / 2) } + private def timeMs(body: => Unit): Double = { + val t0 = System.nanoTime(); body; (System.nanoTime() - t0) / 1e6 + } + private val warmups = 3 + private val trials = 7 + private def pct(a: Double, b: Double): String = f"${a / b}%.2fx" + + // Row region: each hop is a Kryo DataFrame round-trip, each operator runs per tuple. + private def rowRun(rows: Array[Tuple]): Unit = { + aggExec.open() + // source -> project edge (carries the full wide rows, payload columns included). + val srcRows = + serde.deserialize(serde.serialize(DataFrame(rows)).get, classOf[DataFrame]).get.frame + val projected = srcRows.map(t => + projExec.processTuple(t, 0).next().asInstanceOf[SchemaEnforceable].enforceSchema(projSchema) + ) + val afterEdge1 = + serde.deserialize(serde.serialize(DataFrame(projected)).get, classOf[DataFrame]).get.frame + val filtered = afterEdge1.filter(filterExec.filterFunc) + val afterEdge2 = + serde.deserialize(serde.serialize(DataFrame(filtered)).get, classOf[DataFrame]).get.frame + var i = 0 + while (i < afterEdge2.length) { aggExec.processTuple(afterEdge2(i), 0); i += 1 } + aggExec.onFinish(0).foreach(_ => ()) + } + + // Columnar region: each hop is a Kryo ColumnarFrame round-trip, each operator runs + // processColumnarBatch, and the batch stays Arrow the whole way. + private def colRun(rows: Array[Tuple]): Unit = { + aggExec.open() + def hop(bytes: Array[Byte], rowCount: Int, schema: Schema): Array[Byte] = + serde + .deserialize( + serde.serialize(ColumnarFrame(bytes, rowCount, schema)).get, + classOf[ColumnarFrame] + ) + .get + .arrowIpcBytes + // source -> project + val srcWire = hop(ArrowUtils.serializeTuples(srcSchema, rows), rows.length, srcSchema) + val projBytes = projExec.processColumnarBatch(srcWire, 0) match { + case ColumnarResult.Emit(root) => + try ArrowUtils.serializeRoot(root) + finally root.close() + case other => fail(s"projection: expected Emit, got $other") + } + // project -> filter + val filterIn = hop(projBytes, rows.length, projSchema) + val (filterBytes, keptCount) = filterExec.processColumnarBatch(filterIn, 0) match { + case ColumnarResult.Emit(root) => + try (ArrowUtils.serializeRoot(root), root.getRowCount) + finally root.close() + case other => fail(s"filter: expected Emit, got $other") + } + // filter -> aggregate + val aggIn = hop(filterBytes, keptCount, projSchema) + aggExec.processColumnarBatch(aggIn, 0) + aggExec.onFinish(0).foreach(_ => ()) + } + + private def benchEnabled: Boolean = sys.props.get("columnar.bench").contains("true") + + "a columnar region (project -> filter -> aggregate)" should "beat the row path across serialized edges" in { + assume(benchEnabled, "set -Dcolumnar.bench=true to run the pipeline benchmark") + println( + "\n===== Pipeline project->filter->aggregate, columnar region vs row (median of %d) =====" + .format(trials) + ) + println("%-10s | %12s %12s %8s".format("rows", "row ms", "columnar ms", "col/row")) + for (n <- Seq(2000, 20000, 100000)) { + val rows = sourceRows(n) + for (_ <- 0 until warmups) { rowRun(rows); colRun(rows) } + val rowMs = median((0 until trials).map(_ => timeMs(rowRun(rows)))) + val colMs = median((0 until trials).map(_ => timeMs(colRun(rows)))) + println("%-10d | %12.2f %12.2f %8s".format(n, rowMs, colMs, pct(colMs, rowMs))) + } + println("(col/row < 1.00x means the columnar region is faster end to end)\n") + succeed + } + + override def afterAll(): Unit = { + projExec.close(); filterExec.close(); aggExec.close() + TestKit.shutdownActorSystem(system) + super.afterAll() + } +} From 8600cd88c8819c3ed29eccfd7d068010ad3212b7 Mon Sep 17 00:00:00 2001 From: Matthew Ball Date: Sat, 14 Nov 2026 04:43:05 -0800 Subject: [PATCH 11/16] feat(engine): keep local (same-JVM) edges on rows, columnar only for remote hops The columnar wire now yields to locality: an edge to a co-located receiver stays on rows even when the planner enabled columns for it. A same-JVM hop is delivered by reference and never serializes, so encoding it to Arrow would be pure overhead; the columnar wire only pays on a remote hop that actually crosses the network. The decision is per receiver, not per link, because one sender fans out to receivers on different nodes (a hash shuffle is local to some, remote to others). This closes the same-JVM pessimization the pipeline benchmark exposed: a single-node run now behaves exactly as the row engine, while a cross-node run keeps the columnar win. Locality signal (PekkoActorRefMappingService): - isLocalWorker(id) returns whether the worker's resolved actor ref is in this same ActorSystem (its address has local scope or equals this actor's own address), or None when the ref is not resolved yet. The sender already holds these refs to route data, so no new lookup is needed. Per-receiver decision (NetworkOutputBuffer, OutputManager): - Each NetworkOutputBuffer gains a localityCheck and an effectiveColumnar = columnar && the receiver is not known-local (unknown is treated as remote, so the worst case is briefly using columns before a ref resolves). flush() now consults effectiveColumnar, so the row path emits a DataFrame to a local receiver and a ColumnarFrame to a remote one on the very same link. - OutputManager carries isLocalReceiver (set by the worker) and wires each buffer's localityCheck to it when a partitioner is added. tryEmitColumnarBatch's no-decode fast path now requires every receiver to be effectiveColumnar; a local or mixed-locality edge falls back to the row path, whose per-receiver flush already does the right thing (rows to local receivers, Arrow to remote ones). Fully-remote one-to-one and fully-remote shuffles still take the fast path. Worker wiring (WorkflowWorker): - Sets dp.outputManager.isLocalReceiver = actorRefMappingService.isLocalWorker when the data processor is created and when it is restored from a checkpoint. Tests: - OutputManagerSpec: a local one-to-one edge stays on rows though columnar is enabled; the no-decode fast path is declined for a local receiver and taken for a remote one; and on a mixed-locality hash shuffle the row path sends DataFrames to the local receiver and ColumnarFrames to the remote one. Existing columnar tests are unaffected (locality defaults to unknown, i.e. remote). --- .../common/PekkoActorRefMappingService.scala | 13 ++++ .../messaginglayer/OutputManager.scala | 13 +++- .../partitioners/Partitioner.scala | 11 +++- .../architecture/worker/WorkflowWorker.scala | 4 ++ .../messaginglayer/OutputManagerSpec.scala | 60 +++++++++++++++++++ 5 files changed, 99 insertions(+), 2 deletions(-) diff --git a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/common/PekkoActorRefMappingService.scala b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/common/PekkoActorRefMappingService.scala index 223ffdf8c6a..c8c51406474 100644 --- a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/common/PekkoActorRefMappingService.scala +++ b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/common/PekkoActorRefMappingService.scala @@ -62,6 +62,19 @@ class PekkoActorRefMappingService(actorService: PekkoActorService) extends Amber actorRefMapping.contains(id) } + /** + * Whether worker `id` resolves to an actor in this same ActorSystem, i.e. a local, + * by-reference hop that never serializes, as opposed to a remote node. None when the + * ref is not resolved yet (the caller treats unknown as remote). The columnar output + * path uses this to keep a local edge on rows, since serializing it to Arrow would be + * pure overhead for a hop that otherwise copies nothing. + */ + def isLocalWorker(id: ActorVirtualIdentity): Option[Boolean] = + actorRefMapping.get(id).map { ref => + val address = ref.path.address + address.hasLocalScope || address == self.path.address + } + def forwardToActor(msg: NetworkMessage): Unit = { val id = msg.internalMessage.channelId.toWorkerId if (actorRefMapping.contains(id)) { diff --git a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManager.scala b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManager.scala index d395ab6f1f9..3e0976e93a5 100644 --- a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManager.scala +++ b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManager.scala @@ -115,6 +115,12 @@ class OutputManager( ) extends AmberLogging { val outputIterator: DPOutputIterator = new DPOutputIterator() + + // Set by the worker: whether a receiver worker is co-located (same ActorSystem). A local + // hop never serializes, so the columnar wire is pure overhead there and that edge stays + // on rows. None = not yet known (treated as remote). Wired into each buffer's locality + // check when the partitioner is added. + var isLocalReceiver: ActorVirtualIdentity => Option[Boolean] = _ => None private val partitioners: mutable.Map[PhysicalLink, Partitioner] = mutable.HashMap[PhysicalLink, Partitioner]() @@ -147,6 +153,8 @@ class OutputManager( partitioner.allReceivers.foreach(receiver => { val buffer = new NetworkOutputBuffer(receiver, outputGateway, getBatchSize(partitioning), columnar) + // A local (same-JVM) receiver keeps the edge on rows regardless of the planner flag. + buffer.localityCheck = () => isLocalReceiver(receiver) networkOutputBuffers.update((link, receiver), buffer) outputGateway.addOutputChannel(ChannelIdentity(actorId, receiver, isControl = false)) }) @@ -213,8 +221,11 @@ class OutputManager( !outputPortResultWriterThreads.contains(portId) && links.forall { case (link, partitioner) => + // The no-decode fast path runs only when every receiver is remote-columnar. A + // local (or mixed) edge falls back to the row path, whose per-receiver flush + // already emits rows to local receivers and Arrow to remote ones. partitioner.allReceivers.forall(r => - networkOutputBuffers.get((link, r)).exists(_.columnar) + networkOutputBuffers.get((link, r)).exists(_.effectiveColumnar) ) } if (!eligible) return None diff --git a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/Partitioner.scala b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/Partitioner.scala index 7dfce654257..3126d718f23 100644 --- a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/Partitioner.scala +++ b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/Partitioner.scala @@ -65,6 +65,15 @@ class NetworkOutputBuffer( var columnar: Boolean = false ) { + // Set by the output manager: whether `to` is co-located (same ActorSystem). A local hop + // never serializes, so the columnar wire is pure overhead there; None means not yet + // known, treated as remote. + var localityCheck: () => Option[Boolean] = () => None + + // The columnar decision after locality: honor the planner's flag only for a receiver + // that is remote (or not yet known). A known-local receiver stays on rows. + def effectiveColumnar: Boolean = columnar && !localityCheck().getOrElse(false) + var buffer = new ArrayBuffer[Tuple]() def addTuple(tuple: Tuple): Unit = { @@ -91,7 +100,7 @@ class NetworkOutputBuffer( def flush(): Unit = { if (buffer.nonEmpty) { val batch = buffer.toArray - if (columnar) { + if (effectiveColumnar) { // Serialize the batch to Arrow once; all tuples on a link share the schema. val schema = batch(0).getSchema dataOutputPort.sendTo( diff --git a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/worker/WorkflowWorker.scala b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/worker/WorkflowWorker.scala index 99f10050f39..2371876e6e5 100644 --- a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/worker/WorkflowWorker.scala +++ b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/worker/WorkflowWorker.scala @@ -86,6 +86,9 @@ class WorkflowWorker( // Internal inputQueue is passed to dp.InputManager because input port materialization // reader threads need to put input data read from materialization into this queue. var dp = new DataProcessor(workerConfig.workerId, logManager.sendCommitted, inputQueue) + // Let the output manager tell a local (same-JVM) receiver from a remote one, so the + // columnar wire is used only where it pays (a remote hop that actually serializes). + dp.outputManager.isLocalReceiver = actorRefMappingService.isLocalWorker val timerService = new WorkerTimerService(actorService) var dpThread: DPThread = _ @@ -173,6 +176,7 @@ class WorkflowWorker( logger.info("output messages restored.") dp = dpState // overwrite dp state dp.outputHandler = logManager.sendCommitted + dp.outputManager.isLocalReceiver = actorRefMappingService.isLocalWorker dp.initTimerService(timerService) logger.info("start re-initialize executor from checkpoint.") val (executor, iter) = dp.serializationManager.restoreExecutorState(chkpt) diff --git a/amber/src/test/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManagerSpec.scala b/amber/src/test/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManagerSpec.scala index 26fbda10d09..44957666a30 100644 --- a/amber/src/test/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManagerSpec.scala +++ b/amber/src/test/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManagerSpec.scala @@ -505,6 +505,66 @@ class OutputManagerSpec extends AnyFlatSpec with MockFactory { receivers.foreach(r => assert(got.getOrElse(r, Nil) == rows.toList)) } + // -- locality guard (phase 2b): a local (same-JVM) receiver stays on rows --------- + + "locality guard" should "keep a local one-to-one edge on rows even when columnar is enabled" in { + val (om, sent) = capturingOutputManager() + val rec = ActorVirtualIdentity("local-o2o") + val portId = PortIdentity(40) + om.addPort(portId, schema, None) + om.addPartitionerWithPartitioning( + PhysicalLink(physicalOpId(), portId, physicalOpId(), portId), + OneToOnePartitioning(1, Seq(channelTo(rec))), + columnar = true + ) + om.isLocalReceiver = id => if (id == rec) Some(true) else None + om.passTupleToDownstream(sampleTuple(), Some(portId)) + // columnar is on, but the receiver is local, so the batch goes out as rows. + assert(sent.size == 1) + assert(sent.head.payload.isInstanceOf[DataFrame]) + } + + it should "decline the no-decode fast path for a local receiver, take it for a remote one" in { + def fastPathTaken(local: Boolean): Boolean = { + val (om, _) = capturingOutputManager() + val rec = ActorVirtualIdentity(s"fast-$local") + val portId = PortIdentity(if (local) 41 else 42) + om.addPort(portId, schema, None) + om.addPartitionerWithPartitioning( + PhysicalLink(physicalOpId(), portId, physicalOpId(), portId), + OneToOnePartitioning(1000, Seq(channelTo(rec))), + columnar = true + ) + om.isLocalReceiver = _ => Some(local) + emitThrough(om, Array(sampleTuple())).isDefined + } + assert(!fastPathTaken(local = true)) // local -> fall back to the row path + assert(fastPathTaken(local = false)) // remote -> columnar fast path + } + + it should "in the row path, send rows to a local receiver and Arrow to a remote one on a mixed shuffle" in { + val local = ActorVirtualIdentity("mix-local") + val remote = ActorVirtualIdentity("mix-remote") + val (om, sent) = capturingOutputManager() + val portId = PortIdentity(43) + om.addPort(portId, schema, None) + om.addPartitionerWithPartitioning( + PhysicalLink(physicalOpId(), portId, physicalOpId(), portId), + // batchSize 1 so each tuple flushes to its bucket immediately. + HashBasedShufflePartitioning(1, Seq(channelTo(local), channelTo(remote)), Seq("field1")), + columnar = true + ) + om.isLocalReceiver = id => Some(id == local) + (0 until 40).foreach(v => om.passTupleToDownstream(rowWith(v), Some(portId))) + om.flush() + val byReceiver = sent.groupBy(_.channelId.toWorkerId) + // Both buckets got data, the local one as DataFrames and the remote one as ColumnarFrames. + assert(byReceiver.get(local).exists(_.nonEmpty)) + assert(byReceiver.get(remote).exists(_.nonEmpty)) + assert(byReceiver(local).forall(_.payload.isInstanceOf[DataFrame])) + assert(byReceiver(remote).forall(_.payload.isInstanceOf[ColumnarFrame])) + } + it should "decline when columnar output is off" in { val (om, sent) = capturingOutputManager() val portId = PortIdentity(22) From f6dc5fbf9139305734fcf99d7560462328229589 Mon Sep 17 00:00:00 2001 From: Matthew Ball Date: Sat, 14 Nov 2026 04:58:12 -0800 Subject: [PATCH 12/16] feat(engine): per-receiver columnar on a mixed-locality edge, no decode for remote buckets A shuffle whose receivers are split across the local node and remote nodes no longer gives up the columnar fast path for the whole edge. The output path now decides per receiver: a remote receiver gets its bucket as Arrow with no tuple decode, while a local receiver gets its bucket as rows (delivered by reference, which is free). Previously a mixed-locality edge fell back entirely to the row path, so the remote buckets paid a decode plus re-encode; now only the local buckets are decoded, and only their own rows. OutputManager: - tryEmitColumnarBatch takes the fast path when at least one receiver is remote-columnar (rather than requiring all of them). It still declines when no receiver is columnar (all local, or the wire is off) so the caller decodes once and uses the row path, and when the port needs storage or the schema does not match. - emitColumnarToLink sends each receiver its data in the right shape. For a one-to-one or broadcast edge it serializes the batch to Arrow once for the remote receivers and decodes it to rows once for the local ones. For a splitting shuffle it assigns buckets as before (through the same getBucketIndex the row path uses) and then, per bucket, calls sendBucket. - sendBucket ships a bucket as Arrow (gather + ColumnarFrame) when the receiver's buffer is columnar, or decodes just that bucket's rows (getTexeraTuple per row) and sends them as a DataFrame when it is local. NetworkOutputBuffer: - sendRows is the row counterpart of sendColumnarFrame: it flushes any buffered tuples, then ships a prebuilt DataFrame straight to the receiver, so a local receiver on a mixed edge gets rows in FIFO order alongside the Arrow sent to remote receivers. Tests: - OutputManagerSpec: on a mixed-locality hash shuffle the fast path ships DataFrames to the local receiver and ColumnarFrames to the remote one, and each receiver holds exactly the rows the row partitioner assigns, with nothing lost. The earlier all-local (declines) and fully-remote (fast path) cases still hold. --- .../messaginglayer/OutputManager.scala | 95 +++++++++++++------ .../partitioners/Partitioner.scala | 8 ++ .../messaginglayer/OutputManagerSpec.scala | 38 ++++++++ 3 files changed, 113 insertions(+), 28 deletions(-) diff --git a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManager.scala b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManager.scala index 3e0976e93a5..1f36d8fe9f6 100644 --- a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManager.scala +++ b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManager.scala @@ -216,19 +216,17 @@ class OutputManager( if (outputPortId.isEmpty && ports.size != 1) return None val portId = outputPortId.getOrElse(ports.head._1) val links = partitioners.filter(_._1.fromPortId == portId).toSeq - val eligible = - links.nonEmpty && - !outputPortResultWriterThreads.contains(portId) && - links.forall { - case (link, partitioner) => - // The no-decode fast path runs only when every receiver is remote-columnar. A - // local (or mixed) edge falls back to the row path, whose per-receiver flush - // already emits rows to local receivers and Arrow to remote ones. - partitioner.allReceivers.forall(r => - networkOutputBuffers.get((link, r)).exists(_.effectiveColumnar) - ) - } - if (!eligible) return None + // Take the no-decode fast path when at least one receiver is remote-columnar, so those + // receivers get Arrow with no tuple decode; any local receivers on the same edge get + // rows. If no receiver is columnar (all local, or the wire is off), fall back so the + // caller decodes the batch once and routes it through the row path. + val anyColumnar = links.exists { + case (link, partitioner) => + partitioner.allReceivers.exists(r => + networkOutputBuffers.get((link, r)).exists(_.effectiveColumnar) + ) + } + if (links.isEmpty || outputPortResultWriterThreads.contains(portId) || !anyColumnar) return None val schema = getPort(portId).schema // The executor's Arrow schema must match the declared output port schema; if not, // fall back so the row path's enforceSchema can adjust it. @@ -236,8 +234,10 @@ class OutputManager( Some((portId, links.map { case (link, p) => emitColumnarToLink(root, schema, link, p) }.sum)) } - // Ship `root` to one link's receivers in Arrow, splitting per bucket if the partitioner - // splits. Returns the total serialized bytes put on the wire for this link. + // Ship `root` to one link's receivers, splitting per bucket if the partitioner splits. + // Each receiver gets Arrow if its buffer is columnar (remote) or rows if it is local, so + // a mixed-locality edge keeps the remote buckets columnar while sending rows locally. + // Returns the total bytes accounted for this link (serialized Arrow + local row sizes). private def emitColumnarToLink( root: VectorSchemaRoot, schema: Schema, @@ -246,13 +246,26 @@ class OutputManager( ): Long = { val receivers = partitioner.allReceivers if (!partitioner.columnarSplits) { - // One-to-one / broadcast: the whole batch goes to each receiver; serialize once. - val bytes = ArrowUtils.serializeRoot(root) - val frame = ColumnarFrame(bytes, root.getRowCount, schema) - receivers.foreach(r => networkOutputBuffers((link, r)).sendColumnarFrame(frame)) - bytes.length.toLong + // One-to-one / broadcast: the whole batch goes to each receiver. Serialize to Arrow + // once for the remote receivers, decode to rows once for the local ones. + val (remote, local) = + receivers.partition(r => networkOutputBuffers((link, r)).effectiveColumnar) + var bytes = 0L + if (remote.nonEmpty) { + val arrow = ArrowUtils.serializeRoot(root) + val frame = ColumnarFrame(arrow, root.getRowCount, schema) + remote.foreach(r => networkOutputBuffers((link, r)).sendColumnarFrame(frame)) + bytes += arrow.length.toLong + } + if (local.nonEmpty) { + val tuples = ArrowUtils.tuplesOfRoot(root) + local.foreach(r => networkOutputBuffers((link, r)).sendRows(tuples)) + bytes += tuples.foldLeft(0L)(_ + _.inMemSize) + } + bytes } else { - // Splitting shuffle: assign each row a bucket, then gather and send per bucket. + // Splitting shuffle: assign each row a bucket, then send each bucket to its receiver + // as Arrow (remote) or rows (local). val n = root.getRowCount val rowsPerBucket = Array.fill(receivers.length)(new mutable.ArrayBuffer[Int]()) // Build only the columns getBucketIndex needs into a partial tuple per row. @@ -279,13 +292,12 @@ class OutputManager( while (b < receivers.length) { val rows = rowsPerBucket(b) if (rows.nonEmpty) { - val bucketRoot = ArrowUtils.gather(root, rows.toArray, columnarAllocator) - try { - val frameBytes = ArrowUtils.serializeRoot(bucketRoot) - networkOutputBuffers((link, receivers(b))) - .sendColumnarFrame(ColumnarFrame(frameBytes, rows.length, schema)) - bytes += frameBytes.length.toLong - } finally bucketRoot.close() + bytes += sendBucket( + root, + schema, + networkOutputBuffers((link, receivers(b))), + rows.toArray + ) } b += 1 } @@ -293,6 +305,33 @@ class OutputManager( } } + // Send one bucket's rows to a receiver: Arrow (gather + ColumnarFrame) if the buffer is + // columnar (remote), otherwise decode just those rows and send them as a DataFrame + // (local). Returns the bytes accounted for the send. + private def sendBucket( + root: VectorSchemaRoot, + schema: Schema, + buffer: NetworkOutputBuffer, + rows: Array[Int] + ): Long = { + if (buffer.effectiveColumnar) { + val bucketRoot = ArrowUtils.gather(root, rows, columnarAllocator) + try { + val frameBytes = ArrowUtils.serializeRoot(bucketRoot) + buffer.sendColumnarFrame(ColumnarFrame(frameBytes, rows.length, schema)) + frameBytes.length.toLong + } finally bucketRoot.close() + } else { + val tuples = new Array[Tuple](rows.length) + var k = 0 + while (k < rows.length) { + tuples(k) = ArrowUtils.getTexeraTuple(rows(k), root, schema); k += 1 + } + buffer.sendRows(tuples) + tuples.foldLeft(0L)(_ + _.inMemSize) + } + } + /** * Flushes the network output buffers based on the specified set of physical links. * diff --git a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/Partitioner.scala b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/Partitioner.scala index 3126d718f23..e4e2377d251 100644 --- a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/Partitioner.scala +++ b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/Partitioner.scala @@ -97,6 +97,14 @@ class NetworkOutputBuffer( dataOutputPort.sendTo(to, frame) } + // Row counterpart of sendColumnarFrame: ship a prebuilt row batch (a DataFrame) to a + // local receiver, flushing any buffered tuples first to keep FIFO order. Used when a + // mixed-locality edge sends Arrow to its remote receivers and rows to its local ones. + def sendRows(tuples: Array[Tuple]): Unit = { + flush() + if (tuples.nonEmpty) dataOutputPort.sendTo(to, DataFrame(tuples)) + } + def flush(): Unit = { if (buffer.nonEmpty) { val batch = buffer.toArray diff --git a/amber/src/test/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManagerSpec.scala b/amber/src/test/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManagerSpec.scala index 44957666a30..1e795cdcc5b 100644 --- a/amber/src/test/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManagerSpec.scala +++ b/amber/src/test/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManagerSpec.scala @@ -565,6 +565,44 @@ class OutputManagerSpec extends AnyFlatSpec with MockFactory { assert(byReceiver(remote).forall(_.payload.isInstanceOf[ColumnarFrame])) } + it should "in the fast path, ship Arrow to remote buckets and rows to local buckets on a mixed shuffle" in { + val local = ActorVirtualIdentity("c-local") + val remote = ActorVirtualIdentity("c-remote") + val (om, sent) = capturingOutputManager() + val portId = PortIdentity(44) + om.addPort(portId, schema, None) + val partitioning = + HashBasedShufflePartitioning(1000, Seq(channelTo(local), channelTo(remote)), Seq("field1")) + om.addPartitionerWithPartitioning( + PhysicalLink(physicalOpId(), portId, physicalOpId(), portId), + partitioning, + columnar = true + ) + om.isLocalReceiver = id => Some(id == local) + + val rows = (0 until 40).map(rowWith).toArray + assert(emitThrough(om, rows).isDefined) // a remote receiver is present, so the fast path runs + + val byReceiver = sent.groupBy(_.channelId.toWorkerId) + // The local bucket arrives as rows, the remote bucket as Arrow. + assert(byReceiver(local).forall(_.payload.isInstanceOf[DataFrame])) + assert(byReceiver(remote).forall(_.payload.isInstanceOf[ColumnarFrame])) + // Both buckets hold exactly the rows the row partitioner assigns, nothing lost. + val got: Map[ActorVirtualIdentity, List[Tuple]] = byReceiver.map { + case (r, msgs) => + r -> msgs.flatMap { + case m if m.payload.isInstanceOf[ColumnarFrame] => + ArrowUtils.deserializeTuples(m.payload.asInstanceOf[ColumnarFrame].arrowIpcBytes) + case m => m.payload.asInstanceOf[DataFrame].frame.toSeq + }.toList + } + val expected = + rowPathBuckets(HashBasedShufflePartitioner(partitioning), Seq(local, remote), rows) + assert(got.values.map(_.size).sum == rows.length) + assert(got.getOrElse(local, Nil) == expected.getOrElse(local, Nil)) + assert(got.getOrElse(remote, Nil) == expected.getOrElse(remote, Nil)) + } + it should "decline when columnar output is off" in { val (om, sent) = capturingOutputManager() val portId = PortIdentity(22) From 3e2aa96c4a165948a648ac9c7694041fc7d011e0 Mon Sep 17 00:00:00 2001 From: Matthew Ball Date: Sat, 14 Nov 2026 05:43:23 -0800 Subject: [PATCH 13/16] feat(operator): processColumnarRoot, the zero-copy Arrow consumption primitive Adds processColumnarRoot to the ColumnarOperatorExecutor contract: consume an already-decoded Arrow batch directly, with no IPC round-trip. This is the primitive a local (same-JVM) edge will use to hand an operator a live VectorSchemaRoot by reference, so the operator reads columns straight rather than through serialized bytes. The caller owns the root; the executor must not close it. The default serializes the root once and calls processColumnarBatch, so every columnar operator gets a correct implementation for free; filter, aggregate, and projection override it to read the root with no serialize at all. Contract (ColumnarOperatorExecutor): - processColumnarRoot(root, port) defaults to processColumnarBatch(serializeRoot(root), port). Operator overrides: - SpecializedFilterOpExec and AggregateOpExec factor their batch logic into a root-taking core (emitFiltered / accumulateRoot) that both the IPC path and the root path call; they only read the input root, so a foreign (caller-owned) root is safe. - ProjectionOpExec's projectRoot gains a moveBuffers flag. The IPC-decode path keeps the zero-copy buffer move (the decoded root shares the operator's allocator). The live-root path cannot move buffers, because Arrow forbids reassociating a buffer across allocator roots, so it copies each selected column into the output instead; the input root is left intact. Tests: - Each operator's spec asserts processColumnarRoot produces the same result as processColumnarBatch on the same input, built as a live root in a separate allocator (the cross-allocator case the live transport will exercise): the filter's Emit survivor count, the projection's projected schema and values, and the aggregate's grouped result all match. This is the consumption half of local zero-copy. The transport half, passing the live root across actors by reference, is deferred: checkpointing serializes in-flight data payloads, so a payload carrying a VectorSchemaRoot needs a dedicated Kryo serializer and a careful single-consumer allocator-ownership handoff, which should be designed and reviewed on its own rather than folded in here. --- .../executor/ColumnarOperatorExecutor.scala | 11 +++++ .../operator/aggregate/AggregateOpExec.scala | 7 +++ .../filter/SpecializedFilterOpExec.scala | 19 +++++--- .../projection/ProjectionOpExec.scala | 34 +++++++++++--- .../operator/aggregate/AggregateOpSpec.scala | 45 +++++++++++++++++++ .../filter/SelectionVectorFilterSpec.scala | 21 +++++++++ .../projection/ProjectionOpExecSpec.scala | 30 +++++++++++++ 7 files changed, 155 insertions(+), 12 deletions(-) diff --git a/common/workflow-core/src/main/scala/org/apache/texera/amber/core/executor/ColumnarOperatorExecutor.scala b/common/workflow-core/src/main/scala/org/apache/texera/amber/core/executor/ColumnarOperatorExecutor.scala index 853004b32e1..d597ccf4425 100644 --- a/common/workflow-core/src/main/scala/org/apache/texera/amber/core/executor/ColumnarOperatorExecutor.scala +++ b/common/workflow-core/src/main/scala/org/apache/texera/amber/core/executor/ColumnarOperatorExecutor.scala @@ -22,6 +22,7 @@ package org.apache.texera.amber.core.executor import org.apache.arrow.vector.VectorSchemaRoot import org.apache.texera.amber.core.tuple.TupleLike import org.apache.texera.amber.core.workflow.PortIdentity +import org.apache.texera.amber.util.ArrowUtils /** * Outcome of consuming one Arrow batch: @@ -49,4 +50,14 @@ object ColumnarResult { */ trait ColumnarOperatorExecutor { def processColumnarBatch(arrowIpcBytes: Array[Byte], port: Int): ColumnarResult + + /** + * Consume an already-decoded Arrow batch directly, with no IPC round-trip. This is the + * zero-copy consumption primitive a local (same-JVM) edge uses to hand an operator a + * live VectorSchemaRoot by reference. The caller owns the root (the executor must not + * close it). The default decodes nothing extra on the producer side but still pays one + * serialize; an operator overrides this to read the root straight (true zero-copy). + */ + def processColumnarRoot(root: VectorSchemaRoot, port: Int): ColumnarResult = + processColumnarBatch(ArrowUtils.serializeRoot(root), port) } diff --git a/common/workflow-operator/src/main/scala/org/apache/texera/amber/operator/aggregate/AggregateOpExec.scala b/common/workflow-operator/src/main/scala/org/apache/texera/amber/operator/aggregate/AggregateOpExec.scala index 16871ff8870..23d37cd7c60 100644 --- a/common/workflow-operator/src/main/scala/org/apache/texera/amber/operator/aggregate/AggregateOpExec.scala +++ b/common/workflow-operator/src/main/scala/org/apache/texera/amber/operator/aggregate/AggregateOpExec.scala @@ -155,6 +155,13 @@ class AggregateOpExec(descString: String) extends OperatorExecutor with Columnar ArrowUtils.deserializeRootFold(arrowIpcBytes, columnarAllocator)(accumulateRoot) } + // Zero-copy path: accumulate straight from the live root (no IPC decode). The caller + // owns `root`; accumulateRoot reads it and does not close it. + override def processColumnarRoot(root: VectorSchemaRoot, port: Int): ColumnarResult = { + if (columnarAllocator == null) columnarAllocator = new RootAllocator() + accumulateRoot(root) + } + override def onFinish(port: Int): Iterator[TupleLike] = { // Finalize aggregation for all keys and produce the result keyedPartialAggregates.iterator.map { diff --git a/common/workflow-operator/src/main/scala/org/apache/texera/amber/operator/filter/SpecializedFilterOpExec.scala b/common/workflow-operator/src/main/scala/org/apache/texera/amber/operator/filter/SpecializedFilterOpExec.scala index 32643cd73bc..6775b778da0 100644 --- a/common/workflow-operator/src/main/scala/org/apache/texera/amber/operator/filter/SpecializedFilterOpExec.scala +++ b/common/workflow-operator/src/main/scala/org/apache/texera/amber/operator/filter/SpecializedFilterOpExec.scala @@ -88,14 +88,21 @@ class SpecializedFilterOpExec(descString: String) override def processColumnarBatch(arrowIpcBytes: Array[Byte], port: Int): ColumnarResult = { if (columnarAllocator == null) columnarAllocator = new RootAllocator() - ArrowUtils.deserializeRootFold(arrowIpcBytes, columnarAllocator) { root => - columnarMask(root) match { - case Some(mask) => ColumnarResult.Emit(ArrowUtils.selectRows(root, mask, columnarAllocator)) - case None => ColumnarResult.Unsupported - } - } + ArrowUtils.deserializeRootFold(arrowIpcBytes, columnarAllocator)(emitFiltered) } + // Zero-copy path: read the live root directly (no IPC decode). The caller owns `root`. + override def processColumnarRoot(root: VectorSchemaRoot, port: Int): ColumnarResult = { + if (columnarAllocator == null) columnarAllocator = new RootAllocator() + emitFiltered(root) + } + + private def emitFiltered(root: VectorSchemaRoot): ColumnarResult = + columnarMask(root) match { + case Some(mask) => ColumnarResult.Emit(ArrowUtils.selectRows(root, mask, columnarAllocator)) + case None => ColumnarResult.Unsupported + } + // Selection-vector path: the indices of surviving rows, computed without // compacting or copying the batch. None when the predicate is not vectorizable. // For a fused consumer (count/aggregate) that reads the indices instead of a diff --git a/common/workflow-operator/src/main/scala/org/apache/texera/amber/operator/projection/ProjectionOpExec.scala b/common/workflow-operator/src/main/scala/org/apache/texera/amber/operator/projection/ProjectionOpExec.scala index 6b4da6cc32e..55c9bc0a808 100644 --- a/common/workflow-operator/src/main/scala/org/apache/texera/amber/operator/projection/ProjectionOpExec.scala +++ b/common/workflow-operator/src/main/scala/org/apache/texera/amber/operator/projection/ProjectionOpExec.scala @@ -80,12 +80,27 @@ class ProjectionOpExec( override def processColumnarBatch(arrowIpcBytes: Array[Byte], port: Int): ColumnarResult = { if (columnarAllocator == null) columnarAllocator = new RootAllocator() - ArrowUtils.deserializeRootFold(arrowIpcBytes, columnarAllocator)(projectRoot) + // The decoded root lives in this operator's allocator, so its buffers can be moved. + ArrowUtils.deserializeRootFold(arrowIpcBytes, columnarAllocator)( + projectRoot(_, moveBuffers = true) + ) + } + + // Local path: project the live root directly (no IPC decode). The selected columns are + // copied into a fresh output root (a foreign root's buffers cannot be moved), leaving + // `root` intact; the caller still owns and closes it. + override def processColumnarRoot(root: VectorSchemaRoot, port: Int): ColumnarResult = { + if (columnarAllocator == null) columnarAllocator = new RootAllocator() + // A foreign (caller-owned) root cannot have its buffers moved, so columns are copied. + projectRoot(root, moveBuffers = false) } // Resolve the (sourceColumn -> outputAlias) pairs exactly as project() does, then move - // each source column into a fresh output root under its alias. - private def projectRoot(root: VectorSchemaRoot): ColumnarResult = { + // each source column into a fresh output root under its alias. `moveBuffers` transfers + // the source buffers (a zero-copy move, valid only when `root` shares this operator's + // allocator, i.e. the IPC-decode path); otherwise each column is copied (a foreign live + // root does not share the allocator, and Arrow forbids moving a buffer across roots). + private def projectRoot(root: VectorSchemaRoot, moveBuffers: Boolean): ColumnarResult = { val inSchema = ArrowUtils.toTexeraSchema(root.getSchema) val units: List[(String, String)] = if (desc.isDrop) { @@ -113,13 +128,20 @@ class ProjectionOpExec( try ArrowUtils.projectionIndices(root, originals) catch { case _: Exception => return ColumnarResult.Unsupported } val outRoot = VectorSchemaRoot.create(ArrowUtils.fromTexeraSchema(outSchema), columnarAllocator) + val n = root.getRowCount var j = 0 while (j < units.size) { - // Move the source column's buffers into the output column (same Arrow type), renamed. - root.getVector(srcIdx(j)).makeTransferPair(outRoot.getVector(j)).transfer() + val src = root.getVector(srcIdx(j)) + val dest = outRoot.getVector(j) + if (moveBuffers) { + src.makeTransferPair(dest).transfer() // zero-copy move (same allocator), renamed + } else { + var r = 0 + while (r < n) { dest.copyFromSafe(r, r, src); r += 1 } // copy (foreign allocator) + } j += 1 } - outRoot.setRowCount(root.getRowCount) + outRoot.setRowCount(n) ColumnarResult.Emit(outRoot) } diff --git a/common/workflow-operator/src/test/scala/org/apache/texera/amber/operator/aggregate/AggregateOpSpec.scala b/common/workflow-operator/src/test/scala/org/apache/texera/amber/operator/aggregate/AggregateOpSpec.scala index 52fa9a757f5..d6937846430 100644 --- a/common/workflow-operator/src/test/scala/org/apache/texera/amber/operator/aggregate/AggregateOpSpec.scala +++ b/common/workflow-operator/src/test/scala/org/apache/texera/amber/operator/aggregate/AggregateOpSpec.scala @@ -766,4 +766,49 @@ class AggregateOpSpec extends AnyFunSuite { assert(colResult(city) == rowResult(city), s"group $city differs") } } + + test("processColumnarRoot accumulates a live root identically to processColumnarBatch") { + val schema = makeSchema("city" -> AttributeType.STRING, "sales" -> AttributeType.INTEGER) + val rows = Seq( + makeTuple(schema, "NY", 10), + makeTuple(schema, "SF", 20), + makeTuple(schema, "NY", 5), + makeTuple(schema, "SF", null) + ) + val desc = new AggregateOpDesc() + desc.aggregations = List( + makeAggregationOp(AggregationFunction.SUM, "sales", "sum_sales"), + makeAggregationOp(AggregationFunction.COUNT, "", "n_rows") + ) + desc.groupByKeys = List("city") + val descJson = objectMapper.writeValueAsString(desc) + + def resultsOf(feed: AggregateOpExec => Unit): Map[String, List[Any]] = { + val exec = new AggregateOpExec(descJson) + exec.open() + feed(exec) + val out = exec + .onFinish(0) + .toList + .map { t => + val f = t.getFields; f(0).asInstanceOf[String] -> f.drop(1).toList + } + .toMap + exec.close() + out + } + + val bytesResult = resultsOf(exec => + exec.processColumnarBatch(ArrowUtils.serializeTuples(schema, rows.toArray), 0) + ) + val rootResult = resultsOf { exec => + val alloc = new org.apache.arrow.memory.RootAllocator() + try { + ArrowUtils.deserializeRootFold(ArrowUtils.serializeTuples(schema, rows.toArray), alloc)( + exec.processColumnarRoot(_, 0) + ) + } finally alloc.close() + } + assert(rootResult == bytesResult) + } } diff --git a/common/workflow-operator/src/test/scala/org/apache/texera/amber/operator/filter/SelectionVectorFilterSpec.scala b/common/workflow-operator/src/test/scala/org/apache/texera/amber/operator/filter/SelectionVectorFilterSpec.scala index 516df12879c..4b7fd819912 100644 --- a/common/workflow-operator/src/test/scala/org/apache/texera/amber/operator/filter/SelectionVectorFilterSpec.scala +++ b/common/workflow-operator/src/test/scala/org/apache/texera/amber/operator/filter/SelectionVectorFilterSpec.scala @@ -19,6 +19,7 @@ package org.apache.texera.amber.operator.filter +import org.apache.arrow.memory.RootAllocator import org.apache.texera.amber.core.executor.ColumnarResult import org.apache.texera.amber.core.tuple.{Attribute, AttributeType, Schema, Tuple} import org.apache.texera.amber.util.ArrowUtils @@ -95,6 +96,26 @@ class SelectionVectorFilterSpec extends AnyFlatSpec { exec.close() } + "processColumnarRoot (zero-copy)" should "produce the same Emit as processColumnarBatch" in { + val rows = batch(5, 2000) + val bytes = ArrowUtils.serializeTuples(schema, rows) + val exec = execFor(("v", ComparisonType.GREATER_THAN, "30")) + exec.open() + val expected = rows.count(exec.filterFunc) + val alloc = new RootAllocator() + try { + ArrowUtils.deserializeRootFold(bytes, alloc) { root => + exec.processColumnarRoot(root, 0) match { + case ColumnarResult.Emit(out) => + assert(out.getRowCount == expected) + out.close() + case other => fail(s"expected Emit, got $other") + } + } + } finally alloc.close() + exec.close() + } + "gather from a selection" should "yield the same rows as the row path" in { val rows = batch(4, 1500) val bytes = ArrowUtils.serializeTuples(schema, rows) diff --git a/common/workflow-operator/src/test/scala/org/apache/texera/amber/operator/projection/ProjectionOpExecSpec.scala b/common/workflow-operator/src/test/scala/org/apache/texera/amber/operator/projection/ProjectionOpExecSpec.scala index cf793cf4cd2..f5cc4425647 100644 --- a/common/workflow-operator/src/test/scala/org/apache/texera/amber/operator/projection/ProjectionOpExecSpec.scala +++ b/common/workflow-operator/src/test/scala/org/apache/texera/amber/operator/projection/ProjectionOpExecSpec.scala @@ -338,6 +338,36 @@ class ProjectionOpExecSpec extends AnyFlatSpec with BeforeAndAfter { exec.close() } + it should "project a live root (zero-copy) identically to processColumnarBatch" in { + opDesc.isDrop = false + opDesc.attributes = List(new AttributeUnit("field2", "f2"), new AttributeUnit("field1", "f1")) + val exec = new ProjectionOpExec(objectMapper.writeValueAsString(opDesc)) + exec.open() + val rows = Array(tuple, tuple2) + val viaBytes = columnarProject(exec, rows) + val alloc = new org.apache.arrow.memory.RootAllocator() + val viaRoot = + try { + ArrowUtils.deserializeRootFold(ArrowUtils.serializeTuples(tupleSchema, rows), alloc) { + root => + exec.processColumnarRoot(root, 0) match { + case ColumnarResult.Emit(out) => + try ArrowUtils.tuplesOfRoot(out) + finally out.close() + case other => fail(s"expected Emit, got: $other") + } + } + } finally alloc.close() + assert(viaRoot.length == viaBytes.length) + viaRoot.zip(viaBytes).foreach { + case (r, b) => + assert(r.getSchema == b.getSchema) + assert(r.getField[Any]("f1") == b.getField[Any]("f1")) + assert(r.getField[Any]("f2") == b.getField[Any]("f2")) + } + exec.close() + } + it should "fall back to the row path (Unsupported) on a duplicate alias" in { opDesc.isDrop = false opDesc.attributes = List(new AttributeUnit("field1", "f"), new AttributeUnit("field2", "f")) From 8ef3980250d07475eca66897ea64b750a0251434 Mon Sep 17 00:00:00 2001 From: Matthew Ball Date: Mon, 16 Nov 2026 14:55:36 -0800 Subject: [PATCH 14/16] feat(engine): local zero-copy wire, hand a live Arrow root to a co-located receiver A single-consumer edge to a co-located, columnar-capable operator now hands the receiver the operator's Arrow result root by reference, with no serialization at all. The sender neither serializes to bytes nor decodes to rows; the receiver consumes the columns straight through processColumnarRoot. This is the local counterpart of the columnar wire: a remote hop still ships Arrow bytes (ColumnarFrame) and a non-columnar or multi-consumer local hop still ships rows, but a local columnar chain (scan, filter, aggregate in one JVM) now flows as live roots end to end. New payload (LocalColumnarBatch): - Carries a live VectorSchemaRoot, its row count, and schema. Ownership transfers to the receiver, which closes the root after consuming it. Because a checkpoint of an in-flight batch would serialize it and a VectorSchemaRoot is not serializable, a custom Kryo serializer (AmberKryoInitializer) converts it to and from Arrow IPC bytes, so an accidental serialization stays correct, losing only the zero-copy property. ArrowUtils.deserializeRootOwned rebuilds an owned (not auto-closed) root from those bytes, and ArrowUtils.sharedAllocator backs the rebuilt root. Send side (OutputManager, NetworkOutputBuffer): - tryEmitLocalColumnarRoot hands the root off only in the one shape where ownership is unambiguous: the output port has a single one-to-one edge whose single receiver is known-local and columnar-capable, needs no storage, and matches the schema, so exactly one consumer receives the root. Every other shape returns None. NetworkOutputBuffer.sendLocalColumnar ships the batch after flushing any buffered tuples, keeping FIFO order. Worker (DataProcessor): - The Arrow result of any operator now goes out through a shared emitProducedRoot, which tries the local live-root handoff first, then the remote Arrow bytes, then decoded rows; it closes the produced root unless it was handed off live. A LocalColumnarBatch input is consumed by processLocalColumnarRoot: a columnar executor reads the root via processColumnarRoot (no IPC decode), any other operator or a decline decodes it to tuples, and the receiver closes the handed-off root in a finally either way. The two columnar input paths share routeConsumedResult for the natively-consumed tail. Scope and safety: the live handoff is restricted to a single local consumer so no two receivers can close the same root; unknown locality is treated as remote (never a live root); the Kryo serializer makes checkpointing correct; and the receiver owns and frees the root. Tests: - LocalColumnarBatchSerdeSpec round-trips a batch through the real Pekko/Kryo stack and gets the same rows back (the checkpoint path). OutputManagerSpec covers tryEmitLocalColumnarRoot: a local one-to-one columnar receiver gets a LocalColumnarBatch, while a remote receiver, a non-columnar receiver, and a splitting shuffle are all declined. DataProcessorSpec feeds a live root to a columnar operator, asserts it is consumed via processColumnarRoot (not the row path), and asserts the receiver freed the root (the input allocator returns to zero). --- .../messaginglayer/OutputManager.scala | 35 +++++- .../partitioners/Partitioner.scala | 14 ++- .../architecture/worker/DataProcessor.scala | 117 +++++++++++++----- .../engine/common/AmberKryoInitializer.scala | 36 ++++++ .../common/ambermessage/DataPayload.scala | 22 ++++ .../messaginglayer/OutputManagerSpec.scala | 88 +++++++++++++ .../worker/DataProcessorSpec.scala | 36 +++++- .../LocalColumnarBatchSerdeSpec.scala | 81 ++++++++++++ .../apache/texera/amber/util/ArrowUtils.scala | 26 ++++ 9 files changed, 420 insertions(+), 35 deletions(-) create mode 100644 amber/src/test/scala/org/apache/texera/amber/engine/common/ambermessage/LocalColumnarBatchSerdeSpec.scala diff --git a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManager.scala b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManager.scala index 1f36d8fe9f6..ed502ebb987 100644 --- a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManager.scala +++ b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManager.scala @@ -37,7 +37,7 @@ import org.apache.texera.amber.engine.architecture.worker.managers.{ PortStorageWriterTerminateSignal } import org.apache.texera.amber.engine.common.AmberLogging -import org.apache.texera.amber.engine.common.ambermessage.ColumnarFrame +import org.apache.texera.amber.engine.common.ambermessage.{ColumnarFrame, LocalColumnarBatch} import org.apache.texera.amber.util.{ArrowUtils, VirtualIdentityUtils} import org.apache.arrow.memory.{BufferAllocator, RootAllocator} import org.apache.arrow.vector.VectorSchemaRoot @@ -209,6 +209,39 @@ class OutputManager( * @return Some((portId, totalSerializedByteCount)) if it shipped the batch (caller * records output statistics), or None if the port is not eligible (fall back). */ + /** + * Local zero-copy fast path: hand the operator's Arrow result root to a co-located + * receiver by reference, with no serialization. Ownership transfers to the receiver (it + * closes the root), so on success the caller must NOT close it. Eligible only for the + * simplest single-consumer shape: the port has one one-to-one edge whose single receiver + * is known-local and columnar-capable, needs no storage, and whose schema matches, so the + * root goes to exactly one consumer. Every other shape returns None (the caller tries the + * remote columnar path, then rows). + * + * @return Some((portId, rootInMemSize)) if the root was handed off, else None. + */ + def tryEmitLocalColumnarRoot( + root: VectorSchemaRoot, + outputPortId: Option[PortIdentity] + ): Option[(PortIdentity, Long)] = { + if (outputPortId.isEmpty && ports.size != 1) return None + val portId = outputPortId.getOrElse(ports.head._1) + if (outputPortResultWriterThreads.contains(portId)) return None + val links = partitioners.filter(_._1.fromPortId == portId).toSeq + if (links.size != 1) return None + val (link, partitioner) = links.head + val receivers = partitioner.allReceivers + if (receivers.size != 1) return None + val buffer = networkOutputBuffers((link, receivers.head)) + // Receiver must be columnar-capable (planner flag) and known-local. + if (!buffer.columnar || !buffer.localityCheck().contains(true)) return None + val schema = getPort(portId).schema + if (ArrowUtils.toTexeraSchema(root.getSchema) != schema) return None + val batch = LocalColumnarBatch(root, root.getRowCount, schema) + buffer.sendLocalColumnar(batch) + Some((portId, batch.inMemSize)) + } + def tryEmitColumnarBatch( root: VectorSchemaRoot, outputPortId: Option[PortIdentity] diff --git a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/Partitioner.scala b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/Partitioner.scala index e4e2377d251..fb520b4ccc0 100644 --- a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/Partitioner.scala +++ b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/Partitioner.scala @@ -24,7 +24,12 @@ import org.apache.texera.amber.core.state.State import org.apache.texera.amber.core.tuple.Tuple import org.apache.texera.amber.core.virtualidentity.ActorVirtualIdentity import org.apache.texera.amber.engine.architecture.messaginglayer.NetworkOutputGateway -import org.apache.texera.amber.engine.common.ambermessage.{ColumnarFrame, DataFrame, StateFrame} +import org.apache.texera.amber.engine.common.ambermessage.{ + ColumnarFrame, + DataFrame, + LocalColumnarBatch, + StateFrame +} import org.apache.texera.amber.util.ArrowUtils import scala.collection.mutable.ArrayBuffer @@ -105,6 +110,13 @@ class NetworkOutputBuffer( if (tuples.nonEmpty) dataOutputPort.sendTo(to, DataFrame(tuples)) } + // Local zero-copy: hand the receiver a live Arrow root by reference (no serialization). + // Ownership transfers to the receiver; the sender must not touch the root after this. + def sendLocalColumnar(batch: LocalColumnarBatch): Unit = { + flush() + dataOutputPort.sendTo(to, batch) + } + def flush(): Unit = { if (buffer.nonEmpty) { val batch = buffer.toArray diff --git a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/worker/DataProcessor.scala b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/worker/DataProcessor.scala index 031caf20bc7..9b2c23af0cd 100644 --- a/amber/src/main/scala/org/apache/texera/amber/engine/architecture/worker/DataProcessor.scala +++ b/amber/src/main/scala/org/apache/texera/amber/engine/architecture/worker/DataProcessor.scala @@ -64,6 +64,7 @@ import org.apache.texera.amber.engine.common.statetransition.WorkerStateManager import org.apache.texera.amber.engine.common.virtualidentity.util.COORDINATOR import org.apache.texera.amber.error.ErrorUtils.{mkConsoleMessage, mkPrintConsoleMessage, safely} import org.apache.texera.amber.util.ArrowUtils +import org.apache.arrow.vector.VectorSchemaRoot import java.util.concurrent.LinkedBlockingQueue @@ -175,42 +176,94 @@ class DataProcessor( // The executor declined this batch: fall back to the row path. startInputBatch(channelId, ArrowUtils.deserializeTuples(arrowIpcBytes)) case consumed => - // Consumed natively: no per-tuple input remains for the DP loop to drain. - // Report the whole batch's input statistics in one call. - inputManager.initBatch(channelId, Array.empty) - statisticsManager.increaseInputStatistics( - portId, - rowCount.toLong, - arrowIpcBytes.length.toLong - ) - consumed match { - case ColumnarResult.EmitRows(rows) => - outputManager.outputIterator.setTupleOutput(rows) - case ColumnarResult.Emit(root) => - try { - val rowCount = root.getRowCount - // No round-trip: on an eligible (one-to-one, no-storage, columnar) - // edge, ship the Arrow batch straight downstream. Otherwise - // materialize it to output tuples (the row output path) and let the - // network buffer handle it. - outputManager.tryEmitColumnarBatch(root, None) match { - case Some((portId, byteCount)) => - statisticsManager.increaseOutputStatistics(portId, rowCount.toLong, byteCount) - case None => - val tuples = ArrowUtils.tuplesOfRoot(root) - outputManager.outputIterator.setTupleOutput( - tuples.iterator.map(t => (t: TupleLike, None: Option[PortIdentity])) - ) - } - } finally root.close() - case _ => // Consumed: a blocking operator accumulated the batch, nothing to emit now - } + routeConsumedResult(channelId, portId, rowCount, arrowIpcBytes.length.toLong, consumed) } } catch safely { case e => handleExecutorException(e) } } + // Local zero-copy wire: a live Arrow root arrived by reference (no serialization). This + // worker owns the root and closes it here. A ColumnarOperatorExecutor consumes it + // directly via processColumnarRoot (no IPC decode); any other operator, or a decline, + // decodes it to tuples. Mirrors processColumnarFrame, but the input is a live root. + private[this] def processLocalColumnarRoot( + channelId: ChannelIdentity, + portId: PortIdentity, + root: VectorSchemaRoot, + rowCount: Int, + inMemSize: Long + ): Unit = { + val columnarExecutor = executor match { + case c: ColumnarOperatorExecutor => c + case _ => null + } + try { + if (columnarExecutor == null) { + startInputBatch(channelId, ArrowUtils.tuplesOfRoot(root)) + } else { + transitToRunning() + inputManager.currentChannelId = channelId + bindStateReferences() + try { + columnarExecutor.processColumnarRoot(root, portId.id) match { + case ColumnarResult.Unsupported => + startInputBatch(channelId, ArrowUtils.tuplesOfRoot(root)) + case consumed => + routeConsumedResult(channelId, portId, rowCount, inMemSize, consumed) + } + } catch safely { + case e => handleExecutorException(e) + } + } + } finally root.close() // the receiver owns the handed-off root + } + + // Shared tail of the two columnar input paths for a natively-consumed batch: the DP loop + // has no per-tuple input to drain, so count the whole batch's input statistics once, then + // route the result. Emit ships a produced root downstream; EmitRows installs rows; + // Consumed (a blocking operator) emits nothing now. + private[this] def routeConsumedResult( + channelId: ChannelIdentity, + portId: PortIdentity, + rowCount: Int, + inputByteSize: Long, + consumed: ColumnarResult + ): Unit = { + inputManager.initBatch(channelId, Array.empty) + statisticsManager.increaseInputStatistics(portId, rowCount.toLong, inputByteSize) + consumed match { + case ColumnarResult.EmitRows(rows) => outputManager.outputIterator.setTupleOutput(rows) + case ColumnarResult.Emit(root) => emitProducedRoot(root) + case _ => // Consumed: a blocking operator accumulated the batch + } + } + + // Ship an operator-produced Arrow result root downstream in the cheapest shape the edge + // allows: a live root by reference to a local receiver (ownership transfers, so the root + // is NOT closed here), Arrow bytes to a remote one, or decoded tuples (the row path). + private[this] def emitProducedRoot(outRoot: VectorSchemaRoot): Unit = { + var retained = false + try { + val rc = outRoot.getRowCount + outputManager.tryEmitLocalColumnarRoot(outRoot, None) match { + case Some((pid, sz)) => + retained = true + statisticsManager.increaseOutputStatistics(pid, rc.toLong, sz) + case None => + outputManager.tryEmitColumnarBatch(outRoot, None) match { + case Some((pid, bytes)) => + statisticsManager.increaseOutputStatistics(pid, rc.toLong, bytes) + case None => + val tuples = ArrowUtils.tuplesOfRoot(outRoot) + outputManager.outputIterator.setTupleOutput( + tuples.iterator.map(t => (t: TupleLike, None: Option[PortIdentity])) + ) + } + } + } finally if (!retained) outRoot.close() + } + private[this] def processInputTuple(tuple: Tuple): Unit = { try { val portIdentity: PortIdentity = @@ -347,6 +400,10 @@ class DataProcessor( // decode); any other operator, or one that declines the batch, decodes it // back to tuples and processes it exactly as a DataFrame. processColumnarFrame(channelId, portId, arrowIpcBytes, rowCount) + case batch: LocalColumnarBatch => + // Local zero-copy wire: a live Arrow root arrived by reference from a co-located + // sender. This worker owns and closes it. + processLocalColumnarRoot(channelId, portId, batch.root, batch.rowCount, batch.inMemSize) case StateFrame(state, loopCounter, loopStartId) => processInputState(state, portId.id, loopCounter, loopStartId) } diff --git a/amber/src/main/scala/org/apache/texera/amber/engine/common/AmberKryoInitializer.scala b/amber/src/main/scala/org/apache/texera/amber/engine/common/AmberKryoInitializer.scala index 1721764d414..a6ea0f6aca0 100644 --- a/amber/src/main/scala/org/apache/texera/amber/engine/common/AmberKryoInitializer.scala +++ b/amber/src/main/scala/org/apache/texera/amber/engine/common/AmberKryoInitializer.scala @@ -19,9 +19,14 @@ package org.apache.texera.amber.engine.common +import com.esotericsoftware.kryo.kryo5.io.{Input, Output} import com.esotericsoftware.kryo.kryo5.serializers.ClosureSerializer +import com.esotericsoftware.kryo.kryo5.{Kryo, Serializer => Kryo5Serializer} import io.altoo.serialization.kryo.pekko.DefaultKryoInitializer import io.altoo.serialization.kryo.scala.serializer.ScalaKryo +import org.apache.texera.amber.core.tuple.Schema +import org.apache.texera.amber.engine.common.ambermessage.LocalColumnarBatch +import org.apache.texera.amber.util.ArrowUtils import java.lang.invoke.SerializedLambda @@ -29,5 +34,36 @@ class AmberKryoInitializer extends DefaultKryoInitializer { override def preInit(kryo: ScalaKryo): Unit = { kryo.register(classOf[SerializedLambda]) kryo.register(classOf[ClosureSerializer.Closure], new ClosureSerializer()) + // A LocalColumnarBatch normally travels in-JVM by reference and never serializes, but a + // checkpoint of an in-flight batch would. Its live VectorSchemaRoot is not serializable, + // so convert it to/from Arrow IPC bytes here: correct, just no longer zero-copy. The + // rebuilt root is owned by whoever consumes the batch (it closes it). + kryo.register(classOf[LocalColumnarBatch], new LocalColumnarBatchSerializer()) + } +} + +private class LocalColumnarBatchSerializer extends Kryo5Serializer[LocalColumnarBatch] { + override def write(kryo: Kryo, output: Output, batch: LocalColumnarBatch): Unit = { + val bytes = ArrowUtils.serializeRoot(batch.root) + output.writeInt(batch.rowCount) + kryo.writeObject(output, batch.schema) + output.writeInt(bytes.length) + output.writeBytes(bytes) + } + + override def read( + kryo: Kryo, + input: Input, + tpe: Class[_ <: LocalColumnarBatch] + ): LocalColumnarBatch = { + val rowCount = input.readInt() + val schema = kryo.readObject(input, classOf[Schema]) + val len = input.readInt() + val bytes = input.readBytes(len) + LocalColumnarBatch( + ArrowUtils.deserializeRootOwned(bytes, ArrowUtils.sharedAllocator), + rowCount, + schema + ) } } diff --git a/amber/src/main/scala/org/apache/texera/amber/engine/common/ambermessage/DataPayload.scala b/amber/src/main/scala/org/apache/texera/amber/engine/common/ambermessage/DataPayload.scala index bc767c38b1a..ba68d636a17 100644 --- a/amber/src/main/scala/org/apache/texera/amber/engine/common/ambermessage/DataPayload.scala +++ b/amber/src/main/scala/org/apache/texera/amber/engine/common/ambermessage/DataPayload.scala @@ -19,6 +19,7 @@ package org.apache.texera.amber.engine.common.ambermessage +import org.apache.arrow.vector.VectorSchemaRoot import org.apache.texera.amber.core.state.State import org.apache.texera.amber.core.tuple.{Schema, Tuple} @@ -50,6 +51,27 @@ final case class ColumnarFrame(arrowIpcBytes: Array[Byte], rowCount: Int, schema val inMemSize: Long = arrowIpcBytes.length.toLong } +/** + * A batch handed to a co-located (same-JVM) receiver as a LIVE Arrow root, by reference, + * with no serialization at all: the local zero-copy wire. Ownership transfers to the + * receiver, which closes `root` after consuming it (via processColumnarRoot); the sender + * must not touch it after sending. Produced only for a single-consumer local columnar + * edge; a remote hop uses `ColumnarFrame` and a non-columnar receiver uses `DataFrame`. + * A custom Kryo serializer (AmberKryoInitializer) converts it to/from Arrow IPC bytes so + * an accidental serialization (e.g. a checkpoint of an in-flight batch) stays correct, + * losing only the zero-copy property. + */ +final case class LocalColumnarBatch(root: VectorSchemaRoot, rowCount: Int, schema: Schema) + extends DataPayload { + val inMemSize: Long = { + val vecs = root.getFieldVectors + var sum = 0L + var i = 0 + while (i < vecs.size) { sum += vecs.get(i).getBufferSize.toLong; i += 1 } + sum + } +} + final case class DataFrame(frame: Array[Tuple]) extends DataPayload { val inMemSize: Long = { frame.map(_.inMemSize).sum diff --git a/amber/src/test/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManagerSpec.scala b/amber/src/test/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManagerSpec.scala index 1e795cdcc5b..afa13d252a1 100644 --- a/amber/src/test/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManagerSpec.scala +++ b/amber/src/test/scala/org/apache/texera/amber/engine/architecture/messaginglayer/OutputManagerSpec.scala @@ -644,6 +644,94 @@ class OutputManagerSpec extends AnyFlatSpec with MockFactory { assert(sent.head.payload.isInstanceOf[DataFrame]) } + // -- tryEmitLocalColumnarRoot (phase 5b: local zero-copy, live root by reference) ----- + + // Build an owned root the test manages (deserializeRootFold would close it), run the + // live-emit, and clean up. Returns the result and the captured messages. + private def liveEmit( + om: OutputManager, + sent: ArrayBuffer[WorkflowFIFOMessage], + rows: Array[Tuple] + )(check: (Option[(PortIdentity, Long)], ArrayBuffer[WorkflowFIFOMessage]) => Unit): Unit = { + val alloc = new RootAllocator() + val root = + ArrowUtils.deserializeRootOwned(ArrowUtils.serializeTuples(schema, rows), alloc) + try check(om.tryEmitLocalColumnarRoot(root, None), sent) + finally { root.close(); alloc.close() } + } + + private def oneToOneCapable( + om: OutputManager, + portId: PortIdentity, + rec: ActorVirtualIdentity + ): Unit = { + om.addPort(portId, schema, None) + om.addPartitionerWithPartitioning( + PhysicalLink(physicalOpId(), portId, physicalOpId(), portId), + OneToOnePartitioning(1000, Seq(channelTo(rec))), + columnar = true + ) + } + + "tryEmitLocalColumnarRoot" should "hand a live root to a local one-to-one columnar receiver" in { + val (om, sent) = capturingOutputManager() + val rec = ActorVirtualIdentity("live-rec") + oneToOneCapable(om, PortIdentity(50), rec) + om.isLocalReceiver = _ => Some(true) + liveEmit(om, sent, (0 until 10).map(rowWith).toArray) { (res, msgs) => + assert(res.exists(_._1 == PortIdentity(50))) + assert(msgs.size == 1) + val batch = msgs.head.payload.asInstanceOf[LocalColumnarBatch] + assert(batch.rowCount == 10) + assert(ArrowUtils.tuplesOfRoot(batch.root).length == 10) + } + } + + it should "decline a remote receiver (that hop serializes, so it is not zero-copy)" in { + val (om, sent) = capturingOutputManager() + oneToOneCapable(om, PortIdentity(51), ActorVirtualIdentity("remote-rec")) + om.isLocalReceiver = _ => Some(false) + liveEmit(om, sent, Array(sampleTuple())) { (res, msgs) => + assert(res.isEmpty) + assert(msgs.isEmpty) + } + } + + it should "decline when the receiver is not columnar-capable" in { + val (om, sent) = capturingOutputManager() + val rec = ActorVirtualIdentity("local-rowonly") + om.addPort(PortIdentity(52), schema, None) + om.addPartitionerWithPartitioning( + PhysicalLink(physicalOpId(), PortIdentity(52), physicalOpId(), PortIdentity(52)), + OneToOnePartitioning(1000, Seq(channelTo(rec))) + // columnar defaults to false: receiver cannot consume columns + ) + om.isLocalReceiver = _ => Some(true) + liveEmit(om, sent, Array(sampleTuple())) { (res, msgs) => + assert(res.isEmpty) + assert(msgs.isEmpty) + } + } + + it should "decline a splitting shuffle (more than one consumer)" in { + val (om, sent) = capturingOutputManager() + om.addPort(PortIdentity(53), schema, None) + om.addPartitionerWithPartitioning( + PhysicalLink(physicalOpId(), PortIdentity(53), physicalOpId(), PortIdentity(53)), + HashBasedShufflePartitioning( + 1000, + Seq(channelTo(ActorVirtualIdentity("a")), channelTo(ActorVirtualIdentity("b"))), + Seq("field1") + ), + columnar = true + ) + om.isLocalReceiver = _ => Some(true) + liveEmit(om, sent, Array(sampleTuple())) { (res, msgs) => + assert(res.isEmpty) + assert(msgs.isEmpty) + } + } + "getSingleOutputPortIdentity" should "return the sole port when exactly one is present" in { val outputManager: OutputManager = wire[OutputManager] val portId = PortIdentity(13) diff --git a/amber/src/test/scala/org/apache/texera/amber/engine/architecture/worker/DataProcessorSpec.scala b/amber/src/test/scala/org/apache/texera/amber/engine/architecture/worker/DataProcessorSpec.scala index a40052bb095..a343166e89f 100644 --- a/amber/src/test/scala/org/apache/texera/amber/engine/architecture/worker/DataProcessorSpec.scala +++ b/amber/src/test/scala/org/apache/texera/amber/engine/architecture/worker/DataProcessorSpec.scala @@ -61,6 +61,7 @@ import org.apache.texera.amber.engine.architecture.worker.statistics.WorkerState import org.apache.texera.amber.engine.common.ambermessage.{ ColumnarFrame, DataFrame, + LocalColumnarBatch, StateFrame, WorkflowFIFOMessage } @@ -862,6 +863,25 @@ class DataProcessorSpec extends AnyFlatSpec with MockFactory with Matchers with assert(exec.columnarCalls == 1) } + "data processor" should "consume a local live root via processColumnarRoot and free it" in { + val exec = new DataProcessorSpec.EmitAllColumnarExec + val (dp, sent) = columnarSetup(exec) + dp.outputManager.setColumnarOutput(true) + val alloc = new RootAllocator() + val root = + ArrowUtils.deserializeRootOwned(ArrowUtils.serializeTuples(schema, columnarBatch), alloc) + dp.processDataPayload(senderChannel, LocalColumnarBatch(root, columnarBatch.length, schema)) + drain(dp) + // The executor consumed the live root natively (processColumnarRoot, not processTuple), + // and the received root was closed by the receiver (the allocator is back to zero). + assert(exec.columnarRootCalls == 1) + assert(exec.processTupleCalls == 0) + assert(dp.statisticsManager.getInputTupleCount == columnarBatch.length.toLong) + assert(alloc.getAllocatedMemory == 0L, "the received live root must be freed by the receiver") + alloc.close() + exec.close() + } + "data processor" should "decode a ColumnarFrame to tuples for a non-columnar operator" in { val exec = new DataProcessorSpec.RowOnlyExec val (dp, sent) = columnarSetup(exec) @@ -889,13 +909,23 @@ object DataProcessorSpec { /** Consumes the Arrow batch and emits every row back (a pass-through filter). */ class EmitAllColumnarExec extends EchoingExec with ColumnarOperatorExecutor { var columnarCalls = 0 + var columnarRootCalls = 0 private val alloc = new RootAllocator() override def processColumnarBatch(arrowIpcBytes: Array[Byte], port: Int): ColumnarResult = { columnarCalls += 1 - ArrowUtils.deserializeRootFold(arrowIpcBytes, alloc) { root => - ColumnarResult.Emit(ArrowUtils.selectRows(root, Array.fill(root.getRowCount)(true), alloc)) - } + ArrowUtils.deserializeRootFold(arrowIpcBytes, alloc)(emitAll) + } + // Zero-copy path: read the live root directly (selectRows copies, so the foreign root + // is only read, not freed). + override def processColumnarRoot( + root: org.apache.arrow.vector.VectorSchemaRoot, + port: Int + ): ColumnarResult = { + columnarRootCalls += 1 + emitAll(root) } + private def emitAll(root: org.apache.arrow.vector.VectorSchemaRoot): ColumnarResult = + ColumnarResult.Emit(ArrowUtils.selectRows(root, Array.fill(root.getRowCount)(true), alloc)) override def close(): Unit = alloc.close() } diff --git a/amber/src/test/scala/org/apache/texera/amber/engine/common/ambermessage/LocalColumnarBatchSerdeSpec.scala b/amber/src/test/scala/org/apache/texera/amber/engine/common/ambermessage/LocalColumnarBatchSerdeSpec.scala new file mode 100644 index 00000000000..6f8037d0df4 --- /dev/null +++ b/amber/src/test/scala/org/apache/texera/amber/engine/common/ambermessage/LocalColumnarBatchSerdeSpec.scala @@ -0,0 +1,81 @@ +/* + * 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. + */ + +package org.apache.texera.amber.engine.common.ambermessage + +import org.apache.pekko.actor.ActorSystem +import org.apache.pekko.serialization.SerializationExtension +import org.apache.pekko.testkit.TestKit +import org.apache.texera.amber.core.tuple.{Attribute, AttributeType, Schema, Tuple} +import org.apache.texera.amber.engine.common.AmberRuntime +import org.apache.texera.amber.util.ArrowUtils +import org.scalatest.BeforeAndAfterAll +import org.scalatest.flatspec.AnyFlatSpecLike + +/** + * A LocalColumnarBatch carries a live, non-serializable VectorSchemaRoot. In-JVM it is + * passed by reference and never serialized, but a checkpoint of an in-flight batch would + * serialize it, so the custom Kryo serializer (AmberKryoInitializer) must convert it to + * Arrow bytes and back correctly. These run it through the real Pekko/Kryo stack. + */ +class LocalColumnarBatchSerdeSpec + extends TestKit(ActorSystem("LocalColumnarBatchSerde", AmberRuntime.pekkoConfig)) + with AnyFlatSpecLike + with BeforeAndAfterAll { + + private val serde = SerializationExtension(system) + private val schema: Schema = + Schema( + List(new Attribute("k", AttributeType.INTEGER), new Attribute("v", AttributeType.STRING)) + ) + + private def rows: Array[Tuple] = + (0 until 50) + .map(i => Tuple.builder(schema).addSequentially(Array[Any](Int.box(i), s"row-$i")).build()) + .toArray + + "a LocalColumnarBatch" should "survive Pekko/Kryo serialization as the same rows" in { + val original = rows + val root = ArrowUtils.deserializeRootOwned( + ArrowUtils.serializeTuples(schema, original), + ArrowUtils.sharedAllocator + ) + val batch = LocalColumnarBatch(root, root.getRowCount, schema) + + val wire = serde.serialize(batch).get + val restored = serde.deserialize(wire, classOf[LocalColumnarBatch]).get + + assert(restored.rowCount == original.length) + assert(restored.schema == schema) + val decoded = ArrowUtils.tuplesOfRoot(restored.root) + assert(decoded.length == original.length) + decoded.zip(original).foreach { + case (got, exp) => + assert(got.getField[Any]("k") == exp.getField[Any]("k")) + assert(got.getField[Any]("v") == exp.getField[Any]("v")) + } + root.close() + restored.root.close() + } + + override def afterAll(): Unit = { + TestKit.shutdownActorSystem(system) + super.afterAll() + } +} diff --git a/common/workflow-core/src/main/scala/org/apache/texera/amber/util/ArrowUtils.scala b/common/workflow-core/src/main/scala/org/apache/texera/amber/util/ArrowUtils.scala index ccd04c7e4f7..6c28e747ec9 100644 --- a/common/workflow-core/src/main/scala/org/apache/texera/amber/util/ArrowUtils.scala +++ b/common/workflow-core/src/main/scala/org/apache/texera/amber/util/ArrowUtils.scala @@ -56,6 +56,10 @@ object ArrowUtils extends LazyLogging { // Create a single allocator for the entire utility private val allocator: BufferAllocator = new RootAllocator() + // The shared utility allocator, for callers that must decode into a long-lived owned root + // (e.g. rebuilding a LocalColumnarBatch after deserialization). + def sharedAllocator: BufferAllocator = allocator + implicit def bool2int(b: Boolean): Int = if (b) 1 else 0 // Serialize a VectorSchemaRoot to Arrow IPC stream bytes. Does not close root. @@ -130,6 +134,28 @@ object ArrowUtils extends LazyLogging { } finally reader.close() } + // Decode one Arrow IPC batch into a root the caller OWNS (and must close), unlike + // deserializeRootFold which frees the root when it returns. The reader decodes into + // `allocator`, then the batch is transferred (zero-copy move, same allocator) into an + // independent root and the reader is closed. Used to rebuild a LocalColumnarBatch's live + // root after it was serialized (e.g. a checkpoint). + def deserializeRootOwned(bytes: Array[Byte], allocator: BufferAllocator): VectorSchemaRoot = { + val reader = new ArrowStreamReader(new ByteArrayInputStream(bytes), allocator) + try { + reader.loadNextBatch() + val src = reader.getVectorSchemaRoot + val dest = VectorSchemaRoot.create(src.getSchema, allocator) + val srcVecs = src.getFieldVectors + val destVecs = dest.getFieldVectors + var c = 0 + while (c < srcVecs.size) { + srcVecs.get(c).makeTransferPair(destVecs.get(c)).transfer(); c += 1 + } + dest.setRowCount(src.getRowCount) + dest + } finally reader.close() + } + // Decode a live Arrow root to tuples. Like deserializeTuples but over an // already-open root (the Emit output path's root-to-rows step); does not close // the root. Resolves the schema, field vectors, and column types once, then From 317a93528337d639f5c8f77bf57ab14056d6c4a7 Mon Sep 17 00:00:00 2001 From: Matthew Ball Date: Tue, 17 Nov 2026 01:41:50 -0800 Subject: [PATCH 15/16] test(bench): add the local (same-JVM, no-serialization) regime to the pipeline benchmark The existing scenario measures a columnar region against the row path across serialized edges, which is the cross-node case. This adds the other regime a workflow runs in: a same-JVM region where neither path serializes, so the comparison isolates vectorized columnar processing against per-tuple row processing. It is the measurement for the local zero-copy wire (handing a live Arrow root to a co-located operator): the row path passes a DataFrame by reference and runs each operator per tuple, while the columnar path hands each operator a live root and runs processColumnarRoot, with no serialization on either side. ColumnarPipelineBenchSpec: - rowLocalRun runs project -> filter -> aggregate per tuple with no DataFrame round-trip. colLocalRun runs the same pipeline on a live root reused across trials (projection reads it without consuming it), threading each operator's Emit root to the next via processColumnarRoot and closing the intermediates. Both reset the aggregate per run, warm up, and report the median over the same 2k/20k/100k sizes. Guarded by -Dcolumnar.bench=true, so it stays out of CI. Findings (this machine, JDK 17, median of 7): with no serialization on either side, the local live-root columnar path runs in about 0.03x the row path at 2k rows, 0.02x at 20k, and 0.01x at 100k. The row path barely changes between the cross-node and local runs (serialization was never its bottleneck), which shows its cost is dominated by building a Tuple per row at each operator rather than by the wire. So the columnar benefit is mostly about not materializing a Tuple per row at every stage; the wire format is secondary. The large ratio reflects a chain of lightweight relational operators, where per-tuple overhead dominates; a heavy per-tuple operator would narrow it. --- .../ColumnarPipelineBenchSpec.scala | 58 +++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/amber/src/test/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/ColumnarPipelineBenchSpec.scala b/amber/src/test/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/ColumnarPipelineBenchSpec.scala index f4c2273ca2c..81ddd3dc63e 100644 --- a/amber/src/test/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/ColumnarPipelineBenchSpec.scala +++ b/amber/src/test/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/ColumnarPipelineBenchSpec.scala @@ -19,6 +19,8 @@ package org.apache.texera.amber.engine.architecture.sendsemantics.partitioners +import org.apache.arrow.memory.RootAllocator +import org.apache.arrow.vector.VectorSchemaRoot import org.apache.pekko.actor.ActorSystem import org.apache.pekko.serialization.SerializationExtension import org.apache.pekko.testkit.TestKit @@ -196,6 +198,37 @@ class ColumnarPipelineBenchSpec aggExec.onFinish(0).foreach(_ => ()) } + // Local regime (same-JVM, NO serialization): both paths pass data by reference, so this + // isolates vectorized processing vs per-tuple processing (the phase-5b question). The row + // path never serializes a DataFrame; the columnar path hands each operator a live root. + private def rowLocalRun(rows: Array[Tuple]): Unit = { + aggExec.open() + val projected = rows.map(t => + projExec.processTuple(t, 0).next().asInstanceOf[SchemaEnforceable].enforceSchema(projSchema) + ) + val filtered = projected.filter(filterExec.filterFunc) + var i = 0 + while (i < filtered.length) { aggExec.processTuple(filtered(i), 0); i += 1 } + aggExec.onFinish(0).foreach(_ => ()) + } + + // srcRoot is read-only (projection copies it), so it is reused across trials. + private def colLocalRun(srcRoot: VectorSchemaRoot): Unit = { + aggExec.open() + val r1 = projExec.processColumnarRoot(srcRoot, 0) match { + case ColumnarResult.Emit(r) => r + case other => fail(s"projection: expected Emit, got $other") + } + val r2 = filterExec.processColumnarRoot(r1, 0) match { + case ColumnarResult.Emit(r) => r + case other => fail(s"filter: expected Emit, got $other") + } + r1.close() + aggExec.processColumnarRoot(r2, 0) + r2.close() + aggExec.onFinish(0).foreach(_ => ()) + } + private def benchEnabled: Boolean = sys.props.get("columnar.bench").contains("true") "a columnar region (project -> filter -> aggregate)" should "beat the row path across serialized edges" in { @@ -216,6 +249,31 @@ class ColumnarPipelineBenchSpec succeed } + "a local columnar region (same-JVM, no serialization)" should "show the zero-copy processing tradeoff vs rows" in { + assume(benchEnabled, "set -Dcolumnar.bench=true to run the pipeline benchmark") + println( + "\n===== Pipeline LOCAL (same-JVM, no serialization): live-root columnar vs row (median of %d) =====" + .format(trials) + ) + println("%-10s | %12s %14s %8s".format("rows", "row ms", "col-live ms", "col/row")) + for (n <- Seq(2000, 20000, 100000)) { + val rows = sourceRows(n) + val alloc = new RootAllocator() + val srcRoot = + ArrowUtils.deserializeRootOwned(ArrowUtils.serializeTuples(srcSchema, rows), alloc) + try { + for (_ <- 0 until warmups) { rowLocalRun(rows); colLocalRun(srcRoot) } + val rowMs = median((0 until trials).map(_ => timeMs(rowLocalRun(rows)))) + val colMs = median((0 until trials).map(_ => timeMs(colLocalRun(srcRoot)))) + println("%-10d | %12.2f %14.2f %8s".format(n, rowMs, colMs, pct(colMs, rowMs))) + } finally { srcRoot.close(); alloc.close() } + } + println( + "(col/row < 1.00x means the local live-root columnar path is faster; no serde either side)\n" + ) + succeed + } + override def afterAll(): Unit = { projExec.close(); filterExec.close(); aggExec.close() TestKit.shutdownActorSystem(system) From d417d436e7df7c76fa525465b5f2fdebd89bf2f1 Mon Sep 17 00:00:00 2001 From: Matthew Ball Date: Thu, 19 Nov 2026 01:24:42 -0800 Subject: [PATCH 16/16] test(bench): workflow-matrix benchmark across operator shapes and both regimes ColumnarWorkflowMatrixBenchSpec runs many operator-chain shapes (not one pipeline) through one fair, measured harness and reports columnar vs row speed per shape, in two regimes. It is guarded by -Dcolumnar.bench=true so it stays out of CI, like the other bench specs. Fairness is by construction. For each workflow the row path and the columnar path cross the same number of serialized hops (a source edge, then one edge per stage), and each path serializes its own native source form: the row path a DataFrame of Tuples, the columnar path the Arrow bytes a scan would already hold. Every workflow ends in a terminal both paths run: a vectorizing aggregate, or a row sink that decodes back to Tuples (the conservative case, where the columnar path pays a final decode). A transform stage (projection, filter) carries all three executions, so the same shape runs per tuple, over columnar bytes, and over a live root; the aggregate terminal consumes the stream and returns its group count, an exact integer used as the cross-path correctness checksum. Accuracy is by method. Each cell warms up, then interleaves row and columnar trials within one loop so GC or thermal drift hits both paths alike, and reports the median and the inter-quartile spread over nine trials. It runs a fixed seed, calls System.gc() before timing, and feeds every result into a blackhole so nothing is dead-code-eliminated. A parity assertion fails the benchmark if the two paths disagree on a cell, so a path that is fast because it is wrong cannot pass. Two regimes: CROSS-NODE runs every edge through the real Pekko/Kryo stack (where the columnar wire pays off), and LOCAL serializes on neither side and hands live Arrow roots along (phase 5), isolating vectorized processing from per-tuple processing. The shape set covers aggregate-only at two group cardinalities, filter-to-aggregate at two selectivities, projection, a project-filter-aggregate chain, a two-filter chain, and a projection-filter region ending at a row sink. Workflow size and the shape list are overridable via -Dcolumnar.bench.sizes. --- .../ColumnarWorkflowMatrixBenchSpec.scala | 480 ++++++++++++++++++ 1 file changed, 480 insertions(+) create mode 100644 amber/src/test/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/ColumnarWorkflowMatrixBenchSpec.scala diff --git a/amber/src/test/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/ColumnarWorkflowMatrixBenchSpec.scala b/amber/src/test/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/ColumnarWorkflowMatrixBenchSpec.scala new file mode 100644 index 00000000000..17b1d3c5bae --- /dev/null +++ b/amber/src/test/scala/org/apache/texera/amber/engine/architecture/sendsemantics/partitioners/ColumnarWorkflowMatrixBenchSpec.scala @@ -0,0 +1,480 @@ +/* + * 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. + */ + +package org.apache.texera.amber.engine.architecture.sendsemantics.partitioners + +import org.apache.arrow.memory.RootAllocator +import org.apache.arrow.vector.VectorSchemaRoot +import org.apache.pekko.actor.ActorSystem +import org.apache.pekko.serialization.SerializationExtension +import org.apache.pekko.testkit.TestKit +import org.apache.texera.amber.core.executor.ColumnarResult +import org.apache.texera.amber.core.tuple.{ + Attribute, + AttributeType, + Schema, + SchemaEnforceable, + Tuple +} +import org.apache.texera.amber.engine.common.AmberRuntime +import org.apache.texera.amber.engine.common.ambermessage.{ColumnarFrame, DataFrame} +import org.apache.texera.amber.operator.aggregate.{ + AggregateOpDesc, + AggregateOpExec, + AggregationFunction, + AggregationOperation +} +import org.apache.texera.amber.operator.filter.{ + ComparisonType, + FilterPredicate, + SpecializedFilterOpDesc, + SpecializedFilterOpExec +} +import org.apache.texera.amber.operator.projection.{ + AttributeUnit, + ProjectionOpDesc, + ProjectionOpExec +} +import org.apache.texera.amber.util.ArrowUtils +import org.apache.texera.amber.util.JSONUtils.{objectMapper => om} +import org.scalatest.BeforeAndAfterAll +import org.scalatest.flatspec.AnyFlatSpecLike + +import scala.util.Random + +/** + * A workflow-matrix benchmark: it runs many operator-chain shapes (not one pipeline) and + * reports columnar vs row speed for each, in two regimes, under one fair, measured method. + * + * Fairness is by construction. For every workflow, the row path and the columnar path cross + * the SAME number of serialized hops (a source edge, then one edge per stage), and each path + * serializes its OWN native source form (the row path a DataFrame of Tuples, the columnar path + * the Arrow bytes a scan would already hold). Each workflow ends in a consuming terminal that + * both paths run: either a vectorizing aggregate, or a row sink that decodes back to Tuples + * (the conservative case, where columnar must pay a final decode). So no path is handed free + * work the other pays for. + * + * Accuracy is by method. Each cell warms up, then interleaves row and columnar trials (row, + * then col, within one trial loop) so GC or thermal drift hits both paths alike; it reports + * the median and the inter-quartile spread, runs a fixed seed, calls System.gc() before timing, + * and feeds every result into a blackhole so nothing is dead-code-eliminated. A correctness gate + * asserts the two paths produce the same result (group count or row count) for every cell, so a + * path that is fast because it is wrong fails the benchmark. + * + * Two regimes: + * CROSS-NODE: every edge is a real Pekko/Kryo round-trip (where the columnar wire pays off). + * LOCAL: no serialization on either side; the columnar path hands live Arrow roots along + * (phase 5), isolating vectorized processing vs per-tuple processing. + * + * This is a benchmark, not a CI assertion: it is skipped unless -Dcolumnar.bench=true. Run with: + * sbt -Dcolumnar.bench=true "WorkflowExecutionService/testOnly *ColumnarWorkflowMatrixBenchSpec" + */ +class ColumnarWorkflowMatrixBenchSpec + extends TestKit(ActorSystem("ColumnarWorkflowMatrixBench", AmberRuntime.pekkoConfig)) + with AnyFlatSpecLike + with BeforeAndAfterAll { + + private val serde = SerializationExtension(system) + + // Wide source: a group/filter key, a numeric measure, and two string payload columns a + // projection can drop (so the row path pays to carry them until the projection runs). + private val srcSchema: Schema = Schema( + List( + new Attribute("key", AttributeType.INTEGER), + new Attribute("v", AttributeType.DOUBLE), + new Attribute("p1", AttributeType.STRING), + new Attribute("p2", AttributeType.STRING) + ) + ) + private val projSchema: Schema = + Schema( + List(new Attribute("key", AttributeType.INTEGER), new Attribute("v", AttributeType.DOUBLE)) + ) + + // nKeys controls group cardinality; vShift controls filter selectivity (fraction with v>0). + private def sourceRows(n: Int, nKeys: Int, vShift: Double): Array[Tuple] = { + val rng = new Random(1234) // fixed per build => reproducible, and identical for row and col + Array.tabulate(n) { _ => + Tuple + .builder(srcSchema) + .addSequentially( + Array[Any]( + Int.box(rng.nextInt(nKeys)), + Double.box(rng.nextDouble() + vShift), + rng.alphanumeric.take(16).mkString, + rng.alphanumeric.take(16).mkString + ) + ) + .build() + } + } + + // ---- stages ------------------------------------------------------------------------ + + // A transform stage knows all three ways to run: per-tuple rows, columnar bytes (cross-node), + // and a live columnar root (local). out() is the schema it produces. + private trait Xform { + def out(in: Schema): Schema + def rows(in: Array[Tuple]): Array[Tuple] + def colBytes(inBytes: Array[Byte]): (Array[Byte], Int) + def colRoot(in: VectorSchemaRoot): VectorSchemaRoot + def close(): Unit + } + + private def projection(outSchema: Schema): Xform = + new Xform { + private val units = outSchema.getAttributeNames.map(n => new AttributeUnit(n, n)) + private val desc = { + val x = new ProjectionOpDesc(); x.isDrop = false; x.attributes = units; x + } + private val e = new ProjectionOpExec(om.writeValueAsString(desc)); e.open() + def out(in: Schema): Schema = outSchema + def rows(in: Array[Tuple]): Array[Tuple] = + in.map(t => + e.processTuple(t, 0).next().asInstanceOf[SchemaEnforceable].enforceSchema(outSchema) + ) + def colBytes(inBytes: Array[Byte]): (Array[Byte], Int) = + e.processColumnarBatch(inBytes, 0) match { + case ColumnarResult.Emit(r) => + try (ArrowUtils.serializeRoot(r), r.getRowCount) + finally r.close() + case other => fail(s"projection colBytes: expected Emit, got $other") + } + def colRoot(in: VectorSchemaRoot): VectorSchemaRoot = + e.processColumnarRoot(in, 0) match { + case ColumnarResult.Emit(r) => r + case other => fail(s"projection colRoot: expected Emit, got $other") + } + def close(): Unit = e.close() + } + + private def filter(attr: String): Xform = + new Xform { + private val d = new SpecializedFilterOpDesc() + d.predicates = List(new FilterPredicate(attr, ComparisonType.GREATER_THAN, "0")) + private val e = new SpecializedFilterOpExec(om.writeValueAsString(d)); e.open() + def out(in: Schema): Schema = in + def rows(in: Array[Tuple]): Array[Tuple] = in.filter(e.filterFunc) + def colBytes(inBytes: Array[Byte]): (Array[Byte], Int) = + e.processColumnarBatch(inBytes, 0) match { + case ColumnarResult.Emit(r) => + try (ArrowUtils.serializeRoot(r), r.getRowCount) + finally r.close() + case other => fail(s"filter colBytes: expected Emit, got $other") + } + def colRoot(in: VectorSchemaRoot): VectorSchemaRoot = + e.processColumnarRoot(in, 0) match { + case ColumnarResult.Emit(r) => r + case other => fail(s"filter colRoot: expected Emit, got $other") + } + def close(): Unit = e.close() + } + + // The aggregate terminal: groups by key, sums v. Consumes the whole stream and returns the + // group count (an exact integer, so it is a reliable cross-path correctness checksum). + private class AggTerminal(groupSchemaKey: String = "key", measure: String = "v") { + private val desc = { + val d = new AggregateOpDesc() + val sum = new AggregationOperation() + sum.aggFunction = AggregationFunction.SUM + sum.attribute = measure + sum.resultAttribute = "sum_v" + d.aggregations = List(sum) + d.groupByKeys = List(groupSchemaKey) + om.writeValueAsString(d) + } + private val e = new AggregateOpExec(desc) + private def finish(): Long = { var c = 0L; e.onFinish(0).foreach(_ => c += 1); c } + def consumeRows(in: Array[Tuple]): Long = { + e.open(); var i = 0; while (i < in.length) { e.processTuple(in(i), 0); i += 1 }; finish() + } + def consumeBytes(bytes: Array[Byte]): Long = { + e.open(); e.processColumnarBatch(bytes, 0); finish() + } + def consumeRoot(root: VectorSchemaRoot): Long = { + e.open(); e.processColumnarRoot(root, 0); finish() + } + def close(): Unit = e.close() + } + + // ---- a workflow is a chain of transforms + a terminal (aggregate or a row sink) ---- + + private sealed trait Terminal + private case class Agg(t: AggTerminal) extends Terminal + private case object RowSink extends Terminal // decode the region output back to Tuples + + private case class Workflow( + name: String, + nKeys: Int, + vShift: Double, + stages: Seq[Xform], + terminal: Terminal + ) + + // ---- edges (one serde round-trip each) --------------------------------------------- + + private def edgeRows(rows: Array[Tuple]): Array[Tuple] = + serde.deserialize(serde.serialize(DataFrame(rows)).get, classOf[DataFrame]).get.frame + private def edgeCol(bytes: Array[Byte], rc: Int, schema: Schema): Array[Byte] = + serde + .deserialize(serde.serialize(ColumnarFrame(bytes, rc, schema)).get, classOf[ColumnarFrame]) + .get + .arrowIpcBytes + + // ---- CROSS-NODE runners (serde on every edge) -------------------------------------- + + private def crossRow(w: Workflow, src: Array[Tuple]): Long = { + var cur = edgeRows(src) + for (s <- w.stages) { cur = s.rows(cur); cur = edgeRows(cur) } + w.terminal match { + case Agg(t) => t.consumeRows(cur) + case RowSink => cur.length.toLong + } + } + + private def crossCol(w: Workflow, srcBytes: Array[Byte], srcRc: Int): Long = { + var bytes = edgeCol(srcBytes, srcRc, srcSchema) + var rc = srcRc + var schema = srcSchema + for (s <- w.stages) { + val (ob, orc) = s.colBytes(bytes) + schema = s.out(schema) + bytes = edgeCol(ob, orc, schema) + rc = orc + } + w.terminal match { + case Agg(t) => t.consumeBytes(bytes) + case RowSink => ArrowUtils.deserializeTuples(bytes).length.toLong // fair: col pays the decode + } + } + + // ---- LOCAL runners (no serde; columnar hands live roots along) --------------------- + + private def localRow(w: Workflow, src: Array[Tuple]): Long = { + var cur = src + for (s <- w.stages) cur = s.rows(cur) + w.terminal match { + case Agg(t) => t.consumeRows(cur) + case RowSink => cur.length.toLong + } + } + + // srcRoot is read-only (the first stage copies it), so it is reused across trials. + private def localCol(w: Workflow, srcRoot: VectorSchemaRoot): Long = { + var cur = srcRoot + var owned = false // whether cur is an intermediate we must close + for (s <- w.stages) { + val next = s.colRoot(cur) + if (owned) cur.close() + cur = next; owned = true + } + val out = w.terminal match { + case Agg(t) => t.consumeRoot(cur) + case RowSink => ArrowUtils.tuplesOfRoot(cur).length.toLong + } + if (owned) cur.close() + out + } + + // ---- timing ------------------------------------------------------------------------ + + @volatile private var blackhole: Long = 0L + private val warmups = 3 + private val trials = 9 + private def timeMs(body: => Long): (Double, Long) = { + val t0 = System.nanoTime(); val r = body; ((System.nanoTime() - t0) / 1e6, r) + } + private def median(xs: Seq[Double]): Double = { val s = xs.sorted; s(s.length / 2) } + private def iqr(xs: Seq[Double]): Double = { + val s = xs.sorted; s(math.min(s.length - 1, (s.length * 3) / 4)) - s(s.length / 4) + } + private def ratio(a: Double, b: Double): String = f"${a / b}%.2fx" + private def mrowsPerSec(n: Int, ms: Double): Double = if (ms <= 0) 0.0 else n / (ms * 1000.0) + + private case class Cell( + rowMs: Double, + rowIqr: Double, + colMs: Double, + colIqr: Double, + parity: Boolean + ) + + // Interleave row and col trials so drift hits both equally; assert result parity. + private def runCell(rowOnce: => Long, colOnce: => Long): Cell = { + System.gc(); Thread.sleep(30) + for (_ <- 0 until warmups) { blackhole ^= rowOnce; blackhole ^= colOnce } + val rowTimes = Array.ofDim[Double](trials) + val colTimes = Array.ofDim[Double](trials) + var rowRes = Long.MinValue + var colRes = Long.MinValue + for (i <- 0 until trials) { + val (rm, rr) = timeMs(rowOnce); rowTimes(i) = rm; rowRes = rr; blackhole ^= rr + val (cm, cr) = timeMs(colOnce); colTimes(i) = cm; colRes = cr; blackhole ^= cr + } + Cell( + median(rowTimes.toSeq), + iqr(rowTimes.toSeq), + median(colTimes.toSeq), + iqr(colTimes.toSeq), + rowRes == colRes + ) + } + + private def benchEnabled: Boolean = sys.props.get("columnar.bench").contains("true") + private val sizes: Seq[Int] = + sys.props + .get("columnar.bench.sizes") + .map(_.split(",").map(_.trim.toInt).toSeq) + .getOrElse(Seq(1000, 10000, 100000)) + + // Build the workflow set fresh (operators are stateful) and return it with a cleanup. + private def workflows(): (Seq[Workflow], () => Unit) = { + val wfs = Seq( + Workflow("agg (100 groups)", 100, 0.0, Seq.empty, Agg(new AggTerminal())), + Workflow("agg (10k groups)", 10000, 0.0, Seq.empty, Agg(new AggTerminal())), + Workflow("filter>agg (sel ~15%)", 100, -0.85, Seq(filter("v")), Agg(new AggTerminal())), + Workflow("filter>agg (perm ~85%)", 100, -0.15, Seq(filter("v")), Agg(new AggTerminal())), + Workflow("project>agg", 100, 0.0, Seq(projection(projSchema)), Agg(new AggTerminal())), + Workflow( + "project>filter>agg", + 100, + 0.0, + Seq(projection(projSchema), filter("v")), + Agg(new AggTerminal()) + ), + Workflow( + "filter>filter>agg", + 100, + 0.0, + Seq(filter("v"), filter("v")), + Agg(new AggTerminal()) + ), + Workflow( + "project>filter (row sink)", + 100, + 0.0, + Seq(projection(projSchema), filter("v")), + RowSink + ) + ) + val cleanup = () => + wfs.foreach { w => + w.stages.foreach(_.close()) + w.terminal match { case Agg(t) => t.close(); case _ => () } + } + (wfs, cleanup) + } + + // ---- the two regimes --------------------------------------------------------------- + + "the columnar wire, across a matrix of workflows" should "beat the row path cross-node (serialized edges)" in { + assume(benchEnabled, "set -Dcolumnar.bench=true to run the workflow-matrix benchmark") + val (wfs, cleanup) = workflows() + try { + println( + "\n================ CROSS-NODE: columnar region vs row, per workflow (median of %d) ================" + .format(trials) + ) + println( + "%-26s %8s | %10s %8s | %12s %8s | %7s %8s" + .format("workflow", "rows", "row ms", "(iqr)", "col ms", "(iqr)", "col/row", "parity") + ) + for (w <- wfs; n <- sizes) { + val rows = sourceRows(n, w.nKeys, w.vShift) + val srcBytes = ArrowUtils.serializeTuples(srcSchema, rows) + val c = runCell(crossRow(w, rows), crossCol(w, srcBytes, n)) + println( + "%-26s %8d | %10.2f %8.2f | %12.2f %8.2f | %7s %8s" + .format( + w.name, + n, + c.rowMs, + c.rowIqr, + c.colMs, + c.colIqr, + ratio(c.colMs, c.rowMs), + if (c.parity) "ok" else "MISMATCH" + ) + ) + assert(c.parity, s"cross-node parity failed for ${w.name} @ $n rows") + } + println( + "(col/row < 1.00x means the columnar region is faster end to end; iqr is p75-p25 ms)\n" + ) + } finally cleanup() + succeed + } + + "the columnar wire, across a matrix of workflows" should "show the local (same-JVM, no-serde) tradeoff" in { + assume(benchEnabled, "set -Dcolumnar.bench=true to run the workflow-matrix benchmark") + val (wfs, cleanup) = workflows() + try { + println( + "\n================ LOCAL (same-JVM, no serialization): live-root columnar vs row (median of %d) ================" + .format(trials) + ) + println( + "%-26s %8s | %10s %8s | %12s %8s | %7s %9s %8s" + .format( + "workflow", + "rows", + "row ms", + "(iqr)", + "col ms", + "(iqr)", + "col/row", + "col Mr/s", + "parity" + ) + ) + for (w <- wfs; n <- sizes) { + val rows = sourceRows(n, w.nKeys, w.vShift) + val alloc = new RootAllocator() + val srcRoot = + ArrowUtils.deserializeRootOwned(ArrowUtils.serializeTuples(srcSchema, rows), alloc) + try { + val c = runCell(localRow(w, rows), localCol(w, srcRoot)) + println( + "%-26s %8d | %10.2f %8.2f | %12.2f %8.2f | %7s %9.2f %8s" + .format( + w.name, + n, + c.rowMs, + c.rowIqr, + c.colMs, + c.colIqr, + ratio(c.colMs, c.rowMs), + mrowsPerSec(n, c.colMs), + if (c.parity) "ok" else "MISMATCH" + ) + ) + assert(c.parity, s"local parity failed for ${w.name} @ $n rows") + } finally { srcRoot.close(); alloc.close() } + } + println("(col/row < 1.00x means the local live-root path is faster; no serde either side)\n") + println(s"[blackhole=$blackhole]\n") + } finally cleanup() + succeed + } + + override def afterAll(): Unit = { + TestKit.shutdownActorSystem(system) + super.afterAll() + } +}