Arrow Flight RPC#

Note

Flight is currently unstable. APIs are subject to change, though we don’t expect drastic changes.

Common Types#

structAction:publicarrow::flight::internal::BaseType<Action >#

An action to perform with the DoAction RPC.

Public Functions

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

Serialize this message to its wire-format representation.

Use SerializeToString() if you want a Result-returning version.

Public Members

std::stringtype#: The action type.

std::shared_ptr<Buffer >body#: The action content as a Buffer.

Public Static Functions

staticarrow::Status Deserialize(std::string_viewserialized, Action *out)#

Deserialize this message from its wire-format representation.

Use Deserialize(serialized) if you want a Result-returning version.

structActionType:publicarrow::flight::internal::BaseType<ActionType >#

A type of action that can be performed with the DoAction RPC.

Public Functions

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

Serialize this message to its wire-format representation.

Use SerializeToString() if you want a Result-returning version.

Public Members

std::stringtype#: The name of the action.

std::stringdescription#: A human-readable description of the action.

Public Static Functions

staticarrow::Status Deserialize(std::string_viewserialized, ActionType *out)#

Deserialize this message from its wire-format representation.

Use Deserialize(serialized) if you want a Result-returning version.

classAddCallHeaders#

A write-only wrapper around headers for an RPC call.

Public Functions

virtualvoidAddHeader(conststd::string&key, conststd::string&value)=0#

Add a header to be sent to the client.

Parameters:

key – [in] The header name. Must be lowercase ASCII; some transports may reject invalid header names.
value – [in] The header value. Some transports may only accept binary header values if the header name ends in "-bin".

structCallInfo#

Information about an instance of a Flight RPC.

Public Members

FlightMethod method#: The RPC method of this call.

structCriteria:publicarrow::flight::internal::BaseType<Criteria >#

Opaque selection criteria for ListFlights RPC.

Public Functions

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

Serialize this message to its wire-format representation.

Use SerializeToString() if you want a Result-returning version.

Public Members

std::stringexpression#: Opaque criteria expression, dependent on server implementation.

Public Static Functions

staticarrow::Status Deserialize(std::string_viewserialized, Criteria *out)#

Deserialize this message from its wire-format representation.

Use Deserialize(serialized) if you want a Result-returning version.

structFlightDescriptor:publicarrow::flight::internal::BaseType<FlightDescriptor >#

A request to retrieve or generate a dataset.

Public Functions

std::stringToString()const#: Get a human-readable form of this descriptor.

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

Get the wire-format representation of this type.

Useful when interoperating with non-Flight systems (e.g. REST services) that may want to return Flight types.

Use SerializeToString() if you want a Result-returning version.

Public Members

DescriptorTypetype=UNKNOWN#: The descriptor type.

std::stringcmd#

Opaque value used to express a command.

Should only be defined when type is CMD

std::vector<std::string>path#

List of strings identifying a particular dataset.

Should only be defined when type is PATH

Public Static Functions

staticarrow::Status Deserialize(std::string_viewserialized, FlightDescriptor *out)#

Parse the wire-format representation of this type.

Useful when interoperating with non-Flight systems (e.g. REST services) that may want to return Flight types.

Use Deserialize(serialized) if you want a Result-returning version.

structFlightEndpoint:publicarrow::flight::internal::BaseType<FlightEndpoint >#

A flight ticket and list of locations where the ticket can be redeemed.

Public Functions

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

Serialize this message to its wire-format representation.

Use SerializeToString() if you want a Result-returning version.

Public Members

Ticket ticket#: Opaque ticket identify; use with DoGet RPC.

std::vector<Location >locations#

List of locations where ticket can be redeemed.

If the list is empty, the ticket can only be redeemed on the current service where the ticket was generated

std::optional<Timestamp>expiration_time#

Expiration time of this stream.

If present, clients may assume they can retry DoGet requests. Otherwise, clients should avoid retrying DoGet requests.

std::stringapp_metadata#: Opaque Application-defined metadata.

Public Static Functions

staticarrow::Status Deserialize(std::string_viewserialized, FlightEndpoint *out)#

Deserialize this message from its wire-format representation.

Use Deserialize(serialized) if you want a Result-returning version.

classFlightInfo:publicarrow::flight::internal::BaseType<std::unique_ptr<FlightInfo >>#

The access coordinates for retrieval of a dataset, returned by GetFlightInfo.

Public Functions

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

Deserialize the Arrow schema of the dataset.

Populate any dictionary encoded fields into a DictionaryMemo for bookkeeping

Parameters:: dictionary_memo – [inout] for dictionary bookkeeping, will be modified
Returns:: Arrow result with the reconstructed Schema. Note that the schema may be nullptr, as the schema is optional.

inlineconstFlightDescriptor &descriptor()const#: The descriptor associated with this flight, may not be set.

inlineconststd::vector<FlightEndpoint >&endpoints()const#

A list of endpoints associated with the flight (dataset).

To consume the whole flight, all endpoints must be consumed

inlineint64_ttotal_records()const#: The total number of records (rows) in the dataset. If unknown, set to -1.

inlineint64_ttotal_bytes()const#: The total number of bytes in the dataset. If unknown, set to -1.

inlineboolordered()const#: Whether endpoints are in the same order as the data.

inlineconststd::string&app_metadata()const#: Application-defined opaque metadata.

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

Get the wire-format representation of this type.

Useful when interoperating with non-Flight systems (e.g. REST services) that may want to return Flight types.

Use SerializeToString() if you want a Result-returning version.

boolEquals(constFlightInfo &other)const#

Compare two FlightInfo for equality.

This will compare the serialized schema representations, NOT the logical equality of the schemas.

Public Static Functions

staticarrow::Result <FlightInfo >Make(constSchema &schema, constFlightDescriptor &descriptor, conststd::vector<FlightEndpoint >&endpoints, int64_ttotal_records, int64_ttotal_bytes, boolordered=false, std::stringapp_metadata="")#: Factory method to construct a FlightInfo.

staticarrow::Result <FlightInfo >Make(conststd::shared_ptr<Schema >&schema, constFlightDescriptor &descriptor, conststd::vector<FlightEndpoint >&endpoints, int64_ttotal_records, int64_ttotal_bytes, boolordered=false, std::stringapp_metadata="")#: Factory method to construct a FlightInfo.

staticarrow::Status Deserialize(std::string_viewserialized, std::unique_ptr<FlightInfo >*out)#

Parse the wire-format representation of this type.

Useful when interoperating with non-Flight systems (e.g. REST services) that may want to return Flight types.

Use Deserialize(serialized) if you want a Result-returning version.

structData#

structFlightPayload#

Staging data structure for messages about to be put on the wire.

This structure corresponds to FlightData in the protocol.

Public Functions

Status Validate()const#: Check that the payload can be written to the wire.

classFlightListing#

An iterator to FlightInfo instances returned by ListFlights.

Subclassed by arrow::flight::SimpleFlightListing

Public Functions

virtualarrow::Result <std::unique_ptr<FlightInfo >>Next()=0#

Retrieve the next FlightInfo from the iterator.

Returns:: Arrow result with a single FlightInfo. Set to nullptr if there are none left.

enumclassarrow::flight::FlightMethod:char#

An enumeration of the RPC methods Flight implements.

Values:

enumeratorInvalid#

enumeratorHandshake#

enumeratorListFlights#

enumeratorGetFlightInfo#

enumeratorGetSchema#

enumeratorDoGet#

enumeratorDoPut#

enumeratorDoAction#

enumeratorListActions#

enumeratorDoExchange#

enumeratorPollFlightInfo#

structLocation:publicarrow::flight::internal::BaseType<Location >#

A host location (a URI)

Public Functions

Location()#: Initialize a blank location.

std::stringscheme()const#: Get the scheme of this URI.

std::stringToString()const#: Get a representation of this URI as a string.

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

Serialize this message to its wire-format representation.

Use SerializeToString() if you want a Result-returning version.

Public Static Functions

staticarrow::Result <Location >Parse(conststd::string&uri_string)#: Initialize a location by parsing a URI string.

staticconstLocation &ReuseConnection()#

Get the fallback URI.

arrow-flight-reuse-connection://? means that a client may attempt to reuse an existing connection to a Flight service to fetch data instead of creating a new connection to one of the other locations listed in a FlightEndpoint response.

staticarrow::Result <Location >ForGrpcTcp(conststd::string&host, constintport)#

Initialize a location for a non-TLS, gRPC-based Flight service from a host and port.

Parameters:

host – [in] The hostname to connect to
port – [in] The port

Returns:

Arrow result with the resulting location

staticarrow::Result <Location >ForGrpcTls(conststd::string&host, constintport)#

Initialize a location for a TLS-enabled, gRPC-based Flight service from a host and port.

Parameters:

host – [in] The hostname to connect to
port – [in] The port

Returns:

Arrow result with the resulting location

staticarrow::Result <Location >ForGrpcUnix(conststd::string&path)#

Initialize a location for a domain socket-based Flight service.

Parameters:: path – [in] The path to the domain socket
Returns:: Arrow result with the resulting location

staticarrow::Result <Location >ForScheme(conststd::string&scheme, conststd::string&host, constintport)#: Initialize a location based on a URI scheme.

staticarrow::Status Deserialize(std::string_viewserialized, Location *out)#

Deserialize this message from its wire-format representation.

Use Deserialize(serialized) if you want a Result-returning version.

classMetadataRecordBatchReader#

An interface to read Flight data with metadata.

Subclassed by arrow::flight::FlightMessageReader, arrow::flight::FlightStreamReader

Public Functions

virtualarrow::Result <std::shared_ptr<Schema >>GetSchema()=0#: Get the schema for this stream.

virtualarrow::Result <FlightStreamChunk>Next()=0#

Get the next message from Flight.

If the stream is finished, then the members of FlightStreamChunk will be nullptr.

virtualarrow::Result <std::vector<std::shared_ptr<RecordBatch >>>ToRecordBatches()#: Consume entire stream as a vector of record batches.

virtualarrow::Result <std::shared_ptr<Table >>ToTable()#: Consume entire stream as a Table.

structResult:publicarrow::flight::internal::BaseType<Result >#

Opaque result returned after executing an action.

Public Functions

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

Serialize this message to its wire-format representation.

Use SerializeToString() if you want a Result-returning version.

Public Static Functions

staticarrow::Status Deserialize(std::string_viewserialized, Result *out)#

Deserialize this message from its wire-format representation.

Use Deserialize(serialized) if you want a Result-returning version.

classResultStream#

An iterator to Result instances returned by DoAction.

Subclassed by arrow::flight::SimpleResultStream

Public Functions

virtualarrow::Result <std::unique_ptr<Result >>Next()=0#

Retrieve the next Result from the iterator.

Returns:: Arrow result with a single Result. Set to nullptr if there are none left.

Status Drain()#

Read and drop the remaining messages to get the error (if any) from a server.

Returns:: Status OK if this is no error from a server, any other status if a server returns an error.

structTicket:publicarrow::flight::internal::BaseType<Ticket >#

Data structure providing an opaque identifier or credential to use when requesting a data stream with the DoGet RPC.

Public Functions

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

Get the wire-format representation of this type.

Useful when interoperating with non-Flight systems (e.g. REST services) that may want to return Flight types.

Use SerializeToString() if you want a Result-returning version.

Public Static Functions

staticarrow::Status Deserialize(std::string_viewserialized, Ticket *out)#

Parse the wire-format representation of this type.

Useful when interoperating with non-Flight systems (e.g. REST services) that may want to return Flight types.

Use Deserialize(serialized) if you want a Result-returning version.

Clients#

classFlightClient#

Client class for Arrow Flight RPC services.

Public Functions

Status Authenticate(constFlightCallOptions &options, std::unique_ptr<ClientAuthHandler >auth_handler)#

Authenticate to the server using the given handler.

Parameters:

options – [in] Per-RPC options
auth_handler – [in] The authentication mechanism to use

Returns:

Status OK if the client authenticated successfully

arrow::Result <std::pair<std::string,std::string>>AuthenticateBasicToken(constFlightCallOptions &options, conststd::string&username, conststd::string&password)#

Authenticate to the server using basic HTTP style authentication.

Parameters:

options – [in] Per-RPC options
username – [in] Username to use
password – [in] Password to use

Returns:

Arrow result with bearer token and status OK if client authenticated successfully

arrow::Result <std::unique_ptr<ResultStream >>DoAction(constFlightCallOptions &options, constAction &action)#

Perform the indicated action, returning an iterator to the stream of results, if any.

Parameters:

options – [in] Per-RPC options
action – [in] the action to be performed

Returns:

Arrow result with an iterator object for reading the returned results

arrow::Result <CancelFlightInfoResult>CancelFlightInfo(constFlightCallOptions &options, constCancelFlightInfoRequest&request)#

Perform the CancelFlightInfo action, returning a CancelFlightInfoResult.

Parameters:

options – [in] Per-RPC options
request – [in] The CancelFlightInfoRequest

Returns:

Arrow result with a CancelFlightInfoResult

arrow::Result <FlightEndpoint >RenewFlightEndpoint(constFlightCallOptions &options, constRenewFlightEndpointRequest&request)#

Perform the RenewFlightEndpoint action, returning a renewed FlightEndpoint.

Parameters:

options – [in] Per-RPC options
request – [in] The RenewFlightEndpointRequest

Returns:

Arrow result with a renewed FlightEndpoint

arrow::Result <std::vector<ActionType >>ListActions(constFlightCallOptions &options)#

Retrieve a list of available Action types.

Parameters:: options – [in] Per-RPC options
Returns:: Arrow result with the available actions

arrow::Result <std::unique_ptr<FlightInfo >>GetFlightInfo(constFlightCallOptions &options, constFlightDescriptor &descriptor)#

Request access plan for a single flight, which may be an existing dataset or a command to be executed.

Parameters:

options – [in] Per-RPC options
descriptor – [in] the dataset request, whether a named dataset or command

Returns:

Arrow result with the FlightInfo describing where to access the dataset

voidGetFlightInfoAsync(constFlightCallOptions &options, constFlightDescriptor &descriptor, std::shared_ptr<AsyncListener<FlightInfo >>listener)#

Asynchronous GetFlightInfo.

Parameters:

options – [in] Per-RPC options
descriptor – [in] the dataset request
listener – [in] Callbacks for response and RPC completion

arrow::Future <FlightInfo >GetFlightInfoAsync(constFlightCallOptions &options, constFlightDescriptor &descriptor)#

Asynchronous GetFlightInfo returning a Future.

Parameters:

options – [in] Per-RPC options
descriptor – [in] the dataset request

arrow::Result <std::unique_ptr<PollInfo>>PollFlightInfo(constFlightCallOptions &options, constFlightDescriptor &descriptor)#

Request and poll a long running query.

Parameters:

options – [in] Per-RPC options
descriptor – [in] the dataset request or a descriptor returned by a prior PollFlightInfo call

Returns:

Arrow result with the PollInfo describing the status of the requested query

arrow::Result <std::unique_ptr<SchemaResult>>GetSchema(constFlightCallOptions &options, constFlightDescriptor &descriptor)#

Request schema for a single flight, which may be an existing dataset or a command to be executed.

Parameters:

options – [in] Per-RPC options
descriptor – [in] the dataset request, whether a named dataset or command

Returns:

Arrow result with the SchemaResult describing the dataset schema

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

List all available flights known to the server.

Returns:: Arrow result with an iterator that returns a FlightInfo for each flight

arrow::Result <std::unique_ptr<FlightListing >>ListFlights(constFlightCallOptions &options, constCriteria &criteria)#

List available flights given indicated filter criteria.

Parameters:

options – [in] Per-RPC options
criteria – [in] the filter criteria (opaque)

Returns:

Arrow result with an iterator that returns a FlightInfo for each flight

arrow::Result <std::unique_ptr<FlightStreamReader >>DoGet(constFlightCallOptions &options, constTicket &ticket)#

Given a flight ticket and schema, request to be sent the stream.

Returns record batch stream reader

Parameters:

options – [in] Per-RPC options
ticket – [in] The flight ticket to use

Returns:

Arrow result with the returned RecordBatchReader

arrow::Result <DoPutResult >DoPut(constFlightCallOptions &options, constFlightDescriptor &descriptor, conststd::shared_ptr<Schema >&schema)#

Upload data to a Flight described by the given descriptor.

The caller must call Close() on the returned stream once they are done writing.

The reader and writer are linked; closing the writer will also close the reader. Use DoneWriting to only close the write side of the channel.

Parameters:

options – [in] Per-RPC options
descriptor – [in] the descriptor of the stream
schema – [in] the schema for the data to upload

Returns:

Arrow result with a DoPutResult struct holding a reader and a writer

::arrow::Result <SetSessionOptionsResult>SetSessionOptions(constFlightCallOptions &options, constSetSessionOptionsRequest&request)#

Set server session option(s) by name/value.

Sessions are generally persisted via HTTP cookies.

Parameters:

options – [in] Per-RPC options
request – [in] The server session options to set

::arrow::Result <GetSessionOptionsResult>GetSessionOptions(constFlightCallOptions &options, constGetSessionOptionsRequest&request)#

Get the current server session options.

The session is generally accessed via an HTTP cookie.

Parameters:

options – [in] Per-RPC options
request – [in] The (empty) GetSessionOptions request object.

::arrow::Result <CloseSessionResult>CloseSession(constFlightCallOptions &options, constCloseSessionRequest&request)#

Close/invalidate the current server session.

The session is generally accessed via an HTTP cookie.

Parameters:

options – [in] Per-RPC options
request – [in] The (empty) CloseSession request object.

Status Close()#

Explicitly shut down and clean up the client.

For backwards compatibility, this will be implicitly called by the destructor if not already called, but this gives the application no chance to handle errors, so it is recommended to explicitly close the client.

Since: 8.0.0

boolsupports_async()const#: Whether this client supports asynchronous methods.

Status CheckAsyncSupport()const#

Check whether this client supports asynchronous methods.

This is like supports_async(), except that a detailed error message is returned if async support is not available. If async support is available, this function returns successfully.

Public Static Functions

staticarrow::Result <std::unique_ptr<FlightClient >>Connect(constLocation &location)#

Connect to an unauthenticated flight service.

Parameters:: location – [in] the URI
Returns:: Arrow result with the created FlightClient, OK status may not indicate that the connection was successful

staticarrow::Result <std::unique_ptr<FlightClient >>Connect(constLocation &location, constFlightClientOptions &options)#

Connect to an unauthenticated flight service.

Parameters:

location – [in] the URI
options – [in] Other options for setting up the client

Returns:

Arrow result with the created FlightClient, OK status may not indicate that the connection was successful

structDoExchangeResult#

structDoPutResult#

DoPut return value.

Public Members

std::unique_ptr<FlightStreamWriter >writer#: a writer to write record batches to

std::unique_ptr<FlightMetadataReader>reader#: a reader for application metadata from the server

structFlightClientOptions#

Public Members

std::stringtls_root_certs#: Root certificates to use for validating server certificates.

std::stringoverride_hostname#: Override the hostname checked by TLS. Use with caution.

std::stringcert_chain#: The client certificate to use if using Mutual TLS.

std::stringprivate_key#: The private key associated with the client certificate for Mutual TLS.

std::vector<std::shared_ptr<ClientMiddlewareFactory >>middleware#: A list of client middleware to apply.

int64_twrite_size_limit_bytes=0#

A soft limit on the number of bytes to write in a single batch when sending Arrow data to a server.

Used to help limit server memory consumption. Only enabled if positive. When enabled, FlightStreamWriter.Write* may yield a IOError with error detail FlightWriteSizeStatusDetail.

std::vector<std::pair<std::string,std::variant<int,std::string>>>generic_options#: Generic connection options, passed to the underlying transport; interpretation is implementation-dependent.

booldisable_server_verification=false#: Use TLS without validating the server certificate. Use with caution.

Public Static Functions

staticFlightClientOptions Defaults()#: Get default options.

classFlightCallOptions#

Hints to the underlying RPC layer for Arrow Flight calls.

Public Functions

FlightCallOptions()#: Create a default set of call options.

Public Members

TimeoutDuration timeout#

An optional timeout for this call.

Negative durations mean an implementation-defined default behavior will be used instead. This is the default value.

ipc::IpcReadOptions read_options#: IPC reader options, if applicable for the call.

ipc::IpcWriteOptions write_options#: IPC writer options, if applicable for the call.

std::vector<std::pair<std::string,std::string>>headers#: Headers for client to add to context.

StopTokenstop_token#: A token to enable interactive user cancellation of long-running requests.

std::shared_ptr<MemoryManager >memory_manager#: An optional memory manager to control where to allocate incoming data.

classClientAuthHandler#

An authentication implementation for a Flight service.

Authentication includes both an initial negotiation and a per-call token validation. Implementations may choose to use either or both mechanisms.

Public Functions

virtualStatus Authenticate(ClientAuthSender*outgoing, ClientAuthReader*incoming)=0#

Authenticate the client on initial connection.

The client can send messages to/read responses from the server at any time.

Returns:: Status OK if authenticated successfully

virtualStatus GetToken(std::string*token)=0#

Get a per-call token.

Parameters:: token – [out] The token to send to the server.

classClientMiddleware#

Client-side middleware for a call, instantiated per RPC.

Middleware should be fast and must be infallible: there is no way to reject the call or report errors from the middleware instance.

Public Functions

virtualvoidSendingHeaders(AddCallHeaders *outgoing_headers)=0#

A callback before headers are sent.

Extra headers can be added, but existing ones cannot be read.

virtualvoidReceivedHeaders(constCallHeaders&incoming_headers)=0#

A callback when headers are received from the server.

This may be called more than once, since servers send both headers and trailers. Some implementations (e.g. gRPC-Java, and hence Arrow Flight in Java) may consolidate headers into trailers if the RPC errored.

virtualvoidCallCompleted(constStatus &status)=0#: A callback after the call has completed.

classClientMiddlewareFactory#

A factory for new middleware instances.

If added to a client, this will be called for each RPC (including Handshake) to give the opportunity to intercept the call.

It is guaranteed that all client middleware methods are called from the same thread that calls the RPC method implementation.

Public Functions

virtualvoidStartCall(constCallInfo &info, std::unique_ptr<ClientMiddleware >*middleware)=0#

A callback for the start of a new call.

Parameters:

info – Information about the call.
middleware – [out] The middleware instance for this call. If unset, will not add middleware to this call instance from this factory.

typedefstd::chrono::duration<double,std::chrono::seconds::period>arrow::flight::TimeoutDuration#: A duration type for Flight call timeouts.

classFlightStreamReader:publicarrow::flight::MetadataRecordBatchReader #

A RecordBatchReader exposing Flight metadata and cancel operations.

Public Functions

virtualvoidCancel()=0#: Try to cancel the call.

virtualarrow::Result <std::vector<std::shared_ptr<RecordBatch >>>ToRecordBatches(constStopToken&stop_token)=0#: Consume entire stream as a vector of record batches.

arrow::Result <std::shared_ptr<Table >>ToTable(constStopToken&stop_token)#: Consume entire stream as a Table.

virtualarrow::Result <std::vector<std::shared_ptr<RecordBatch >>>ToRecordBatches()#: Consume entire stream as a vector of record batches.

virtualarrow::Result <std::shared_ptr<Table >>ToTable()#: Consume entire stream as a Table.

classFlightStreamWriter:publicarrow::flight::MetadataRecordBatchWriter#

A RecordBatchWriter that also allows sending application-defined metadata via the Flight protocol.

Public Functions

virtualStatus DoneWriting()=0#

Indicate that the application is done writing to this stream.

The application may not write to this stream after calling this. This differs from closing the stream because this writer may represent only one half of a readable and writable stream.

Servers#

classFlightServerBase#

Skeleton RPC server implementation which can be used to create custom servers by implementing its abstract methods.

Subclassed by arrow::flight::sql::FlightSqlServerBase

Public Functions

Status Init(constFlightServerOptions &options)#

Initialize a Flight server listening at the given location.

This method must be called before any other method.

Parameters:: options – [in] The configuration for this server.

intport()const#

Get the port that the Flight server is listening on.

This method must only be called after Init(). Will return a non-positive value if no port exists (e.g. when listening on a domain socket).

Location location()const#

Get the address that the Flight server is listening on.

This method must only be called after Init().

Status SetShutdownOnSignals(conststd::vector<int>sigs)#

Set the server to stop when receiving any of the given signal numbers.

This method must be called before Serve().

Status Serve()#

Start serving.

This method blocks until the server shuts down.

The server will start to shut down when either Shutdown() is called or one of the signals registered in SetShutdownOnSignals() is received.

intGotSignal()const#

Query whether Serve() was interrupted by a signal.

This method must be called after Serve() has returned.

Returns:: int the signal number that interrupted Serve(), if any, otherwise 0

Status Shutdown(conststd::chrono::system_clock::time_point*deadline=NULLPTR)#

Shut down the server, blocking until current requests finish.

Can be called from a signal handler or another thread while Serve() blocks. Optionally a deadline can be set. Once the deadline expires server will wait until remaining running calls complete.

Should only be called once.

Status Wait()#

Block until server shuts down with Shutdown.

Does not respond to signals like Serve().

virtualStatus ListFlights(constServerCallContext &context, constCriteria *criteria, std::unique_ptr<FlightListing >*listings)#

Retrieve a list of available fields given an optional opaque criteria.

Parameters:

context – [in] The call context.
criteria – [in] may be null
listings – [out] the returned listings iterator

Returns:

Status

virtualStatus GetFlightInfo(constServerCallContext &context, constFlightDescriptor &request, std::unique_ptr<FlightInfo >*info)#

Retrieve the schema and an access plan for the indicated descriptor.

Parameters:

context – [in] The call context.
request – [in] the dataset request, whether a named dataset or command
info – [out] the returned flight info provider

Returns:

Status

virtualStatus PollFlightInfo(constServerCallContext &context, constFlightDescriptor &request, std::unique_ptr<PollInfo>*info)#

Retrieve the current status of the target query.

Parameters:

context – [in] The call context.
request – [in] the dataset request or a descriptor returned by a prior PollFlightInfo call
info – [out] the returned retry info provider

Returns:

Status

virtualStatus GetSchema(constServerCallContext &context, constFlightDescriptor &request, std::unique_ptr<SchemaResult>*schema)#

Retrieve the schema for the indicated descriptor.

Parameters:

context – [in] The call context.
request – [in] the dataset request, whether a named dataset or command
schema – [out] the returned flight schema provider

Returns:

Status

virtualStatus DoGet(constServerCallContext &context, constTicket &request, std::unique_ptr<FlightDataStream >*stream)#

Get a stream of IPC payloads to put on the wire.

Parameters:

context – [in] The call context.
request – [in] an opaque ticket
stream – [out] the returned stream provider

Returns:

Status

virtualStatus DoPut(constServerCallContext &context, std::unique_ptr<FlightMessageReader >reader, std::unique_ptr<FlightMetadataWriter >writer)#

Process a stream of IPC payloads sent from a client.

Parameters:

context – [in] The call context.
reader – [in] a sequence of uploaded record batches
writer – [in] send metadata back to the client

Returns:

Status

virtualStatus DoExchange(constServerCallContext &context, std::unique_ptr<FlightMessageReader >reader, std::unique_ptr<FlightMessageWriter>writer)#

Process a bidirectional stream of IPC payloads.

Parameters:

context – [in] The call context.
reader – [in] a sequence of uploaded record batches
writer – [in] send data back to the client

Returns:

Status

virtualStatus DoAction(constServerCallContext &context, constAction &action, std::unique_ptr<ResultStream >*result)#

Execute an action, return stream of zero or more results.

Parameters:

context – [in] The call context.
action – [in] the action to execute, with type and body
result – [out] the result iterator

Returns:

Status

virtualStatus ListActions(constServerCallContext &context, std::vector<ActionType >*actions)#

Retrieve the list of available actions.

Parameters:

context – [in] The call context.
actions – [out] a vector of available action types

Returns:

Status

classFlightServerOptions#

Public Members

Location location#

The host & port (or domain socket path) to listen on.

Use port 0 to bind to an available port.

std::shared_ptr<ServerAuthHandler >auth_handler#: The authentication handler to use.

std::vector<CertKeyPair >tls_certificates#: A list of TLS certificate+key pairs to use.

boolverify_client#: Enable mTLS and require that the client present a certificate.

std::stringroot_certificates#: If using mTLS, the PEM-encoded root certificate to use.

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

A list of server middleware to apply, along with a key to identify them by.

Middleware are always applied in the order provided. Duplicate keys are an error.

std::shared_ptr<MemoryManager >memory_manager#: An optional memory manager to control where to allocate incoming data.

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

A Flight implementation-specific callback to customize transport-specific options.

Not guaranteed to be called. The type of the parameter is specific to the Flight implementation. Users should take care to link to the same transport implementation as Flight to avoid runtime problems. See "Using Arrow C++ in your own project" in the documentation for more details.

structCertKeyPair#

A TLS certificate plus key.

Public Members

std::stringpem_cert#: The certificate in PEM format.

std::stringpem_key#: The key in PEM format.

classFlightDataStream#

Interface that produces a sequence of IPC payloads to be sent in FlightData protobuf messages.

Subclassed by arrow::flight::RecordBatchStream

Public Functions

virtualarrow::Result <FlightPayload >GetSchemaPayload()=0#: Compute FlightPayload containing serialized RecordBatch schema.

classFlightMessageReader:publicarrow::flight::MetadataRecordBatchReader #

A reader for IPC payloads uploaded by a client.

Also allows reading application-defined metadata via the Flight protocol.

Public Functions

virtualconstFlightDescriptor &descriptor()const=0#: Get the descriptor for this upload.

classFlightMetadataWriter#

A writer for application-specific metadata sent back to the client during an upload.

Public Functions

virtualStatus WriteMetadata(constBuffer &app_metadata)=0#: Send a message to the client.

classRecordBatchStream:publicarrow::flight::FlightDataStream #

A basic implementation of FlightDataStream that will provide a sequence of FlightData messages to be written to a stream.

Public Functions

explicitRecordBatchStream(conststd::shared_ptr<RecordBatchReader >&reader, constipc::IpcWriteOptions &options=ipc::IpcWriteOptions ::Defaults())#

Parameters:

reader – [in] produces a sequence of record batches
options – [in] IPC options for writing

virtualarrow::Result <FlightPayload >GetSchemaPayload()override#: Compute FlightPayload containing serialized RecordBatch schema.

virtualarrow::Result <FlightPayload >GetSchemaPayload()=0: Compute FlightPayload containing serialized RecordBatch schema.

classServerAuthHandler#

An authentication implementation for a Flight service.

Authentication includes both an initial negotiation and a per-call token validation. Implementations may choose to use either or both mechanisms. An implementation may need to track some state, e.g. a mapping of client tokens to authenticated identities.

Subclassed by arrow::flight::NoOpAuthHandler

Public Functions

virtualStatus Authenticate(constServerCallContext &context, ServerAuthSender*outgoing, ServerAuthReader*incoming)=0#

Authenticate the client on initial connection.

The server can send and read responses from the client at any time.

Parameters:

context – [in] The call context.
outgoing – [in] The writer for messages to the client.
incoming – [in] The reader for messages from the client.

Returns:

Status OK if this authentication is succeeded.

inlinevirtualStatus IsValid(constServerCallContext &context, conststd::string&token, std::string*peer_identity)#

Validate a per-call client token.

Parameters:

context – [in] The call context.
token – [in] The client token. May be the empty string if the client does not provide a token.
peer_identity – [out] The identity of the peer, if this authentication method supports it.

Returns:

Status OK if the token is valid, any other status if validation failed

inlinevirtualStatus IsValid(conststd::string&token, std::string*peer_identity)#

Validate a per-call client token.

Deprecated:: Deprecated in 13.0.0. Implement the IsValid() with ServerCallContext version instead.

Parameters:

token – [in] The client token. May be the empty string if the client does not provide a token.
peer_identity – [out] The identity of the peer, if this authentication method supports it.

Returns:

Status OK if the token is valid, any other status if validation failed

classServerCallContext#

Call state/contextual data.

Public Functions

virtualconststd::string&peer_identity()const=0#: The name of the authenticated peer (may be the empty string)

virtualconststd::string&peer()const=0#: The peer address (not validated)

virtualvoidAddHeader(conststd::string&key, conststd::string&value)const=0#

Add a response header.

This is only valid before the server starts sending the response; generally this isn’t an issue unless you are implementing FlightDataStream, ResultStream, or similar interfaces yourself, or during a DoExchange or DoPut.

virtualvoidAddTrailer(conststd::string&key, conststd::string&value)const=0#

Add a response trailer.

This is only valid before the server sends the final status; generally this isn’t an issue unless your RPC handler launches a thread or similar.

virtualServerMiddleware *GetMiddleware(conststd::string&key)const=0#

Look up a middleware by key.

Do not maintain a reference to the object beyond the request body.

Returns:: The middleware, or nullptr if not found.

virtualboolis_cancelled()const=0#: Check if the current RPC has been cancelled (by the client, by a network error, etc.).

virtualconstCallHeaders&incoming_headers()const=0#: The headers sent by the client for this call.

classServerMiddleware#

Server-side middleware for a call, instantiated per RPC.

Middleware should be fast and must be infallible: there is no way to reject the call or report errors from the middleware instance.

Subclassed by arrow::flight::TracingServerMiddleware, arrow::flight::sql::ServerSessionMiddleware

Public Functions

virtualstd::stringname()const=0#

Unique name of middleware, used as alternative to RTTI.

Returns:: the string name of the middleware

virtualvoidSendingHeaders(AddCallHeaders *outgoing_headers)=0#

A callback before headers are sent.

Extra headers can be added, but existing ones cannot be read.

virtualvoidCallCompleted(constStatus &status)=0#: A callback after the call has completed.

classServerMiddlewareFactory#

A factory for new middleware instances.

If added to a server, this will be called for each RPC (including Handshake) to give the opportunity to intercept the call.

It is guaranteed that all server middleware methods are called from the same thread that calls the RPC method implementation.

Subclassed by arrow::flight::sql::ServerSessionMiddlewareFactory

Public Functions

virtualStatus StartCall(constCallInfo &info, constServerCallContext &context, std::shared_ptr<ServerMiddleware >*middleware)=0#

A callback for the start of a new call.

Return a non-OK status to reject the call with the given status.

Parameters:

info – [in] Information about the call.
context – [in] The call context.
middleware – [out] The middleware instance for this call. If null, no middleware will be added to this call instance from this factory.

Returns:

Status A non-OK status will reject the call with the given status. Middleware previously in the chain will have their CallCompleted callback called. Other middleware factories will not be called.

classSimpleFlightListing:publicarrow::flight::FlightListing #

A FlightListing implementation based on a vector of FlightInfo objects.

This can be iterated once, then it is consumed.

Public Functions

virtualarrow::Result <std::unique_ptr<FlightInfo >>Next()override#

Retrieve the next FlightInfo from the iterator.

Returns:: Arrow result with a single FlightInfo. Set to nullptr if there are none left.

classSimpleResultStream:publicarrow::flight::ResultStream #

A ResultStream implementation based on a vector of Result objects.

This can be iterated once, then it is consumed.

Public Functions

virtualarrow::Result <std::unique_ptr<Result >>Next()override#

Retrieve the next Result from the iterator.

Returns:: Arrow result with a single Result. Set to nullptr if there are none left.

Error Handling#

Error handling uses the normal arrow::Status class, combined with a custom arrow::StatusDetail object for Flight-specific error codes.

enumclassarrow::flight::FlightStatusCode:int8_t#

A Flight-specific status code.

Used to encode some additional status codes into an Arrow Status.

Values:

enumeratorInternal#: An implementation error has occurred.

enumeratorTimedOut#: A request timed out.

enumeratorCancelled#: A request was cancelled.

enumeratorUnauthenticated#: We are not authenticated to the remote service.

enumeratorUnauthorized#: We do not have permission to make this request.

enumeratorUnavailable#: The remote service cannot handle this request at the moment.

enumeratorFailed#: A request failed for some other reason.

classFlightStatusDetail:publicarrow::StatusDetail #

Flight-specific error information in a Status.

Public Functions

virtualconstchar*type_id()constoverride#: Return a unique id for the type of the StatusDetail (effectively a poor man’s substitute for RTTI).

virtualstd::stringToString()constoverride#: Produce a human-readable description of this status.

FlightStatusCode code()const#: Get the Flight status code.

std::stringextra_info()const#: Get the extra error info.

std::stringCodeAsString()const#: Get the human-readable name of the status code.

voidset_extra_info(std::stringextra_info)#: Set the extra error info.

Public Static Functions

staticstd::shared_ptr<FlightStatusDetail >UnwrapStatus(constarrow::Status &status)#

Try to extract a FlightStatusDetail from any Arrow status.

Returns:: a FlightStatusDetail if it could be unwrapped, nullptr otherwise

Status arrow::flight::MakeFlightError(FlightStatusCode code, std::stringmessage, std::stringextra_info={})#

Make an appropriate Arrow status for the given Flight-specific status.

Parameters:

code – The Flight status code.
message – The message for the error.
extra_info – Optional extra binary info for the error (eg protobuf)

Implementing Custom Transports#

Internal (but not private) interface for implementing alternate network transports in Flight.

To implement a transport, implement ServerTransport and ClientTransport, and register the desired URI schemes with TransportRegistry. Flight takes care of most of the per-RPC details; transports only handle connections and providing a I/O stream implementation (TransportDataStream).

On the server side:

Applications subclass FlightServerBase and override RPC handlers.
FlightServerBase::Init will look up and create a ServerTransport based on the scheme of the Location given to it.
The ServerTransport will start the actual server. (For instance, for gRPC, it creates a gRPC server and registers a gRPC service.) That server will handle connections.
The transport should forward incoming calls to the server to the RPC handlers defined on ServerTransport, which implements the actual RPC handler using the interfaces here. Any I/O the RPC handler needs to do is managed by transport-specific implementations of TransportDataStream.
ServerTransport calls FlightServerBase for the actual application logic.

On the client side:

Applications create a FlightClient with a Location.
FlightClient will look up and create a ClientTransport based on the scheme of the Location given to it.
When calling a method on FlightClient, FlightClient will delegate to the ClientTransport. There is some indirection, e.g. for DoGet, FlightClient only requests that the ClientTransport start the call and provide it with an I/O stream. The "Flight implementation" itself still lives in FlightClient.