Arrow Flight RPC

注意

Flight 目前尚不稳定。API 可能会有变动，尽管我们预计不会发生剧烈变更。

常见类型

struct Action : public arrow::flight::internal::BaseType<Action>

使用 DoAction RPC 执行的操作。

公共函数

arrow::Status SerializeToString(std::string *out) const

将此消息序列化为其在线传输格式的表示形式。

如果您需要返回 Result 的版本，请使用 SerializeToString()。

公共成员

std::string type

操作类型。

std::shared_ptr<Buffer> body

以 Buffer 形式表示的操作内容。

公共静态函数

static arrow::Status Deserialize(std::string_view serialized, Action *out)

从其在线传输格式表示中反序列化此消息。

如果您需要返回 Result 的版本，请使用 Deserialize(serialized)。

struct ActionType : public arrow::flight::internal::BaseType<ActionType>

可以使用 DoAction RPC 执行的操作类型。

公共函数

arrow::Status SerializeToString(std::string *out) const

将此消息序列化为其在线传输格式的表示形式。

如果您需要返回 Result 的版本，请使用 SerializeToString()。

公共成员

std::string type

操作名称。

std::string description

人类可读的操作描述。

公共静态函数

static arrow::Status Deserialize(std::string_view serialized, ActionType *out)

从其在线传输格式表示中反序列化此消息。

如果您需要返回 Result 的版本，请使用 Deserialize(serialized)。

class AddCallHeaders

针对 RPC 调用头部的只写包装器。

公共函数

virtual void AddHeader(const std::string &key, const std::string &value) = 0

添加要发送给客户端的头部。

参数:

• key – [in] 头部名称。必须是小写 ASCII 字符；某些传输协议可能会拒绝无效的头部名称。

• value – [in] 头部值。某些传输协议可能仅在头部名称以“-bin”结尾时接受二进制头部值。

struct CallInfo

关于 Flight RPC 实例的信息。

公共成员

FlightMethod method

此调用的 RPC 方法。

struct Criteria : public arrow::flight::internal::BaseType<Criteria>

用于 ListFlights RPC 的不透明选择标准。

公共函数

arrow::Status SerializeToString(std::string *out) const

将此消息序列化为其在线传输格式的表示形式。

如果您需要返回 Result 的版本，请使用 SerializeToString()。

公共成员

std::string expression

不透明的标准表达式，取决于服务器实现。

公共静态函数

static arrow::Status Deserialize(std::string_view serialized, Criteria *out)

从其在线传输格式表示中反序列化此消息。

如果您需要返回 Result 的版本，请使用 Deserialize(serialized)。

struct FlightDescriptor : public arrow::flight::internal::BaseType<FlightDescriptor>

用于检索或生成数据集的请求。

公共函数

std::string ToString() const

获取此描述符的人类可读形式。

arrow::Status SerializeToString(std::string *out) const

获取此类型的在线传输格式表示。

在与可能需要返回 Flight 类型的非 Flight 系统（例如 REST 服务）互操作时很有用。

如果您需要返回 Result 的版本，请使用 SerializeToString()。

公共成员

DescriptorType type = UNKNOWN

描述符类型。

std::string cmd

用于表示命令的不透明值。

仅当类型为 CMD 时才应定义。

std::vector<std::string> path

标识特定数据集的字符串列表。

仅当类型为 PATH 时才应定义。

公共静态函数

static arrow::Status Deserialize(std::string_view serialized, FlightDescriptor *out)

解析此类型的在线传输格式表示。

在与可能需要返回 Flight 类型的非 Flight 系统（例如 REST 服务）互操作时很有用。

如果您需要返回 Result 的版本，请使用 Deserialize(serialized)。

struct FlightEndpoint : public arrow::flight::internal::BaseType<FlightEndpoint>

Flight 票据以及可以兑换该票据的位置列表。

公共函数

arrow::Status SerializeToString(std::string *out) const

将此消息序列化为其在线传输格式的表示形式。

如果您需要返回 Result 的版本，请使用 SerializeToString()。

公共成员

Ticket ticket

不透明的票据标识；与 DoGet RPC 一起使用。

std::vector<Location> locations

可以兑换票据的位置列表。

如果列表为空，则票据只能在生成该票据的当前服务上兑换。

std::optional<Timestamp> expiration_time

此数据流的过期时间。

如果存在，客户端可以假设它们可以重试 DoGet 请求。否则，客户端应避免重试 DoGet 请求。

std::string app_metadata

应用程序定义的不透明元数据。

公共静态函数

static arrow::Status Deserialize(std::string_view serialized, FlightEndpoint *out)

从其在线传输格式表示中反序列化此消息。

如果您需要返回 Result 的版本，请使用 Deserialize(serialized)。

class FlightInfo : public arrow::flight::internal::BaseType<std::unique_ptr<FlightInfo>>

由 GetFlightInfo 返回的用于检索数据集的访问坐标。

公共函数

arrow::Result<std::shared_ptr<Schema>> GetSchema(ipc::DictionaryMemo *dictionary_memo) const

反序列化数据集的 Arrow Schema。

将任何字典编码字段填充到 DictionaryMemo 中以进行记账。

参数:

dictionary_memo – [inout] 用于字典记账，将被修改。

返回：

包含重构后的 Schema 的 Arrow 结果。请注意，Schema 可能为 nullptr，因为它是可选的。

inline const FlightDescriptor &descriptor() const

与此 flight 关联的描述符，可能未设置。

inline const std::vector<FlightEndpoint> &endpoints() const

与此 flight（数据集）关联的端点列表。

要使用整个 flight，必须使用所有端点。

inline int64_t total_records() const

数据集中的总记录数（行数）。如果未知，请设为 -1。

inline int64_t total_bytes() const

数据集中的总字节数。如果未知，请设为 -1。

inline bool ordered() const

端点是否与数据顺序一致。

inline const std::string &app_metadata() const

应用程序定义的不透明元数据。

arrow::Status SerializeToString(std::string *out) const

获取此类型的在线传输格式表示。

在与可能需要返回 Flight 类型的非 Flight 系统（例如 REST 服务）互操作时很有用。

如果您需要返回 Result 的版本，请使用 SerializeToString()。

bool Equals(const FlightInfo &other) const

比较两个 FlightInfo 是否相等。

这将比较序列化的 Schema 表示，而不是 Schema 的逻辑相等性。

公共静态函数

static arrow::Result<FlightInfo> Make(const Schema &schema, const FlightDescriptor &descriptor, const std::vector<FlightEndpoint> &endpoints, int64_t total_records, int64_t total_bytes, bool ordered = false, std::string app_metadata = "")

用于构建 FlightInfo 的工厂方法。

static arrow::Result<FlightInfo> Make(const std::shared_ptr<Schema> &schema, const FlightDescriptor &descriptor, const std::vector<FlightEndpoint> &endpoints, int64_t total_records, int64_t total_bytes, bool ordered = false, std::string app_metadata = "")

用于构建 FlightInfo 的工厂方法。

static arrow::Status Deserialize(std::string_view serialized, std::unique_ptr<FlightInfo> *out)

解析此类型的在线传输格式表示。

在与可能需要返回 Flight 类型的非 Flight 系统（例如 REST 服务）互操作时很有用。

如果您需要返回 Result 的版本，请使用 Deserialize(serialized)。

struct Data

struct FlightPayload

用于即将放入线路的消息的暂存数据结构。

此结构对应于协议中的 FlightData。

公共函数

Status Validate() const

检查有效载荷是否可以写入线路。

arrow::Result<BufferVector> SerializeToBuffers() const

将此有效载荷序列化为缓冲区向量。

class FlightListing

ListFlights 返回的 FlightInfo 实例的迭代器。

子类：arrow::flight::SimpleFlightListing

公共函数

virtual arrow::Result<std::unique_ptr<FlightInfo>> Next() = 0

从迭代器中检索下一个 FlightInfo。

返回：

包含单个 FlightInfo 的 Arrow 结果。如果没有剩余项，则设为 nullptr。

enum class arrow::flight::FlightMethod : char

Flight 实现的 RPC 方法枚举。

值

enumerator Invalid

enumerator Handshake

enumerator ListFlights

enumerator GetFlightInfo

enumerator GetSchema

enumerator DoGet

enumerator DoPut

enumerator DoAction

enumerator ListActions

enumerator DoExchange

enumerator PollFlightInfo

struct Location : public arrow::flight::internal::BaseType<Location>

主机位置（URI）。

公共函数

Location()

初始化一个空白位置。

std::string scheme() const

获取此 URI 的方案（scheme）。

std::string ToString() const

将此 URI 表示为字符串。

arrow::Status SerializeToString(std::string *out) const

将此消息序列化为其在线传输格式的表示形式。

如果您需要返回 Result 的版本，请使用 SerializeToString()。

公共静态函数

static arrow::Result<Location> Parse(const std::string &uri_string)

通过解析 URI 字符串初始化一个位置。

static const Location &ReuseConnection()

获取回退 URI。

arrow-flight-reuse-connection://? 表示客户端可以尝试重用现有的 Flight 服务连接来获取数据，而不是为 FlightEndpoint 响应中列出的其他位置之一创建新连接。

static arrow::Result<Location> ForGrpcTcp(const std::string &host, const int port)

从主机名和端口初始化非 TLS、基于 gRPC 的 Flight 服务的位置。

参数:

• host – [in] 要连接的主机名。

• port – [in] 端口。

返回：

包含结果位置的 Arrow 结果。

static arrow::Result<Location> ForGrpcTls(const std::string &host, const int port)

从主机名和端口初始化支持 TLS 的、基于 gRPC 的 Flight 服务的位置。

参数:

• host – [in] 要连接的主机名。

• port – [in] 端口。

返回：

包含结果位置的 Arrow 结果。

static arrow::Result<Location> ForGrpcUnix(const std::string &path)

初始化基于域套接字（domain socket）的 Flight 服务的位置。

参数:

path – [in] 域套接字的路径。

返回：

包含结果位置的 Arrow 结果。

static arrow::Result<Location> ForScheme(const std::string &scheme, const std::string &host, const int port)

根据 URI 方案初始化位置。

static arrow::Status Deserialize(std::string_view serialized, Location *out)

从其在线传输格式表示中反序列化此消息。

如果您需要返回 Result 的版本，请使用 Deserialize(serialized)。

class MetadataRecordBatchReader

用于读取带有元数据的 Flight 数据的接口。

子类包括 arrow::flight::FlightMessageReader, arrow::flight::FlightStreamReader

公共函数

virtual arrow::Result<std::shared_ptr<Schema>> GetSchema() = 0

获取此流的 Schema。

virtual arrow::Result<FlightStreamChunk> Next() = 0

从 Flight 获取下一条消息。

如果流已结束，则 FlightStreamChunk 的成员将为 nullptr。

virtual arrow::Result<std::vector<std::shared_ptr<RecordBatch>>> ToRecordBatches()

将整个流作为记录批次向量消耗。

virtual arrow::Result<std::shared_ptr<Table>> ToTable()

将整个流作为 Table 消耗。

virtual arrow::ipc::ReadStats stats() const = 0

返回当前的读取统计信息。

struct Result : public arrow::flight::internal::BaseType<Result>

执行操作后返回的不透明结果。

公共函数

arrow::Status SerializeToString(std::string *out) const

将此消息序列化为其在线传输格式的表示形式。

如果您需要返回 Result 的版本，请使用 SerializeToString()。

公共静态函数

static arrow::Status Deserialize(std::string_view serialized, Result *out)

从其在线传输格式表示中反序列化此消息。

如果您需要返回 Result 的版本，请使用 Deserialize(serialized)。

class ResultStream

一个指向 DoAction 返回的 Result 实例的迭代器。

子类包括 arrow::flight::SimpleResultStream

公共函数

virtual arrow::Result<std::unique_ptr<Result>> Next() = 0

从迭代器中检索下一个 Result。

返回：

包含单个 Result 的 Arrow 结果。如果没有剩余项，则设置为 nullptr。

Status Drain()

读取并丢弃剩余的消息，以从服务器获取错误（如有）。

返回：

如果服务器没有错误，则返回 Status OK；如果服务器返回错误，则返回任何其他状态。

struct Ticket : public arrow::flight::internal::BaseType<Ticket>

提供在通过 DoGet RPC 请求数据流时使用的不透明标识符或凭据的数据结构。

公共函数

arrow::Status SerializeToString(std::string *out) const

获取此类型的在线传输格式表示。

在与可能需要返回 Flight 类型的非 Flight 系统（例如 REST 服务）互操作时很有用。

如果您需要返回 Result 的版本，请使用 SerializeToString()。

公共静态函数

static arrow::Status Deserialize(std::string_view serialized, Ticket *out)

解析此类型的在线传输格式表示。

在与可能需要返回 Flight 类型的非 Flight 系统（例如 REST 服务）互操作时很有用。

如果您需要返回 Result 的版本，请使用 Deserialize(serialized)。

客户端

class FlightClient

用于 Arrow Flight RPC 服务的客户端类。

公共函数

Status Authenticate(const FlightCallOptions &options, std::unique_ptr<ClientAuthHandler> auth_handler)

使用给定的处理程序向服务器进行身份验证。

参数:

• options – [in] 每个 RPC 的选项

• auth_handler – [in] 要使用的身份验证机制

返回：

如果客户端身份验证成功，则返回 Status OK

arrow::Result<std::pair<std::string, std::string>> AuthenticateBasicToken(const FlightCallOptions &options, const std::string &username, const std::string &password)

使用基本 HTTP 样式身份验证向服务器进行身份验证。

参数:

• options – [in] 每个 RPC 的选项

• username – [in] 要使用的用户名

• password – [in] 要使用的密码

返回：

如果客户端身份验证成功，则返回带有 Bearer 令牌和状态 OK 的 Arrow 结果

arrow::Result<std::unique_ptr<ResultStream>> DoAction(const FlightCallOptions &options, const Action &action)

执行指定的操作，并返回结果流的迭代器（如有）。

参数:

• options – [in] 每个 RPC 的选项

• action – [in] 要执行的操作

返回：

返回带有用于读取结果的迭代器对象的 Arrow 结果

arrow::Result<CancelFlightInfoResult> CancelFlightInfo(const FlightCallOptions &options, const CancelFlightInfoRequest &request)

执行 CancelFlightInfo 操作，并返回 CancelFlightInfoResult。

参数:

• options – [in] 每个 RPC 的选项

• request – [in] CancelFlightInfoRequest

返回：

返回带有 CancelFlightInfoResult 的 Arrow 结果

arrow::Result<FlightEndpoint> RenewFlightEndpoint(const FlightCallOptions &options, const RenewFlightEndpointRequest &request)

执行 RenewFlightEndpoint 操作，并返回更新后的 FlightEndpoint。

参数:

• options – [in] 每个 RPC 的选项

• request – [in] RenewFlightEndpointRequest

返回：

返回带有更新后的 FlightEndpoint 的 Arrow 结果

arrow::Result<std::vector<ActionType>> ListActions(const FlightCallOptions &options)

检索可用 Action 类型的列表。

参数:

options – [in] 每个 RPC 的选项

返回：

返回包含可用操作的 Arrow 结果

arrow::Result<std::unique_ptr<FlightInfo>> GetFlightInfo(const FlightCallOptions &options, const FlightDescriptor &descriptor)

请求单个 Flight 的访问计划，这可以是一个现有的数据集或要执行的命令。

参数:

• options – [in] 每个 RPC 的选项

• descriptor – [in] 数据集请求，无论是命名数据集还是命令

返回：

返回带有 FlightInfo 的 Arrow 结果，该信息描述了如何访问数据集

void GetFlightInfoAsync(const FlightCallOptions &options, const FlightDescriptor &descriptor, std::shared_ptr<AsyncListener<FlightInfo>> listener)

异步 GetFlightInfo。

参数:

• options – [in] 每个 RPC 的选项

• descriptor – [in] 数据集请求

• listener – [in] 响应和 RPC 完成的回调

arrow::Future<FlightInfo> GetFlightInfoAsync(const FlightCallOptions &options, const FlightDescriptor &descriptor)

返回 Future 的异步 GetFlightInfo。

参数:

• options – [in] 每个 RPC 的选项

• descriptor – [in] 数据集请求

arrow::Result<std::unique_ptr<PollInfo>> PollFlightInfo(const FlightCallOptions &options, const FlightDescriptor &descriptor)

请求并轮询长时间运行的查询。

参数:

• options – [in] 每个 RPC 的选项

• descriptor – [in] 数据集请求或由之前的 PollFlightInfo 调用返回的描述符

返回：

返回带有描述请求查询状态的 PollInfo 的 Arrow 结果

arrow::Result<std::unique_ptr<SchemaResult>> GetSchema(const FlightCallOptions &options, const FlightDescriptor &descriptor)

请求单个 Flight 的 schema，这可以是一个现有的数据集或要执行的命令。

参数:

• options – [in] 每个 RPC 的选项

• descriptor – [in] 数据集请求，无论是命名数据集还是命令

返回：

返回带有描述数据集 schema 的 SchemaResult 的 Arrow 结果

arrow::Result<std::unique_ptr<FlightListing>> ListFlights()

列出服务器已知的所有可用 Flight。

返回：

返回带有迭代器的 Arrow 结果，该迭代器为每个 Flight 返回一个 FlightInfo

arrow::Result<std::unique_ptr<FlightListing>> ListFlights(const FlightCallOptions &options, const Criteria &criteria)

根据指定的过滤条件列出可用的 Flight。

参数:

• options – [in] 每个 RPC 的选项

• criteria – [in] 过滤条件（不透明）

返回：

返回带有迭代器的 Arrow 结果，该迭代器为每个 Flight 返回一个 FlightInfo

arrow::Result<std::unique_ptr<FlightStreamReader>> DoGet(const FlightCallOptions &options, const Ticket &ticket)

给定一个 Flight 票据和 schema，请求被发送流。

返回记录批次流读取器

参数:

• options – [in] 每个 RPC 的选项

• ticket – [in] 要使用的 Flight 票据

返回：

返回带有 RecordBatchReader 的 Arrow 结果

arrow::Result<DoPutResult> DoPut(const FlightCallOptions &options, const FlightDescriptor &descriptor, const std::shared_ptr<Schema> &schema)

将数据上传到由给定描述符描述的 Flight。

调用者在完成写入后，必须对返回的流调用 Close()。

读取器和写入器是链接在一起的；关闭写入器也会关闭读取器。使用 DoneWriting 仅关闭通道的写入侧。

参数:

• options – [in] 每个 RPC 的选项

• descriptor – [in] 流的描述符

• schema – [in] 要上传数据的 schema

返回：

返回带有包含读取器和写入器的 DoPutResult 结构体的 Arrow 结果

::arrow::Result<SetSessionOptionsResult> SetSessionOptions(const FlightCallOptions &options, const SetSessionOptionsRequest &request)

按名称/值设置服务器会话选项。

会话通常通过 HTTP Cookie 持久化。

参数:

• options – [in] 每个 RPC 的选项

• request – [in] 要设置的服务器会话选项

::arrow::Result<GetSessionOptionsResult> GetSessionOptions(const FlightCallOptions &options, const GetSessionOptionsRequest &request)

获取当前的服务器会话选项。

会话通常通过 HTTP Cookie 访问。

参数:

• options – [in] 每个 RPC 的选项

• request – [in] (空) GetSessionOptions 请求对象。

::arrow::Result<CloseSessionResult> CloseSession(const FlightCallOptions &options, const CloseSessionRequest &request)

关闭/使当前的服务器会话失效。

会话通常通过 HTTP Cookie 访问。

参数:

• options – [in] 每个 RPC 的选项

• request – [in] (空) CloseSession 请求对象。

Status Close()

显式关闭并清理客户端。

为了向后兼容，如果未显式调用，析构函数将隐式调用此方法，但这会让应用程序失去处理错误的机会，因此建议显式关闭客户端。

自

8.0.0

bool supports_async() const

此客户端是否支持异步方法。

Status CheckAsyncSupport() const

检查此客户端是否支持异步方法。

这类似于 supports_async()，不同之处在于，如果不支持异步，则会返回详细的错误消息。如果支持异步，此函数将成功返回。

公共静态函数

static arrow::Result<std::unique_ptr<FlightClient>> Connect(const Location &location)

连接到未经身份验证的 Flight 服务。

参数:

location – [in] URI

返回：

返回带有创建的 FlightClient 的 Arrow 结果，状态 OK 可能并不表示连接已成功

static arrow::Result<std::unique_ptr<FlightClient>> Connect(const Location &location, const FlightClientOptions &options)

连接到未经身份验证的 Flight 服务。

参数:

• location – [in] URI

• options – [in] 设置客户端的其他选项

返回：

返回带有创建的 FlightClient 的 Arrow 结果，状态 OK 可能并不表示连接已成功

struct DoExchangeResult

struct DoPutResult

DoPut 返回值。

公共成员

std::unique_ptr<FlightStreamWriter> writer

用于写入记录批次的写入器

std::unique_ptr<FlightMetadataReader> reader

用于从服务器读取应用程序元数据的读取器

struct FlightClientOptions

公共成员

std::string tls_root_certs

用于验证服务器证书的根证书。

std::string override_hostname

覆盖 TLS 检查的主机名。请谨慎使用。

std::string cert_chain

如果使用双向 TLS，则使用的客户端证书。

std::string private_key

用于双向 TLS 的客户端证书关联的私钥。

std::vector<std::shared_ptr<ClientMiddlewareFactory>> middleware

要应用的客户端中间件列表。

int64_t write_size_limit_bytes = 0

向服务器发送 Arrow 数据时，单批次写入字节数的软限制。

用于帮助限制服务器内存消耗。仅在正数时启用。启用后，FlightStreamWriter.Write* 可能会抛出带有 FlightWriteSizeStatusDetail 错误详情的 IOError。

std::vector<std::pair<std::string, std::variant<int, std::string>>> generic_options

通用连接选项，传递给底层传输层；其解释取决于具体实现。

bool disable_server_verification = false

使用 TLS 但不验证服务器证书。请谨慎使用。

公共静态函数

static FlightClientOptions Defaults()

获取默认选项。

class FlightCallOptions

为 Arrow Flight 调用提供给底层 RPC 层的提示。

公共函数

FlightCallOptions()

创建一组默认的调用选项。

公共成员

TimeoutDuration timeout

本次调用的可选超时时间。

负数持续时间表示将改用实现定义的默认行为。这是默认值。

ipc::IpcReadOptions read_options

IPC 读取选项（如果适用于该调用）。

ipc::IpcWriteOptions write_options

IPC 写入选项（如果适用于该调用）。

std::vector<std::pair<std::string, std::string>> headers

客户端添加到上下文的头部信息。

StopToken stop_token

用于实现长运行请求的交互式用户取消的令牌。

std::shared_ptr<MemoryManager> memory_manager

用于控制传入数据分配位置的可选内存管理器。

class ClientAuthHandler

Flight 服务的身份验证实现。

身份验证包括初始协商和针对每个调用的令牌验证。实现可以选择使用其中一种或两种机制。

公共函数

virtual Status Authenticate(ClientAuthSender *outgoing, ClientAuthReader *incoming) = 0

在初始连接时对客户端进行身份验证。

客户端可以随时向服务器发送消息或从服务器读取响应。

返回：

如果身份验证成功，返回 Status OK

virtual Status GetToken(std::string *token) = 0

获取每个调用的令牌。

参数:

token – [out] 发送给服务器的令牌。

class ClientMiddleware

用于调用的客户端中间件，每个 RPC 实例化一次。

中间件必须运行迅速且绝对可靠：中间件实例没有办法拒绝调用或报告错误。

公共函数

virtual void SendingHeaders(AddCallHeaders *outgoing_headers) = 0

发送头部信息之前的回调。

可以添加额外的头部信息，但无法读取已存在的头部信息。

virtual void ReceivedHeaders(const CallHeaders &incoming_headers) = 0

从服务器接收到头部信息时的回调。

该方法可能会被多次调用，因为服务器会发送头部信息和尾部信息。某些实现（例如 gRPC-Java，因此 Java 版 Arrow Flight）在 RPC 出错时可能会将头部信息合并到尾部信息中。

virtual void CallCompleted(const Status &status) = 0

调用完成后的回调。

class ClientMiddlewareFactory

新中间件实例的工厂。

如果添加到客户端，该工厂将被用于每个 RPC（包括握手），以提供拦截调用的机会。

保证所有客户端中间件方法都从调用 RPC 方法实现的同一线程调用。

公共函数

virtual void StartCall(const CallInfo &info, std::unique_ptr<ClientMiddleware> *middleware) = 0

新调用开始时的回调。

参数:

• info – 关于该调用的信息。

• middleware – [out] 此调用的中间件实例。如果未设置，将不会从此工厂向此调用实例添加中间件。

typedef std::chrono::duration<double, std::chrono::seconds::period> arrow::flight::TimeoutDuration

Flight 调用超时的持续时间类型。

class FlightStreamReader : public arrow::flight::MetadataRecordBatchReader

暴露 Flight 元数据和取消操作的 RecordBatchReader。

公共函数

virtual void Cancel() = 0

尝试取消调用。

virtual arrow::Result<std::vector<std::shared_ptr<RecordBatch>>> ToRecordBatches(const StopToken &stop_token) = 0

将整个流作为记录批次向量消耗。

arrow::Result<std::shared_ptr<Table>> ToTable(const StopToken &stop_token)

将整个流作为 Table 消耗。

virtual arrow::ipc::ReadStats stats() const = 0

返回当前的读取统计信息。

virtual arrow::Result<std::vector<std::shared_ptr<RecordBatch>>> ToRecordBatches()

将整个流作为记录批次向量消耗。

virtual arrow::Result<std::shared_ptr<Table>> ToTable()

将整个流作为 Table 消耗。

virtual arrow::ipc::ReadStats stats() const = 0

返回当前的读取统计信息。

class FlightStreamWriter : public arrow::flight::MetadataRecordBatchWriter

一个 RecordBatchWriter，还允许通过 Flight 协议发送应用程序定义的元数据。

公共函数

virtual Status DoneWriting() = 0

指示应用程序已完成对该流的写入。

调用此方法后，应用程序不得再向该流写入数据。这与关闭流不同，因为此写入器可能仅代表可读可写流的一半。

服务器

class FlightServerBase

RPC 服务器骨架实现，可通过实现其抽象方法来创建自定义服务器。

子类：arrow::flight::sql::FlightSqlServerBase

公共函数

Status Init(const FlightServerOptions &options)

初始化一个监听于给定位置的 Flight 服务器。

必须在调用任何其他方法之前调用此方法。

参数:

options – [in] 此服务器的配置。

int port() const

获取 Flight 服务器正在监听的端口。

此方法必须仅在 Init() 之后调用。如果不存在端口（例如在域套接字上监听时），将返回非正数值。

Location location() const

获取 Flight 服务器正在监听的地址。

此方法必须仅在 Init() 之后调用。

Status SetShutdownOnSignals(const std::vector<int> sigs)

设置服务器在接收到任何给定信号编号时停止。

此方法必须在 Serve() 之前调用。

Status Serve()

开始提供服务。

此方法会阻塞，直到服务器关闭。

服务器将在调用 Shutdown() 或收到在 SetShutdownOnSignals() 中注册的信号之一时开始关闭。

int GotSignal() const

查询 Serve() 是否被信号中断。

此方法必须在 Serve() 返回后调用。

返回：

int 中断 Serve() 的信号编号（如果有），否则为 0

Status Shutdown(const std::chrono::system_clock::time_point *deadline = NULLPTR)

关闭服务器，阻塞直到当前请求完成。

可以在 Serve() 阻塞时从信号处理程序或其他线程调用。可选设置最后期限。一旦最后期限过期，服务器将等待剩余的运行中调用完成。

应该只被调用一次。

Status Wait()

阻塞直到服务器通过 Shutdown 关闭。

不像 Serve() 那样响应信号。

virtual Status ListFlights(const ServerCallContext &context, const Criteria *criteria, std::unique_ptr<FlightListing> *listings)

检索给定可选不透明标准的可用字段列表。

参数:

• context – [in] 调用上下文。

• criteria – [in] 可以为空

• listings – [out] 返回的列表迭代器

返回：

Status（状态）

virtual Status GetFlightInfo(const ServerCallContext &context, const FlightDescriptor &request, std::unique_ptr<FlightInfo> *info)

为指定描述符检索模式和访问计划。

参数:

• context – [in] 调用上下文。

• request – [in] 数据集请求，无论是命名数据集还是命令

• info – [out] 返回的 flight info 提供程序

返回：

Status（状态）

virtual Status PollFlightInfo(const ServerCallContext &context, const FlightDescriptor &request, std::unique_ptr<PollInfo> *info)

检索目标查询的当前状态。

参数:

• context – [in] 调用上下文。

• request – [in] 数据集请求或由之前的 PollFlightInfo 调用返回的描述符

• info – [out] 返回的重试 info 提供程序

返回：

Status（状态）

virtual Status GetSchema(const ServerCallContext &context, const FlightDescriptor &request, std::unique_ptr<SchemaResult> *schema)

检索指定描述符的模式。

参数:

• context – [in] 调用上下文。

• request – [in] 数据集请求，无论是命名数据集还是命令

• schema – [out] 返回的 flight schema 提供程序

返回：

Status（状态）

virtual Status DoGet(const ServerCallContext &context, const Ticket &request, std::unique_ptr<FlightDataStream> *stream)

获取 IPC 有效负载流以在网络上传输。

参数:

• context – [in] 调用上下文。

• request – [in] 不透明票据

• stream – [out] 返回的流提供程序

返回：

Status（状态）

virtual Status DoPut(const ServerCallContext &context, std::unique_ptr<FlightMessageReader> reader, std::unique_ptr<FlightMetadataWriter> writer)

处理从客户端发送的 IPC 有效负载流。

参数:

• context – [in] 调用上下文。

• reader – [in] 一系列上传的记录批次

• writer – [in] 将元数据发送回客户端

返回：

Status（状态）

virtual Status DoExchange(const ServerCallContext &context, std::unique_ptr<FlightMessageReader> reader, std::unique_ptr<FlightMessageWriter> writer)

处理双向 IPC 有效负载流。

参数:

• context – [in] 调用上下文。

• reader – [in] 一系列上传的记录批次

• writer – [in] 将数据发送回客户端

返回：

Status（状态）

virtual Status DoAction(const ServerCallContext &context, const Action &action, std::unique_ptr<ResultStream> *result)

执行操作，返回零个或多个结果的流。

参数:

• context – [in] 调用上下文。

• action – [in] 要执行的操作，包含类型和正文

• result – [out] 结果迭代器

返回：

Status（状态）

virtual Status ListActions(const ServerCallContext &context, std::vector<ActionType> *actions)

检索可用操作的列表。

参数:

• context – [in] 调用上下文。

• actions – [out] 可用操作类型的向量

返回：

Status（状态）

class FlightServerOptions

公共成员

Location location

监听的主机和端口（或域套接字路径）。

使用端口 0 绑定到可用端口。

std::shared_ptr<ServerAuthHandler> auth_handler

使用的身份验证处理程序。

std::vector<CertKeyPair> tls_certificates

使用的 TLS 证书+密钥对列表。

bool verify_client

启用 mTLS 并要求客户端提供证书。

std::string root_certificates

如果使用 mTLS，使用的 PEM 编码的根证书。

std::vector<std::pair<std::string, std::shared_ptr<ServerMiddlewareFactory>>> middleware

要应用的服务器中间件列表，以及用于标识它们的键。

中间件总是按照提供的顺序应用。键重复是错误的。

std::shared_ptr<MemoryManager> memory_manager

用于控制传入数据分配位置的可选内存管理器。

std::function<void(void*)> builder_hook

一个特定于 Flight 实现的回调，用于自定义传输特定的选项。

不保证会被调用。参数类型特定于 Flight 实现。用户应确保链接到与 Flight 相同的传输实现，以避免运行时问题。更多详细信息，请参阅文档中的“在您自己的项目中使用 Arrow C++”。

struct CertKeyPair

TLS 证书和密钥。

公共成员

std::string pem_cert

PEM 格式的证书。

std::string pem_key

PEM 格式的密钥。

class FlightDataStream

用于生成 IPC 有效载荷序列的接口，该序列将在 FlightData protobuf 消息中发送。

子类：arrow::flight::RecordBatchStream

公共函数

virtual arrow::Result<FlightPayload> GetSchemaPayload() = 0

计算包含序列化 RecordBatch 模式的 FlightPayload。

class FlightMessageReader : public arrow::flight::MetadataRecordBatchReader

用于读取由客户端上传的 IPC 有效载荷的读取器。

还允许通过 Flight 协议读取应用程序定义的元数据。

公共函数

virtual const FlightDescriptor &descriptor() const = 0

获取此上传的描述符。

class FlightMetadataWriter

用于在上传过程中向客户端发送应用程序特定元数据的写入器。

公共函数

virtual Status WriteMetadata(const Buffer &app_metadata) = 0

向客户端发送消息。

class RecordBatchStream : public arrow::flight::FlightDataStream

FlightDataStream 的基本实现，它将提供一系列要写入流的 FlightData 消息。

公共函数

explicit RecordBatchStream(const std::shared_ptr<RecordBatchReader> &reader, const ipc::IpcWriteOptions &options = ipc::IpcWriteOptions::Defaults())

参数:

• reader – [输入] 生成记录批处理的序列

• options – [输入] 用于写入的 IPC 选项

virtual arrow::Result<FlightPayload> GetSchemaPayload() override

计算包含序列化 RecordBatch 模式的 FlightPayload。

virtual arrow::Result<FlightPayload> GetSchemaPayload() = 0

计算包含序列化 RecordBatch 模式的 FlightPayload。

class ServerAuthHandler

Flight 服务的身份验证实现。

身份验证既包括初始协商，也包括每次调用的令牌验证。实现可以选择使用其中一种或两种机制。实现可能需要跟踪某些状态，例如客户端令牌到已认证身份的映射。

子类：arrow::flight::NoOpAuthHandler

公共函数

virtual Status Authenticate(const ServerCallContext &context, ServerAuthSender *outgoing, ServerAuthReader *incoming) = 0

在初始连接时对客户端进行身份验证。

服务器可以随时发送和读取来自客户端的响应。

参数:

• context – [in] 调用上下文。

• outgoing – [输入] 向客户端发送消息的写入器。

• incoming – [输入] 从客户端读取消息的读取器。

返回：

如果身份验证成功，则返回 Status OK。

inline virtual Status IsValid(const ServerCallContext &context, const std::string &token, std::string *peer_identity)

验证每次调用的客户端令牌。

参数:

• context – [in] 调用上下文。

• token – [输入] 客户端令牌。如果客户端未提供令牌，则可能为空字符串。

• peer_identity – [输出] 对端的身份（如果此身份验证方法支持）。

返回：

如果令牌有效，则返回 Status OK；如果验证失败，则返回任何其他状态。

inline virtual Status IsValid(const std::string &token, std::string *peer_identity)

验证每次调用的客户端令牌。

已弃用

在 13.0.0 版本中已弃用。请改为实现带有 ServerCallContext 版本的 IsValid()。

参数:

• token – [输入] 客户端令牌。如果客户端未提供令牌，则可能为空字符串。

• peer_identity – [输出] 对端的身份（如果此身份验证方法支持）。

返回：

如果令牌有效，则返回 Status OK；如果验证失败，则返回任何其他状态。

class ServerCallContext

调用状态/上下文数据。

公共函数

virtual const std::string &peer_identity() const = 0

已认证对端的名称（可能是空字符串）

virtual const std::string &peer() const = 0

对端地址（未验证）

virtual void AddHeader(const std::string &key, const std::string &value) const = 0

添加响应头。

这仅在服务器开始发送响应之前有效；通常除非您自己实现 FlightDataStream、ResultStream 或类似接口，或者在 DoExchange 或 DoPut 期间，这通常不是问题。

virtual void AddTrailer(const std::string &key, const std::string &value) const = 0

添加响应尾部。

这仅在服务器发送最终状态之前有效；除非您的 RPC 处理程序启动线程或类似操作，否则这通常不是问题。

virtual ServerMiddleware *GetMiddleware(const std::string &key) const = 0

通过键查找中间件。

不要在请求主体之外维护对该对象的引用。

返回：

中间件，如果未找到则返回 nullptr。

virtual bool is_cancelled() const = 0

检查当前 RPC 是否已被取消（由客户端、网络错误等引起）。

virtual const CallHeaders &incoming_headers() const = 0

客户端为此调用发送的头文件。

class ServerMiddleware

调用的服务器端中间件，按 RPC 实例化。

中间件必须运行迅速且绝对可靠：中间件实例没有办法拒绝调用或报告错误。

子类：arrow::flight::TracingServerMiddleware, arrow::flight::sql::ServerSessionMiddleware

公共函数

virtual std::string name() const = 0

中间件的唯一名称，用作 RTTI 的替代方案。

返回：

中间件的字符串名称

virtual void SendingHeaders(AddCallHeaders *outgoing_headers) = 0

发送头部信息之前的回调。

可以添加额外的头部信息，但无法读取已存在的头部信息。

virtual void CallCompleted(const Status &status) = 0

调用完成后的回调。

class ServerMiddlewareFactory

新中间件实例的工厂。

如果添加到服务器，这将为每个 RPC（包括握手）调用，以提供拦截调用的机会。

保证所有服务器中间件方法都在调用 RPC 方法实现的同一线程中调用。

子类：arrow::flight::sql::ServerSessionMiddlewareFactory

公共函数

virtual Status StartCall(const CallInfo &info, const ServerCallContext &context, std::shared_ptr<ServerMiddleware> *middleware) = 0

新调用开始时的回调。

返回非 OK 状态以拒绝给定状态的调用。

参数:

• info – [输入] 关于调用的信息。

• context – [in] 调用上下文。

• middleware – [输出] 此调用的中间件实例。如果为空，则不会从此工厂将中间件添加到此调用实例中。

返回：

Status 非 OK 状态将拒绝给定状态的调用。之前链中的中间件将调用其 CallCompleted 回调。其他中间件工厂将不会被调用。

class SimpleFlightListing : public arrow::flight::FlightListing

基于 FlightInfo 对象向量的 FlightListing 实现。

这可以迭代一次，然后被消耗。

公共函数

virtual arrow::Result<std::unique_ptr<FlightInfo>> Next() override

从迭代器中检索下一个 FlightInfo。

返回：

包含单个 FlightInfo 的 Arrow 结果。如果没有剩余项，则设为 nullptr。

class SimpleResultStream : public arrow::flight::ResultStream

基于 Result 对象向量的 ResultStream 实现。

这可以迭代一次，然后被消耗。

公共函数

virtual arrow::Result<std::unique_ptr<Result>> Next() override

从迭代器中检索下一个 Result。

返回：

包含单个 Result 的 Arrow 结果。如果没有剩余项，则设置为 nullptr。

错误处理

错误处理使用普通的 arrow::Status 类，并结合用于 Flight 特定错误代码的自定义 arrow::StatusDetail 对象。

enum class arrow::flight::FlightStatusCode : int8_t

Flight 特定的状态代码。

用于将一些额外的状态代码编码到 Arrow Status 中。

值

enumerator Internal

发生了实现错误。

enumerator TimedOut

请求超时。

enumerator Cancelled

请求被取消。

enumerator Unauthenticated

我们未对远程服务进行身份验证。

enumerator Unauthorized

我们没有权限进行此请求。

enumerator Unavailable

远程服务目前无法处理此请求。

enumerator Failed

请求因其他原因失败。

class FlightStatusDetail : public arrow::StatusDetail

Status 中 Flight 特定的错误信息。

公共函数

virtual const char *type_id() const override

返回 StatusDetail 类型的唯一 ID（实际上是 RTTI 的拙劣替代品）。

virtual std::string ToString() const override

生成此状态的人类可读描述。

FlightStatusCode code() const

获取 Flight 状态代码。

std::string extra_info() const

获取额外的错误信息。

std::string CodeAsString() const

获取状态代码的人类可读名称。

void set_extra_info(std::string extra_info)

设置额外的错误信息。

公共静态函数

static std::shared_ptr<FlightStatusDetail> UnwrapStatus(const arrow::Status &status)

尝试从任何 Arrow 状态中提取 FlightStatusDetail。

返回：

如果可以解包则返回 FlightStatusDetail，否则返回 nullptr

Status arrow::flight::MakeFlightError(FlightStatusCode code, std::string message, std::string extra_info = {})

为给定的 Flight 特定状态制作适当的 Arrow 状态。

参数:

• code – Flight 状态代码。

• message – 错误消息。

• extra_info – 可选的错误额外二进制信息（例如 protobuf）

实现自定义传输

用于在 Flight 中实现替代网络传输的内部（但不是私有）接口。

要实现传输，请实现 ServerTransport 和 ClientTransport，并向 TransportRegistry 注册所需的 URI 方案。Flight 处理了大部分每个 RPC 的细节；传输仅处理连接并提供 I/O 流实现 (TransportDataStream)。

在服务器端

1. 应用程序继承 FlightServerBase 并重写 RPC 处理程序。

2. FlightServerBase::Init 将根据赋予它的 Location 方案查找并创建 ServerTransport。

3. ServerTransport 将启动实际的服务器。（例如，对于 gRPC，它创建一个 gRPC 服务器并注册一个 gRPC 服务。）该服务器将处理连接。

4. 传输应将传入的服务器调用转发到 ServerTransport 上定义的 RPC 处理程序，该处理程序使用此处的接口实现实际的 RPC 处理程序。RPC 处理程序需要的任何 I/O 都由传输特定的 TransportDataStream 实现管理。

5. ServerTransport 调用 FlightServerBase 以获取实际的应用程序逻辑。

在客户端

1. 应用程序使用 Location 创建 FlightClient。

2. FlightClient 将根据赋予它的 Location 方案查找并创建 ClientTransport。

3. 当在 FlightClient 上调用方法时，FlightClient 将委托给 ClientTransport。存在一些间接调用，例如对于 DoGet，FlightClient 仅请求 ClientTransport 启动调用并为其提供 I/O 流。“Flight 实现”本身仍然存在于 FlightClient 中。