Note
Flight is currently unstable. APIs are subject to change, though we donât expect drastic changes.
Common Types#An action to perform with the DoAction RPC.
Public Functions
Serialize this message to its wire-format representation.
Use SerializeToString() if you want a Result-returning version.
Public Members
The action type.
The action content as a Buffer.
Public Static Functions
Deserialize this message from its wire-format representation.
Use Deserialize(serialized) if you want a Result-returning version.
A type of action that can be performed with the DoAction RPC.
Public Functions
Serialize this message to its wire-format representation.
Use SerializeToString() if you want a Result-returning version.
Public Members
The name of the action.
A human-readable description of the action.
Public Static Functions
Deserialize this message from its wire-format representation.
Use Deserialize(serialized) if you want a Result-returning version.
A write-only wrapper around headers for an RPC call.
Public Functions
Add a header to be sent to the client.
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â.
Information about an instance of a Flight RPC.
Opaque selection criteria for ListFlights RPC.
Public Functions
Serialize this message to its wire-format representation.
Use SerializeToString() if you want a Result-returning version.
Public Members
Opaque criteria expression, dependent on server implementation.
Public Static Functions
Deserialize this message from its wire-format representation.
Use Deserialize(serialized) if you want a Result-returning version.
A request to retrieve or generate a dataset.
Public Functions
Get a human-readable form of this descriptor.
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
The descriptor type.
Opaque value used to express a command.
Should only be defined when type is CMD
List of strings identifying a particular dataset.
Should only be defined when type is PATH
Public Static Functions
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.
A flight ticket and list of locations where the ticket can be redeemed.
Public Functions
Serialize this message to its wire-format representation.
Use SerializeToString() if you want a Result-returning version.
Public Members
Opaque ticket identify; use with DoGet RPC.
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
Expiration time of this stream.
If present, clients may assume they can retry DoGet requests. Otherwise, clients should avoid retrying DoGet requests.
Opaque Application-defined metadata.
Public Static Functions
Deserialize this message from its wire-format representation.
Use Deserialize(serialized) if you want a Result-returning version.
The access coordinates for retrieval of a dataset, returned by GetFlightInfo.
Public Functions
Deserialize the Arrow schema of the dataset.
Populate any dictionary encoded fields into a DictionaryMemo for bookkeeping
dictionary_memo â [inout] for dictionary bookkeeping, will be modified
Arrow result with the reconstructed Schema. Note that the schema may be nullptr, as the schema is optional.
The descriptor associated with this flight, may not be set.
A list of endpoints associated with the flight (dataset).
To consume the whole flight, all endpoints must be consumed
The total number of records (rows) in the dataset. If unknown, set to -1.
The total number of bytes in the dataset. If unknown, set to -1.
Whether endpoints are in the same order as the data.
Application-defined opaque metadata.
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.
Compare two FlightInfo for equality.
This will compare the serialized schema representations, NOT the logical equality of the schemas.
Public Static Functions
Factory method to construct a FlightInfo.
Factory method to construct a FlightInfo.
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.
Staging data structure for messages about to be put on the wire.
This structure corresponds to FlightData in the protocol.
Public Functions
Check that the payload can be written to the wire.
An iterator to FlightInfo instances returned by ListFlights.
Subclassed by arrow::flight::SimpleFlightListing
Public Functions
Retrieve the next FlightInfo from the iterator.
Arrow result with a single FlightInfo. Set to nullptr if there are none left.
An enumeration of the RPC methods Flight implements.
Values:
A host location (a URI)
Public Functions
Initialize a blank location.
Get the scheme of this URI.
Get a representation of this URI as a string.
Serialize this message to its wire-format representation.
Use SerializeToString() if you want a Result-returning version.
Public Static Functions
Initialize a location by parsing a URI string.
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.
Initialize a location for a non-TLS, gRPC-based Flight service from a host and port.
host â [in] The hostname to connect to
port â [in] The port
Arrow result with the resulting location
Initialize a location for a TLS-enabled, gRPC-based Flight service from a host and port.
host â [in] The hostname to connect to
port â [in] The port
Arrow result with the resulting location
Initialize a location for a domain socket-based Flight service.
path â [in] The path to the domain socket
Arrow result with the resulting location
Initialize a location based on a URI scheme.
Deserialize this message from its wire-format representation.
Use Deserialize(serialized) if you want a Result-returning version.
An interface to read Flight data with metadata.
Subclassed by arrow::flight::FlightMessageReader, arrow::flight::FlightStreamReader
Public Functions
Get the schema for this stream.
Get the next message from Flight.
If the stream is finished, then the members of FlightStreamChunk will be nullptr.
Consume entire stream as a vector of record batches.
Consume entire stream as a Table.
Opaque result returned after executing an action.
Public Functions
Serialize this message to its wire-format representation.
Use SerializeToString() if you want a Result-returning version.
Public Static Functions
Deserialize this message from its wire-format representation.
Use Deserialize(serialized) if you want a Result-returning version.
An iterator to Result instances returned by DoAction.
Subclassed by arrow::flight::SimpleResultStream
Public Functions
Retrieve the next Result from the iterator.
Arrow result with a single Result. Set to nullptr if there are none left.
Read and drop the remaining messages to get the error (if any) from a server.
Status OK if this is no error from a server, any other status if a server returns an error.
Data structure providing an opaque identifier or credential to use when requesting a data stream with the DoGet RPC.
Public Functions
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
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.
Client class for Arrow Flight RPC services.
Public Functions
Authenticate to the server using the given handler.
options â [in] Per-RPC options
auth_handler â [in] The authentication mechanism to use
Status OK if the client authenticated successfully
Authenticate to the server using basic HTTP style authentication.
options â [in] Per-RPC options
username â [in] Username to use
password â [in] Password to use
Arrow result with bearer token and status OK if client authenticated successfully
Perform the indicated action, returning an iterator to the stream of results, if any.
options â [in] Per-RPC options
action â [in] the action to be performed
Arrow result with an iterator object for reading the returned results
Perform the CancelFlightInfo action, returning a CancelFlightInfoResult.
options â [in] Per-RPC options
request â [in] The CancelFlightInfoRequest
Arrow result with a CancelFlightInfoResult
Perform the RenewFlightEndpoint action, returning a renewed FlightEndpoint.
options â [in] Per-RPC options
request â [in] The RenewFlightEndpointRequest
Arrow result with a renewed FlightEndpoint
Retrieve a list of available Action types.
options â [in] Per-RPC options
Arrow result with the available actions
Request access plan for a single flight, which may be an existing dataset or a command to be executed.
options â [in] Per-RPC options
descriptor â [in] the dataset request, whether a named dataset or command
Arrow result with the FlightInfo describing where to access the dataset
Asynchronous GetFlightInfo.
options â [in] Per-RPC options
descriptor â [in] the dataset request
listener â [in] Callbacks for response and RPC completion
Asynchronous GetFlightInfo returning a Future.
options â [in] Per-RPC options
descriptor â [in] the dataset request
Request and poll a long running query.
options â [in] Per-RPC options
descriptor â [in] the dataset request or a descriptor returned by a prior PollFlightInfo call
Arrow result with the PollInfo describing the status of the requested query
Request schema for a single flight, which may be an existing dataset or a command to be executed.
options â [in] Per-RPC options
descriptor â [in] the dataset request, whether a named dataset or command
Arrow result with the SchemaResult describing the dataset schema
List all available flights known to the server.
Arrow result with an iterator that returns a FlightInfo for each flight
List available flights given indicated filter criteria.
options â [in] Per-RPC options
criteria â [in] the filter criteria (opaque)
Arrow result with an iterator that returns a FlightInfo for each flight
Given a flight ticket and schema, request to be sent the stream.
Returns record batch stream reader
options â [in] Per-RPC options
ticket â [in] The flight ticket to use
Arrow result with the returned RecordBatchReader
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.
options â [in] Per-RPC options
descriptor â [in] the descriptor of the stream
schema â [in] the schema for the data to upload
Arrow result with a DoPutResult struct holding a reader and a writer
Set server session option(s) by name/value.
Sessions are generally persisted via HTTP cookies.
options â [in] Per-RPC options
request â [in] The server session options to set
Get the current server session options.
The session is generally accessed via an HTTP cookie.
options â [in] Per-RPC options
request â [in] The (empty) GetSessionOptions request object.
Close/invalidate the current server session.
The session is generally accessed via an HTTP cookie.
options â [in] Per-RPC options
request â [in] The (empty) CloseSession request object.
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.
8.0.0
Whether this client supports asynchronous methods.
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
Connect to an unauthenticated flight service.
location â [in] the URI
Arrow result with the created FlightClient, OK status may not indicate that the connection was successful
Connect to an unauthenticated flight service.
location â [in] the URI
options â [in] Other options for setting up the client
Arrow result with the created FlightClient, OK status may not indicate that the connection was successful
DoPut return value.
Public Members
a writer to write record batches to
a reader for application metadata from the server
Public Members
Root certificates to use for validating server certificates.
Override the hostname checked by TLS. Use with caution.
The client certificate to use if using Mutual TLS.
The private key associated with the client certificate for Mutual TLS.
A list of client middleware to apply.
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.
Generic connection options, passed to the underlying transport; interpretation is implementation-dependent.
Use TLS without validating the server certificate. Use with caution.
Hints to the underlying RPC layer for Arrow Flight calls.
Public Functions
Create a default set of call options.
Public Members
An optional timeout for this call.
Negative durations mean an implementation-defined default behavior will be used instead. This is the default value.
IPC reader options, if applicable for the call.
IPC writer options, if applicable for the call.
Headers for client to add to context.
A token to enable interactive user cancellation of long-running requests.
An optional memory manager to control where to allocate incoming data.
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
Authenticate the client on initial connection.
The client can send messages to/read responses from the server at any time.
Status OK if authenticated successfully
Get a per-call token.
token â [out] The token to send to the server.
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
A callback before headers are sent.
Extra headers can be added, but existing ones cannot be read.
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.
A callback after the call has completed.
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
A callback for the start of a new call.
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.
A duration type for Flight call timeouts.
A RecordBatchReader exposing Flight metadata and cancel operations.
Public Functions
Try to cancel the call.
Consume entire stream as a vector of record batches.
Consume entire stream as a Table.
Consume entire stream as a vector of record batches.
Consume entire stream as a Table.
A RecordBatchWriter that also allows sending application-defined metadata via the Flight protocol.
Public Functions
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.
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
Initialize a Flight server listening at the given location.
This method must be called before any other method.
options â [in] The configuration for this server.
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).
Get the address that the Flight server is listening on.
This method must only be called after Init().
Set the server to stop when receiving any of the given signal numbers.
This method must be called before 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.
Query whether Serve() was interrupted by a signal.
This method must be called after Serve() has returned.
int the signal number that interrupted Serve(), if any, otherwise 0
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.
Block until server shuts down with Shutdown.
Does not respond to signals like Serve().
Retrieve a list of available fields given an optional opaque criteria.
context â [in] The call context.
criteria â [in] may be null
listings â [out] the returned listings iterator
Retrieve the schema and an access plan for the indicated descriptor.
context â [in] The call context.
request â [in] the dataset request, whether a named dataset or command
info â [out] the returned flight info provider
Retrieve the current status of the target query.
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
Retrieve the schema for the indicated descriptor.
context â [in] The call context.
request â [in] the dataset request, whether a named dataset or command
schema â [out] the returned flight schema provider
Get a stream of IPC payloads to put on the wire.
context â [in] The call context.
request â [in] an opaque ticket
stream â [out] the returned stream provider
Process a stream of IPC payloads sent from a client.
context â [in] The call context.
reader â [in] a sequence of uploaded record batches
writer â [in] send metadata back to the client
Process a bidirectional stream of IPC payloads.
context â [in] The call context.
reader â [in] a sequence of uploaded record batches
writer â [in] send data back to the client
Execute an action, return stream of zero or more results.
context â [in] The call context.
action â [in] the action to execute, with type and body
result â [out] the result iterator
Retrieve the list of available actions.
context â [in] The call context.
actions â [out] a vector of available action types
Public Members
The host & port (or domain socket path) to listen on.
Use port 0 to bind to an available port.
The authentication handler to use.
A list of TLS certificate+key pairs to use.
Enable mTLS and require that the client present a certificate.
If using mTLS, the PEM-encoded root certificate to use.
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.
An optional memory manager to control where to allocate incoming data.
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.
A TLS certificate plus key.
Public Members
The certificate in PEM format.
The key in PEM format.
Interface that produces a sequence of IPC payloads to be sent in FlightData protobuf messages.
Subclassed by arrow::flight::RecordBatchStream
A reader for IPC payloads uploaded by a client.
Also allows reading application-defined metadata via the Flight protocol.
Public Functions
Get the descriptor for this upload.
A writer for application-specific metadata sent back to the client during an upload.
Public Functions
Send a message to the client.
A basic implementation of FlightDataStream that will provide a sequence of FlightData messages to be written to a stream.
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
Authenticate the client on initial connection.
The server can send and read responses from the client at any time.
context â [in] The call context.
outgoing â [in] The writer for messages to the client.
incoming â [in] The reader for messages from the client.
Status OK if this authentication is succeeded.
Validate a per-call client token.
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.
Status OK if the token is valid, any other status if validation failed
Validate a per-call client token.
Deprecated in 13.0.0. Implement the IsValid() with ServerCallContext version instead.
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.
Status OK if the token is valid, any other status if validation failed
Call state/contextual data.
Public Functions
The name of the authenticated peer (may be the empty string)
The peer address (not validated)
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.
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.
Look up a middleware by key.
Do not maintain a reference to the object beyond the request body.
The middleware, or nullptr if not found.
Check if the current RPC has been cancelled (by the client, by a network error, etc.).
The headers sent by the client for this call.
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
Unique name of middleware, used as alternative to RTTI.
the string name of the middleware
A callback before headers are sent.
Extra headers can be added, but existing ones cannot be read.
A callback after the call has completed.
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
A callback for the start of a new call.
Return a non-OK status to reject the call with the given status.
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.
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.
A FlightListing implementation based on a vector of FlightInfo objects.
This can be iterated once, then it is consumed.
Public Functions
Retrieve the next FlightInfo from the iterator.
Arrow result with a single FlightInfo. Set to nullptr if there are none left.
A ResultStream implementation based on a vector of Result objects.
This can be iterated once, then it is consumed.
Public Functions
Error handling uses the normal arrow::Status class, combined with a custom arrow::StatusDetail object for Flight-specific error codes.
A Flight-specific status code.
Used to encode some additional status codes into an Arrow Status.
Values:
An implementation error has occurred.
A request timed out.
A request was cancelled.
We are not authenticated to the remote service.
We do not have permission to make this request.
The remote service cannot handle this request at the moment.
A request failed for some other reason.
Flight-specific error information in a Status.
Public Functions
Return a unique id for the type of the StatusDetail (effectively a poor manâs substitute for RTTI).
Produce a human-readable description of this status.
Get the Flight status code.
Get the extra error info.
Get the human-readable name of the status code.
Set the extra error info.
Make an appropriate Arrow status for the given Flight-specific status.
code â The Flight status code.
message â The message for the error.
extra_info â Optional extra binary info for the error (eg protobuf)
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.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4