OpenSearch Arrow Flight 原生传输路径(Native Arrow Transport)设计与实战指南

原创2026-09-21 12:55:541,612 阅读
文章标签:搜索引擎全文检索可观测性数据分析

OpenSearch Arrow Flight 原生传输路径(Native Arrow Transport)设计与实战指南

导读

本指南深入解析 OpenSearch arrow-flight-rpc 插件提供的 Native Arrow Transport 路径:类型化的 VectorSchemaRoot 数据无需任何字节序列化,直接经由 Arrow Flight 在节点间流动,是 DataFusion 等原生产出 Arrow 列式数据的查询引擎对接 OpenSearch 的推荐通道。阅读本文后,你将掌握该路径的完整接入流程(服务端产出、客户端消费)、分配器生命周期管理、所有权契约、流水线并行生产,以及如何利用应用级元数据(Application Metadata)随批次携带业务信息。

概述:两条并行的传输路径

在 OpenSearch 的 Arrow Flight 传输层中,同一份数据存在两条截然不同的通道(对应文档见 native-arrow-transport-design.md):

  • 字节序列化路径(Byte-serialized path):沿用 OpenSearch 传统的 writeTo/read 机制,数据先经由 StreamOutput/StreamInput 序列化为字节流,再写入 Flight 帧。该路径保持不变,兼容既有代码。
  • 原生 Arrow 路径(Native Arrow path):类型化的 VectorSchemaRoot 数据直接通过 Flight 流动,不发生字节序列化。这是为那些原生产出 Arrow 列式数据的 API 设计的,例如 DataFusion 这类查询引擎。

两条路径由响应类型自动区分:sendBatch 在 FlightServerChannel.sendBatch 中通过 response instanceof ArrowBatchResponse 判断是否为原生路径。原生路径下,响应根(root)被零拷贝转移进共享流根;字节路径下,writeTo 的结果被写入一个复用的 VarBinary 向量(见 serializeIntoStreamRoot 与 VectorStreamOutput)。

快速上手:三步接入 Native Arrow 路径

第一步:定义你的响应类型

服务端与客户端共用一个响应类,只需继承 ArrowBatchResponse,无需覆写 writeTo/read——框架会全权处理序列化。该基类定义在 ArrowBatchResponse.java,要求子类提供两个构造器:

  • 发送侧构造器:包装一个已填充数据的 VectorSchemaRoot;
  • 接收侧构造器:接收 StreamInput,从传输层认领向量。
public class MyQueryResponse extends ArrowBatchResponse {
    public MyQueryResponse(VectorSchemaRoot root) { super(root); }
    public MyQueryResponse(StreamInput in) throws IOException { super(in); }
}

需要特别说明的是,ArrowBatchResponse.writeTo 被声明为 final 并直接抛出 UnsupportedOperationException。这是一种快速失败设计:若响应被错误地路由到非 Arrow 传输,会在发送端立刻暴露问题,而不是静默产出空帧(见 ArrowBatchResponse.java#L139-L146)。接收侧构造器同样要求 StreamInput 实现 ArrowStreamInput,否则抛出 IllegalStateException(ArrowBatchResponse.java#L113-L127)。

第二步:服务端 handler——产出 Arrow 数据

服务端 handler 通过 TransportChannel 逐个批次发送:

void handleRequest(MyRequest request, TransportChannel channel, Task task) throws IOException {
    // 获取 channel 的分配器。生产者 root 应直接使用它
    // (不要使用子分配器),以规避 C Data import 引入的
    // 跨分配器 transfer 缺陷(详见下文"分配器管理"一节)。
    BufferAllocator allocator = ArrowFlightChannel.from(channel).getAllocator();

    Schema schema = new Schema(List.of(
        new Field("name", FieldType.nullable(new ArrowType.Utf8()), null),
        new Field("score", FieldType.nullable(new ArrowType.FloatingPoint(FloatingPointPrecision.DOUBLE)), null)
    ));

    try {
        for (int i = 0; i < batchCount; i++) {
            VectorSchemaRoot root = VectorSchemaRoot.create(schema, allocator);
            // populate vectors...
            channel.sendResponseBatch(new MyQueryResponse(root));
            // root 的所有权已移交框架——不要复用或关闭它
        }
        // 清理回调在所有批次刷出后在执行器上运行。
        channel.completeStream();
    } catch (Exception e) {
        channel.sendResponse(e);
    }
}

ArrowFlightChannel.from(channel) 是一个解包工具:它会穿透 TaskTransportChannel、BaseTcpTransportChannel 等包装层,找到底层真正的 Arrow Flight 通道并返回其分配器;若通道并非由 Flight 支撑,则抛出 IllegalArgumentException(见 ArrowFlightChannel.java#L44-L63)。

从源码结构看,sendResponseBatch 最终进入 FlightTransportChannel.sendResponseBatch,再交由 FlightOutboundHandler 在 channel 专属的 flight executor 上执行发送。注意 FlightTransportChannel 覆写了 sendResponse(单响应版本),直接抛出 UnsupportedOperationException 并提示改用 sendResponseBatch——流式请求不支持单次响应。

第三步:客户端 handler——消费 Arrow 数据

客户端实现 StreamTransportResponseHandler<MyQueryResponse>,在流回调中逐批消费类型化向量:

class MyQueryHandler implements StreamTransportResponseHandler<MyQueryResponse> {

    public MyQueryResponse read(StreamInput in) throws IOException {
        return new MyQueryResponse(in);
    }

    public void handleStreamResponse(StreamTransportResponse<MyQueryResponse> stream) {
        MyQueryResponse response;
        while ((response = stream.nextResponse()) != null) {
            VectorSchemaRoot root = response.getRoot();
            VarCharVector names = (VarCharVector) root.getVector("name");
            Float8Vector scores = (Float8Vector) root.getVector("score");
            // process typed vectors...
        }
        stream.close();
    }

    public void handleException(TransportException exp) { /* handle error */ }
    public String executor() { return ThreadPool.Names.GENERIC; }
}

重要:为了让传输层路由到原生路径而非字节反序列化,客户端 handler 最好继承 ArrowBatchResponseHandler。该基类将 skipsDeserialization() 固定返回 true,这是原生路径被选中的关键开关(见 ArrowBatchResponseHandler.java)。在接收侧,VectorStreamInput.forNativeArrow 会把流根的向量转移到一个新创建的 consumer root 上,使响应生命周期超越 Flight 流的游标(见 VectorStreamInput.java#L68-L83)。

底层原理:零拷贝转移是如何发生的

原生路径"无字节序列化"的承诺由 FlightServerChannel 的 transferIntoStreamRoot 兑现(FlightServerChannel.java#L307-L330):

  1. 首个批次:用生产者第一个批次向量的分配器创建一个新的共享流根,然后通过 VectorTransfer.transferRoot 将生产者 root 的向量零拷贝转移进去;如果转移失败,新建的根会在 finally 中关闭,避免泄漏。
  2. 后续批次:直接向已复用的共享流根转移数据。
  3. 数据就绪后调用 serverStreamListener.putNext()(带元数据时调用 putNext(ArrowBuf))推给 gRPC。

整个发送流程在 FlightOutboundHandler.sendResponseBatch 中被提交到 channel 的 flight executor(FlightOutboundHandler.java#L117-L189),并在入队前经过 awaitReadyOrThrow() 背压门——当 gRPC 出站缓冲区满时,生产者线程会被阻塞,从而把背压传导到分配环节而不是让事件循环的队列无限增长。

分配器管理

分配器必须长生命周期

用于生产者 root 的分配器必须是长生命周期的——它必须活得比 gRPC 流更久。原因在于:gRPC 的零拷贝写路径(ArrowBufRetainingCompositeByteBuf)会在 putNext() 与 completed() 之后仍保留对 ArrowBuf 的引用,并在 Netty 事件循环上异步释放它们。如果在 gRPC 仍持有这些引用时关闭分配器,将引发内存记账错误(memory accounting errors)。

正确的做法是:

  • 通过 ArrowFlightChannel.from(channel).getAllocator() 获取 channel 的分配器;
  • 或者使用你自己的长生命周期应用级分配器;
  • 禁止为每个请求创建并在请求结束时关闭子分配器。

注意:C Data Import 与分配器选择

如果你的生产者通过 Arrow C Data Interface(Data.importIntoVector、Data.importIntoVectorSchemaRoot)导入数据,导入进来的缓冲区是**外部托管(foreign-backed)**的。Arrow Java 存在一个缺陷:对 foreign-backed 缓冲区执行跨分配器 transferOwnership 时,不会正确释放内部的 ArrowArray C 结构缓冲区(每次导入调用约 128 字节),从而在源分配器中造成内存泄漏。

框架的应对策略正是 transferIntoStreamRoot 中的设计:共享 Flight root 使用生产者的分配器(即第一个批次向量的分配器)创建,保证转移发生在同一分配器内,从而规避该缺陷。因此,所有后续批次都必须使用同一个分配器。

命名池分配器

除了 channel 分配器,框架还提供了命名池分配器。ArrowNativeAllocator.getPoolAllocator(String) 按池名返回底层 BufferAllocator(ArrowNativeAllocator.java#L519-L525),三个内置池按组件语义划分:

池名 适用场景
POOL_FLIGHT 传输层生产者/消费者(arrow-flight-rpc 及基于 StreamTransportService 构建的插件)
POOL_INGEST ingest 路径的生产者(如 parquet-data-format 的 VSR 分配器)
POOL_QUERY 查询执行生产者(analytics-engine 的分片及协调端中间批次)

所有分配器必须共享同一个根(root),零拷贝转移才能通过 Arrow 的 AllocationManager associate 检查。若插件绕过命名池直接 new RootAllocator(),单插件自用可能正常,但一旦与其他插件的缓冲区发生零拷贝交接,就会触发 associate 检查失败——因为根是按身份而非地址空间比较的(详见 ArrowBatchResponse.java#L48-L74 的 javadoc 说明)。

所有权契约

原文档定义了清晰的资源所有权矩阵:

资源 创建方 关闭方
Channel 分配器 框架 框架(channel 关闭时)
生产者 root(每个批次) 生产者 框架(执行器上零拷贝转移之后)
共享 Flight root 框架 框架(channel 关闭时)

调用 sendResponseBatch(response) 之后,框架即拥有该响应 root 的所有权。不要复用或关闭它——框架会转移其缓冲区,并在执行器上将其关闭。

从源码可以印证这一契约的严谨性:FlightOutboundHandler.sendResponseBatch 用 handedOff 标志保证批次被"恰好释放一次"——要么 sendBatch 在 executor 上运行(其 finally 释放源),要么批次从未送达 sendBatch(此时 releaseUnsent 负责释放),两条路径互斥(见 FlightOutboundHandler.java#L152-L188 与 FlightServerChannel.releaseUnsent)。而 FlightServerChannel.sendBatch 的 finally 会在每次退出时关闭源 root:转移成功后它是空 root(关闭为 no-op),提前抛出异常时则真正释放缓冲区(FlightServerChannel.java#L291-L297)。

流水线并行生产

批次可以并行生产。每条批次必须拥有自己的 VectorSchemaRoot(使用 channel 的分配器创建)。框架会在执行器线程上串行化转移与发送,生产者无需等待每个批次刷出即可排队后续批次。

这一点在 NativeArrowTransportIT.testParallelBatchProduction 中得到验证:5 个并行线程生产 100 个批次(每批 10 行),断言所有 100 个批次全部到达、无丢失无重复,且每个批次的 batch_id 在批次内一致。该测试的 handler 采用"生产者线程产出入队、主线程串行 drain 发送"的模式(NativeArrowTransportIT.java#L398-L445),与文档描述的生产者语义完全一致。

同一测试类还验证了批次数据在流推进与关闭后仍然存活:testBatchesSurviveStreamAdvanceAndClose 先完整排空并关闭流,再回头读取每个保留批次中的向量数据,确认行数与值都完好(NativeArrowTransportIT.java#L153-L229)——这正是接收侧转移 consumer root 的价值所在。

应用级元数据(Application Metadata)

每个 ArrowBatchResponse 都可以携带一段不透明的 byte[] 应用元数据,与数据放在同一个 Flight 帧上传输——底层正是 Arrow Flight 的 OutboundStreamListener.putNext(ArrowBuf metadata)。传输层不解释这些字节,编码与解码完全是 action 自身的责任。

典型用途:

  • 逐批次元数据:与当前批次数据强关联的信息——行偏移、水位线(watermark)、批次级统计。
  • 流终止载荷:只附加在最后一个批次上——性能剖析计数器、累计统计、摘要 blob。

发送侧与接收侧的配合示例(源自原文档,并经 StreamMetadataIT 集成测试验证):

// send-side: attach to the last batch
boolean isLast = (b == batchCount - 1);
if (isLast && profile) {
    byte[] profileBytes = serializeProfile(...);
    channel.sendResponseBatch(new MyQueryResponse(root, profileBytes));
} else {
    channel.sendResponseBatch(new MyQueryResponse(root));
}

// receive-side: read on every batch, act when present
while ((r = stream.nextResponse()) != null) {
    consume(r.getRoot());
    byte[] meta = r.getMetadata();
    if (meta != null) handleProfile(meta);
}

生命周期上,元数据字节会从 Flight 线上缓冲区拷贝进响应自有的 byte<a href="https://link.gitcode.com/i/f0c706ef37cf0e7533b9ec52eba9af85" target="_blank">],因此元数据的存活时间超过流游标。实现上,接收侧 FlightTransportResponse.copyMetadata 在每次 next() 时把 Flight 的 getLatestMetadata() 缓冲区拷贝出来(Flight 在下次 next() 前会复用该缓冲区),空或缺省时返回 null(见 [FlightTransportResponse.java#L237-L251);发送侧则在 FlightServerChannel.sendBatch 中把元数据写入 ArrowBuf 并交给 putNext(metadataBuf),若 putNext 抛出异常则检查引用计数并自行关闭该 ArrowBuf(FlightServerChannel.java#L260-L275)。

注意:元数据通道暴露在 ArrowBatchResponse 上,仅原生 Arrow 路径可用;字节序列化路径不会把它带到线上。

测试与验证

原生 Arrow 路径的正确性由以下测试覆盖,可作为实现参考:

使用约束小结

  1. 原生路径仅适用于原生产出 Arrow 列式数据的 API;普通响应继续走字节序列化路径,二者互不干扰。
  2. 生产者分配器必须长生命周期,禁止每请求创建/关闭子分配器。
  3. 涉及 C Data Interface 导入时,务必保证所有批次使用同一分配器,避免跨分配器 transfer 触发 ArrowArray 内存泄漏。
  4. sendResponseBatch 之后即失去对 root 的控制权,不得复用或关闭。
  5. 客户端 handler 应继承 ArrowBatchResponseHandler(或正确转发 skipsDeserialization()),否则会被路由到字节反序列化路径,接收侧构造器将直接抛错。
  6. 元数据通道仅原生路径可用,且传输层不做编解码,业务语义由 action 自行约定。
登录后查看全文
OpenSearch