This is an automated email from the ASF dual-hosted git repository.
lidavidm pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow.git
The following commit(s) were added to refs/heads/main by this push:
new 2bb5fd587f GH-46087: [FlightSQL] Allow returning column remarks in
FlightSQL's CommandGetTables (#46110)
2bb5fd587f is described below
commit 2bb5fd587f735730ed511a3c875033820a982f06
Author: Mateusz Rzeszutek <[email protected]>
AuthorDate: Sat May 3 12:39:43 2025 +0200
GH-46087: [FlightSQL] Allow returning column remarks in FlightSQL's
CommandGetTables (#46110)
Resolves #46087
### Rationale for this change
FlightSQL allows returning various column metadata in `CommandGetTables`,
but one thing that's missing is human-readable column description. This PR
proposes adding a new `ARROW:FLIGHT:SQL:REMARKS` metadata property taht will
contain a comment describing a column. This is inspired by JDBC's
[`DatabaseMetaData#getColumns()`](https://docs.oracle.com/javase/8/docs/api/java/sql/DatabaseMetaData.html#getColumns-java.lang.String-java.lang.String-java.lang.String-java.lang.String-)
method, a [...]
### What changes are included in this PR?
* A new column metadata property `ARROW:FLIGHT:SQL:REMARKS`
* C++ `ColumnMetadata` implementation
Please tell me if there's anything else in the other languages that I
should add.
### Are these changes tested?
Covered by existing tests; no new test cases added.
### Are there any user-facing changes?
Yes, a couple new constants/methods added to the `ColumnMetadata` class and
its builder
* GitHub Issue: #46087
Authored-by: mateuszrzeszutek <[email protected]>
Signed-off-by: David Li <[email protected]>
---
cpp/src/arrow/flight/integration_tests/test_integration.cc | 2 ++
cpp/src/arrow/flight/sql/column_metadata.cc | 11 +++++++++++
cpp/src/arrow/flight/sql/column_metadata.h | 12 ++++++++++++
format/FlightSql.proto | 6 +++++-
4 files changed, 30 insertions(+), 1 deletion(-)
diff --git a/cpp/src/arrow/flight/integration_tests/test_integration.cc
b/cpp/src/arrow/flight/integration_tests/test_integration.cc
index f38076822c..25600b92cd 100644
--- a/cpp/src/arrow/flight/integration_tests/test_integration.cc
+++ b/cpp/src/arrow/flight/integration_tests/test_integration.cc
@@ -1167,6 +1167,7 @@ const std::shared_ptr<Schema>& GetQuerySchema() {
.IsSearchable(true)
.CatalogName("catalog_test")
.Precision(100)
+ .Remarks("test column")
.Build()
.metadata_map())});
return kSchema;
@@ -1187,6 +1188,7 @@ std::shared_ptr<Schema> GetQueryWithTransactionSchema() {
.IsSearchable(true)
.CatalogName("catalog_test")
.Precision(100)
+ .Remarks("test column")
.Build()
.metadata_map())});
return kSchema;
diff --git a/cpp/src/arrow/flight/sql/column_metadata.cc
b/cpp/src/arrow/flight/sql/column_metadata.cc
index c855e2f09a..e9b9db05d8 100644
--- a/cpp/src/arrow/flight/sql/column_metadata.cc
+++ b/cpp/src/arrow/flight/sql/column_metadata.cc
@@ -55,6 +55,7 @@ const char* ColumnMetadata::kIsAutoIncrement =
"ARROW:FLIGHT:SQL:IS_AUTO_INCREME
const char* ColumnMetadata::kIsCaseSensitive =
"ARROW:FLIGHT:SQL:IS_CASE_SENSITIVE";
const char* ColumnMetadata::kIsReadOnly = "ARROW:FLIGHT:SQL:IS_READ_ONLY";
const char* ColumnMetadata::kIsSearchable = "ARROW:FLIGHT:SQL:IS_SEARCHABLE";
+const char* ColumnMetadata::kRemarks = "ARROW:FLIGHT:SQL:REMARKS";
ColumnMetadata::ColumnMetadata(
std::shared_ptr<const arrow::KeyValueMetadata> metadata_map)
@@ -114,6 +115,10 @@ arrow::Result<bool> ColumnMetadata::GetIsSearchable()
const {
return StringToBoolean(is_case_sensitive);
}
+arrow::Result<std::string> ColumnMetadata::GetRemarks() const {
+ return metadata_map_->Get(kRemarks);
+}
+
ColumnMetadata::ColumnMetadataBuilder ColumnMetadata::Builder() {
return ColumnMetadataBuilder{};
}
@@ -185,6 +190,12 @@ ColumnMetadata::ColumnMetadataBuilder::IsSearchable(bool
is_searchable) {
return *this;
}
+ColumnMetadata::ColumnMetadataBuilder&
ColumnMetadata::ColumnMetadataBuilder::Remarks(
+ const std::string& remarks) {
+ metadata_map_->Append(ColumnMetadata::kRemarks, remarks);
+ return *this;
+}
+
ColumnMetadata::ColumnMetadataBuilder::ColumnMetadataBuilder()
: metadata_map_(std::make_shared<arrow::KeyValueMetadata>()) {}
diff --git a/cpp/src/arrow/flight/sql/column_metadata.h
b/cpp/src/arrow/flight/sql/column_metadata.h
index 0eb53f3e0b..fe29df9040 100644
--- a/cpp/src/arrow/flight/sql/column_metadata.h
+++ b/cpp/src/arrow/flight/sql/column_metadata.h
@@ -66,6 +66,9 @@ class ARROW_FLIGHT_SQL_EXPORT ColumnMetadata {
/// \brief Constant variable to hold the value of the key that
/// will be used in the KeyValueMetadata class.
static const char* kIsSearchable;
+ /// \brief Constant variable to hold the value of the key that
+ /// will be used in the KeyValueMetadata class.
+ static const char* kRemarks;
/// \brief Static initializer.
static ColumnMetadataBuilder Builder();
@@ -110,6 +113,10 @@ class ARROW_FLIGHT_SQL_EXPORT ColumnMetadata {
/// \return The IsSearchable.
arrow::Result<bool> GetIsSearchable() const;
+ /// \brief Return the Remarks set in the KeyValueMetadata.
+ /// \return The Remarks.
+ arrow::Result<std::string> GetRemarks() const;
+
/// \brief Return the KeyValueMetadata.
/// \return The KeyValueMetadata.
const std::shared_ptr<const arrow::KeyValueMetadata>& metadata_map() const;
@@ -169,6 +176,11 @@ class ARROW_FLIGHT_SQL_EXPORT ColumnMetadata {
/// \return A ColumnMetadataBuilder.
ColumnMetadataBuilder& IsSearchable(bool is_searchable);
+ /// \brief Set the column description in the KeyValueMetadata object.
+ /// \param[in] remarks The comment describing column.
+ /// \return A ColumnMetadataBuilder.
+ ColumnMetadataBuilder& Remarks(const std::string& remarks);
+
ColumnMetadata Build() const;
private:
diff --git a/format/FlightSql.proto b/format/FlightSql.proto
index ef1ae7513d..25dc131874 100644
--- a/format/FlightSql.proto
+++ b/format/FlightSql.proto
@@ -1212,6 +1212,7 @@ message CommandGetDbSchemas {
* - 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.
*/
message CommandGetTables {
@@ -1678,6 +1679,7 @@ message ActionEndSavepointRequest {
* - 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.
*/
message CommandStatementQuery {
@@ -1703,6 +1705,7 @@ message CommandStatementQuery {
* - 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.
*/
@@ -1739,6 +1742,7 @@ message TicketStatementQuery {
* - 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.
@@ -1857,7 +1861,7 @@ message DoPutPreparedStatementResult {
// statement should be considered invalid, and all subsequent requests for
this prepared
// statement must use this new handle.
// The updated handle allows implementing query parameters with stateless
services.
- //
+ //
// When an updated handle is not provided by the server, clients should
contiue
// using the previous handle provided by
`ActionCreatePreparedStatementResonse`.
optional bytes prepared_statement_handle = 1;
