Arrow Flight SQL#
Arrow Flight SQL 是一种使用 Arrow 内存格式和 Flight RPC 框架与 SQL 数据库交互的协议。
通常，数据库将根据规范实现 RPC 方法，但不需要实现客户端驱动程序。数据库客户端可以使用提供的 Flight SQL 客户端与支持必要端点的任何数据库进行交互。Flight SQL 客户端包装底层的 Flight 客户端，以提供此处描述的新 RPC 方法的方法。
警告
Flight SQL 处于实验阶段，协议可能会发生变化。
RPC 方法#
Flight SQL 重用 Arrow Flight 中预定义的 RPC 方法，并提供各种命令，这些命令将这些方法与通过 Protobuf 定义的请求/响应消息配对（见下文）。
SQL 元数据#
Flight SQL 提供各种命令来获取有关数据库服务器的目录元数据。
所有这些命令都可以与 GetFlightInfo 和 GetSchema RPC 方法一起使用。Protobuf 请求消息应打包到 google.protobuf.Any 消息中，然后序列化并打包为 CMD 类型 FlightDescriptor 中的 cmd 字段。
如果命令与 GetFlightInfo 一起使用，服务器将返回 FlightInfo 响应。然后，客户端应使用 FlightInfo 中的 Ticket(s) 与 DoGet RPC 方法一起使用，以获取包含命令结果的 Arrow 数据。换句话说，SQL 元数据作为 Arrow 数据返回，就像查询结果本身一样。
GetSchema 或 DoGet 为特定命令返回的 Arrow 架构根据规范是固定的。
CommandGetCatalogs列出数据库中可用的目录。定义因供应商而异。
CommandGetCrossReference列出给定表中引用给定父表中列的外键列。
CommandGetDbSchemas列出数据库中可用的模式（注意：表的组合，不是 Arrow 模式）。定义因供应商而异。
CommandGetExportedKeys列出引用给定表的主键列的外键列。
CommandGetImportedKeys列出给定表的外键。
CommandGetPrimaryKeys列出给定表的主键。
CommandGetSqlInfo获取有关数据库服务器及其支持的 SQL 功能的元数据。
CommandGetTables列出数据库中的表。
CommandGetTableTypes列出数据库中的表类型。类型列表因供应商而异。
查询执行#
Flight SQL 还提供命令来执行 SQL 查询和管理准备好的语句。
这些命令中的许多也与 GetFlightInfo/GetSchema 一起使用，并且工作方式与上面的元数据方法相同。其中一些命令可以与 DoPut RPC 方法一起使用，但命令仍应以相同的方式编码在请求 FlightDescriptor 中。
以“Action”开头的命令改为与 DoAction RPC 方法一起使用，在这种情况下，命令应打包到 google.protobuf.Any 消息中，然后序列化并打包到 Flight Action 的 body 中。此外，操作 type 应设置为命令名称（即对于 ActionClosePreparedStatementRequest，type 应为 ClosePreparedStatement）。
ActionClosePreparedStatementRequest关闭先前创建的准备好的语句。
ActionCreatePreparedStatementRequest为 SQL 查询创建一个新的准备好的语句。
响应将包含一个不透明句柄，用于标识准备好的语句。它还可以包含两个可选的模式：结果集的 Arrow 模式和绑定参数（如果有）的 Arrow 模式。由于结果集的模式可能取决于绑定参数，因此这些模式可能不会在此处作为结果提供，或者如果提供，它们可能不准确。客户端不应假设此处提供的模式将是实际由执行准备好的语句返回的任何数据的模式。
某些语句可能具有没有特定类型的绑定参数。（作为 SQL 的一个简单示例，请考虑
SELECT ?。）目前没有指定如何在上面的绑定参数模式中处理这种情况。我们建议使用联合类型来枚举可能的类型，或者使用 NA（空）类型作为通配符/占位符。CommandPreparedStatementQuery执行先前创建的准备好的语句并获取结果。
与 DoPut 一起使用时：将参数值绑定到准备好的语句。服务器可以选择在响应中提供更新的句柄。更新句柄允许客户端提供执行查询所需的全部状态，这些状态包含在 ActionPreparedStatementExecute 消息中。例如，无状态服务器可以将绑定参数值编码到新句柄中，客户端将使用该新句柄将参数发送回服务器。
请注意，从使用 CommandPreparedStatementQuery 的 DoPut 调用返回的句柄本身可以传递到使用 CommandPreparedStatementQuery 的后续 DoPut 调用，以绑定一组新的参数。后续调用本身可能会返回一个更新的句柄，该句柄也应用于后续请求。
服务器负责检测客户端未使用更新句柄的情况，并应返回错误。
与 GetFlightInfo 一起使用时：执行准备好的语句。准备好的语句可以在获取结果后重复使用。
与 GetSchema 一起使用时：获取结果集的预期 Arrow 模式。如果客户端之前已使用 DoPut 绑定参数值，则服务器应考虑这些值。
CommandPreparedStatementUpdate执行先前创建的不会返回结果的准备好的语句。
与 DoPut 一起使用时：执行查询并返回受影响的行数。准备好的语句之后可以重复使用。
CommandStatementQuery执行临时 SQL 查询。
与 GetFlightInfo 一起使用时：执行查询（调用 DoGet 以获取结果）。
与 GetSchema 一起使用时：返回查询结果的模式。
CommandStatementUpdate执行不会返回结果的临时 SQL 查询。
与 DoPut 一起使用时：执行查询并返回受影响的行数。
Flight 服务器会话管理#
Flight SQL 提供命令来设置和更新服务器会话变量，这些变量以各种方式影响服务器行为。常见选项可能包括（取决于服务器实现）catalog 和 schema，指示要针对其运行查询的当前选定目录和模式。
客户端应尽可能优先在发出查询和其他命令之前设置选项，因为某些服务器实现可能要求这些选项恰好设置一次，并且在可能触发其隐式设置的任何其他活动之前设置。
为了与数据库连接驱动程序（JDBC、ODBC 等）兼容，强烈建议服务器实现接受所有选项值的字符串表示形式，这些值可以作为服务器连接字符串的一部分提供给驱动程序，并通过服务器传递，而无需进一步转换。为了便于使用，还建议接受和转换其他数字类型以转换为选项值的首选类型，但这并非必需。
会话通过实现定义的机制在客户端和服务器之间持久保存，该机制通常是 RFC 6265 cookie。服务器还可以将其他连接状态与会话令牌不透明地组合在一起：请考虑会话的寿命和语义对于任何其他用途都应该有意义，例如 CloseSession 还将使通过会话上下文持久保存的任何身份验证上下文失效。会话可以在非空（或空）SetSessionOptions 调用时启动，或者在服务器选择的任何其他时间启动。
SetSessionOptions 通过名称/值设置服务器会话选项。
GetSessionOptions 获取当前服务器会话选项，包括由客户端设置的选项以及由服务器默认或隐式设置的选项。
CloseSession 关闭并使当前会话上下文失效。
时序图#
列出可用的表。#
执行临时查询。#
创建准备好的语句，然后执行它。#
外部资源#
协议缓冲区定义#
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/gen/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 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 same 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 cannot be determined.
1027 */
1028 NULLABILITY_UNKNOWN = 2;
1029}
1030
1031enum Searchable {
1032 /**
1033 * Indicates that column cannot 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 result set. It should be an IPC-encapsulated Schema, as described in Schema.fbs.
1541 // For some queries, the schema of the results may depend on the schema of the parameters. The server
1542 // should provide its best guess as to the schema at this point. Clients must not assume that this
1543 // schema, if provided, will be accurate.
1544 bytes dataset_schema = 2;
1545
1546 // If the query provided contained parameters, parameter_schema contains the
1547 // schema of the expected parameters. It should be an IPC-encapsulated Schema, as described in Schema.fbs.
1548 bytes parameter_schema = 3;
1549}
1550
1551/*
1552 * Request message for the "ClosePreparedStatement" action on a Flight SQL enabled backend.
1553 * Closes server resources associated with the prepared statement handle.
1554 */
1555message ActionClosePreparedStatementRequest {
1556 option (experimental) = true;
1557
1558 // Opaque handle for the prepared statement on the server.
1559 bytes prepared_statement_handle = 1;
1560}
1561
1562/*
1563 * Request message for the "BeginTransaction" action.
1564 * Begins a transaction.
1565 */
1566message ActionBeginTransactionRequest {
1567 option (experimental) = true;
1568}
1569
1570/*
1571 * Request message for the "BeginSavepoint" action.
1572 * Creates a savepoint within a transaction.
1573 *
1574 * Only supported if FLIGHT_SQL_TRANSACTION is
1575 * FLIGHT_SQL_TRANSACTION_SUPPORT_SAVEPOINT.
1576 */
1577message ActionBeginSavepointRequest {
1578 option (experimental) = true;
1579
1580 // The transaction to which a savepoint belongs.
1581 bytes transaction_id = 1;
1582 // Name for the savepoint.
1583 string name = 2;
1584}
1585
1586/*
1587 * The result of a "BeginTransaction" action.
1588 *
1589 * The transaction can be manipulated with the "EndTransaction" action, or
1590 * automatically via server timeout. If the transaction times out, then it is
1591 * automatically rolled back.
1592 *
1593 * The result should be wrapped in a google.protobuf.Any message.
1594 */
1595message ActionBeginTransactionResult {
1596 option (experimental) = true;
1597
1598 // Opaque handle for the transaction on the server.
1599 bytes transaction_id = 1;
1600}
1601
1602/*
1603 * The result of a "BeginSavepoint" action.
1604 *
1605 * The transaction can be manipulated with the "EndSavepoint" action.
1606 * If the associated transaction is committed, rolled back, or times
1607 * out, then the savepoint is also invalidated.
1608 *
1609 * The result should be wrapped in a google.protobuf.Any message.
1610 */
1611message ActionBeginSavepointResult {
1612 option (experimental) = true;
1613
1614 // Opaque handle for the savepoint on the server.
1615 bytes savepoint_id = 1;
1616}
1617
1618/*
1619 * Request message for the "EndTransaction" action.
1620 *
1621 * Commit (COMMIT) or rollback (ROLLBACK) the transaction.
1622 *
1623 * If the action completes successfully, the transaction handle is
1624 * invalidated, as are all associated savepoints.
1625 */
1626message ActionEndTransactionRequest {
1627 option (experimental) = true;
1628
1629 enum EndTransaction {
1630 END_TRANSACTION_UNSPECIFIED = 0;
1631 // Commit the transaction.
1632 END_TRANSACTION_COMMIT = 1;
1633 // Roll back the transaction.
1634 END_TRANSACTION_ROLLBACK = 2;
1635 }
1636 // Opaque handle for the transaction on the server.
1637 bytes transaction_id = 1;
1638 // Whether to commit/rollback the given transaction.
1639 EndTransaction action = 2;
1640}
1641
1642/*
1643 * Request message for the "EndSavepoint" action.
1644 *
1645 * Release (RELEASE) the savepoint or rollback (ROLLBACK) to the
1646 * savepoint.
1647 *
1648 * Releasing a savepoint invalidates that savepoint. Rolling back to
1649 * a savepoint does not invalidate the savepoint, but invalidates all
1650 * savepoints created after the current savepoint.
1651 */
1652message ActionEndSavepointRequest {
1653 option (experimental) = true;
1654
1655 enum EndSavepoint {
1656 END_SAVEPOINT_UNSPECIFIED = 0;
1657 // Release the savepoint.
1658 END_SAVEPOINT_RELEASE = 1;
1659 // Roll back to a savepoint.
1660 END_SAVEPOINT_ROLLBACK = 2;
1661 }
1662 // Opaque handle for the savepoint on the server.
1663 bytes savepoint_id = 1;
1664 // Whether to rollback/release the given savepoint.
1665 EndSavepoint action = 2;
1666}
1667
1668// Query Execution Messages.
1669
1670/*
1671 * Represents a SQL query. Used in the command member of FlightDescriptor
1672 * for the following RPC calls:
1673 * - GetSchema: return the Arrow schema of the query.
1674 * Fields on this schema may contain the following metadata:
1675 * - ARROW:FLIGHT:SQL:CATALOG_NAME - Table's catalog name
1676 * - ARROW:FLIGHT:SQL:DB_SCHEMA_NAME - Database schema name
1677 * - ARROW:FLIGHT:SQL:TABLE_NAME - Table name
1678 * - ARROW:FLIGHT:SQL:TYPE_NAME - The data source-specific name for the data type of the column.
1679 * - ARROW:FLIGHT:SQL:PRECISION - Column precision/size
1680 * - ARROW:FLIGHT:SQL:SCALE - Column scale/decimal digits if applicable
1681 * - ARROW:FLIGHT:SQL:IS_AUTO_INCREMENT - "1" indicates if the column is auto incremented, "0" otherwise.
1682 * - ARROW:FLIGHT:SQL:IS_CASE_SENSITIVE - "1" indicates if the column is case-sensitive, "0" otherwise.
1683 * - ARROW:FLIGHT:SQL:IS_READ_ONLY - "1" indicates if the column is read only, "0" otherwise.
1684 * - ARROW:FLIGHT:SQL:IS_SEARCHABLE - "1" indicates if the column is searchable via WHERE clause, "0" otherwise.
1685 * - GetFlightInfo: execute the query.
1686 */
1687message CommandStatementQuery {
1688 option (experimental) = true;
1689
1690 // The SQL syntax.
1691 string query = 1;
1692 // Include the query as part of this transaction (if unset, the query is auto-committed).
1693 optional bytes transaction_id = 2;
1694}
1695
1696/*
1697 * Represents a Substrait plan. Used in the command member of FlightDescriptor
1698 * for the following RPC calls:
1699 * - GetSchema: return the Arrow schema of the query.
1700 * Fields on this schema may contain the following metadata:
1701 * - ARROW:FLIGHT:SQL:CATALOG_NAME - Table's catalog name
1702 * - ARROW:FLIGHT:SQL:DB_SCHEMA_NAME - Database schema name
1703 * - ARROW:FLIGHT:SQL:TABLE_NAME - Table name
1704 * - ARROW:FLIGHT:SQL:TYPE_NAME - The data source-specific name for the data type of the column.
1705 * - ARROW:FLIGHT:SQL:PRECISION - Column precision/size
1706 * - ARROW:FLIGHT:SQL:SCALE - Column scale/decimal digits if applicable
1707 * - ARROW:FLIGHT:SQL:IS_AUTO_INCREMENT - "1" indicates if the column is auto incremented, "0" otherwise.
1708 * - ARROW:FLIGHT:SQL:IS_CASE_SENSITIVE - "1" indicates if the column is case-sensitive, "0" otherwise.
1709 * - ARROW:FLIGHT:SQL:IS_READ_ONLY - "1" indicates if the column is read only, "0" otherwise.
1710 * - ARROW:FLIGHT:SQL:IS_SEARCHABLE - "1" indicates if the column is searchable via WHERE clause, "0" otherwise.
1711 * - GetFlightInfo: execute the query.
1712 * - DoPut: execute the query.
1713 */
1714message CommandStatementSubstraitPlan {
1715 option (experimental) = true;
1716
1717 // A serialized substrait.Plan
1718 SubstraitPlan plan = 1;
1719 // Include the query as part of this transaction (if unset, the query is auto-committed).
1720 optional bytes transaction_id = 2;
1721}
1722
1723/**
1724 * Represents a ticket resulting from GetFlightInfo with a CommandStatementQuery.
1725 * This should be used only once and treated as an opaque value, that is, clients should not attempt to parse this.
1726 */
1727message TicketStatementQuery {
1728 option (experimental) = true;
1729
1730 // Unique identifier for the instance of the statement to execute.
1731 bytes statement_handle = 1;
1732}
1733
1734/*
1735 * Represents an instance of executing a prepared statement. Used in the command member of FlightDescriptor for
1736 * the following RPC calls:
1737 * - GetSchema: return the Arrow schema of the query.
1738 * Fields on this schema may contain the following metadata:
1739 * - ARROW:FLIGHT:SQL:CATALOG_NAME - Table's catalog name
1740 * - ARROW:FLIGHT:SQL:DB_SCHEMA_NAME - Database schema name
1741 * - ARROW:FLIGHT:SQL:TABLE_NAME - Table name
1742 * - ARROW:FLIGHT:SQL:TYPE_NAME - The data source-specific name for the data type of the column.
1743 * - ARROW:FLIGHT:SQL:PRECISION - Column precision/size
1744 * - ARROW:FLIGHT:SQL:SCALE - Column scale/decimal digits if applicable
1745 * - ARROW:FLIGHT:SQL:IS_AUTO_INCREMENT - "1" indicates if the column is auto incremented, "0" otherwise.
1746 * - ARROW:FLIGHT:SQL:IS_CASE_SENSITIVE - "1" indicates if the column is case-sensitive, "0" otherwise.
1747 * - ARROW:FLIGHT:SQL:IS_READ_ONLY - "1" indicates if the column is read only, "0" otherwise.
1748 * - ARROW:FLIGHT:SQL:IS_SEARCHABLE - "1" indicates if the column is searchable via WHERE clause, "0" otherwise.
1749 *
1750 * If the schema is retrieved after parameter values have been bound with DoPut, then the server should account
1751 * for the parameters when determining the schema.
1752 * - DoPut: bind parameter values. All of the bound parameter sets will be executed as a single atomic execution.
1753 * - GetFlightInfo: execute the prepared statement instance.
1754 */
1755message CommandPreparedStatementQuery {
1756 option (experimental) = true;
1757
1758 // Opaque handle for the prepared statement on the server.
1759 bytes prepared_statement_handle = 1;
1760}
1761
1762/*
1763 * Represents a SQL update query. Used in the command member of FlightDescriptor
1764 * for the RPC call DoPut to cause the server to execute the included SQL update.
1765 */
1766message CommandStatementUpdate {
1767 option (experimental) = true;
1768
1769 // The SQL syntax.
1770 string query = 1;
1771 // Include the query as part of this transaction (if unset, the query is auto-committed).
1772 optional bytes transaction_id = 2;
1773}
1774
1775/*
1776 * Represents a SQL update query. Used in the command member of FlightDescriptor
1777 * for the RPC call DoPut to cause the server to execute the included
1778 * prepared statement handle as an update.
1779 */
1780message CommandPreparedStatementUpdate {
1781 option (experimental) = true;
1782
1783 // Opaque handle for the prepared statement on the server.
1784 bytes prepared_statement_handle = 1;
1785}
1786
1787/*
1788 * Returned from the RPC call DoPut when a CommandStatementUpdate
1789 * CommandPreparedStatementUpdate was in the request, containing
1790 * results from the update.
1791 */
1792message DoPutUpdateResult {
1793 option (experimental) = true;
1794
1795 // The number of records updated. A return value of -1 represents
1796 // an unknown updated record count.
1797 int64 record_count = 1;
1798}
1799
1800/* An *optional* response returned when `DoPut` is called with `CommandPreparedStatementQuery`.
1801 *
1802 * *Note on legacy behavior*: previous versions of the protocol did not return any result for
1803 * this command, and that behavior should still be supported by clients. In that case, the client
1804 * can continue as though the fields in this message were not provided or set to sensible default values.
1805 */
1806message DoPutPreparedStatementResult {
1807 option (experimental) = true;
1808
1809 // Represents a (potentially updated) opaque handle for the prepared statement on the server.
1810 // Because the handle could potentially be updated, any previous handles for this prepared
1811 // statement should be considered invalid, and all subsequent requests for this prepared
1812 // statement must use this new handle.
1813 // The updated handle allows implementing query parameters with stateless services.
1814 //
1815 // When an updated handle is not provided by the server, clients should contiue
1816 // using the previous handle provided by `ActionCreatePreparedStatementResonse`.
1817 optional bytes prepared_statement_handle = 1;
1818}
1819
1820/*
1821 * Request message for the "CancelQuery" action.
1822 *
1823 * Explicitly cancel a running query.
1824 *
1825 * This lets a single client explicitly cancel work, no matter how many clients
1826 * are involved/whether the query is distributed or not, given server support.
1827 * The transaction/statement is not rolled back; it is the application's job to
1828 * commit or rollback as appropriate. This only indicates the client no longer
1829 * wishes to read the remainder of the query results or continue submitting
1830 * data.
1831 *
1832 * This command is idempotent.
1833 *
1834 * This command is deprecated since 13.0.0. Use the "CancelFlightInfo"
1835 * action with DoAction instead.
1836 */
1837message ActionCancelQueryRequest {
1838 option deprecated = true;
1839 option (experimental) = true;
1840
1841 // The result of the GetFlightInfo RPC that initiated the query.
1842 // XXX(ARROW-16902): this must be a serialized FlightInfo, but is
1843 // rendered as bytes because Protobuf does not really support one
1844 // DLL using Protobuf definitions from another DLL.
1845 bytes info = 1;
1846}
1847
1848/*
1849 * The result of cancelling a query.
1850 *
1851 * The result should be wrapped in a google.protobuf.Any message.
1852 *
1853 * This command is deprecated since 13.0.0. Use the "CancelFlightInfo"
1854 * action with DoAction instead.
1855 */
1856message ActionCancelQueryResult {
1857 option deprecated = true;
1858 option (experimental) = true;
1859
1860 enum CancelResult {
1861 // The cancellation status is unknown. Servers should avoid using
1862 // this value (send a NOT_FOUND error if the requested query is
1863 // not known). Clients can retry the request.
1864 CANCEL_RESULT_UNSPECIFIED = 0;
1865 // The cancellation request is complete. Subsequent requests with
1866 // the same payload may return CANCELLED or a NOT_FOUND error.
1867 CANCEL_RESULT_CANCELLED = 1;
1868 // The cancellation request is in progress. The client may retry
1869 // the cancellation request.
1870 CANCEL_RESULT_CANCELLING = 2;
1871 // The query is not cancellable. The client should not retry the
1872 // cancellation request.
1873 CANCEL_RESULT_NOT_CANCELLABLE = 3;
1874 }
1875
1876 CancelResult result = 1;
1877}
1878
1879extend google.protobuf.MessageOptions {
1880 bool experimental = 1000;
1881}