[WIP] [POC] Flight SQL

format/FlightSql.proto

@@ -0,0 +1,370 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ * <p>
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * <p>
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+syntax = "proto3";
+
+option java_package = "org.apache.arrow.flight.sql.impl";
+package arrow.flight.protocol.sql;
+
+/*
+ * Represents a metadata request. Used in the command member of FlightDescriptor
+ * for the following RPC calls:
+ *  - GetSchema: return the schema of the query.
+ *  - GetFlightInfo: execute the metadata request.
+ *
+ * The returned schema will be:
+ * <
+ *  info_name: utf8,
+ *  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 {
+  /*
+   * 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.
+   * More information types can be added in future releases.
+   * E.g. more SQL syntax support types, scalar functions support, type conversion support etc.
+   *
+   * // TODO: Flesh out the available set of metadata below.
+   *
+   * Initially, Flight SQL will support the following information types:
+   * - Server Information
+   * - Syntax Information
+   *
+   * 1. Server Information: Provides basic information about the Flight SQL Server.
+   *
+   * The name of the Flight SQL Server.
+   * FLIGHT_SQL_SERVER_NAME
+   *
+   * The native version of the Flight SQL Server.
+   * FLIGHT_SQL_SERVER_VERSION
+   *
+   * The Arrow format version of the Flight SQL Server.
+   * FLIGHT_SQL_SERVER_ARROW_VERSION
+   *
+   * Indicates whether the Flight SQL Server is read only.
+   * FLIGHT_SQL_SERVER_READ_ONLY
+   *
+   * 2. SQL Syntax Information: provides information about SQL syntax supported by the Flight SQL Server.
+   *
+   * Indicates whether the Flight SQL Server supports CREATE and DROP of catalogs.
+   * In a SQL environment, a catalog is a collection of schemas.
+   * SQL_DDL_CATALOG
+   *
+   * Indicates whether the Flight SQL Server supports CREATE and DROP of schemas.
+   * In a SQL environment, a catalog is a collection of tables, views, indexes etc.
+   * SQL_DDL_SCHEMA
+   *
+   * Indicates whether the Flight SQL Server supports CREATE and DROP of tables.
+   * In a SQL environment, a table is a collection of rows of information. Each row of information
+   * may have one or more columns of data.
+   * SQL_DDL_TABLE
+   *
+   * Indicates the case sensitivity of catalog, table and schema names.
+   * SQL_IDENTIFIER_CASE
+   *
+   * Indicates the supported character(s) used to surround a delimited identifier.
+   * SQL_IDENTIFIER_QUOTE_CHAR
+   *
+   * Indicates case sensitivity of quoted identifiers.
+   * SQL_QUOTED_IDENTIFIER_CASE
+   *
+   * 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. If additional metadata is included, the metadata names should be prefixed
+   * with "CUSTOM_" to identify them as such.
+   */
+  repeated string info = 1;
+}
+
+/*
+ * Represents a request to retrieve the list of catalogs 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:
+ * <
+ *  catalog_name: utf8
+ * >
+ * The returned data should be ordered by catalog_name.
+ */
+message CommandGetCatalogs {
+}
+
+/*
+ * Represents a request to retrieve the list of schemas 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:
+ * <
+ *  catalog_name: utf8,
+ *  schema_name: utf8
+ * >
+ * The returned data should be ordered by catalog_name, then schema_name.
+ */
+message CommandGetSchemas {
+  /*
+   * Specifies the Catalog to search for schemas.
+   * If omitted, then all catalogs are searched.
+   */ 
+  string catalog = 1;
+
+  /*
+   * Specifies a filter pattern for schemas to search for.
+   * When no schema_filter_pattern is provided, the pattern will not be used to narrow the search.
+   * In the pattern string, two special characters can be used to denote matching rules:
+   *    - "%" means to match any substring with 0 or more characters.
+   *    - "_" means to match any one character.
+   */
+  string schema_filter_pattern = 2;
+}
+
+/*
+ * 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 schema of the query.
+ *  - GetFlightInfo: execute the catalog metadata request.
+ *
+ * The returned schema will be:
+ * <
+ *  catalog_name: utf8,
+ *  schema_name: utf8,
+ *  table_name: utf8,
+ *  table_type: utf8,
+ *  table_schema: bytes
+ * >
+ * The returned data should be ordered by catalog_name, schema_name, table_name, then table_type.
+ */
+message CommandGetTables {
+  /*
+   * Specifies the Catalog to search for the tables.
+   * If omitted, then all catalogs are searched.
+   */
+  string catalog = 1;
+
+  /*
+   * Specifies a filter pattern for schemas to search for.
+   * When no schema_filter_pattern is provided, all schemas matching other filters are searched.
+   * In the pattern string, two special characters can be used to denote matching rules:
+   *    - "%" means to match any substring with 0 or more characters.
+   *    - "_" means to match any one character.
+   */
+  string schema_filter_pattern = 2;
+
+  /*
+   * Specifies a filter pattern for tables to search for.
+   * When no table_name_filter_pattern is provided, all tables matching other filters are searched.
+   * In the pattern string, two special characters can be used to denote matching rules:
+   *    - "%" means to match any substring with 0 or more characters.
+   *    - "_" means to match any one character.
+   */
+  string table_name_filter_pattern = 3;
+
+  // Specifies a filter of table types which must match.
+  repeated string table_types = 4;
+
+  // Specifies if the schema should be returned for found tables.
+  bool include_schema = 5;
+}
+
+/*
+ * Represents a request to retrieve the list of table types 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:
+ * <
+ *  table_type: utf8
+ * >
+ * The returned data should be ordered by table_type.
+ */
+message CommandGetTableTypes {
+}
+
+/*
+ * 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 schema of the query.
+ *  - GetFlightInfo: execute the catalog metadata request.
+ *
+ * The returned schema will be:
+ * <
+ *  catalog_name: utf8,
+ *  schema_name: utf8,
+ *  table_name: utf8,
+ *  column_name: utf8,
+ *  key_sequence: int,
+ *  key_name: utf8
+ * >
+ * The returned data should be ordered by catalog_name, schema_name, table_name, key_name, then key_sequence.
+ */
+message CommandGetPrimaryKeys {
+  // Specifies the catalog to search for the table.
+  string catalog = 1;
+
+  // Specifies the schema to search for the table.
+  string schema = 2;
+
+  // Specifies the table to get the primary keys for.
+  string table = 3;
+}
+
+/*
+ * 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 schema of the query.
+ *  - GetFlightInfo: execute the catalog metadata request.
+ *
+ * The returned schema will be:
+ * <
+ *  pk_catalog_name: utf8,
+ *  pk_schema_name: utf8,
+ *  pk_table_name: utf8,
+ *  pk_column_name: utf8,
+ *  fk_catalog_name: utf8,
+ *  fk_schema_name: utf8,
+ *  fk_table_name: utf8,
+ *  fk_column_name: utf8,
+ *  key_sequence: int,
+ *  fk_key_name: utf8,
+ *  pk_key_name: utf8,
+ *  update_rule: int,
+ *  delete_rule: int
+ * >
+ * The returned data should be ordered by catalog_name, schema_name, table_name, key_name, then key_sequence.
+ */
+message CommandGetForeignKeys {
+  // Specifies the catalog to search for the primary key table.
+  string pk_catalog = 1;
+
+  // Specifies the schema to search for the primary key table.
+  string pk_schema = 2;
+
+  // Specifies the primary key table to get the foreign keys for.
+  string pk_table = 3;
+
+  // Specifies the catalog to search for the foreign key table.
+  string fk_catalog = 4;
+
+  // Specifies the schema to search for the foreign key table.
+  string fk_schema = 5;
+
+  // Specifies the foreign key table to get the foreign keys for.
+  string fk_table = 6;
+}
+
+// SQL Execution Action Messages
+
+/*
+ * Request message for the "GetPreparedStatement" action on a Flight SQL enabled backend.
+ */
+message ActionCreatePreparedStatementRequest {
+  // The valid SQL string to create a prepared statement for.
+  string query = 1;
+}
+
+/*
+ * Wrap the result of a "GetPreparedStatement" action.
+ */
+message ActionCreatePreparedStatementResult {
+  // Opaque handle for the prepared statement on the server.
+  bytes prepared_statement_handle = 1;
+
+  // If a result set generating query was provided, dataset_schema contains the 
+  // schema of the dataset as described in Schema.fbs::Schema, it is serialized as an IPC message.
+  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.
+  bytes parameter_schema = 3;
+}
+
+/*
+ * Request message for the "ClosePreparedStatement" action on a Flight SQL enabled backend.
+ * Closes server resources associated with the prepared statement handle.
+ */
+message ActionClosePreparedStatementRequest {
+  // Opaque handle for the prepared statement on the server.
+  string prepared_statement_handle = 1;
+}
+
+
+// SQL Execution Messages.
+
+/*
+ * Represents a SQL query. Used in the command member of FlightDescriptor
+ * for the following RPC calls:
+ *  - GetSchema: return the schema of the query.
+ *  - GetFlightInfo: execute the query.
+ */
+message CommandStatementQuery {
+  // The SQL syntax.
+  string query = 1;
+}
+
+/*
+ * Represents an instance of executing a prepared statement. Used in the command member of FlightDescriptor for
+ * the following RPC calls:
+ *  - DoPut: bind parameter values. All of the bound parameter sets will be executed as a single atomic execution.
+ *  - GetFlightInfo: execute the prepared statement instance.
+ */
+message CommandPreparedStatementQuery {
+  // Unique identifier for the instance of the prepared statement to execute.
+  bytes client_execution_handle = 1;
+
+  // Opaque handle for the prepared statement on the server.
+  bytes prepared_statement_handle = 2;
+}
+
+/*
+ * Represents a SQL update query. Used in the command member of FlightDescriptor
+ * for the the RPC call DoPut to cause the server to execute the included SQL update.
+ */
+message CommandStatementUpdate {
+  // The SQL syntax.
+  string query = 1;
+}
+
+/*
+ * Represents a SQL update query. Used in the command member of FlightDescriptor
+ * for the the RPC call DoPut to cause the server to execute the included 
+ * prepared statement handle as an update.
+ */
+message CommandPreparedStatementUpdate {
+  // Unique identifier for the instance of the prepared statement to execute.
+  bytes client_execution_handle = 1;
+
+  // Opaque handle for the prepared statement on the server.
+  bytes prepared_statement_handle = 2;
+}
+
+/*
+ * Returned from the RPC call DoPut when a CommandStatementUpdate
+ * CommandPreparedStatementUpdate was in the request, containing
+ * results from the update. 
+ */
+message DoPutUpdateResult {
+  // The number of records updated. A return value of -1 represents 
+  // an unknown updated record count.
+  int64 record_count = 1; 
+}