Thank you for your response. As I understand it, the table description is currently stored as a table property within the table metadata’s `properties` map.
In my opinion, this approach has a few issues: - Table metadata `properties` are not versioned. As a result, when querying an older snapshot, the description may be inaccurate because the value reflects only the current state. - According to the specification, the purpose of table metadata properties is: “A string to string map of table properties. This is used to control settings that affect reading and writing and is not intended to be used for arbitrary metadata.” Based on this, a comment seems to fall under “arbitrary metadata,” and therefore may not be an appropriate use of properties. - Table comments seem to have become significant enough that relying on a convention alone may no longer be sufficient. It might be worth considering a standardized, schema-level field for them. Thank you. Taeyun -----Original Message----- From: "Ryan Blue" <rdb...@gmail.com> To: <dev@iceberg.apache.org>; Cc: Sent: 2025-07-25 (금) 08:48:48 (UTC+09:00) Subject: Re: Thoughts on Adding a `doc` Property for Schema Objects Iceberg does allow you to store table descriptions. The convention is to use a table property, "comment". While this isn't a schema-level doc/comment, I don't know of anything that makes a distinction between schema description and table description, so I think it should work for your use. On Tue, Jul 22, 2025 at 5:48 PM 김태연 (Taeyun Kim) <taeyun....@innowireless.com> wrote: Hi, With the growing trend of using LLMs to automatically generate SQL, it feels increasingly important to manage descriptions of database tables and columns in a way that these tools can easily access. In the Iceberg specification, comments for schema fields (i.e., columns) can be specified using the `doc` property within the `fields` array of a `struct` type. However, there doesn’t seem to be a way to specify a comment for the root struct type itself - that is, for the table as a whole. From what I can tell, OLAP DBMSs today may handle table-level comments by storing them in the `properties` map within the table metadata under various non-standard keys. But since a table comment conceptually belongs to the schema, and can vary by schema, it feels like the `properties` map within the table metadata might not be the best place for it. Would it make sense to allow a `doc` property on the `schema` object (the root struct type), alongside `schema-id` and `identifier-field-ids`, so that a description for the schema itself can be included? It seems like it would be helpful, especially for tooling and LLM-related use cases. Curious to hear your thoughts. Apologies if I’m overlooking something or if this has already been discussed. Thank you, Taeyun
