| /* |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the |
| * "License"); you may not use this file except in compliance |
| * with the License. You may obtain a copy of the License at |
| * <p> |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * <p> |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| syntax = "proto3"; |
| import "google/protobuf/timestamp.proto"; |
| |
| option java_package = "org.apache.arrow.flight.impl"; |
| option go_package = "github.com/apache/arrow/go/arrow/flight/gen/flight"; |
| option csharp_namespace = "Apache.Arrow.Flight.Protocol"; |
| |
| package arrow.flight.protocol; |
| |
| /* |
| * A flight service is an endpoint for retrieving or storing Arrow data. A |
| * flight service can expose one or more predefined endpoints that can be |
| * accessed using the Arrow Flight Protocol. Additionally, a flight service |
| * can expose a set of actions that are available. |
| */ |
| service FlightService { |
| |
| /* |
| * Handshake between client and server. Depending on the server, the |
| * handshake may be required to determine the token that should be used for |
| * future operations. Both request and response are streams to allow multiple |
| * round-trips depending on auth mechanism. |
| */ |
| rpc Handshake(stream HandshakeRequest) returns (stream HandshakeResponse) {} |
| |
| /* |
| * Get a list of available streams given a particular criteria. Most flight |
| * services will expose one or more streams that are readily available for |
| * retrieval. This api allows listing the streams available for |
| * consumption. A user can also provide a criteria. The criteria can limit |
| * the subset of streams that can be listed via this interface. Each flight |
| * service allows its own definition of how to consume criteria. |
| */ |
| rpc ListFlights(Criteria) returns (stream FlightInfo) {} |
| |
| /* |
| * For a given FlightDescriptor, get information about how the flight can be |
| * consumed. This is a useful interface if the consumer of the interface |
| * already can identify the specific flight to consume. This interface can |
| * also allow a consumer to generate a flight stream through a specified |
| * descriptor. For example, a flight descriptor might be something that |
| * includes a SQL statement or a Pickled Python operation that will be |
| * executed. In those cases, the descriptor will not be previously available |
| * within the list of available streams provided by ListFlights but will be |
| * available for consumption for the duration defined by the specific flight |
| * service. |
| */ |
| rpc GetFlightInfo(FlightDescriptor) returns (FlightInfo) {} |
| |
| /* |
| * For a given FlightDescriptor, start a query and get information |
| * to poll its execution status. This is a useful interface if the |
| * query may be a long-running query. The first PollFlightInfo call |
| * should return as quickly as possible. (GetFlightInfo doesn't |
| * return until the query is complete.) |
| * |
| * A client can consume any available results before |
| * the query is completed. See PollInfo.info for details. |
| * |
| * A client can poll the updated query status by calling |
| * PollFlightInfo() with PollInfo.flight_descriptor. A server |
| * should not respond until the result would be different from last |
| * time. That way, the client can "long poll" for updates |
| * without constantly making requests. Clients can set a short timeout |
| * to avoid blocking calls if desired. |
| * |
| * A client can't use PollInfo.flight_descriptor after |
| * PollInfo.expiration_time passes. A server might not accept the |
| * retry descriptor anymore and the query may be cancelled. |
| * |
| * A client may use the CancelFlightInfo action with |
| * PollInfo.info to cancel the running query. |
| */ |
| rpc PollFlightInfo(FlightDescriptor) returns (PollInfo) {} |
| |
| /* |
| * For a given FlightDescriptor, get the Schema as described in Schema.fbs::Schema |
| * This is used when a consumer needs the Schema of flight stream. Similar to |
| * GetFlightInfo this interface may generate a new flight that was not previously |
| * available in ListFlights. |
| */ |
| rpc GetSchema(FlightDescriptor) returns (SchemaResult) {} |
| |
| /* |
| * Retrieve a single stream associated with a particular descriptor |
| * associated with the referenced ticket. A Flight can be composed of one or |
| * more streams where each stream can be retrieved using a separate opaque |
| * ticket that the flight service uses for managing a collection of streams. |
| */ |
| rpc DoGet(Ticket) returns (stream FlightData) {} |
| |
| /* |
| * Push a stream to the flight service associated with a particular |
| * flight stream. This allows a client of a flight service to upload a stream |
| * of data. Depending on the particular flight service, a client consumer |
| * could be allowed to upload a single stream per descriptor or an unlimited |
| * number. In the latter, the service might implement a 'seal' action that |
| * can be applied to a descriptor once all streams are uploaded. |
| */ |
| rpc DoPut(stream FlightData) returns (stream PutResult) {} |
| |
| /* |
| * Open a bidirectional data channel for a given descriptor. This |
| * allows clients to send and receive arbitrary Arrow data and |
| * application-specific metadata in a single logical stream. In |
| * contrast to DoGet/DoPut, this is more suited for clients |
| * offloading computation (rather than storage) to a Flight service. |
| */ |
| rpc DoExchange(stream FlightData) returns (stream FlightData) {} |
| |
| /* |
| * Flight services can support an arbitrary number of simple actions in |
| * addition to the possible ListFlights, GetFlightInfo, DoGet, DoPut |
| * operations that are potentially available. DoAction allows a flight client |
| * to do a specific action against a flight service. An action includes |
| * opaque request and response objects that are specific to the type action |
| * being undertaken. |
| */ |
| rpc DoAction(Action) returns (stream Result) {} |
| |
| /* |
| * A flight service exposes all of the available action types that it has |
| * along with descriptions. This allows different flight consumers to |
| * understand the capabilities of the flight service. |
| */ |
| rpc ListActions(Empty) returns (stream ActionType) {} |
| } |
| |
| /* |
| * The request that a client provides to a server on handshake. |
| */ |
| message HandshakeRequest { |
| |
| /* |
| * A defined protocol version |
| */ |
| uint64 protocol_version = 1; |
| |
| /* |
| * Arbitrary auth/handshake info. |
| */ |
| bytes payload = 2; |
| } |
| |
| message HandshakeResponse { |
| |
| /* |
| * A defined protocol version |
| */ |
| uint64 protocol_version = 1; |
| |
| /* |
| * Arbitrary auth/handshake info. |
| */ |
| bytes payload = 2; |
| } |
| |
| /* |
| * A message for doing simple auth. |
| */ |
| message BasicAuth { |
| string username = 2; |
| string password = 3; |
| } |
| |
| message Empty {} |
| |
| /* |
| * Describes an available action, including both the name used for execution |
| * along with a short description of the purpose of the action. |
| */ |
| message ActionType { |
| string type = 1; |
| string description = 2; |
| } |
| |
| /* |
| * A service specific expression that can be used to return a limited set |
| * of available Arrow Flight streams. |
| */ |
| message Criteria { |
| bytes expression = 1; |
| } |
| |
| /* |
| * An opaque action specific for the service. |
| */ |
| message Action { |
| string type = 1; |
| bytes body = 2; |
| } |
| |
| /* |
| * The request of the CancelFlightInfo action. |
| * |
| * The request should be stored in Action.body. |
| */ |
| message CancelFlightInfoRequest { |
| FlightInfo info = 1; |
| } |
| |
| /* |
| * The request of the RenewFlightEndpoint action. |
| * |
| * The request should be stored in Action.body. |
| */ |
| message RenewFlightEndpointRequest { |
| FlightEndpoint endpoint = 1; |
| } |
| |
| /* |
| * An opaque result returned after executing an action. |
| */ |
| message Result { |
| bytes body = 1; |
| } |
| |
| /* |
| * The result of a cancel operation. |
| * |
| * This is used by CancelFlightInfoResult.status. |
| */ |
| enum CancelStatus { |
| // The cancellation status is unknown. Servers should avoid using |
| // this value (send a NOT_FOUND error if the requested query is |
| // not known). Clients can retry the request. |
| CANCEL_STATUS_UNSPECIFIED = 0; |
| // The cancellation request is complete. Subsequent requests with |
| // the same payload may return CANCELLED or a NOT_FOUND error. |
| CANCEL_STATUS_CANCELLED = 1; |
| // The cancellation request is in progress. The client may retry |
| // the cancellation request. |
| CANCEL_STATUS_CANCELLING = 2; |
| // The query is not cancellable. The client should not retry the |
| // cancellation request. |
| CANCEL_STATUS_NOT_CANCELLABLE = 3; |
| } |
| |
| /* |
| * The result of the CancelFlightInfo action. |
| * |
| * The result should be stored in Result.body. |
| */ |
| message CancelFlightInfoResult { |
| CancelStatus status = 1; |
| } |
| |
| /* |
| * Wrap the result of a getSchema call |
| */ |
| message SchemaResult { |
| // The schema of the dataset in its IPC form: |
| // 4 bytes - an optional IPC_CONTINUATION_TOKEN prefix |
| // 4 bytes - the byte length of the payload |
| // a flatbuffer Message whose header is the Schema |
| bytes schema = 1; |
| } |
| |
| /* |
| * The name or tag for a Flight. May be used as a way to retrieve or generate |
| * a flight or be used to expose a set of previously defined flights. |
| */ |
| message FlightDescriptor { |
| |
| /* |
| * Describes what type of descriptor is defined. |
| */ |
| enum DescriptorType { |
| |
| // Protobuf pattern, not used. |
| UNKNOWN = 0; |
| |
| /* |
| * A named path that identifies a dataset. A path is composed of a string |
| * or list of strings describing a particular dataset. This is conceptually |
| * similar to a path inside a filesystem. |
| */ |
| PATH = 1; |
| |
| /* |
| * An opaque command to generate a dataset. |
| */ |
| CMD = 2; |
| } |
| |
| DescriptorType type = 1; |
| |
| /* |
| * Opaque value used to express a command. Should only be defined when |
| * type = CMD. |
| */ |
| bytes cmd = 2; |
| |
| /* |
| * List of strings identifying a particular dataset. Should only be defined |
| * when type = PATH. |
| */ |
| repeated string path = 3; |
| } |
| |
| /* |
| * The access coordinates for retrieval of a dataset. With a FlightInfo, a |
| * consumer is able to determine how to retrieve a dataset. |
| */ |
| message FlightInfo { |
| // The schema of the dataset in its IPC form: |
| // 4 bytes - an optional IPC_CONTINUATION_TOKEN prefix |
| // 4 bytes - the byte length of the payload |
| // a flatbuffer Message whose header is the Schema |
| bytes schema = 1; |
| |
| /* |
| * The descriptor associated with this info. |
| */ |
| FlightDescriptor flight_descriptor = 2; |
| |
| /* |
| * A list of endpoints associated with the flight. To consume the |
| * whole flight, all endpoints (and hence all Tickets) must be |
| * consumed. Endpoints can be consumed in any order. |
| * |
| * In other words, an application can use multiple endpoints to |
| * represent partitioned data. |
| * |
| * If the returned data has an ordering, an application can use |
| * "FlightInfo.ordered = true" or should return the all data in a |
| * single endpoint. Otherwise, there is no ordering defined on |
| * endpoints or the data within. |
| * |
| * A client can read ordered data by reading data from returned |
| * endpoints, in order, from front to back. |
| * |
| * Note that a client may ignore "FlightInfo.ordered = true". If an |
| * ordering is important for an application, an application must |
| * choose one of them: |
| * |
| * * An application requires that all clients must read data in |
| * returned endpoints order. |
| * * An application must return the all data in a single endpoint. |
| */ |
| repeated FlightEndpoint endpoint = 3; |
| |
| // Set these to -1 if unknown. |
| int64 total_records = 4; |
| int64 total_bytes = 5; |
| |
| /* |
| * FlightEndpoints are in the same order as the data. |
| */ |
| bool ordered = 6; |
| |
| /* |
| * Application-defined metadata. |
| * |
| * There is no inherent or required relationship between this |
| * and the app_metadata fields in the FlightEndpoints or resulting |
| * FlightData messages. Since this metadata is application-defined, |
| * a given application could define there to be a relationship, |
| * but there is none required by the spec. |
| */ |
| bytes app_metadata = 7; |
| } |
| |
| /* |
| * The information to process a long-running query. |
| */ |
| message PollInfo { |
| /* |
| * The currently available results. |
| * |
| * If "flight_descriptor" is not specified, the query is complete |
| * and "info" specifies all results. Otherwise, "info" contains |
| * partial query results. |
| * |
| * Note that each PollInfo response contains a complete |
| * FlightInfo (not just the delta between the previous and current |
| * FlightInfo). |
| * |
| * Subsequent PollInfo responses may only append new endpoints to |
| * info. |
| * |
| * Clients can begin fetching results via DoGet(Ticket) with the |
| * ticket in the info before the query is |
| * completed. FlightInfo.ordered is also valid. |
| */ |
| FlightInfo info = 1; |
| |
| /* |
| * The descriptor the client should use on the next try. |
| * If unset, the query is complete. |
| */ |
| FlightDescriptor flight_descriptor = 2; |
| |
| /* |
| * Query progress. If known, must be in [0.0, 1.0] but need not be |
| * monotonic or nondecreasing. If unknown, do not set. |
| */ |
| optional double progress = 3; |
| |
| /* |
| * Expiration time for this request. After this passes, the server |
| * might not accept the retry descriptor anymore (and the query may |
| * be cancelled). This may be updated on a call to PollFlightInfo. |
| */ |
| google.protobuf.Timestamp expiration_time = 4; |
| } |
| |
| /* |
| * A particular stream or split associated with a flight. |
| */ |
| message FlightEndpoint { |
| |
| /* |
| * Token used to retrieve this stream. |
| */ |
| Ticket ticket = 1; |
| |
| /* |
| * A list of URIs where this ticket can be redeemed via DoGet(). |
| * |
| * If the list is empty, the expectation is that the ticket can only |
| * be redeemed on the current service where the ticket was |
| * generated. |
| * |
| * If the list is not empty, the expectation is that the ticket can |
| * be redeemed at any of the locations, and that the data returned |
| * will be equivalent. In this case, the ticket may only be redeemed |
| * at one of the given locations, and not (necessarily) on the |
| * current service. |
| * |
| * In other words, an application can use multiple locations to |
| * represent redundant and/or load balanced services. |
| */ |
| repeated Location location = 2; |
| |
| /* |
| * Expiration time of this stream. If present, clients may assume |
| * they can retry DoGet requests. Otherwise, it is |
| * application-defined whether DoGet requests may be retried. |
| */ |
| google.protobuf.Timestamp expiration_time = 3; |
| |
| /* |
| * Application-defined metadata. |
| * |
| * There is no inherent or required relationship between this |
| * and the app_metadata fields in the FlightInfo or resulting |
| * FlightData messages. Since this metadata is application-defined, |
| * a given application could define there to be a relationship, |
| * but there is none required by the spec. |
| */ |
| bytes app_metadata = 4; |
| } |
| |
| /* |
| * A location where a Flight service will accept retrieval of a particular |
| * stream given a ticket. |
| */ |
| message Location { |
| string uri = 1; |
| } |
| |
| /* |
| * An opaque identifier that the service can use to retrieve a particular |
| * portion of a stream. |
| * |
| * Tickets are meant to be single use. It is an error/application-defined |
| * behavior to reuse a ticket. |
| */ |
| message Ticket { |
| bytes ticket = 1; |
| } |
| |
| /* |
| * A batch of Arrow data as part of a stream of batches. |
| */ |
| message FlightData { |
| |
| /* |
| * The descriptor of the data. This is only relevant when a client is |
| * starting a new DoPut stream. |
| */ |
| FlightDescriptor flight_descriptor = 1; |
| |
| /* |
| * Header for message data as described in Message.fbs::Message. |
| */ |
| bytes data_header = 2; |
| |
| /* |
| * Application-defined metadata. |
| */ |
| bytes app_metadata = 3; |
| |
| /* |
| * The actual batch of Arrow data. Preferably handled with minimal-copies |
| * coming last in the definition to help with sidecar patterns (it is |
| * expected that some implementations will fetch this field off the wire |
| * with specialized code to avoid extra memory copies). |
| */ |
| bytes data_body = 1000; |
| } |
| |
| /** |
| * The response message associated with the submission of a DoPut. |
| */ |
| message PutResult { |
| bytes app_metadata = 1; |
| } |