You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@arrow.apache.org by gi...@apache.org on 2026/10/11 02:32:33 UTC
(arrow-rs) branch main updated: Sync Arrow format documentation and Go metadata (#11499)
This is an automated email from the ASF dual-hosted git repository.
github-merge-queue[bot] pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow-rs.git
The following commit(s) were added to refs/heads/main by this push:
new 7b05f773dc Sync Arrow format documentation and Go metadata (#11499)
7b05f773dc is described below
commit 7b05f773dc77ab9ef2f246a5c85ed8dbd56fc329
Author: Phoenix <Ph...@163.com>
AuthorDate: Sun Oct 11 01:59:05 2026 +0000
Sync Arrow format documentation and Go metadata (#11499)
# Which issue does this PR close?
- Part of #11383
# Rationale for this change
The bundled format definitions contain outdated comments and a Flight
SQL Go package path that no longer matches apache/arrow-go. Keeping the
definitions and generated Rust docs aligned makes the protocol
descriptions accurate for downstream users.
# What changes are included in this PR?
- Refresh FlatBuffer and Flight SQL comments, including tensor
deprecation, decimal widths, and SQL metadata descriptions.
- Update the Flight SQL go_package to
github.com/apache/arrow-go/arrow/flight/gen/flight.
- Normalize proto formatting and sync checked-in IPC and Flight SQL Rust
documentation.
# Are these changes tested?
No new tests were added because the wire format and Rust APIs are
unchanged. Existing arrow-ipc and arrow-flight tests cover the generated
bindings.
# Are there any significant user-facing changes?
No wire-format or Rust API changes. The updated go_package affects the
import path used by Go code generators.
AI assistance was used to synchronize IPC generated Rust docs and review
the diff.
---
arrow-flight/src/arrow.flight.protocol.rs | 137 +-
arrow-flight/src/sql/arrow.flight.protocol.sql.rs | 114 +-
arrow-ipc/src/gen/File.rs | 2 +-
arrow-ipc/src/gen/Message.rs | 14 +-
arrow-ipc/src/gen/Schema.rs | 53 +-
arrow-ipc/src/gen/SparseTensor.rs | 19 +-
arrow-ipc/src/gen/Tensor.rs | 2 +
format/File.fbs | 2 +-
format/Flight.proto | 1056 +++---
format/FlightSql.proto | 3682 +++++++++++----------
format/Message.fbs | 24 +-
format/Schema.fbs | 98 +-
format/SparseTensor.fbs | 21 +-
format/Tensor.fbs | 4 +-
14 files changed, 2691 insertions(+), 2537 deletions(-)
diff --git a/arrow-flight/src/arrow.flight.protocol.rs b/arrow-flight/src/arrow.flight.protocol.rs
index bb6370d1ac..4796cbb10d 100644
--- a/arrow-flight/src/arrow.flight.protocol.rs
+++ b/arrow-flight/src/arrow.flight.protocol.rs
@@ -64,24 +64,6 @@ pub struct Action {
pub body: ::prost::bytes::Bytes,
}
///
-/// The request of the CancelFlightInfo action.
-///
-/// The request should be stored in Action.body.
-#[derive(Clone, PartialEq, ::prost::Message)]
-pub struct CancelFlightInfoRequest {
- #[prost(message, optional, tag = "1")]
- pub info: ::core::option::Option<FlightInfo>,
-}
-///
-/// The request of the RenewFlightEndpoint action.
-///
-/// The request should be stored in Action.body.
-#[derive(Clone, PartialEq, ::prost::Message)]
-pub struct RenewFlightEndpointRequest {
- #[prost(message, optional, tag = "1")]
- pub endpoint: ::core::option::Option<FlightEndpoint>,
-}
-///
/// An opaque result returned after executing an action.
#[derive(Clone, PartialEq, Eq, Hash, ::prost::Message)]
pub struct Result {
@@ -89,15 +71,6 @@ pub struct Result {
pub body: ::prost::bytes::Bytes,
}
///
-/// The result of the CancelFlightInfo action.
-///
-/// The result should be stored in Result.body.
-#[derive(Clone, Copy, PartialEq, Eq, Hash, ::prost::Message)]
-pub struct CancelFlightInfoResult {
- #[prost(enumeration = "CancelStatus", tag = "1")]
- pub status: i32,
-}
-///
/// Wrap the result of a getSchema call
#[derive(Clone, PartialEq, Eq, Hash, ::prost::Message)]
pub struct SchemaResult {
@@ -201,7 +174,7 @@ pub struct FlightInfo {
/// 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
+ /// "FlightInfo.ordered = true" or should return all data in a
/// single endpoint. Otherwise, there is no ordering defined on
/// endpoints or the data within.
///
@@ -214,7 +187,7 @@ pub struct FlightInfo {
///
/// * An application requires that all clients must read data in
/// returned endpoints order.
- /// * An application must return the all data in a single endpoint.
+ /// * An application must return all data in a single endpoint.
#[prost(message, repeated, tag = "3")]
pub endpoint: ::prost::alloc::vec::Vec<FlightEndpoint>,
/// Set these to -1 if unknown.
@@ -278,6 +251,76 @@ pub struct PollInfo {
pub expiration_time: ::core::option::Option<::prost_types::Timestamp>,
}
///
+/// The request of the CancelFlightInfo action.
+///
+/// The request should be stored in Action.body.
+#[derive(Clone, PartialEq, ::prost::Message)]
+pub struct CancelFlightInfoRequest {
+ #[prost(message, optional, tag = "1")]
+ pub info: ::core::option::Option<FlightInfo>,
+}
+///
+/// The result of the CancelFlightInfo action.
+///
+/// The result should be stored in Result.body.
+#[derive(Clone, Copy, PartialEq, Eq, Hash, ::prost::Message)]
+pub struct CancelFlightInfoResult {
+ #[prost(enumeration = "CancelStatus", tag = "1")]
+ pub status: i32,
+}
+///
+/// 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.
+#[derive(Clone, PartialEq, Eq, Hash, ::prost::Message)]
+pub struct Ticket {
+ #[prost(bytes = "bytes", tag = "1")]
+ pub ticket: ::prost::bytes::Bytes,
+}
+///
+/// A location to retrieve a particular stream from. This URI should be one of
+/// the following:
+/// - An empty string or the string 'arrow-flight-reuse-connection://?':
+/// indicating that the ticket can be redeemed on the service where the
+/// ticket was generated via a DoGet request.
+/// - A valid grpc URI (grpc://, grpc+tls://, grpc+unix://, etc.):
+/// indicating that the ticket can be redeemed on the service at the given
+/// URI via a DoGet request.
+/// - A valid HTTP URI (<http://,> <https://,> etc.):
+/// indicating that the client should perform a GET request against the
+/// given URI to retrieve the stream. The ticket should be empty
+/// in this case and should be ignored by the client. Cloud object storage
+/// can be utilized by presigned URLs or mediating the auth separately and
+/// returning the full URL (e.g. <https://amzn-s3-demo-bucket.s3.us-west-2.amazonaws.com/...>).
+///
+/// We allow non-Flight URIs for the purpose of allowing Flight services to indicate that
+/// results can be downloaded in formats other than Arrow (such as Parquet) or to allow
+/// direct fetching of results from a URI to reduce excess copying and data movement.
+/// In these cases, the following conventions should be followed by servers and clients:
+///
+/// - Unless otherwise specified by the 'Content-Type' header of the response,
+/// a client should assume the response is using the Arrow IPC Streaming format.
+/// Usage of an IANA media type like 'application/octet-stream' should be assumed to
+/// be using the Arrow IPC Streaming format.
+/// - The server may allow the client to choose a specific response format by
+/// specifying an 'Accept' header in the request, such as 'application/vnd.apache.parquet'
+/// or 'application/vnd.apache.arrow.stream'. If multiple types are requested and
+/// supported by the server, the choice of which to use is server-specific. If
+/// none of the requested content-types are supported, the server may respond with
+/// either 406 (Not Acceptable) or 415 (Unsupported Media Type), or successfully
+/// respond with a different format that it does support along with the correct
+/// 'Content-Type' header.
+///
+/// Note: new schemes may be proposed in the future to allow for more flexibility based
+/// on community requests.
+#[derive(Clone, PartialEq, Eq, Hash, ::prost::Message)]
+pub struct Location {
+ #[prost(string, tag = "1")]
+ pub uri: ::prost::alloc::string::String,
+}
+///
/// A particular stream or split associated with a flight.
#[derive(Clone, PartialEq, ::prost::Message)]
pub struct FlightEndpoint {
@@ -292,11 +335,15 @@ pub struct FlightEndpoint {
/// 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 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.
@@ -320,23 +367,13 @@ pub struct FlightEndpoint {
pub app_metadata: ::prost::bytes::Bytes,
}
///
-/// A location where a Flight service will accept retrieval of a particular
-/// stream given a ticket.
-#[derive(Clone, PartialEq, Eq, Hash, ::prost::Message)]
-pub struct Location {
- #[prost(string, tag = "1")]
- pub uri: ::prost::alloc::string::String,
-}
-///
-/// An opaque identifier that the service can use to retrieve a particular
-/// portion of a stream.
+/// The request of the RenewFlightEndpoint action.
///
-/// Tickets are meant to be single use. It is an error/application-defined
-/// behavior to reuse a ticket.
-#[derive(Clone, PartialEq, Eq, Hash, ::prost::Message)]
-pub struct Ticket {
- #[prost(bytes = "bytes", tag = "1")]
- pub ticket: ::prost::bytes::Bytes,
+/// The request should be stored in Action.body.
+#[derive(Clone, PartialEq, ::prost::Message)]
+pub struct RenewFlightEndpointRequest {
+ #[prost(message, optional, tag = "1")]
+ pub endpoint: ::core::option::Option<FlightEndpoint>,
}
///
/// A batch of Arrow data as part of a stream of batches.
diff --git a/arrow-flight/src/sql/arrow.flight.protocol.sql.rs b/arrow-flight/src/sql/arrow.flight.protocol.sql.rs
index e7083c583e..225d85198c 100644
--- a/arrow-flight/src/sql/arrow.flight.protocol.sql.rs
+++ b/arrow-flight/src/sql/arrow.flight.protocol.sql.rs
@@ -176,6 +176,7 @@ pub struct CommandGetDbSchemas {
/// - ARROW:FLIGHT:SQL:IS_CASE_SENSITIVE - "1" indicates if the column is case-sensitive, "0" otherwise.
/// - ARROW:FLIGHT:SQL:IS_READ_ONLY - "1" indicates if the column is read only, "0" otherwise.
/// - ARROW:FLIGHT:SQL:IS_SEARCHABLE - "1" indicates if the column is searchable via WHERE clause, "0" otherwise.
+/// - ARROW:FLIGHT:SQL:REMARKS - A comment describing the column. This field has been added after all others, clients should be prepared to find it missing.
/// The returned data should be ordered by catalog_name, db_schema_name, table_name, then table_type, followed by table_schema if requested.
#[derive(Clone, PartialEq, Eq, Hash, ::prost::Message)]
pub struct CommandGetTables {
@@ -501,8 +502,8 @@ pub struct ActionBeginTransactionRequest {}
/// Request message for the "BeginSavepoint" action.
/// Creates a savepoint within a transaction.
///
-/// Only supported if FLIGHT_SQL_TRANSACTION is
-/// FLIGHT_SQL_TRANSACTION_SUPPORT_SAVEPOINT.
+/// Only supported if FLIGHT_SQL_SERVER_TRANSACTION returns
+/// SQL_SUPPORTED_TRANSACTION_SAVEPOINT.
#[derive(Clone, PartialEq, Eq, Hash, ::prost::Message)]
pub struct ActionBeginSavepointRequest {
/// The transaction to which a savepoint belongs.
@@ -677,6 +678,7 @@ pub mod action_end_savepoint_request {
/// - ARROW:FLIGHT:SQL:IS_CASE_SENSITIVE - "1" indicates if the column is case-sensitive, "0" otherwise.
/// - ARROW:FLIGHT:SQL:IS_READ_ONLY - "1" indicates if the column is read only, "0" otherwise.
/// - ARROW:FLIGHT:SQL:IS_SEARCHABLE - "1" indicates if the column is searchable via WHERE clause, "0" otherwise.
+/// - ARROW:FLIGHT:SQL:REMARKS - A comment describing the column. This field has been added after all others, clients should be prepared to find it missing.
/// - GetFlightInfo: execute the query.
#[derive(Clone, PartialEq, Eq, Hash, ::prost::Message)]
pub struct CommandStatementQuery {
@@ -702,6 +704,7 @@ pub struct CommandStatementQuery {
/// - ARROW:FLIGHT:SQL:IS_CASE_SENSITIVE - "1" indicates if the column is case-sensitive, "0" otherwise.
/// - ARROW:FLIGHT:SQL:IS_READ_ONLY - "1" indicates if the column is read only, "0" otherwise.
/// - ARROW:FLIGHT:SQL:IS_SEARCHABLE - "1" indicates if the column is searchable via WHERE clause, "0" otherwise.
+/// - ARROW:FLIGHT:SQL:REMARKS - A comment describing the column. This field has been added after all others, clients should be prepared to find it missing.
/// - GetFlightInfo: execute the query.
/// - DoPut: execute the query.
#[derive(Clone, PartialEq, Eq, Hash, ::prost::Message)]
@@ -737,6 +740,7 @@ pub struct TicketStatementQuery {
/// - ARROW:FLIGHT:SQL:IS_CASE_SENSITIVE - "1" indicates if the column is case-sensitive, "0" otherwise.
/// - ARROW:FLIGHT:SQL:IS_READ_ONLY - "1" indicates if the column is read only, "0" otherwise.
/// - ARROW:FLIGHT:SQL:IS_SEARCHABLE - "1" indicates if the column is searchable via WHERE clause, "0" otherwise.
+/// - ARROW:FLIGHT:SQL:REMARKS - A comment describing the column. This field has been added after all others, clients should be prepared to find it missing.
///
/// If the schema is retrieved after parameter values have been bound with DoPut, then the server should account
/// for the parameters when determining the schema.
@@ -772,7 +776,7 @@ pub struct CommandPreparedStatementUpdate {
}
///
/// Represents a bulk ingestion request. Used in the command member of FlightDescriptor
-/// for the the RPC call DoPut to cause the server load the contents of the stream's
+/// for the RPC call DoPut to cause the server load the contents of the stream's
/// FlightData into the target destination.
#[derive(Clone, PartialEq, ::prost::Message)]
pub struct CommandStatementIngest {
@@ -938,8 +942,8 @@ pub struct DoPutPreparedStatementResult {
/// statement must use this new handle.
/// The updated handle allows implementing query parameters with stateless services.
///
- /// When an updated handle is not provided by the server, clients should contiue
- /// using the previous handle provided by `ActionCreatePreparedStatementResonse`.
+ /// When an updated handle is not provided by the server, clients should continue
+ /// using the previous handle provided by `ActionCreatePreparedStatementResult`.
#[prost(bytes = "bytes", optional, tag = "1")]
pub prepared_statement_handle: ::core::option::Option<::prost::bytes::Bytes>,
}
@@ -1129,14 +1133,14 @@ pub enum SqlInfo {
/// - true: if it supports CREATE and DROP of tables.
SqlDdlTable = 502,
///
- /// Retrieves a int32 ordinal representing the case sensitivity of catalog, table, schema and table names.
+ /// Retrieves an int32 ordinal representing the case sensitivity of catalog, table, schema and table names.
///
/// The possible values are listed in `arrow.flight.protocol.sql.SqlSupportedCaseSensitivity`.
SqlIdentifierCase = 503,
/// Retrieves a UTF-8 string with the supported character(s) used to surround a delimited identifier.
SqlIdentifierQuoteChar = 504,
///
- /// Retrieves a int32 describing the case sensitivity of quoted identifiers.
+ /// Retrieves an int32 describing the case sensitivity of quoted identifiers.
///
/// The possible values are listed in `arrow.flight.protocol.sql.SqlSupportedCaseSensitivity`.
SqlQuotedIdentifierCase = 505,
@@ -1150,7 +1154,7 @@ pub enum SqlInfo {
///
/// Retrieves the null ordering.
///
- /// Returns a int32 ordinal for the null ordering being used, as described in
+ /// Returns an int32 ordinal for the null ordering being used, as described in
/// `arrow.flight.protocol.sql.SqlNullOrdering`.
SqlNullOrdering = 507,
/// Retrieves a UTF-8 string list with values of the supported keywords.
@@ -1187,7 +1191,7 @@ pub enum SqlInfo {
/// Retrieves a boolean value indicating whether concatenations between null and non-null values being
/// null are supported.
///
- /// - Returns:
+ /// Returns:
/// - false: if concatenations between null and non-null values being null are unsupported;
/// - true: if concatenations between null and non-null values being null are supported.
SqlNullPlusNullIsNull = 516,
@@ -1293,13 +1297,13 @@ pub enum SqlInfo {
/// Retrieves a boolean value indicating whether the SQL Integrity Enhancement Facility is supported.
///
/// Returns:
- /// - false: if the SQL Integrity Enhancement Facility is supported;
+ /// - false: if the SQL Integrity Enhancement Facility is unsupported;
/// - true: if the SQL Integrity Enhancement Facility is supported.
SqlSupportsIntegrityEnhancementFacility = 527,
///
/// Retrieves the support level for SQL OUTER JOINs.
///
- /// Returns a int32 ordinal for the SQL ordering being used, as described in
+ /// Returns an int32 ordinal for the SQL ordering being used, as described in
/// `arrow.flight.protocol.sql.SqlOuterJoinsSupportLevel`.
SqlOuterJoinsSupportLevel = 528,
/// Retrieves a UTF-8 string with the preferred term for "schema".
@@ -1308,7 +1312,7 @@ pub enum SqlInfo {
SqlProcedureTerm = 530,
///
/// Retrieves a UTF-8 string with the preferred term for "catalog".
- /// If a empty string is returned its assumed that the server does NOT supports catalogs.
+ /// If an empty string is returned it is assumed that the server does NOT support catalogs.
SqlCatalogTerm = 531,
///
/// Retrieves a boolean value indicating whether a catalog appears at the start of a fully qualified table name.
@@ -1331,10 +1335,10 @@ pub enum SqlInfo {
/// - return 5 (\b101) => \[SQL_ELEMENT_IN_PROCEDURE_CALLS, SQL_ELEMENT_IN_PRIVILEGE_DEFINITIONS\];
/// - return 6 (\b110) => \[SQL_ELEMENT_IN_INDEX_DEFINITIONS, SQL_ELEMENT_IN_PRIVILEGE_DEFINITIONS\];
/// - return 7 (\b111) => \[SQL_ELEMENT_IN_PROCEDURE_CALLS, SQL_ELEMENT_IN_INDEX_DEFINITIONS, SQL_ELEMENT_IN_PRIVILEGE_DEFINITIONS\].
- /// Valid actions for a SQL schema described under `arrow.flight.protocol.sql.SqlSupportedElementActions`.
+ /// Valid actions for a SQL schema are described under `arrow.flight.protocol.sql.SqlSupportedElementActions`.
SqlSchemasSupportedActions = 533,
///
- /// Retrieves the supported actions for a SQL schema.
+ /// Retrieves the supported actions for a SQL catalog.
///
/// Returns an int32 bitmask value representing the supported actions for a SQL catalog.
/// The returned bitmask should be parsed in order to retrieve the supported actions for a SQL catalog.
@@ -1418,43 +1422,43 @@ pub enum SqlInfo {
/// The returned bitmask should be parsed in order to retrieve the supported SQL UNIONs.
///
/// For instance:
- /// - return 0 (\b0) => \[\] (no supported SQL positioned commands);
+ /// - return 0 (\b0) => \[\] (no supported SQL UNIONs);
/// - return 1 (\b1) => \[SQL_UNION\];
/// - return 2 (\b10) => \[SQL_UNION_ALL\];
/// - return 3 (\b11) => \[SQL_UNION, SQL_UNION_ALL\].
- /// Valid SQL positioned commands are described under `arrow.flight.protocol.sql.SqlSupportedUnions`.
+ /// Valid SQL UNIONs are described under `arrow.flight.protocol.sql.SqlSupportedUnions`.
SqlSupportedUnions = 540,
- /// Retrieves a int64 value representing the maximum number of hex characters allowed in an inline binary literal.
+ /// Retrieves an int64 value representing the maximum number of hex characters allowed in an inline binary literal.
SqlMaxBinaryLiteralLength = 541,
- /// Retrieves a int64 value representing the maximum number of characters allowed for a character literal.
+ /// Retrieves an int64 value representing the maximum number of characters allowed for a character literal.
SqlMaxCharLiteralLength = 542,
- /// Retrieves a int64 value representing the maximum number of characters allowed for a column name.
+ /// Retrieves an int64 value representing the maximum number of characters allowed for a column name.
SqlMaxColumnNameLength = 543,
- /// Retrieves a int64 value representing the maximum number of columns allowed in a GROUP BY clause.
+ /// Retrieves an int64 value representing the maximum number of columns allowed in a GROUP BY clause.
SqlMaxColumnsInGroupBy = 544,
- /// Retrieves a int64 value representing the maximum number of columns allowed in an index.
+ /// Retrieves an int64 value representing the maximum number of columns allowed in an index.
SqlMaxColumnsInIndex = 545,
- /// Retrieves a int64 value representing the maximum number of columns allowed in an ORDER BY clause.
+ /// Retrieves an int64 value representing the maximum number of columns allowed in an ORDER BY clause.
SqlMaxColumnsInOrderBy = 546,
- /// Retrieves a int64 value representing the maximum number of columns allowed in a SELECT list.
+ /// Retrieves an int64 value representing the maximum number of columns allowed in a SELECT list.
SqlMaxColumnsInSelect = 547,
- /// Retrieves a int64 value representing the maximum number of columns allowed in a table.
+ /// Retrieves an int64 value representing the maximum number of columns allowed in a table.
SqlMaxColumnsInTable = 548,
- /// Retrieves a int64 value representing the maximum number of concurrent connections possible.
+ /// Retrieves an int64 value representing the maximum number of concurrent connections possible.
SqlMaxConnections = 549,
- /// Retrieves a int64 value the maximum number of characters allowed in a cursor name.
+ /// Retrieves an int64 value representing the maximum number of characters allowed in a cursor name.
SqlMaxCursorNameLength = 550,
///
- /// Retrieves a int64 value representing the maximum number of bytes allowed for an index,
+ /// Retrieves an int64 value representing the maximum number of bytes allowed for an index,
/// including all of the parts of the index.
SqlMaxIndexLength = 551,
- /// Retrieves a int64 value representing the maximum number of characters allowed in a schema name.
+ /// Retrieves an int64 value representing the maximum number of characters allowed in a schema name.
SqlDbSchemaNameLength = 552,
- /// Retrieves a int64 value representing the maximum number of characters allowed in a procedure name.
+ /// Retrieves an int64 value representing the maximum number of characters allowed in a procedure name.
SqlMaxProcedureNameLength = 553,
- /// Retrieves a int64 value representing the maximum number of characters allowed in a catalog name.
+ /// Retrieves an int64 value representing the maximum number of characters allowed in a catalog name.
SqlMaxCatalogNameLength = 554,
- /// Retrieves a int64 value representing the maximum number of bytes allowed in a single row.
+ /// Retrieves an int64 value representing the maximum number of bytes allowed in a single row.
SqlMaxRowSize = 555,
///
/// Retrieves a boolean indicating whether the return value for the JDBC method getMaxRowSize includes the SQL
@@ -1467,22 +1471,22 @@ pub enum SqlInfo {
/// the SQL data types LONGVARCHAR and LONGVARBINARY.
SqlMaxRowSizeIncludesBlobs = 556,
///
- /// Retrieves a int64 value representing the maximum number of characters allowed for an SQL statement;
+ /// Retrieves an int64 value representing the maximum number of characters allowed for an SQL statement;
/// a result of 0 (zero) means that there is no limit or the limit is not known.
SqlMaxStatementLength = 557,
- /// Retrieves a int64 value representing the maximum number of active statements that can be open at the same time.
+ /// Retrieves an int64 value representing the maximum number of active statements that can be open at the same time.
SqlMaxStatements = 558,
- /// Retrieves a int64 value representing the maximum number of characters allowed in a table name.
+ /// Retrieves an int64 value representing the maximum number of characters allowed in a table name.
SqlMaxTableNameLength = 559,
- /// Retrieves a int64 value representing the maximum number of tables allowed in a SELECT statement.
+ /// Retrieves an int64 value representing the maximum number of tables allowed in a SELECT statement.
SqlMaxTablesInSelect = 560,
- /// Retrieves a int64 value representing the maximum number of characters allowed in a user name.
+ /// Retrieves an int64 value representing the maximum number of characters allowed in a user name.
SqlMaxUsernameLength = 561,
///
/// Retrieves this database's default transaction isolation level as described in
/// `arrow.flight.protocol.sql.SqlTransactionIsolationLevel`.
///
- /// Returns a int32 ordinal for the SQL transaction isolation level.
+ /// Returns an int32 ordinal for the SQL transaction isolation level.
SqlDefaultTransactionIsolation = 562,
///
/// Retrieves a boolean value indicating whether transactions are supported. If not, invoking the method commit is a
@@ -1503,21 +1507,21 @@ pub enum SqlInfo {
/// - return 1 (\b1) => \[SQL_TRANSACTION_NONE\];
/// - return 2 (\b10) => \[SQL_TRANSACTION_READ_UNCOMMITTED\];
/// - return 3 (\b11) => \[SQL_TRANSACTION_NONE, SQL_TRANSACTION_READ_UNCOMMITTED\];
- /// - return 4 (\b100) => \[SQL_TRANSACTION_REPEATABLE_READ\];
- /// - return 5 (\b101) => \[SQL_TRANSACTION_NONE, SQL_TRANSACTION_REPEATABLE_READ\];
- /// - return 6 (\b110) => \[SQL_TRANSACTION_READ_UNCOMMITTED, SQL_TRANSACTION_REPEATABLE_READ\];
- /// - return 7 (\b111) => \[SQL_TRANSACTION_NONE, SQL_TRANSACTION_READ_UNCOMMITTED, SQL_TRANSACTION_REPEATABLE_READ\];
+ /// - return 4 (\b100) => \[SQL_TRANSACTION_READ_COMMITTED\];
+ /// - return 5 (\b101) => \[SQL_TRANSACTION_NONE, SQL_TRANSACTION_READ_COMMITTED\];
+ /// - return 6 (\b110) => \[SQL_TRANSACTION_READ_UNCOMMITTED, SQL_TRANSACTION_READ_COMMITTED\];
+ /// - return 7 (\b111) => \[SQL_TRANSACTION_NONE, SQL_TRANSACTION_READ_UNCOMMITTED, SQL_TRANSACTION_READ_COMMITTED\];
/// - return 8 (\b1000) => \[SQL_TRANSACTION_REPEATABLE_READ\];
/// - return 9 (\b1001) => \[SQL_TRANSACTION_NONE, SQL_TRANSACTION_REPEATABLE_READ\];
/// - return 10 (\b1010) => \[SQL_TRANSACTION_READ_UNCOMMITTED, SQL_TRANSACTION_REPEATABLE_READ\];
/// - return 11 (\b1011) => \[SQL_TRANSACTION_NONE, SQL_TRANSACTION_READ_UNCOMMITTED, SQL_TRANSACTION_REPEATABLE_READ\];
- /// - return 12 (\b1100) => \[SQL_TRANSACTION_REPEATABLE_READ, SQL_TRANSACTION_REPEATABLE_READ\];
- /// - return 13 (\b1101) => \[SQL_TRANSACTION_NONE, SQL_TRANSACTION_REPEATABLE_READ, SQL_TRANSACTION_REPEATABLE_READ\];
- /// - return 14 (\b1110) => \[SQL_TRANSACTION_READ_UNCOMMITTED, SQL_TRANSACTION_REPEATABLE_READ, SQL_TRANSACTION_REPEATABLE_READ\];
- /// - return 15 (\b1111) => \[SQL_TRANSACTION_NONE, SQL_TRANSACTION_READ_UNCOMMITTED, SQL_TRANSACTION_REPEATABLE_READ, SQL_TRANSACTION_REPEATABLE_READ\];
+ /// - return 12 (\b1100) => \[SQL_TRANSACTION_READ_COMMITTED, SQL_TRANSACTION_REPEATABLE_READ\];
+ /// - return 13 (\b1101) => \[SQL_TRANSACTION_NONE, SQL_TRANSACTION_READ_COMMITTED, SQL_TRANSACTION_REPEATABLE_READ\];
+ /// - return 14 (\b1110) => \[SQL_TRANSACTION_READ_UNCOMMITTED, SQL_TRANSACTION_READ_COMMITTED, SQL_TRANSACTION_REPEATABLE_READ\];
+ /// - return 15 (\b1111) => \[SQL_TRANSACTION_NONE, SQL_TRANSACTION_READ_UNCOMMITTED, SQL_TRANSACTION_READ_COMMITTED, SQL_TRANSACTION_REPEATABLE_READ\];
/// - return 16 (\b10000) => \[SQL_TRANSACTION_SERIALIZABLE\];
/// - ...
- /// Valid SQL positioned commands are described under `arrow.flight.protocol.sql.SqlTransactionIsolationLevel`.
+ /// Valid SQL transaction isolation levels are described under `arrow.flight.protocol.sql.SqlTransactionIsolationLevel`.
SqlSupportedTransactionsIsolationLevels = 564,
///
/// Retrieves a boolean value indicating whether a data definition statement within a transaction forces
@@ -1552,7 +1556,7 @@ pub enum SqlInfo {
/// Valid result set types are described under `arrow.flight.protocol.sql.SqlSupportedResultSetType`.
SqlSupportedResultSetTypes = 567,
///
- /// Returns an int32 bitmask value concurrency types supported for
+ /// Returns an int32 bitmask value representing the concurrency types supported for
/// `arrow.flight.protocol.sql.SqlSupportedResultSetType.SQL_RESULT_SET_TYPE_UNSPECIFIED`.
///
/// For instance:
@@ -1564,10 +1568,10 @@ pub enum SqlInfo {
/// - return 5 (\b101) => \[SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED, SQL_RESULT_SET_CONCURRENCY_UPDATABLE\]
/// - return 6 (\b110) => \[SQL_RESULT_SET_CONCURRENCY_READ_ONLY, SQL_RESULT_SET_CONCURRENCY_UPDATABLE\]
/// - return 7 (\b111) => \[SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED, SQL_RESULT_SET_CONCURRENCY_READ_ONLY, SQL_RESULT_SET_CONCURRENCY_UPDATABLE\]
- /// Valid result set types are described under `arrow.flight.protocol.sql.SqlSupportedResultSetConcurrency`.
+ /// Valid result set concurrency types are described under `arrow.flight.protocol.sql.SqlSupportedResultSetConcurrency`.
SqlSupportedConcurrenciesForResultSetUnspecified = 568,
///
- /// Returns an int32 bitmask value concurrency types supported for
+ /// Returns an int32 bitmask value representing the concurrency types supported for
/// `arrow.flight.protocol.sql.SqlSupportedResultSetType.SQL_RESULT_SET_TYPE_FORWARD_ONLY`.
///
/// For instance:
@@ -1579,10 +1583,10 @@ pub enum SqlInfo {
/// - return 5 (\b101) => \[SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED, SQL_RESULT_SET_CONCURRENCY_UPDATABLE\]
/// - return 6 (\b110) => \[SQL_RESULT_SET_CONCURRENCY_READ_ONLY, SQL_RESULT_SET_CONCURRENCY_UPDATABLE\]
/// - return 7 (\b111) => \[SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED, SQL_RESULT_SET_CONCURRENCY_READ_ONLY, SQL_RESULT_SET_CONCURRENCY_UPDATABLE\]
- /// Valid result set types are described under `arrow.flight.protocol.sql.SqlSupportedResultSetConcurrency`.
+ /// Valid result set concurrency types are described under `arrow.flight.protocol.sql.SqlSupportedResultSetConcurrency`.
SqlSupportedConcurrenciesForResultSetForwardOnly = 569,
///
- /// Returns an int32 bitmask value concurrency types supported for
+ /// Returns an int32 bitmask value representing the concurrency types supported for
/// `arrow.flight.protocol.sql.SqlSupportedResultSetType.SQL_RESULT_SET_TYPE_SCROLL_SENSITIVE`.
///
/// For instance:
@@ -1594,10 +1598,10 @@ pub enum SqlInfo {
/// - return 5 (\b101) => \[SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED, SQL_RESULT_SET_CONCURRENCY_UPDATABLE\]
/// - return 6 (\b110) => \[SQL_RESULT_SET_CONCURRENCY_READ_ONLY, SQL_RESULT_SET_CONCURRENCY_UPDATABLE\]
/// - return 7 (\b111) => \[SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED, SQL_RESULT_SET_CONCURRENCY_READ_ONLY, SQL_RESULT_SET_CONCURRENCY_UPDATABLE\]
- /// Valid result set types are described under `arrow.flight.protocol.sql.SqlSupportedResultSetConcurrency`.
+ /// Valid result set concurrency types are described under `arrow.flight.protocol.sql.SqlSupportedResultSetConcurrency`.
SqlSupportedConcurrenciesForResultSetScrollSensitive = 570,
///
- /// Returns an int32 bitmask value concurrency types supported for
+ /// Returns an int32 bitmask value representing the concurrency types supported for
/// `arrow.flight.protocol.sql.SqlSupportedResultSetType.SQL_RESULT_SET_TYPE_SCROLL_INSENSITIVE`.
///
/// For instance:
@@ -1609,7 +1613,7 @@ pub enum SqlInfo {
/// - return 5 (\b101) => \[SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED, SQL_RESULT_SET_CONCURRENCY_UPDATABLE\]
/// - return 6 (\b110) => \[SQL_RESULT_SET_CONCURRENCY_READ_ONLY, SQL_RESULT_SET_CONCURRENCY_UPDATABLE\]
/// - return 7 (\b111) => \[SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED, SQL_RESULT_SET_CONCURRENCY_READ_ONLY, SQL_RESULT_SET_CONCURRENCY_UPDATABLE\]
- /// Valid result set types are described under `arrow.flight.protocol.sql.SqlSupportedResultSetConcurrency`.
+ /// Valid result set concurrency types are described under `arrow.flight.protocol.sql.SqlSupportedResultSetConcurrency`.
SqlSupportedConcurrenciesForResultSetScrollInsensitive = 571,
///
/// Retrieves a boolean value indicating whether this database supports batch updates.
@@ -2717,7 +2721,7 @@ impl XdbcDatetimeSubcode {
#[repr(i32)]
pub enum Nullable {
/// *
- /// Indicates that the fields does not allow the use of null values.
+ /// Indicates that the field does not allow the use of null values.
NullabilityNoNulls = 0,
/// *
/// Indicates that the fields allow the use of null values.
diff --git a/arrow-ipc/src/gen/File.rs b/arrow-ipc/src/gen/File.rs
index ab22736147..b1930bfc47 100644
--- a/arrow-ipc/src/gen/File.rs
+++ b/arrow-ipc/src/gen/File.rs
@@ -98,7 +98,7 @@ impl<'a> Block {
s
}
- /// Index to the start of the RecordBlock (note this is past the Message header)
+ /// Index to the start of the RecordBatch (note this is past the Message header)
pub fn offset(&self) -> i64 {
let mut mem = core::mem::MaybeUninit::<<i64 as EndianScalar>::Scalar>::uninit();
// Safety:
diff --git a/arrow-ipc/src/gen/Message.rs b/arrow-ipc/src/gen/Message.rs
index 082461c900..98eb7c8950 100644
--- a/arrow-ipc/src/gen/Message.rs
+++ b/arrow-ipc/src/gen/Message.rs
@@ -50,7 +50,11 @@ pub const ENUM_VALUES_COMPRESSION_TYPE: [CompressionType; 2] =
pub struct CompressionType(pub i8);
#[allow(non_upper_case_globals)]
impl CompressionType {
+ /// LZ4 frame format, for portability, as provided by lz4frame.h or wrappers
+ /// thereof. Not to be confused with "raw" (also called "block") format
+ /// provided by lz4.h
pub const LZ4_FRAME: Self = Self(0);
+ /// Zstandard
pub const ZSTD: Self = Self(1);
pub const ENUM_MIN: i8 = 0;
@@ -152,6 +156,8 @@ impl BodyCompressionMethod {
/// uncompressed length may be set to -1 to indicate that the data that
/// follows is not compressed, which can be useful for cases where
/// compression does not yield appreciable savings.
+ /// Also, empty buffers can optionally be written out as 0-byte compressed
+ /// buffers, thereby omitting the 8-bytes length header.
pub const BUFFER: Self = Self(0);
pub const ENUM_MIN: i8 = 0;
@@ -250,7 +256,11 @@ pub const ENUM_VALUES_MESSAGE_HEADER: [MessageHeader; 6] = [
///
/// Arrow implementations do not need to implement all of the message types,
/// which may include experimental metadata types. For maximum compatibility,
-/// it is best to send data using RecordBatch
+/// it is best to send data using RecordBatch.
+///
+/// Tensor and SparseTensor are DEPRECATED. The recommended way to pass dense
+/// tensors over Arrow IPC is a RecordBatch field with the `arrow.fixed_shape_tensor`
+/// canonical type. Sparse tensors currently do not have a recommended replacement.
#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Default)]
#[repr(transparent)]
pub struct MessageHeader(pub u8);
@@ -744,7 +754,7 @@ impl<'a> RecordBatch<'a> {
}
/// Some types such as Utf8View are represented using a variable number of buffers.
/// For each such Field in the pre-ordered flattened logical schema, there will be
- /// an entry in variadicBufferCounts to indicate the number of number of variadic
+ /// an entry in variadicBufferCounts to indicate the number of variadic
/// buffers which belong to that Field in the current RecordBatch.
///
/// For example, the schema
diff --git a/arrow-ipc/src/gen/Schema.rs b/arrow-ipc/src/gen/Schema.rs
index 0472455ce0..f15072b517 100644
--- a/arrow-ipc/src/gen/Schema.rs
+++ b/arrow-ipc/src/gen/Schema.rs
@@ -169,8 +169,8 @@ pub const ENUM_VALUES_FEATURE: [Feature; 3] = [
/// forward compatibility guarantees).
/// 2. A means of negotiating between a client and server
/// what features a stream is allowed to use. The enums
-/// values here are intented to represent higher level
-/// features, additional details maybe negotiated
+/// values here are intended to represent higher level
+/// features, additional details may be negotiated
/// with key-value pairs specific to the protocol.
///
/// Enums added to this list should be assigned power-of-two values
@@ -664,13 +664,29 @@ pub const ENUM_VALUES_INTERVAL_UNIT: [IntervalUnit; 3] = [
IntervalUnit::MONTH_DAY_NANO,
];
+/// The unit of an Interval.
+///
+/// All integers in the units below are stored in the endianness indicated
+/// by the schema.
#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Default)]
#[repr(transparent)]
pub struct IntervalUnit(pub i16);
#[allow(non_upper_case_globals)]
impl IntervalUnit {
+ /// Indicates the number of elapsed whole months, stored as
+ /// 4-byte signed integers.
pub const YEAR_MONTH: Self = Self(0);
+ /// Indicates the number of elapsed days and milliseconds (no leap seconds),
+ /// stored as 2 contiguous 32-bit signed integers (8-bytes in total). Support
+ /// of this IntervalUnit is not required for full Arrow compatibility.
pub const DAY_TIME: Self = Self(1);
+ /// A triple of the number of elapsed months, days, and nanoseconds.
+ /// The values are stored contiguously in 16-byte blocks. Months and days are
+ /// encoded as 32-bit signed integers and nanoseconds is encoded as a 64-bit
+ /// signed integer. Nanoseconds does not allow for leap seconds. Each field is
+ /// independent (e.g. there is no constraint that nanoseconds have the same
+ /// sign as days or that the quantity of nanoseconds represents less than a
+ /// day's worth of time).
pub const MONTH_DAY_NANO: Self = Self(2);
pub const ENUM_MIN: i16 = 0;
@@ -1862,7 +1878,7 @@ pub enum MapOffset {}
/// may be set in the metadata for this field.
///
/// In a field with Map type, the field has a child Struct field, which then
-/// has two children: key type and the second the value type. The names of the
+/// has two children: the key type and the value type. The names of the
/// child fields may be respectively "entries", "key", and "value", but this is
/// not enforced.
///
@@ -3098,9 +3114,9 @@ pub enum DecimalOffset {}
#[derive(Copy, Clone, PartialEq)]
/// Exact decimal value represented as an integer value in two's
-/// complement. Currently only 128-bit (16-byte) and 256-bit (32-byte) integers
-/// are used. The representation uses the endianness indicated
-/// in the Schema.
+/// complement. Currently 32-bit (4-byte), 64-bit (8-byte),
+/// 128-bit (16-byte) and 256-bit (32-byte) integers are used.
+/// The representation uses the endianness indicated in the Schema.
pub struct Decimal<'a> {
pub _tab: flatbuffers::Table<'a>,
}
@@ -3156,7 +3172,7 @@ impl<'a> Decimal<'a> {
// which contains a valid value in this slot
unsafe { self._tab.get::<i32>(Decimal::VT_SCALE, Some(0)).unwrap() }
}
- /// Number of bits per value. The only accepted widths are 128 and 256.
+ /// Number of bits per value. The accepted widths are 32, 64, 128 and 256.
/// We use bitWidth for consistency with Int::bitWidth.
#[inline]
pub fn bitWidth(&self) -> i32 {
@@ -3739,6 +3755,9 @@ impl core::fmt::Debug for Timestamp<'_> {
pub enum IntervalOffset {}
#[derive(Copy, Clone, PartialEq)]
+/// A "calendar" interval which models types that don't necessarily
+/// have a precise duration without the context of a base timestamp (e.g.
+/// days can differ in length during day light savings time transitions).
pub struct Interval<'a> {
pub _tab: flatbuffers::Table<'a>,
}
@@ -3843,6 +3862,19 @@ impl core::fmt::Debug for Interval<'_> {
pub enum DurationOffset {}
#[derive(Copy, Clone, PartialEq)]
+/// An absolute length of time unrelated to any calendar artifacts.
+///
+/// For the purposes of Arrow Implementations, adding this value to a Timestamp
+/// ("t1") naively (i.e. simply summing the two numbers) is acceptable even
+/// though in some cases the resulting Timestamp (t2) would not account for
+/// leap-seconds during the elapsed time between "t1" and "t2". Similarly,
+/// representing the difference between two Unix timestamps is acceptable, but
+/// would yield a value that is possibly a few seconds off from the true elapsed
+/// time.
+///
+/// The resolution defaults to millisecond, but can be any of the other
+/// supported TimeUnit values as with Timestamp and Time types. This type is
+/// always represented as an 8-byte integer.
pub struct Duration<'a> {
pub _tab: flatbuffers::Table<'a>,
}
@@ -3948,7 +3980,7 @@ pub enum KeyValueOffset {}
#[derive(Copy, Clone, PartialEq)]
/// ----------------------------------------------------------------------
-/// user defined key value pairs to add custom metadata to arrow
+/// user defined key value pairs to add custom metadata to Arrow
/// key namespacing is the responsibility of the user
pub struct KeyValue<'a> {
pub _tab: flatbuffers::Table<'a>,
@@ -4147,7 +4179,7 @@ impl<'a> DictionaryEncoding<'a> {
}
}
/// By default, dictionaries are not ordered, or the order does not have
- /// semantic meaning. In some statistical, applications, dictionary-encoding
+ /// semantic meaning. In some statistical applications, dictionary-encoding
/// is used to represent ordered categorical data, and we provide a way to
/// preserve that metadata here
#[inline]
@@ -4330,7 +4362,7 @@ impl<'a> Field<'a> {
builder.finish()
}
- /// Name is not required, in i.e. a List
+ /// Name is not required (e.g., in a List)
#[inline]
pub fn name(&self) -> Option<&'a str> {
// Safety:
@@ -5412,6 +5444,7 @@ impl<'a> Schema<'a> {
>>(Schema::VT_FIELDS, None)
}
}
+ /// User-defined metadata
#[inline]
pub fn custom_metadata(
&self,
diff --git a/arrow-ipc/src/gen/SparseTensor.rs b/arrow-ipc/src/gen/SparseTensor.rs
index 1cadd1d3e0..1c754c8c9d 100644
--- a/arrow-ipc/src/gen/SparseTensor.rs
+++ b/arrow-ipc/src/gen/SparseTensor.rs
@@ -234,11 +234,11 @@ pub enum SparseTensorIndexCOOOffset {}
/// EXPERIMENTAL: Data structures for sparse tensors
/// Coordinate (COO) format of sparse tensor index.
///
-/// COO's index list are represented as a NxM matrix,
+/// COO's index list is represented as an NxM matrix,
/// where N is the number of non-zero values,
/// and M is the number of dimensions of a sparse tensor.
///
-/// indicesBuffer stores the location and size of the data of this indices
+/// indicesBuffer stores the location and size of the data of these indices
/// matrix. The value type and the stride of the indices matrix is
/// specified in indicesType and indicesStrides fields.
///
@@ -259,7 +259,7 @@ pub enum SparseTensorIndexCOOOffset {}
/// [2, 2, 3, 1, 2, 0],
/// [0, 1, 0, 0, 3, 4]]
/// ```
-/// When isCanonical is true, the indices is sorted in lexicographical order
+/// When isCanonical is true, the indices are sorted in lexicographical order
/// (row-major order), and it does not have duplicated entries. Otherwise,
/// the indices may not be sorted, or may have duplicated entries.
pub struct SparseTensorIndexCOO<'a> {
@@ -601,7 +601,7 @@ impl<'a> SparseMatrixIndexCSX<'a> {
/// contains the column indices of the corresponding non-zero values.
/// The type of index value is long.
///
- /// For example, the indices of the above X is:
+ /// For example, the indices of the above X are:
/// ```text
/// indices(X) = [1, 2, 2, 1, 3, 0, 2, 3, 1].
/// ```
@@ -800,7 +800,7 @@ impl<'a> SparseTensorIndexCSF<'a> {
/// CSF index recursively compresses each dimension of a tensor into a set
/// of prefix trees. Each path from a root to leaf forms one tensor
/// non-zero index. CSF is implemented with two arrays of buffers and one
- /// arrays of integers.
+ /// array of integers.
///
/// For example, let X be a 2x3x4x5 tensor and let it have the following
/// 8 non-zero values:
@@ -842,7 +842,7 @@ impl<'a> SparseTensorIndexCSF<'a> {
/// and `indptrBuffers[dim][i + 1]` signify a range of nodes in
/// `indicesBuffers[dim + 1]` who are children of `indicesBuffers[dim][i]` node.
///
- /// For example, the indptrBuffers for the above X is:
+ /// For example, the indptrBuffers for the above X are:
/// ```text
/// indptrBuffer(X) = [
/// [0, 2, 3],
@@ -881,7 +881,7 @@ impl<'a> SparseTensorIndexCSF<'a> {
}
/// indicesBuffers stores values of nodes.
/// Each tensor dimension corresponds to a buffer in indicesBuffers.
- /// For example, the indicesBuffers for the above X is:
+ /// For example, the indicesBuffers for the above X are:
/// ```text
/// indicesBuffer(X) = [
/// [0, 1],
@@ -1073,6 +1073,11 @@ impl core::fmt::Debug for SparseTensorIndexCSF<'_> {
pub enum SparseTensorOffset {}
#[derive(Copy, Clone, PartialEq)]
+/// DEPRECATED. Unlike dense tensors (see Tensor.fbs), the SparseTensor message
+/// currently doesn't have a recommended replacement as a RecordBatch column type.
+/// Feel free to discuss this on the development mailing-list (*) if this use case
+/// is important to you.
+/// (*) see <https://arrow.apache.org/community/>
pub struct SparseTensor<'a> {
pub _tab: flatbuffers::Table<'a>,
}
diff --git a/arrow-ipc/src/gen/Tensor.rs b/arrow-ipc/src/gen/Tensor.rs
index 80be30b686..c307110cef 100644
--- a/arrow-ipc/src/gen/Tensor.rs
+++ b/arrow-ipc/src/gen/Tensor.rs
@@ -155,6 +155,8 @@ impl core::fmt::Debug for TensorDim<'_> {
pub enum TensorOffset {}
#[derive(Copy, Clone, PartialEq)]
+/// DEPRECATED: The recommended way to pass tensors over Arrow IPC is
+/// using columns with the `arrow.fixed_shape_tensor` canonical type.
pub struct Tensor<'a> {
pub _tab: flatbuffers::Table<'a>,
}
diff --git a/format/File.fbs b/format/File.fbs
index 906d494f27..568b5482eb 100644
--- a/format/File.fbs
+++ b/format/File.fbs
@@ -38,7 +38,7 @@ table Footer {
struct Block {
- /// Index to the start of the RecordBlock (note this is past the Message header)
+ /// Index to the start of the RecordBatch (note this is past the Message header)
offset: long;
/// Length of the metadata
diff --git a/format/Flight.proto b/format/Flight.proto
index 653b983ef2..a8c6e72dbe 100644
--- a/format/Flight.proto
+++ b/format/Flight.proto
@@ -16,513 +16,549 @@
* 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;
- }
+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 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 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 to retrieve a particular stream from. This URI should be one of
+ * the following:
+ * - An empty string or the string 'arrow-flight-reuse-connection://?':
+ * indicating that the ticket can be redeemed on the service where the
+ * ticket was generated via a DoGet request.
+ * - A valid grpc URI (grpc://, grpc+tls://, grpc+unix://, etc.):
+ * indicating that the ticket can be redeemed on the service at the given
+ * URI via a DoGet request.
+ * - A valid HTTP URI (http://, https://, etc.):
+ * indicating that the client should perform a GET request against the
+ * given URI to retrieve the stream. The ticket should be empty
+ * in this case and should be ignored by the client. Cloud object storage
+ * can be utilized by presigned URLs or mediating the auth separately and
+ * returning the full URL (e.g. https://amzn-s3-demo-bucket.s3.us-west-2.amazonaws.com/...).
+ *
+ * We allow non-Flight URIs for the purpose of allowing Flight services to indicate that
+ * results can be downloaded in formats other than Arrow (such as Parquet) or to allow
+ * direct fetching of results from a URI to reduce excess copying and data movement.
+ * In these cases, the following conventions should be followed by servers and clients:
+ *
+ * - Unless otherwise specified by the 'Content-Type' header of the response,
+ * a client should assume the response is using the Arrow IPC Streaming format.
+ * Usage of an IANA media type like 'application/octet-stream' should be assumed to
+ * be using the Arrow IPC Streaming format.
+ * - The server may allow the client to choose a specific response format by
+ * specifying an 'Accept' header in the request, such as 'application/vnd.apache.parquet'
+ * or 'application/vnd.apache.arrow.stream'. If multiple types are requested and
+ * supported by the server, the choice of which to use is server-specific. If
+ * none of the requested content-types are supported, the server may respond with
+ * either 406 (Not Acceptable) or 415 (Unsupported Media Type), or successfully
+ * respond with a different format that it does support along with the correct
+ * 'Content-Type' header.
+ *
+ * Note: new schemes may be proposed in the future to allow for more flexibility based
+ * on community requests.
+ */
+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;
+}
diff --git a/format/FlightSql.proto b/format/FlightSql.proto
index 8f9e1c8d82..90e6e5baeb 100644
--- a/format/FlightSql.proto
+++ b/format/FlightSql.proto
@@ -16,1767 +16,1771 @@
* limitations under the License.
*/
- syntax = "proto3";
- import "google/protobuf/descriptor.proto";
-
- option java_package = "org.apache.arrow.flight.sql.impl";
- option go_package = "github.com/apache/arrow/go/arrow/flight/gen/flight";
- package arrow.flight.protocol.sql;
-
- /*
- * Represents a metadata request. Used in the command member of FlightDescriptor
- * for the following RPC calls:
- * - GetSchema: return the Arrow schema of the query.
- * - GetFlightInfo: execute the metadata request.
- *
- * The returned Arrow schema will be:
- * <
- * info_name: uint32 not null,
- * value: dense_union<
- * string_value: utf8,
- * bool_value: bool,
- * bigint_value: int64,
- * int32_bitmask: int32,
- * string_list: list<string_data: utf8>
- * int32_to_int32_list_map: map<key: int32, value: list<$data$: int32>>
- * >
- * where there is one row per requested piece of metadata information.
- */
- message CommandGetSqlInfo {
-
- /*
- * Values are modelled after ODBC's SQLGetInfo() function. This information is intended to provide
- * Flight SQL clients with basic, SQL syntax and SQL functions related information.
- * More information types can be added in future releases.
- * E.g. more SQL syntax support types, scalar functions support, type conversion support etc.
- *
- * Note that the set of metadata may expand.
- *
- * Initially, Flight SQL will support the following information types:
- * - Server Information - Range [0-500)
- * - Syntax Information - Range [500-1000)
- * Range [0-10,000) is reserved for defaults (see SqlInfo enum for default options).
- * Custom options should start at 10,000.
- *
- * If omitted, then all metadata will be retrieved.
- * Flight SQL Servers may choose to include additional metadata above and beyond the specified set, however they must
- * at least return the specified set. IDs ranging from 0 to 10,000 (exclusive) are reserved for future use.
- * If additional metadata is included, the metadata IDs should start from 10,000.
- */
- repeated uint32 info = 1;
- }
-
- // Options for CommandGetSqlInfo.
- enum SqlInfo {
-
- // Server Information [0-500): Provides basic information about the Flight SQL Server.
-
- // Retrieves a UTF-8 string with the name of the Flight SQL Server.
- FLIGHT_SQL_SERVER_NAME = 0;
-
- // Retrieves a UTF-8 string with the native version of the Flight SQL Server.
- FLIGHT_SQL_SERVER_VERSION = 1;
-
- // Retrieves a UTF-8 string with the Arrow format version of the Flight SQL Server.
- FLIGHT_SQL_SERVER_ARROW_VERSION = 2;
-
- /*
- * Retrieves a boolean value indicating whether the Flight SQL Server is read only.
- *
- * Returns:
- * - false: if read-write
- * - true: if read only
- */
- FLIGHT_SQL_SERVER_READ_ONLY = 3;
-
- /*
- * Retrieves a boolean value indicating whether the Flight SQL Server supports executing
- * SQL queries.
- *
- * Note that the absence of this info (as opposed to a false value) does not necessarily
- * mean that SQL is not supported, as this property was not originally defined.
- */
- FLIGHT_SQL_SERVER_SQL = 4;
-
- /*
- * Retrieves a boolean value indicating whether the Flight SQL Server supports executing
- * Substrait plans.
- */
- FLIGHT_SQL_SERVER_SUBSTRAIT = 5;
-
- /*
- * Retrieves a string value indicating the minimum supported Substrait version, or null
- * if Substrait is not supported.
- */
- FLIGHT_SQL_SERVER_SUBSTRAIT_MIN_VERSION = 6;
-
- /*
- * Retrieves a string value indicating the maximum supported Substrait version, or null
- * if Substrait is not supported.
- */
- FLIGHT_SQL_SERVER_SUBSTRAIT_MAX_VERSION = 7;
-
- /*
- * Retrieves an int32 indicating whether the Flight SQL Server supports the
- * BeginTransaction/EndTransaction/BeginSavepoint/EndSavepoint actions.
- *
- * Even if this is not supported, the database may still support explicit "BEGIN
- * TRANSACTION"/"COMMIT" SQL statements (see SQL_TRANSACTIONS_SUPPORTED); this property
- * is only about whether the server implements the Flight SQL API endpoints.
- *
- * The possible values are listed in `SqlSupportedTransaction`.
- */
- FLIGHT_SQL_SERVER_TRANSACTION = 8;
-
- /*
- * Retrieves a boolean value indicating whether the Flight SQL Server supports explicit
- * query cancellation (the CancelQuery action).
- */
- FLIGHT_SQL_SERVER_CANCEL = 9;
-
+syntax = "proto3";
+import "google/protobuf/descriptor.proto";
+
+option java_package = "org.apache.arrow.flight.sql.impl";
+option go_package = "github.com/apache/arrow-go/arrow/flight/gen/flight";
+package arrow.flight.protocol.sql;
+
+/*
+ * Represents a metadata request. Used in the command member of FlightDescriptor
+ * for the following RPC calls:
+ * - GetSchema: return the Arrow schema of the query.
+ * - GetFlightInfo: execute the metadata request.
+ *
+ * The returned Arrow schema will be:
+ * <
+ * info_name: uint32 not null,
+ * value: dense_union<
+ * string_value: utf8,
+ * bool_value: bool,
+ * bigint_value: int64,
+ * int32_bitmask: int32,
+ * string_list: list<string_data: utf8>
+ * int32_to_int32_list_map: map<key: int32, value: list<$data$: int32>>
+ * >
+ * where there is one row per requested piece of metadata information.
+ */
+message CommandGetSqlInfo {
+
+ /*
+ * Values are modelled after ODBC's SQLGetInfo() function. This information is intended to provide
+ * Flight SQL clients with basic, SQL syntax and SQL functions related information.
+ * More information types can be added in future releases.
+ * E.g. more SQL syntax support types, scalar functions support, type conversion support etc.
+ *
+ * Note that the set of metadata may expand.
+ *
+ * Initially, Flight SQL will support the following information types:
+ * - Server Information - Range [0-500)
+ * - Syntax Information - Range [500-1000)
+ * Range [0-10,000) is reserved for defaults (see SqlInfo enum for default options).
+ * Custom options should start at 10,000.
+ *
+ * If omitted, then all metadata will be retrieved.
+ * Flight SQL Servers may choose to include additional metadata above and beyond the specified set, however they must
+ * at least return the specified set. IDs ranging from 0 to 10,000 (exclusive) are reserved for future use.
+ * If additional metadata is included, the metadata IDs should start from 10,000.
+ */
+ repeated uint32 info = 1;
+}
+
+// Options for CommandGetSqlInfo.
+enum SqlInfo {
+
+ // Server Information [0-500): Provides basic information about the Flight SQL Server.
+
+ // Retrieves a UTF-8 string with the name of the Flight SQL Server.
+ FLIGHT_SQL_SERVER_NAME = 0;
+
+ // Retrieves a UTF-8 string with the native version of the Flight SQL Server.
+ FLIGHT_SQL_SERVER_VERSION = 1;
+
+ // Retrieves a UTF-8 string with the Arrow format version of the Flight SQL Server.
+ FLIGHT_SQL_SERVER_ARROW_VERSION = 2;
+
+ /*
+ * Retrieves a boolean value indicating whether the Flight SQL Server is read only.
+ *
+ * Returns:
+ * - false: if read-write
+ * - true: if read only
+ */
+ FLIGHT_SQL_SERVER_READ_ONLY = 3;
+
+ /*
+ * Retrieves a boolean value indicating whether the Flight SQL Server supports executing
+ * SQL queries.
+ *
+ * Note that the absence of this info (as opposed to a false value) does not necessarily
+ * mean that SQL is not supported, as this property was not originally defined.
+ */
+ FLIGHT_SQL_SERVER_SQL = 4;
+
+ /*
+ * Retrieves a boolean value indicating whether the Flight SQL Server supports executing
+ * Substrait plans.
+ */
+ FLIGHT_SQL_SERVER_SUBSTRAIT = 5;
+
+ /*
+ * Retrieves a string value indicating the minimum supported Substrait version, or null
+ * if Substrait is not supported.
+ */
+ FLIGHT_SQL_SERVER_SUBSTRAIT_MIN_VERSION = 6;
+
+ /*
+ * Retrieves a string value indicating the maximum supported Substrait version, or null
+ * if Substrait is not supported.
+ */
+ FLIGHT_SQL_SERVER_SUBSTRAIT_MAX_VERSION = 7;
+
+ /*
+ * Retrieves an int32 indicating whether the Flight SQL Server supports the
+ * BeginTransaction/EndTransaction/BeginSavepoint/EndSavepoint actions.
+ *
+ * Even if this is not supported, the database may still support explicit "BEGIN
+ * TRANSACTION"/"COMMIT" SQL statements (see SQL_TRANSACTIONS_SUPPORTED); this property
+ * is only about whether the server implements the Flight SQL API endpoints.
+ *
+ * The possible values are listed in `SqlSupportedTransaction`.
+ */
+ FLIGHT_SQL_SERVER_TRANSACTION = 8;
+
+ /*
+ * Retrieves a boolean value indicating whether the Flight SQL Server supports explicit
+ * query cancellation (the CancelQuery action).
+ */
+ FLIGHT_SQL_SERVER_CANCEL = 9;
+
+ /*
+ * Retrieves a boolean value indicating whether the Flight SQL Server supports executing
+ * bulk ingestion.
+ */
+ FLIGHT_SQL_SERVER_BULK_INGESTION = 10;
+
+ /*
+ * Retrieves a boolean value indicating whether transactions are supported for bulk ingestion. If not, invoking
+ * the method commit in the context of a bulk ingestion is a noop, and the isolation level is
+ * `arrow.flight.protocol.sql.SqlTransactionIsolationLevel.TRANSACTION_NONE`.
+ *
+ * Returns:
+ * - false: if bulk ingestion transactions are unsupported;
+ * - true: if bulk ingestion transactions are supported.
+ */
+ FLIGHT_SQL_SERVER_INGEST_TRANSACTIONS_SUPPORTED = 11;
+
+ /*
+ * Retrieves an int32 indicating the timeout (in milliseconds) for prepared statement handles.
+ *
+ * If 0, there is no timeout. Servers should reset the timeout when the handle is used in a command.
+ */
+ FLIGHT_SQL_SERVER_STATEMENT_TIMEOUT = 100;
+
+ /*
+ * Retrieves an int32 indicating the timeout (in milliseconds) for transactions, since transactions are not tied to a connection.
+ *
+ * If 0, there is no timeout. Servers should reset the timeout when the handle is used in a command.
+ */
+ FLIGHT_SQL_SERVER_TRANSACTION_TIMEOUT = 101;
+
+ // SQL Syntax Information [500-1000): provides information about SQL syntax supported by the Flight SQL Server.
+
+ /*
+ * Retrieves a boolean value indicating whether the Flight SQL Server supports CREATE and DROP of catalogs.
+ *
+ * Returns:
+ * - false: if it doesn't support CREATE and DROP of catalogs.
+ * - true: if it supports CREATE and DROP of catalogs.
+ */
+ SQL_DDL_CATALOG = 500;
+
+ /*
+ * Retrieves a boolean value indicating whether the Flight SQL Server supports CREATE and DROP of schemas.
+ *
+ * Returns:
+ * - false: if it doesn't support CREATE and DROP of schemas.
+ * - true: if it supports CREATE and DROP of schemas.
+ */
+ SQL_DDL_SCHEMA = 501;
+
+ /*
+ * Indicates whether the Flight SQL Server supports CREATE and DROP of tables.
+ *
+ * Returns:
+ * - false: if it doesn't support CREATE and DROP of tables.
+ * - true: if it supports CREATE and DROP of tables.
+ */
+ SQL_DDL_TABLE = 502;
+
+ /*
+ * Retrieves an int32 ordinal representing the case sensitivity of catalog, table, schema and table names.
+ *
+ * The possible values are listed in `arrow.flight.protocol.sql.SqlSupportedCaseSensitivity`.
+ */
+ SQL_IDENTIFIER_CASE = 503;
+
+ // Retrieves a UTF-8 string with the supported character(s) used to surround a delimited identifier.
+ SQL_IDENTIFIER_QUOTE_CHAR = 504;
+
+ /*
+ * Retrieves an int32 describing the case sensitivity of quoted identifiers.
+ *
+ * The possible values are listed in `arrow.flight.protocol.sql.SqlSupportedCaseSensitivity`.
+ */
+ SQL_QUOTED_IDENTIFIER_CASE = 505;
+
+ /*
+ * Retrieves a boolean value indicating whether all tables are selectable.
+ *
+ * Returns:
+ * - false: if not all tables are selectable or if none are;
+ * - true: if all tables are selectable.
+ */
+ SQL_ALL_TABLES_ARE_SELECTABLE = 506;
+
+ /*
+ * Retrieves the null ordering.
+ *
+ * Returns an int32 ordinal for the null ordering being used, as described in
+ * `arrow.flight.protocol.sql.SqlNullOrdering`.
+ */
+ SQL_NULL_ORDERING = 507;
+
+ // Retrieves a UTF-8 string list with values of the supported keywords.
+ SQL_KEYWORDS = 508;
+
+ // Retrieves a UTF-8 string list with values of the supported numeric functions.
+ SQL_NUMERIC_FUNCTIONS = 509;
+
+ // Retrieves a UTF-8 string list with values of the supported string functions.
+ SQL_STRING_FUNCTIONS = 510;
+
+ // Retrieves a UTF-8 string list with values of the supported system functions.
+ SQL_SYSTEM_FUNCTIONS = 511;
+
+ // Retrieves a UTF-8 string list with values of the supported datetime functions.
+ SQL_DATETIME_FUNCTIONS = 512;
+
+ /*
+ * Retrieves the UTF-8 string that can be used to escape wildcard characters.
+ * This is the string that can be used to escape '_' or '%' in the catalog search parameters that are a pattern
+ * (and therefore use one of the wildcard characters).
+ * The '_' character represents any single character; the '%' character represents any sequence of zero or more
+ * characters.
+ */
+ SQL_SEARCH_STRING_ESCAPE = 513;
+
+ /*
+ * Retrieves a UTF-8 string with all the "extra" characters that can be used in unquoted identifier names
+ * (those beyond a-z, A-Z, 0-9 and _).
+ */
+ SQL_EXTRA_NAME_CHARACTERS = 514;
+
+ /*
+ * Retrieves a boolean value indicating whether column aliasing is supported.
+ * If so, the SQL AS clause can be used to provide names for computed columns or to provide alias names for columns
+ * as required.
+ *
+ * Returns:
+ * - false: if column aliasing is unsupported;
+ * - true: if column aliasing is supported.
+ */
+ SQL_SUPPORTS_COLUMN_ALIASING = 515;
+
+ /*
+ * Retrieves a boolean value indicating whether concatenations between null and non-null values being
+ * null are supported.
+ *
+ * Returns:
+ * - false: if concatenations between null and non-null values being null are unsupported;
+ * - true: if concatenations between null and non-null values being null are supported.
+ */
+ SQL_NULL_PLUS_NULL_IS_NULL = 516;
+
+ /*
+ * Retrieves a map where the key is the type to convert from and the value is a list with the types to convert to,
+ * indicating the supported conversions. Each key and each item on the list value is a value to a predefined type on
+ * SqlSupportsConvert enum.
+ * The returned map will be: map<int32, list<int32>>
+ */
+ SQL_SUPPORTS_CONVERT = 517;
+
+ /*
+ * Retrieves a boolean value indicating whether, when table correlation names are supported,
+ * they are restricted to being different from the names of the tables.
+ *
+ * Returns:
+ * - false: if table correlation names are unsupported;
+ * - true: if table correlation names are supported.
+ */
+ SQL_SUPPORTS_TABLE_CORRELATION_NAMES = 518;
+
+ /*
+ * Retrieves a boolean value indicating whether, when table correlation names are supported,
+ * they are restricted to being different from the names of the tables.
+ *
+ * Returns:
+ * - false: if different table correlation names are unsupported;
+ * - true: if different table correlation names are supported
+ */
+ SQL_SUPPORTS_DIFFERENT_TABLE_CORRELATION_NAMES = 519;
+
+ /*
+ * Retrieves a boolean value indicating whether expressions in ORDER BY lists are supported.
+ *
+ * Returns:
+ * - false: if expressions in ORDER BY are unsupported;
+ * - true: if expressions in ORDER BY are supported;
+ */
+ SQL_SUPPORTS_EXPRESSIONS_IN_ORDER_BY = 520;
+
+ /*
+ * Retrieves a boolean value indicating whether using a column that is not in the SELECT statement in a GROUP BY
+ * clause is supported.
+ *
+ * Returns:
+ * - false: if using a column that is not in the SELECT statement in a GROUP BY clause is unsupported;
+ * - true: if using a column that is not in the SELECT statement in a GROUP BY clause is supported.
+ */
+ SQL_SUPPORTS_ORDER_BY_UNRELATED = 521;
+
+ /*
+ * Retrieves the supported GROUP BY commands;
+ *
+ * Returns an int32 bitmask value representing the supported commands.
+ * The returned bitmask should be parsed in order to retrieve the supported commands.
+ *
+ * For instance:
+ * - return 0 (\b0) => [] (GROUP BY is unsupported);
+ * - return 1 (\b1) => [SQL_GROUP_BY_UNRELATED];
+ * - return 2 (\b10) => [SQL_GROUP_BY_BEYOND_SELECT];
+ * - return 3 (\b11) => [SQL_GROUP_BY_UNRELATED, SQL_GROUP_BY_BEYOND_SELECT].
+ * Valid GROUP BY types are described under `arrow.flight.protocol.sql.SqlSupportedGroupBy`.
+ */
+ SQL_SUPPORTED_GROUP_BY = 522;
+
+ /*
+ * Retrieves a boolean value indicating whether specifying a LIKE escape clause is supported.
+ *
+ * Returns:
+ * - false: if specifying a LIKE escape clause is unsupported;
+ * - true: if specifying a LIKE escape clause is supported.
+ */
+ SQL_SUPPORTS_LIKE_ESCAPE_CLAUSE = 523;
+
+ /*
+ * Retrieves a boolean value indicating whether columns may be defined as non-nullable.
+ *
+ * Returns:
+ * - false: if columns cannot be defined as non-nullable;
+ * - true: if columns may be defined as non-nullable.
+ */
+ SQL_SUPPORTS_NON_NULLABLE_COLUMNS = 524;
+
+ /*
+ * Retrieves the supported SQL grammar level as per the ODBC specification.
+ *
+ * Returns an int32 bitmask value representing the supported SQL grammar level.
+ * The returned bitmask should be parsed in order to retrieve the supported grammar levels.
+ *
+ * For instance:
+ * - return 0 (\b0) => [] (SQL grammar is unsupported);
+ * - return 1 (\b1) => [SQL_MINIMUM_GRAMMAR];
+ * - return 2 (\b10) => [SQL_CORE_GRAMMAR];
+ * - return 3 (\b11) => [SQL_MINIMUM_GRAMMAR, SQL_CORE_GRAMMAR];
+ * - return 4 (\b100) => [SQL_EXTENDED_GRAMMAR];
+ * - return 5 (\b101) => [SQL_MINIMUM_GRAMMAR, SQL_EXTENDED_GRAMMAR];
+ * - return 6 (\b110) => [SQL_CORE_GRAMMAR, SQL_EXTENDED_GRAMMAR];
+ * - return 7 (\b111) => [SQL_MINIMUM_GRAMMAR, SQL_CORE_GRAMMAR, SQL_EXTENDED_GRAMMAR].
+ * Valid SQL grammar levels are described under `arrow.flight.protocol.sql.SupportedSqlGrammar`.
+ */
+ SQL_SUPPORTED_GRAMMAR = 525;
+
+ /*
+ * Retrieves the supported ANSI92 SQL grammar level.
+ *
+ * Returns an int32 bitmask value representing the supported ANSI92 SQL grammar level.
+ * The returned bitmask should be parsed in order to retrieve the supported commands.
+ *
+ * For instance:
+ * - return 0 (\b0) => [] (ANSI92 SQL grammar is unsupported);
+ * - return 1 (\b1) => [ANSI92_ENTRY_SQL];
+ * - return 2 (\b10) => [ANSI92_INTERMEDIATE_SQL];
+ * - return 3 (\b11) => [ANSI92_ENTRY_SQL, ANSI92_INTERMEDIATE_SQL];
+ * - return 4 (\b100) => [ANSI92_FULL_SQL];
+ * - return 5 (\b101) => [ANSI92_ENTRY_SQL, ANSI92_FULL_SQL];
+ * - return 6 (\b110) => [ANSI92_INTERMEDIATE_SQL, ANSI92_FULL_SQL];
+ * - return 7 (\b111) => [ANSI92_ENTRY_SQL, ANSI92_INTERMEDIATE_SQL, ANSI92_FULL_SQL].
+ * Valid ANSI92 SQL grammar levels are described under `arrow.flight.protocol.sql.SupportedAnsi92SqlGrammarLevel`.
+ */
+ SQL_ANSI92_SUPPORTED_LEVEL = 526;
+
+ /*
+ * Retrieves a boolean value indicating whether the SQL Integrity Enhancement Facility is supported.
+ *
+ * Returns:
+ * - false: if the SQL Integrity Enhancement Facility is unsupported;
+ * - true: if the SQL Integrity Enhancement Facility is supported.
+ */
+ SQL_SUPPORTS_INTEGRITY_ENHANCEMENT_FACILITY = 527;
+
+ /*
+ * Retrieves the support level for SQL OUTER JOINs.
+ *
+ * Returns an int32 ordinal for the SQL ordering being used, as described in
+ * `arrow.flight.protocol.sql.SqlOuterJoinsSupportLevel`.
+ */
+ SQL_OUTER_JOINS_SUPPORT_LEVEL = 528;
+
+ // Retrieves a UTF-8 string with the preferred term for "schema".
+ SQL_SCHEMA_TERM = 529;
+
+ // Retrieves a UTF-8 string with the preferred term for "procedure".
+ SQL_PROCEDURE_TERM = 530;
+
+ /*
+ * Retrieves a UTF-8 string with the preferred term for "catalog".
+ * If an empty string is returned it is assumed that the server does NOT support catalogs.
+ */
+ SQL_CATALOG_TERM = 531;
+
+ /*
+ * Retrieves a boolean value indicating whether a catalog appears at the start of a fully qualified table name.
+ *
+ * - false: if a catalog does not appear at the start of a fully qualified table name;
+ * - true: if a catalog appears at the start of a fully qualified table name.
+ */
+ SQL_CATALOG_AT_START = 532;
+
+ /*
+ * Retrieves the supported actions for a SQL schema.
+ *
+ * Returns an int32 bitmask value representing the supported actions for a SQL schema.
+ * The returned bitmask should be parsed in order to retrieve the supported actions for a SQL schema.
+ *
+ * For instance:
+ * - return 0 (\b0) => [] (no supported actions for SQL schema);
+ * - return 1 (\b1) => [SQL_ELEMENT_IN_PROCEDURE_CALLS];
+ * - return 2 (\b10) => [SQL_ELEMENT_IN_INDEX_DEFINITIONS];
+ * - return 3 (\b11) => [SQL_ELEMENT_IN_PROCEDURE_CALLS, SQL_ELEMENT_IN_INDEX_DEFINITIONS];
+ * - return 4 (\b100) => [SQL_ELEMENT_IN_PRIVILEGE_DEFINITIONS];
+ * - return 5 (\b101) => [SQL_ELEMENT_IN_PROCEDURE_CALLS, SQL_ELEMENT_IN_PRIVILEGE_DEFINITIONS];
+ * - return 6 (\b110) => [SQL_ELEMENT_IN_INDEX_DEFINITIONS, SQL_ELEMENT_IN_PRIVILEGE_DEFINITIONS];
+ * - return 7 (\b111) => [SQL_ELEMENT_IN_PROCEDURE_CALLS, SQL_ELEMENT_IN_INDEX_DEFINITIONS, SQL_ELEMENT_IN_PRIVILEGE_DEFINITIONS].
+ * Valid actions for a SQL schema are described under `arrow.flight.protocol.sql.SqlSupportedElementActions`.
+ */
+ SQL_SCHEMAS_SUPPORTED_ACTIONS = 533;
+
+ /*
+ * Retrieves the supported actions for a SQL catalog.
+ *
+ * Returns an int32 bitmask value representing the supported actions for a SQL catalog.
+ * The returned bitmask should be parsed in order to retrieve the supported actions for a SQL catalog.
+ *
+ * For instance:
+ * - return 0 (\b0) => [] (no supported actions for SQL catalog);
+ * - return 1 (\b1) => [SQL_ELEMENT_IN_PROCEDURE_CALLS];
+ * - return 2 (\b10) => [SQL_ELEMENT_IN_INDEX_DEFINITIONS];
+ * - return 3 (\b11) => [SQL_ELEMENT_IN_PROCEDURE_CALLS, SQL_ELEMENT_IN_INDEX_DEFINITIONS];
+ * - return 4 (\b100) => [SQL_ELEMENT_IN_PRIVILEGE_DEFINITIONS];
+ * - return 5 (\b101) => [SQL_ELEMENT_IN_PROCEDURE_CALLS, SQL_ELEMENT_IN_PRIVILEGE_DEFINITIONS];
+ * - return 6 (\b110) => [SQL_ELEMENT_IN_INDEX_DEFINITIONS, SQL_ELEMENT_IN_PRIVILEGE_DEFINITIONS];
+ * - return 7 (\b111) => [SQL_ELEMENT_IN_PROCEDURE_CALLS, SQL_ELEMENT_IN_INDEX_DEFINITIONS, SQL_ELEMENT_IN_PRIVILEGE_DEFINITIONS].
+ * Valid actions for a SQL catalog are described under `arrow.flight.protocol.sql.SqlSupportedElementActions`.
+ */
+ SQL_CATALOGS_SUPPORTED_ACTIONS = 534;
+
+ /*
+ * Retrieves the supported SQL positioned commands.
+ *
+ * Returns an int32 bitmask value representing the supported SQL positioned commands.
+ * The returned bitmask should be parsed in order to retrieve the supported SQL positioned commands.
+ *
+ * For instance:
+ * - return 0 (\b0) => [] (no supported SQL positioned commands);
+ * - return 1 (\b1) => [SQL_POSITIONED_DELETE];
+ * - return 2 (\b10) => [SQL_POSITIONED_UPDATE];
+ * - return 3 (\b11) => [SQL_POSITIONED_DELETE, SQL_POSITIONED_UPDATE].
+ * Valid SQL positioned commands are described under `arrow.flight.protocol.sql.SqlSupportedPositionedCommands`.
+ */
+ SQL_SUPPORTED_POSITIONED_COMMANDS = 535;
+
+ /*
+ * Retrieves a boolean value indicating whether SELECT FOR UPDATE statements are supported.
+ *
+ * Returns:
+ * - false: if SELECT FOR UPDATE statements are unsupported;
+ * - true: if SELECT FOR UPDATE statements are supported.
+ */
+ SQL_SELECT_FOR_UPDATE_SUPPORTED = 536;
+
+ /*
+ * Retrieves a boolean value indicating whether stored procedure calls that use the stored procedure escape syntax
+ * are supported.
+ *
+ * Returns:
+ * - false: if stored procedure calls that use the stored procedure escape syntax are unsupported;
+ * - true: if stored procedure calls that use the stored procedure escape syntax are supported.
+ */
+ SQL_STORED_PROCEDURES_SUPPORTED = 537;
+
+ /*
+ * Retrieves the supported SQL subqueries.
+ *
+ * Returns an int32 bitmask value representing the supported SQL subqueries.
+ * The returned bitmask should be parsed in order to retrieve the supported SQL subqueries.
+ *
+ * For instance:
+ * - return 0 (\b0) => [] (no supported SQL subqueries);
+ * - return 1 (\b1) => [SQL_SUBQUERIES_IN_COMPARISONS];
+ * - return 2 (\b10) => [SQL_SUBQUERIES_IN_EXISTS];
+ * - return 3 (\b11) => [SQL_SUBQUERIES_IN_COMPARISONS, SQL_SUBQUERIES_IN_EXISTS];
+ * - return 4 (\b100) => [SQL_SUBQUERIES_IN_INS];
+ * - return 5 (\b101) => [SQL_SUBQUERIES_IN_COMPARISONS, SQL_SUBQUERIES_IN_INS];
+ * - return 6 (\b110) => [SQL_SUBQUERIES_IN_INS, SQL_SUBQUERIES_IN_EXISTS];
+ * - return 7 (\b111) => [SQL_SUBQUERIES_IN_COMPARISONS, SQL_SUBQUERIES_IN_EXISTS, SQL_SUBQUERIES_IN_INS];
+ * - return 8 (\b1000) => [SQL_SUBQUERIES_IN_QUANTIFIEDS];
+ * - return 9 (\b1001) => [SQL_SUBQUERIES_IN_COMPARISONS, SQL_SUBQUERIES_IN_QUANTIFIEDS];
+ * - return 10 (\b1010) => [SQL_SUBQUERIES_IN_EXISTS, SQL_SUBQUERIES_IN_QUANTIFIEDS];
+ * - return 11 (\b1011) => [SQL_SUBQUERIES_IN_COMPARISONS, SQL_SUBQUERIES_IN_EXISTS, SQL_SUBQUERIES_IN_QUANTIFIEDS];
+ * - return 12 (\b1100) => [SQL_SUBQUERIES_IN_INS, SQL_SUBQUERIES_IN_QUANTIFIEDS];
+ * - return 13 (\b1101) => [SQL_SUBQUERIES_IN_COMPARISONS, SQL_SUBQUERIES_IN_INS, SQL_SUBQUERIES_IN_QUANTIFIEDS];
+ * - return 14 (\b1110) => [SQL_SUBQUERIES_IN_EXISTS, SQL_SUBQUERIES_IN_INS, SQL_SUBQUERIES_IN_QUANTIFIEDS];
+ * - return 15 (\b1111) => [SQL_SUBQUERIES_IN_COMPARISONS, SQL_SUBQUERIES_IN_EXISTS, SQL_SUBQUERIES_IN_INS, SQL_SUBQUERIES_IN_QUANTIFIEDS];
+ * - ...
+ * Valid SQL subqueries are described under `arrow.flight.protocol.sql.SqlSupportedSubqueries`.
+ */
+ SQL_SUPPORTED_SUBQUERIES = 538;
+
+ /*
+ * Retrieves a boolean value indicating whether correlated subqueries are supported.
+ *
+ * Returns:
+ * - false: if correlated subqueries are unsupported;
+ * - true: if correlated subqueries are supported.
+ */
+ SQL_CORRELATED_SUBQUERIES_SUPPORTED = 539;
+
+ /*
+ * Retrieves the supported SQL UNIONs.
+ *
+ * Returns an int32 bitmask value representing the supported SQL UNIONs.
+ * The returned bitmask should be parsed in order to retrieve the supported SQL UNIONs.
+ *
+ * For instance:
+ * - return 0 (\b0) => [] (no supported SQL UNIONs);
+ * - return 1 (\b1) => [SQL_UNION];
+ * - return 2 (\b10) => [SQL_UNION_ALL];
+ * - return 3 (\b11) => [SQL_UNION, SQL_UNION_ALL].
+ * Valid SQL UNIONs are described under `arrow.flight.protocol.sql.SqlSupportedUnions`.
+ */
+ SQL_SUPPORTED_UNIONS = 540;
+
+ // Retrieves an int64 value representing the maximum number of hex characters allowed in an inline binary literal.
+ SQL_MAX_BINARY_LITERAL_LENGTH = 541;
+
+ // Retrieves an int64 value representing the maximum number of characters allowed for a character literal.
+ SQL_MAX_CHAR_LITERAL_LENGTH = 542;
+
+ // Retrieves an int64 value representing the maximum number of characters allowed for a column name.
+ SQL_MAX_COLUMN_NAME_LENGTH = 543;
+
+ // Retrieves an int64 value representing the maximum number of columns allowed in a GROUP BY clause.
+ SQL_MAX_COLUMNS_IN_GROUP_BY = 544;
+
+ // Retrieves an int64 value representing the maximum number of columns allowed in an index.
+ SQL_MAX_COLUMNS_IN_INDEX = 545;
+
+ // Retrieves an int64 value representing the maximum number of columns allowed in an ORDER BY clause.
+ SQL_MAX_COLUMNS_IN_ORDER_BY = 546;
+
+ // Retrieves an int64 value representing the maximum number of columns allowed in a SELECT list.
+ SQL_MAX_COLUMNS_IN_SELECT = 547;
+
+ // Retrieves an int64 value representing the maximum number of columns allowed in a table.
+ SQL_MAX_COLUMNS_IN_TABLE = 548;
+
+ // Retrieves an int64 value representing the maximum number of concurrent connections possible.
+ SQL_MAX_CONNECTIONS = 549;
+
+ // Retrieves an int64 value representing the maximum number of characters allowed in a cursor name.
+ SQL_MAX_CURSOR_NAME_LENGTH = 550;
+
+ /*
+ * Retrieves an int64 value representing the maximum number of bytes allowed for an index,
+ * including all of the parts of the index.
+ */
+ SQL_MAX_INDEX_LENGTH = 551;
+
+ // Retrieves an int64 value representing the maximum number of characters allowed in a schema name.
+ SQL_DB_SCHEMA_NAME_LENGTH = 552;
+
+ // Retrieves an int64 value representing the maximum number of characters allowed in a procedure name.
+ SQL_MAX_PROCEDURE_NAME_LENGTH = 553;
+
+ // Retrieves an int64 value representing the maximum number of characters allowed in a catalog name.
+ SQL_MAX_CATALOG_NAME_LENGTH = 554;
+
+ // Retrieves an int64 value representing the maximum number of bytes allowed in a single row.
+ SQL_MAX_ROW_SIZE = 555;
+
+ /*
+ * Retrieves a boolean indicating whether the return value for the JDBC method getMaxRowSize includes the SQL
+ * data types LONGVARCHAR and LONGVARBINARY.
+ *
+ * Returns:
+ * - false: if return value for the JDBC method getMaxRowSize does
+ * not include the SQL data types LONGVARCHAR and LONGVARBINARY;
+ * - true: if return value for the JDBC method getMaxRowSize includes
+ * the SQL data types LONGVARCHAR and LONGVARBINARY.
+ */
+ SQL_MAX_ROW_SIZE_INCLUDES_BLOBS = 556;
+
+ /*
+ * Retrieves an int64 value representing the maximum number of characters allowed for an SQL statement;
+ * a result of 0 (zero) means that there is no limit or the limit is not known.
+ */
+ SQL_MAX_STATEMENT_LENGTH = 557;
+
+ // Retrieves an int64 value representing the maximum number of active statements that can be open at the same time.
+ SQL_MAX_STATEMENTS = 558;
+
+ // Retrieves an int64 value representing the maximum number of characters allowed in a table name.
+ SQL_MAX_TABLE_NAME_LENGTH = 559;
+
+ // Retrieves an int64 value representing the maximum number of tables allowed in a SELECT statement.
+ SQL_MAX_TABLES_IN_SELECT = 560;
+
+ // Retrieves an int64 value representing the maximum number of characters allowed in a user name.
+ SQL_MAX_USERNAME_LENGTH = 561;
+
+ /*
+ * Retrieves this database's default transaction isolation level as described in
+ * `arrow.flight.protocol.sql.SqlTransactionIsolationLevel`.
+ *
+ * Returns an int32 ordinal for the SQL transaction isolation level.
+ */
+ SQL_DEFAULT_TRANSACTION_ISOLATION = 562;
+
+ /*
+ * Retrieves a boolean value indicating whether transactions are supported. If not, invoking the method commit is a
+ * noop, and the isolation level is `arrow.flight.protocol.sql.SqlTransactionIsolationLevel.TRANSACTION_NONE`.
+ *
+ * Returns:
+ * - false: if transactions are unsupported;
+ * - true: if transactions are supported.
+ */
+ SQL_TRANSACTIONS_SUPPORTED = 563;
+
+ /*
+ * Retrieves the supported transactions isolation levels.
+ *
+ * Returns an int32 bitmask value representing the supported transactions isolation levels.
+ * The returned bitmask should be parsed in order to retrieve the supported transactions isolation levels.
+ *
+ * For instance:
+ * - return 0 (\b0) => [] (no supported SQL transactions isolation levels);
+ * - return 1 (\b1) => [SQL_TRANSACTION_NONE];
+ * - return 2 (\b10) => [SQL_TRANSACTION_READ_UNCOMMITTED];
+ * - return 3 (\b11) => [SQL_TRANSACTION_NONE, SQL_TRANSACTION_READ_UNCOMMITTED];
+ * - return 4 (\b100) => [SQL_TRANSACTION_READ_COMMITTED];
+ * - return 5 (\b101) => [SQL_TRANSACTION_NONE, SQL_TRANSACTION_READ_COMMITTED];
+ * - return 6 (\b110) => [SQL_TRANSACTION_READ_UNCOMMITTED, SQL_TRANSACTION_READ_COMMITTED];
+ * - return 7 (\b111) => [SQL_TRANSACTION_NONE, SQL_TRANSACTION_READ_UNCOMMITTED, SQL_TRANSACTION_READ_COMMITTED];
+ * - return 8 (\b1000) => [SQL_TRANSACTION_REPEATABLE_READ];
+ * - return 9 (\b1001) => [SQL_TRANSACTION_NONE, SQL_TRANSACTION_REPEATABLE_READ];
+ * - return 10 (\b1010) => [SQL_TRANSACTION_READ_UNCOMMITTED, SQL_TRANSACTION_REPEATABLE_READ];
+ * - return 11 (\b1011) => [SQL_TRANSACTION_NONE, SQL_TRANSACTION_READ_UNCOMMITTED, SQL_TRANSACTION_REPEATABLE_READ];
+ * - return 12 (\b1100) => [SQL_TRANSACTION_READ_COMMITTED, SQL_TRANSACTION_REPEATABLE_READ];
+ * - return 13 (\b1101) => [SQL_TRANSACTION_NONE, SQL_TRANSACTION_READ_COMMITTED, SQL_TRANSACTION_REPEATABLE_READ];
+ * - return 14 (\b1110) => [SQL_TRANSACTION_READ_UNCOMMITTED, SQL_TRANSACTION_READ_COMMITTED, SQL_TRANSACTION_REPEATABLE_READ];
+ * - return 15 (\b1111) => [SQL_TRANSACTION_NONE, SQL_TRANSACTION_READ_UNCOMMITTED, SQL_TRANSACTION_READ_COMMITTED, SQL_TRANSACTION_REPEATABLE_READ];
+ * - return 16 (\b10000) => [SQL_TRANSACTION_SERIALIZABLE];
+ * - ...
+ * Valid SQL transaction isolation levels are described under `arrow.flight.protocol.sql.SqlTransactionIsolationLevel`.
+ */
+ SQL_SUPPORTED_TRANSACTIONS_ISOLATION_LEVELS = 564;
+
+ /*
+ * Retrieves a boolean value indicating whether a data definition statement within a transaction forces
+ * the transaction to commit.
+ *
+ * Returns:
+ * - false: if a data definition statement within a transaction does not force the transaction to commit;
+ * - true: if a data definition statement within a transaction forces the transaction to commit.
+ */
+ SQL_DATA_DEFINITION_CAUSES_TRANSACTION_COMMIT = 565;
+
+ /*
+ * Retrieves a boolean value indicating whether a data definition statement within a transaction is ignored.
+ *
+ * Returns:
+ * - false: if a data definition statement within a transaction is taken into account;
+ * - true: a data definition statement within a transaction is ignored.
+ */
+ SQL_DATA_DEFINITIONS_IN_TRANSACTIONS_IGNORED = 566;
+
+ /*
+ * Retrieves an int32 bitmask value representing the supported result set types.
+ * The returned bitmask should be parsed in order to retrieve the supported result set types.
+ *
+ * For instance:
+ * - return 0 (\b0) => [] (no supported result set types);
+ * - return 1 (\b1) => [SQL_RESULT_SET_TYPE_UNSPECIFIED];
+ * - return 2 (\b10) => [SQL_RESULT_SET_TYPE_FORWARD_ONLY];
+ * - return 3 (\b11) => [SQL_RESULT_SET_TYPE_UNSPECIFIED, SQL_RESULT_SET_TYPE_FORWARD_ONLY];
+ * - return 4 (\b100) => [SQL_RESULT_SET_TYPE_SCROLL_INSENSITIVE];
+ * - return 5 (\b101) => [SQL_RESULT_SET_TYPE_UNSPECIFIED, SQL_RESULT_SET_TYPE_SCROLL_INSENSITIVE];
+ * - return 6 (\b110) => [SQL_RESULT_SET_TYPE_FORWARD_ONLY, SQL_RESULT_SET_TYPE_SCROLL_INSENSITIVE];
+ * - return 7 (\b111) => [SQL_RESULT_SET_TYPE_UNSPECIFIED, SQL_RESULT_SET_TYPE_FORWARD_ONLY, SQL_RESULT_SET_TYPE_SCROLL_INSENSITIVE];
+ * - return 8 (\b1000) => [SQL_RESULT_SET_TYPE_SCROLL_SENSITIVE];
+ * - ...
+ * Valid result set types are described under `arrow.flight.protocol.sql.SqlSupportedResultSetType`.
+ */
+ SQL_SUPPORTED_RESULT_SET_TYPES = 567;
+
+ /*
+ * Returns an int32 bitmask value representing the concurrency types supported for
+ * `arrow.flight.protocol.sql.SqlSupportedResultSetType.SQL_RESULT_SET_TYPE_UNSPECIFIED`.
+ *
+ * For instance:
+ * - return 0 (\b0) => [] (no supported concurrency types for this result set type)
+ * - return 1 (\b1) => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED]
+ * - return 2 (\b10) => [SQL_RESULT_SET_CONCURRENCY_READ_ONLY]
+ * - return 3 (\b11) => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED, SQL_RESULT_SET_CONCURRENCY_READ_ONLY]
+ * - return 4 (\b100) => [SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
+ * - return 5 (\b101) => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED, SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
+ * - return 6 (\b110) => [SQL_RESULT_SET_CONCURRENCY_READ_ONLY, SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
+ * - return 7 (\b111) => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED, SQL_RESULT_SET_CONCURRENCY_READ_ONLY, SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
+ * Valid result set concurrency types are described under `arrow.flight.protocol.sql.SqlSupportedResultSetConcurrency`.
+ */
+ SQL_SUPPORTED_CONCURRENCIES_FOR_RESULT_SET_UNSPECIFIED = 568;
+
+ /*
+ * Returns an int32 bitmask value representing the concurrency types supported for
+ * `arrow.flight.protocol.sql.SqlSupportedResultSetType.SQL_RESULT_SET_TYPE_FORWARD_ONLY`.
+ *
+ * For instance:
+ * - return 0 (\b0) => [] (no supported concurrency types for this result set type)
+ * - return 1 (\b1) => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED]
+ * - return 2 (\b10) => [SQL_RESULT_SET_CONCURRENCY_READ_ONLY]
+ * - return 3 (\b11) => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED, SQL_RESULT_SET_CONCURRENCY_READ_ONLY]
+ * - return 4 (\b100) => [SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
+ * - return 5 (\b101) => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED, SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
+ * - return 6 (\b110) => [SQL_RESULT_SET_CONCURRENCY_READ_ONLY, SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
+ * - return 7 (\b111) => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED, SQL_RESULT_SET_CONCURRENCY_READ_ONLY, SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
+ * Valid result set concurrency types are described under `arrow.flight.protocol.sql.SqlSupportedResultSetConcurrency`.
+ */
+ SQL_SUPPORTED_CONCURRENCIES_FOR_RESULT_SET_FORWARD_ONLY = 569;
+
+ /*
+ * Returns an int32 bitmask value representing the concurrency types supported for
+ * `arrow.flight.protocol.sql.SqlSupportedResultSetType.SQL_RESULT_SET_TYPE_SCROLL_SENSITIVE`.
+ *
+ * For instance:
+ * - return 0 (\b0) => [] (no supported concurrency types for this result set type)
+ * - return 1 (\b1) => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED]
+ * - return 2 (\b10) => [SQL_RESULT_SET_CONCURRENCY_READ_ONLY]
+ * - return 3 (\b11) => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED, SQL_RESULT_SET_CONCURRENCY_READ_ONLY]
+ * - return 4 (\b100) => [SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
+ * - return 5 (\b101) => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED, SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
+ * - return 6 (\b110) => [SQL_RESULT_SET_CONCURRENCY_READ_ONLY, SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
+ * - return 7 (\b111) => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED, SQL_RESULT_SET_CONCURRENCY_READ_ONLY, SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
+ * Valid result set concurrency types are described under `arrow.flight.protocol.sql.SqlSupportedResultSetConcurrency`.
+ */
+ SQL_SUPPORTED_CONCURRENCIES_FOR_RESULT_SET_SCROLL_SENSITIVE = 570;
+
+ /*
+ * Returns an int32 bitmask value representing the concurrency types supported for
+ * `arrow.flight.protocol.sql.SqlSupportedResultSetType.SQL_RESULT_SET_TYPE_SCROLL_INSENSITIVE`.
+ *
+ * For instance:
+ * - return 0 (\b0) => [] (no supported concurrency types for this result set type)
+ * - return 1 (\b1) => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED]
+ * - return 2 (\b10) => [SQL_RESULT_SET_CONCURRENCY_READ_ONLY]
+ * - return 3 (\b11) => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED, SQL_RESULT_SET_CONCURRENCY_READ_ONLY]
+ * - return 4 (\b100) => [SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
+ * - return 5 (\b101) => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED, SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
+ * - return 6 (\b110) => [SQL_RESULT_SET_CONCURRENCY_READ_ONLY, SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
+ * - return 7 (\b111) => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED, SQL_RESULT_SET_CONCURRENCY_READ_ONLY, SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
+ * Valid result set concurrency types are described under `arrow.flight.protocol.sql.SqlSupportedResultSetConcurrency`.
+ */
+ SQL_SUPPORTED_CONCURRENCIES_FOR_RESULT_SET_SCROLL_INSENSITIVE = 571;
+
+ /*
+ * Retrieves a boolean value indicating whether this database supports batch updates.
+ *
+ * - false: if this database does not support batch updates;
+ * - true: if this database supports batch updates.
+ */
+ SQL_BATCH_UPDATES_SUPPORTED = 572;
+
+ /*
+ * Retrieves a boolean value indicating whether this database supports savepoints.
+ *
+ * Returns:
+ * - false: if this database does not support savepoints;
+ * - true: if this database supports savepoints.
+ */
+ SQL_SAVEPOINTS_SUPPORTED = 573;
+
+ /*
+ * Retrieves a boolean value indicating whether named parameters are supported in callable statements.
+ *
+ * Returns:
+ * - false: if named parameters in callable statements are unsupported;
+ * - true: if named parameters in callable statements are supported.
+ */
+ SQL_NAMED_PARAMETERS_SUPPORTED = 574;
+
+ /*
+ * Retrieves a boolean value indicating whether updates made to a LOB are made on a copy or directly to the LOB.
+ *
+ * Returns:
+ * - false: if updates made to a LOB are made directly to the LOB;
+ * - true: if updates made to a LOB are made on a copy.
+ */
+ SQL_LOCATORS_UPDATE_COPY = 575;
+
+ /*
+ * Retrieves a boolean value indicating whether invoking user-defined or vendor functions
+ * using the stored procedure escape syntax is supported.
+ *
+ * Returns:
+ * - false: if invoking user-defined or vendor functions using the stored procedure escape syntax is unsupported;
+ * - true: if invoking user-defined or vendor functions using the stored procedure escape syntax is supported.
+ */
+ SQL_STORED_FUNCTIONS_USING_CALL_SYNTAX_SUPPORTED = 576;
+}
+
+// The level of support for Flight SQL transaction RPCs.
+enum SqlSupportedTransaction {
+ // Unknown/not indicated/no support
+ SQL_SUPPORTED_TRANSACTION_NONE = 0;
+ // Transactions, but not savepoints.
+ // A savepoint is a mark within a transaction that can be individually
+ // rolled back to. Not all databases support savepoints.
+ SQL_SUPPORTED_TRANSACTION_TRANSACTION = 1;
+ // Transactions and savepoints
+ SQL_SUPPORTED_TRANSACTION_SAVEPOINT = 2;
+}
+
+enum SqlSupportedCaseSensitivity {
+ SQL_CASE_SENSITIVITY_UNKNOWN = 0;
+ SQL_CASE_SENSITIVITY_CASE_INSENSITIVE = 1;
+ SQL_CASE_SENSITIVITY_UPPERCASE = 2;
+ SQL_CASE_SENSITIVITY_LOWERCASE = 3;
+}
+
+enum SqlNullOrdering {
+ SQL_NULLS_SORTED_HIGH = 0;
+ SQL_NULLS_SORTED_LOW = 1;
+ SQL_NULLS_SORTED_AT_START = 2;
+ SQL_NULLS_SORTED_AT_END = 3;
+}
+
+enum SupportedSqlGrammar {
+ SQL_MINIMUM_GRAMMAR = 0;
+ SQL_CORE_GRAMMAR = 1;
+ SQL_EXTENDED_GRAMMAR = 2;
+}
+
+enum SupportedAnsi92SqlGrammarLevel {
+ ANSI92_ENTRY_SQL = 0;
+ ANSI92_INTERMEDIATE_SQL = 1;
+ ANSI92_FULL_SQL = 2;
+}
+
+enum SqlOuterJoinsSupportLevel {
+ SQL_JOINS_UNSUPPORTED = 0;
+ SQL_LIMITED_OUTER_JOINS = 1;
+ SQL_FULL_OUTER_JOINS = 2;
+}
+
+enum SqlSupportedGroupBy {
+ SQL_GROUP_BY_UNRELATED = 0;
+ SQL_GROUP_BY_BEYOND_SELECT = 1;
+}
+
+enum SqlSupportedElementActions {
+ SQL_ELEMENT_IN_PROCEDURE_CALLS = 0;
+ SQL_ELEMENT_IN_INDEX_DEFINITIONS = 1;
+ SQL_ELEMENT_IN_PRIVILEGE_DEFINITIONS = 2;
+}
+
+enum SqlSupportedPositionedCommands {
+ SQL_POSITIONED_DELETE = 0;
+ SQL_POSITIONED_UPDATE = 1;
+}
+
+enum SqlSupportedSubqueries {
+ SQL_SUBQUERIES_IN_COMPARISONS = 0;
+ SQL_SUBQUERIES_IN_EXISTS = 1;
+ SQL_SUBQUERIES_IN_INS = 2;
+ SQL_SUBQUERIES_IN_QUANTIFIEDS = 3;
+}
+
+enum SqlSupportedUnions {
+ SQL_UNION = 0;
+ SQL_UNION_ALL = 1;
+}
+
+enum SqlTransactionIsolationLevel {
+ SQL_TRANSACTION_NONE = 0;
+ SQL_TRANSACTION_READ_UNCOMMITTED = 1;
+ SQL_TRANSACTION_READ_COMMITTED = 2;
+ SQL_TRANSACTION_REPEATABLE_READ = 3;
+ SQL_TRANSACTION_SERIALIZABLE = 4;
+}
+
+enum SqlSupportedTransactions {
+ SQL_TRANSACTION_UNSPECIFIED = 0;
+ SQL_DATA_DEFINITION_TRANSACTIONS = 1;
+ SQL_DATA_MANIPULATION_TRANSACTIONS = 2;
+}
+
+enum SqlSupportedResultSetType {
+ SQL_RESULT_SET_TYPE_UNSPECIFIED = 0;
+ SQL_RESULT_SET_TYPE_FORWARD_ONLY = 1;
+ SQL_RESULT_SET_TYPE_SCROLL_INSENSITIVE = 2;
+ SQL_RESULT_SET_TYPE_SCROLL_SENSITIVE = 3;
+}
+
+enum SqlSupportedResultSetConcurrency {
+ SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED = 0;
+ SQL_RESULT_SET_CONCURRENCY_READ_ONLY = 1;
+ SQL_RESULT_SET_CONCURRENCY_UPDATABLE = 2;
+}
+
+enum SqlSupportsConvert {
+ SQL_CONVERT_BIGINT = 0;
+ SQL_CONVERT_BINARY = 1;
+ SQL_CONVERT_BIT = 2;
+ SQL_CONVERT_CHAR = 3;
+ SQL_CONVERT_DATE = 4;
+ SQL_CONVERT_DECIMAL = 5;
+ SQL_CONVERT_FLOAT = 6;
+ SQL_CONVERT_INTEGER = 7;
+ SQL_CONVERT_INTERVAL_DAY_TIME = 8;
+ SQL_CONVERT_INTERVAL_YEAR_MONTH = 9;
+ SQL_CONVERT_LONGVARBINARY = 10;
+ SQL_CONVERT_LONGVARCHAR = 11;
+ SQL_CONVERT_NUMERIC = 12;
+ SQL_CONVERT_REAL = 13;
+ SQL_CONVERT_SMALLINT = 14;
+ SQL_CONVERT_TIME = 15;
+ SQL_CONVERT_TIMESTAMP = 16;
+ SQL_CONVERT_TINYINT = 17;
+ SQL_CONVERT_VARBINARY = 18;
+ SQL_CONVERT_VARCHAR = 19;
+}
+
+/**
+ * The JDBC/ODBC-defined type of any object.
+ * All the values here are the same as in the JDBC and ODBC specs.
+ */
+enum XdbcDataType {
+ XDBC_UNKNOWN_TYPE = 0;
+ XDBC_CHAR = 1;
+ XDBC_NUMERIC = 2;
+ XDBC_DECIMAL = 3;
+ XDBC_INTEGER = 4;
+ XDBC_SMALLINT = 5;
+ XDBC_FLOAT = 6;
+ XDBC_REAL = 7;
+ XDBC_DOUBLE = 8;
+ XDBC_DATETIME = 9;
+ XDBC_INTERVAL = 10;
+ XDBC_VARCHAR = 12;
+ XDBC_DATE = 91;
+ XDBC_TIME = 92;
+ XDBC_TIMESTAMP = 93;
+ XDBC_LONGVARCHAR = -1;
+ XDBC_BINARY = -2;
+ XDBC_VARBINARY = -3;
+ XDBC_LONGVARBINARY = -4;
+ XDBC_BIGINT = -5;
+ XDBC_TINYINT = -6;
+ XDBC_BIT = -7;
+ XDBC_WCHAR = -8;
+ XDBC_WVARCHAR = -9;
+}
+
+/**
+ * Detailed subtype information for XDBC_TYPE_DATETIME and XDBC_TYPE_INTERVAL.
+ */
+enum XdbcDatetimeSubcode {
+ option allow_alias = true;
+ XDBC_SUBCODE_UNKNOWN = 0;
+ XDBC_SUBCODE_YEAR = 1;
+ XDBC_SUBCODE_DATE = 1;
+ XDBC_SUBCODE_TIME = 2;
+ XDBC_SUBCODE_MONTH = 2;
+ XDBC_SUBCODE_TIMESTAMP = 3;
+ XDBC_SUBCODE_DAY = 3;
+ XDBC_SUBCODE_TIME_WITH_TIMEZONE = 4;
+ XDBC_SUBCODE_HOUR = 4;
+ XDBC_SUBCODE_TIMESTAMP_WITH_TIMEZONE = 5;
+ XDBC_SUBCODE_MINUTE = 5;
+ XDBC_SUBCODE_SECOND = 6;
+ XDBC_SUBCODE_YEAR_TO_MONTH = 7;
+ XDBC_SUBCODE_DAY_TO_HOUR = 8;
+ XDBC_SUBCODE_DAY_TO_MINUTE = 9;
+ XDBC_SUBCODE_DAY_TO_SECOND = 10;
+ XDBC_SUBCODE_HOUR_TO_MINUTE = 11;
+ XDBC_SUBCODE_HOUR_TO_SECOND = 12;
+ XDBC_SUBCODE_MINUTE_TO_SECOND = 13;
+ XDBC_SUBCODE_INTERVAL_YEAR = 101;
+ XDBC_SUBCODE_INTERVAL_MONTH = 102;
+ XDBC_SUBCODE_INTERVAL_DAY = 103;
+ XDBC_SUBCODE_INTERVAL_HOUR = 104;
+ XDBC_SUBCODE_INTERVAL_MINUTE = 105;
+ XDBC_SUBCODE_INTERVAL_SECOND = 106;
+ XDBC_SUBCODE_INTERVAL_YEAR_TO_MONTH = 107;
+ XDBC_SUBCODE_INTERVAL_DAY_TO_HOUR = 108;
+ XDBC_SUBCODE_INTERVAL_DAY_TO_MINUTE = 109;
+ XDBC_SUBCODE_INTERVAL_DAY_TO_SECOND = 110;
+ XDBC_SUBCODE_INTERVAL_HOUR_TO_MINUTE = 111;
+ XDBC_SUBCODE_INTERVAL_HOUR_TO_SECOND = 112;
+ XDBC_SUBCODE_INTERVAL_MINUTE_TO_SECOND = 113;
+}
+
+enum Nullable {
+ /**
+ * Indicates that the field does not allow the use of null values.
+ */
+ NULLABILITY_NO_NULLS = 0;
+
+ /**
+ * Indicates that the fields allow the use of null values.
+ */
+ NULLABILITY_NULLABLE = 1;
+
+ /**
+ * Indicates that nullability of the fields cannot be determined.
+ */
+ NULLABILITY_UNKNOWN = 2;
+}
+
+enum Searchable {
+ /**
+ * Indicates that column cannot be used in a WHERE clause.
+ */
+ SEARCHABLE_NONE = 0;
+
+ /**
+ * Indicates that the column can be used in a WHERE clause if it is using a
+ * LIKE operator.
+ */
+ SEARCHABLE_CHAR = 1;
+
+ /**
+ * Indicates that the column can be used In a WHERE clause with any
+ * operator other than LIKE.
+ *
+ * - Allowed operators: comparison, quantified comparison, BETWEEN,
+ * DISTINCT, IN, MATCH, and UNIQUE.
+ */
+ SEARCHABLE_BASIC = 2;
+
+ /**
+ * Indicates that the column can be used in a WHERE clause using any operator.
+ */
+ SEARCHABLE_FULL = 3;
+}
+
+/*
+ * Represents a request to retrieve information about data type supported on a Flight SQL enabled backend.
+ * Used in the command member of FlightDescriptor for the following RPC calls:
+ * - GetSchema: return the schema of the query.
+ * - GetFlightInfo: execute the catalog metadata request.
+ *
+ * The returned schema will be:
+ * <
+ * type_name: utf8 not null (The name of the data type, for example: VARCHAR, INTEGER, etc),
+ * data_type: int32 not null (The SQL data type),
+ * column_size: int32 (The maximum size supported by that column.
+ * In case of exact numeric types, this represents the maximum precision.
+ * In case of string types, this represents the character length.
+ * In case of datetime data types, this represents the length in characters of the string representation.
+ * NULL is returned for data types where column size is not applicable.),
+ * literal_prefix: utf8 (Character or characters used to prefix a literal, NULL is returned for
+ * data types where a literal prefix is not applicable.),
+ * literal_suffix: utf8 (Character or characters used to terminate a literal,
+ * NULL is returned for data types where a literal suffix is not applicable.),
+ * create_params: list<utf8 not null>
+ * (A list of keywords corresponding to which parameters can be used when creating
+ * a column for that specific type.
+ * NULL is returned if there are no parameters for the data type definition.),
+ * nullable: int32 not null (Shows if the data type accepts a NULL value. The possible values can be seen in the
+ * Nullable enum.),
+ * case_sensitive: bool not null (Shows if a character data type is case-sensitive in collations and comparisons),
+ * searchable: int32 not null (Shows how the data type is used in a WHERE clause. The possible values can be seen in the
+ * Searchable enum.),
+ * unsigned_attribute: bool (Shows if the data type is unsigned. NULL is returned if the attribute is
+ * not applicable to the data type or the data type is not numeric.),
+ * fixed_prec_scale: bool not null (Shows if the data type has predefined fixed precision and scale.),
+ * auto_increment: bool (Shows if the data type is auto incremental. NULL is returned if the attribute
+ * is not applicable to the data type or the data type is not numeric.),
+ * local_type_name: utf8 (Localized version of the data source-dependent name of the data type. NULL
+ * is returned if a localized name is not supported by the data source),
+ * minimum_scale: int32 (The minimum scale of the data type on the data source.
+ * If a data type has a fixed scale, the MINIMUM_SCALE and MAXIMUM_SCALE
+ * columns both contain this value. NULL is returned if scale is not applicable.),
+ * maximum_scale: int32 (The maximum scale of the data type on the data source.
+ * NULL is returned if scale is not applicable.),
+ * sql_data_type: int32 not null (The value of the SQL DATA TYPE which has the same values
+ * as data_type value. Except for interval and datetime, which
+ * uses generic values. More info about those types can be
+ * obtained through datetime_subcode. The possible values can be seen
+ * in the XdbcDataType enum.),
+ * datetime_subcode: int32 (Only used when the SQL DATA TYPE is interval or datetime. It contains
+ * its sub types. For type different from interval and datetime, this value
+ * is NULL. The possible values can be seen in the XdbcDatetimeSubcode enum.),
+ * num_prec_radix: int32 (If the data type is an approximate numeric type, this column contains
+ * the value 2 to indicate that COLUMN_SIZE specifies a number of bits. For
+ * exact numeric types, this column contains the value 10 to indicate that
+ * column size specifies a number of decimal digits. Otherwise, this column is NULL.),
+ * interval_precision: int32 (If the data type is an interval data type, then this column contains the value
+ * of the interval leading precision. Otherwise, this column is NULL. This fields
+ * is only relevant to be used by ODBC).
+ * >
+ * The returned data should be ordered by data_type and then by type_name.
+ */
+message CommandGetXdbcTypeInfo {
+
/*
- * Retrieves a boolean value indicating whether the Flight SQL Server supports executing
- * bulk ingestion.
+ * Specifies the data type to search for the info.
*/
- FLIGHT_SQL_SERVER_BULK_INGESTION = 10;
+ optional int32 data_type = 1;
+}
+
+/*
+ * Represents a request to retrieve the list of catalogs on a Flight SQL enabled backend.
+ * The definition of a catalog depends on vendor/implementation. It is usually the database itself
+ * Used in the command member of FlightDescriptor for the following RPC calls:
+ * - GetSchema: return the Arrow schema of the query.
+ * - GetFlightInfo: execute the catalog metadata request.
+ *
+ * The returned Arrow schema will be:
+ * <
+ * catalog_name: utf8 not null
+ * >
+ * The returned data should be ordered by catalog_name.
+ */
+message CommandGetCatalogs {
+}
+
+/*
+ * Represents a request to retrieve the list of database schemas on a Flight SQL enabled backend.
+ * The definition of a database schema depends on vendor/implementation. It is usually a collection of tables.
+ * Used in the command member of FlightDescriptor for the following RPC calls:
+ * - GetSchema: return the Arrow schema of the query.
+ * - GetFlightInfo: execute the catalog metadata request.
+ *
+ * The returned Arrow schema will be:
+ * <
+ * catalog_name: utf8,
+ * db_schema_name: utf8 not null
+ * >
+ * The returned data should be ordered by catalog_name, then db_schema_name.
+ */
+message CommandGetDbSchemas {
/*
- * Retrieves a boolean value indicating whether transactions are supported for bulk ingestion. If not, invoking
- * the method commit in the context of a bulk ingestion is a noop, and the isolation level is
- * `arrow.flight.protocol.sql.SqlTransactionIsolationLevel.TRANSACTION_NONE`.
- *
- * Returns:
- * - false: if bulk ingestion transactions are unsupported;
- * - true: if bulk ingestion transactions are supported.
+ * Specifies the Catalog to search for the tables.
+ * An empty string retrieves those without a catalog.
+ * If omitted the catalog name should not be used to narrow the search.
*/
- FLIGHT_SQL_SERVER_INGEST_TRANSACTIONS_SUPPORTED = 11;
+ optional string catalog = 1;
- /*
- * Retrieves an int32 indicating the timeout (in milliseconds) for prepared statement handles.
- *
- * If 0, there is no timeout. Servers should reset the timeout when the handle is used in a command.
- */
- FLIGHT_SQL_SERVER_STATEMENT_TIMEOUT = 100;
-
- /*
- * Retrieves an int32 indicating the timeout (in milliseconds) for transactions, since transactions are not tied to a connection.
- *
- * If 0, there is no timeout. Servers should reset the timeout when the handle is used in a command.
- */
- FLIGHT_SQL_SERVER_TRANSACTION_TIMEOUT = 101;
-
- // SQL Syntax Information [500-1000): provides information about SQL syntax supported by the Flight SQL Server.
-
- /*
- * Retrieves a boolean value indicating whether the Flight SQL Server supports CREATE and DROP of catalogs.
- *
- * Returns:
- * - false: if it doesn't support CREATE and DROP of catalogs.
- * - true: if it supports CREATE and DROP of catalogs.
- */
- SQL_DDL_CATALOG = 500;
-
- /*
- * Retrieves a boolean value indicating whether the Flight SQL Server supports CREATE and DROP of schemas.
- *
- * Returns:
- * - false: if it doesn't support CREATE and DROP of schemas.
- * - true: if it supports CREATE and DROP of schemas.
- */
- SQL_DDL_SCHEMA = 501;
-
- /*
- * Indicates whether the Flight SQL Server supports CREATE and DROP of tables.
- *
- * Returns:
- * - false: if it doesn't support CREATE and DROP of tables.
- * - true: if it supports CREATE and DROP of tables.
- */
- SQL_DDL_TABLE = 502;
-
- /*
- * Retrieves a int32 ordinal representing the case sensitivity of catalog, table, schema and table names.
- *
- * The possible values are listed in `arrow.flight.protocol.sql.SqlSupportedCaseSensitivity`.
- */
- SQL_IDENTIFIER_CASE = 503;
-
- // Retrieves a UTF-8 string with the supported character(s) used to surround a delimited identifier.
- SQL_IDENTIFIER_QUOTE_CHAR = 504;
-
- /*
- * Retrieves a int32 describing the case sensitivity of quoted identifiers.
- *
- * The possible values are listed in `arrow.flight.protocol.sql.SqlSupportedCaseSensitivity`.
- */
- SQL_QUOTED_IDENTIFIER_CASE = 505;
-
- /*
- * Retrieves a boolean value indicating whether all tables are selectable.
- *
- * Returns:
- * - false: if not all tables are selectable or if none are;
- * - true: if all tables are selectable.
- */
- SQL_ALL_TABLES_ARE_SELECTABLE = 506;
-
- /*
- * Retrieves the null ordering.
- *
- * Returns a int32 ordinal for the null ordering being used, as described in
- * `arrow.flight.protocol.sql.SqlNullOrdering`.
- */
- SQL_NULL_ORDERING = 507;
-
- // Retrieves a UTF-8 string list with values of the supported keywords.
- SQL_KEYWORDS = 508;
-
- // Retrieves a UTF-8 string list with values of the supported numeric functions.
- SQL_NUMERIC_FUNCTIONS = 509;
-
- // Retrieves a UTF-8 string list with values of the supported string functions.
- SQL_STRING_FUNCTIONS = 510;
-
- // Retrieves a UTF-8 string list with values of the supported system functions.
- SQL_SYSTEM_FUNCTIONS = 511;
-
- // Retrieves a UTF-8 string list with values of the supported datetime functions.
- SQL_DATETIME_FUNCTIONS = 512;
-
- /*
- * Retrieves the UTF-8 string that can be used to escape wildcard characters.
- * This is the string that can be used to escape '_' or '%' in the catalog search parameters that are a pattern
- * (and therefore use one of the wildcard characters).
- * The '_' character represents any single character; the '%' character represents any sequence of zero or more
- * characters.
- */
- SQL_SEARCH_STRING_ESCAPE = 513;
-
- /*
- * Retrieves a UTF-8 string with all the "extra" characters that can be used in unquoted identifier names
- * (those beyond a-z, A-Z, 0-9 and _).
- */
- SQL_EXTRA_NAME_CHARACTERS = 514;
-
- /*
- * Retrieves a boolean value indicating whether column aliasing is supported.
- * If so, the SQL AS clause can be used to provide names for computed columns or to provide alias names for columns
- * as required.
- *
- * Returns:
- * - false: if column aliasing is unsupported;
- * - true: if column aliasing is supported.
- */
- SQL_SUPPORTS_COLUMN_ALIASING = 515;
-
- /*
- * Retrieves a boolean value indicating whether concatenations between null and non-null values being
- * null are supported.
- *
- * - Returns:
- * - false: if concatenations between null and non-null values being null are unsupported;
- * - true: if concatenations between null and non-null values being null are supported.
- */
- SQL_NULL_PLUS_NULL_IS_NULL = 516;
-
- /*
- * Retrieves a map where the key is the type to convert from and the value is a list with the types to convert to,
- * indicating the supported conversions. Each key and each item on the list value is a value to a predefined type on
- * SqlSupportsConvert enum.
- * The returned map will be: map<int32, list<int32>>
- */
- SQL_SUPPORTS_CONVERT = 517;
-
- /*
- * Retrieves a boolean value indicating whether, when table correlation names are supported,
- * they are restricted to being different from the names of the tables.
- *
- * Returns:
- * - false: if table correlation names are unsupported;
- * - true: if table correlation names are supported.
- */
- SQL_SUPPORTS_TABLE_CORRELATION_NAMES = 518;
-
- /*
- * Retrieves a boolean value indicating whether, when table correlation names are supported,
- * they are restricted to being different from the names of the tables.
- *
- * Returns:
- * - false: if different table correlation names are unsupported;
- * - true: if different table correlation names are supported
- */
- SQL_SUPPORTS_DIFFERENT_TABLE_CORRELATION_NAMES = 519;
-
- /*
- * Retrieves a boolean value indicating whether expressions in ORDER BY lists are supported.
- *
- * Returns:
- * - false: if expressions in ORDER BY are unsupported;
- * - true: if expressions in ORDER BY are supported;
- */
- SQL_SUPPORTS_EXPRESSIONS_IN_ORDER_BY = 520;
-
- /*
- * Retrieves a boolean value indicating whether using a column that is not in the SELECT statement in a GROUP BY
- * clause is supported.
- *
- * Returns:
- * - false: if using a column that is not in the SELECT statement in a GROUP BY clause is unsupported;
- * - true: if using a column that is not in the SELECT statement in a GROUP BY clause is supported.
- */
- SQL_SUPPORTS_ORDER_BY_UNRELATED = 521;
-
- /*
- * Retrieves the supported GROUP BY commands;
- *
- * Returns an int32 bitmask value representing the supported commands.
- * The returned bitmask should be parsed in order to retrieve the supported commands.
- *
- * For instance:
- * - return 0 (\b0) => [] (GROUP BY is unsupported);
- * - return 1 (\b1) => [SQL_GROUP_BY_UNRELATED];
- * - return 2 (\b10) => [SQL_GROUP_BY_BEYOND_SELECT];
- * - return 3 (\b11) => [SQL_GROUP_BY_UNRELATED, SQL_GROUP_BY_BEYOND_SELECT].
- * Valid GROUP BY types are described under `arrow.flight.protocol.sql.SqlSupportedGroupBy`.
- */
- SQL_SUPPORTED_GROUP_BY = 522;
-
- /*
- * Retrieves a boolean value indicating whether specifying a LIKE escape clause is supported.
- *
- * Returns:
- * - false: if specifying a LIKE escape clause is unsupported;
- * - true: if specifying a LIKE escape clause is supported.
- */
- SQL_SUPPORTS_LIKE_ESCAPE_CLAUSE = 523;
-
- /*
- * Retrieves a boolean value indicating whether columns may be defined as non-nullable.
- *
- * Returns:
- * - false: if columns cannot be defined as non-nullable;
- * - true: if columns may be defined as non-nullable.
- */
- SQL_SUPPORTS_NON_NULLABLE_COLUMNS = 524;
-
- /*
- * Retrieves the supported SQL grammar level as per the ODBC specification.
- *
- * Returns an int32 bitmask value representing the supported SQL grammar level.
- * The returned bitmask should be parsed in order to retrieve the supported grammar levels.
- *
- * For instance:
- * - return 0 (\b0) => [] (SQL grammar is unsupported);
- * - return 1 (\b1) => [SQL_MINIMUM_GRAMMAR];
- * - return 2 (\b10) => [SQL_CORE_GRAMMAR];
- * - return 3 (\b11) => [SQL_MINIMUM_GRAMMAR, SQL_CORE_GRAMMAR];
- * - return 4 (\b100) => [SQL_EXTENDED_GRAMMAR];
- * - return 5 (\b101) => [SQL_MINIMUM_GRAMMAR, SQL_EXTENDED_GRAMMAR];
- * - return 6 (\b110) => [SQL_CORE_GRAMMAR, SQL_EXTENDED_GRAMMAR];
- * - return 7 (\b111) => [SQL_MINIMUM_GRAMMAR, SQL_CORE_GRAMMAR, SQL_EXTENDED_GRAMMAR].
- * Valid SQL grammar levels are described under `arrow.flight.protocol.sql.SupportedSqlGrammar`.
- */
- SQL_SUPPORTED_GRAMMAR = 525;
-
- /*
- * Retrieves the supported ANSI92 SQL grammar level.
- *
- * Returns an int32 bitmask value representing the supported ANSI92 SQL grammar level.
- * The returned bitmask should be parsed in order to retrieve the supported commands.
- *
- * For instance:
- * - return 0 (\b0) => [] (ANSI92 SQL grammar is unsupported);
- * - return 1 (\b1) => [ANSI92_ENTRY_SQL];
- * - return 2 (\b10) => [ANSI92_INTERMEDIATE_SQL];
- * - return 3 (\b11) => [ANSI92_ENTRY_SQL, ANSI92_INTERMEDIATE_SQL];
- * - return 4 (\b100) => [ANSI92_FULL_SQL];
- * - return 5 (\b101) => [ANSI92_ENTRY_SQL, ANSI92_FULL_SQL];
- * - return 6 (\b110) => [ANSI92_INTERMEDIATE_SQL, ANSI92_FULL_SQL];
- * - return 7 (\b111) => [ANSI92_ENTRY_SQL, ANSI92_INTERMEDIATE_SQL, ANSI92_FULL_SQL].
- * Valid ANSI92 SQL grammar levels are described under `arrow.flight.protocol.sql.SupportedAnsi92SqlGrammarLevel`.
- */
- SQL_ANSI92_SUPPORTED_LEVEL = 526;
-
- /*
- * Retrieves a boolean value indicating whether the SQL Integrity Enhancement Facility is supported.
- *
- * Returns:
- * - false: if the SQL Integrity Enhancement Facility is supported;
- * - true: if the SQL Integrity Enhancement Facility is supported.
- */
- SQL_SUPPORTS_INTEGRITY_ENHANCEMENT_FACILITY = 527;
-
- /*
- * Retrieves the support level for SQL OUTER JOINs.
- *
- * Returns a int32 ordinal for the SQL ordering being used, as described in
- * `arrow.flight.protocol.sql.SqlOuterJoinsSupportLevel`.
- */
- SQL_OUTER_JOINS_SUPPORT_LEVEL = 528;
-
- // Retrieves a UTF-8 string with the preferred term for "schema".
- SQL_SCHEMA_TERM = 529;
-
- // Retrieves a UTF-8 string with the preferred term for "procedure".
- SQL_PROCEDURE_TERM = 530;
-
- /*
- * Retrieves a UTF-8 string with the preferred term for "catalog".
- * If a empty string is returned its assumed that the server does NOT supports catalogs.
- */
- SQL_CATALOG_TERM = 531;
-
- /*
- * Retrieves a boolean value indicating whether a catalog appears at the start of a fully qualified table name.
- *
- * - false: if a catalog does not appear at the start of a fully qualified table name;
- * - true: if a catalog appears at the start of a fully qualified table name.
- */
- SQL_CATALOG_AT_START = 532;
-
- /*
- * Retrieves the supported actions for a SQL schema.
- *
- * Returns an int32 bitmask value representing the supported actions for a SQL schema.
- * The returned bitmask should be parsed in order to retrieve the supported actions for a SQL schema.
- *
- * For instance:
- * - return 0 (\b0) => [] (no supported actions for SQL schema);
- * - return 1 (\b1) => [SQL_ELEMENT_IN_PROCEDURE_CALLS];
- * - return 2 (\b10) => [SQL_ELEMENT_IN_INDEX_DEFINITIONS];
- * - return 3 (\b11) => [SQL_ELEMENT_IN_PROCEDURE_CALLS, SQL_ELEMENT_IN_INDEX_DEFINITIONS];
- * - return 4 (\b100) => [SQL_ELEMENT_IN_PRIVILEGE_DEFINITIONS];
- * - return 5 (\b101) => [SQL_ELEMENT_IN_PROCEDURE_CALLS, SQL_ELEMENT_IN_PRIVILEGE_DEFINITIONS];
- * - return 6 (\b110) => [SQL_ELEMENT_IN_INDEX_DEFINITIONS, SQL_ELEMENT_IN_PRIVILEGE_DEFINITIONS];
- * - return 7 (\b111) => [SQL_ELEMENT_IN_PROCEDURE_CALLS, SQL_ELEMENT_IN_INDEX_DEFINITIONS, SQL_ELEMENT_IN_PRIVILEGE_DEFINITIONS].
- * Valid actions for a SQL schema described under `arrow.flight.protocol.sql.SqlSupportedElementActions`.
- */
- SQL_SCHEMAS_SUPPORTED_ACTIONS = 533;
-
- /*
- * Retrieves the supported actions for a SQL schema.
- *
- * Returns an int32 bitmask value representing the supported actions for a SQL catalog.
- * The returned bitmask should be parsed in order to retrieve the supported actions for a SQL catalog.
- *
- * For instance:
- * - return 0 (\b0) => [] (no supported actions for SQL catalog);
- * - return 1 (\b1) => [SQL_ELEMENT_IN_PROCEDURE_CALLS];
- * - return 2 (\b10) => [SQL_ELEMENT_IN_INDEX_DEFINITIONS];
- * - return 3 (\b11) => [SQL_ELEMENT_IN_PROCEDURE_CALLS, SQL_ELEMENT_IN_INDEX_DEFINITIONS];
- * - return 4 (\b100) => [SQL_ELEMENT_IN_PRIVILEGE_DEFINITIONS];
- * - return 5 (\b101) => [SQL_ELEMENT_IN_PROCEDURE_CALLS, SQL_ELEMENT_IN_PRIVILEGE_DEFINITIONS];
- * - return 6 (\b110) => [SQL_ELEMENT_IN_INDEX_DEFINITIONS, SQL_ELEMENT_IN_PRIVILEGE_DEFINITIONS];
- * - return 7 (\b111) => [SQL_ELEMENT_IN_PROCEDURE_CALLS, SQL_ELEMENT_IN_INDEX_DEFINITIONS, SQL_ELEMENT_IN_PRIVILEGE_DEFINITIONS].
- * Valid actions for a SQL catalog are described under `arrow.flight.protocol.sql.SqlSupportedElementActions`.
- */
- SQL_CATALOGS_SUPPORTED_ACTIONS = 534;
-
- /*
- * Retrieves the supported SQL positioned commands.
- *
- * Returns an int32 bitmask value representing the supported SQL positioned commands.
- * The returned bitmask should be parsed in order to retrieve the supported SQL positioned commands.
- *
- * For instance:
- * - return 0 (\b0) => [] (no supported SQL positioned commands);
- * - return 1 (\b1) => [SQL_POSITIONED_DELETE];
- * - return 2 (\b10) => [SQL_POSITIONED_UPDATE];
- * - return 3 (\b11) => [SQL_POSITIONED_DELETE, SQL_POSITIONED_UPDATE].
- * Valid SQL positioned commands are described under `arrow.flight.protocol.sql.SqlSupportedPositionedCommands`.
- */
- SQL_SUPPORTED_POSITIONED_COMMANDS = 535;
-
- /*
- * Retrieves a boolean value indicating whether SELECT FOR UPDATE statements are supported.
- *
- * Returns:
- * - false: if SELECT FOR UPDATE statements are unsupported;
- * - true: if SELECT FOR UPDATE statements are supported.
- */
- SQL_SELECT_FOR_UPDATE_SUPPORTED = 536;
-
- /*
- * Retrieves a boolean value indicating whether stored procedure calls that use the stored procedure escape syntax
- * are supported.
- *
- * Returns:
- * - false: if stored procedure calls that use the stored procedure escape syntax are unsupported;
- * - true: if stored procedure calls that use the stored procedure escape syntax are supported.
- */
- SQL_STORED_PROCEDURES_SUPPORTED = 537;
-
- /*
- * Retrieves the supported SQL subqueries.
- *
- * Returns an int32 bitmask value representing the supported SQL subqueries.
- * The returned bitmask should be parsed in order to retrieve the supported SQL subqueries.
- *
- * For instance:
- * - return 0 (\b0) => [] (no supported SQL subqueries);
- * - return 1 (\b1) => [SQL_SUBQUERIES_IN_COMPARISONS];
- * - return 2 (\b10) => [SQL_SUBQUERIES_IN_EXISTS];
- * - return 3 (\b11) => [SQL_SUBQUERIES_IN_COMPARISONS, SQL_SUBQUERIES_IN_EXISTS];
- * - return 4 (\b100) => [SQL_SUBQUERIES_IN_INS];
- * - return 5 (\b101) => [SQL_SUBQUERIES_IN_COMPARISONS, SQL_SUBQUERIES_IN_INS];
- * - return 6 (\b110) => [SQL_SUBQUERIES_IN_INS, SQL_SUBQUERIES_IN_EXISTS];
- * - return 7 (\b111) => [SQL_SUBQUERIES_IN_COMPARISONS, SQL_SUBQUERIES_IN_EXISTS, SQL_SUBQUERIES_IN_INS];
- * - return 8 (\b1000) => [SQL_SUBQUERIES_IN_QUANTIFIEDS];
- * - return 9 (\b1001) => [SQL_SUBQUERIES_IN_COMPARISONS, SQL_SUBQUERIES_IN_QUANTIFIEDS];
- * - return 10 (\b1010) => [SQL_SUBQUERIES_IN_EXISTS, SQL_SUBQUERIES_IN_QUANTIFIEDS];
- * - return 11 (\b1011) => [SQL_SUBQUERIES_IN_COMPARISONS, SQL_SUBQUERIES_IN_EXISTS, SQL_SUBQUERIES_IN_QUANTIFIEDS];
- * - return 12 (\b1100) => [SQL_SUBQUERIES_IN_INS, SQL_SUBQUERIES_IN_QUANTIFIEDS];
- * - return 13 (\b1101) => [SQL_SUBQUERIES_IN_COMPARISONS, SQL_SUBQUERIES_IN_INS, SQL_SUBQUERIES_IN_QUANTIFIEDS];
- * - return 14 (\b1110) => [SQL_SUBQUERIES_IN_EXISTS, SQL_SUBQUERIES_IN_INS, SQL_SUBQUERIES_IN_QUANTIFIEDS];
- * - return 15 (\b1111) => [SQL_SUBQUERIES_IN_COMPARISONS, SQL_SUBQUERIES_IN_EXISTS, SQL_SUBQUERIES_IN_INS, SQL_SUBQUERIES_IN_QUANTIFIEDS];
- * - ...
- * Valid SQL subqueries are described under `arrow.flight.protocol.sql.SqlSupportedSubqueries`.
- */
- SQL_SUPPORTED_SUBQUERIES = 538;
-
- /*
- * Retrieves a boolean value indicating whether correlated subqueries are supported.
- *
- * Returns:
- * - false: if correlated subqueries are unsupported;
- * - true: if correlated subqueries are supported.
- */
- SQL_CORRELATED_SUBQUERIES_SUPPORTED = 539;
-
- /*
- * Retrieves the supported SQL UNIONs.
- *
- * Returns an int32 bitmask value representing the supported SQL UNIONs.
- * The returned bitmask should be parsed in order to retrieve the supported SQL UNIONs.
- *
- * For instance:
- * - return 0 (\b0) => [] (no supported SQL positioned commands);
- * - return 1 (\b1) => [SQL_UNION];
- * - return 2 (\b10) => [SQL_UNION_ALL];
- * - return 3 (\b11) => [SQL_UNION, SQL_UNION_ALL].
- * Valid SQL positioned commands are described under `arrow.flight.protocol.sql.SqlSupportedUnions`.
- */
- SQL_SUPPORTED_UNIONS = 540;
-
- // Retrieves a int64 value representing the maximum number of hex characters allowed in an inline binary literal.
- SQL_MAX_BINARY_LITERAL_LENGTH = 541;
-
- // Retrieves a int64 value representing the maximum number of characters allowed for a character literal.
- SQL_MAX_CHAR_LITERAL_LENGTH = 542;
-
- // Retrieves a int64 value representing the maximum number of characters allowed for a column name.
- SQL_MAX_COLUMN_NAME_LENGTH = 543;
-
- // Retrieves a int64 value representing the maximum number of columns allowed in a GROUP BY clause.
- SQL_MAX_COLUMNS_IN_GROUP_BY = 544;
-
- // Retrieves a int64 value representing the maximum number of columns allowed in an index.
- SQL_MAX_COLUMNS_IN_INDEX = 545;
-
- // Retrieves a int64 value representing the maximum number of columns allowed in an ORDER BY clause.
- SQL_MAX_COLUMNS_IN_ORDER_BY = 546;
-
- // Retrieves a int64 value representing the maximum number of columns allowed in a SELECT list.
- SQL_MAX_COLUMNS_IN_SELECT = 547;
-
- // Retrieves a int64 value representing the maximum number of columns allowed in a table.
- SQL_MAX_COLUMNS_IN_TABLE = 548;
-
- // Retrieves a int64 value representing the maximum number of concurrent connections possible.
- SQL_MAX_CONNECTIONS = 549;
-
- // Retrieves a int64 value the maximum number of characters allowed in a cursor name.
- SQL_MAX_CURSOR_NAME_LENGTH = 550;
-
- /*
- * Retrieves a int64 value representing the maximum number of bytes allowed for an index,
- * including all of the parts of the index.
- */
- SQL_MAX_INDEX_LENGTH = 551;
-
- // Retrieves a int64 value representing the maximum number of characters allowed in a schema name.
- SQL_DB_SCHEMA_NAME_LENGTH = 552;
-
- // Retrieves a int64 value representing the maximum number of characters allowed in a procedure name.
- SQL_MAX_PROCEDURE_NAME_LENGTH = 553;
-
- // Retrieves a int64 value representing the maximum number of characters allowed in a catalog name.
- SQL_MAX_CATALOG_NAME_LENGTH = 554;
-
- // Retrieves a int64 value representing the maximum number of bytes allowed in a single row.
- SQL_MAX_ROW_SIZE = 555;
-
- /*
- * Retrieves a boolean indicating whether the return value for the JDBC method getMaxRowSize includes the SQL
- * data types LONGVARCHAR and LONGVARBINARY.
- *
- * Returns:
- * - false: if return value for the JDBC method getMaxRowSize does
- * not include the SQL data types LONGVARCHAR and LONGVARBINARY;
- * - true: if return value for the JDBC method getMaxRowSize includes
- * the SQL data types LONGVARCHAR and LONGVARBINARY.
- */
- SQL_MAX_ROW_SIZE_INCLUDES_BLOBS = 556;
-
- /*
- * Retrieves a int64 value representing the maximum number of characters allowed for an SQL statement;
- * a result of 0 (zero) means that there is no limit or the limit is not known.
- */
- SQL_MAX_STATEMENT_LENGTH = 557;
-
- // Retrieves a int64 value representing the maximum number of active statements that can be open at the same time.
- SQL_MAX_STATEMENTS = 558;
-
- // Retrieves a int64 value representing the maximum number of characters allowed in a table name.
- SQL_MAX_TABLE_NAME_LENGTH = 559;
-
- // Retrieves a int64 value representing the maximum number of tables allowed in a SELECT statement.
- SQL_MAX_TABLES_IN_SELECT = 560;
-
- // Retrieves a int64 value representing the maximum number of characters allowed in a user name.
- SQL_MAX_USERNAME_LENGTH = 561;
-
- /*
- * Retrieves this database's default transaction isolation level as described in
- * `arrow.flight.protocol.sql.SqlTransactionIsolationLevel`.
- *
- * Returns a int32 ordinal for the SQL transaction isolation level.
- */
- SQL_DEFAULT_TRANSACTION_ISOLATION = 562;
-
- /*
- * Retrieves a boolean value indicating whether transactions are supported. If not, invoking the method commit is a
- * noop, and the isolation level is `arrow.flight.protocol.sql.SqlTransactionIsolationLevel.TRANSACTION_NONE`.
- *
- * Returns:
- * - false: if transactions are unsupported;
- * - true: if transactions are supported.
- */
- SQL_TRANSACTIONS_SUPPORTED = 563;
-
- /*
- * Retrieves the supported transactions isolation levels.
- *
- * Returns an int32 bitmask value representing the supported transactions isolation levels.
- * The returned bitmask should be parsed in order to retrieve the supported transactions isolation levels.
- *
- * For instance:
- * - return 0 (\b0) => [] (no supported SQL transactions isolation levels);
- * - return 1 (\b1) => [SQL_TRANSACTION_NONE];
- * - return 2 (\b10) => [SQL_TRANSACTION_READ_UNCOMMITTED];
- * - return 3 (\b11) => [SQL_TRANSACTION_NONE, SQL_TRANSACTION_READ_UNCOMMITTED];
- * - return 4 (\b100) => [SQL_TRANSACTION_REPEATABLE_READ];
- * - return 5 (\b101) => [SQL_TRANSACTION_NONE, SQL_TRANSACTION_REPEATABLE_READ];
- * - return 6 (\b110) => [SQL_TRANSACTION_READ_UNCOMMITTED, SQL_TRANSACTION_REPEATABLE_READ];
- * - return 7 (\b111) => [SQL_TRANSACTION_NONE, SQL_TRANSACTION_READ_UNCOMMITTED, SQL_TRANSACTION_REPEATABLE_READ];
- * - return 8 (\b1000) => [SQL_TRANSACTION_REPEATABLE_READ];
- * - return 9 (\b1001) => [SQL_TRANSACTION_NONE, SQL_TRANSACTION_REPEATABLE_READ];
- * - return 10 (\b1010) => [SQL_TRANSACTION_READ_UNCOMMITTED, SQL_TRANSACTION_REPEATABLE_READ];
- * - return 11 (\b1011) => [SQL_TRANSACTION_NONE, SQL_TRANSACTION_READ_UNCOMMITTED, SQL_TRANSACTION_REPEATABLE_READ];
- * - return 12 (\b1100) => [SQL_TRANSACTION_REPEATABLE_READ, SQL_TRANSACTION_REPEATABLE_READ];
- * - return 13 (\b1101) => [SQL_TRANSACTION_NONE, SQL_TRANSACTION_REPEATABLE_READ, SQL_TRANSACTION_REPEATABLE_READ];
- * - return 14 (\b1110) => [SQL_TRANSACTION_READ_UNCOMMITTED, SQL_TRANSACTION_REPEATABLE_READ, SQL_TRANSACTION_REPEATABLE_READ];
- * - return 15 (\b1111) => [SQL_TRANSACTION_NONE, SQL_TRANSACTION_READ_UNCOMMITTED, SQL_TRANSACTION_REPEATABLE_READ, SQL_TRANSACTION_REPEATABLE_READ];
- * - return 16 (\b10000) => [SQL_TRANSACTION_SERIALIZABLE];
- * - ...
- * Valid SQL positioned commands are described under `arrow.flight.protocol.sql.SqlTransactionIsolationLevel`.
- */
- SQL_SUPPORTED_TRANSACTIONS_ISOLATION_LEVELS = 564;
-
- /*
- * Retrieves a boolean value indicating whether a data definition statement within a transaction forces
- * the transaction to commit.
- *
- * Returns:
- * - false: if a data definition statement within a transaction does not force the transaction to commit;
- * - true: if a data definition statement within a transaction forces the transaction to commit.
- */
- SQL_DATA_DEFINITION_CAUSES_TRANSACTION_COMMIT = 565;
-
- /*
- * Retrieves a boolean value indicating whether a data definition statement within a transaction is ignored.
- *
- * Returns:
- * - false: if a data definition statement within a transaction is taken into account;
- * - true: a data definition statement within a transaction is ignored.
- */
- SQL_DATA_DEFINITIONS_IN_TRANSACTIONS_IGNORED = 566;
-
- /*
- * Retrieves an int32 bitmask value representing the supported result set types.
- * The returned bitmask should be parsed in order to retrieve the supported result set types.
- *
- * For instance:
- * - return 0 (\b0) => [] (no supported result set types);
- * - return 1 (\b1) => [SQL_RESULT_SET_TYPE_UNSPECIFIED];
- * - return 2 (\b10) => [SQL_RESULT_SET_TYPE_FORWARD_ONLY];
- * - return 3 (\b11) => [SQL_RESULT_SET_TYPE_UNSPECIFIED, SQL_RESULT_SET_TYPE_FORWARD_ONLY];
- * - return 4 (\b100) => [SQL_RESULT_SET_TYPE_SCROLL_INSENSITIVE];
- * - return 5 (\b101) => [SQL_RESULT_SET_TYPE_UNSPECIFIED, SQL_RESULT_SET_TYPE_SCROLL_INSENSITIVE];
- * - return 6 (\b110) => [SQL_RESULT_SET_TYPE_FORWARD_ONLY, SQL_RESULT_SET_TYPE_SCROLL_INSENSITIVE];
- * - return 7 (\b111) => [SQL_RESULT_SET_TYPE_UNSPECIFIED, SQL_RESULT_SET_TYPE_FORWARD_ONLY, SQL_RESULT_SET_TYPE_SCROLL_INSENSITIVE];
- * - return 8 (\b1000) => [SQL_RESULT_SET_TYPE_SCROLL_SENSITIVE];
- * - ...
- * Valid result set types are described under `arrow.flight.protocol.sql.SqlSupportedResultSetType`.
- */
- SQL_SUPPORTED_RESULT_SET_TYPES = 567;
-
- /*
- * Returns an int32 bitmask value concurrency types supported for
- * `arrow.flight.protocol.sql.SqlSupportedResultSetType.SQL_RESULT_SET_TYPE_UNSPECIFIED`.
- *
- * For instance:
- * - return 0 (\b0) => [] (no supported concurrency types for this result set type)
- * - return 1 (\b1) => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED]
- * - return 2 (\b10) => [SQL_RESULT_SET_CONCURRENCY_READ_ONLY]
- * - return 3 (\b11) => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED, SQL_RESULT_SET_CONCURRENCY_READ_ONLY]
- * - return 4 (\b100) => [SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
- * - return 5 (\b101) => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED, SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
- * - return 6 (\b110) => [SQL_RESULT_SET_CONCURRENCY_READ_ONLY, SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
- * - return 7 (\b111) => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED, SQL_RESULT_SET_CONCURRENCY_READ_ONLY, SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
- * Valid result set types are described under `arrow.flight.protocol.sql.SqlSupportedResultSetConcurrency`.
- */
- SQL_SUPPORTED_CONCURRENCIES_FOR_RESULT_SET_UNSPECIFIED = 568;
-
- /*
- * Returns an int32 bitmask value concurrency types supported for
- * `arrow.flight.protocol.sql.SqlSupportedResultSetType.SQL_RESULT_SET_TYPE_FORWARD_ONLY`.
- *
- * For instance:
- * - return 0 (\b0) => [] (no supported concurrency types for this result set type)
- * - return 1 (\b1) => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED]
- * - return 2 (\b10) => [SQL_RESULT_SET_CONCURRENCY_READ_ONLY]
- * - return 3 (\b11) => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED, SQL_RESULT_SET_CONCURRENCY_READ_ONLY]
- * - return 4 (\b100) => [SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
- * - return 5 (\b101) => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED, SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
- * - return 6 (\b110) => [SQL_RESULT_SET_CONCURRENCY_READ_ONLY, SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
- * - return 7 (\b111) => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED, SQL_RESULT_SET_CONCURRENCY_READ_ONLY, SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
- * Valid result set types are described under `arrow.flight.protocol.sql.SqlSupportedResultSetConcurrency`.
- */
- SQL_SUPPORTED_CONCURRENCIES_FOR_RESULT_SET_FORWARD_ONLY = 569;
-
- /*
- * Returns an int32 bitmask value concurrency types supported for
- * `arrow.flight.protocol.sql.SqlSupportedResultSetType.SQL_RESULT_SET_TYPE_SCROLL_SENSITIVE`.
- *
- * For instance:
- * - return 0 (\b0) => [] (no supported concurrency types for this result set type)
- * - return 1 (\b1) => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED]
- * - return 2 (\b10) => [SQL_RESULT_SET_CONCURRENCY_READ_ONLY]
- * - return 3 (\b11) => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED, SQL_RESULT_SET_CONCURRENCY_READ_ONLY]
- * - return 4 (\b100) => [SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
- * - return 5 (\b101) => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED, SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
- * - return 6 (\b110) => [SQL_RESULT_SET_CONCURRENCY_READ_ONLY, SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
- * - return 7 (\b111) => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED, SQL_RESULT_SET_CONCURRENCY_READ_ONLY, SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
- * Valid result set types are described under `arrow.flight.protocol.sql.SqlSupportedResultSetConcurrency`.
- */
- SQL_SUPPORTED_CONCURRENCIES_FOR_RESULT_SET_SCROLL_SENSITIVE = 570;
-
- /*
- * Returns an int32 bitmask value concurrency types supported for
- * `arrow.flight.protocol.sql.SqlSupportedResultSetType.SQL_RESULT_SET_TYPE_SCROLL_INSENSITIVE`.
- *
- * For instance:
- * - return 0 (\b0) => [] (no supported concurrency types for this result set type)
- * - return 1 (\b1) => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED]
- * - return 2 (\b10) => [SQL_RESULT_SET_CONCURRENCY_READ_ONLY]
- * - return 3 (\b11) => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED, SQL_RESULT_SET_CONCURRENCY_READ_ONLY]
- * - return 4 (\b100) => [SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
- * - return 5 (\b101) => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED, SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
- * - return 6 (\b110) => [SQL_RESULT_SET_CONCURRENCY_READ_ONLY, SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
- * - return 7 (\b111) => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED, SQL_RESULT_SET_CONCURRENCY_READ_ONLY, SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
- * Valid result set types are described under `arrow.flight.protocol.sql.SqlSupportedResultSetConcurrency`.
- */
- SQL_SUPPORTED_CONCURRENCIES_FOR_RESULT_SET_SCROLL_INSENSITIVE = 571;
-
- /*
- * Retrieves a boolean value indicating whether this database supports batch updates.
- *
- * - false: if this database does not support batch updates;
- * - true: if this database supports batch updates.
- */
- SQL_BATCH_UPDATES_SUPPORTED = 572;
-
- /*
- * Retrieves a boolean value indicating whether this database supports savepoints.
- *
- * Returns:
- * - false: if this database does not support savepoints;
- * - true: if this database supports savepoints.
- */
- SQL_SAVEPOINTS_SUPPORTED = 573;
-
- /*
- * Retrieves a boolean value indicating whether named parameters are supported in callable statements.
- *
- * Returns:
- * - false: if named parameters in callable statements are unsupported;
- * - true: if named parameters in callable statements are supported.
- */
- SQL_NAMED_PARAMETERS_SUPPORTED = 574;
-
- /*
- * Retrieves a boolean value indicating whether updates made to a LOB are made on a copy or directly to the LOB.
- *
- * Returns:
- * - false: if updates made to a LOB are made directly to the LOB;
- * - true: if updates made to a LOB are made on a copy.
- */
- SQL_LOCATORS_UPDATE_COPY = 575;
-
- /*
- * Retrieves a boolean value indicating whether invoking user-defined or vendor functions
- * using the stored procedure escape syntax is supported.
- *
- * Returns:
- * - false: if invoking user-defined or vendor functions using the stored procedure escape syntax is unsupported;
- * - true: if invoking user-defined or vendor functions using the stored procedure escape syntax is supported.
- */
- SQL_STORED_FUNCTIONS_USING_CALL_SYNTAX_SUPPORTED = 576;
- }
-
- // The level of support for Flight SQL transaction RPCs.
- enum SqlSupportedTransaction {
- // Unknown/not indicated/no support
- SQL_SUPPORTED_TRANSACTION_NONE = 0;
- // Transactions, but not savepoints.
- // A savepoint is a mark within a transaction that can be individually
- // rolled back to. Not all databases support savepoints.
- SQL_SUPPORTED_TRANSACTION_TRANSACTION = 1;
- // Transactions and savepoints
- SQL_SUPPORTED_TRANSACTION_SAVEPOINT = 2;
- }
-
- enum SqlSupportedCaseSensitivity {
- SQL_CASE_SENSITIVITY_UNKNOWN = 0;
- SQL_CASE_SENSITIVITY_CASE_INSENSITIVE = 1;
- SQL_CASE_SENSITIVITY_UPPERCASE = 2;
- SQL_CASE_SENSITIVITY_LOWERCASE = 3;
- }
-
- enum SqlNullOrdering {
- SQL_NULLS_SORTED_HIGH = 0;
- SQL_NULLS_SORTED_LOW = 1;
- SQL_NULLS_SORTED_AT_START = 2;
- SQL_NULLS_SORTED_AT_END = 3;
- }
-
- enum SupportedSqlGrammar {
- SQL_MINIMUM_GRAMMAR = 0;
- SQL_CORE_GRAMMAR = 1;
- SQL_EXTENDED_GRAMMAR = 2;
- }
-
- enum SupportedAnsi92SqlGrammarLevel {
- ANSI92_ENTRY_SQL = 0;
- ANSI92_INTERMEDIATE_SQL = 1;
- ANSI92_FULL_SQL = 2;
- }
-
- enum SqlOuterJoinsSupportLevel {
- SQL_JOINS_UNSUPPORTED = 0;
- SQL_LIMITED_OUTER_JOINS = 1;
- SQL_FULL_OUTER_JOINS = 2;
- }
-
- enum SqlSupportedGroupBy {
- SQL_GROUP_BY_UNRELATED = 0;
- SQL_GROUP_BY_BEYOND_SELECT = 1;
- }
-
- enum SqlSupportedElementActions {
- SQL_ELEMENT_IN_PROCEDURE_CALLS = 0;
- SQL_ELEMENT_IN_INDEX_DEFINITIONS = 1;
- SQL_ELEMENT_IN_PRIVILEGE_DEFINITIONS = 2;
- }
-
- enum SqlSupportedPositionedCommands {
- SQL_POSITIONED_DELETE = 0;
- SQL_POSITIONED_UPDATE = 1;
- }
-
- enum SqlSupportedSubqueries {
- SQL_SUBQUERIES_IN_COMPARISONS = 0;
- SQL_SUBQUERIES_IN_EXISTS = 1;
- SQL_SUBQUERIES_IN_INS = 2;
- SQL_SUBQUERIES_IN_QUANTIFIEDS = 3;
- }
-
- enum SqlSupportedUnions {
- SQL_UNION = 0;
- SQL_UNION_ALL = 1;
- }
-
- enum SqlTransactionIsolationLevel {
- SQL_TRANSACTION_NONE = 0;
- SQL_TRANSACTION_READ_UNCOMMITTED = 1;
- SQL_TRANSACTION_READ_COMMITTED = 2;
- SQL_TRANSACTION_REPEATABLE_READ = 3;
- SQL_TRANSACTION_SERIALIZABLE = 4;
- }
-
- enum SqlSupportedTransactions {
- SQL_TRANSACTION_UNSPECIFIED = 0;
- SQL_DATA_DEFINITION_TRANSACTIONS = 1;
- SQL_DATA_MANIPULATION_TRANSACTIONS = 2;
- }
-
- enum SqlSupportedResultSetType {
- SQL_RESULT_SET_TYPE_UNSPECIFIED = 0;
- SQL_RESULT_SET_TYPE_FORWARD_ONLY = 1;
- SQL_RESULT_SET_TYPE_SCROLL_INSENSITIVE = 2;
- SQL_RESULT_SET_TYPE_SCROLL_SENSITIVE = 3;
- }
-
- enum SqlSupportedResultSetConcurrency {
- SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED = 0;
- SQL_RESULT_SET_CONCURRENCY_READ_ONLY = 1;
- SQL_RESULT_SET_CONCURRENCY_UPDATABLE = 2;
- }
-
- enum SqlSupportsConvert {
- SQL_CONVERT_BIGINT = 0;
- SQL_CONVERT_BINARY = 1;
- SQL_CONVERT_BIT = 2;
- SQL_CONVERT_CHAR = 3;
- SQL_CONVERT_DATE = 4;
- SQL_CONVERT_DECIMAL = 5;
- SQL_CONVERT_FLOAT = 6;
- SQL_CONVERT_INTEGER = 7;
- SQL_CONVERT_INTERVAL_DAY_TIME = 8;
- SQL_CONVERT_INTERVAL_YEAR_MONTH = 9;
- SQL_CONVERT_LONGVARBINARY = 10;
- SQL_CONVERT_LONGVARCHAR = 11;
- SQL_CONVERT_NUMERIC = 12;
- SQL_CONVERT_REAL = 13;
- SQL_CONVERT_SMALLINT = 14;
- SQL_CONVERT_TIME = 15;
- SQL_CONVERT_TIMESTAMP = 16;
- SQL_CONVERT_TINYINT = 17;
- SQL_CONVERT_VARBINARY = 18;
- SQL_CONVERT_VARCHAR = 19;
- }
-
- /**
- * The JDBC/ODBC-defined type of any object.
- * All the values here are the same as in the JDBC and ODBC specs.
- */
- enum XdbcDataType {
- XDBC_UNKNOWN_TYPE = 0;
- XDBC_CHAR = 1;
- XDBC_NUMERIC = 2;
- XDBC_DECIMAL = 3;
- XDBC_INTEGER = 4;
- XDBC_SMALLINT = 5;
- XDBC_FLOAT = 6;
- XDBC_REAL = 7;
- XDBC_DOUBLE = 8;
- XDBC_DATETIME = 9;
- XDBC_INTERVAL = 10;
- XDBC_VARCHAR = 12;
- XDBC_DATE = 91;
- XDBC_TIME = 92;
- XDBC_TIMESTAMP = 93;
- XDBC_LONGVARCHAR = -1;
- XDBC_BINARY = -2;
- XDBC_VARBINARY = -3;
- XDBC_LONGVARBINARY = -4;
- XDBC_BIGINT = -5;
- XDBC_TINYINT = -6;
- XDBC_BIT = -7;
- XDBC_WCHAR = -8;
- XDBC_WVARCHAR = -9;
- }
-
- /**
- * Detailed subtype information for XDBC_TYPE_DATETIME and XDBC_TYPE_INTERVAL.
- */
- enum XdbcDatetimeSubcode {
- option allow_alias = true;
- XDBC_SUBCODE_UNKNOWN = 0;
- XDBC_SUBCODE_YEAR = 1;
- XDBC_SUBCODE_DATE = 1;
- XDBC_SUBCODE_TIME = 2;
- XDBC_SUBCODE_MONTH = 2;
- XDBC_SUBCODE_TIMESTAMP = 3;
- XDBC_SUBCODE_DAY = 3;
- XDBC_SUBCODE_TIME_WITH_TIMEZONE = 4;
- XDBC_SUBCODE_HOUR = 4;
- XDBC_SUBCODE_TIMESTAMP_WITH_TIMEZONE = 5;
- XDBC_SUBCODE_MINUTE = 5;
- XDBC_SUBCODE_SECOND = 6;
- XDBC_SUBCODE_YEAR_TO_MONTH = 7;
- XDBC_SUBCODE_DAY_TO_HOUR = 8;
- XDBC_SUBCODE_DAY_TO_MINUTE = 9;
- XDBC_SUBCODE_DAY_TO_SECOND = 10;
- XDBC_SUBCODE_HOUR_TO_MINUTE = 11;
- XDBC_SUBCODE_HOUR_TO_SECOND = 12;
- XDBC_SUBCODE_MINUTE_TO_SECOND = 13;
- XDBC_SUBCODE_INTERVAL_YEAR = 101;
- XDBC_SUBCODE_INTERVAL_MONTH = 102;
- XDBC_SUBCODE_INTERVAL_DAY = 103;
- XDBC_SUBCODE_INTERVAL_HOUR = 104;
- XDBC_SUBCODE_INTERVAL_MINUTE = 105;
- XDBC_SUBCODE_INTERVAL_SECOND = 106;
- XDBC_SUBCODE_INTERVAL_YEAR_TO_MONTH = 107;
- XDBC_SUBCODE_INTERVAL_DAY_TO_HOUR = 108;
- XDBC_SUBCODE_INTERVAL_DAY_TO_MINUTE = 109;
- XDBC_SUBCODE_INTERVAL_DAY_TO_SECOND = 110;
- XDBC_SUBCODE_INTERVAL_HOUR_TO_MINUTE = 111;
- XDBC_SUBCODE_INTERVAL_HOUR_TO_SECOND = 112;
- XDBC_SUBCODE_INTERVAL_MINUTE_TO_SECOND = 113;
- }
-
- enum Nullable {
- /**
- * Indicates that the fields does not allow the use of null values.
- */
- NULLABILITY_NO_NULLS = 0;
-
- /**
- * Indicates that the fields allow the use of null values.
- */
- NULLABILITY_NULLABLE = 1;
-
- /**
- * Indicates that nullability of the fields cannot be determined.
- */
- NULLABILITY_UNKNOWN = 2;
- }
-
- enum Searchable {
- /**
- * Indicates that column cannot be used in a WHERE clause.
- */
- SEARCHABLE_NONE = 0;
-
- /**
- * Indicates that the column can be used in a WHERE clause if it is using a
- * LIKE operator.
- */
- SEARCHABLE_CHAR = 1;
-
- /**
- * Indicates that the column can be used In a WHERE clause with any
- * operator other than LIKE.
- *
- * - Allowed operators: comparison, quantified comparison, BETWEEN,
- * DISTINCT, IN, MATCH, and UNIQUE.
- */
- SEARCHABLE_BASIC = 2;
-
- /**
- * Indicates that the column can be used in a WHERE clause using any operator.
- */
- SEARCHABLE_FULL = 3;
- }
-
- /*
- * Represents a request to retrieve information about data type supported on a Flight SQL enabled backend.
- * Used in the command member of FlightDescriptor for the following RPC calls:
- * - GetSchema: return the schema of the query.
- * - GetFlightInfo: execute the catalog metadata request.
- *
- * The returned schema will be:
- * <
- * type_name: utf8 not null (The name of the data type, for example: VARCHAR, INTEGER, etc),
- * data_type: int32 not null (The SQL data type),
- * column_size: int32 (The maximum size supported by that column.
- * In case of exact numeric types, this represents the maximum precision.
- * In case of string types, this represents the character length.
- * In case of datetime data types, this represents the length in characters of the string representation.
- * NULL is returned for data types where column size is not applicable.),
- * literal_prefix: utf8 (Character or characters used to prefix a literal, NULL is returned for
- * data types where a literal prefix is not applicable.),
- * literal_suffix: utf8 (Character or characters used to terminate a literal,
- * NULL is returned for data types where a literal suffix is not applicable.),
- * create_params: list<utf8 not null>
- * (A list of keywords corresponding to which parameters can be used when creating
- * a column for that specific type.
- * NULL is returned if there are no parameters for the data type definition.),
- * nullable: int32 not null (Shows if the data type accepts a NULL value. The possible values can be seen in the
- * Nullable enum.),
- * case_sensitive: bool not null (Shows if a character data type is case-sensitive in collations and comparisons),
- * searchable: int32 not null (Shows how the data type is used in a WHERE clause. The possible values can be seen in the
- * Searchable enum.),
- * unsigned_attribute: bool (Shows if the data type is unsigned. NULL is returned if the attribute is
- * not applicable to the data type or the data type is not numeric.),
- * fixed_prec_scale: bool not null (Shows if the data type has predefined fixed precision and scale.),
- * auto_increment: bool (Shows if the data type is auto incremental. NULL is returned if the attribute
- * is not applicable to the data type or the data type is not numeric.),
- * local_type_name: utf8 (Localized version of the data source-dependent name of the data type. NULL
- * is returned if a localized name is not supported by the data source),
- * minimum_scale: int32 (The minimum scale of the data type on the data source.
- * If a data type has a fixed scale, the MINIMUM_SCALE and MAXIMUM_SCALE
- * columns both contain this value. NULL is returned if scale is not applicable.),
- * maximum_scale: int32 (The maximum scale of the data type on the data source.
- * NULL is returned if scale is not applicable.),
- * sql_data_type: int32 not null (The value of the SQL DATA TYPE which has the same values
- * as data_type value. Except for interval and datetime, which
- * uses generic values. More info about those types can be
- * obtained through datetime_subcode. The possible values can be seen
- * in the XdbcDataType enum.),
- * datetime_subcode: int32 (Only used when the SQL DATA TYPE is interval or datetime. It contains
- * its sub types. For type different from interval and datetime, this value
- * is NULL. The possible values can be seen in the XdbcDatetimeSubcode enum.),
- * num_prec_radix: int32 (If the data type is an approximate numeric type, this column contains
- * the value 2 to indicate that COLUMN_SIZE specifies a number of bits. For
- * exact numeric types, this column contains the value 10 to indicate that
- * column size specifies a number of decimal digits. Otherwise, this column is NULL.),
- * interval_precision: int32 (If the data type is an interval data type, then this column contains the value
- * of the interval leading precision. Otherwise, this column is NULL. This fields
- * is only relevant to be used by ODBC).
- * >
- * The returned data should be ordered by data_type and then by type_name.
- */
- message CommandGetXdbcTypeInfo {
-
- /*
- * Specifies the data type to search for the info.
- */
- optional int32 data_type = 1;
- }
-
- /*
- * Represents a request to retrieve the list of catalogs on a Flight SQL enabled backend.
- * The definition of a catalog depends on vendor/implementation. It is usually the database itself
- * Used in the command member of FlightDescriptor for the following RPC calls:
- * - GetSchema: return the Arrow schema of the query.
- * - GetFlightInfo: execute the catalog metadata request.
- *
- * The returned Arrow schema will be:
- * <
- * catalog_name: utf8 not null
- * >
- * The returned data should be ordered by catalog_name.
- */
- message CommandGetCatalogs {
- }
-
- /*
- * Represents a request to retrieve the list of database schemas on a Flight SQL enabled backend.
- * The definition of a database schema depends on vendor/implementation. It is usually a collection of tables.
- * Used in the command member of FlightDescriptor for the following RPC calls:
- * - GetSchema: return the Arrow schema of the query.
- * - GetFlightInfo: execute the catalog metadata request.
- *
- * The returned Arrow schema will be:
- * <
- * catalog_name: utf8,
- * db_schema_name: utf8 not null
- * >
- * The returned data should be ordered by catalog_name, then db_schema_name.
- */
- message CommandGetDbSchemas {
-
- /*
- * Specifies the Catalog to search for the tables.
- * An empty string retrieves those without a catalog.
- * If omitted the catalog name should not be used to narrow the search.
- */
- optional string catalog = 1;
-
- /*
- * Specifies a filter pattern for schemas to search for.
- * When no db_schema_filter_pattern is provided, the pattern will not be used to narrow the search.
- * In the pattern string, two special characters can be used to denote matching rules:
- * - "%" means to match any substring with 0 or more characters.
- * - "_" means to match any one character.
- */
- optional string db_schema_filter_pattern = 2;
- }
-
- /*
- * Represents a request to retrieve the list of tables, and optionally their schemas, on a Flight SQL enabled backend.
- * Used in the command member of FlightDescriptor for the following RPC calls:
- * - GetSchema: return the Arrow schema of the query.
- * - GetFlightInfo: execute the catalog metadata request.
- *
- * The returned Arrow schema will be:
- * <
- * catalog_name: utf8,
- * db_schema_name: utf8,
- * table_name: utf8 not null,
- * table_type: utf8 not null,
- * [optional] table_schema: bytes not null (schema of the table as described in Schema.fbs::Schema,
- * it is serialized as an IPC message.)
- * >
- * Fields on table_schema may contain the following metadata:
- * - ARROW:FLIGHT:SQL:CATALOG_NAME - Table's catalog name
- * - ARROW:FLIGHT:SQL:DB_SCHEMA_NAME - Database schema name
- * - ARROW:FLIGHT:SQL:TABLE_NAME - Table name
- * - ARROW:FLIGHT:SQL:TYPE_NAME - The data source-specific name for the data type of the column.
- * - ARROW:FLIGHT:SQL:PRECISION - Column precision/size
- * - ARROW:FLIGHT:SQL:SCALE - Column scale/decimal digits if applicable
- * - ARROW:FLIGHT:SQL:IS_AUTO_INCREMENT - "1" indicates if the column is auto incremented, "0" otherwise.
- * - ARROW:FLIGHT:SQL:IS_CASE_SENSITIVE - "1" indicates if the column is case-sensitive, "0" otherwise.
- * - ARROW:FLIGHT:SQL:IS_READ_ONLY - "1" indicates if the column is read only, "0" otherwise.
- * - ARROW:FLIGHT:SQL:IS_SEARCHABLE - "1" indicates if the column is searchable via WHERE clause, "0" otherwise.
- * The returned data should be ordered by catalog_name, db_schema_name, table_name, then table_type, followed by table_schema if requested.
- */
- message CommandGetTables {
-
- /*
- * Specifies the Catalog to search for the tables.
- * An empty string retrieves those without a catalog.
- * If omitted the catalog name should not be used to narrow the search.
- */
- optional string catalog = 1;
-
- /*
- * Specifies a filter pattern for schemas to search for.
- * When no db_schema_filter_pattern is provided, all schemas matching other filters are searched.
- * In the pattern string, two special characters can be used to denote matching rules:
- * - "%" means to match any substring with 0 or more characters.
- * - "_" means to match any one character.
- */
- optional string db_schema_filter_pattern = 2;
-
- /*
- * Specifies a filter pattern for tables to search for.
- * When no table_name_filter_pattern is provided, all tables matching other filters are searched.
- * In the pattern string, two special characters can be used to denote matching rules:
- * - "%" means to match any substring with 0 or more characters.
- * - "_" means to match any one character.
- */
- optional string table_name_filter_pattern = 3;
-
- /*
- * Specifies a filter of table types which must match.
- * The table types depend on vendor/implementation. It is usually used to separate tables from views or system tables.
- * TABLE, VIEW, and SYSTEM TABLE are commonly supported.
- */
- repeated string table_types = 4;
-
- // Specifies if the Arrow schema should be returned for found tables.
- bool include_schema = 5;
- }
-
- /*
- * Represents a request to retrieve the list of table types on a Flight SQL enabled backend.
- * The table types depend on vendor/implementation. It is usually used to separate tables from views or system tables.
- * TABLE, VIEW, and SYSTEM TABLE are commonly supported.
- * Used in the command member of FlightDescriptor for the following RPC calls:
- * - GetSchema: return the Arrow schema of the query.
- * - GetFlightInfo: execute the catalog metadata request.
- *
- * The returned Arrow schema will be:
- * <
- * table_type: utf8 not null
- * >
- * The returned data should be ordered by table_type.
- */
- message CommandGetTableTypes {
- }
-
- /*
- * Represents a request to retrieve the primary keys of a table on a Flight SQL enabled backend.
- * Used in the command member of FlightDescriptor for the following RPC calls:
- * - GetSchema: return the Arrow schema of the query.
- * - GetFlightInfo: execute the catalog metadata request.
- *
- * The returned Arrow schema will be:
- * <
- * catalog_name: utf8,
- * db_schema_name: utf8,
- * table_name: utf8 not null,
- * column_name: utf8 not null,
- * key_name: utf8,
- * key_sequence: int32 not null
- * >
- * The returned data should be ordered by catalog_name, db_schema_name, table_name, key_name, then key_sequence.
- */
- message CommandGetPrimaryKeys {
-
- /*
- * Specifies the catalog to search for the table.
- * An empty string retrieves those without a catalog.
- * If omitted the catalog name should not be used to narrow the search.
- */
- optional string catalog = 1;
-
- /*
- * Specifies the schema to search for the table.
- * An empty string retrieves those without a schema.
- * If omitted the schema name should not be used to narrow the search.
- */
- optional string db_schema = 2;
-
- // Specifies the table to get the primary keys for.
- string table = 3;
- }
-
- enum UpdateDeleteRules {
- CASCADE = 0;
- RESTRICT = 1;
- SET_NULL = 2;
- NO_ACTION = 3;
- SET_DEFAULT = 4;
- }
-
- /*
- * Represents a request to retrieve a description of the foreign key columns that reference the given table's
- * primary key columns (the foreign keys exported by a table) of a table on a Flight SQL enabled backend.
- * Used in the command member of FlightDescriptor for the following RPC calls:
- * - GetSchema: return the Arrow schema of the query.
- * - GetFlightInfo: execute the catalog metadata request.
- *
- * The returned Arrow schema will be:
- * <
- * pk_catalog_name: utf8,
- * pk_db_schema_name: utf8,
- * pk_table_name: utf8 not null,
- * pk_column_name: utf8 not null,
- * fk_catalog_name: utf8,
- * fk_db_schema_name: utf8,
- * fk_table_name: utf8 not null,
- * fk_column_name: utf8 not null,
- * key_sequence: int32 not null,
- * fk_key_name: utf8,
- * pk_key_name: utf8,
- * update_rule: uint8 not null,
- * delete_rule: uint8 not null
- * >
- * The returned data should be ordered by fk_catalog_name, fk_db_schema_name, fk_table_name, fk_key_name, then key_sequence.
- * update_rule and delete_rule returns a byte that is equivalent to actions declared on UpdateDeleteRules enum.
- */
- message CommandGetExportedKeys {
-
- /*
- * Specifies the catalog to search for the foreign key table.
- * An empty string retrieves those without a catalog.
- * If omitted the catalog name should not be used to narrow the search.
- */
- optional string catalog = 1;
-
- /*
- * Specifies the schema to search for the foreign key table.
- * An empty string retrieves those without a schema.
- * If omitted the schema name should not be used to narrow the search.
- */
- optional string db_schema = 2;
-
- // Specifies the foreign key table to get the foreign keys for.
- string table = 3;
- }
-
- /*
- * Represents a request to retrieve the foreign keys of a table on a Flight SQL enabled backend.
- * Used in the command member of FlightDescriptor for the following RPC calls:
- * - GetSchema: return the Arrow schema of the query.
- * - GetFlightInfo: execute the catalog metadata request.
- *
- * The returned Arrow schema will be:
- * <
- * pk_catalog_name: utf8,
- * pk_db_schema_name: utf8,
- * pk_table_name: utf8 not null,
- * pk_column_name: utf8 not null,
- * fk_catalog_name: utf8,
- * fk_db_schema_name: utf8,
- * fk_table_name: utf8 not null,
- * fk_column_name: utf8 not null,
- * key_sequence: int32 not null,
- * fk_key_name: utf8,
- * pk_key_name: utf8,
- * update_rule: uint8 not null,
- * delete_rule: uint8 not null
- * >
- * The returned data should be ordered by pk_catalog_name, pk_db_schema_name, pk_table_name, pk_key_name, then key_sequence.
- * update_rule and delete_rule returns a byte that is equivalent to actions:
- * - 0 = CASCADE
- * - 1 = RESTRICT
- * - 2 = SET NULL
- * - 3 = NO ACTION
- * - 4 = SET DEFAULT
- */
- message CommandGetImportedKeys {
-
- /*
- * Specifies the catalog to search for the primary key table.
- * An empty string retrieves those without a catalog.
- * If omitted the catalog name should not be used to narrow the search.
- */
- optional string catalog = 1;
-
- /*
- * Specifies the schema to search for the primary key table.
- * An empty string retrieves those without a schema.
- * If omitted the schema name should not be used to narrow the search.
- */
- optional string db_schema = 2;
-
- // Specifies the primary key table to get the foreign keys for.
- string table = 3;
- }
-
- /*
- * Represents a request to retrieve a description of the foreign key columns in the given foreign key table that
- * reference the primary key or the columns representing a unique constraint of the parent table (could be the same
- * or a different table) on a Flight SQL enabled backend.
- * Used in the command member of FlightDescriptor for the following RPC calls:
- * - GetSchema: return the Arrow schema of the query.
- * - GetFlightInfo: execute the catalog metadata request.
- *
- * The returned Arrow schema will be:
- * <
- * pk_catalog_name: utf8,
- * pk_db_schema_name: utf8,
- * pk_table_name: utf8 not null,
- * pk_column_name: utf8 not null,
- * fk_catalog_name: utf8,
- * fk_db_schema_name: utf8,
- * fk_table_name: utf8 not null,
- * fk_column_name: utf8 not null,
- * key_sequence: int32 not null,
- * fk_key_name: utf8,
- * pk_key_name: utf8,
- * update_rule: uint8 not null,
- * delete_rule: uint8 not null
- * >
- * The returned data should be ordered by pk_catalog_name, pk_db_schema_name, pk_table_name, pk_key_name, then key_sequence.
- * update_rule and delete_rule returns a byte that is equivalent to actions:
- * - 0 = CASCADE
- * - 1 = RESTRICT
- * - 2 = SET NULL
- * - 3 = NO ACTION
- * - 4 = SET DEFAULT
- */
- message CommandGetCrossReference {
-
- /**
- * The catalog name where the parent table is.
- * An empty string retrieves those without a catalog.
- * If omitted the catalog name should not be used to narrow the search.
- */
- optional string pk_catalog = 1;
-
- /**
- * The Schema name where the parent table is.
- * An empty string retrieves those without a schema.
- * If omitted the schema name should not be used to narrow the search.
- */
- optional string pk_db_schema = 2;
-
- /**
- * The parent table name. It cannot be null.
- */
- string pk_table = 3;
-
- /**
- * The catalog name where the foreign table is.
- * An empty string retrieves those without a catalog.
- * If omitted the catalog name should not be used to narrow the search.
- */
- optional string fk_catalog = 4;
-
- /**
- * The schema name where the foreign table is.
- * An empty string retrieves those without a schema.
- * If omitted the schema name should not be used to narrow the search.
- */
- optional string fk_db_schema = 5;
-
- /**
- * The foreign table name. It cannot be null.
- */
- string fk_table = 6;
- }
-
- // Query Execution Action Messages
-
- /*
- * Request message for the "CreatePreparedStatement" action on a Flight SQL enabled backend.
- */
- message ActionCreatePreparedStatementRequest {
-
- // The valid SQL string to create a prepared statement for.
- string query = 1;
- // Create/execute the prepared statement as part of this transaction (if
- // unset, executions of the prepared statement will be auto-committed).
- optional bytes transaction_id = 2;
- }
-
- /*
- * An embedded message describing a Substrait plan to execute.
- */
- message SubstraitPlan {
-
- // The serialized substrait.Plan to create a prepared statement for.
- // XXX(ARROW-16902): this is bytes instead of an embedded message
- // because Protobuf does not really support one DLL using Protobuf
- // definitions from another DLL.
- bytes plan = 1;
- // The Substrait release, e.g. "0.12.0". This information is not
- // tracked in the plan itself, so this is the only way for consumers
- // to potentially know if they can handle the plan.
- string version = 2;
- }
-
- /*
- * Request message for the "CreatePreparedSubstraitPlan" action on a Flight SQL enabled backend.
- */
- message ActionCreatePreparedSubstraitPlanRequest {
-
- // The serialized substrait.Plan to create a prepared statement for.
- SubstraitPlan plan = 1;
- // Create/execute the prepared statement as part of this transaction (if
- // unset, executions of the prepared statement will be auto-committed).
- optional bytes transaction_id = 2;
- }
-
- /*
- * Wrap the result of a "CreatePreparedStatement" or "CreatePreparedSubstraitPlan" action.
- *
- * The resultant PreparedStatement can be closed either:
- * - Manually, through the "ClosePreparedStatement" action;
- * - Automatically, by a server timeout.
- *
- * The result should be wrapped in a google.protobuf.Any message.
- */
- message ActionCreatePreparedStatementResult {
-
- // Opaque handle for the prepared statement on the server.
- bytes prepared_statement_handle = 1;
-
- // If a result set generating query was provided, dataset_schema contains the
- // schema of the result set. It should be an IPC-encapsulated Schema, as described in Schema.fbs.
- // For some queries, the schema of the results may depend on the schema of the parameters. The server
- // should provide its best guess as to the schema at this point. Clients must not assume that this
- // schema, if provided, will be accurate.
- bytes dataset_schema = 2;
-
- // If the query provided contained parameters, parameter_schema contains the
- // schema of the expected parameters. It should be an IPC-encapsulated Schema, as described in Schema.fbs.
- bytes parameter_schema = 3;
- }
-
- /*
- * Request message for the "ClosePreparedStatement" action on a Flight SQL enabled backend.
- * Closes server resources associated with the prepared statement handle.
- */
- message ActionClosePreparedStatementRequest {
-
- // Opaque handle for the prepared statement on the server.
- bytes prepared_statement_handle = 1;
- }
-
- /*
- * Request message for the "BeginTransaction" action.
- * Begins a transaction.
- */
- message ActionBeginTransactionRequest {
- }
-
- /*
- * Request message for the "BeginSavepoint" action.
- * Creates a savepoint within a transaction.
- *
- * Only supported if FLIGHT_SQL_TRANSACTION is
- * FLIGHT_SQL_TRANSACTION_SUPPORT_SAVEPOINT.
- */
- message ActionBeginSavepointRequest {
-
- // The transaction to which a savepoint belongs.
- bytes transaction_id = 1;
- // Name for the savepoint.
- string name = 2;
- }
-
- /*
- * The result of a "BeginTransaction" action.
- *
- * The transaction can be manipulated with the "EndTransaction" action, or
- * automatically via server timeout. If the transaction times out, then it is
- * automatically rolled back.
- *
- * The result should be wrapped in a google.protobuf.Any message.
- */
- message ActionBeginTransactionResult {
-
- // Opaque handle for the transaction on the server.
- bytes transaction_id = 1;
- }
-
- /*
- * The result of a "BeginSavepoint" action.
- *
- * The transaction can be manipulated with the "EndSavepoint" action.
- * If the associated transaction is committed, rolled back, or times
- * out, then the savepoint is also invalidated.
- *
- * The result should be wrapped in a google.protobuf.Any message.
- */
- message ActionBeginSavepointResult {
-
- // Opaque handle for the savepoint on the server.
- bytes savepoint_id = 1;
- }
-
- /*
- * Request message for the "EndTransaction" action.
- *
- * Commit (COMMIT) or rollback (ROLLBACK) the transaction.
- *
- * If the action completes successfully, the transaction handle is
- * invalidated, as are all associated savepoints.
- */
- message ActionEndTransactionRequest {
-
- enum EndTransaction {
- END_TRANSACTION_UNSPECIFIED = 0;
- // Commit the transaction.
- END_TRANSACTION_COMMIT = 1;
- // Roll back the transaction.
- END_TRANSACTION_ROLLBACK = 2;
- }
- // Opaque handle for the transaction on the server.
- bytes transaction_id = 1;
- // Whether to commit/rollback the given transaction.
- EndTransaction action = 2;
- }
-
- /*
- * Request message for the "EndSavepoint" action.
- *
- * Release (RELEASE) the savepoint or rollback (ROLLBACK) to the
- * savepoint.
- *
- * Releasing a savepoint invalidates that savepoint. Rolling back to
- * a savepoint does not invalidate the savepoint, but invalidates all
- * savepoints created after the current savepoint.
- */
- message ActionEndSavepointRequest {
-
- enum EndSavepoint {
- END_SAVEPOINT_UNSPECIFIED = 0;
- // Release the savepoint.
- END_SAVEPOINT_RELEASE = 1;
- // Roll back to a savepoint.
- END_SAVEPOINT_ROLLBACK = 2;
- }
- // Opaque handle for the savepoint on the server.
- bytes savepoint_id = 1;
- // Whether to rollback/release the given savepoint.
- EndSavepoint action = 2;
- }
-
- // Query Execution Messages.
-
- /*
- * Represents a SQL query. Used in the command member of FlightDescriptor
- * for the following RPC calls:
- * - GetSchema: return the Arrow schema of the query.
- * Fields on this schema may contain the following metadata:
- * - ARROW:FLIGHT:SQL:CATALOG_NAME - Table's catalog name
- * - ARROW:FLIGHT:SQL:DB_SCHEMA_NAME - Database schema name
- * - ARROW:FLIGHT:SQL:TABLE_NAME - Table name
- * - ARROW:FLIGHT:SQL:TYPE_NAME - The data source-specific name for the data type of the column.
- * - ARROW:FLIGHT:SQL:PRECISION - Column precision/size
- * - ARROW:FLIGHT:SQL:SCALE - Column scale/decimal digits if applicable
- * - ARROW:FLIGHT:SQL:IS_AUTO_INCREMENT - "1" indicates if the column is auto incremented, "0" otherwise.
- * - ARROW:FLIGHT:SQL:IS_CASE_SENSITIVE - "1" indicates if the column is case-sensitive, "0" otherwise.
- * - ARROW:FLIGHT:SQL:IS_READ_ONLY - "1" indicates if the column is read only, "0" otherwise.
- * - ARROW:FLIGHT:SQL:IS_SEARCHABLE - "1" indicates if the column is searchable via WHERE clause, "0" otherwise.
- * - GetFlightInfo: execute the query.
- */
- message CommandStatementQuery {
-
- // The SQL syntax.
- string query = 1;
- // Include the query as part of this transaction (if unset, the query is auto-committed).
- optional bytes transaction_id = 2;
- }
-
- /*
- * Represents a Substrait plan. Used in the command member of FlightDescriptor
- * for the following RPC calls:
- * - GetSchema: return the Arrow schema of the query.
- * Fields on this schema may contain the following metadata:
- * - ARROW:FLIGHT:SQL:CATALOG_NAME - Table's catalog name
- * - ARROW:FLIGHT:SQL:DB_SCHEMA_NAME - Database schema name
- * - ARROW:FLIGHT:SQL:TABLE_NAME - Table name
- * - ARROW:FLIGHT:SQL:TYPE_NAME - The data source-specific name for the data type of the column.
- * - ARROW:FLIGHT:SQL:PRECISION - Column precision/size
- * - ARROW:FLIGHT:SQL:SCALE - Column scale/decimal digits if applicable
- * - ARROW:FLIGHT:SQL:IS_AUTO_INCREMENT - "1" indicates if the column is auto incremented, "0" otherwise.
- * - ARROW:FLIGHT:SQL:IS_CASE_SENSITIVE - "1" indicates if the column is case-sensitive, "0" otherwise.
- * - ARROW:FLIGHT:SQL:IS_READ_ONLY - "1" indicates if the column is read only, "0" otherwise.
- * - ARROW:FLIGHT:SQL:IS_SEARCHABLE - "1" indicates if the column is searchable via WHERE clause, "0" otherwise.
- * - GetFlightInfo: execute the query.
- * - DoPut: execute the query.
- */
- message CommandStatementSubstraitPlan {
-
- // A serialized substrait.Plan
- SubstraitPlan plan = 1;
- // Include the query as part of this transaction (if unset, the query is auto-committed).
- optional bytes transaction_id = 2;
- }
-
- /**
- * Represents a ticket resulting from GetFlightInfo with a CommandStatementQuery.
- * This should be used only once and treated as an opaque value, that is, clients should not attempt to parse this.
- */
- message TicketStatementQuery {
-
- // Unique identifier for the instance of the statement to execute.
- bytes statement_handle = 1;
- }
-
- /*
- * Represents an instance of executing a prepared statement. Used in the command member of FlightDescriptor for
- * the following RPC calls:
- * - GetSchema: return the Arrow schema of the query.
- * Fields on this schema may contain the following metadata:
- * - ARROW:FLIGHT:SQL:CATALOG_NAME - Table's catalog name
- * - ARROW:FLIGHT:SQL:DB_SCHEMA_NAME - Database schema name
- * - ARROW:FLIGHT:SQL:TABLE_NAME - Table name
- * - ARROW:FLIGHT:SQL:TYPE_NAME - The data source-specific name for the data type of the column.
- * - ARROW:FLIGHT:SQL:PRECISION - Column precision/size
- * - ARROW:FLIGHT:SQL:SCALE - Column scale/decimal digits if applicable
- * - ARROW:FLIGHT:SQL:IS_AUTO_INCREMENT - "1" indicates if the column is auto incremented, "0" otherwise.
- * - ARROW:FLIGHT:SQL:IS_CASE_SENSITIVE - "1" indicates if the column is case-sensitive, "0" otherwise.
- * - ARROW:FLIGHT:SQL:IS_READ_ONLY - "1" indicates if the column is read only, "0" otherwise.
- * - ARROW:FLIGHT:SQL:IS_SEARCHABLE - "1" indicates if the column is searchable via WHERE clause, "0" otherwise.
- *
- * If the schema is retrieved after parameter values have been bound with DoPut, then the server should account
- * for the parameters when determining the schema.
- * - DoPut: bind parameter values. All of the bound parameter sets will be executed as a single atomic execution.
- * - GetFlightInfo: execute the prepared statement instance.
- */
- message CommandPreparedStatementQuery {
-
- // Opaque handle for the prepared statement on the server.
- bytes prepared_statement_handle = 1;
- }
-
- /*
- * Represents a SQL update query. Used in the command member of FlightDescriptor
- * for the RPC call DoPut to cause the server to execute the included SQL update.
- */
- message CommandStatementUpdate {
-
- // The SQL syntax.
- string query = 1;
- // Include the query as part of this transaction (if unset, the query is auto-committed).
- optional bytes transaction_id = 2;
- }
-
- /*
- * Represents a SQL update query. Used in the command member of FlightDescriptor
- * for the RPC call DoPut to cause the server to execute the included
- * prepared statement handle as an update.
- */
- message CommandPreparedStatementUpdate {
-
- // Opaque handle for the prepared statement on the server.
- bytes prepared_statement_handle = 1;
- }
-
- /*
+ /*
+ * Specifies a filter pattern for schemas to search for.
+ * When no db_schema_filter_pattern is provided, the pattern will not be used to narrow the search.
+ * In the pattern string, two special characters can be used to denote matching rules:
+ * - "%" means to match any substring with 0 or more characters.
+ * - "_" means to match any one character.
+ */
+ optional string db_schema_filter_pattern = 2;
+}
+
+/*
+ * Represents a request to retrieve the list of tables, and optionally their schemas, on a Flight SQL enabled backend.
+ * Used in the command member of FlightDescriptor for the following RPC calls:
+ * - GetSchema: return the Arrow schema of the query.
+ * - GetFlightInfo: execute the catalog metadata request.
+ *
+ * The returned Arrow schema will be:
+ * <
+ * catalog_name: utf8,
+ * db_schema_name: utf8,
+ * table_name: utf8 not null,
+ * table_type: utf8 not null,
+ * [optional] table_schema: bytes not null (schema of the table as described in Schema.fbs::Schema,
+ * it is serialized as an IPC message.)
+ * >
+ * Fields on table_schema may contain the following metadata:
+ * - ARROW:FLIGHT:SQL:CATALOG_NAME - Table's catalog name
+ * - ARROW:FLIGHT:SQL:DB_SCHEMA_NAME - Database schema name
+ * - ARROW:FLIGHT:SQL:TABLE_NAME - Table name
+ * - ARROW:FLIGHT:SQL:TYPE_NAME - The data source-specific name for the data type of the column.
+ * - ARROW:FLIGHT:SQL:PRECISION - Column precision/size
+ * - ARROW:FLIGHT:SQL:SCALE - Column scale/decimal digits if applicable
+ * - ARROW:FLIGHT:SQL:IS_AUTO_INCREMENT - "1" indicates if the column is auto incremented, "0" otherwise.
+ * - ARROW:FLIGHT:SQL:IS_CASE_SENSITIVE - "1" indicates if the column is case-sensitive, "0" otherwise.
+ * - ARROW:FLIGHT:SQL:IS_READ_ONLY - "1" indicates if the column is read only, "0" otherwise.
+ * - ARROW:FLIGHT:SQL:IS_SEARCHABLE - "1" indicates if the column is searchable via WHERE clause, "0" otherwise.
+ * - ARROW:FLIGHT:SQL:REMARKS - A comment describing the column. This field has been added after all others, clients should be prepared to find it missing.
+ * The returned data should be ordered by catalog_name, db_schema_name, table_name, then table_type, followed by table_schema if requested.
+ */
+message CommandGetTables {
+
+ /*
+ * Specifies the Catalog to search for the tables.
+ * An empty string retrieves those without a catalog.
+ * If omitted the catalog name should not be used to narrow the search.
+ */
+ optional string catalog = 1;
+
+ /*
+ * Specifies a filter pattern for schemas to search for.
+ * When no db_schema_filter_pattern is provided, all schemas matching other filters are searched.
+ * In the pattern string, two special characters can be used to denote matching rules:
+ * - "%" means to match any substring with 0 or more characters.
+ * - "_" means to match any one character.
+ */
+ optional string db_schema_filter_pattern = 2;
+
+ /*
+ * Specifies a filter pattern for tables to search for.
+ * When no table_name_filter_pattern is provided, all tables matching other filters are searched.
+ * In the pattern string, two special characters can be used to denote matching rules:
+ * - "%" means to match any substring with 0 or more characters.
+ * - "_" means to match any one character.
+ */
+ optional string table_name_filter_pattern = 3;
+
+ /*
+ * Specifies a filter of table types which must match.
+ * The table types depend on vendor/implementation. It is usually used to separate tables from views or system tables.
+ * TABLE, VIEW, and SYSTEM TABLE are commonly supported.
+ */
+ repeated string table_types = 4;
+
+ // Specifies if the Arrow schema should be returned for found tables.
+ bool include_schema = 5;
+}
+
+/*
+ * Represents a request to retrieve the list of table types on a Flight SQL enabled backend.
+ * The table types depend on vendor/implementation. It is usually used to separate tables from views or system tables.
+ * TABLE, VIEW, and SYSTEM TABLE are commonly supported.
+ * Used in the command member of FlightDescriptor for the following RPC calls:
+ * - GetSchema: return the Arrow schema of the query.
+ * - GetFlightInfo: execute the catalog metadata request.
+ *
+ * The returned Arrow schema will be:
+ * <
+ * table_type: utf8 not null
+ * >
+ * The returned data should be ordered by table_type.
+ */
+message CommandGetTableTypes {
+}
+
+/*
+ * Represents a request to retrieve the primary keys of a table on a Flight SQL enabled backend.
+ * Used in the command member of FlightDescriptor for the following RPC calls:
+ * - GetSchema: return the Arrow schema of the query.
+ * - GetFlightInfo: execute the catalog metadata request.
+ *
+ * The returned Arrow schema will be:
+ * <
+ * catalog_name: utf8,
+ * db_schema_name: utf8,
+ * table_name: utf8 not null,
+ * column_name: utf8 not null,
+ * key_name: utf8,
+ * key_sequence: int32 not null
+ * >
+ * The returned data should be ordered by catalog_name, db_schema_name, table_name, key_name, then key_sequence.
+ */
+message CommandGetPrimaryKeys {
+
+ /*
+ * Specifies the catalog to search for the table.
+ * An empty string retrieves those without a catalog.
+ * If omitted the catalog name should not be used to narrow the search.
+ */
+ optional string catalog = 1;
+
+ /*
+ * Specifies the schema to search for the table.
+ * An empty string retrieves those without a schema.
+ * If omitted the schema name should not be used to narrow the search.
+ */
+ optional string db_schema = 2;
+
+ // Specifies the table to get the primary keys for.
+ string table = 3;
+}
+
+enum UpdateDeleteRules {
+ CASCADE = 0;
+ RESTRICT = 1;
+ SET_NULL = 2;
+ NO_ACTION = 3;
+ SET_DEFAULT = 4;
+}
+
+/*
+ * Represents a request to retrieve a description of the foreign key columns that reference the given table's
+ * primary key columns (the foreign keys exported by a table) of a table on a Flight SQL enabled backend.
+ * Used in the command member of FlightDescriptor for the following RPC calls:
+ * - GetSchema: return the Arrow schema of the query.
+ * - GetFlightInfo: execute the catalog metadata request.
+ *
+ * The returned Arrow schema will be:
+ * <
+ * pk_catalog_name: utf8,
+ * pk_db_schema_name: utf8,
+ * pk_table_name: utf8 not null,
+ * pk_column_name: utf8 not null,
+ * fk_catalog_name: utf8,
+ * fk_db_schema_name: utf8,
+ * fk_table_name: utf8 not null,
+ * fk_column_name: utf8 not null,
+ * key_sequence: int32 not null,
+ * fk_key_name: utf8,
+ * pk_key_name: utf8,
+ * update_rule: uint8 not null,
+ * delete_rule: uint8 not null
+ * >
+ * The returned data should be ordered by fk_catalog_name, fk_db_schema_name, fk_table_name, fk_key_name, then key_sequence.
+ * update_rule and delete_rule returns a byte that is equivalent to actions declared on UpdateDeleteRules enum.
+ */
+message CommandGetExportedKeys {
+
+ /*
+ * Specifies the catalog to search for the foreign key table.
+ * An empty string retrieves those without a catalog.
+ * If omitted the catalog name should not be used to narrow the search.
+ */
+ optional string catalog = 1;
+
+ /*
+ * Specifies the schema to search for the foreign key table.
+ * An empty string retrieves those without a schema.
+ * If omitted the schema name should not be used to narrow the search.
+ */
+ optional string db_schema = 2;
+
+ // Specifies the foreign key table to get the foreign keys for.
+ string table = 3;
+}
+
+/*
+ * Represents a request to retrieve the foreign keys of a table on a Flight SQL enabled backend.
+ * Used in the command member of FlightDescriptor for the following RPC calls:
+ * - GetSchema: return the Arrow schema of the query.
+ * - GetFlightInfo: execute the catalog metadata request.
+ *
+ * The returned Arrow schema will be:
+ * <
+ * pk_catalog_name: utf8,
+ * pk_db_schema_name: utf8,
+ * pk_table_name: utf8 not null,
+ * pk_column_name: utf8 not null,
+ * fk_catalog_name: utf8,
+ * fk_db_schema_name: utf8,
+ * fk_table_name: utf8 not null,
+ * fk_column_name: utf8 not null,
+ * key_sequence: int32 not null,
+ * fk_key_name: utf8,
+ * pk_key_name: utf8,
+ * update_rule: uint8 not null,
+ * delete_rule: uint8 not null
+ * >
+ * The returned data should be ordered by pk_catalog_name, pk_db_schema_name, pk_table_name, pk_key_name, then key_sequence.
+ * update_rule and delete_rule returns a byte that is equivalent to actions:
+ * - 0 = CASCADE
+ * - 1 = RESTRICT
+ * - 2 = SET NULL
+ * - 3 = NO ACTION
+ * - 4 = SET DEFAULT
+ */
+message CommandGetImportedKeys {
+
+ /*
+ * Specifies the catalog to search for the primary key table.
+ * An empty string retrieves those without a catalog.
+ * If omitted the catalog name should not be used to narrow the search.
+ */
+ optional string catalog = 1;
+
+ /*
+ * Specifies the schema to search for the primary key table.
+ * An empty string retrieves those without a schema.
+ * If omitted the schema name should not be used to narrow the search.
+ */
+ optional string db_schema = 2;
+
+ // Specifies the primary key table to get the foreign keys for.
+ string table = 3;
+}
+
+/*
+ * Represents a request to retrieve a description of the foreign key columns in the given foreign key table that
+ * reference the primary key or the columns representing a unique constraint of the parent table (could be the same
+ * or a different table) on a Flight SQL enabled backend.
+ * Used in the command member of FlightDescriptor for the following RPC calls:
+ * - GetSchema: return the Arrow schema of the query.
+ * - GetFlightInfo: execute the catalog metadata request.
+ *
+ * The returned Arrow schema will be:
+ * <
+ * pk_catalog_name: utf8,
+ * pk_db_schema_name: utf8,
+ * pk_table_name: utf8 not null,
+ * pk_column_name: utf8 not null,
+ * fk_catalog_name: utf8,
+ * fk_db_schema_name: utf8,
+ * fk_table_name: utf8 not null,
+ * fk_column_name: utf8 not null,
+ * key_sequence: int32 not null,
+ * fk_key_name: utf8,
+ * pk_key_name: utf8,
+ * update_rule: uint8 not null,
+ * delete_rule: uint8 not null
+ * >
+ * The returned data should be ordered by pk_catalog_name, pk_db_schema_name, pk_table_name, pk_key_name, then key_sequence.
+ * update_rule and delete_rule returns a byte that is equivalent to actions:
+ * - 0 = CASCADE
+ * - 1 = RESTRICT
+ * - 2 = SET NULL
+ * - 3 = NO ACTION
+ * - 4 = SET DEFAULT
+ */
+message CommandGetCrossReference {
+
+ /**
+ * The catalog name where the parent table is.
+ * An empty string retrieves those without a catalog.
+ * If omitted the catalog name should not be used to narrow the search.
+ */
+ optional string pk_catalog = 1;
+
+ /**
+ * The Schema name where the parent table is.
+ * An empty string retrieves those without a schema.
+ * If omitted the schema name should not be used to narrow the search.
+ */
+ optional string pk_db_schema = 2;
+
+ /**
+ * The parent table name. It cannot be null.
+ */
+ string pk_table = 3;
+
+ /**
+ * The catalog name where the foreign table is.
+ * An empty string retrieves those without a catalog.
+ * If omitted the catalog name should not be used to narrow the search.
+ */
+ optional string fk_catalog = 4;
+
+ /**
+ * The schema name where the foreign table is.
+ * An empty string retrieves those without a schema.
+ * If omitted the schema name should not be used to narrow the search.
+ */
+ optional string fk_db_schema = 5;
+
+ /**
+ * The foreign table name. It cannot be null.
+ */
+ string fk_table = 6;
+}
+
+// Query Execution Action Messages
+
+/*
+ * Request message for the "CreatePreparedStatement" action on a Flight SQL enabled backend.
+ */
+message ActionCreatePreparedStatementRequest {
+
+ // The valid SQL string to create a prepared statement for.
+ string query = 1;
+ // Create/execute the prepared statement as part of this transaction (if
+ // unset, executions of the prepared statement will be auto-committed).
+ optional bytes transaction_id = 2;
+}
+
+/*
+ * An embedded message describing a Substrait plan to execute.
+ */
+message SubstraitPlan {
+
+ // The serialized substrait.Plan to create a prepared statement for.
+ // XXX(ARROW-16902): this is bytes instead of an embedded message
+ // because Protobuf does not really support one DLL using Protobuf
+ // definitions from another DLL.
+ bytes plan = 1;
+ // The Substrait release, e.g. "0.12.0". This information is not
+ // tracked in the plan itself, so this is the only way for consumers
+ // to potentially know if they can handle the plan.
+ string version = 2;
+}
+
+/*
+ * Request message for the "CreatePreparedSubstraitPlan" action on a Flight SQL enabled backend.
+ */
+message ActionCreatePreparedSubstraitPlanRequest {
+
+ // The serialized substrait.Plan to create a prepared statement for.
+ SubstraitPlan plan = 1;
+ // Create/execute the prepared statement as part of this transaction (if
+ // unset, executions of the prepared statement will be auto-committed).
+ optional bytes transaction_id = 2;
+}
+
+/*
+ * Wrap the result of a "CreatePreparedStatement" or "CreatePreparedSubstraitPlan" action.
+ *
+ * The resultant PreparedStatement can be closed either:
+ * - Manually, through the "ClosePreparedStatement" action;
+ * - Automatically, by a server timeout.
+ *
+ * The result should be wrapped in a google.protobuf.Any message.
+ */
+message ActionCreatePreparedStatementResult {
+
+ // Opaque handle for the prepared statement on the server.
+ bytes prepared_statement_handle = 1;
+
+ // If a result set generating query was provided, dataset_schema contains the
+ // schema of the result set. It should be an IPC-encapsulated Schema, as described in Schema.fbs.
+ // For some queries, the schema of the results may depend on the schema of the parameters. The server
+ // should provide its best guess as to the schema at this point. Clients must not assume that this
+ // schema, if provided, will be accurate.
+ bytes dataset_schema = 2;
+
+ // If the query provided contained parameters, parameter_schema contains the
+ // schema of the expected parameters. It should be an IPC-encapsulated Schema, as described in Schema.fbs.
+ bytes parameter_schema = 3;
+}
+
+/*
+ * Request message for the "ClosePreparedStatement" action on a Flight SQL enabled backend.
+ * Closes server resources associated with the prepared statement handle.
+ */
+message ActionClosePreparedStatementRequest {
+
+ // Opaque handle for the prepared statement on the server.
+ bytes prepared_statement_handle = 1;
+}
+
+/*
+ * Request message for the "BeginTransaction" action.
+ * Begins a transaction.
+ */
+message ActionBeginTransactionRequest {
+}
+
+/*
+ * Request message for the "BeginSavepoint" action.
+ * Creates a savepoint within a transaction.
+ *
+ * Only supported if FLIGHT_SQL_SERVER_TRANSACTION returns
+ * SQL_SUPPORTED_TRANSACTION_SAVEPOINT.
+ */
+message ActionBeginSavepointRequest {
+
+ // The transaction to which a savepoint belongs.
+ bytes transaction_id = 1;
+ // Name for the savepoint.
+ string name = 2;
+}
+
+/*
+ * The result of a "BeginTransaction" action.
+ *
+ * The transaction can be manipulated with the "EndTransaction" action, or
+ * automatically via server timeout. If the transaction times out, then it is
+ * automatically rolled back.
+ *
+ * The result should be wrapped in a google.protobuf.Any message.
+ */
+message ActionBeginTransactionResult {
+
+ // Opaque handle for the transaction on the server.
+ bytes transaction_id = 1;
+}
+
+/*
+ * The result of a "BeginSavepoint" action.
+ *
+ * The transaction can be manipulated with the "EndSavepoint" action.
+ * If the associated transaction is committed, rolled back, or times
+ * out, then the savepoint is also invalidated.
+ *
+ * The result should be wrapped in a google.protobuf.Any message.
+ */
+message ActionBeginSavepointResult {
+
+ // Opaque handle for the savepoint on the server.
+ bytes savepoint_id = 1;
+}
+
+/*
+ * Request message for the "EndTransaction" action.
+ *
+ * Commit (COMMIT) or rollback (ROLLBACK) the transaction.
+ *
+ * If the action completes successfully, the transaction handle is
+ * invalidated, as are all associated savepoints.
+ */
+message ActionEndTransactionRequest {
+
+ enum EndTransaction {
+ END_TRANSACTION_UNSPECIFIED = 0;
+ // Commit the transaction.
+ END_TRANSACTION_COMMIT = 1;
+ // Roll back the transaction.
+ END_TRANSACTION_ROLLBACK = 2;
+ }
+ // Opaque handle for the transaction on the server.
+ bytes transaction_id = 1;
+ // Whether to commit/rollback the given transaction.
+ EndTransaction action = 2;
+}
+
+/*
+ * Request message for the "EndSavepoint" action.
+ *
+ * Release (RELEASE) the savepoint or rollback (ROLLBACK) to the
+ * savepoint.
+ *
+ * Releasing a savepoint invalidates that savepoint. Rolling back to
+ * a savepoint does not invalidate the savepoint, but invalidates all
+ * savepoints created after the current savepoint.
+ */
+message ActionEndSavepointRequest {
+
+ enum EndSavepoint {
+ END_SAVEPOINT_UNSPECIFIED = 0;
+ // Release the savepoint.
+ END_SAVEPOINT_RELEASE = 1;
+ // Roll back to a savepoint.
+ END_SAVEPOINT_ROLLBACK = 2;
+ }
+ // Opaque handle for the savepoint on the server.
+ bytes savepoint_id = 1;
+ // Whether to rollback/release the given savepoint.
+ EndSavepoint action = 2;
+}
+
+// Query Execution Messages.
+
+/*
+ * Represents a SQL query. Used in the command member of FlightDescriptor
+ * for the following RPC calls:
+ * - GetSchema: return the Arrow schema of the query.
+ * Fields on this schema may contain the following metadata:
+ * - ARROW:FLIGHT:SQL:CATALOG_NAME - Table's catalog name
+ * - ARROW:FLIGHT:SQL:DB_SCHEMA_NAME - Database schema name
+ * - ARROW:FLIGHT:SQL:TABLE_NAME - Table name
+ * - ARROW:FLIGHT:SQL:TYPE_NAME - The data source-specific name for the data type of the column.
+ * - ARROW:FLIGHT:SQL:PRECISION - Column precision/size
+ * - ARROW:FLIGHT:SQL:SCALE - Column scale/decimal digits if applicable
+ * - ARROW:FLIGHT:SQL:IS_AUTO_INCREMENT - "1" indicates if the column is auto incremented, "0" otherwise.
+ * - ARROW:FLIGHT:SQL:IS_CASE_SENSITIVE - "1" indicates if the column is case-sensitive, "0" otherwise.
+ * - ARROW:FLIGHT:SQL:IS_READ_ONLY - "1" indicates if the column is read only, "0" otherwise.
+ * - ARROW:FLIGHT:SQL:IS_SEARCHABLE - "1" indicates if the column is searchable via WHERE clause, "0" otherwise.
+ * - ARROW:FLIGHT:SQL:REMARKS - A comment describing the column. This field has been added after all others, clients should be prepared to find it missing.
+ * - GetFlightInfo: execute the query.
+ */
+message CommandStatementQuery {
+
+ // The SQL syntax.
+ string query = 1;
+ // Include the query as part of this transaction (if unset, the query is auto-committed).
+ optional bytes transaction_id = 2;
+}
+
+/*
+ * Represents a Substrait plan. Used in the command member of FlightDescriptor
+ * for the following RPC calls:
+ * - GetSchema: return the Arrow schema of the query.
+ * Fields on this schema may contain the following metadata:
+ * - ARROW:FLIGHT:SQL:CATALOG_NAME - Table's catalog name
+ * - ARROW:FLIGHT:SQL:DB_SCHEMA_NAME - Database schema name
+ * - ARROW:FLIGHT:SQL:TABLE_NAME - Table name
+ * - ARROW:FLIGHT:SQL:TYPE_NAME - The data source-specific name for the data type of the column.
+ * - ARROW:FLIGHT:SQL:PRECISION - Column precision/size
+ * - ARROW:FLIGHT:SQL:SCALE - Column scale/decimal digits if applicable
+ * - ARROW:FLIGHT:SQL:IS_AUTO_INCREMENT - "1" indicates if the column is auto incremented, "0" otherwise.
+ * - ARROW:FLIGHT:SQL:IS_CASE_SENSITIVE - "1" indicates if the column is case-sensitive, "0" otherwise.
+ * - ARROW:FLIGHT:SQL:IS_READ_ONLY - "1" indicates if the column is read only, "0" otherwise.
+ * - ARROW:FLIGHT:SQL:IS_SEARCHABLE - "1" indicates if the column is searchable via WHERE clause, "0" otherwise.
+ * - ARROW:FLIGHT:SQL:REMARKS - A comment describing the column. This field has been added after all others, clients should be prepared to find it missing.
+ * - GetFlightInfo: execute the query.
+ * - DoPut: execute the query.
+ */
+message CommandStatementSubstraitPlan {
+
+ // A serialized substrait.Plan
+ SubstraitPlan plan = 1;
+ // Include the query as part of this transaction (if unset, the query is auto-committed).
+ optional bytes transaction_id = 2;
+}
+
+/**
+ * Represents a ticket resulting from GetFlightInfo with a CommandStatementQuery.
+ * This should be used only once and treated as an opaque value, that is, clients should not attempt to parse this.
+ */
+message TicketStatementQuery {
+
+ // Unique identifier for the instance of the statement to execute.
+ bytes statement_handle = 1;
+}
+
+/*
+ * Represents an instance of executing a prepared statement. Used in the command member of FlightDescriptor for
+ * the following RPC calls:
+ * - GetSchema: return the Arrow schema of the query.
+ * Fields on this schema may contain the following metadata:
+ * - ARROW:FLIGHT:SQL:CATALOG_NAME - Table's catalog name
+ * - ARROW:FLIGHT:SQL:DB_SCHEMA_NAME - Database schema name
+ * - ARROW:FLIGHT:SQL:TABLE_NAME - Table name
+ * - ARROW:FLIGHT:SQL:TYPE_NAME - The data source-specific name for the data type of the column.
+ * - ARROW:FLIGHT:SQL:PRECISION - Column precision/size
+ * - ARROW:FLIGHT:SQL:SCALE - Column scale/decimal digits if applicable
+ * - ARROW:FLIGHT:SQL:IS_AUTO_INCREMENT - "1" indicates if the column is auto incremented, "0" otherwise.
+ * - ARROW:FLIGHT:SQL:IS_CASE_SENSITIVE - "1" indicates if the column is case-sensitive, "0" otherwise.
+ * - ARROW:FLIGHT:SQL:IS_READ_ONLY - "1" indicates if the column is read only, "0" otherwise.
+ * - ARROW:FLIGHT:SQL:IS_SEARCHABLE - "1" indicates if the column is searchable via WHERE clause, "0" otherwise.
+ * - ARROW:FLIGHT:SQL:REMARKS - A comment describing the column. This field has been added after all others, clients should be prepared to find it missing.
+ *
+ * If the schema is retrieved after parameter values have been bound with DoPut, then the server should account
+ * for the parameters when determining the schema.
+ * - DoPut: bind parameter values. All of the bound parameter sets will be executed as a single atomic execution.
+ * - GetFlightInfo: execute the prepared statement instance.
+ */
+message CommandPreparedStatementQuery {
+
+ // Opaque handle for the prepared statement on the server.
+ bytes prepared_statement_handle = 1;
+}
+
+/*
+ * Represents a SQL update query. Used in the command member of FlightDescriptor
+ * for the RPC call DoPut to cause the server to execute the included SQL update.
+ */
+message CommandStatementUpdate {
+
+ // The SQL syntax.
+ string query = 1;
+ // Include the query as part of this transaction (if unset, the query is auto-committed).
+ optional bytes transaction_id = 2;
+}
+
+/*
+ * Represents a SQL update query. Used in the command member of FlightDescriptor
+ * for the RPC call DoPut to cause the server to execute the included
+ * prepared statement handle as an update.
+ */
+message CommandPreparedStatementUpdate {
+
+ // Opaque handle for the prepared statement on the server.
+ bytes prepared_statement_handle = 1;
+}
+
+/*
* Represents a bulk ingestion request. Used in the command member of FlightDescriptor
- * for the the RPC call DoPut to cause the server load the contents of the stream's
+ * for the RPC call DoPut to cause the server load the contents of the stream's
* FlightData into the target destination.
*/
message CommandStatementIngest {
@@ -1836,90 +1840,90 @@ message CommandStatementIngest {
* Returned from the RPC call DoPut when a CommandStatementUpdate,
* CommandPreparedStatementUpdate, or CommandStatementIngest was
* in the request, containing results from the update.
- */
- message DoPutUpdateResult {
-
- // The number of records updated. A return value of -1 represents
- // an unknown updated record count.
- int64 record_count = 1;
- }
-
- /* An *optional* response returned when `DoPut` is called with `CommandPreparedStatementQuery`.
- *
- * *Note on legacy behavior*: previous versions of the protocol did not return any result for
- * this command, and that behavior should still be supported by clients. In that case, the client
- * can continue as though the fields in this message were not provided or set to sensible default values.
- */
- message DoPutPreparedStatementResult {
-
- // Represents a (potentially updated) opaque handle for the prepared statement on the server.
- // Because the handle could potentially be updated, any previous handles for this prepared
- // statement should be considered invalid, and all subsequent requests for this prepared
- // statement must use this new handle.
- // The updated handle allows implementing query parameters with stateless services.
- //
- // When an updated handle is not provided by the server, clients should contiue
- // using the previous handle provided by `ActionCreatePreparedStatementResonse`.
- optional bytes prepared_statement_handle = 1;
+ */
+message DoPutUpdateResult {
+
+ // The number of records updated. A return value of -1 represents
+ // an unknown updated record count.
+ int64 record_count = 1;
+}
+
+/* An *optional* response returned when `DoPut` is called with `CommandPreparedStatementQuery`.
+ *
+ * *Note on legacy behavior*: previous versions of the protocol did not return any result for
+ * this command, and that behavior should still be supported by clients. In that case, the client
+ * can continue as though the fields in this message were not provided or set to sensible default values.
+ */
+message DoPutPreparedStatementResult {
+
+ // Represents a (potentially updated) opaque handle for the prepared statement on the server.
+ // Because the handle could potentially be updated, any previous handles for this prepared
+ // statement should be considered invalid, and all subsequent requests for this prepared
+ // statement must use this new handle.
+ // The updated handle allows implementing query parameters with stateless services.
+ //
+ // When an updated handle is not provided by the server, clients should continue
+ // using the previous handle provided by `ActionCreatePreparedStatementResult`.
+ optional bytes prepared_statement_handle = 1;
+}
+
+/*
+ * Request message for the "CancelQuery" action.
+ *
+ * Explicitly cancel a running query.
+ *
+ * This lets a single client explicitly cancel work, no matter how many clients
+ * are involved/whether the query is distributed or not, given server support.
+ * The transaction/statement is not rolled back; it is the application's job to
+ * commit or rollback as appropriate. This only indicates the client no longer
+ * wishes to read the remainder of the query results or continue submitting
+ * data.
+ *
+ * This command is idempotent.
+ *
+ * This command is deprecated since 13.0.0. Use the "CancelFlightInfo"
+ * action with DoAction instead.
+ */
+message ActionCancelQueryRequest {
+ option deprecated = true;
+
+ // The result of the GetFlightInfo RPC that initiated the query.
+ // XXX(ARROW-16902): this must be a serialized FlightInfo, but is
+ // rendered as bytes because Protobuf does not really support one
+ // DLL using Protobuf definitions from another DLL.
+ bytes info = 1;
+}
+
+/*
+ * The result of cancelling a query.
+ *
+ * The result should be wrapped in a google.protobuf.Any message.
+ *
+ * This command is deprecated since 13.0.0. Use the "CancelFlightInfo"
+ * action with DoAction instead.
+ */
+message ActionCancelQueryResult {
+ option deprecated = true;
+
+ enum CancelResult {
+ // 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_RESULT_UNSPECIFIED = 0;
+ // The cancellation request is complete. Subsequent requests with
+ // the same payload may return CANCELLED or a NOT_FOUND error.
+ CANCEL_RESULT_CANCELLED = 1;
+ // The cancellation request is in progress. The client may retry
+ // the cancellation request.
+ CANCEL_RESULT_CANCELLING = 2;
+ // The query is not cancellable. The client should not retry the
+ // cancellation request.
+ CANCEL_RESULT_NOT_CANCELLABLE = 3;
}
- /*
- * Request message for the "CancelQuery" action.
- *
- * Explicitly cancel a running query.
- *
- * This lets a single client explicitly cancel work, no matter how many clients
- * are involved/whether the query is distributed or not, given server support.
- * The transaction/statement is not rolled back; it is the application's job to
- * commit or rollback as appropriate. This only indicates the client no longer
- * wishes to read the remainder of the query results or continue submitting
- * data.
- *
- * This command is idempotent.
- *
- * This command is deprecated since 13.0.0. Use the "CancelFlightInfo"
- * action with DoAction instead.
- */
- message ActionCancelQueryRequest {
- option deprecated = true;
-
- // The result of the GetFlightInfo RPC that initiated the query.
- // XXX(ARROW-16902): this must be a serialized FlightInfo, but is
- // rendered as bytes because Protobuf does not really support one
- // DLL using Protobuf definitions from another DLL.
- bytes info = 1;
- }
-
- /*
- * The result of cancelling a query.
- *
- * The result should be wrapped in a google.protobuf.Any message.
- *
- * This command is deprecated since 13.0.0. Use the "CancelFlightInfo"
- * action with DoAction instead.
- */
- message ActionCancelQueryResult {
- option deprecated = true;
-
- enum CancelResult {
- // 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_RESULT_UNSPECIFIED = 0;
- // The cancellation request is complete. Subsequent requests with
- // the same payload may return CANCELLED or a NOT_FOUND error.
- CANCEL_RESULT_CANCELLED = 1;
- // The cancellation request is in progress. The client may retry
- // the cancellation request.
- CANCEL_RESULT_CANCELLING = 2;
- // The query is not cancellable. The client should not retry the
- // cancellation request.
- CANCEL_RESULT_NOT_CANCELLABLE = 3;
- }
-
- CancelResult result = 1;
- }
-
- extend google.protobuf.MessageOptions {
- bool experimental = 1000;
- }
+ CancelResult result = 1;
+}
+
+extend google.protobuf.MessageOptions {
+ bool experimental = 1000;
+}
diff --git a/format/Message.fbs b/format/Message.fbs
index c8c9b4b82c..61d9b05c69 100644
--- a/format/Message.fbs
+++ b/format/Message.fbs
@@ -42,20 +42,20 @@ struct FieldNode {
null_count: long;
}
-enum CompressionType:byte {
- // LZ4 frame format, for portability, as provided by lz4frame.h or wrappers
- // thereof. Not to be confused with "raw" (also called "block") format
- // provided by lz4.h
+enum CompressionType: byte {
+ /// LZ4 frame format, for portability, as provided by lz4frame.h or wrappers
+ /// thereof. Not to be confused with "raw" (also called "block") format
+ /// provided by lz4.h
LZ4_FRAME,
- // Zstandard
+ /// Zstandard
ZSTD
}
/// Provided for forward compatibility in case we need to support different
/// strategies for compressing the IPC message body (like whole-body
/// compression rather than buffer-level) in the future
-enum BodyCompressionMethod:byte {
+enum BodyCompressionMethod: byte {
/// Each constituent buffer is first compressed with the indicated
/// compressor, and then written with the uncompressed length in the first 8
/// bytes as a 64-bit little-endian signed integer followed by the compressed
@@ -63,6 +63,8 @@ enum BodyCompressionMethod:byte {
/// uncompressed length may be set to -1 to indicate that the data that
/// follows is not compressed, which can be useful for cases where
/// compression does not yield appreciable savings.
+ /// Also, empty buffers can optionally be written out as 0-byte compressed
+ /// buffers, thereby omitting the 8-bytes length header.
BUFFER
}
@@ -102,7 +104,7 @@ table RecordBatch {
/// Some types such as Utf8View are represented using a variable number of buffers.
/// For each such Field in the pre-ordered flattened logical schema, there will be
- /// an entry in variadicBufferCounts to indicate the number of number of variadic
+ /// an entry in variadicBufferCounts to indicate the number of variadic
/// buffers which belong to that Field in the current RecordBatch.
///
/// For example, the schema
@@ -142,7 +144,11 @@ table DictionaryBatch {
///
/// Arrow implementations do not need to implement all of the message types,
/// which may include experimental metadata types. For maximum compatibility,
-/// it is best to send data using RecordBatch
+/// it is best to send data using RecordBatch.
+///
+/// Tensor and SparseTensor are DEPRECATED. The recommended way to pass dense
+/// tensors over Arrow IPC is a RecordBatch field with the `arrow.fixed_shape_tensor`
+/// canonical type. Sparse tensors currently do not have a recommended replacement.
union MessageHeader {
Schema, DictionaryBatch, RecordBatch, Tensor, SparseTensor
}
@@ -154,4 +160,4 @@ table Message {
custom_metadata: [ KeyValue ];
}
-root_type Message;
\ No newline at end of file
+root_type Message;
diff --git a/format/Schema.fbs b/format/Schema.fbs
index ab726903d1..19e1633e80 100644
--- a/format/Schema.fbs
+++ b/format/Schema.fbs
@@ -24,6 +24,7 @@
/// Version 1.3 - Add Run-End Encoded.
/// Version 1.4 - Add BinaryView, Utf8View, variadicBufferCounts, ListView, and
/// LargeListView.
+/// Version 1.5 - Add 32-bit and 64-bit as allowed bit widths for Decimal
namespace org.apache.arrow.flatbuf;
@@ -60,8 +61,8 @@ enum MetadataVersion:short {
/// forward compatibility guarantees).
/// 2. A means of negotiating between a client and server
/// what features a stream is allowed to use. The enums
-/// values here are intented to represent higher level
-/// features, additional details maybe negotiated
+/// values here are intended to represent higher level
+/// features, additional details may be negotiated
/// with key-value pairs specific to the protocol.
///
/// Enums added to this list should be assigned power-of-two values
@@ -124,7 +125,7 @@ table FixedSizeList {
/// may be set in the metadata for this field.
///
/// In a field with Map type, the field has a child Struct field, which then
-/// has two children: key type and the second the value type. The names of the
+/// has two children: the key type and the value type. The names of the
/// child fields may be respectively "entries", "key", and "value", but this is
/// not enforced.
///
@@ -222,9 +223,9 @@ table RunEndEncoded {
}
/// Exact decimal value represented as an integer value in two's
-/// complement. Currently only 128-bit (16-byte) and 256-bit (32-byte) integers
-/// are used. The representation uses the endianness indicated
-/// in the Schema.
+/// complement. Currently 32-bit (4-byte), 64-bit (8-byte),
+/// 128-bit (16-byte) and 256-bit (32-byte) integers are used.
+/// The representation uses the endianness indicated in the Schema.
table Decimal {
/// Total number of decimal digits
precision: int;
@@ -232,7 +233,7 @@ table Decimal {
/// Number of digits after the decimal point "."
scale: int;
- /// Number of bits per value. The only accepted widths are 128 and 256.
+ /// Number of bits per value. The accepted widths are 32, 64, 128 and 256.
/// We use bitWidth for consistency with Int::bitWidth.
bitWidth: int = 128;
}
@@ -394,42 +395,50 @@ table Timestamp {
timezone: string;
}
-enum IntervalUnit: short { YEAR_MONTH, DAY_TIME, MONTH_DAY_NANO}
-// A "calendar" interval which models types that don't necessarily
-// have a precise duration without the context of a base timestamp (e.g.
-// days can differ in length during day light savings time transitions).
-// All integers in the types below are stored in the endianness indicated
-// by the schema.
-//
-// YEAR_MONTH - Indicates the number of elapsed whole months, stored as
-// 4-byte signed integers.
-// DAY_TIME - Indicates the number of elapsed days and milliseconds (no leap seconds),
-// stored as 2 contiguous 32-bit signed integers (8-bytes in total). Support
-// of this IntervalUnit is not required for full arrow compatibility.
-// MONTH_DAY_NANO - A triple of the number of elapsed months, days, and nanoseconds.
-// The values are stored contiguously in 16-byte blocks. Months and days are
-// encoded as 32-bit signed integers and nanoseconds is encoded as a 64-bit
-// signed integer. Nanoseconds does not allow for leap seconds. Each field is
-// independent (e.g. there is no constraint that nanoseconds have the same
-// sign as days or that the quantity of nanoseconds represents less than a
-// day's worth of time).
+/// The unit of an Interval.
+///
+/// All integers in the units below are stored in the endianness indicated
+/// by the schema.
+enum IntervalUnit: short {
+ /// Indicates the number of elapsed whole months, stored as
+ /// 4-byte signed integers.
+ YEAR_MONTH,
+
+ /// Indicates the number of elapsed days and milliseconds (no leap seconds),
+ /// stored as 2 contiguous 32-bit signed integers (8-bytes in total). Support
+ /// of this IntervalUnit is not required for full Arrow compatibility.
+ DAY_TIME,
+
+ /// A triple of the number of elapsed months, days, and nanoseconds.
+ /// The values are stored contiguously in 16-byte blocks. Months and days are
+ /// encoded as 32-bit signed integers and nanoseconds is encoded as a 64-bit
+ /// signed integer. Nanoseconds does not allow for leap seconds. Each field is
+ /// independent (e.g. there is no constraint that nanoseconds have the same
+ /// sign as days or that the quantity of nanoseconds represents less than a
+ /// day's worth of time).
+ MONTH_DAY_NANO
+}
+
+/// A "calendar" interval which models types that don't necessarily
+/// have a precise duration without the context of a base timestamp (e.g.
+/// days can differ in length during day light savings time transitions).
table Interval {
unit: IntervalUnit;
}
-// An absolute length of time unrelated to any calendar artifacts.
-//
-// For the purposes of Arrow Implementations, adding this value to a Timestamp
-// ("t1") naively (i.e. simply summing the two number) is acceptable even
-// though in some cases the resulting Timestamp (t2) would not account for
-// leap-seconds during the elapsed time between "t1" and "t2". Similarly,
-// representing the difference between two Unix timestamp is acceptable, but
-// would yield a value that is possibly a few seconds off from the true elapsed
-// time.
-//
-// The resolution defaults to millisecond, but can be any of the other
-// supported TimeUnit values as with Timestamp and Time types. This type is
-// always represented as an 8-byte integer.
+/// An absolute length of time unrelated to any calendar artifacts.
+///
+/// For the purposes of Arrow Implementations, adding this value to a Timestamp
+/// ("t1") naively (i.e. simply summing the two numbers) is acceptable even
+/// though in some cases the resulting Timestamp (t2) would not account for
+/// leap-seconds during the elapsed time between "t1" and "t2". Similarly,
+/// representing the difference between two Unix timestamps is acceptable, but
+/// would yield a value that is possibly a few seconds off from the true elapsed
+/// time.
+///
+/// The resolution defaults to millisecond, but can be any of the other
+/// supported TimeUnit values as with Timestamp and Time types. This type is
+/// always represented as an 8-byte integer.
table Duration {
unit: TimeUnit = MILLISECOND;
}
@@ -468,7 +477,7 @@ union Type {
}
/// ----------------------------------------------------------------------
-/// user defined key value pairs to add custom metadata to arrow
+/// user defined key value pairs to add custom metadata to Arrow
/// key namespacing is the responsibility of the user
table KeyValue {
@@ -496,7 +505,7 @@ table DictionaryEncoding {
indexType: Int;
/// By default, dictionaries are not ordered, or the order does not have
- /// semantic meaning. In some statistical, applications, dictionary-encoding
+ /// semantic meaning. In some statistical applications, dictionary-encoding
/// is used to represent ordered categorical data, and we provide a way to
/// preserve that metadata here
isOrdered: bool;
@@ -509,7 +518,7 @@ table DictionaryEncoding {
/// nested type.
table Field {
- /// Name is not required, in i.e. a List
+ /// Name is not required (e.g., in a List)
name: string;
/// Whether or not this field can contain nulls. Should be true in general.
@@ -560,11 +569,12 @@ table Schema {
endianness: Endianness=Little;
fields: [Field];
- // User-defined metadata
+
+ /// User-defined metadata
custom_metadata: [ KeyValue ];
/// Features used in the stream/file.
features : [ Feature ];
}
-root_type Schema;
\ No newline at end of file
+root_type Schema;
diff --git a/format/SparseTensor.fbs b/format/SparseTensor.fbs
index a6fd2f9e74..a346e539cd 100644
--- a/format/SparseTensor.fbs
+++ b/format/SparseTensor.fbs
@@ -15,7 +15,7 @@
// specific language governing permissions and limitations
// under the License.
-/// EXPERIMENTAL: Metadata for n-dimensional sparse arrays, aka "sparse tensors".
+/// DEPRECATED: Metadata for n-dimensional sparse arrays, aka "sparse tensors".
/// Arrow implementations in general are not required to implement this type
include "Tensor.fbs";
@@ -27,11 +27,11 @@ namespace org.apache.arrow.flatbuf;
/// Coordinate (COO) format of sparse tensor index.
///
-/// COO's index list are represented as a NxM matrix,
+/// COO's index list is represented as an NxM matrix,
/// where N is the number of non-zero values,
/// and M is the number of dimensions of a sparse tensor.
///
-/// indicesBuffer stores the location and size of the data of this indices
+/// indicesBuffer stores the location and size of the data of these indices
/// matrix. The value type and the stride of the indices matrix is
/// specified in indicesType and indicesStrides fields.
///
@@ -52,7 +52,7 @@ namespace org.apache.arrow.flatbuf;
/// [2, 2, 3, 1, 2, 0],
/// [0, 1, 0, 0, 3, 4]]
/// ```
-/// When isCanonical is true, the indices is sorted in lexicographical order
+/// When isCanonical is true, the indices are sorted in lexicographical order
/// (row-major order), and it does not have duplicated entries. Otherwise,
/// the indices may not be sorted, or may have duplicated entries.
table SparseTensorIndexCOO {
@@ -116,7 +116,7 @@ table SparseMatrixIndexCSX {
/// contains the column indices of the corresponding non-zero values.
/// The type of index value is long.
///
- /// For example, the indices of the above X is:
+ /// For example, the indices of the above X are:
/// ```text
/// indices(X) = [1, 2, 2, 1, 3, 0, 2, 3, 1].
/// ```
@@ -132,7 +132,7 @@ table SparseTensorIndexCSF {
/// CSF index recursively compresses each dimension of a tensor into a set
/// of prefix trees. Each path from a root to leaf forms one tensor
/// non-zero index. CSF is implemented with two arrays of buffers and one
- /// arrays of integers.
+ /// array of integers.
///
/// For example, let X be a 2x3x4x5 tensor and let it have the following
/// 8 non-zero values:
@@ -165,7 +165,7 @@ table SparseTensorIndexCSF {
/// and `indptrBuffers[dim][i + 1]` signify a range of nodes in
/// `indicesBuffers[dim + 1]` who are children of `indicesBuffers[dim][i]` node.
///
- /// For example, the indptrBuffers for the above X is:
+ /// For example, the indptrBuffers for the above X are:
/// ```text
/// indptrBuffer(X) = [
/// [0, 2, 3],
@@ -180,7 +180,7 @@ table SparseTensorIndexCSF {
/// indicesBuffers stores values of nodes.
/// Each tensor dimension corresponds to a buffer in indicesBuffers.
- /// For example, the indicesBuffers for the above X is:
+ /// For example, the indicesBuffers for the above X are:
/// ```text
/// indicesBuffer(X) = [
/// [0, 1],
@@ -206,6 +206,11 @@ union SparseTensorIndex {
SparseTensorIndexCSF
}
+/// DEPRECATED. Unlike dense tensors (see Tensor.fbs), the SparseTensor message
+/// currently doesn't have a recommended replacement as a RecordBatch column type.
+/// Feel free to discuss this on the development mailing-list (*) if this use case
+/// is important to you.
+/// (*) see <https://arrow.apache.org/community/>
table SparseTensor {
/// The type of data contained in a value cell.
/// Currently only fixed-width value types are supported,
diff --git a/format/Tensor.fbs b/format/Tensor.fbs
index 409297ccf8..cd7952281f 100644
--- a/format/Tensor.fbs
+++ b/format/Tensor.fbs
@@ -15,7 +15,7 @@
// specific language governing permissions and limitations
// under the License.
-/// EXPERIMENTAL: Metadata for n-dimensional arrays, aka "tensors" or
+/// DEPRECATED: Metadata for n-dimensional arrays, aka "tensors" or
/// "ndarrays". Arrow implementations in general are not required to implement
/// this type
@@ -35,6 +35,8 @@ table TensorDim {
name: string;
}
+/// DEPRECATED: The recommended way to pass tensors over Arrow IPC is
+/// using columns with the `arrow.fixed_shape_tensor` canonical type.
table Tensor {
/// The type of data contained in a value cell. Currently only fixed-width
/// value types are supported, no strings or nested types