stevenzwu commented on code in PR #15367:
URL: https://github.com/apache/iceberg/pull/15367#discussion_r2830278668
##########
docs/docs/configuration.md:
##########
@@ -127,6 +127,15 @@ The value of these properties are not persisted as a part
of the table metadata.
| -------------- | --------
|--------------------------------------------------------------------------------------------------------------------------------------|
| format-version | 2 | Table's format version as defined in the
[Spec](../../spec.md#format-versioning). Defaults to 2 since version 1.4.0. |
+### Informational properties
+
+Informational properties are not used by Iceberg operations, but can be set by
engines to provide additional context about a table.
Review Comment:
nit: an alternative
```
Informational properties can be set by engines to provide additional context
about a table. They can be useful for documentation, discovery, and integration
with external tools. They do not affect read/write behavior or query semantics.
```
##########
docs/docs/configuration.md:
##########
@@ -127,6 +127,15 @@ The value of these properties are not persisted as a part
of the table metadata.
| -------------- | --------
|--------------------------------------------------------------------------------------------------------------------------------------|
| format-version | 2 | Table's format version as defined in the
[Spec](../../spec.md#format-versioning). Defaults to 2 since version 1.4.0. |
+### Informational properties
+
+Informational properties are not used by Iceberg operations, but can be set by
engines to provide additional context about a table.
+These properties are persisted in table metadata and can be useful for
documentation, discovery, and integration with external tools.
+
+| Property | Default | Description
|
+| -------- | ---------- |
-------------------------------------------------------------------------------------------------------------------
|
+| comment | (not set) | A human-readable description of the table. Engines
like Spark and Flink set this via `COMMENT` in create table DDL. |
Review Comment:
> Engines like Spark and Flink set this via `COMMENT` in create table DDL.
I am not sure we need to call this out. I would be good to just remove it.
> A human-readable description of the table.
The doc is not just for human to read. The semantic context for LLMs might
be the important use case nowadays :)
```
A table-level description intended to document business meaning and usage
context.
```
I am also debating if we need to add more details like these. I guess we
probably should leave those details out.
```
It can cover information like business purpose, data source/pipeline,
granularity, ownership, update frequency, SLA/freshness, common query patterns,
relationships, disambiguation, domain-specific context, etc.
```
--
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]
