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

previous

Arrow Flight RPC

next

Integration Testing