企业官网建设流程全解析

• 数据工程
• 大数据
• 序列化
• 数据分析

本文基于 Apache Arrow 官方协议文档 docs/source/format/FlightSql.rst 展开，结合仓库中的协议定义 format/FlightSql.proto、时序图与 Java 实现进行纵深解读。读完本文，你将掌握 Flight SQL 的命令分类、消息封装约定、SQL 元数据命令的返回 Schema、查询执行与预编译语句的完整流程，以及会话管理机制，并能在仓库源码中定位到对应实现。

协议概览：让数据库通过 Arrow 内存格式与 Flight RPC 对话

Arrow Flight SQL 是一套用于通过 Arrow 内存格式和 Flight RPC 框架与 SQL 数据库交互的协议。它将 SQL 数据库的能力映射为 Flight 的 RPC 方法：数据库厂商只需按规范实现服务端 RPC 方法，无需为每种语言分别编写客户端驱动程序；而数据库客户端则可以直接使用现成的 Flight SQL 客户端（如仓库中的 FlightSqlClient.java）连接任何实现了所需端点的数据库。

从源码结构看，协议的核心承载形式有两层：

• 传输层：复用 Arrow Flight 的既有 RPC 方法（GetFlightInfo、GetSchema、DoGet、DoPut、DoAction），详见 docs/source/format/Flight.rst 与 format/Flight.proto；
• 消息层：通过 Protobuf 定义各类 command 消息，打包后放入 FlightDescriptor 或 Flight Action 中传递，定义集中在 format/FlightSql.proto（package arrow.flight.protocol.sql）。

协议的整体设计目标是：SQL 查询结果、元数据乃至批量导入的数据，都以 Arrow 列式数据流的形式传输，从而消除行式序列化（如 JDBC/ODBC 的逐行取值）带来的转换开销。

RPC 方法与消息封装约定

Flight SQL 的所有命令都遵循一套统一的封装约定，理解它是阅读后续所有命令的前提。

元数据与查询命令：打包进 FlightDescriptor

绝大多数命令（包括全部 SQL 元数据命令和查询执行命令）通过GetFlightInfo与GetSchema两个 RPC 方法使用。封装方式为：

1. 将命令对应的 Protobuf 请求消息装入google.protobuf.Any；
2. 序列化后填入CMD 类型FlightDescriptor 的cmd字段。

客户端侧的具体做法可以在 FlightSqlClient.java 中看到：execute()方法构造CommandStatementQuery后，通过Any.pack(builder.build()).toByteArray()生成 descriptor，再调用底层 Flight 客户端的client.getInfo(descriptor, options)。

• 若命令用于GetFlightInfo：服务端返回FlightInfo，客户端用其中的Ticket配合DoGetRPC 拉取 Arrow 数据——SQL 元数据本身就是以 Arrow 数据形式返回的，与查询结果的处理方式完全一致；
• 若命令用于GetSchema：服务端返回该命令固定的 Arrow Schema（协议对每个命令的返回 Schema 都有严格规定，详见下文）。

Action 命令：打包进 Flight Action

以Action开头的命令（如创建/关闭预编译语句）改用DoActionRPC 方法：

• 命令消息装入google.protobuf.Any后，序列化并填入 Flight Action 的body字段；
• Action 的type字段设置为命令名（例如对于ActionClosePreparedStatementRequest，type应为ClosePreparedStatement）。

在 Java 实现中，prepare()方法正是以FLIGHT_SQL_CREATE_PREPARED_STATEMENT作为 Action type，将ActionCreatePreparedStatementRequest的 Any 包装结果作为 body 发起client.doAction（见 FlightSqlClient.java）。

更新类命令：通过 DoPut 返回结果

执行更新（如CommandStatementUpdate、CommandStatementIngest）的命令使用DoPutRPC：客户端消费完整 FlightData 数据流后，服务端返回 Flight RPC 的PutResult，其中app_metadata字段携带 Flight SQL 的DoPutUpdateResult消息（包含被影响的行数record_count，-1表示行数未知，见 format/FlightSql.proto）。

SQL 元数据命令：数据库目录信息的标准查询接口

Flight SQL 提供一组命令来获取数据库服务端的目录（catalog）元数据，涵盖了 JDBCDatabaseMetaData类接口的大多数能力。下表汇总了文档中列出的九个命令及各自含义：

所有命令均可在GetFlightInfo/GetSchema上使用，且返回 Schema 由协议固定。下面结合 format/FlightSql.proto 中的消息定义，给出各命令的返回 Schema 细节。

目录与 Schema 列举

• CommandGetCatalogs（proto 定义）：返回单列catalog_name: utf8 not null，结果按catalog_name排序；
• CommandGetDbSchemas（proto 定义）：返回catalog_name: utf8（可空）与db_schema_name: utf8 not null两列，按 catalog 再按 schema 排序。请求消息支持catalog（可选，空字符串表示检索无 catalog 的 schema，省略则不做过滤）与db_schema_filter_pattern过滤模式，模式串中%匹配任意长度子串、_匹配任意单个字符——这与 ODBC 的搜索模式约定一致。

表与表类型

• CommandGetTableTypes（proto 定义）：返回单列table_type: utf8 not null，按table_type排序。TABLE、VIEW、SYSTEM TABLE是常见取值；

• CommandGetTables（proto 定义）：返回catalog_name、db_schema_name、table_name: utf8 not null、table_type: utf8 not null，若请求了include_schema，还会追加table_schema: bytes not null列——该字段以 IPC 消息承载 Schema.fbs 中描述的 Arrow Schema。请求参数包括catalog、db_schema_filter_pattern、table_name_filter_pattern（三者均支持%/_通配）、table_types（重复字段，用于过滤）以及include_schema。

  特别值得注意的是，返回的 table schema 字段上可以携带以下元数据键（同样适用于CommandStatementQuery/CommandPreparedStatementQuery的返回 Schema）：

  • ARROW:FLIGHT:SQL:CATALOG_NAME：表的 catalog 名
  • ARROW:FLIGHT:SQL:DB_SCHEMA_NAME：数据库 schema 名
  • ARROW:FLIGHT:SQL:TABLE_NAME：表名
  • ARROW:FLIGHT:SQL:TYPE_NAME：数据源特有的数据类型名
  • ARROW:FLIGHT:SQL:PRECISION：列精度/大小
  • ARROW:FLIGHT:SQL:SCALE：列小数位
  • ARROW:FLIGHT:SQL:IS_AUTO_INCREMENT："1"表示自增列，"0"否则
  • ARROW:FLIGHT:SQL:IS_CASE_SENSITIVE："1"表示大小写敏感
  • ARROW:FLIGHT:SQL:IS_READ_ONLY："1"表示只读列
  • ARROW:FLIGHT:SQL:IS_SEARCHABLE："1"表示可通过 WHERE 子句检索

  这些元数据为 JDBC/ODBC 驱动映射列级属性提供了标准通道。

主键与外键

• CommandGetPrimaryKeys（proto 定义）：返回catalog_name、db_schema_name、table_name: utf8 not null、column_name: utf8 not null、key_name: utf8、key_sequence: int32 not null，按 catalog、schema、table、key_name 再按 key_sequence 排序。请求参数为catalog（可选）、db_schema（可选）与必填的table；

• CommandGetExportedKeys/CommandGetImportedKeys/CommandGetCrossReference（proto 定义）：三者都返回成对的主键/外键列描述（pk_catalog_name、pk_db_schema_name、pk_table_name、pk_column_name、fk_catalog_name、fk_db_schema_name、fk_table_name、fk_column_name、key_sequence、fk_key_name、pk_key_name、update_rule、delete_rule）。其中update_rule与delete_rule为uint8，取值对应 UpdateDeleteRules 枚举：0=CASCADE、1=RESTRICT、2=SET NULL、3=NO ACTION、4=SET DEFAULT。

  三者的语义差异在于查询方向：

  • CommandGetExportedKeys：给定表作为父表，列出引用其主键的外键（由catalog/db_schema/table指定父表）；
  • CommandGetImportedKeys：给定表作为子表，列出其自身的外键（由catalog/db_schema/table指定子表）；
  • CommandGetCrossReference：同时指定父表（pk_catalog/pk_db_schema/pk_table）与子表（fk_catalog/fk_db_schema/fk_table），列出子表中引用父表主键或唯一约束列的外键列。

CommandGetSqlInfo：服务端能力自描述

CommandGetSqlInfo（proto 定义）是元数据命令中最重要的一员，其请求消息CommandGetSqlInfo仅含一个repeated uint32 info字段：若省略，则返回全部元数据；否则只返回指定 ID 的元数据项。其返回 Schema 固定为：

< info_name: uint32 not null, value: dense_union< string_value: utf8, bool_value: bool, bigint_value: int64, int32_bitmask: int32, string_list: list<string_data: utf8>, int32_to_int32_list_map: map<key: int32, value: list<int32>> > >

每行对应一条元数据信息。info_name的取值由 SqlInfo 枚举 定义，其 ID 区间划分非常清晰，模仿 ODBC 的SQLGetInfo()函数：

SqlInfo枚举取值类型多样：布尔型（如是否只读、是否支持 SQL）、字符串型（服务器名、标识符引号字符）、int32 位掩码型（如SQL_SUPPORTED_GRAMMAR的位组合：1=MINIMUM、2=CORE、4=EXTENDED）、int64 型（各类长度上限，如SQL_MAX_COLUMNS_IN_SELECT(547)）以及 map 型（如SQL_SUPPORTS_CONVERT(517)，返回map<int32, list<int32>>）。位掩码型返回值的解析方式在 proto 注释中均有逐位示例，例如SQL_SUPPORTED_GROUP_BY返回 1 表示支持SQL_GROUP_BY_UNRELATED，返回 2 表示支持SQL_GROUP_BY_BEYOND_SELECT，返回 3 表示两者皆支持。

SqlInfo之外，proto 还定义了配套的细粒度枚举用于解释这些信息，包括：

• SqlSupportedTransaction：NONE/TRANSACTION/SAVEPOINT三级事务支持；
• SqlSupportedCaseSensitivity、SqlNullOrdering、SupportedSqlGrammar、SupportedAnsi92SqlGrammarLevel、SqlOuterJoinsSupportLevel、SqlSupportedGroupBy、SqlSupportedSubqueries、SqlSupportedUnions、SqlTransactionIsolationLevel、SqlSupportedResultSetType、SqlSupportedResultSetConcurrency 等；
• XdbcDataType 与 XdbcDatetimeSubcode：与 JDBC/ODBC 规范保持一致的 SQL 类型编号及 datetime/interval 子类型；
• Nullable、Searchable：描述列空值约束与 WHERE 子句可检索性。

CommandGetXdbcTypeInfo：数据类型支持描述

除文档正文列出的九个命令外，协议文件还定义了CommandGetXdbcTypeInfo（proto 定义），用于获取后端支持的数据类型信息。其请求可携带可选的data_type指定要查询的特定类型；返回 Schema 极为详尽，包含type_name、data_type（XdbcDataType 枚举值）、column_size、literal_prefix/literal_suffix、create_params、nullable、case_sensitive、searchable、unsigned_attribute、fixed_prec_scale、auto_increment、local_type_name、minimum_scale/maximum_scale、sql_data_type、datetime_subcode、num_prec_radix、interval_precision等列，完整对应 ODBC 的SQLGetTypeInfo结果集。

查询执行：即席查询、更新与批量导入

Flight SQL 的查询执行命令复用前述封装约定，覆盖即席查询、无结果更新、批量数据导入三类场景。

CommandStatementQuery：即席查询

• GetFlightInfo：执行即席 SQL 查询，随后客户端调用DoGet拉取结果；
• GetSchema：仅返回查询结果的 Arrow Schema。

消息定义为 CommandStatementQuery：query为 SQL 文本，可选的transaction_id表示将该查询纳入某个事务执行（未设置则自动提交）。配套的 TicketStatementQuery 是GetFlightInfo返回的 Ticket 内容，协议明确要求客户端将其视为一次性、不透明的值，不得尝试解析。

对应的 Java 客户端 API 为execute(query)与getExecuteSchema(query)（见 FlightSqlClient.java）。CommandStatementSubstraitPlan（proto 定义）则是该命令的 Substrait 变体，用SubstraitPlan（内含序列化的substrait.Plan与版本号字符串version，见 format/FlightSql.proto）代替 SQL 文本。

CommandStatementUpdate：无结果的更新语句

用于执行不返回结果集的 SQL 更新（UPDATE/INSERT/DELETE等）：

• DoPut：执行查询并返回受影响行数（CommandStatementUpdate 定义）。行数通过DoPutUpdateResult.record_count传递，-1表示未知。

Java 客户端的executeUpdate()方法即对应此命令，返回long类型的受影响行数（见 FlightSqlClient.java）。

CommandStatementIngest：批量数据导入

批量导入是 Flight SQL 加速数据写入的重要能力：

• DoPut：将 FlightData 流中的 Arrow record batches 加载到指定目标表，并通过DoPutUpdateResult返回导入的行数。

CommandStatementIngest 定义 提供了丰富的导入控制参数：

其中TableDefinitionOptions内嵌两个枚举：

• TableNotExistOption：TABLE_NOT_EXIST_OPTION_CREATE(1) 不存在则创建；TABLE_NOT_EXIST_OPTION_FAIL(2) 不存在则报错；UNSPECIFIED(0) 仅用于占位，客户端不应使用；
• TableExistsOption：TABLE_EXISTS_OPTION_FAIL(1) 已存在则失败；TABLE_EXISTS_OPTION_APPEND(2) 追加写入；TABLE_EXISTS_OPTION_REPLACE(3) 先删后建；UNSPECIFIED(0) 不应使用。

该命令的完整调用链可参考仓库中的时序图源文件 CommandStatementIngest.mmd：DoPut(CommandStatementIngest)→ 客户端推送 FlightData 流 → 服务端返回PutResult{DoPutUpdateResult{RecordCount}}。

预编译语句：创建、绑定参数、执行与关闭

预编译语句（Prepared Statement）是 Flight SQL 中流程最完整、状态管理最复杂的部分，涉及DoAction、DoPut、GetFlightInfo/GetSchema四种 RPC 的组合。

创建：ActionCreatePreparedStatementRequest

通过DoAction发送ActionCreatePreparedStatementRequest（proto 定义，query为 SQL 文本，可带transaction_id；另有 Substrait 变体 ActionCreatePreparedSubstraitPlanRequest）。

响应为 ActionCreatePreparedStatementResult，包含三个字段：

• prepared_statement_handle：服务端返回的不透明句柄，用于后续标识该预编译语句；
• dataset_schema：结果集 Schema 的 IPC 封装（来自 Schema.fbs）；
• parameter_schema：绑定参数的 Schema（若有）。

协议在此给出两条重要提示：

1. 由于结果集 Schema 可能依赖绑定参数，dataset_schema只是服务端的"最佳猜测"，客户端不得假定该 Schema 与最终实际返回的数据一致；
2. 对于无具体类型的绑定参数（如SELECT ?），协议目前未规定参数 Schema 的表示方式，建议服务端使用 union 类型枚举可能的类型，或用 NA（null）类型作为通配/占位。

绑定参数与执行：CommandPreparedStatementQuery

CommandPreparedStatementQuery（proto 定义，仅含prepared_statement_handle）有三种用法：

• DoPut：向预编译语句绑定参数值，可选的响应消息 DoPutPreparedStatementResult 中可能返回更新后的句柄（prepared_statement_handle）。更新句柄机制的意义在于支持无状态服务：服务端可以把已绑定的参数编码进新句柄，客户端后续请求都携带新句柄。一旦收到新句柄，所有旧句柄立即失效。值得注意的是，DoPut 返回的句柄本身可以再次传给下一次 DoPut 以绑定新参数集，服务端负责检测客户端未使用更新句柄的情况并返回错误；
• GetFlightInfo：执行预编译语句并取回结果，语句执行后可以复用；
• GetSchema：获取结果集预期 Schema；若客户端此前已通过 DoPut 绑定参数，服务端应将参数值纳入考虑。

无结果执行与关闭

• CommandPreparedStatementUpdate（proto 定义）：执行不返回结果的预编译语句。DoPut时执行并返回受影响行数，语句可复用；
• ActionClosePreparedStatementRequest（proto 定义）：关闭预编译语句并释放服务端资源。可通过FLIGHT_SQL_SERVER_STATEMENT_TIMEOUT（SqlInfo ID=100）查询/控制句柄超时（0 表示无超时，句柄被使用时服务端应重置计时）。

完整调用链时序见 CommandPreparedStatementQuery.mmd：DoAction(CreatePreparedStatementRequest)→Result{handle}→ 对每次执行循环DoPut(CommandPreparedStatementQuery)+ FlightData 流 →（可选）DoPutPreparedStatementResult{handle}→GetFlightInfo(CommandPreparedStatementQuery)→ 对每个 endpoint 执行DoGet(ticket)→ 最后DoAction(ClosePreparedStatementRequest)。

Java 客户端的prepare()方法返回PreparedStatement内部类（实现AutoCloseable），封装了上述全部流程（见 FlightSqlClient.java）。

事务与取消：相关 Action 命令

协议文件还定义了与查询生命周期配套的 Action 命令（事务能力是否支持可由 SqlInfo ID=8FLIGHT_SQL_SERVER_TRANSACTION查询，取值见 SqlSupportedTransaction）：

• ActionBeginTransactionRequest→ActionBeginTransactionResult（定义）：开启事务，返回不透明transaction_id；事务可被EndTransaction操作，超时自动回滚；
• ActionBeginSavepointRequest→ActionBeginSavepointResult（定义）：在事务内创建保存点，仅在服务端支持保存点时可用；
• ActionEndTransactionRequest（定义）：END_TRANSACTION_COMMIT(1) 提交或END_TRANSACTION_ROLLBACK(2) 回滚，成功后事务句柄及其全部保存点失效；
• ActionEndSavepointRequest（定义）：END_SAVEPOINT_RELEASE(1) 释放或END_SAVEPOINT_ROLLBACK(2) 回滚到保存点（回滚会使其后创建的保存点失效）。

Java 客户端对应方法为beginTransaction()、beginSavepoint()、commit()、rollback()（见 FlightSqlClient.java）。

另外，ActionCancelQueryRequest/ActionCancelQueryResult（proto 定义）提供显式取消运行中查询的能力（幂等），但其消息已标注deprecated（自 13.0.0 起），协议建议改用 Flight 核心协议中的CancelFlightInfoaction 配合DoAction使用。

Flight Server 会话管理：SetSessionOptions / GetSessionOptions / CloseSession

Flight SQL 提供会话管理命令，用于设置和更新影响服务端行为的会话变量，例如catalog与schema（当前查询针对的 catalog/schema）。三个命令的语义如下：

• SetSessionOptions：按名称/值设置服务端会话选项；
• GetSessionOptions：获取当前会话选项，包括客户端设置的以及服务端默认或隐式设置的；
• CloseSession：关闭并使当前会话上下文失效。

对应的消息定义位于 Flight 核心协议 format/Flight.proto（SetSessionOptionsRequest/GetSessionOptionsRequest/CloseSessionRequest等），Flight SQL 服务端与客户端直接复用。Java 客户端封装见 FlightSqlClient.java。

文档对会话使用给出了三条实践指导：

1. 尽早设置：客户端应尽可能在任何查询及其他命令之前设置选项，因为某些服务端实现要求选项恰好设置一次，且必须早于任何可能触发其隐式设置的活动；
2. 兼容 JDBC/ODBC 驱动：强烈建议服务端接受选项值的字符串表示，以便连接串中的参数无需转换即可透传；同时建议（非强制）接受其他数值类型并转换为选项的首选类型；
3. 会话持久化：会话在客户端与服务端之间通过实现定义机制保持，典型实现是RFC 6265 Cookie。服务端可以把其他连接状态与会话令牌不透明地捆绑在一起——在设计会话生命周期与语义时，应兼顾这些附加用途，例如CloseSession也应使通过会话上下文持久化的任何认证上下文失效。会话可由一次非空（或空）的SetSessionOptions调用触发，也可由服务端自选时机建立。

四个核心流程时序图

协议文档用四份 Mermaid 时序图（位于 docs/source/format/FlightSql/）直观刻画了典型交互流程：

1. CommandGetTables.mmd：列出可用表。GetFlightInfo(CommandGetTables)→FlightInfo{Ticket}→DoGet(Ticket)→ FlightData 数据流。这一模式适用于全部元数据命令；
2. CommandStatementQuery.mmd：执行即席查询。GetFlightInfo(CommandStatementQuery)→FlightInfo{endpoints:[FlightEndpoint,…]}→ 对每个 endpoint 循环DoGet(endpoint.ticket)拉取数据流——多 endpoint 意味着查询结果可以分布在多个数据流中（如分区/分片场景）；
3. CommandPreparedStatementQuery.mmd：预编译语句完整生命周期，即上文"预编译语句"一节的调用链；
4. CommandStatementIngest.mmd：批量导入。DoPut(CommandStatementIngest)+ FlightData 流 →PutResult{DoPutUpdateResult{RecordCount: int64}}。

仓库中的实现验证与后续阅读

协议在仓库中有多语言实现，其中 Java 实现最能体现上述全部约定：

• 客户端：FlightSqlClient.java 覆盖元数据查询、即席查询、更新、预编译语句、事务、会话管理全部 API；
• 服务端接口：FlightSqlProducer.java 定义服务端需实现的全部回调（含 SQL 元数据、预编译语句、导入、事务与会话管理），另有 BasicFlightSqlProducer.java 作为骨架实现，SqlInfoBuilder.java 用于构建 SqlInfo 返回数据。

其他语言的协议生成代码同样位于仓库中（如 Go 的github.com/apache/arrow/go/arrow/flight/gen/flight包、Python/C++/Ruby 等均有对应绑定）。若想深入理解底层 RPC 语义，可继续阅读 docs/source/format/Flight.rst（Flight RPC 框架）与 format/Flight.proto（核心消息定义）。

结语

Flight SQL 的设计精髓在于"协议最小化 + 复用最大化"：数据库只需实现规范规定的 RPC 端点，客户端即可获得统一的 SQL 交互能力；所有结果与元数据都以 Arrow 列式格式流动，消除了传统驱动层的行式转换瓶颈。无论是构建新的 SQL 数据库服务端、为现有数据库编写 Flight SQL 适配层，还是开发跨数据库的客户端工具，本文梳理的命令清单、消息封装约定与源码映射都能作为直接的实现参考。

• 数据工程
• 大数据
• 序列化
• 数据分析