Arrow Flight SQL

Arrow Flight SQL is a protocol for interacting with SQL databases using the Arrow in-memory format and the Flight RPC framework.

Generally, a database will implement the RPC methods according to the specification, but does not need to implement a client-side driver. A database client can use the provided Flight SQL client to interact with any database that supports the necessary endpoints. Flight SQL clients wrap the underlying Flight client to provide methods for the new RPC methods described here.

Warning

Flight SQL is experimental and changes to the protocol may still be made.

RPC Methods

Flight SQL reuses the predefined RPC methods in Arrow Flight, and provides various commands that pair those methods with request/response messages defined via Protobuf (see below).

SQL Metadata

Flight SQL provides a variety of commands to fetch catalog metadata about the database server.

All of these commands can be used with the GetFlightInfo and GetSchema RPC methods. The Protobuf request message should be packed into a google.protobuf.Any message, then serialized and packed as the cmd field in a CMD-type FlightDescriptor.

If the command is used with GetFlightInfo, the server will return a FlightInfo response. The client should then use the Ticket(s) in the FlightInfo with the DoGet RPC method to fetch a Arrow data containing the results of the command. In other words, SQL metadata is returned as Arrow data, just like query results themselves.

The Arrow schema returned by GetSchema or DoGet for a particular command is fixed according to the specification.

CommandGetCatalogs

List the catalogs available in the database. The definition varies by vendor.

CommandGetCrossReference

List the foreign key columns in a given table that reference columns in a given parent table.

CommandGetDbSchemas

List the schemas (note: a grouping of tables, not an Arrow schema) available in the database. The definition varies by vendor.

CommandGetExportedKeys

List foreign key columns that reference the primary key columns of a given table.

CommandGetImportedKeys

List foreign keys of a given table.

CommandGetPrimaryKeys

List the primary keys of a given table.

CommandGetSqlInfo

Fetch metadata about the database server and its supported SQL features.

CommandGetTables

List tables in the database.

CommandGetTableTypes

List table types in the database. The list of types varies by vendor.

Query Execution

Flight SQL also provides commands to execute SQL queries and manage prepared statements.

Many of these commands are also used with GetFlightInfo/GetSchema and work identically to the metadata methods above. Some of these commands can be used with the DoPut RPC method, but the command should still be encoded in the request FlightDescriptor in the same way.

Commands beginning with “Action” are instead used with the DoAction RPC method, in which case the command should be packed into a google.protobuf.Any message, then serialized and packed into the body of a Flight Action. Also, the action type should be set to the command name (i.e. for ActionClosePreparedStatementRequest, the type should be ClosePreparedStatement).

ActionClosePreparedStatementRequest

Close a previously created prepared statement.

ActionCreatePreparedStatementRequest

Create a new prepared statement for a SQL query.

CommandPreparedStatementQuery

Execute a previously created prepared statement and get the results.

When used with DoPut: binds parameter values to the prepared statement.

When used with GetFlightInfo: execute the prepared statement. The prepared statement can be reused after fetching results.

CommandPreparedStatementUpdate

Execute a previously created prepared statement that does not return results.

When used with DoPut: execute the query and return the number of affected rows. The prepared statement can be reused afterwards.

CommandStatementQuery

Execute an ad-hoc SQL query.

When used with GetFlightInfo: execute the query (call DoGet to fetch results).

When used with GetSchema: return the schema of the query results.

CommandStatementUpdate

Execute an ad-hoc SQL query that does not return results.

When used with DoPut: execute the query and return the number of affected rows.

Sequence Diagrams

../_images/CommandGetTables.mmd.svg

Listing available tables.

../_images/CommandStatementQuery.mmd.svg

Executing an ad-hoc query.

../_images/CommandPreparedStatementQuery.mmd.svg

Creating a prepared statement, then executing it.

External Resources

Protocol Buffer Definitions

   1/*
   2 * Licensed to the Apache Software Foundation (ASF) under one
   3 * or more contributor license agreements.  See the NOTICE file
   4 * distributed with this work for additional information
   5 * regarding copyright ownership.  The ASF licenses this file
   6 * to you under the Apache License, Version 2.0 (the
   7 * "License"); you may not use this file except in compliance
   8 * with the License.  You may obtain a copy of the License at
   9 * <p>
  10 * http://www.apache.org/licenses/LICENSE-2.0
  11 * <p>
  12 * Unless required by applicable law or agreed to in writing, software
  13 * distributed under the License is distributed on an "AS IS" BASIS,
  14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15 * See the License for the specific language governing permissions and
  16 * limitations under the License.
  17 */
  18
  19syntax = "proto3";
  20import "google/protobuf/descriptor.proto";
  21
  22option java_package = "org.apache.arrow.flight.sql.impl";
  23option go_package = "github.com/apache/arrow/go/arrow/flight/internal/flight";
  24package arrow.flight.protocol.sql;
  25
  26/*
  27 * Represents a metadata request. Used in the command member of FlightDescriptor
  28 * for the following RPC calls:
  29 *  - GetSchema: return the Arrow schema of the query.
  30 *  - GetFlightInfo: execute the metadata request.
  31 *
  32 * The returned Arrow schema will be:
  33 * <
  34 *  info_name: uint32 not null,
  35 *  value: dense_union<
  36 *              string_value: utf8,
  37 *              bool_value: bool,
  38 *              bigint_value: int64,
  39 *              int32_bitmask: int32,
  40 *              string_list: list<string_data: utf8>
  41 *              int32_to_int32_list_map: map<key: int32, value: list<$data$: int32>>
  42 * >
  43 * where there is one row per requested piece of metadata information.
  44 */
  45message CommandGetSqlInfo {
  46  option (experimental) = true;
  47
  48  /*
  49   * Values are modelled after ODBC's SQLGetInfo() function. This information is intended to provide
  50   * Flight SQL clients with basic, SQL syntax and SQL functions related information.
  51   * More information types can be added in future releases.
  52   * E.g. more SQL syntax support types, scalar functions support, type conversion support etc.
  53   *
  54   * Note that the set of metadata may expand.
  55   *
  56   * Initially, Flight SQL will support the following information types:
  57   * - Server Information - Range [0-500)
  58   * - Syntax Information - Range [500-1000)
  59   * Range [0-10,000) is reserved for defaults (see SqlInfo enum for default options).
  60   * Custom options should start at 10,000.
  61   *
  62   * If omitted, then all metadata will be retrieved.
  63   * Flight SQL Servers may choose to include additional metadata above and beyond the specified set, however they must
  64   * at least return the specified set. IDs ranging from 0 to 10,000 (exclusive) are reserved for future use.
  65   * If additional metadata is included, the metadata IDs should start from 10,000.
  66   */
  67  repeated uint32 info = 1;
  68}
  69
  70// Options for CommandGetSqlInfo.
  71enum SqlInfo {
  72
  73  // Server Information [0-500): Provides basic information about the Flight SQL Server.
  74
  75  // Retrieves a UTF-8 string with the name of the Flight SQL Server.
  76  FLIGHT_SQL_SERVER_NAME = 0;
  77
  78  // Retrieves a UTF-8 string with the native version of the Flight SQL Server.
  79  FLIGHT_SQL_SERVER_VERSION = 1;
  80
  81  // Retrieves a UTF-8 string with the Arrow format version of the Flight SQL Server.
  82  FLIGHT_SQL_SERVER_ARROW_VERSION = 2;
  83
  84  /*
  85   * Retrieves a boolean value indicating whether the Flight SQL Server is read only.
  86   *
  87   * Returns:
  88   * - false: if read-write
  89   * - true: if read only
  90   */
  91  FLIGHT_SQL_SERVER_READ_ONLY = 3;
  92
  93  /*
  94   * Retrieves a boolean value indicating whether the Flight SQL Server supports executing
  95   * SQL queries.
  96   *
  97   * Note that the absence of this info (as opposed to a false value) does not necessarily
  98   * mean that SQL is not supported, as this property was not originally defined.
  99   */
 100  FLIGHT_SQL_SERVER_SQL = 4;
 101
 102  /*
 103   * Retrieves a boolean value indicating whether the Flight SQL Server supports executing
 104   * Substrait plans.
 105   */
 106  FLIGHT_SQL_SERVER_SUBSTRAIT = 5;
 107
 108  /*
 109   * Retrieves a string value indicating the minimum supported Substrait version, or null
 110   * if Substrait is not supported.
 111   */
 112  FLIGHT_SQL_SERVER_SUBSTRAIT_MIN_VERSION = 6;
 113
 114  /*
 115   * Retrieves a string value indicating the maximum supported Substrait version, or null
 116   * if Substrait is not supported.
 117   */
 118  FLIGHT_SQL_SERVER_SUBSTRAIT_MAX_VERSION = 7;
 119
 120  /*
 121   * Retrieves an int32 indicating whether the Flight SQL Server supports the
 122   * BeginTransaction/EndTransaction/BeginSavepoint/EndSavepoint actions.
 123   *
 124   * Even if this is not supported, the database may still support explicit "BEGIN
 125   * TRANSACTION"/"COMMIT" SQL statements (see SQL_TRANSACTIONS_SUPPORTED); this property
 126   * is only about whether the server implements the Flight SQL API endpoints.
 127   *
 128   * The possible values are listed in `SqlSupportedTransaction`.
 129   */
 130  FLIGHT_SQL_SERVER_TRANSACTION = 8;
 131
 132  /*
 133   * Retrieves a boolean value indicating whether the Flight SQL Server supports explicit
 134   * query cancellation (the CancelQuery action).
 135   */
 136  FLIGHT_SQL_SERVER_CANCEL = 9;
 137
 138  /*
 139   * Retrieves an int32 indicating the timeout (in milliseconds) for prepared statement handles.
 140   *
 141   * If 0, there is no timeout.  Servers should reset the timeout when the handle is used in a command.
 142   */
 143  FLIGHT_SQL_SERVER_STATEMENT_TIMEOUT = 100;
 144
 145  /*
 146   * Retrieves an int32 indicating the timeout (in milliseconds) for transactions, since transactions are not tied to a connection.
 147   *
 148   * If 0, there is no timeout.  Servers should reset the timeout when the handle is used in a command.
 149   */
 150  FLIGHT_SQL_SERVER_TRANSACTION_TIMEOUT = 101;
 151
 152  // SQL Syntax Information [500-1000): provides information about SQL syntax supported by the Flight SQL Server.
 153
 154  /*
 155   * Retrieves a boolean value indicating whether the Flight SQL Server supports CREATE and DROP of catalogs.
 156   *
 157   * Returns:
 158   * - false: if it doesn't support CREATE and DROP of catalogs.
 159   * - true: if it supports CREATE and DROP of catalogs.
 160   */
 161  SQL_DDL_CATALOG = 500;
 162
 163  /*
 164   * Retrieves a boolean value indicating whether the Flight SQL Server supports CREATE and DROP of schemas.
 165   *
 166   * Returns:
 167   * - false: if it doesn't support CREATE and DROP of schemas.
 168   * - true: if it supports CREATE and DROP of schemas.
 169   */
 170  SQL_DDL_SCHEMA = 501;
 171
 172  /*
 173   * Indicates whether the Flight SQL Server supports CREATE and DROP of tables.
 174   *
 175   * Returns:
 176   * - false: if it doesn't support CREATE and DROP of tables.
 177   * - true: if it supports CREATE and DROP of tables.
 178   */
 179  SQL_DDL_TABLE = 502;
 180
 181  /*
 182   * Retrieves a int32 ordinal representing the case sensitivity of catalog, table, schema and table names.
 183   *
 184   * The possible values are listed in `arrow.flight.protocol.sql.SqlSupportedCaseSensitivity`.
 185   */
 186  SQL_IDENTIFIER_CASE = 503;
 187
 188  // Retrieves a UTF-8 string with the supported character(s) used to surround a delimited identifier.
 189  SQL_IDENTIFIER_QUOTE_CHAR = 504;
 190
 191  /*
 192   * Retrieves a int32 describing the case sensitivity of quoted identifiers.
 193   *
 194   * The possible values are listed in `arrow.flight.protocol.sql.SqlSupportedCaseSensitivity`.
 195   */
 196  SQL_QUOTED_IDENTIFIER_CASE = 505;
 197
 198  /*
 199   * Retrieves a boolean value indicating whether all tables are selectable.
 200   *
 201   * Returns:
 202   * - false: if not all tables are selectable or if none are;
 203   * - true: if all tables are selectable.
 204   */
 205  SQL_ALL_TABLES_ARE_SELECTABLE = 506;
 206
 207  /*
 208   * Retrieves the null ordering.
 209   *
 210   * Returns a int32 ordinal for the null ordering being used, as described in
 211   * `arrow.flight.protocol.sql.SqlNullOrdering`.
 212   */
 213  SQL_NULL_ORDERING = 507;
 214
 215  // Retrieves a UTF-8 string list with values of the supported keywords.
 216  SQL_KEYWORDS = 508;
 217
 218  // Retrieves a UTF-8 string list with values of the supported numeric functions.
 219  SQL_NUMERIC_FUNCTIONS = 509;
 220
 221  // Retrieves a UTF-8 string list with values of the supported string functions.
 222  SQL_STRING_FUNCTIONS = 510;
 223
 224  // Retrieves a UTF-8 string list with values of the supported system functions.
 225  SQL_SYSTEM_FUNCTIONS = 511;
 226
 227  // Retrieves a UTF-8 string list with values of the supported datetime functions.
 228  SQL_DATETIME_FUNCTIONS = 512;
 229
 230  /*
 231   * Retrieves the UTF-8 string that can be used to escape wildcard characters.
 232   * This is the string that can be used to escape '_' or '%' in the catalog search parameters that are a pattern
 233   * (and therefore use one of the wildcard characters).
 234   * The '_' character represents any single character; the '%' character represents any sequence of zero or more
 235   * characters.
 236   */
 237  SQL_SEARCH_STRING_ESCAPE = 513;
 238
 239  /*
 240   * Retrieves a UTF-8 string with all the "extra" characters that can be used in unquoted identifier names
 241   * (those beyond a-z, A-Z, 0-9 and _).
 242   */
 243  SQL_EXTRA_NAME_CHARACTERS = 514;
 244
 245  /*
 246   * Retrieves a boolean value indicating whether column aliasing is supported.
 247   * If so, the SQL AS clause can be used to provide names for computed columns or to provide alias names for columns
 248   * as required.
 249   *
 250   * Returns:
 251   * - false: if column aliasing is unsupported;
 252   * - true: if column aliasing is supported.
 253   */
 254  SQL_SUPPORTS_COLUMN_ALIASING = 515;
 255
 256  /*
 257   * Retrieves a boolean value indicating whether concatenations between null and non-null values being
 258   * null are supported.
 259   *
 260   * - Returns:
 261   * - false: if concatenations between null and non-null values being null are unsupported;
 262   * - true: if concatenations between null and non-null values being null are supported.
 263   */
 264  SQL_NULL_PLUS_NULL_IS_NULL = 516;
 265
 266  /*
 267   * Retrieves a map where the key is the type to convert from and the value is a list with the types to convert to,
 268   * indicating the supported conversions. Each key and each item on the list value is a value to a predefined type on
 269   * SqlSupportsConvert enum.
 270   * The returned map will be:  map<int32, list<int32>>
 271   */
 272  SQL_SUPPORTS_CONVERT = 517;
 273
 274  /*
 275   * Retrieves a boolean value indicating whether, when table correlation names are supported,
 276   * they are restricted to being different from the names of the tables.
 277   *
 278   * Returns:
 279   * - false: if table correlation names are unsupported;
 280   * - true: if table correlation names are supported.
 281   */
 282  SQL_SUPPORTS_TABLE_CORRELATION_NAMES = 518;
 283
 284  /*
 285   * Retrieves a boolean value indicating whether, when table correlation names are supported,
 286   * they are restricted to being different from the names of the tables.
 287   *
 288   * Returns:
 289   * - false: if different table correlation names are unsupported;
 290   * - true: if different table correlation names are supported
 291   */
 292  SQL_SUPPORTS_DIFFERENT_TABLE_CORRELATION_NAMES = 519;
 293
 294  /*
 295   * Retrieves a boolean value indicating whether expressions in ORDER BY lists are supported.
 296   *
 297   * Returns:
 298   * - false: if expressions in ORDER BY are unsupported;
 299   * - true: if expressions in ORDER BY are supported;
 300   */
 301  SQL_SUPPORTS_EXPRESSIONS_IN_ORDER_BY = 520;
 302
 303  /*
 304   * Retrieves a boolean value indicating whether using a column that is not in the SELECT statement in a GROUP BY
 305   * clause is supported.
 306   *
 307   * Returns:
 308   * - false: if using a column that is not in the SELECT statement in a GROUP BY clause is unsupported;
 309   * - true: if using a column that is not in the SELECT statement in a GROUP BY clause is supported.
 310   */
 311  SQL_SUPPORTS_ORDER_BY_UNRELATED = 521;
 312
 313  /*
 314   * Retrieves the supported GROUP BY commands;
 315   *
 316   * Returns an int32 bitmask value representing the supported commands.
 317   * The returned bitmask should be parsed in order to retrieve the supported commands.
 318   *
 319   * For instance:
 320   * - return 0 (\b0)   => [] (GROUP BY is unsupported);
 321   * - return 1 (\b1)   => [SQL_GROUP_BY_UNRELATED];
 322   * - return 2 (\b10)  => [SQL_GROUP_BY_BEYOND_SELECT];
 323   * - return 3 (\b11)  => [SQL_GROUP_BY_UNRELATED, SQL_GROUP_BY_BEYOND_SELECT].
 324   * Valid GROUP BY types are described under `arrow.flight.protocol.sql.SqlSupportedGroupBy`.
 325   */
 326  SQL_SUPPORTED_GROUP_BY = 522;
 327
 328  /*
 329   * Retrieves a boolean value indicating whether specifying a LIKE escape clause is supported.
 330   *
 331   * Returns:
 332   * - false: if specifying a LIKE escape clause is unsupported;
 333   * - true: if specifying a LIKE escape clause is supported.
 334   */
 335  SQL_SUPPORTS_LIKE_ESCAPE_CLAUSE = 523;
 336
 337  /*
 338   * Retrieves a boolean value indicating whether columns may be defined as non-nullable.
 339   *
 340   * Returns:
 341   * - false: if columns cannot be defined as non-nullable;
 342   * - true: if columns may be defined as non-nullable.
 343   */
 344  SQL_SUPPORTS_NON_NULLABLE_COLUMNS = 524;
 345
 346  /*
 347   * Retrieves the supported SQL grammar level as per the ODBC specification.
 348   *
 349   * Returns an int32 bitmask value representing the supported SQL grammar level.
 350   * The returned bitmask should be parsed in order to retrieve the supported grammar levels.
 351   *
 352   * For instance:
 353   * - return 0 (\b0)   => [] (SQL grammar is unsupported);
 354   * - return 1 (\b1)   => [SQL_MINIMUM_GRAMMAR];
 355   * - return 2 (\b10)  => [SQL_CORE_GRAMMAR];
 356   * - return 3 (\b11)  => [SQL_MINIMUM_GRAMMAR, SQL_CORE_GRAMMAR];
 357   * - return 4 (\b100) => [SQL_EXTENDED_GRAMMAR];
 358   * - return 5 (\b101) => [SQL_MINIMUM_GRAMMAR, SQL_EXTENDED_GRAMMAR];
 359   * - return 6 (\b110) => [SQL_CORE_GRAMMAR, SQL_EXTENDED_GRAMMAR];
 360   * - return 7 (\b111) => [SQL_MINIMUM_GRAMMAR, SQL_CORE_GRAMMAR, SQL_EXTENDED_GRAMMAR].
 361   * Valid SQL grammar levels are described under `arrow.flight.protocol.sql.SupportedSqlGrammar`.
 362   */
 363  SQL_SUPPORTED_GRAMMAR = 525;
 364
 365  /*
 366   * Retrieves the supported ANSI92 SQL grammar level.
 367   *
 368   * Returns an int32 bitmask value representing the supported ANSI92 SQL grammar level.
 369   * The returned bitmask should be parsed in order to retrieve the supported commands.
 370   *
 371   * For instance:
 372   * - return 0 (\b0)   => [] (ANSI92 SQL grammar is unsupported);
 373   * - return 1 (\b1)   => [ANSI92_ENTRY_SQL];
 374   * - return 2 (\b10)  => [ANSI92_INTERMEDIATE_SQL];
 375   * - return 3 (\b11)  => [ANSI92_ENTRY_SQL, ANSI92_INTERMEDIATE_SQL];
 376   * - return 4 (\b100) => [ANSI92_FULL_SQL];
 377   * - return 5 (\b101) => [ANSI92_ENTRY_SQL, ANSI92_FULL_SQL];
 378   * - return 6 (\b110) => [ANSI92_INTERMEDIATE_SQL, ANSI92_FULL_SQL];
 379   * - return 7 (\b111) => [ANSI92_ENTRY_SQL, ANSI92_INTERMEDIATE_SQL, ANSI92_FULL_SQL].
 380   * Valid ANSI92 SQL grammar levels are described under `arrow.flight.protocol.sql.SupportedAnsi92SqlGrammarLevel`.
 381   */
 382  SQL_ANSI92_SUPPORTED_LEVEL = 526;
 383
 384  /*
 385   * Retrieves a boolean value indicating whether the SQL Integrity Enhancement Facility is supported.
 386   *
 387   * Returns:
 388   * - false: if the SQL Integrity Enhancement Facility is supported;
 389   * - true: if the SQL Integrity Enhancement Facility is supported.
 390   */
 391  SQL_SUPPORTS_INTEGRITY_ENHANCEMENT_FACILITY = 527;
 392
 393  /*
 394   * Retrieves the support level for SQL OUTER JOINs.
 395   *
 396   * Returns a int32 ordinal for the SQL ordering being used, as described in
 397   * `arrow.flight.protocol.sql.SqlOuterJoinsSupportLevel`.
 398   */
 399  SQL_OUTER_JOINS_SUPPORT_LEVEL = 528;
 400
 401  // Retrieves a UTF-8 string with the preferred term for "schema".
 402  SQL_SCHEMA_TERM = 529;
 403
 404  // Retrieves a UTF-8 string with the preferred term for "procedure".
 405  SQL_PROCEDURE_TERM = 530;
 406
 407  /*
 408   * Retrieves a UTF-8 string with the preferred term for "catalog".
 409   * If a empty string is returned its assumed that the server does NOT supports catalogs.
 410   */
 411  SQL_CATALOG_TERM = 531;
 412
 413  /*
 414   * Retrieves a boolean value indicating whether a catalog appears at the start of a fully qualified table name.
 415   *
 416   * - false: if a catalog does not appear at the start of a fully qualified table name;
 417   * - true: if a catalog appears at the start of a fully qualified table name.
 418   */
 419  SQL_CATALOG_AT_START = 532;
 420
 421  /*
 422   * Retrieves the supported actions for a SQL schema.
 423   *
 424   * Returns an int32 bitmask value representing the supported actions for a SQL schema.
 425   * The returned bitmask should be parsed in order to retrieve the supported actions for a SQL schema.
 426   *
 427   * For instance:
 428   * - return 0 (\b0)   => [] (no supported actions for SQL schema);
 429   * - return 1 (\b1)   => [SQL_ELEMENT_IN_PROCEDURE_CALLS];
 430   * - return 2 (\b10)  => [SQL_ELEMENT_IN_INDEX_DEFINITIONS];
 431   * - return 3 (\b11)  => [SQL_ELEMENT_IN_PROCEDURE_CALLS, SQL_ELEMENT_IN_INDEX_DEFINITIONS];
 432   * - return 4 (\b100) => [SQL_ELEMENT_IN_PRIVILEGE_DEFINITIONS];
 433   * - return 5 (\b101) => [SQL_ELEMENT_IN_PROCEDURE_CALLS, SQL_ELEMENT_IN_PRIVILEGE_DEFINITIONS];
 434   * - return 6 (\b110) => [SQL_ELEMENT_IN_INDEX_DEFINITIONS, SQL_ELEMENT_IN_PRIVILEGE_DEFINITIONS];
 435   * - return 7 (\b111) => [SQL_ELEMENT_IN_PROCEDURE_CALLS, SQL_ELEMENT_IN_INDEX_DEFINITIONS, SQL_ELEMENT_IN_PRIVILEGE_DEFINITIONS].
 436   * Valid actions for a SQL schema described under `arrow.flight.protocol.sql.SqlSupportedElementActions`.
 437   */
 438  SQL_SCHEMAS_SUPPORTED_ACTIONS = 533;
 439
 440  /*
 441   * Retrieves the supported actions for a SQL schema.
 442   *
 443   * Returns an int32 bitmask value representing the supported actions for a SQL catalog.
 444   * The returned bitmask should be parsed in order to retrieve the supported actions for a SQL catalog.
 445   *
 446   * For instance:
 447   * - return 0 (\b0)   => [] (no supported actions for SQL catalog);
 448   * - return 1 (\b1)   => [SQL_ELEMENT_IN_PROCEDURE_CALLS];
 449   * - return 2 (\b10)  => [SQL_ELEMENT_IN_INDEX_DEFINITIONS];
 450   * - return 3 (\b11)  => [SQL_ELEMENT_IN_PROCEDURE_CALLS, SQL_ELEMENT_IN_INDEX_DEFINITIONS];
 451   * - return 4 (\b100) => [SQL_ELEMENT_IN_PRIVILEGE_DEFINITIONS];
 452   * - return 5 (\b101) => [SQL_ELEMENT_IN_PROCEDURE_CALLS, SQL_ELEMENT_IN_PRIVILEGE_DEFINITIONS];
 453   * - return 6 (\b110) => [SQL_ELEMENT_IN_INDEX_DEFINITIONS, SQL_ELEMENT_IN_PRIVILEGE_DEFINITIONS];
 454   * - return 7 (\b111) => [SQL_ELEMENT_IN_PROCEDURE_CALLS, SQL_ELEMENT_IN_INDEX_DEFINITIONS, SQL_ELEMENT_IN_PRIVILEGE_DEFINITIONS].
 455   * Valid actions for a SQL catalog are described under `arrow.flight.protocol.sql.SqlSupportedElementActions`.
 456   */
 457  SQL_CATALOGS_SUPPORTED_ACTIONS = 534;
 458
 459  /*
 460   * Retrieves the supported SQL positioned commands.
 461   *
 462   * Returns an int32 bitmask value representing the supported SQL positioned commands.
 463   * The returned bitmask should be parsed in order to retrieve the supported SQL positioned commands.
 464   *
 465   * For instance:
 466   * - return 0 (\b0)   => [] (no supported SQL positioned commands);
 467   * - return 1 (\b1)   => [SQL_POSITIONED_DELETE];
 468   * - return 2 (\b10)  => [SQL_POSITIONED_UPDATE];
 469   * - return 3 (\b11)  => [SQL_POSITIONED_DELETE, SQL_POSITIONED_UPDATE].
 470   * Valid SQL positioned commands are described under `arrow.flight.protocol.sql.SqlSupportedPositionedCommands`.
 471   */
 472  SQL_SUPPORTED_POSITIONED_COMMANDS = 535;
 473
 474  /*
 475   * Retrieves a boolean value indicating whether SELECT FOR UPDATE statements are supported.
 476   *
 477   * Returns:
 478   * - false: if SELECT FOR UPDATE statements are unsupported;
 479   * - true: if SELECT FOR UPDATE statements are supported.
 480   */
 481  SQL_SELECT_FOR_UPDATE_SUPPORTED = 536;
 482
 483  /*
 484   * Retrieves a boolean value indicating whether stored procedure calls that use the stored procedure escape syntax
 485   * are supported.
 486   *
 487   * Returns:
 488   * - false: if stored procedure calls that use the stored procedure escape syntax are unsupported;
 489   * - true: if stored procedure calls that use the stored procedure escape syntax are supported.
 490   */
 491  SQL_STORED_PROCEDURES_SUPPORTED = 537;
 492
 493  /*
 494   * Retrieves the supported SQL subqueries.
 495   *
 496   * Returns an int32 bitmask value representing the supported SQL subqueries.
 497   * The returned bitmask should be parsed in order to retrieve the supported SQL subqueries.
 498   *
 499   * For instance:
 500   * - return 0   (\b0)     => [] (no supported SQL subqueries);
 501   * - return 1   (\b1)     => [SQL_SUBQUERIES_IN_COMPARISONS];
 502   * - return 2   (\b10)    => [SQL_SUBQUERIES_IN_EXISTS];
 503   * - return 3   (\b11)    => [SQL_SUBQUERIES_IN_COMPARISONS, SQL_SUBQUERIES_IN_EXISTS];
 504   * - return 4   (\b100)   => [SQL_SUBQUERIES_IN_INS];
 505   * - return 5   (\b101)   => [SQL_SUBQUERIES_IN_COMPARISONS, SQL_SUBQUERIES_IN_INS];
 506   * - return 6   (\b110)   => [SQL_SUBQUERIES_IN_INS, SQL_SUBQUERIES_IN_EXISTS];
 507   * - return 7   (\b111)   => [SQL_SUBQUERIES_IN_COMPARISONS, SQL_SUBQUERIES_IN_EXISTS, SQL_SUBQUERIES_IN_INS];
 508   * - return 8   (\b1000)  => [SQL_SUBQUERIES_IN_QUANTIFIEDS];
 509   * - return 9   (\b1001)  => [SQL_SUBQUERIES_IN_COMPARISONS, SQL_SUBQUERIES_IN_QUANTIFIEDS];
 510   * - return 10  (\b1010)  => [SQL_SUBQUERIES_IN_EXISTS, SQL_SUBQUERIES_IN_QUANTIFIEDS];
 511   * - return 11  (\b1011)  => [SQL_SUBQUERIES_IN_COMPARISONS, SQL_SUBQUERIES_IN_EXISTS, SQL_SUBQUERIES_IN_QUANTIFIEDS];
 512   * - return 12  (\b1100)  => [SQL_SUBQUERIES_IN_INS, SQL_SUBQUERIES_IN_QUANTIFIEDS];
 513   * - return 13  (\b1101)  => [SQL_SUBQUERIES_IN_COMPARISONS, SQL_SUBQUERIES_IN_INS, SQL_SUBQUERIES_IN_QUANTIFIEDS];
 514   * - return 14  (\b1110)  => [SQL_SUBQUERIES_IN_EXISTS, SQL_SUBQUERIES_IN_INS, SQL_SUBQUERIES_IN_QUANTIFIEDS];
 515   * - return 15  (\b1111)  => [SQL_SUBQUERIES_IN_COMPARISONS, SQL_SUBQUERIES_IN_EXISTS, SQL_SUBQUERIES_IN_INS, SQL_SUBQUERIES_IN_QUANTIFIEDS];
 516   * - ...
 517   * Valid SQL subqueries are described under `arrow.flight.protocol.sql.SqlSupportedSubqueries`.
 518   */
 519  SQL_SUPPORTED_SUBQUERIES = 538;
 520
 521  /*
 522   * Retrieves a boolean value indicating whether correlated subqueries are supported.
 523   *
 524   * Returns:
 525   * - false: if correlated subqueries are unsupported;
 526   * - true: if correlated subqueries are supported.
 527   */
 528  SQL_CORRELATED_SUBQUERIES_SUPPORTED = 539;
 529
 530  /*
 531   * Retrieves the supported SQL UNIONs.
 532   *
 533   * Returns an int32 bitmask value representing the supported SQL UNIONs.
 534   * The returned bitmask should be parsed in order to retrieve the supported SQL UNIONs.
 535   *
 536   * For instance:
 537   * - return 0 (\b0)   => [] (no supported SQL positioned commands);
 538   * - return 1 (\b1)   => [SQL_UNION];
 539   * - return 2 (\b10)  => [SQL_UNION_ALL];
 540   * - return 3 (\b11)  => [SQL_UNION, SQL_UNION_ALL].
 541   * Valid SQL positioned commands are described under `arrow.flight.protocol.sql.SqlSupportedUnions`.
 542   */
 543  SQL_SUPPORTED_UNIONS = 540;
 544
 545  // Retrieves a int64 value representing the maximum number of hex characters allowed in an inline binary literal.
 546  SQL_MAX_BINARY_LITERAL_LENGTH = 541;
 547
 548  // Retrieves a int64 value representing the maximum number of characters allowed for a character literal.
 549  SQL_MAX_CHAR_LITERAL_LENGTH = 542;
 550
 551  // Retrieves a int64 value representing the maximum number of characters allowed for a column name.
 552  SQL_MAX_COLUMN_NAME_LENGTH = 543;
 553
 554  // Retrieves a int64 value representing the the maximum number of columns allowed in a GROUP BY clause.
 555  SQL_MAX_COLUMNS_IN_GROUP_BY = 544;
 556
 557  // Retrieves a int64 value representing the maximum number of columns allowed in an index.
 558  SQL_MAX_COLUMNS_IN_INDEX = 545;
 559
 560  // Retrieves a int64 value representing the maximum number of columns allowed in an ORDER BY clause.
 561  SQL_MAX_COLUMNS_IN_ORDER_BY = 546;
 562
 563  // Retrieves a int64 value representing the maximum number of columns allowed in a SELECT list.
 564  SQL_MAX_COLUMNS_IN_SELECT = 547;
 565
 566  // Retrieves a int64 value representing the maximum number of columns allowed in a table.
 567  SQL_MAX_COLUMNS_IN_TABLE = 548;
 568
 569  // Retrieves a int64 value representing the maximum number of concurrent connections possible.
 570  SQL_MAX_CONNECTIONS = 549;
 571
 572  // Retrieves a int64 value the maximum number of characters allowed in a cursor name.
 573  SQL_MAX_CURSOR_NAME_LENGTH = 550;
 574
 575  /*
 576   * Retrieves a int64 value representing the maximum number of bytes allowed for an index,
 577   * including all of the parts of the index.
 578   */
 579  SQL_MAX_INDEX_LENGTH = 551;
 580
 581  // Retrieves a int64 value representing the maximum number of characters allowed in a schema name.
 582  SQL_DB_SCHEMA_NAME_LENGTH = 552;
 583
 584  // Retrieves a int64 value representing the maximum number of characters allowed in a procedure name.
 585  SQL_MAX_PROCEDURE_NAME_LENGTH = 553;
 586
 587  // Retrieves a int64 value representing the maximum number of characters allowed in a catalog name.
 588  SQL_MAX_CATALOG_NAME_LENGTH = 554;
 589
 590  // Retrieves a int64 value representing the maximum number of bytes allowed in a single row.
 591  SQL_MAX_ROW_SIZE = 555;
 592
 593  /*
 594   * Retrieves a boolean indicating whether the return value for the JDBC method getMaxRowSize includes the SQL
 595   * data types LONGVARCHAR and LONGVARBINARY.
 596   *
 597   * Returns:
 598   * - false: if return value for the JDBC method getMaxRowSize does
 599   *          not include the SQL data types LONGVARCHAR and LONGVARBINARY;
 600   * - true: if return value for the JDBC method getMaxRowSize includes
 601   *         the SQL data types LONGVARCHAR and LONGVARBINARY.
 602   */
 603  SQL_MAX_ROW_SIZE_INCLUDES_BLOBS = 556;
 604
 605  /*
 606   * Retrieves a int64 value representing the maximum number of characters allowed for an SQL statement;
 607   * a result of 0 (zero) means that there is no limit or the limit is not known.
 608   */
 609  SQL_MAX_STATEMENT_LENGTH = 557;
 610
 611  // Retrieves a int64 value representing the maximum number of active statements that can be open at the same time.
 612  SQL_MAX_STATEMENTS = 558;
 613
 614  // Retrieves a int64 value representing the maximum number of characters allowed in a table name.
 615  SQL_MAX_TABLE_NAME_LENGTH = 559;
 616
 617  // Retrieves a int64 value representing the maximum number of tables allowed in a SELECT statement.
 618  SQL_MAX_TABLES_IN_SELECT = 560;
 619
 620  // Retrieves a int64 value representing the maximum number of characters allowed in a user name.
 621  SQL_MAX_USERNAME_LENGTH = 561;
 622
 623  /*
 624   * Retrieves this database's default transaction isolation level as described in
 625   * `arrow.flight.protocol.sql.SqlTransactionIsolationLevel`.
 626   *
 627   * Returns a int32 ordinal for the SQL transaction isolation level.
 628   */
 629  SQL_DEFAULT_TRANSACTION_ISOLATION = 562;
 630
 631  /*
 632   * Retrieves a boolean value indicating whether transactions are supported. If not, invoking the method commit is a
 633   * noop, and the isolation level is `arrow.flight.protocol.sql.SqlTransactionIsolationLevel.TRANSACTION_NONE`.
 634   *
 635   * Returns:
 636   * - false: if transactions are unsupported;
 637   * - true: if transactions are supported.
 638   */
 639  SQL_TRANSACTIONS_SUPPORTED = 563;
 640
 641  /*
 642   * Retrieves the supported transactions isolation levels.
 643   *
 644   * Returns an int32 bitmask value representing the supported transactions isolation levels.
 645   * The returned bitmask should be parsed in order to retrieve the supported transactions isolation levels.
 646   *
 647   * For instance:
 648   * - return 0   (\b0)     => [] (no supported SQL transactions isolation levels);
 649   * - return 1   (\b1)     => [SQL_TRANSACTION_NONE];
 650   * - return 2   (\b10)    => [SQL_TRANSACTION_READ_UNCOMMITTED];
 651   * - return 3   (\b11)    => [SQL_TRANSACTION_NONE, SQL_TRANSACTION_READ_UNCOMMITTED];
 652   * - return 4   (\b100)   => [SQL_TRANSACTION_REPEATABLE_READ];
 653   * - return 5   (\b101)   => [SQL_TRANSACTION_NONE, SQL_TRANSACTION_REPEATABLE_READ];
 654   * - return 6   (\b110)   => [SQL_TRANSACTION_READ_UNCOMMITTED, SQL_TRANSACTION_REPEATABLE_READ];
 655   * - return 7   (\b111)   => [SQL_TRANSACTION_NONE, SQL_TRANSACTION_READ_UNCOMMITTED, SQL_TRANSACTION_REPEATABLE_READ];
 656   * - return 8   (\b1000)  => [SQL_TRANSACTION_REPEATABLE_READ];
 657   * - return 9   (\b1001)  => [SQL_TRANSACTION_NONE, SQL_TRANSACTION_REPEATABLE_READ];
 658   * - return 10  (\b1010)  => [SQL_TRANSACTION_READ_UNCOMMITTED, SQL_TRANSACTION_REPEATABLE_READ];
 659   * - return 11  (\b1011)  => [SQL_TRANSACTION_NONE, SQL_TRANSACTION_READ_UNCOMMITTED, SQL_TRANSACTION_REPEATABLE_READ];
 660   * - return 12  (\b1100)  => [SQL_TRANSACTION_REPEATABLE_READ, SQL_TRANSACTION_REPEATABLE_READ];
 661   * - return 13  (\b1101)  => [SQL_TRANSACTION_NONE, SQL_TRANSACTION_REPEATABLE_READ, SQL_TRANSACTION_REPEATABLE_READ];
 662   * - return 14  (\b1110)  => [SQL_TRANSACTION_READ_UNCOMMITTED, SQL_TRANSACTION_REPEATABLE_READ, SQL_TRANSACTION_REPEATABLE_READ];
 663   * - return 15  (\b1111)  => [SQL_TRANSACTION_NONE, SQL_TRANSACTION_READ_UNCOMMITTED, SQL_TRANSACTION_REPEATABLE_READ, SQL_TRANSACTION_REPEATABLE_READ];
 664   * - return 16  (\b10000) => [SQL_TRANSACTION_SERIALIZABLE];
 665   * - ...
 666   * Valid SQL positioned commands are described under `arrow.flight.protocol.sql.SqlTransactionIsolationLevel`.
 667   */
 668  SQL_SUPPORTED_TRANSACTIONS_ISOLATION_LEVELS = 564;
 669
 670  /*
 671   * Retrieves a boolean value indicating whether a data definition statement within a transaction forces
 672   * the transaction to commit.
 673   *
 674   * Returns:
 675   * - false: if a data definition statement within a transaction does not force the transaction to commit;
 676   * - true: if a data definition statement within a transaction forces the transaction to commit.
 677   */
 678  SQL_DATA_DEFINITION_CAUSES_TRANSACTION_COMMIT = 565;
 679
 680  /*
 681   * Retrieves a boolean value indicating whether a data definition statement within a transaction is ignored.
 682   *
 683   * Returns:
 684   * - false: if a data definition statement within a transaction is taken into account;
 685   * - true: a data definition statement within a transaction is ignored.
 686   */
 687  SQL_DATA_DEFINITIONS_IN_TRANSACTIONS_IGNORED = 566;
 688
 689  /*
 690   * Retrieves an int32 bitmask value representing the supported result set types.
 691   * The returned bitmask should be parsed in order to retrieve the supported result set types.
 692   *
 693   * For instance:
 694   * - return 0   (\b0)     => [] (no supported result set types);
 695   * - return 1   (\b1)     => [SQL_RESULT_SET_TYPE_UNSPECIFIED];
 696   * - return 2   (\b10)    => [SQL_RESULT_SET_TYPE_FORWARD_ONLY];
 697   * - return 3   (\b11)    => [SQL_RESULT_SET_TYPE_UNSPECIFIED, SQL_RESULT_SET_TYPE_FORWARD_ONLY];
 698   * - return 4   (\b100)   => [SQL_RESULT_SET_TYPE_SCROLL_INSENSITIVE];
 699   * - return 5   (\b101)   => [SQL_RESULT_SET_TYPE_UNSPECIFIED, SQL_RESULT_SET_TYPE_SCROLL_INSENSITIVE];
 700   * - return 6   (\b110)   => [SQL_RESULT_SET_TYPE_FORWARD_ONLY, SQL_RESULT_SET_TYPE_SCROLL_INSENSITIVE];
 701   * - return 7   (\b111)   => [SQL_RESULT_SET_TYPE_UNSPECIFIED, SQL_RESULT_SET_TYPE_FORWARD_ONLY, SQL_RESULT_SET_TYPE_SCROLL_INSENSITIVE];
 702   * - return 8   (\b1000)  => [SQL_RESULT_SET_TYPE_SCROLL_SENSITIVE];
 703   * - ...
 704   * Valid result set types are described under `arrow.flight.protocol.sql.SqlSupportedResultSetType`.
 705   */
 706  SQL_SUPPORTED_RESULT_SET_TYPES = 567;
 707
 708  /*
 709   * Returns an int32 bitmask value concurrency types supported for
 710   * `arrow.flight.protocol.sql.SqlSupportedResultSetType.SQL_RESULT_SET_TYPE_UNSPECIFIED`.
 711   *
 712   * For instance:
 713   * - return 0 (\b0)   => [] (no supported concurrency types for this result set type)
 714   * - return 1 (\b1)   => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED]
 715   * - return 2 (\b10)  => [SQL_RESULT_SET_CONCURRENCY_READ_ONLY]
 716   * - return 3 (\b11)  => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED, SQL_RESULT_SET_CONCURRENCY_READ_ONLY]
 717   * - return 4 (\b100) => [SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
 718   * - return 5 (\b101) => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED, SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
 719   * - return 6 (\b110)  => [SQL_RESULT_SET_CONCURRENCY_READ_ONLY, SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
 720   * - return 7 (\b111)  => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED, SQL_RESULT_SET_CONCURRENCY_READ_ONLY, SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
 721   * Valid result set types are described under `arrow.flight.protocol.sql.SqlSupportedResultSetConcurrency`.
 722   */
 723  SQL_SUPPORTED_CONCURRENCIES_FOR_RESULT_SET_UNSPECIFIED = 568;
 724
 725  /*
 726   * Returns an int32 bitmask value concurrency types supported for
 727   * `arrow.flight.protocol.sql.SqlSupportedResultSetType.SQL_RESULT_SET_TYPE_FORWARD_ONLY`.
 728   *
 729   * For instance:
 730   * - return 0 (\b0)   => [] (no supported concurrency types for this result set type)
 731   * - return 1 (\b1)   => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED]
 732   * - return 2 (\b10)  => [SQL_RESULT_SET_CONCURRENCY_READ_ONLY]
 733   * - return 3 (\b11)  => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED, SQL_RESULT_SET_CONCURRENCY_READ_ONLY]
 734   * - return 4 (\b100) => [SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
 735   * - return 5 (\b101) => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED, SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
 736   * - return 6 (\b110)  => [SQL_RESULT_SET_CONCURRENCY_READ_ONLY, SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
 737   * - return 7 (\b111)  => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED, SQL_RESULT_SET_CONCURRENCY_READ_ONLY, SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
 738   * Valid result set types are described under `arrow.flight.protocol.sql.SqlSupportedResultSetConcurrency`.
 739   */
 740  SQL_SUPPORTED_CONCURRENCIES_FOR_RESULT_SET_FORWARD_ONLY = 569;
 741
 742  /*
 743   * Returns an int32 bitmask value concurrency types supported for
 744   * `arrow.flight.protocol.sql.SqlSupportedResultSetType.SQL_RESULT_SET_TYPE_SCROLL_SENSITIVE`.
 745   *
 746   * For instance:
 747   * - return 0 (\b0)   => [] (no supported concurrency types for this result set type)
 748   * - return 1 (\b1)   => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED]
 749   * - return 2 (\b10)  => [SQL_RESULT_SET_CONCURRENCY_READ_ONLY]
 750   * - return 3 (\b11)  => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED, SQL_RESULT_SET_CONCURRENCY_READ_ONLY]
 751   * - return 4 (\b100) => [SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
 752   * - return 5 (\b101) => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED, SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
 753   * - return 6 (\b110)  => [SQL_RESULT_SET_CONCURRENCY_READ_ONLY, SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
 754   * - return 7 (\b111)  => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED, SQL_RESULT_SET_CONCURRENCY_READ_ONLY, SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
 755   * Valid result set types are described under `arrow.flight.protocol.sql.SqlSupportedResultSetConcurrency`.
 756   */
 757  SQL_SUPPORTED_CONCURRENCIES_FOR_RESULT_SET_SCROLL_SENSITIVE = 570;
 758
 759  /*
 760   * Returns an int32 bitmask value concurrency types supported for
 761   * `arrow.flight.protocol.sql.SqlSupportedResultSetType.SQL_RESULT_SET_TYPE_SCROLL_INSENSITIVE`.
 762   *
 763   * For instance:
 764   * - return 0 (\b0)   => [] (no supported concurrency types for this result set type)
 765   * - return 1 (\b1)   => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED]
 766   * - return 2 (\b10)  => [SQL_RESULT_SET_CONCURRENCY_READ_ONLY]
 767   * - return 3 (\b11)  => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED, SQL_RESULT_SET_CONCURRENCY_READ_ONLY]
 768   * - return 4 (\b100) => [SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
 769   * - return 5 (\b101) => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED, SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
 770   * - return 6 (\b110)  => [SQL_RESULT_SET_CONCURRENCY_READ_ONLY, SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
 771   * - return 7 (\b111)  => [SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED, SQL_RESULT_SET_CONCURRENCY_READ_ONLY, SQL_RESULT_SET_CONCURRENCY_UPDATABLE]
 772   * Valid result set types are described under `arrow.flight.protocol.sql.SqlSupportedResultSetConcurrency`.
 773   */
 774  SQL_SUPPORTED_CONCURRENCIES_FOR_RESULT_SET_SCROLL_INSENSITIVE = 571;
 775
 776  /*
 777   * Retrieves a boolean value indicating whether this database supports batch updates.
 778   *
 779   * - false: if this database does not support batch updates;
 780   * - true: if this database supports batch updates.
 781   */
 782  SQL_BATCH_UPDATES_SUPPORTED = 572;
 783
 784  /*
 785   * Retrieves a boolean value indicating whether this database supports savepoints.
 786   *
 787   * Returns:
 788   * - false: if this database does not support savepoints;
 789   * - true: if this database supports savepoints.
 790   */
 791  SQL_SAVEPOINTS_SUPPORTED = 573;
 792
 793  /*
 794   * Retrieves a boolean value indicating whether named parameters are supported in callable statements.
 795   *
 796   * Returns:
 797   * - false: if named parameters in callable statements are unsupported;
 798   * - true: if named parameters in callable statements are supported.
 799   */
 800  SQL_NAMED_PARAMETERS_SUPPORTED = 574;
 801
 802  /*
 803   * Retrieves a boolean value indicating whether updates made to a LOB are made on a copy or directly to the LOB.
 804   *
 805   * Returns:
 806   * - false: if updates made to a LOB are made directly to the LOB;
 807   * - true: if updates made to a LOB are made on a copy.
 808   */
 809  SQL_LOCATORS_UPDATE_COPY = 575;
 810
 811  /*
 812   * Retrieves a boolean value indicating whether invoking user-defined or vendor functions
 813   * using the stored procedure escape syntax is supported.
 814   *
 815   * Returns:
 816   * - false: if invoking user-defined or vendor functions using the stored procedure escape syntax is unsupported;
 817   * - true: if invoking user-defined or vendor functions using the stored procedure escape syntax is supported.
 818   */
 819  SQL_STORED_FUNCTIONS_USING_CALL_SYNTAX_SUPPORTED = 576;
 820}
 821
 822// The level of support for Flight SQL transaction RPCs.
 823enum SqlSupportedTransaction {
 824  // Unknown/not indicated/no support
 825  SQL_SUPPORTED_TRANSACTION_NONE = 0;
 826  // Transactions, but not savepoints.
 827  // A savepoint is a mark within a transaction that can be individually
 828  // rolled back to. Not all databases support savepoints.
 829  SQL_SUPPORTED_TRANSACTION_TRANSACTION = 1;
 830  // Transactions and savepoints
 831  SQL_SUPPORTED_TRANSACTION_SAVEPOINT = 2;
 832}
 833
 834enum SqlSupportedCaseSensitivity {
 835  SQL_CASE_SENSITIVITY_UNKNOWN = 0;
 836  SQL_CASE_SENSITIVITY_CASE_INSENSITIVE = 1;
 837  SQL_CASE_SENSITIVITY_UPPERCASE = 2;
 838  SQL_CASE_SENSITIVITY_LOWERCASE = 3;
 839}
 840
 841enum SqlNullOrdering {
 842  SQL_NULLS_SORTED_HIGH = 0;
 843  SQL_NULLS_SORTED_LOW = 1;
 844  SQL_NULLS_SORTED_AT_START = 2;
 845  SQL_NULLS_SORTED_AT_END = 3;
 846}
 847
 848enum SupportedSqlGrammar {
 849  SQL_MINIMUM_GRAMMAR = 0;
 850  SQL_CORE_GRAMMAR = 1;
 851  SQL_EXTENDED_GRAMMAR = 2;
 852}
 853
 854enum SupportedAnsi92SqlGrammarLevel {
 855  ANSI92_ENTRY_SQL = 0;
 856  ANSI92_INTERMEDIATE_SQL = 1;
 857  ANSI92_FULL_SQL = 2;
 858}
 859
 860enum SqlOuterJoinsSupportLevel {
 861  SQL_JOINS_UNSUPPORTED = 0;
 862  SQL_LIMITED_OUTER_JOINS = 1;
 863  SQL_FULL_OUTER_JOINS = 2;
 864}
 865
 866enum SqlSupportedGroupBy {
 867  SQL_GROUP_BY_UNRELATED = 0;
 868  SQL_GROUP_BY_BEYOND_SELECT = 1;
 869}
 870
 871enum SqlSupportedElementActions {
 872  SQL_ELEMENT_IN_PROCEDURE_CALLS = 0;
 873  SQL_ELEMENT_IN_INDEX_DEFINITIONS = 1;
 874  SQL_ELEMENT_IN_PRIVILEGE_DEFINITIONS = 2;
 875}
 876
 877enum SqlSupportedPositionedCommands {
 878  SQL_POSITIONED_DELETE = 0;
 879  SQL_POSITIONED_UPDATE = 1;
 880}
 881
 882enum SqlSupportedSubqueries {
 883  SQL_SUBQUERIES_IN_COMPARISONS = 0;
 884  SQL_SUBQUERIES_IN_EXISTS = 1;
 885  SQL_SUBQUERIES_IN_INS = 2;
 886  SQL_SUBQUERIES_IN_QUANTIFIEDS = 3;
 887}
 888
 889enum SqlSupportedUnions {
 890  SQL_UNION = 0;
 891  SQL_UNION_ALL = 1;
 892}
 893
 894enum SqlTransactionIsolationLevel {
 895  SQL_TRANSACTION_NONE = 0;
 896  SQL_TRANSACTION_READ_UNCOMMITTED = 1;
 897  SQL_TRANSACTION_READ_COMMITTED = 2;
 898  SQL_TRANSACTION_REPEATABLE_READ = 3;
 899  SQL_TRANSACTION_SERIALIZABLE = 4;
 900}
 901
 902enum SqlSupportedTransactions {
 903  SQL_TRANSACTION_UNSPECIFIED = 0;
 904  SQL_DATA_DEFINITION_TRANSACTIONS = 1;
 905  SQL_DATA_MANIPULATION_TRANSACTIONS = 2;
 906}
 907
 908enum SqlSupportedResultSetType {
 909  SQL_RESULT_SET_TYPE_UNSPECIFIED = 0;
 910  SQL_RESULT_SET_TYPE_FORWARD_ONLY = 1;
 911  SQL_RESULT_SET_TYPE_SCROLL_INSENSITIVE = 2;
 912  SQL_RESULT_SET_TYPE_SCROLL_SENSITIVE = 3;
 913}
 914
 915enum SqlSupportedResultSetConcurrency {
 916  SQL_RESULT_SET_CONCURRENCY_UNSPECIFIED = 0;
 917  SQL_RESULT_SET_CONCURRENCY_READ_ONLY = 1;
 918  SQL_RESULT_SET_CONCURRENCY_UPDATABLE = 2;
 919}
 920
 921enum SqlSupportsConvert {
 922  SQL_CONVERT_BIGINT = 0;
 923  SQL_CONVERT_BINARY = 1;
 924  SQL_CONVERT_BIT = 2;
 925  SQL_CONVERT_CHAR = 3;
 926  SQL_CONVERT_DATE = 4;
 927  SQL_CONVERT_DECIMAL = 5;
 928  SQL_CONVERT_FLOAT = 6;
 929  SQL_CONVERT_INTEGER = 7;
 930  SQL_CONVERT_INTERVAL_DAY_TIME = 8;
 931  SQL_CONVERT_INTERVAL_YEAR_MONTH = 9;
 932  SQL_CONVERT_LONGVARBINARY = 10;
 933  SQL_CONVERT_LONGVARCHAR = 11;
 934  SQL_CONVERT_NUMERIC = 12;
 935  SQL_CONVERT_REAL = 13;
 936  SQL_CONVERT_SMALLINT = 14;
 937  SQL_CONVERT_TIME = 15;
 938  SQL_CONVERT_TIMESTAMP = 16;
 939  SQL_CONVERT_TINYINT = 17;
 940  SQL_CONVERT_VARBINARY = 18;
 941  SQL_CONVERT_VARCHAR = 19;
 942}
 943
 944/**
 945 * The JDBC/ODBC-defined type of any object.
 946 * All the values here are the sames as in the JDBC and ODBC specs.
 947 */
 948enum XdbcDataType {
 949  XDBC_UNKNOWN_TYPE = 0;
 950  XDBC_CHAR = 1;
 951  XDBC_NUMERIC = 2;
 952  XDBC_DECIMAL = 3;
 953  XDBC_INTEGER = 4;
 954  XDBC_SMALLINT = 5;
 955  XDBC_FLOAT = 6;
 956  XDBC_REAL = 7;
 957  XDBC_DOUBLE = 8;
 958  XDBC_DATETIME = 9;
 959  XDBC_INTERVAL = 10;
 960  XDBC_VARCHAR = 12;
 961  XDBC_DATE = 91;
 962  XDBC_TIME = 92;
 963  XDBC_TIMESTAMP = 93;
 964  XDBC_LONGVARCHAR = -1;
 965  XDBC_BINARY = -2;
 966  XDBC_VARBINARY = -3;
 967  XDBC_LONGVARBINARY = -4;
 968  XDBC_BIGINT = -5;
 969  XDBC_TINYINT = -6;
 970  XDBC_BIT = -7;
 971  XDBC_WCHAR = -8;
 972  XDBC_WVARCHAR = -9;
 973}
 974
 975/**
 976 * Detailed subtype information for XDBC_TYPE_DATETIME and XDBC_TYPE_INTERVAL.
 977 */
 978enum XdbcDatetimeSubcode {
 979  option allow_alias = true;
 980  XDBC_SUBCODE_UNKNOWN = 0;
 981  XDBC_SUBCODE_YEAR = 1;
 982  XDBC_SUBCODE_DATE = 1;
 983  XDBC_SUBCODE_TIME = 2;
 984  XDBC_SUBCODE_MONTH = 2;
 985  XDBC_SUBCODE_TIMESTAMP = 3;
 986  XDBC_SUBCODE_DAY = 3;
 987  XDBC_SUBCODE_TIME_WITH_TIMEZONE = 4;
 988  XDBC_SUBCODE_HOUR = 4;
 989  XDBC_SUBCODE_TIMESTAMP_WITH_TIMEZONE = 5;
 990  XDBC_SUBCODE_MINUTE = 5;
 991  XDBC_SUBCODE_SECOND = 6;
 992  XDBC_SUBCODE_YEAR_TO_MONTH = 7;
 993  XDBC_SUBCODE_DAY_TO_HOUR = 8;
 994  XDBC_SUBCODE_DAY_TO_MINUTE = 9;
 995  XDBC_SUBCODE_DAY_TO_SECOND = 10;
 996  XDBC_SUBCODE_HOUR_TO_MINUTE = 11;
 997  XDBC_SUBCODE_HOUR_TO_SECOND = 12;
 998  XDBC_SUBCODE_MINUTE_TO_SECOND = 13;
 999  XDBC_SUBCODE_INTERVAL_YEAR = 101;
1000  XDBC_SUBCODE_INTERVAL_MONTH = 102;
1001  XDBC_SUBCODE_INTERVAL_DAY = 103;
1002  XDBC_SUBCODE_INTERVAL_HOUR = 104;
1003  XDBC_SUBCODE_INTERVAL_MINUTE = 105;
1004  XDBC_SUBCODE_INTERVAL_SECOND = 106;
1005  XDBC_SUBCODE_INTERVAL_YEAR_TO_MONTH = 107;
1006  XDBC_SUBCODE_INTERVAL_DAY_TO_HOUR = 108;
1007  XDBC_SUBCODE_INTERVAL_DAY_TO_MINUTE = 109;
1008  XDBC_SUBCODE_INTERVAL_DAY_TO_SECOND = 110;
1009  XDBC_SUBCODE_INTERVAL_HOUR_TO_MINUTE = 111;
1010  XDBC_SUBCODE_INTERVAL_HOUR_TO_SECOND = 112;
1011  XDBC_SUBCODE_INTERVAL_MINUTE_TO_SECOND = 113;
1012}
1013
1014enum Nullable {
1015  /**
1016   * Indicates that the fields does not allow the use of null values.
1017   */
1018  NULLABILITY_NO_NULLS = 0;
1019
1020  /**
1021   * Indicates that the fields allow the use of null values.
1022   */
1023  NULLABILITY_NULLABLE = 1;
1024
1025  /**
1026   * Indicates that nullability of the fields can not be determined.
1027   */
1028  NULLABILITY_UNKNOWN = 2;
1029}
1030
1031enum Searchable {
1032  /**
1033   * Indicates that column can not be used in a WHERE clause.
1034   */
1035  SEARCHABLE_NONE = 0;
1036
1037  /**
1038   * Indicates that the column can be used in a WHERE clause if it is using a
1039   * LIKE operator.
1040   */
1041  SEARCHABLE_CHAR = 1;
1042
1043  /**
1044   * Indicates that the column can be used In a WHERE clause with any
1045   * operator other than LIKE.
1046   *
1047   * - Allowed operators: comparison, quantified comparison, BETWEEN,
1048   *                      DISTINCT, IN, MATCH, and UNIQUE.
1049   */
1050  SEARCHABLE_BASIC = 2;
1051
1052  /**
1053   * Indicates that the column can be used in a WHERE clause using any operator.
1054   */
1055  SEARCHABLE_FULL = 3;
1056}
1057
1058/*
1059 * Represents a request to retrieve information about data type supported on a Flight SQL enabled backend.
1060 * Used in the command member of FlightDescriptor for the following RPC calls:
1061 *  - GetSchema: return the schema of the query.
1062 *  - GetFlightInfo: execute the catalog metadata request.
1063 *
1064 * The returned schema will be:
1065 * <
1066 *   type_name: utf8 not null (The name of the data type, for example: VARCHAR, INTEGER, etc),
1067 *   data_type: int32 not null (The SQL data type),
1068 *   column_size: int32 (The maximum size supported by that column.
1069 *                       In case of exact numeric types, this represents the maximum precision.
1070 *                       In case of string types, this represents the character length.
1071 *                       In case of datetime data types, this represents the length in characters of the string representation.
1072 *                       NULL is returned for data types where column size is not applicable.),
1073 *   literal_prefix: utf8 (Character or characters used to prefix a literal, NULL is returned for
1074 *                         data types where a literal prefix is not applicable.),
1075 *   literal_suffix: utf8 (Character or characters used to terminate a literal,
1076 *                         NULL is returned for data types where a literal suffix is not applicable.),
1077 *   create_params: list<utf8 not null>
1078 *                        (A list of keywords corresponding to which parameters can be used when creating
1079 *                         a column for that specific type.
1080 *                         NULL is returned if there are no parameters for the data type definition.),
1081 *   nullable: int32 not null (Shows if the data type accepts a NULL value. The possible values can be seen in the
1082 *                             Nullable enum.),
1083 *   case_sensitive: bool not null (Shows if a character data type is case-sensitive in collations and comparisons),
1084 *   searchable: int32 not null (Shows how the data type is used in a WHERE clause. The possible values can be seen in the
1085 *                               Searchable enum.),
1086 *   unsigned_attribute: bool (Shows if the data type is unsigned. NULL is returned if the attribute is
1087 *                             not applicable to the data type or the data type is not numeric.),
1088 *   fixed_prec_scale: bool not null (Shows if the data type has predefined fixed precision and scale.),
1089 *   auto_increment: bool (Shows if the data type is auto incremental. NULL is returned if the attribute
1090 *                         is not applicable to the data type or the data type is not numeric.),
1091 *   local_type_name: utf8 (Localized version of the data source-dependent name of the data type. NULL
1092 *                          is returned if a localized name is not supported by the data source),
1093 *   minimum_scale: int32 (The minimum scale of the data type on the data source.
1094 *                         If a data type has a fixed scale, the MINIMUM_SCALE and MAXIMUM_SCALE
1095 *                         columns both contain this value. NULL is returned if scale is not applicable.),
1096 *   maximum_scale: int32 (The maximum scale of the data type on the data source.
1097 *                         NULL is returned if scale is not applicable.),
1098 *   sql_data_type: int32 not null (The value of the SQL DATA TYPE which has the same values
1099 *                                  as data_type value. Except for interval and datetime, which
1100 *                                  uses generic values. More info about those types can be
1101 *                                  obtained through datetime_subcode. The possible values can be seen
1102 *                                  in the XdbcDataType enum.),
1103 *   datetime_subcode: int32 (Only used when the SQL DATA TYPE is interval or datetime. It contains
1104 *                            its sub types. For type different from interval and datetime, this value
1105 *                            is NULL. The possible values can be seen in the XdbcDatetimeSubcode enum.),
1106 *   num_prec_radix: int32 (If the data type is an approximate numeric type, this column contains
1107 *                          the value 2 to indicate that COLUMN_SIZE specifies a number of bits. For
1108 *                          exact numeric types, this column contains the value 10 to indicate that
1109 *                          column size specifies a number of decimal digits. Otherwise, this column is NULL.),
1110 *   interval_precision: int32 (If the data type is an interval data type, then this column contains the value
1111 *                              of the interval leading precision. Otherwise, this column is NULL. This fields
1112 *                              is only relevant to be used by ODBC).
1113 * >
1114 * The returned data should be ordered by data_type and then by type_name.
1115 */
1116message CommandGetXdbcTypeInfo {
1117  option (experimental) = true;
1118
1119  /*
1120   * Specifies the data type to search for the info.
1121   */
1122  optional int32 data_type = 1;
1123}
1124
1125/*
1126 * Represents a request to retrieve the list of catalogs on a Flight SQL enabled backend.
1127 * The definition of a catalog depends on vendor/implementation. It is usually the database itself
1128 * Used in the command member of FlightDescriptor for the following RPC calls:
1129 *  - GetSchema: return the Arrow schema of the query.
1130 *  - GetFlightInfo: execute the catalog metadata request.
1131 *
1132 * The returned Arrow schema will be:
1133 * <
1134 *  catalog_name: utf8 not null
1135 * >
1136 * The returned data should be ordered by catalog_name.
1137 */
1138message CommandGetCatalogs {
1139  option (experimental) = true;
1140}
1141
1142/*
1143 * Represents a request to retrieve the list of database schemas on a Flight SQL enabled backend.
1144 * The definition of a database schema depends on vendor/implementation. It is usually a collection of tables.
1145 * Used in the command member of FlightDescriptor for the following RPC calls:
1146 *  - GetSchema: return the Arrow schema of the query.
1147 *  - GetFlightInfo: execute the catalog metadata request.
1148 *
1149 * The returned Arrow schema will be:
1150 * <
1151 *  catalog_name: utf8,
1152 *  db_schema_name: utf8 not null
1153 * >
1154 * The returned data should be ordered by catalog_name, then db_schema_name.
1155 */
1156message CommandGetDbSchemas {
1157  option (experimental) = true;
1158
1159  /*
1160   * Specifies the Catalog to search for the tables.
1161   * An empty string retrieves those without a catalog.
1162   * If omitted the catalog name should not be used to narrow the search.
1163   */
1164  optional string catalog = 1;
1165
1166  /*
1167   * Specifies a filter pattern for schemas to search for.
1168   * When no db_schema_filter_pattern is provided, the pattern will not be used to narrow the search.
1169   * In the pattern string, two special characters can be used to denote matching rules:
1170   *    - "%" means to match any substring with 0 or more characters.
1171   *    - "_" means to match any one character.
1172   */
1173  optional string db_schema_filter_pattern = 2;
1174}
1175
1176/*
1177 * Represents a request to retrieve the list of tables, and optionally their schemas, on a Flight SQL enabled backend.
1178 * Used in the command member of FlightDescriptor for the following RPC calls:
1179 *  - GetSchema: return the Arrow schema of the query.
1180 *  - GetFlightInfo: execute the catalog metadata request.
1181 *
1182 * The returned Arrow schema will be:
1183 * <
1184 *  catalog_name: utf8,
1185 *  db_schema_name: utf8,
1186 *  table_name: utf8 not null,
1187 *  table_type: utf8 not null,
1188 *  [optional] table_schema: bytes not null (schema of the table as described in Schema.fbs::Schema,
1189 *                                           it is serialized as an IPC message.)
1190 * >
1191 * Fields on table_schema may contain the following metadata:
1192 *  - ARROW:FLIGHT:SQL:CATALOG_NAME      - Table's catalog name
1193 *  - ARROW:FLIGHT:SQL:DB_SCHEMA_NAME    - Database schema name
1194 *  - ARROW:FLIGHT:SQL:TABLE_NAME        - Table name
1195 *  - ARROW:FLIGHT:SQL:TYPE_NAME         - The data source-specific name for the data type of the column.
1196 *  - ARROW:FLIGHT:SQL:PRECISION         - Column precision/size
1197 *  - ARROW:FLIGHT:SQL:SCALE             - Column scale/decimal digits if applicable
1198 *  - ARROW:FLIGHT:SQL:IS_AUTO_INCREMENT - "1" indicates if the column is auto incremented, "0" otherwise.
1199 *  - ARROW:FLIGHT:SQL:IS_CASE_SENSITIVE - "1" indicates if the column is case sensitive, "0" otherwise.
1200 *  - ARROW:FLIGHT:SQL:IS_READ_ONLY      - "1" indicates if the column is read only, "0" otherwise.
1201 *  - ARROW:FLIGHT:SQL:IS_SEARCHABLE     - "1" indicates if the column is searchable via WHERE clause, "0" otherwise.
1202 * The returned data should be ordered by catalog_name, db_schema_name, table_name, then table_type, followed by table_schema if requested.
1203 */
1204message CommandGetTables {
1205  option (experimental) = true;
1206
1207  /*
1208   * Specifies the Catalog to search for the tables.
1209   * An empty string retrieves those without a catalog.
1210   * If omitted the catalog name should not be used to narrow the search.
1211   */
1212  optional string catalog = 1;
1213
1214  /*
1215   * Specifies a filter pattern for schemas to search for.
1216   * When no db_schema_filter_pattern is provided, all schemas matching other filters are searched.
1217   * In the pattern string, two special characters can be used to denote matching rules:
1218   *    - "%" means to match any substring with 0 or more characters.
1219   *    - "_" means to match any one character.
1220   */
1221  optional string db_schema_filter_pattern = 2;
1222
1223  /*
1224   * Specifies a filter pattern for tables to search for.
1225   * When no table_name_filter_pattern is provided, all tables matching other filters are searched.
1226   * In the pattern string, two special characters can be used to denote matching rules:
1227   *    - "%" means to match any substring with 0 or more characters.
1228   *    - "_" means to match any one character.
1229   */
1230  optional string table_name_filter_pattern = 3;
1231
1232  /*
1233   * Specifies a filter of table types which must match.
1234   * The table types depend on vendor/implementation. It is usually used to separate tables from views or system tables.
1235   * TABLE, VIEW, and SYSTEM TABLE are commonly supported.
1236   */
1237  repeated string table_types = 4;
1238
1239  // Specifies if the Arrow schema should be returned for found tables.
1240  bool include_schema = 5;
1241}
1242
1243/*
1244 * Represents a request to retrieve the list of table types on a Flight SQL enabled backend.
1245 * The table types depend on vendor/implementation. It is usually used to separate tables from views or system tables.
1246 * TABLE, VIEW, and SYSTEM TABLE are commonly supported.
1247 * Used in the command member of FlightDescriptor for the following RPC calls:
1248 *  - GetSchema: return the Arrow schema of the query.
1249 *  - GetFlightInfo: execute the catalog metadata request.
1250 *
1251 * The returned Arrow schema will be:
1252 * <
1253 *  table_type: utf8 not null
1254 * >
1255 * The returned data should be ordered by table_type.
1256 */
1257message CommandGetTableTypes {
1258  option (experimental) = true;
1259}
1260
1261/*
1262 * Represents a request to retrieve the primary keys of a table on a Flight SQL enabled backend.
1263 * Used in the command member of FlightDescriptor for the following RPC calls:
1264 *  - GetSchema: return the Arrow schema of the query.
1265 *  - GetFlightInfo: execute the catalog metadata request.
1266 *
1267 * The returned Arrow schema will be:
1268 * <
1269 *  catalog_name: utf8,
1270 *  db_schema_name: utf8,
1271 *  table_name: utf8 not null,
1272 *  column_name: utf8 not null,
1273 *  key_name: utf8,
1274 *  key_sequence: int32 not null
1275 * >
1276 * The returned data should be ordered by catalog_name, db_schema_name, table_name, key_name, then key_sequence.
1277 */
1278message CommandGetPrimaryKeys {
1279  option (experimental) = true;
1280
1281  /*
1282   * Specifies the catalog to search for the table.
1283   * An empty string retrieves those without a catalog.
1284   * If omitted the catalog name should not be used to narrow the search.
1285   */
1286  optional string catalog = 1;
1287
1288  /*
1289   * Specifies the schema to search for the table.
1290   * An empty string retrieves those without a schema.
1291   * If omitted the schema name should not be used to narrow the search.
1292   */
1293  optional string db_schema = 2;
1294
1295  // Specifies the table to get the primary keys for.
1296  string table = 3;
1297}
1298
1299enum UpdateDeleteRules {
1300  CASCADE = 0;
1301  RESTRICT = 1;
1302  SET_NULL = 2;
1303  NO_ACTION = 3;
1304  SET_DEFAULT = 4;
1305}
1306
1307/*
1308 * Represents a request to retrieve a description of the foreign key columns that reference the given table's
1309 * primary key columns (the foreign keys exported by a table) of a table on a Flight SQL enabled backend.
1310 * Used in the command member of FlightDescriptor for the following RPC calls:
1311 *  - GetSchema: return the Arrow schema of the query.
1312 *  - GetFlightInfo: execute the catalog metadata request.
1313 *
1314 * The returned Arrow schema will be:
1315 * <
1316 *  pk_catalog_name: utf8,
1317 *  pk_db_schema_name: utf8,
1318 *  pk_table_name: utf8 not null,
1319 *  pk_column_name: utf8 not null,
1320 *  fk_catalog_name: utf8,
1321 *  fk_db_schema_name: utf8,
1322 *  fk_table_name: utf8 not null,
1323 *  fk_column_name: utf8 not null,
1324 *  key_sequence: int32 not null,
1325 *  fk_key_name: utf8,
1326 *  pk_key_name: utf8,
1327 *  update_rule: uint8 not null,
1328 *  delete_rule: uint8 not null
1329 * >
1330 * The returned data should be ordered by fk_catalog_name, fk_db_schema_name, fk_table_name, fk_key_name, then key_sequence.
1331 * update_rule and delete_rule returns a byte that is equivalent to actions declared on UpdateDeleteRules enum.
1332 */
1333message CommandGetExportedKeys {
1334  option (experimental) = true;
1335
1336  /*
1337   * Specifies the catalog to search for the foreign key table.
1338   * An empty string retrieves those without a catalog.
1339   * If omitted the catalog name should not be used to narrow the search.
1340   */
1341  optional string catalog = 1;
1342
1343  /*
1344   * Specifies the schema to search for the foreign key table.
1345   * An empty string retrieves those without a schema.
1346   * If omitted the schema name should not be used to narrow the search.
1347   */
1348  optional string db_schema = 2;
1349
1350  // Specifies the foreign key table to get the foreign keys for.
1351  string table = 3;
1352}
1353
1354/*
1355 * Represents a request to retrieve the foreign keys of a table on a Flight SQL enabled backend.
1356 * Used in the command member of FlightDescriptor for the following RPC calls:
1357 *  - GetSchema: return the Arrow schema of the query.
1358 *  - GetFlightInfo: execute the catalog metadata request.
1359 *
1360 * The returned Arrow schema will be:
1361 * <
1362 *  pk_catalog_name: utf8,
1363 *  pk_db_schema_name: utf8,
1364 *  pk_table_name: utf8 not null,
1365 *  pk_column_name: utf8 not null,
1366 *  fk_catalog_name: utf8,
1367 *  fk_db_schema_name: utf8,
1368 *  fk_table_name: utf8 not null,
1369 *  fk_column_name: utf8 not null,
1370 *  key_sequence: int32 not null,
1371 *  fk_key_name: utf8,
1372 *  pk_key_name: utf8,
1373 *  update_rule: uint8 not null,
1374 *  delete_rule: uint8 not null
1375 * >
1376 * The returned data should be ordered by pk_catalog_name, pk_db_schema_name, pk_table_name, pk_key_name, then key_sequence.
1377 * update_rule and delete_rule returns a byte that is equivalent to actions:
1378 *    - 0 = CASCADE
1379 *    - 1 = RESTRICT
1380 *    - 2 = SET NULL
1381 *    - 3 = NO ACTION
1382 *    - 4 = SET DEFAULT
1383 */
1384message CommandGetImportedKeys {
1385  option (experimental) = true;
1386
1387  /*
1388   * Specifies the catalog to search for the primary key table.
1389   * An empty string retrieves those without a catalog.
1390   * If omitted the catalog name should not be used to narrow the search.
1391   */
1392  optional string catalog = 1;
1393
1394  /*
1395   * Specifies the schema to search for the primary key table.
1396   * An empty string retrieves those without a schema.
1397   * If omitted the schema name should not be used to narrow the search.
1398   */
1399  optional string db_schema = 2;
1400
1401  // Specifies the primary key table to get the foreign keys for.
1402  string table = 3;
1403}
1404
1405/*
1406 * Represents a request to retrieve a description of the foreign key columns in the given foreign key table that
1407 * reference the primary key or the columns representing a unique constraint of the parent table (could be the same
1408 * or a different table) on a Flight SQL enabled backend.
1409 * Used in the command member of FlightDescriptor for the following RPC calls:
1410 *  - GetSchema: return the Arrow schema of the query.
1411 *  - GetFlightInfo: execute the catalog metadata request.
1412 *
1413 * The returned Arrow schema will be:
1414 * <
1415 *  pk_catalog_name: utf8,
1416 *  pk_db_schema_name: utf8,
1417 *  pk_table_name: utf8 not null,
1418 *  pk_column_name: utf8 not null,
1419 *  fk_catalog_name: utf8,
1420 *  fk_db_schema_name: utf8,
1421 *  fk_table_name: utf8 not null,
1422 *  fk_column_name: utf8 not null,
1423 *  key_sequence: int32 not null,
1424 *  fk_key_name: utf8,
1425 *  pk_key_name: utf8,
1426 *  update_rule: uint8 not null,
1427 *  delete_rule: uint8 not null
1428 * >
1429 * The returned data should be ordered by pk_catalog_name, pk_db_schema_name, pk_table_name, pk_key_name, then key_sequence.
1430 * update_rule and delete_rule returns a byte that is equivalent to actions:
1431 *    - 0 = CASCADE
1432 *    - 1 = RESTRICT
1433 *    - 2 = SET NULL
1434 *    - 3 = NO ACTION
1435 *    - 4 = SET DEFAULT
1436 */
1437message CommandGetCrossReference {
1438  option (experimental) = true;
1439
1440  /**
1441   * The catalog name where the parent table is.
1442   * An empty string retrieves those without a catalog.
1443   * If omitted the catalog name should not be used to narrow the search.
1444   */
1445  optional string pk_catalog = 1;
1446
1447  /**
1448   * The Schema name where the parent table is.
1449   * An empty string retrieves those without a schema.
1450   * If omitted the schema name should not be used to narrow the search.
1451   */
1452  optional string pk_db_schema = 2;
1453
1454  /**
1455   * The parent table name. It cannot be null.
1456   */
1457  string pk_table = 3;
1458
1459  /**
1460   * The catalog name where the foreign table is.
1461   * An empty string retrieves those without a catalog.
1462   * If omitted the catalog name should not be used to narrow the search.
1463   */
1464  optional string fk_catalog = 4;
1465
1466  /**
1467   * The schema name where the foreign table is.
1468   * An empty string retrieves those without a schema.
1469   * If omitted the schema name should not be used to narrow the search.
1470   */
1471  optional string fk_db_schema = 5;
1472
1473  /**
1474   * The foreign table name. It cannot be null.
1475   */
1476  string fk_table = 6;
1477}
1478
1479// Query Execution Action Messages
1480
1481/*
1482 * Request message for the "CreatePreparedStatement" action on a Flight SQL enabled backend.
1483 */
1484message ActionCreatePreparedStatementRequest {
1485  option (experimental) = true;
1486
1487  // The valid SQL string to create a prepared statement for.
1488  string query = 1;
1489  // Create/execute the prepared statement as part of this transaction (if
1490  // unset, executions of the prepared statement will be auto-committed).
1491  optional bytes transaction_id = 2;
1492}
1493
1494/*
1495 * An embedded message describing a Substrait plan to execute.
1496 */
1497message SubstraitPlan {
1498  option (experimental) = true;
1499
1500  // The serialized substrait.Plan to create a prepared statement for.
1501  // XXX(ARROW-16902): this is bytes instead of an embedded message
1502  // because Protobuf does not really support one DLL using Protobuf
1503  // definitions from another DLL.
1504  bytes plan = 1;
1505  // The Substrait release, e.g. "0.12.0". This information is not
1506  // tracked in the plan itself, so this is the only way for consumers
1507  // to potentially know if they can handle the plan.
1508  string version = 2;
1509}
1510
1511/*
1512 * Request message for the "CreatePreparedSubstraitPlan" action on a Flight SQL enabled backend.
1513 */
1514message ActionCreatePreparedSubstraitPlanRequest {
1515  option (experimental) = true;
1516
1517  // The serialized substrait.Plan to create a prepared statement for.
1518  SubstraitPlan plan = 1;
1519  // Create/execute the prepared statement as part of this transaction (if
1520  // unset, executions of the prepared statement will be auto-committed).
1521  optional bytes transaction_id = 2;
1522}
1523
1524/*
1525 * Wrap the result of a "CreatePreparedStatement" or "CreatePreparedSubstraitPlan" action.
1526 *
1527 * The resultant PreparedStatement can be closed either:
1528 * - Manually, through the "ClosePreparedStatement" action;
1529 * - Automatically, by a server timeout.
1530 *
1531 * The result should be wrapped in a google.protobuf.Any message.
1532 */
1533message ActionCreatePreparedStatementResult {
1534  option (experimental) = true;
1535
1536  // Opaque handle for the prepared statement on the server.
1537  bytes prepared_statement_handle = 1;
1538
1539  // If a result set generating query was provided, dataset_schema contains the
1540  // schema of the dataset as described in Schema.fbs::Schema, it is serialized as an IPC message.
1541  bytes dataset_schema = 2;
1542
1543  // If the query provided contained parameters, parameter_schema contains the
1544  // schema of the expected parameters as described in Schema.fbs::Schema, it is serialized as an IPC message.
1545  bytes parameter_schema = 3;
1546}
1547
1548/*
1549 * Request message for the "ClosePreparedStatement" action on a Flight SQL enabled backend.
1550 * Closes server resources associated with the prepared statement handle.
1551 */
1552message ActionClosePreparedStatementRequest {
1553  option (experimental) = true;
1554
1555  // Opaque handle for the prepared statement on the server.
1556  bytes prepared_statement_handle = 1;
1557}
1558
1559/*
1560 * Request message for the "BeginTransaction" action.
1561 * Begins a transaction.
1562 */
1563message ActionBeginTransactionRequest {
1564  option (experimental) = true;
1565}
1566
1567/*
1568 * Request message for the "BeginSavepoint" action.
1569 * Creates a savepoint within a transaction.
1570 *
1571 * Only supported if FLIGHT_SQL_TRANSACTION is
1572 * FLIGHT_SQL_TRANSACTION_SUPPORT_SAVEPOINT.
1573 */
1574message ActionBeginSavepointRequest {
1575  option (experimental) = true;
1576
1577  // The transaction to which a savepoint belongs.
1578  bytes transaction_id = 1;
1579  // Name for the savepoint.
1580  string name = 2;
1581}
1582
1583/*
1584 * The result of a "BeginTransaction" action.
1585 *
1586 * The transaction can be manipulated with the "EndTransaction" action, or
1587 * automatically via server timeout. If the transaction times out, then it is
1588 * automatically rolled back.
1589 *
1590 * The result should be wrapped in a google.protobuf.Any message.
1591 */
1592message ActionBeginTransactionResult {
1593  option (experimental) = true;
1594
1595  // Opaque handle for the transaction on the server.
1596  bytes transaction_id = 1;
1597}
1598
1599/*
1600 * The result of a "BeginSavepoint" action.
1601 *
1602 * The transaction can be manipulated with the "EndSavepoint" action.
1603 * If the associated transaction is committed, rolled back, or times
1604 * out, then the savepoint is also invalidated.
1605 *
1606 * The result should be wrapped in a google.protobuf.Any message.
1607 */
1608message ActionBeginSavepointResult {
1609  option (experimental) = true;
1610
1611  // Opaque handle for the savepoint on the server.
1612  bytes savepoint_id = 1;
1613}
1614
1615/*
1616 * Request message for the "EndTransaction" action.
1617 *
1618 * Commit (COMMIT) or rollback (ROLLBACK) the transaction.
1619 *
1620 * If the action completes successfully, the transaction handle is
1621 * invalidated, as are all associated savepoints.
1622 */
1623message ActionEndTransactionRequest {
1624  option (experimental) = true;
1625
1626  enum EndTransaction {
1627    END_TRANSACTION_UNSPECIFIED = 0;
1628    // Commit the transaction.
1629    END_TRANSACTION_COMMIT = 1;
1630    // Roll back the transaction.
1631    END_TRANSACTION_ROLLBACK = 2;
1632  }
1633  // Opaque handle for the transaction on the server.
1634  bytes transaction_id = 1;
1635  // Whether to commit/rollback the given transaction.
1636  EndTransaction action = 2;
1637}
1638
1639/*
1640 * Request message for the "EndSavepoint" action.
1641 *
1642 * Release (RELEASE) the savepoint or rollback (ROLLBACK) to the
1643 * savepoint.
1644 *
1645 * Releasing a savepoint invalidates that savepoint.  Rolling back to
1646 * a savepoint does not invalidate the savepoint, but invalidates all
1647 * savepoints created after the current savepoint.
1648 */
1649message ActionEndSavepointRequest {
1650  option (experimental) = true;
1651
1652  enum EndSavepoint {
1653    END_SAVEPOINT_UNSPECIFIED = 0;
1654    // Release the savepoint.
1655    END_SAVEPOINT_RELEASE = 1;
1656    // Roll back to a savepoint.
1657    END_SAVEPOINT_ROLLBACK = 2;
1658  }
1659  // Opaque handle for the savepoint on the server.
1660  bytes savepoint_id = 1;
1661  // Whether to rollback/release the given savepoint.
1662  EndSavepoint action = 2;
1663}
1664
1665// Query Execution Messages.
1666
1667/*
1668 * Represents a SQL query. Used in the command member of FlightDescriptor
1669 * for the following RPC calls:
1670 *  - GetSchema: return the Arrow schema of the query.
1671 *    Fields on this schema may contain the following metadata:
1672 *    - ARROW:FLIGHT:SQL:CATALOG_NAME      - Table's catalog name
1673 *    - ARROW:FLIGHT:SQL:DB_SCHEMA_NAME    - Database schema name
1674 *    - ARROW:FLIGHT:SQL:TABLE_NAME        - Table name
1675 *    - ARROW:FLIGHT:SQL:TYPE_NAME         - The data source-specific name for the data type of the column.
1676 *    - ARROW:FLIGHT:SQL:PRECISION         - Column precision/size
1677 *    - ARROW:FLIGHT:SQL:SCALE             - Column scale/decimal digits if applicable
1678 *    - ARROW:FLIGHT:SQL:IS_AUTO_INCREMENT - "1" indicates if the column is auto incremented, "0" otherwise.
1679 *    - ARROW:FLIGHT:SQL:IS_CASE_SENSITIVE - "1" indicates if the column is case sensitive, "0" otherwise.
1680 *    - ARROW:FLIGHT:SQL:IS_READ_ONLY      - "1" indicates if the column is read only, "0" otherwise.
1681 *    - ARROW:FLIGHT:SQL:IS_SEARCHABLE     - "1" indicates if the column is searchable via WHERE clause, "0" otherwise.
1682 *  - GetFlightInfo: execute the query.
1683 */
1684message CommandStatementQuery {
1685  option (experimental) = true;
1686
1687  // The SQL syntax.
1688  string query = 1;
1689  // Include the query as part of this transaction (if unset, the query is auto-committed).
1690  optional bytes transaction_id = 2;
1691}
1692
1693/*
1694 * Represents a Substrait plan. Used in the command member of FlightDescriptor
1695 * for the following RPC calls:
1696 *  - GetSchema: return the Arrow schema of the query.
1697 *    Fields on this schema may contain the following metadata:
1698 *    - ARROW:FLIGHT:SQL:CATALOG_NAME      - Table's catalog name
1699 *    - ARROW:FLIGHT:SQL:DB_SCHEMA_NAME    - Database schema name
1700 *    - ARROW:FLIGHT:SQL:TABLE_NAME        - Table name
1701 *    - ARROW:FLIGHT:SQL:TYPE_NAME         - The data source-specific name for the data type of the column.
1702 *    - ARROW:FLIGHT:SQL:PRECISION         - Column precision/size
1703 *    - ARROW:FLIGHT:SQL:SCALE             - Column scale/decimal digits if applicable
1704 *    - ARROW:FLIGHT:SQL:IS_AUTO_INCREMENT - "1" indicates if the column is auto incremented, "0" otherwise.
1705 *    - ARROW:FLIGHT:SQL:IS_CASE_SENSITIVE - "1" indicates if the column is case sensitive, "0" otherwise.
1706 *    - ARROW:FLIGHT:SQL:IS_READ_ONLY      - "1" indicates if the column is read only, "0" otherwise.
1707 *    - ARROW:FLIGHT:SQL:IS_SEARCHABLE     - "1" indicates if the column is searchable via WHERE clause, "0" otherwise.
1708 *  - GetFlightInfo: execute the query.
1709 *  - DoPut: execute the query.
1710 */
1711message CommandStatementSubstraitPlan {
1712  option (experimental) = true;
1713
1714  // A serialized substrait.Plan
1715  SubstraitPlan plan = 1;
1716  // Include the query as part of this transaction (if unset, the query is auto-committed).
1717  optional bytes transaction_id = 2;
1718}
1719
1720/**
1721 * Represents a ticket resulting from GetFlightInfo with a CommandStatementQuery.
1722 * This should be used only once and treated as an opaque value, that is, clients should not attempt to parse this.
1723 */
1724message TicketStatementQuery {
1725  option (experimental) = true;
1726
1727  // Unique identifier for the instance of the statement to execute.
1728  bytes statement_handle = 1;
1729}
1730
1731/*
1732 * Represents an instance of executing a prepared statement. Used in the command member of FlightDescriptor for
1733 * the following RPC calls:
1734 *  - GetSchema: return the Arrow schema of the query.
1735 *    Fields on this schema may contain the following metadata:
1736 *    - ARROW:FLIGHT:SQL:CATALOG_NAME      - Table's catalog name
1737 *    - ARROW:FLIGHT:SQL:DB_SCHEMA_NAME    - Database schema name
1738 *    - ARROW:FLIGHT:SQL:TABLE_NAME        - Table name
1739 *    - ARROW:FLIGHT:SQL:TYPE_NAME         - The data source-specific name for the data type of the column.
1740 *    - ARROW:FLIGHT:SQL:PRECISION         - Column precision/size
1741 *    - ARROW:FLIGHT:SQL:SCALE             - Column scale/decimal digits if applicable
1742 *    - ARROW:FLIGHT:SQL:IS_AUTO_INCREMENT - "1" indicates if the column is auto incremented, "0" otherwise.
1743 *    - ARROW:FLIGHT:SQL:IS_CASE_SENSITIVE - "1" indicates if the column is case sensitive, "0" otherwise.
1744 *    - ARROW:FLIGHT:SQL:IS_READ_ONLY      - "1" indicates if the column is read only, "0" otherwise.
1745 *    - ARROW:FLIGHT:SQL:IS_SEARCHABLE     - "1" indicates if the column is searchable via WHERE clause, "0" otherwise.
1746 *  - DoPut: bind parameter values. All of the bound parameter sets will be executed as a single atomic execution.
1747 *  - GetFlightInfo: execute the prepared statement instance.
1748 */
1749message CommandPreparedStatementQuery {
1750  option (experimental) = true;
1751
1752  // Opaque handle for the prepared statement on the server.
1753  bytes prepared_statement_handle = 1;
1754}
1755
1756/*
1757 * Represents a SQL update query. Used in the command member of FlightDescriptor
1758 * for the the RPC call DoPut to cause the server to execute the included SQL update.
1759 */
1760message CommandStatementUpdate {
1761  option (experimental) = true;
1762
1763  // The SQL syntax.
1764  string query = 1;
1765  // Include the query as part of this transaction (if unset, the query is auto-committed).
1766  optional bytes transaction_id = 2;
1767}
1768
1769/*
1770 * Represents a SQL update query. Used in the command member of FlightDescriptor
1771 * for the the RPC call DoPut to cause the server to execute the included
1772 * prepared statement handle as an update.
1773 */
1774message CommandPreparedStatementUpdate {
1775  option (experimental) = true;
1776
1777  // Opaque handle for the prepared statement on the server.
1778  bytes prepared_statement_handle = 1;
1779}
1780
1781/*
1782 * Returned from the RPC call DoPut when a CommandStatementUpdate
1783 * CommandPreparedStatementUpdate was in the request, containing
1784 * results from the update.
1785 */
1786message DoPutUpdateResult {
1787  option (experimental) = true;
1788
1789  // The number of records updated. A return value of -1 represents
1790  // an unknown updated record count.
1791  int64 record_count = 1;
1792}
1793
1794/*
1795 * Request message for the "CancelQuery" action.
1796 *
1797 * Explicitly cancel a running query.
1798 *
1799 * This lets a single client explicitly cancel work, no matter how many clients
1800 * are involved/whether the query is distributed or not, given server support.
1801 * The transaction/statement is not rolled back; it is the application's job to
1802 * commit or rollback as appropriate. This only indicates the client no longer
1803 * wishes to read the remainder of the query results or continue submitting
1804 * data.
1805 *
1806 * This command is idempotent.
1807 *
1808 * This command is deprecated since 13.0.0. Use the "CancelFlightInfo"
1809 * action with DoAction instead.
1810 */
1811message ActionCancelQueryRequest {
1812  option deprecated = true;
1813  option (experimental) = true;
1814
1815  // The result of the GetFlightInfo RPC that initiated the query.
1816  // XXX(ARROW-16902): this must be a serialized FlightInfo, but is
1817  // rendered as bytes because Protobuf does not really support one
1818  // DLL using Protobuf definitions from another DLL.
1819  bytes info = 1;
1820}
1821
1822/*
1823 * The result of cancelling a query.
1824 *
1825 * The result should be wrapped in a google.protobuf.Any message.
1826 *
1827 * This command is deprecated since 13.0.0. Use the "CancelFlightInfo"
1828 * action with DoAction instead.
1829 */
1830message ActionCancelQueryResult {
1831  option deprecated = true;
1832  option (experimental) = true;
1833
1834  enum CancelResult {
1835    // The cancellation status is unknown. Servers should avoid using
1836    // this value (send a NOT_FOUND error if the requested query is
1837    // not known). Clients can retry the request.
1838    CANCEL_RESULT_UNSPECIFIED = 0;
1839    // The cancellation request is complete. Subsequent requests with
1840    // the same payload may return CANCELLED or a NOT_FOUND error.
1841    CANCEL_RESULT_CANCELLED = 1;
1842    // The cancellation request is in progress. The client may retry
1843    // the cancellation request.
1844    CANCEL_RESULT_CANCELLING = 2;
1845    // The query is not cancellable. The client should not retry the
1846    // cancellation request.
1847    CANCEL_RESULT_NOT_CANCELLABLE = 3;
1848  }
1849
1850  CancelResult result = 1;
1851}
1852
1853extend google.protobuf.MessageOptions {
1854  bool experimental = 1000;
1855}

previous

Arrow Flight RPC

next

Integration Testing