Skip to content

Commit

Permalink
[WIP] FlightSQL Ratification based on Community Comments (apache#73)
Browse files Browse the repository at this point in the history 
* Move FlightSql examples to their own subpackage

* Fix checkstyle issues

* fix: change Status use to CallStatus

* Remove unnecessary overhead of wrapping nullable objects into Optionals for the sole purpose of null-checking

* Replace Guava's Preconditions with the ones provided by Apache

* Fix typo in FlightSql.proto

* Fix ordering of schema for FlightSql.proto

* Explain why reserved range of IDs for GetSqlInfo is not entirely in use

* Add comment to CommandGetTables to explain the encoding of table_schema

* Remove redundat information on schemas

* Fixed Javadoc on some methods, added Thread interrupt to executeUpdate methods, and updated Signal exceptions to CallStatus with description

* Replace int32 with uint32 for GetSqlInfo name representation

* Replace AssertionError with StatusRuntimeException for whenever attempting to unpack an invalid protobuf message

* add comment to FlightSql.proto to update_rule and delete_rule

* Replace inconsistent exception handling with CallStatus predetermined exceptions

* correct comment to CreatePreparedStatement on FlightSql.proto

* Remove unused dependencies

* fix: change Status use to CallStatus on FlightSqlProducer

* Changed from if not null check to Objects requireNonNull on Flight SQL Client

* Remove Nullable annotation

* Changed from checkNotNull to Objects#requireNotNull with description on Flight SQL Example

* Add CallOptions to every RPC call by the client

* Fix Maven dependency problems and checkstyle violations

* Replace generic Collections with Lists when order matters in an RPC call

* Fix Javadoc for FlightSqlClient

* Add description to StatusRuntimeExceptions

* Add descriptions to Exceptions

* Correct update_rule and delete_rule description on FlighSql.proto

* Verify wheter Root is empty before sending request to server

* Add call options to PreparedStatement

* Replace constant checking of whether client is open with #checkOpen

* Add CallOptions to #close for PreparedStatement

* Refactor PreparedStatement usages of CallOptions

* Fix broken tests

* Fix FlightSql.proto documentation

* Update documentation for format/FlightSql.proto

Co-authored-by: kylep-dremio <38920967+kylep-dremio@users.noreply.github.com>

* Fix checkstyle violations

* Require non null tables for GetExportedKeys and GetImportedKeys

* Not storing CallOptions in PreparedStatement

* Update documentation comments for protobuf

* Replace IntVector for UInt1Vector for delete_rule and update_rule

* Fix protobuf for FlightSQL

* Fix bug with empty metadata

* Update update_rule and delete_rule documentation on proto

* Remove explicit dependency on JDBC's DatabaseMetaData on UpdateDeleteRules

* Use MessageOptions instead of FieldOptions on proto

* Add missing JavaDoc about 'options' parameter

* Fix CommandGetSqlInfo documentation

* Add @throws to FlightSqlClient#checkOpen JavaDoc

Co-authored-by: Juscelino Junior <juscelinojunior@id.uff.br>
Co-authored-by: Vinicius Fraga <sxvinifp@gmail.com>
Co-authored-by: Rafael Telles <rafael@telles.dev>
Co-authored-by: kylep-dremio <38920967+kylep-dremio@users.noreply.github.com>
  • Loading branch information
@JrJuscelino @vfraga
@rafael-telles @kylep-dremio
5 people committed Aug 17, 2021
1 parent a28bd4b commit 783ffaf
Show file tree
Hide file tree
Showing 9 changed files with 378 additions and 244 deletions.
69 changes: 58 additions & 11 deletions format/FlightSql.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@

syntax = "proto3";
import "google/protobuf/wrappers.proto";
import "google/protobuf/descriptor.proto";

option java_package = "org.apache.arrow.flight.sql.impl";
package arrow.flight.protocol.sql;
Expand All @@ -30,12 +31,14 @@ package arrow.flight.protocol.sql;
*
* The returned schema will be:
* <
* info_name: int32,
* info_name: uint32,
* value: dense_union<string_value: string, int_value: int32, bigint_value: int64, int32_bitmask: int32>
* >
* where there is one row per requested piece of metadata information.
*/
message CommandGetSqlInfo {
option (experimental) = true;

/*
* Values are modelled after ODBC's SQLGetInfo() function. This information is intended to provide
* Flight SQL clients with basic, SQL syntax and SQL functions related information.
Expand All @@ -46,7 +49,7 @@ message CommandGetSqlInfo {
*
* Initially, Flight SQL will support the following information types:
* - Server Information - Range [0-500)
* - Syntax Information - Ragne [500-1000)
* - Syntax Information - Range [500-1000)
* Range [0-100000) is reserved for defaults. Custom options should start at 100000.
*
* 1. Server Information [0-500): Provides basic information about the Flight SQL Server.
Expand Down Expand Up @@ -89,7 +92,7 @@ message CommandGetSqlInfo {
*
* If omitted, then all metadata will be retrieved.
* Flight SQL Servers may choose to include additional metadata above and beyond the specified set, however they must
* at least return the specified set. IDs ranging from 0 to 10,000 (exclusive) are reserved.
* at least return the specified set. IDs ranging from 0 to 10,000 (exclusive) are reserved for future use.
* If additional metadata is included, the metadata IDs should start from 10,000.
*/
repeated uint32 info = 1;
Expand All @@ -108,6 +111,7 @@ message CommandGetSqlInfo {
* The returned data should be ordered by catalog_name.
*/
message CommandGetCatalogs {
option (experimental) = true;
}

/*
Expand All @@ -124,6 +128,8 @@ message CommandGetCatalogs {
* The returned data should be ordered by catalog_name, then schema_name.
*/
message CommandGetSchemas {
option (experimental) = true;

/*
* Specifies the Catalog to search for schemas.
* If omitted, then all catalogs are searched.
Expand Down Expand Up @@ -152,11 +158,13 @@ message CommandGetSchemas {
* schema_name: utf8,
* table_name: utf8,
* table_type: utf8,
* table_schema: bytes
* table_schema: bytes (schema of the table as described in Schema.fbs::Schema, it is serialized as an IPC message.)
* >
* The returned data should be ordered by catalog_name, schema_name, table_name, then table_type.
*/
message CommandGetTables {
option (experimental) = true;

/*
* Specifies the Catalog to search for the tables.
* If omitted, then all catalogs are searched.
Expand Down Expand Up @@ -201,6 +209,7 @@ message CommandGetTables {
* The returned data should be ordered by table_type.
*/
message CommandGetTableTypes {
option (experimental) = true;
}

/*
Expand All @@ -215,12 +224,14 @@ message CommandGetTableTypes {
* schema_name: utf8,
* table_name: utf8,
* column_name: utf8,
* key_sequence: int,
* key_name: utf8
* key_sequence: int,
* >
* The returned data should be ordered by catalog_name, schema_name, table_name, key_name, then key_sequence.
*/
message CommandGetPrimaryKeys {
option (experimental) = true;

// Specifies the catalog to search for the table.
google.protobuf.StringValue catalog = 1;

Expand Down Expand Up @@ -251,12 +262,20 @@ message CommandGetPrimaryKeys {
* key_sequence: int,
* fk_key_name: utf8,
* pk_key_name: utf8,
* update_rule: int,
* delete_rule: int
* update_rule: uint1,
* delete_rule: uint1
* >
* The returned data should be ordered by catalog_name, schema_name, table_name, key_name, then key_sequence.
* update_rule and delete_rule returns a byte that is equivalent to actions:
* - 0 = CASCADE
* - 1 = RESTRICT
* - 2 = SET NULL
* - 3 = NO ACTION
* - 4 = SET DEFAULT
*/
message CommandGetExportedKeys {
option (experimental) = true;

// Specifies the catalog to search for the foreign key table.
google.protobuf.StringValue catalog = 1;

Expand Down Expand Up @@ -286,12 +305,20 @@ message CommandGetExportedKeys {
* key_sequence: int,
* fk_key_name: utf8,
* pk_key_name: utf8,
* update_rule: int,
* delete_rule: int
* update_rule: uint1,
* delete_rule: uint1
* >
* The returned data should be ordered by catalog_name, schema_name, table_name, key_name, then key_sequence.
* update_rule and delete_rule returns a byte that is equivalent to actions:
* - 0 = CASCADE
* - 1 = RESTRICT
* - 2 = SET NULL
* - 3 = NO ACTION
* - 4 = SET DEFAULT
*/
message CommandGetImportedKeys {
option (experimental) = true;

// Specifies the catalog to search for the primary key table.
google.protobuf.StringValue catalog = 1;

Expand All @@ -305,9 +332,11 @@ message CommandGetImportedKeys {
// SQL Execution Action Messages

/*
* Request message for the "GetPreparedStatement" action on a Flight SQL enabled backend.
* Request message for the "CreatePreparedStatement" action on a Flight SQL enabled backend.
*/
message ActionCreatePreparedStatementRequest {
option (experimental) = true;

// The valid SQL string to create a prepared statement for.
string query = 1;
}
Expand All @@ -316,6 +345,8 @@ message ActionCreatePreparedStatementRequest {
* Wrap the result of a "GetPreparedStatement" action.
*/
message ActionCreatePreparedStatementResult {
option (experimental) = true;

// Opaque handle for the prepared statement on the server.
bytes prepared_statement_handle = 1;

Expand All @@ -324,7 +355,7 @@ message ActionCreatePreparedStatementResult {
bytes dataset_schema = 2;

// If the query provided contained parameters, parameter_schema contains the
// Schema of the expected parameters as described in Schema.fbs::Schema.
// schema of the expected parameters as described in Schema.fbs::Schema, it is serialized as an IPC message.
bytes parameter_schema = 3;
}

Expand All @@ -333,6 +364,8 @@ message ActionCreatePreparedStatementResult {
* Closes server resources associated with the prepared statement handle.
*/
message ActionClosePreparedStatementRequest {
option (experimental) = true;

// Opaque handle for the prepared statement on the server.
bytes prepared_statement_handle = 1;
}
Expand All @@ -347,6 +380,8 @@ message ActionClosePreparedStatementRequest {
* - GetFlightInfo: execute the query.
*/
message CommandStatementQuery {
option (experimental) = true;

// The SQL syntax.
string query = 1;

Expand All @@ -361,6 +396,8 @@ message CommandStatementQuery {
* - GetFlightInfo: execute the prepared statement instance.
*/
message CommandPreparedStatementQuery {
option (experimental) = true;

// Unique identifier for the instance of the prepared statement to execute.
bytes client_execution_handle = 1;

Expand All @@ -373,6 +410,8 @@ message CommandPreparedStatementQuery {
* for the the RPC call DoPut to cause the server to execute the included SQL update.
*/
message CommandStatementUpdate {
option (experimental) = true;

// The SQL syntax.
string query = 1;
}
Expand All @@ -383,6 +422,8 @@ message CommandStatementUpdate {
* prepared statement handle as an update.
*/
message CommandPreparedStatementUpdate {
option (experimental) = true;

// Unique identifier for the instance of the prepared statement to execute.
bytes client_execution_handle = 1;

Expand All @@ -396,7 +437,13 @@ message CommandPreparedStatementUpdate {
* results from the update.
*/
message DoPutUpdateResult {
option (experimental) = true;

// The number of records updated. A return value of -1 represents
// an unknown updated record count.
int64 record_count = 1;
}

extend google.protobuf.MessageOptions {
bool experimental = 1000;
}
4 changes: 0 additions & 4 deletions java/flight/flight-sql/pom.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -129,10 +129,6 @@
<groupId>org.hamcrest</groupId>
<artifactId>hamcrest</artifactId>
</dependency>
<dependency>
<groupId>com.google.code.findbugs</groupId>
<artifactId>jsr305</artifactId>
</dependency>
</dependencies>

<build>
Expand Down

0 comments on commit 783ffaf

Please sign in to comment.