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 >
