Apache Arrow Flight SQL C API 完整指南客户端、服务端与协议实现剖析【免费下载链接】arrowApache Arrow is the universal columnar format and multi-language toolbox for fast data interchange and in-memory analytics项目地址: https://gitcode.com/GitHub_Trending/arrow3/arrow本篇技术指南基于 Apache Arrow 仓库中的官方 C API 参考文档 docs/source/cpp/api/flightsql.rst 撰写系统讲解 Arrow Flight SQL 的 C 侧公共类型Common Types、客户端Client与服务端Server三大 API 区块并结合仓库源码cpp/src/arrow/flight/sql/与format/FlightSql.proto逐层剖析实现原理。读完本文你将掌握FlightSqlClient、PreparedStatement、FlightSqlServerBase、SqlSchema等核心类的完整用法理解 Flight SQL 协议中两阶段查询预编译语句事务与 Savepoint批量摄入等关键流程的底层调用链并能基于示例服务器快速搭建可运行的 Flight SQL 应用。一、文档定位Flight SQL 的 C API 参考骨架docs/source/cpp/api/flightsql.rst是 Apache Arrow C 文档中 Flight SQL 模块的 Doxygen 参考索引页。它以 RST 指令的形式把散落在头文件中的文档注释聚合为三个结构清晰的区块区块覆盖内容对应的 Doxygen 指令Common Types公共类型协议层公共类型与枚举doxygengroup:: flight-sql-common-typesClient客户端客户端 APIdoxygenclass:: FlightSqlClient、doxygenclass:: PreparedStatementServer服务端服务端 API 与协议消息doxygenclass:: FlightSqlServerBase、doxygenfunction:: CreateStatementQueryTicket、doxygenclass:: SqlSchema、doxygengroup:: flight-sql-protocol-messages换言之该文档是三大类 API 的入口页而真正的实现细节分布在cpp/src/arrow/flight/sql/目录下types.h公共类型、client.h/client.cc客户端、server.h/server.cc服务端以及由 format/FlightSql.proto 生成协议代码。下面按文档骨架依次深入。二、Common Types协议公共类型flight-sql-common-types公共类型定义在 cpp/src/arrow/flight/sql/types.h 中通过/// \defgroup flight-sql-common-types标记为同一组供客户端与服务端共享。2.1 SqlInfo 结果变体与结果映射GetSqlInfo端点返回的每条元数据都可能携带不同类型字符串、布尔、整数、字符串列表、映射表因此用 C17std::variant表达using SqlInfoResult std::variantstd::string, bool, int64_t, int32_t, std::vectorstd::string, std::unordered_mapint32_t, std::vectorint32_t; using SqlInfoResultMap std::unordered_mapint32_t, SqlInfoResult;SqlInfoResult覆盖了协议中全部五种取值形态SqlInfoResultMap以SqlInfo枚举值为键组织结果服务端通过RegisterSqlInfo(id, result)注册后即可在GetSqlInfo中返回。2.2 SqlInfoOptions完整的元数据枚举SqlInfoOptions::SqlInfo是协议元数据标识符的 C 映射与 format/FlightSql.proto 中的enum SqlInfo一一对应其取值范围与 ODBC 的SQLGetInfo()语义对齐Server Information值域 [0, 500)服务器基础信息。枚举值含义FLIGHT_SQL_SERVER_NAME 0服务器名称UTF-8 字符串FLIGHT_SQL_SERVER_VERSION 1服务器原生版本FLIGHT_SQL_SERVER_ARROW_VERSION 2服务器使用的 Arrow 格式版本FLIGHT_SQL_SERVER_READ_ONLY 3是否只读false可读写FLIGHT_SQL_SERVER_SQL 4是否支持执行 SQL 查询FLIGHT_SQL_SERVER_SUBSTRAIT 5是否支持执行 Substrait 计划FLIGHT_SQL_SERVER_SUBSTRAIT_MIN_VERSION 6/MAX_VERSION 7支持的 Substrait 版本区间不支持则为 nullFLIGHT_SQL_SERVER_TRANSACTION 8是否实现事务/保存点 RPC 端点见SqlSupportedTransactionFLIGHT_SQL_SERVER_CANCEL 9是否支持显式查询取消FLIGHT_SQL_SERVER_BULK_INGESTION 10是否支持批量摄入FLIGHT_SQL_SERVER_INGEST_TRANSACTIONS_SUPPORTED 11批量摄入是否支持事务FLIGHT_SQL_SERVER_STATEMENT_TIMEOUT 100预编译语句句柄超时毫秒0 表示无超时FLIGHT_SQL_SERVER_TRANSACTION_TIMEOUT 101事务超时毫秒0 表示无超时SQL Syntax Information值域 [500, 1000)SQL 语法与能力信息涵盖 DDL 能力SQL_DDL_CATALOG 500、SQL_DDL_SCHEMA 501、SQL_DDL_TABLE 502、标识符大小写敏感度SQL_IDENTIFIER_CASE 503、null 排序SQL_NULL_ORDERING 507、关键字/函数列表SQL_KEYWORDS 508至SQL_DATETIME_FUNCTIONS 512、各种连接与子查询能力SQL_SUPPORTED_UNIONS 540、SQL_SUPPORTED_SUBQUERIES 538、各类长度上限如SQL_MAX_COLUMN_NAME_LENGTH 543、SQL_MAX_ROW_SIZE 555以及事务隔离级别SQL_DEFAULT_TRANSACTION_ISOLATION 562、SQL_SUPPORTED_TRANSACTIONS_ISOLATION_LEVELS 564等 70 余项。协议规定 [0, 10000) 为保留值域自定义元数据 ID 应从 10000 开始。辅助枚举同一结构体内还定义了SqlSupportedTransactionNONE / TRANSACTION / SAVEPOINT、SqlSupportedCaseSensitivityUNKNOWN / CASE_INSENSITIVE / UPPERCASE、SqlNullOrderingHIGH / LOW / AT_START / AT_END以及SqlSupportsConvert从 BIGINT 到 VARCHAR 共 20 种 SQL 类型转换标识这些枚举被上面的 bitmask 型元数据如SQL_SUPPORTED_GRAMMAR 525、SQL_ANSI92_SUPPORTED_LEVEL 526、SQL_SUPPORTED_RESULT_SET_TYPES 567引用作为取值说明。2.3 其他公共类型TableRef由catalog、db_schema均为std::optionalstd::string和必填的table组成的表引用用于主键/外键查询端点。SubstraitPlan携带序列化计划plan与版本字符串version如 0.12.0是 Substrait 执行入口的参数类型。CancelResult查询取消结果枚举kUnspecified/kCancelled/kCancelling/kNotCancellable并重载了operator便于日志输出。TableDefinitionOptions及其两个子枚举控制批量摄入时目标表不存在kCreate/kFail与已存在kFail/kAppend/kReplace的行为。三、ClientFlightSqlClient 与 PreparedStatement客户端核心类FlightSqlClient定义在 cpp/src/arrow/flight/sql/client.h它包装一个 Flight 客户端以提供 Flight SQL RPC 调用源码注释原话内部持有std::shared_ptrFlightClient impl_通过构造函数注入explicit FlightSqlClient(std::shared_ptrFlightClient client);客户端 API 可归为五类查询执行、元数据发现、预编译语句、事务/保存点、会话与取消。3.1 查询执行Execute(options, query, transaction)执行返回结果集的 SQL 查询返回FlightInfo描述数据集的访问位置。从 client.cc 的实现可见查询会被打包为 protobufCommandStatementQuery再经PackProtoCommand编码进FlightDescriptor后调用底层GetFlightInfo。GetExecuteSchema(options, query, transaction)仅获取结果集 Schema不执行查询。ExecuteUpdate(options, query, transaction)执行 UPDATE/INSERT 等不返回结果集的语句返回受影响行数int64_t。其实现走DoPut通道以空 Schema 发起 DoPut服务端在元数据中回传DoPutUpdateResult客户端解析其中的record_count字段。Substrait 对应版本ExecuteSubstrait、GetExecuteSubstraitSchema、ExecuteSubstraitUpdate参数为SubstraitPlan。ExecuteIngest(options, reader, table_definition_options, table, schema, catalog, temporary, transaction, ingest_options)批量摄入——将RecordBatchReader中的数据流式写入服务端目标表返回摄入行数。实现中会把TableDefinitionOptions逐一映射为 protobuf 枚举如kAppend→TABLE_EXISTS_OPTION_APPEND再通过DoPut逐批写出。3.2 元数据发现FlightSqlClient提供与 JDBCDatabaseMetaData对齐的发现端点每个端点都配有一个GetXxxSchema变体用于提前获取返回 SchemaGetCatalogs列出 catalog。GetDbSchemas(catalog, db_schema_filter_pattern)按 catalog 与 schema 模式过滤列出数据库 schema。GetTables(catalog, db_schema_filter_pattern, table_filter_pattern, include_schema, table_types)列出表include_schema控制是否内嵌 Arrow Schema。GetTableTypes列出表类型如 TABLE、VIEW。GetXdbcTypeInfo/GetXdbcTypeInfo(data_type)查询支持的 SQL 数据类型信息可传data_type过滤。GetSqlInfo(sql_info)按 ID 列表查询服务器元数据。键相关GetPrimaryKeys、GetExportedKeys引用某表主键的外键列、GetImportedKeys某表的外键列、GetCrossReference(pk_table_ref, fk_table_ref)跨表外键引用参数均为TableRef。3.3 PreparedStatement预编译语句PreparedStatement是FlightSqlClient的友元类通常不直接构造而是通过FlightSqlClient::Prepare(options, query, transaction)或PrepareSubstrait创建。其典型生命周期如下创建客户端发送CreatePreparedStatementaction服务端返回数据集 Schema、参数 Schema 与句柄。绑定参数SetParameters(std::shared_ptrRecordBatch)或SetParameters(std::shared_ptrRecordBatchReader)绑定参数。实现上通过DoPut将参数批次上传见 client.cc 的BindParameters。执行Execute()返回FlightInfo查询类或ExecuteUpdate()返回受影响行数更新类。取 Schemadataset_schema()/parameter_schema()直接返回本地缓存GetSchema()可向服务端重新请求。关闭Close()显式释放服务端资源IsClosed()查询状态。析构函数会自动调用Close()但源码注释明确建议显式关闭——否则错误无法被捕获见 client.h 析构函数注释。3.4 事务与 Savepoint客户端以句柄类Transaction持有transaction_idis_valid()判断有效性和Savepoint持有savepoint_id暴露服务端事务能力no_transaction()返回一个空事务句柄作为默认自动提交语义的占位参数。BeginTransaction→TransactionBeginSavepoint(options, transaction, name)→Savepoint。Commit(options, transaction)提交后事务及关联 Savepoint 全部失效。Rollback(options, transaction)/Rollback(options, savepoint)回滚事务或仅回滚到某个 Savepoint后者仍有效但其后创建的 Savepoint 失效。Release(options, savepoint)释放 Savepoint。服务端是否实现这些 RPC 端点通过FLIGHT_SQL_SERVER_TRANSACTION 8元数据声明即使不实现数据库仍可能支持显式BEGIN TRANSACTION/COMMITSQL 语句对应SQL_TRANSACTIONS_SUPPORTED 563二者语义不同。3.5 取消、会话与其他CancelFlightInfo(options, request)显式取消某个 FlightInfo返回CancelFlightInfoResultCancelQuery自 13.0.0 起被弃用源码注释建议新客户端一律使用CancelFlightInfo。会话管理SetSessionOptions/GetSessionOptions/CloseSession直接透传到底层 FlightClient。RenewFlightEndpoint续期即将过期的 FlightEndpoint。DoGet(options, ticket)给定 Flight ticket 拉取结果流返回FlightStreamReaderDoPut、DoAction作为内部包装方法暴露给PreparedStatement使用标记为\internal不应直接调用。四、ServerFlightSqlServerBase 服务端实现服务端基类FlightSqlServerBase继承自FlightServerBase定义在 cpp/src/arrow/flight/sql/server.h其设计原则是应用程序应继承此类并重写其上声明的虚拟方法。同时该类把GetFlightInfo、DoGet、DoPut、DoAction、ListActions等 Flight RPC 处理器标记为final由框架实现协议分发——应用开发者只关心业务虚拟方法。4.1 查询的两阶段执行模型SQL 查询在 Flight SQL 中是典型的两阶段流程GetFlightInfoStatement(context, command, descriptor)接收StatementQuery含 SQL 与可选transaction_id返回描述数据集位置的FlightInfo。DoGetStatement(context, command)客户端用StatementQueryTicket内含服务端生成的statement_handle通过DoGet拉取实际数据流FlightDataStream。两阶段之间的桥梁是文档单独列出的工具函数CreateStatementQueryTicket(statement_handle)——服务端用它把语句句柄编码为不透明二进制 ticket定义于 server.h注释明确其供 Flight SQL 服务端实现使用。预编译语句同理GetFlightInfoPreparedStatementDoGetPreparedStatement。4.2 元数据端点GetFlightInfoXxx / DoGetXxx 成对出现服务端每个元数据端点都拆分为返回 FlightInfo与返回数据流两个虚拟方法与客户端GetXxx/DoGet一一对应catalogGetFlightInfoCatalogs/DoGetCatalogsschemaGetFlightInfoSchemas/DoGetDbSchemas参数GetDbSchemas表GetFlightInfoTables/DoGetTables参数GetTables支持 catalog、schema、表名模式过滤与include_schema表类型GetFlightInfoTableTypes/DoGetTableTypes类型信息GetFlightInfoXdbcTypeInfo/DoGetXdbcTypeInfo参数GetXdbcTypeInfo可带data_type过滤SQL 信息GetFlightInfoSqlInfo/DoGetSqlInfo参数GetSqlInfo携带 ID 列表键信息GetFlightInfoPrimaryKeys/DoGetPrimaryKeys、GetFlightInfoExportedKeys/DoGetExportedKeys、GetFlightInfoImportedKeys/DoGetImportedKeys、GetFlightInfoCrossReference/DoGetCrossReference4.3 写入与预编译语句端点DoPutCommandStatementUpdate/DoPutCommandSubstraitPlan执行更新类语句返回int64_t受影响行数对应客户端的ExecuteUpdate。CreatePreparedStatement/CreatePreparedSubstraitPlan创建预编译语句返回ActionCreatePreparedStatementResult数据集 Schema 参数 Schema 句柄。DoPutPreparedStatementQuery/DoPutPreparedStatementUpdate绑定参数并执行预编译语句前者通过FlightMessageReader/FlightMetadataWriter与客户端交互参数。ClosePreparedStatement释放句柄。DoPutCommandStatementIngest批量摄入入口对应客户端ExecuteIngest。4.4 事务 Action 与取消事务与保存点通过 Flight Action 机制暴露基类声明了对应的ActionType常量kBeginTransactionActionType、kBeginSavepointActionType、kEndTransactionActionType、kEndSavepointActionType、kCreatePreparedStatementActionType、kCreatePreparedSubstraitPlanActionType、kClosePreparedStatementActionType、kCancelQueryActionType自 13.0.0 起弃用改用通用CancelFlightInfo。对应虚拟方法BeginTransaction、BeginSavepoint、EndTransaction提交/回滚二选一、EndSavepoint释放/回滚二选一、CancelFlightInfo、RenewFlightEndpoint、会话三件套SetSessionOptions/GetSessionOptions/CloseSession。4.5 SqlSchema标准响应 SchemaSqlSchema提供所有元数据端点返回流的标准 Schema 模板服务端实现可据此保证与客户端GetXxxSchema预期一致客户端头文件多处注明应与SqlSchema::GetXxxSchema相同包括GetCatalogsSchema、GetDbSchemasSchema、GetTablesSchema、GetTablesSchemaWithIncludedSchema、GetTableTypesSchema、GetPrimaryKeysSchema、GetExportedKeysSchema、GetImportedKeysSchema、GetCrossReferenceSchema、GetXdbcTypeInfoSchema、GetSqlInfoSchema。4.6 协议消息组flight-sql-protocol-messages为避免在公共 API 中暴露 Protobuf 类型server.h 定义了一组轻量 struct 包装协议消息即文档中的doxygengroup:: flight-sql-protocol-messagesStatementQuery、StatementUpdate、StatementSubstraitPlan、StatementQueryTicket、PreparedStatementQuery、PreparedStatementUpdate、StatementIngest、GetSqlInfo、GetDbSchemas、GetTables、GetXdbcTypeInfo、GetPrimaryKeys、GetExportedKeys、GetImportedKeys、GetCrossReference以及各类 Action 请求/结果结构如ActionCreatePreparedStatementRequest、ActionCreatePreparedStatementResult。StatementQueryTicket还自带Deserialize静态方法用于从 ticket 还原。五、协议层FlightSql.proto 与构建配置5.1 协议定义Flight SQL 的线协议定义在 format/FlightSql.protopackage arrow.flight.protocol.sql包含CommandGetSqlInfo、CommandStatementQuery、CommandStatementUpdate、CommandStatementIngest、DoPutUpdateResult、ActionCreatePreparedStatementRequest等消息以及SqlInfo、SqlSupportedTransaction、SqlSupportedCaseSensitivity等枚举。它通过google.protobuf.Any嵌入 Flight 命令/动作载荷这就是客户端实现中PackProtoCommand/PackProtoAction/ReadResult的解析对象。5.2 构建与库产物CMakeLists.txt 显示该模块构建为独立的arrow_flight_sql库共享/静态包名ArrowFlightSqlpkg-config 名arrow-flight-sql并链接arrow_flight。构建期由 protoc 从format/FlightSql.proto生成FlightSql.pb.cc/.h。可用的构建开关包括ARROW_FLIGHT_SQL在 cpp/CMakePresets.json 的预设中默认置 ON以及可选的ARROW_FLIGHT_SQL_ODBC构建 ODBC 驱动层源码位于cpp/src/arrow/flight/sql/odbc/。开启测试/示例构建后ARROW_BUILD_TESTS或ARROW_BUILD_EXAMPLES会额外产出flight_sql_test基于 SQLite 的单元测试源码server_test.cc、server_session_middleware_internals_test.cc覆盖服务端协议与 Session 中间件。flight-sql-test-server与flight-sql-test-app分别基于test_server_cli.cc、test_app_cli.cc的测试服务器与测试客户端。当ARROW_COMPUTE、ARROW_PARQUET、ARROW_SUBSTRAIT同时开启时追加acero_test.cc与acero-flight-sql-server可执行文件基于 Acero 执行引擎的 SQL 服务器示例。六、参考实现SQLite 与 Acero 示例服务器仓库提供了两个可直接参考的完整服务端实现SQLite 示例example/sqlite_server.h 中的SQLiteFlightSqlServer基于内存 SQLite3 数据库实现重写了查询GetFlightInfoStatement/DoGetStatement、元数据catalogs/schemas/tables/table types/type info/keys、更新DoPutCommandStatementUpdate、预编译语句与事务BeginTransaction/EndTransaction等端点是理解如何子类化FlightSqlServerBase的最佳范本配套的sqlite_sql_info.cc、sqlite_type_info.cc展示了RegisterSqlInfo与类型信息的实际注册方式。Acero 示例example/acero_server.cc将 Flight SQL 协议接到 Arrow 的计算引擎 Acero 上展示了不使用传统数据库、直接基于 Arrow 计算图提供 SQL 能力的路径。七、从文档到实战快速上手路径阅读入口以 docs/source/cpp/api/flightsql.rst 为索引按公共类型 → 客户端 → 服务端的顺序阅读对应头文件types.h→client.h→server.h头文件中的 Doxygen 注释即官方文档正文。跑通示例按 CMakeLists.txt 的配置开启ARROW_FLIGHT_SQL构建flight-sql-test-server与flight-sql-test-app先用现成测试服务器体验Execute/GetSqlInfo/Prepare等调用需要计算能力时可构建acero-flight-sql-server。实现服务端继承FlightSqlServerBase参照SQLiteFlightSqlServer重写所需虚拟方法并用RegisterSqlInfo声明能力未重写的方法由基类返回未实现错误。客户端接入构造底层FlightClient后包装为FlightSqlClient用ExecuteDoGet完成两阶段查询用Prepare/SetParameters/Execute走预编译路径用BeginTransaction/Commit/Rollback管理事务。结语Flight SQL 的 C API 以FlightSqlClient客户端、FlightSqlServerBase服务端和一组共享公共类型为核心通过轻量 struct 包装 Protobuf 协议消息保持了 API 的整洁与协议的可演进性。本文所依据的 flightsql.rst 作为官方 API 索引配合types.h、client.h、server.h、client.cc与FlightSql.proto等源码构成了从会调用到懂原理的完整学习链路——无论是为现有数据库暴露 Flight SQL 接口还是基于 Arrow 计算引擎构建全新的 SQL 服务这套 API 都提供了开箱即用的基座。【免费下载链接】arrowApache Arrow is the universal columnar format and multi-language toolbox for fast data interchange and in-memory analytics项目地址: https://gitcode.com/GitHub_Trending/arrow3/arrow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Apache Arrow Flight SQL C API 完整指南客户端、服务端与协议实现剖析【免费下载链接】arrowApache Arrow is the universal columnar format and multi-language toolbox for fast data interchange and in-memory analytics项目地址: https://gitcode.com/GitHub_Trending/arrow3/arrow本篇技术指南基于 Apache Arrow 仓库中的官方 C API 参考文档 docs/source/cpp/api/flightsql.rst 撰写系统讲解 Arrow Flight SQL 的 C 侧公共类型Common Types、客户端Client与服务端Server三大 API 区块并结合仓库源码cpp/src/arrow/flight/sql/与format/FlightSql.proto逐层剖析实现原理。读完本文你将掌握FlightSqlClient、PreparedStatement、FlightSqlServerBase、SqlSchema等核心类的完整用法理解 Flight SQL 协议中两阶段查询预编译语句事务与 Savepoint批量摄入等关键流程的底层调用链并能基于示例服务器快速搭建可运行的 Flight SQL 应用。一、文档定位Flight SQL 的 C API 参考骨架docs/source/cpp/api/flightsql.rst是 Apache Arrow C 文档中 Flight SQL 模块的 Doxygen 参考索引页。它以 RST 指令的形式把散落在头文件中的文档注释聚合为三个结构清晰的区块区块覆盖内容对应的 Doxygen 指令Common Types公共类型协议层公共类型与枚举doxygengroup:: flight-sql-common-typesClient客户端客户端 APIdoxygenclass:: FlightSqlClient、doxygenclass:: PreparedStatementServer服务端服务端 API 与协议消息doxygenclass:: FlightSqlServerBase、doxygenfunction:: CreateStatementQueryTicket、doxygenclass:: SqlSchema、doxygengroup:: flight-sql-protocol-messages换言之该文档是三大类 API 的入口页而真正的实现细节分布在cpp/src/arrow/flight/sql/目录下types.h公共类型、client.h/client.cc客户端、server.h/server.cc服务端以及由 format/FlightSql.proto 生成协议代码。下面按文档骨架依次深入。二、Common Types协议公共类型flight-sql-common-types公共类型定义在 cpp/src/arrow/flight/sql/types.h 中通过/// \defgroup flight-sql-common-types标记为同一组供客户端与服务端共享。2.1 SqlInfo 结果变体与结果映射GetSqlInfo端点返回的每条元数据都可能携带不同类型字符串、布尔、整数、字符串列表、映射表因此用 C17std::variant表达using SqlInfoResult std::variantstd::string, bool, int64_t, int32_t, std::vectorstd::string, std::unordered_mapint32_t, std::vectorint32_t; using SqlInfoResultMap std::unordered_mapint32_t, SqlInfoResult;SqlInfoResult覆盖了协议中全部五种取值形态SqlInfoResultMap以SqlInfo枚举值为键组织结果服务端通过RegisterSqlInfo(id, result)注册后即可在GetSqlInfo中返回。2.2 SqlInfoOptions完整的元数据枚举SqlInfoOptions::SqlInfo是协议元数据标识符的 C 映射与 format/FlightSql.proto 中的enum SqlInfo一一对应其取值范围与 ODBC 的SQLGetInfo()语义对齐Server Information值域 [0, 500)服务器基础信息。枚举值含义FLIGHT_SQL_SERVER_NAME 0服务器名称UTF-8 字符串FLIGHT_SQL_SERVER_VERSION 1服务器原生版本FLIGHT_SQL_SERVER_ARROW_VERSION 2服务器使用的 Arrow 格式版本FLIGHT_SQL_SERVER_READ_ONLY 3是否只读false可读写FLIGHT_SQL_SERVER_SQL 4是否支持执行 SQL 查询FLIGHT_SQL_SERVER_SUBSTRAIT 5是否支持执行 Substrait 计划FLIGHT_SQL_SERVER_SUBSTRAIT_MIN_VERSION 6/MAX_VERSION 7支持的 Substrait 版本区间不支持则为 nullFLIGHT_SQL_SERVER_TRANSACTION 8是否实现事务/保存点 RPC 端点见SqlSupportedTransactionFLIGHT_SQL_SERVER_CANCEL 9是否支持显式查询取消FLIGHT_SQL_SERVER_BULK_INGESTION 10是否支持批量摄入FLIGHT_SQL_SERVER_INGEST_TRANSACTIONS_SUPPORTED 11批量摄入是否支持事务FLIGHT_SQL_SERVER_STATEMENT_TIMEOUT 100预编译语句句柄超时毫秒0 表示无超时FLIGHT_SQL_SERVER_TRANSACTION_TIMEOUT 101事务超时毫秒0 表示无超时SQL Syntax Information值域 [500, 1000)SQL 语法与能力信息涵盖 DDL 能力SQL_DDL_CATALOG 500、SQL_DDL_SCHEMA 501、SQL_DDL_TABLE 502、标识符大小写敏感度SQL_IDENTIFIER_CASE 503、null 排序SQL_NULL_ORDERING 507、关键字/函数列表SQL_KEYWORDS 508至SQL_DATETIME_FUNCTIONS 512、各种连接与子查询能力SQL_SUPPORTED_UNIONS 540、SQL_SUPPORTED_SUBQUERIES 538、各类长度上限如SQL_MAX_COLUMN_NAME_LENGTH 543、SQL_MAX_ROW_SIZE 555以及事务隔离级别SQL_DEFAULT_TRANSACTION_ISOLATION 562、SQL_SUPPORTED_TRANSACTIONS_ISOLATION_LEVELS 564等 70 余项。协议规定 [0, 10000) 为保留值域自定义元数据 ID 应从 10000 开始。辅助枚举同一结构体内还定义了SqlSupportedTransactionNONE / TRANSACTION / SAVEPOINT、SqlSupportedCaseSensitivityUNKNOWN / CASE_INSENSITIVE / UPPERCASE、SqlNullOrderingHIGH / LOW / AT_START / AT_END以及SqlSupportsConvert从 BIGINT 到 VARCHAR 共 20 种 SQL 类型转换标识这些枚举被上面的 bitmask 型元数据如SQL_SUPPORTED_GRAMMAR 525、SQL_ANSI92_SUPPORTED_LEVEL 526、SQL_SUPPORTED_RESULT_SET_TYPES 567引用作为取值说明。2.3 其他公共类型TableRef由catalog、db_schema均为std::optionalstd::string和必填的table组成的表引用用于主键/外键查询端点。SubstraitPlan携带序列化计划plan与版本字符串version如 0.12.0是 Substrait 执行入口的参数类型。CancelResult查询取消结果枚举kUnspecified/kCancelled/kCancelling/kNotCancellable并重载了operator便于日志输出。TableDefinitionOptions及其两个子枚举控制批量摄入时目标表不存在kCreate/kFail与已存在kFail/kAppend/kReplace的行为。三、ClientFlightSqlClient 与 PreparedStatement客户端核心类FlightSqlClient定义在 cpp/src/arrow/flight/sql/client.h它包装一个 Flight 客户端以提供 Flight SQL RPC 调用源码注释原话内部持有std::shared_ptrFlightClient impl_通过构造函数注入explicit FlightSqlClient(std::shared_ptrFlightClient client);客户端 API 可归为五类查询执行、元数据发现、预编译语句、事务/保存点、会话与取消。3.1 查询执行Execute(options, query, transaction)执行返回结果集的 SQL 查询返回FlightInfo描述数据集的访问位置。从 client.cc 的实现可见查询会被打包为 protobufCommandStatementQuery再经PackProtoCommand编码进FlightDescriptor后调用底层GetFlightInfo。GetExecuteSchema(options, query, transaction)仅获取结果集 Schema不执行查询。ExecuteUpdate(options, query, transaction)执行 UPDATE/INSERT 等不返回结果集的语句返回受影响行数int64_t。其实现走DoPut通道以空 Schema 发起 DoPut服务端在元数据中回传DoPutUpdateResult客户端解析其中的record_count字段。Substrait 对应版本ExecuteSubstrait、GetExecuteSubstraitSchema、ExecuteSubstraitUpdate参数为SubstraitPlan。ExecuteIngest(options, reader, table_definition_options, table, schema, catalog, temporary, transaction, ingest_options)批量摄入——将RecordBatchReader中的数据流式写入服务端目标表返回摄入行数。实现中会把TableDefinitionOptions逐一映射为 protobuf 枚举如kAppend→TABLE_EXISTS_OPTION_APPEND再通过DoPut逐批写出。3.2 元数据发现FlightSqlClient提供与 JDBCDatabaseMetaData对齐的发现端点每个端点都配有一个GetXxxSchema变体用于提前获取返回 SchemaGetCatalogs列出 catalog。GetDbSchemas(catalog, db_schema_filter_pattern)按 catalog 与 schema 模式过滤列出数据库 schema。GetTables(catalog, db_schema_filter_pattern, table_filter_pattern, include_schema, table_types)列出表include_schema控制是否内嵌 Arrow Schema。GetTableTypes列出表类型如 TABLE、VIEW。GetXdbcTypeInfo/GetXdbcTypeInfo(data_type)查询支持的 SQL 数据类型信息可传data_type过滤。GetSqlInfo(sql_info)按 ID 列表查询服务器元数据。键相关GetPrimaryKeys、GetExportedKeys引用某表主键的外键列、GetImportedKeys某表的外键列、GetCrossReference(pk_table_ref, fk_table_ref)跨表外键引用参数均为TableRef。3.3 PreparedStatement预编译语句PreparedStatement是FlightSqlClient的友元类通常不直接构造而是通过FlightSqlClient::Prepare(options, query, transaction)或PrepareSubstrait创建。其典型生命周期如下创建客户端发送CreatePreparedStatementaction服务端返回数据集 Schema、参数 Schema 与句柄。绑定参数SetParameters(std::shared_ptrRecordBatch)或SetParameters(std::shared_ptrRecordBatchReader)绑定参数。实现上通过DoPut将参数批次上传见 client.cc 的BindParameters。执行Execute()返回FlightInfo查询类或ExecuteUpdate()返回受影响行数更新类。取 Schemadataset_schema()/parameter_schema()直接返回本地缓存GetSchema()可向服务端重新请求。关闭Close()显式释放服务端资源IsClosed()查询状态。析构函数会自动调用Close()但源码注释明确建议显式关闭——否则错误无法被捕获见 client.h 析构函数注释。3.4 事务与 Savepoint客户端以句柄类Transaction持有transaction_idis_valid()判断有效性和Savepoint持有savepoint_id暴露服务端事务能力no_transaction()返回一个空事务句柄作为默认自动提交语义的占位参数。BeginTransaction→TransactionBeginSavepoint(options, transaction, name)→Savepoint。Commit(options, transaction)提交后事务及关联 Savepoint 全部失效。Rollback(options, transaction)/Rollback(options, savepoint)回滚事务或仅回滚到某个 Savepoint后者仍有效但其后创建的 Savepoint 失效。Release(options, savepoint)释放 Savepoint。服务端是否实现这些 RPC 端点通过FLIGHT_SQL_SERVER_TRANSACTION 8元数据声明即使不实现数据库仍可能支持显式BEGIN TRANSACTION/COMMITSQL 语句对应SQL_TRANSACTIONS_SUPPORTED 563二者语义不同。3.5 取消、会话与其他CancelFlightInfo(options, request)显式取消某个 FlightInfo返回CancelFlightInfoResultCancelQuery自 13.0.0 起被弃用源码注释建议新客户端一律使用CancelFlightInfo。会话管理SetSessionOptions/GetSessionOptions/CloseSession直接透传到底层 FlightClient。RenewFlightEndpoint续期即将过期的 FlightEndpoint。DoGet(options, ticket)给定 Flight ticket 拉取结果流返回FlightStreamReaderDoPut、DoAction作为内部包装方法暴露给PreparedStatement使用标记为\internal不应直接调用。四、ServerFlightSqlServerBase 服务端实现服务端基类FlightSqlServerBase继承自FlightServerBase定义在 cpp/src/arrow/flight/sql/server.h其设计原则是应用程序应继承此类并重写其上声明的虚拟方法。同时该类把GetFlightInfo、DoGet、DoPut、DoAction、ListActions等 Flight RPC 处理器标记为final由框架实现协议分发——应用开发者只关心业务虚拟方法。4.1 查询的两阶段执行模型SQL 查询在 Flight SQL 中是典型的两阶段流程GetFlightInfoStatement(context, command, descriptor)接收StatementQuery含 SQL 与可选transaction_id返回描述数据集位置的FlightInfo。DoGetStatement(context, command)客户端用StatementQueryTicket内含服务端生成的statement_handle通过DoGet拉取实际数据流FlightDataStream。两阶段之间的桥梁是文档单独列出的工具函数CreateStatementQueryTicket(statement_handle)——服务端用它把语句句柄编码为不透明二进制 ticket定义于 server.h注释明确其供 Flight SQL 服务端实现使用。预编译语句同理GetFlightInfoPreparedStatementDoGetPreparedStatement。4.2 元数据端点GetFlightInfoXxx / DoGetXxx 成对出现服务端每个元数据端点都拆分为返回 FlightInfo与返回数据流两个虚拟方法与客户端GetXxx/DoGet一一对应catalogGetFlightInfoCatalogs/DoGetCatalogsschemaGetFlightInfoSchemas/DoGetDbSchemas参数GetDbSchemas表GetFlightInfoTables/DoGetTables参数GetTables支持 catalog、schema、表名模式过滤与include_schema表类型GetFlightInfoTableTypes/DoGetTableTypes类型信息GetFlightInfoXdbcTypeInfo/DoGetXdbcTypeInfo参数GetXdbcTypeInfo可带data_type过滤SQL 信息GetFlightInfoSqlInfo/DoGetSqlInfo参数GetSqlInfo携带 ID 列表键信息GetFlightInfoPrimaryKeys/DoGetPrimaryKeys、GetFlightInfoExportedKeys/DoGetExportedKeys、GetFlightInfoImportedKeys/DoGetImportedKeys、GetFlightInfoCrossReference/DoGetCrossReference4.3 写入与预编译语句端点DoPutCommandStatementUpdate/DoPutCommandSubstraitPlan执行更新类语句返回int64_t受影响行数对应客户端的ExecuteUpdate。CreatePreparedStatement/CreatePreparedSubstraitPlan创建预编译语句返回ActionCreatePreparedStatementResult数据集 Schema 参数 Schema 句柄。DoPutPreparedStatementQuery/DoPutPreparedStatementUpdate绑定参数并执行预编译语句前者通过FlightMessageReader/FlightMetadataWriter与客户端交互参数。ClosePreparedStatement释放句柄。DoPutCommandStatementIngest批量摄入入口对应客户端ExecuteIngest。4.4 事务 Action 与取消事务与保存点通过 Flight Action 机制暴露基类声明了对应的ActionType常量kBeginTransactionActionType、kBeginSavepointActionType、kEndTransactionActionType、kEndSavepointActionType、kCreatePreparedStatementActionType、kCreatePreparedSubstraitPlanActionType、kClosePreparedStatementActionType、kCancelQueryActionType自 13.0.0 起弃用改用通用CancelFlightInfo。对应虚拟方法BeginTransaction、BeginSavepoint、EndTransaction提交/回滚二选一、EndSavepoint释放/回滚二选一、CancelFlightInfo、RenewFlightEndpoint、会话三件套SetSessionOptions/GetSessionOptions/CloseSession。4.5 SqlSchema标准响应 SchemaSqlSchema提供所有元数据端点返回流的标准 Schema 模板服务端实现可据此保证与客户端GetXxxSchema预期一致客户端头文件多处注明应与SqlSchema::GetXxxSchema相同包括GetCatalogsSchema、GetDbSchemasSchema、GetTablesSchema、GetTablesSchemaWithIncludedSchema、GetTableTypesSchema、GetPrimaryKeysSchema、GetExportedKeysSchema、GetImportedKeysSchema、GetCrossReferenceSchema、GetXdbcTypeInfoSchema、GetSqlInfoSchema。4.6 协议消息组flight-sql-protocol-messages为避免在公共 API 中暴露 Protobuf 类型server.h 定义了一组轻量 struct 包装协议消息即文档中的doxygengroup:: flight-sql-protocol-messagesStatementQuery、StatementUpdate、StatementSubstraitPlan、StatementQueryTicket、PreparedStatementQuery、PreparedStatementUpdate、StatementIngest、GetSqlInfo、GetDbSchemas、GetTables、GetXdbcTypeInfo、GetPrimaryKeys、GetExportedKeys、GetImportedKeys、GetCrossReference以及各类 Action 请求/结果结构如ActionCreatePreparedStatementRequest、ActionCreatePreparedStatementResult。StatementQueryTicket还自带Deserialize静态方法用于从 ticket 还原。五、协议层FlightSql.proto 与构建配置5.1 协议定义Flight SQL 的线协议定义在 format/FlightSql.protopackage arrow.flight.protocol.sql包含CommandGetSqlInfo、CommandStatementQuery、CommandStatementUpdate、CommandStatementIngest、DoPutUpdateResult、ActionCreatePreparedStatementRequest等消息以及SqlInfo、SqlSupportedTransaction、SqlSupportedCaseSensitivity等枚举。它通过google.protobuf.Any嵌入 Flight 命令/动作载荷这就是客户端实现中PackProtoCommand/PackProtoAction/ReadResult的解析对象。5.2 构建与库产物CMakeLists.txt 显示该模块构建为独立的arrow_flight_sql库共享/静态包名ArrowFlightSqlpkg-config 名arrow-flight-sql并链接arrow_flight。构建期由 protoc 从format/FlightSql.proto生成FlightSql.pb.cc/.h。可用的构建开关包括ARROW_FLIGHT_SQL在 cpp/CMakePresets.json 的预设中默认置 ON以及可选的ARROW_FLIGHT_SQL_ODBC构建 ODBC 驱动层源码位于cpp/src/arrow/flight/sql/odbc/。开启测试/示例构建后ARROW_BUILD_TESTS或ARROW_BUILD_EXAMPLES会额外产出flight_sql_test基于 SQLite 的单元测试源码server_test.cc、server_session_middleware_internals_test.cc覆盖服务端协议与 Session 中间件。flight-sql-test-server与flight-sql-test-app分别基于test_server_cli.cc、test_app_cli.cc的测试服务器与测试客户端。当ARROW_COMPUTE、ARROW_PARQUET、ARROW_SUBSTRAIT同时开启时追加acero_test.cc与acero-flight-sql-server可执行文件基于 Acero 执行引擎的 SQL 服务器示例。六、参考实现SQLite 与 Acero 示例服务器仓库提供了两个可直接参考的完整服务端实现SQLite 示例example/sqlite_server.h 中的SQLiteFlightSqlServer基于内存 SQLite3 数据库实现重写了查询GetFlightInfoStatement/DoGetStatement、元数据catalogs/schemas/tables/table types/type info/keys、更新DoPutCommandStatementUpdate、预编译语句与事务BeginTransaction/EndTransaction等端点是理解如何子类化FlightSqlServerBase的最佳范本配套的sqlite_sql_info.cc、sqlite_type_info.cc展示了RegisterSqlInfo与类型信息的实际注册方式。Acero 示例example/acero_server.cc将 Flight SQL 协议接到 Arrow 的计算引擎 Acero 上展示了不使用传统数据库、直接基于 Arrow 计算图提供 SQL 能力的路径。七、从文档到实战快速上手路径阅读入口以 docs/source/cpp/api/flightsql.rst 为索引按公共类型 → 客户端 → 服务端的顺序阅读对应头文件types.h→client.h→server.h头文件中的 Doxygen 注释即官方文档正文。跑通示例按 CMakeLists.txt 的配置开启ARROW_FLIGHT_SQL构建flight-sql-test-server与flight-sql-test-app先用现成测试服务器体验Execute/GetSqlInfo/Prepare等调用需要计算能力时可构建acero-flight-sql-server。实现服务端继承FlightSqlServerBase参照SQLiteFlightSqlServer重写所需虚拟方法并用RegisterSqlInfo声明能力未重写的方法由基类返回未实现错误。客户端接入构造底层FlightClient后包装为FlightSqlClient用ExecuteDoGet完成两阶段查询用Prepare/SetParameters/Execute走预编译路径用BeginTransaction/Commit/Rollback管理事务。结语Flight SQL 的 C API 以FlightSqlClient客户端、FlightSqlServerBase服务端和一组共享公共类型为核心通过轻量 struct 包装 Protobuf 协议消息保持了 API 的整洁与协议的可演进性。本文所依据的 flightsql.rst 作为官方 API 索引配合types.h、client.h、server.h、client.cc与FlightSql.proto等源码构成了从会调用到懂原理的完整学习链路——无论是为现有数据库暴露 Flight SQL 接口还是基于 Arrow 计算引擎构建全新的 SQL 服务这套 API 都提供了开箱即用的基座。【免费下载链接】arrowApache Arrow is the universal columnar format and multi-language toolbox for fast data interchange and in-memory analytics项目地址: https://gitcode.com/GitHub_Trending/arrow3/arrow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
