Namespace Arrow.Flight.Protocol.Sql

Classes

Request message for the "BeginSavepoint" action. Creates a savepoint within a transaction.

Only supported if FLIGHT_SQL_TRANSACTION is FLIGHT_SQL_TRANSACTION_SUPPORT_SAVEPOINT.

The result of a "BeginSavepoint" action.

The transaction can be manipulated with the "EndSavepoint" action. If the associated transaction is committed, rolled back, or times out, then the savepoint is also invalidated.

The result should be wrapped in a google.protobuf.Any message.

ActionBeginTransactionRequest: Request message for the "BeginTransaction" action. Begins a transaction.

ActionBeginTransactionResult

The result of a "BeginTransaction" action.

The transaction can be manipulated with the "EndTransaction" action, or automatically via server timeout. If the transaction times out, then it is automatically rolled back.

The result should be wrapped in a google.protobuf.Any message.

ActionCancelQueryRequest

Request message for the "CancelQuery" action.

Explicitly cancel a running query.

This lets a single client explicitly cancel work, no matter how many clients are involved/whether the query is distributed or not, given server support. The transaction/statement is not rolled back; it is the application's job to commit or rollback as appropriate. This only indicates the client no longer wishes to read the remainder of the query results or continue submitting data.

This command is idempotent.

This command is deprecated since 13.0.0. Use the "CancelFlightInfo" action with DoAction instead.

ActionCancelQueryResult

The result of cancelling a query.

The result should be wrapped in a google.protobuf.Any message.

This command is deprecated since 13.0.0. Use the "CancelFlightInfo" action with DoAction instead.

ActionCancelQueryResult.Types: Container for nested types declared in the ActionCancelQueryResult message type.

ActionClosePreparedStatementRequest: Request message for the "ClosePreparedStatement" action on a Flight SQL enabled backend. Closes server resources associated with the prepared statement handle.

ActionCreatePreparedStatementRequest: Request message for the "CreatePreparedStatement" action on a Flight SQL enabled backend.

ActionCreatePreparedStatementResult

Wrap the result of a "CreatePreparedStatement" or "CreatePreparedSubstraitPlan" action.

The resultant PreparedStatement can be closed either:

Manually, through the "ClosePreparedStatement" action;
Automatically, by a server timeout.

The result should be wrapped in a google.protobuf.Any message.

ActionCreatePreparedSubstraitPlanRequest: Request message for the "CreatePreparedSubstraitPlan" action on a Flight SQL enabled backend.

ActionEndSavepointRequest

Request message for the "EndSavepoint" action.

Release (RELEASE) the savepoint or rollback (ROLLBACK) to the savepoint.

Releasing a savepoint invalidates that savepoint. Rolling back to a savepoint does not invalidate the savepoint, but invalidates all savepoints created after the current savepoint.

ActionEndSavepointRequest.Types: Container for nested types declared in the ActionEndSavepointRequest message type.

ActionEndTransactionRequest

Request message for the "EndTransaction" action.

Commit (COMMIT) or rollback (ROLLBACK) the transaction.

If the action completes successfully, the transaction handle is invalidated, as are all associated savepoints.

ActionEndTransactionRequest.Types: Container for nested types declared in the ActionEndTransactionRequest message type.

CommandGetCatalogs

Represents a request to retrieve the list of catalogs on a Flight SQL enabled backend. The definition of a catalog depends on vendor/implementation. It is usually the database itself Used in the command member of FlightDescriptor for the following RPC calls:

GetSchema: return the Arrow schema of the query.
GetFlightInfo: execute the catalog metadata request.

The returned Arrow schema will be: < catalog_name: utf8 not null

The returned data should be ordered by catalog_name.

CommandGetCrossReference

Represents a request to retrieve a description of the foreign key columns in the given foreign key table that reference the primary key or the columns representing a unique constraint of the parent table (could be the same or a different table) on a Flight SQL enabled backend. Used in the command member of FlightDescriptor for the following RPC calls:

GetSchema: return the Arrow schema of the query.
GetFlightInfo: execute the catalog metadata request.

The returned Arrow schema will be: < pk_catalog_name: utf8, pk_db_schema_name: utf8, pk_table_name: utf8 not null, pk_column_name: utf8 not null, fk_catalog_name: utf8, fk_db_schema_name: utf8, fk_table_name: utf8 not null, fk_column_name: utf8 not null, key_sequence: int32 not null, fk_key_name: utf8, pk_key_name: utf8, update_rule: uint8 not null, delete_rule: uint8 not null

The returned data should be ordered by pk_catalog_name, pk_db_schema_name, pk_table_name, pk_key_name, then key_sequence. update_rule and delete_rule returns a byte that is equivalent to actions:

0 = CASCADE
1 = RESTRICT
2 = SET NULL
3 = NO ACTION
4 = SET DEFAULT

CommandGetDbSchemas

Represents a request to retrieve the list of database schemas on a Flight SQL enabled backend. The definition of a database schema depends on vendor/implementation. It is usually a collection of tables. Used in the command member of FlightDescriptor for the following RPC calls:

GetSchema: return the Arrow schema of the query.
GetFlightInfo: execute the catalog metadata request.

The returned Arrow schema will be: < catalog_name: utf8, db_schema_name: utf8 not null

The returned data should be ordered by catalog_name, then db_schema_name.

CommandGetExportedKeys

Represents a request to retrieve a description of the foreign key columns that reference the given table's primary key columns (the foreign keys exported by a table) of a table on a Flight SQL enabled backend. Used in the command member of FlightDescriptor for the following RPC calls:

GetSchema: return the Arrow schema of the query.
GetFlightInfo: execute the catalog metadata request.

The returned data should be ordered by fk_catalog_name, fk_db_schema_name, fk_table_name, fk_key_name, then key_sequence. update_rule and delete_rule returns a byte that is equivalent to actions declared on UpdateDeleteRules enum.

CommandGetImportedKeys

Represents a request to retrieve the foreign keys of a table on a Flight SQL enabled backend. Used in the command member of FlightDescriptor for the following RPC calls:

GetSchema: return the Arrow schema of the query.
GetFlightInfo: execute the catalog metadata request.

The returned data should be ordered by pk_catalog_name, pk_db_schema_name, pk_table_name, pk_key_name, then key_sequence. update_rule and delete_rule returns a byte that is equivalent to actions:

0 = CASCADE
1 = RESTRICT
2 = SET NULL
3 = NO ACTION
4 = SET DEFAULT

CommandGetPrimaryKeys

Represents a request to retrieve the primary keys of a table on a Flight SQL enabled backend. Used in the command member of FlightDescriptor for the following RPC calls:

GetSchema: return the Arrow schema of the query.
GetFlightInfo: execute the catalog metadata request.

The returned Arrow schema will be: < catalog_name: utf8, db_schema_name: utf8, table_name: utf8 not null, column_name: utf8 not null, key_name: utf8, key_sequence: int32 not null

The returned data should be ordered by catalog_name, db_schema_name, table_name, key_name, then key_sequence.

CommandGetSqlInfo

Represents a metadata request. Used in the command member of FlightDescriptor for the following RPC calls:

GetSchema: return the Arrow schema of the query.
GetFlightInfo: execute the metadata request.

The returned Arrow schema will be: < info_name: uint32 not null, value: dense_union< string_value: utf8, bool_value: bool, bigint_value: int64, int32_bitmask: int32, string_list: list<string_data: utf8> int32_to_int32_list_map: map<key: int32, value: list<\(data\): int32>>

where there is one row per requested piece of metadata information.

CommandGetTableTypes

Represents a request to retrieve the list of table types on a Flight SQL enabled backend. The table types depend on vendor/implementation. It is usually used to separate tables from views or system tables. TABLE, VIEW, and SYSTEM TABLE are commonly supported. Used in the command member of FlightDescriptor for the following RPC calls:

GetSchema: return the Arrow schema of the query.
GetFlightInfo: execute the catalog metadata request.

The returned Arrow schema will be: < table_type: utf8 not null

The returned data should be ordered by table_type.

CommandGetTables

Represents a request to retrieve the list of tables, and optionally their schemas, on a Flight SQL enabled backend. Used in the command member of FlightDescriptor for the following RPC calls:

GetSchema: return the Arrow schema of the query.
GetFlightInfo: execute the catalog metadata request.

The returned Arrow schema will be: < catalog_name: utf8, db_schema_name: utf8, table_name: utf8 not null, table_type: utf8 not null, [optional] table_schema: bytes not null (schema of the table as described in Schema.fbs::Schema, it is serialized as an IPC message.)

Fields on table_schema may contain the following metadata:

ARROW:FLIGHT:SQL:CATALOG_NAME - Table's catalog name
ARROW:FLIGHT:SQL:DB_SCHEMA_NAME - Database schema name
ARROW:FLIGHT:SQL:TABLE_NAME - Table name
ARROW:FLIGHT:SQL:TYPE_NAME - The data source-specific name for the data type of the column.
ARROW:FLIGHT:SQL:PRECISION - Column precision/size
ARROW:FLIGHT:SQL:SCALE - Column scale/decimal digits if applicable
ARROW:FLIGHT:SQL:IS_AUTO_INCREMENT - "1" indicates if the column is auto incremented, "0" otherwise.
ARROW:FLIGHT:SQL:IS_CASE_SENSITIVE - "1" indicates if the column is case-sensitive, "0" otherwise.
ARROW:FLIGHT:SQL:IS_READ_ONLY - "1" indicates if the column is read only, "0" otherwise.
ARROW:FLIGHT:SQL:IS_SEARCHABLE - "1" indicates if the column is searchable via WHERE clause, "0" otherwise.
ARROW:FLIGHT:SQL:REMARKS - A comment describing the column. This field has been added after all others, clients should be prepared to find it missing. The returned data should be ordered by catalog_name, db_schema_name, table_name, then table_type, followed by table_schema if requested.

CommandGetXdbcTypeInfo

Represents a request to retrieve information about data type supported on a Flight SQL enabled backend. Used in the command member of FlightDescriptor for the following RPC calls:

GetSchema: return the schema of the query.
GetFlightInfo: execute the catalog metadata request.

The returned schema will be: < type_name: utf8 not null (The name of the data type, for example: VARCHAR, INTEGER, etc), data_type: int32 not null (The SQL data type), column_size: int32 (The maximum size supported by that column. In case of exact numeric types, this represents the maximum precision. In case of string types, this represents the character length. In case of datetime data types, this represents the length in characters of the string representation. NULL is returned for data types where column size is not applicable.), literal_prefix: utf8 (Character or characters used to prefix a literal, NULL is returned for data types where a literal prefix is not applicable.), literal_suffix: utf8 (Character or characters used to terminate a literal, NULL is returned for data types where a literal suffix is not applicable.), create_params: list<utf8 not null> (A list of keywords corresponding to which parameters can be used when creating a column for that specific type. NULL is returned if there are no parameters for the data type definition.), nullable: int32 not null (Shows if the data type accepts a NULL value. The possible values can be seen in the Nullable enum.), case_sensitive: bool not null (Shows if a character data type is case-sensitive in collations and comparisons), searchable: int32 not null (Shows how the data type is used in a WHERE clause. The possible values can be seen in the Searchable enum.), unsigned_attribute: bool (Shows if the data type is unsigned. NULL is returned if the attribute is not applicable to the data type or the data type is not numeric.), fixed_prec_scale: bool not null (Shows if the data type has predefined fixed precision and scale.), auto_increment: bool (Shows if the data type is auto incremental. NULL is returned if the attribute is not applicable to the data type or the data type is not numeric.), local_type_name: utf8 (Localized version of the data source-dependent name of the data type. NULL is returned if a localized name is not supported by the data source), minimum_scale: int32 (The minimum scale of the data type on the data source. If a data type has a fixed scale, the MINIMUM_SCALE and MAXIMUM_SCALE columns both contain this value. NULL is returned if scale is not applicable.), maximum_scale: int32 (The maximum scale of the data type on the data source. NULL is returned if scale is not applicable.), sql_data_type: int32 not null (The value of the SQL DATA TYPE which has the same values as data_type value. Except for interval and datetime, which uses generic values. More info about those types can be obtained through datetime_subcode. The possible values can be seen in the XdbcDataType enum.), datetime_subcode: int32 (Only used when the SQL DATA TYPE is interval or datetime. It contains its sub types. For type different from interval and datetime, this value is NULL. The possible values can be seen in the XdbcDatetimeSubcode enum.), num_prec_radix: int32 (If the data type is an approximate numeric type, this column contains the value 2 to indicate that COLUMN_SIZE specifies a number of bits. For exact numeric types, this column contains the value 10 to indicate that column size specifies a number of decimal digits. Otherwise, this column is NULL.), interval_precision: int32 (If the data type is an interval data type, then this column contains the value of the interval leading precision. Otherwise, this column is NULL. This fields is only relevant to be used by ODBC).

The returned data should be ordered by data_type and then by type_name.

CommandPreparedStatementQuery

Represents an instance of executing a prepared statement. Used in the command member of FlightDescriptor for the following RPC calls:

GetSchema: return the Arrow schema of the query. Fields on this schema may contain the following metadata:
- ARROW:FLIGHT:SQL:CATALOG_NAME - Table's catalog name
- ARROW:FLIGHT:SQL:DB_SCHEMA_NAME - Database schema name
- ARROW:FLIGHT:SQL:TABLE_NAME - Table name
- ARROW:FLIGHT:SQL:TYPE_NAME - The data source-specific name for the data type of the column.
- ARROW:FLIGHT:SQL:PRECISION - Column precision/size
- ARROW:FLIGHT:SQL:SCALE - Column scale/decimal digits if applicable
- ARROW:FLIGHT:SQL:IS_AUTO_INCREMENT - "1" indicates if the column is auto incremented, "0" otherwise.
- ARROW:FLIGHT:SQL:IS_CASE_SENSITIVE - "1" indicates if the column is case-sensitive, "0" otherwise.
- ARROW:FLIGHT:SQL:IS_READ_ONLY - "1" indicates if the column is read only, "0" otherwise.
- ARROW:FLIGHT:SQL:IS_SEARCHABLE - "1" indicates if the column is searchable via WHERE clause, "0" otherwise.
- ARROW:FLIGHT:SQL:REMARKS - A comment describing the column. This field has been added after all others, clients should be prepared to find it missing.
If the schema is retrieved after parameter values have been bound with DoPut, then the server should account for the parameters when determining the schema.
DoPut: bind parameter values. All of the bound parameter sets will be executed as a single atomic execution.
GetFlightInfo: execute the prepared statement instance.

CommandPreparedStatementUpdate: Represents a SQL update query. Used in the command member of FlightDescriptor for the RPC call DoPut to cause the server to execute the included prepared statement handle as an update.

CommandStatementIngest: Represents a bulk ingestion request. Used in the command member of FlightDescriptor for the the RPC call DoPut to cause the server load the contents of the stream's FlightData into the target destination.

CommandStatementIngest.Types: Container for nested types declared in the CommandStatementIngest message type.

CommandStatementIngest.Types.TableDefinitionOptions: Options for table definition behavior

CommandStatementIngest.Types.TableDefinitionOptions.Types: Container for nested types declared in the TableDefinitionOptions message type.

CommandStatementQuery

Represents a SQL query. Used in the command member of FlightDescriptor for the following RPC calls:

GetSchema: return the Arrow schema of the query. Fields on this schema may contain the following metadata:
- ARROW:FLIGHT:SQL:CATALOG_NAME - Table's catalog name
- ARROW:FLIGHT:SQL:DB_SCHEMA_NAME - Database schema name
- ARROW:FLIGHT:SQL:TABLE_NAME - Table name
- ARROW:FLIGHT:SQL:TYPE_NAME - The data source-specific name for the data type of the column.
- ARROW:FLIGHT:SQL:PRECISION - Column precision/size
- ARROW:FLIGHT:SQL:SCALE - Column scale/decimal digits if applicable
- ARROW:FLIGHT:SQL:IS_AUTO_INCREMENT - "1" indicates if the column is auto incremented, "0" otherwise.
- ARROW:FLIGHT:SQL:IS_CASE_SENSITIVE - "1" indicates if the column is case-sensitive, "0" otherwise.
- ARROW:FLIGHT:SQL:IS_READ_ONLY - "1" indicates if the column is read only, "0" otherwise.
- ARROW:FLIGHT:SQL:IS_SEARCHABLE - "1" indicates if the column is searchable via WHERE clause, "0" otherwise.
- ARROW:FLIGHT:SQL:REMARKS - A comment describing the column. This field has been added after all others, clients should be prepared to find it missing.
GetFlightInfo: execute the query.

CommandStatementSubstraitPlan

Represents a Substrait plan. Used in the command member of FlightDescriptor for the following RPC calls:

GetSchema: return the Arrow schema of the query. Fields on this schema may contain the following metadata:
- ARROW:FLIGHT:SQL:CATALOG_NAME - Table's catalog name
- ARROW:FLIGHT:SQL:DB_SCHEMA_NAME - Database schema name
- ARROW:FLIGHT:SQL:TABLE_NAME - Table name
- ARROW:FLIGHT:SQL:TYPE_NAME - The data source-specific name for the data type of the column.
- ARROW:FLIGHT:SQL:PRECISION - Column precision/size
- ARROW:FLIGHT:SQL:SCALE - Column scale/decimal digits if applicable
- ARROW:FLIGHT:SQL:IS_AUTO_INCREMENT - "1" indicates if the column is auto incremented, "0" otherwise.
- ARROW:FLIGHT:SQL:IS_CASE_SENSITIVE - "1" indicates if the column is case-sensitive, "0" otherwise.
- ARROW:FLIGHT:SQL:IS_READ_ONLY - "1" indicates if the column is read only, "0" otherwise.
- ARROW:FLIGHT:SQL:IS_SEARCHABLE - "1" indicates if the column is searchable via WHERE clause, "0" otherwise.
- ARROW:FLIGHT:SQL:REMARKS - A comment describing the column. This field has been added after all others, clients should be prepared to find it missing.
GetFlightInfo: execute the query.
DoPut: execute the query.

CommandStatementUpdate: Represents a SQL update query. Used in the command member of FlightDescriptor for the RPC call DoPut to cause the server to execute the included SQL update.

DoPutPreparedStatementResult

An optional response returned when DoPut is called with CommandPreparedStatementQuery.

Note on legacy behavior: previous versions of the protocol did not return any result for this command, and that behavior should still be supported by clients. In that case, the client can continue as though the fields in this message were not provided or set to sensible default values.

DoPutUpdateResult: Returned from the RPC call DoPut when a CommandStatementUpdate, CommandPreparedStatementUpdate, or CommandStatementIngest was in the request, containing results from the update.

FlightSqlExtensions: Holder for extension identifiers generated from the top level of FlightSql.proto

FlightSqlReflection: Holder for reflection information generated from FlightSql.proto

SubstraitPlan: An embedded message describing a Substrait plan to execute.

TicketStatementQuery

Represents a ticket resulting from GetFlightInfo with a CommandStatementQuery. This should be used only once and treated as an opaque value, that is, clients should not attempt to parse this.