ganeshashree commented on code in PR #57311: URL: https://github.com/apache/spark/pull/57311#discussion_r3601278284
########## docs/sql-ref-syntax-ddl-comment.md: ########## @@ -0,0 +1,95 @@ +--- +layout: global +title: COMMENT ON +displayTitle: COMMENT ON +license: | + 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 + + http://www.apache.org/licenses/LICENSE-2.0 + + 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. +--- + +### Description + +The `COMMENT ON` statement sets or updates the comment on a database, a table, or +one or more table columns. Setting the comment to `NULL` removes it. + +### Syntax + +```sql +COMMENT ON { DATABASE | SCHEMA | NAMESPACE } database_name IS comment + +COMMENT ON TABLE table_name IS comment + +COMMENT ON COLUMN table_name.column_name IS comment + +COMMENT ON TABLE table_name COLUMN ( column_name IS comment [ , ... ] ) Review Comment: Thanks for reviewing. I went with option 1, making both forms work in the session catalog rather than documenting a V2-only limitation. Comment-only changes that span multiple columns or target a nested field are now routed to a dedicated V1 command (`AlterTableChangeColumnCommentsCommand`) that applies all specs at once via `CatalogV2Util.applySchemaChanges`, so `COMMENT ON TABLE t COLUMN (a IS 'x', b IS 'y')` and `... (point.x IS 'x')` work on ordinary managed tables. The single-column path and the existing errors for genuinely unsupported non-comment bulk/nested ALTER COLUMN changes are unchanged. The `NOT_SUPPORTED_CHANGE_SAME_COLUMN` check is now extracted into `AlterColumns.findRepeatedColumn`, shared between CheckAnalysis and the new V1 path (the rewrite happens during resolution, before CheckAnalysis runs), so a parent+child in the same statement is still rejected with the same message and query context. Partition columns are rejected too. Added session-catalog (V1) coverage: multi-column, nested/deeply-nested fields, `IS NULL` removal, DESCRIBE freshness, char/varchar columns, unresolved column, parent-and-child rejection, and partition-column rejection. No doc caveat needed now since both forms work on V1 and V2. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
