Arrow Flight RPC#

Arrow Flight 是一個基於 Arrow 資料的高效能資料服務 RPC 框架，建立於 gRPC 和 IPC 格式之上。

Flight 圍繞 Arrow 記錄批次的串流組織，可以從另一個服務下載或上傳到另一個服務。一組元資料方法提供串流的探索和內省，以及實作應用程式特定方法的能力。

方法和訊息線路格式由 Protobuf 定義，使與可能單獨支援 gRPC 和 Arrow 但不支援 Flight 的客戶端具有互通性。但是，Flight 實作包含進一步的最佳化，以避免 Protobuf 使用中的額外負擔（主要圍繞避免過多的記憶體複製）。

RPC 方法和請求模式#

Flight 定義了一組 RPC 方法，用於上傳/下載資料、檢索關於資料串流的元資料、列出可用的資料串流，以及用於實作應用程式特定的 RPC 方法。Flight 服務實作了這些方法的一些子集，而 Flight 客戶端可以呼叫這些方法中的任何一個。

資料串流由描述符（FlightDescriptor 訊息）識別，描述符可以是路徑或任意二進位命令。例如，描述符可以編碼 SQL 查詢、分散式檔案系統上檔案的路徑，甚至是 pickled Python 物件；應用程式可以根據自己的需要使用此訊息。

因此，一個 Flight 客戶端可以連接到任何服務並執行基本操作。為了促進這一點，Flight 服務預期支援一些常見的請求模式，如下所述。當然，應用程式可以忽略相容性，而只是將 Flight RPC 方法視為用於其自身目的的底層建構區塊。

有關所涉及的方法和訊息的完整詳細資訊，請參閱 Protocol Buffer 定義。

下載資料#

希望下載資料的客戶端將會

透過 DoGet 檢索資料。#

建構或取得他們感興趣的資料集的 FlightDescriptor。

客戶端可能已經知道他們想要的描述符，或者他們可以使用像 ListFlights 這樣的方法來發現它們。
呼叫 GetFlightInfo(FlightDescriptor) 以取得 FlightInfo 訊息。

Flight 不要求資料與元資料位於同一伺服器上。因此，FlightInfo 包含有關資料位置的詳細資訊，因此客戶端可以從適當的伺服器提取資料。這被編碼為 FlightInfo 內的一系列 FlightEndpoint 訊息。每個端點代表包含部分回應資料的位置。

端點包含可以從中檢索此資料的位置（伺服器位址）列表，以及 Ticket，這是一個不透明的二進位權杖，伺服器將使用它來識別正在請求的資料。

如果 FlightInfo.ordered 為 true，則表示來自不同端點的資料之間存在某種順序。客戶端應產生與每個端點傳回的資料以從前到後的順序串連時相同的結果。

如果 FlightInfo.ordered 為 false，則客戶端可以以任意順序傳回來自任何端點的資料。來自任何特定端點的資料必須按順序傳回，但來自不同端點的資料可以交錯以允許平行提取。

請注意，由於某些客戶端可能會忽略 FlightInfo.ordered，因此如果排序很重要且無法確保客戶端支援，則伺服器應傳回單個端點。

回應還包含其他元資料，例如綱要，以及可選的資料集大小估計值。
使用伺服器傳回的每個端點。

要使用端點，客戶端應連接到端點中的一個位置，然後使用端點中的票證呼叫 DoGet(Ticket)。這將為客戶端提供 Arrow 記錄批次的串流。

如果伺服器希望指示資料位於本機伺服器上而不是不同的位置，則它可以傳回空的位置列表。然後，客戶端可以重複使用與原始伺服器的現有連線來提取資料。否則，客戶端必須連接到指示的位置之一。

伺服器可能會將「自身」列為與其他伺服器位置並列的位置。通常，這需要伺服器知道其公用位址，但它也可以使用特殊的 URI 字串 arrow-flight-reuse-connection://? 來告訴客戶端，他們可以重複使用與同一伺服器的現有連線，而無需能夠命名自身。請參閱下面的連線重用。

透過這種方式，端點內的位置也可以被認為執行了前瞻性負載平衡或服務發現功能。端點可以代表已分割或以其他方式分散的資料。

客戶端必須使用所有端點才能檢索完整的資料集。客戶端可以以任何順序使用端點，甚至可以平行使用，或者將端點分發到多台機器上以供使用；這取決於應用程式的實作。客戶端也可以使用 FlightInfo.ordered。請參閱前面的項目以取得 FlightInfo.ordered 的詳細資訊。

每個端點都可能具有到期時間 (FlightEndpoint.expiration_time)。如果端點具有到期時間，則客戶端可以透過 DoGet 多次取得資料，直到達到到期時間。否則，是否可以重試 DoGet 請求由應用程式定義。到期時間表示為 google.protobuf.Timestamp。

如果到期時間很短，客戶端可以透過 RenewFlightEndpoint 動作延長到期時間。客戶端需要使用 DoAction 以及 RenewFlightEndpoint 動作類型來延長到期時間。Action.body 必須是具有要續訂的 FlightEndpoint 的 RenewFlightEndpointRequest。

客戶端可以透過 CancelFlightInfo 動作取消傳回的 FlightInfo。客戶端需要使用 DoAction 以及 CancelFlightInfo 動作類型來取消 FlightInfo。

透過執行繁重查詢下載資料#

客戶端可能需要請求繁重查詢才能下載資料。但是，GetFlightInfo 在查詢完成之前不會傳回，因此客戶端會被封鎖。在這種情況下，客戶端可以使用 PollFlightInfo 而不是 GetFlightInfo

透過 PollFlightInfo 輪詢長時間執行的查詢。#

如同之前一樣，建構或取得 FlightDescriptor。
呼叫 PollFlightInfo(FlightDescriptor) 以取得 PollInfo 訊息。

伺服器應在第一次呼叫時盡快回應。因此，客戶端不應等待第一個 PollInfo 回應。

如果查詢尚未完成，PollInfo.flight_descriptor 具有 FlightDescriptor。客戶端應使用描述符（而不是原始的 FlightDescriptor）來呼叫下一個 PollFlightInfo()。伺服器應辨識 PollInfo.flight_descriptor，即使它不一定是最新的一個，以防客戶端錯過了中間的更新。

如果查詢已完成，則 PollInfo.flight_descriptor 未設定。

PollInfo.info 是目前可用的結果。每次都是完整的 FlightInfo，而不僅僅是先前和目前 FlightInfo 之間的差異。伺服器每次都應僅附加到 PollInfo.info 中的端點。因此，即使查詢尚未完成，客戶端也可以使用 PollInfo.info 中的 Ticket 執行 DoGet(Ticket)。FlightInfo.ordered 也有效。

伺服器不應回應，直到結果與上次不同為止。這樣，客戶端可以「長輪詢」更新，而無需不斷發出請求。如果需要，客戶端可以設定短暫的逾時時間以避免封鎖呼叫。

PollInfo.progress 可能已設定。它代表查詢的進度。如果已設定，則值必須在 [0.0, 1.0] 範圍內。該值不一定是單調或非遞減的。伺服器可以僅透過更新 PollInfo.progress 值來回應，儘管它不應向客戶端發送垃圾郵件般的更新。

PollInfo.timestamp 是此請求的到期時間。在此時間之後，伺服器可能不再接受輪詢描述符，並且查詢可能會被取消。這可能會在呼叫 PollFlightInfo 時更新。到期時間表示為 google.protobuf.Timestamp。

客戶端可以透過 CancelFlightInfo 動作取消查詢。

如果查詢失敗，伺服器應傳回錯誤狀態而不是回應。客戶端不應輪詢請求，除非是 TIMED_OUT 和 UNAVAILABLE，它們可能不是源自伺服器。
如同之前一樣，使用伺服器傳回的每個端點。

上傳資料#

若要上傳資料，客戶端將會

透過 DoPut 上傳資料。#

如同之前一樣，建構或取得 FlightDescriptor。
呼叫 DoPut(FlightData) 並上傳 Arrow 記錄批次的串流。

FlightDescriptor 包含在第一條訊息中，以便伺服器可以識別資料集。

DoPut 允許伺服器將回應訊息連同自訂元資料傳送回客戶端。這可用於實作諸如可恢復寫入之類的功能（例如，伺服器可以定期傳送訊息，指示到目前為止已提交了多少列）。

交換資料#

某些使用案例可能需要在單個呼叫中上傳和下載資料。雖然可以使用多個呼叫來模擬，但如果應用程式是有狀態的，這可能會很困難。例如，應用程式可能希望實作一個呼叫，其中客戶端上傳資料，伺服器以該資料的轉換作為回應；如果使用 DoGet 和 DoPut 實作，這將需要是有狀態的。相反，DoExchange 允許將其作為單個呼叫實作。客戶端將會

使用 DoExchange 的複雜資料流。#

如同之前一樣，建構或取得 FlightDescriptor。
呼叫 DoExchange(FlightData)。

如同 DoPut 一樣，FlightDescriptor 包含在第一條訊息中。此時，客戶端和伺服器都可以同時將資料串流傳輸到另一端。

身份驗證#

Flight 支援各種身份驗證方法，應用程式可以根據自己的需求自訂這些方法。

「交握」身份驗證

這分為兩個部分實作。在連線時，客戶端呼叫 Handshake RPC 方法，應用程式定義的身份驗證處理常式可以與伺服器上的對應方交換任意數量的訊息。然後，處理常式提供二進位權杖。然後，Flight 客戶端將在所有未來呼叫的標頭中包含此權杖，伺服器身份驗證處理常式將驗證該權杖。

應用程式可以使用其中的任何部分；例如，他們可以忽略初始交握，並在每次呼叫時傳送外部取得的權杖（例如，持有者權杖），或者他們可以在交握期間建立信任，並且不驗證每次呼叫的權杖，將連線視為有狀態的（「登入」模式）。

警告

除非在每次呼叫時都驗證權杖，否則此模式不安全，尤其是在存在第 7 層負載平衡器（gRPC 常見的情況）或 gRPC 透明地重新連線客戶端的情況下。

基於標頭/基於中介軟體的身份驗證

客戶端可以在呼叫中包含自訂標頭。然後可以實作自訂中介軟體，以在伺服器端驗證和接受/拒絕呼叫。

相互 TLS (mTLS)

客戶端在連線建立期間提供憑證，伺服器會驗證該憑證。應用程式不需要實作任何身份驗證程式碼，但必須佈建和分發憑證。

這可能僅在某些實作中可用，並且僅在也啟用 TLS 時才可用。

某些 Flight 實作也可能公開底層 gRPC API，在這種情況下，任何 gRPC 支援的身份驗證方法均可用。

位置 URI#

Flight 主要根據以下 Protobuf 和 gRPC 規範定義，但 Arrow 實作也可能支援替代傳輸（請參閱 Flight RPC）。客戶端和伺服器需要知道給定位置中的 URI 使用哪種傳輸，因此 Flight 實作應針對給定的傳輸使用以下 URI 方案

傳輸	URI 方案
gRPC（純文字）	grpc: 或 grpc+tcp
gRPC (TLS)	grpc+tls
gRPC（Unix 網域套接字）	grpc+unix
（重複使用連線）	arrow-flight-reuse-connection
UCX（純文字）(1)	ucx

註解

(1) Flight UCX 傳輸已在 19.0.0 版本中棄用。分離式 IPC 協定章節提出了一種替代解決方案。

連線重用#

上面的「重複使用連線」不是特定的傳輸。相反，它表示客戶端可以嘗試對同一伺服器（以及透過相同的連線）執行 DoGet，它最初從該伺服器取得 FlightInfo（即，它對其呼叫了 GetFlightInfo）。這與未傳回特定 Location 時的解釋方式相同。

這允許伺服器將「自身」作為一個可能的位置傳回以提取資料，而無需知道其自身的公用位址，這在部署中可能很有用，在這種部署中，知道這一點可能很困難或不可能。例如，開發人員可能會將雲端環境中的遠端服務轉發到其本機；在這種情況下，遠端服務將無法知道正在透過其存取的本機主機名稱和埠。

出於相容性原因，URI 應始終為 arrow-flight-reuse-connection://?，並帶有尾隨的空查詢字串。Java 的 URI 實作不接受 scheme: 或 scheme://，而 C++ 的實作不接受空字串，因此顯而易見的候選者不相容。所選的表示形式可以由這兩種實作以及 Go 的 net/url 和 Python 的 urllib.parse 剖析。

錯誤處理#

Arrow Flight 定義了自己的錯誤代碼集。實作在語言之間有所不同（例如，在 C++ 中，「未實作」是通用的 Arrow 錯誤狀態，而在 Java 中是 Flight 特定的例外），但公開了以下集合

錯誤代碼	描述
UNKNOWN	未知的錯誤。如果沒有其他錯誤適用，則為預設值。
INTERNAL	服務實作內部發生錯誤。
INVALID_ARGUMENT	客戶端將無效的引數傳遞給 RPC。
TIMED_OUT	操作超過了逾時時間或截止期限。
NOT_FOUND	找不到請求的資源（動作、資料串流）。
ALREADY_EXISTS	資源已存在。
CANCELLED	操作已取消（由客戶端或伺服器取消）。
UNAUTHENTICATED	客戶端未通過身份驗證。
UNAUTHORIZED	客戶端已通過身份驗證，但不具有請求操作的權限。
UNIMPLEMENTED	RPC 未實作。
UNAVAILABLE	伺服器不可用。可能會由客戶端針對連線問題發出。

外部資源#

Protocol Buffer 定義#

/*
 * 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;
}

/*
 * An opaque result returned after executing an action.
 */
message Result {
  bytes body = 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;
}

/*
 * The request of the CancelFlightInfo action.
 *
 * The request should be stored in Action.body.
 */
message CancelFlightInfoRequest {
  FlightInfo info = 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;
}

/*
 * 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 location where a Flight service will accept retrieval of a particular
 * stream given a ticket.
 */
message Location {
  string uri = 1;
}

/*
 * 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. If one
   * of the given locations is "arrow-flight-reuse-connection://?", the
   * client may redeem the ticket on the service where the ticket was
   * generated (i.e., the same as above), in addition to the other
   * locations. (This URI was chosen to maximize compatibility, as 'scheme:'
   * or 'scheme://' are not accepted by Java's java.net.URI.)
   *
   * 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;
}

/*
 * The request of the RenewFlightEndpoint action.
 *
 * The request should be stored in Action.body.
 */
message RenewFlightEndpointRequest {
  FlightEndpoint endpoint = 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;
}

/*
 * EXPERIMENTAL: Union of possible value types for a Session Option to be set to.
 *
 * By convention, an attempt to set a valueless SessionOptionValue should
 * attempt to unset or clear the named option value on the server.
 */
message SessionOptionValue {
  message StringListValue {
    repeated string values = 1;
  }

  oneof option_value {
    string string_value = 1;
    bool bool_value = 2;
    sfixed64 int64_value = 3;
    double double_value = 4;
    StringListValue string_list_value = 5;
  }
}

/*
 * EXPERIMENTAL: A request to set session options for an existing or new (implicit)
 * server session.
 *
 * Sessions are persisted and referenced via a transport-level state management, typically
 * RFC 6265 HTTP cookies when using an HTTP transport.  The suggested cookie name or state
 * context key is 'arrow_flight_session_id', although implementations may freely choose their
 * own name.
 *
 * Session creation (if one does not already exist) is implied by this RPC request, however
 * server implementations may choose to initiate a session that also contains client-provided
 * session options at any other time, e.g. on authentication, or when any other call is made
 * and the server wishes to use a session to persist any state (or lack thereof).
 */
message SetSessionOptionsRequest {
  map<string, SessionOptionValue> session_options = 1;
}

/*
 * EXPERIMENTAL: The results (individually) of setting a set of session options.
 *
 * Option names should only be present in the response if they were not successfully
 * set on the server; that is, a response without an Error for a name provided in the
 * SetSessionOptionsRequest implies that the named option value was set successfully.
 */
message SetSessionOptionsResult {
  enum ErrorValue {
    // Protobuf deserialization fallback value: The status is unknown or unrecognized.
    // Servers should avoid using this value. The request may be retried by the client.
    UNSPECIFIED = 0;
    // The given session option name is invalid.
    INVALID_NAME = 1;
    // The session option value or type is invalid.
    INVALID_VALUE = 2;
    // The session option cannot be set.
    ERROR = 3;
  }

  message Error {
    ErrorValue value = 1;
  }

  map<string, Error> errors = 1;
}

/*
 * EXPERIMENTAL: A request to access the session options for the current server session.
 *
 * The existing session is referenced via a cookie header or similar (see
 * SetSessionOptionsRequest above); it is an error to make this request with a missing,
 * invalid, or expired session cookie header or other implementation-defined session
 * reference token.
 */
message GetSessionOptionsRequest {
}

/*
 * EXPERIMENTAL: The result containing the current server session options.
 */
message GetSessionOptionsResult {
    map<string, SessionOptionValue> session_options = 1;
}

/*
 * Request message for the "Close Session" action.
 *
 * The exiting session is referenced via a cookie header.
 */
message CloseSessionRequest {
}

/*
 * The result of closing a session.
 */
message CloseSessionResult {
  enum Status {
    // Protobuf deserialization fallback value: The session close status is unknown or
    // not recognized. Servers should avoid using this value (send a NOT_FOUND error if
    // the requested session is not known or expired). Clients can retry the request.
    UNSPECIFIED = 0;
    // The session close request is complete. Subsequent requests with
    // the same session produce a NOT_FOUND error.
    CLOSED = 1;
    // The session close request is in progress. The client may retry
    // the close request.
    CLOSING = 2;
    // The session is not closeable. The client should not retry the
    // close request.
    NOT_CLOSEABLE = 3;
  }

  Status status = 1;
}