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, and later on I'm planning on adding this change to arrow-java as well.

### 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 <rzeszut@pm.me>
Signed-off-by: David Li <li.davidm96@gmail.com>

Author: mateuszrzeszutek

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;

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>()) {}
 

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:

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;