[AMORO-4357][Docs] Document the table. prefix requirement for catalog-level table properties

[Akeron-Zhu]

Why are the changes needed?

Close #4357.

When configuring table-level properties on a catalog, the property key must be
prefixed with table.. The prefix is automatically stripped when the property
is applied to tables. However, this requirement is not documented anywhere in
the user-facing documentation, which can easily lead to misconfiguration.

For example, to set the default optimizer group for all tables under a catalog,
users must configure table.self-optimizing.group instead of
self-optimizing.group. Properties without the table. prefix will not be
recognized as table-level defaults and will be silently ignored.

This behavior is defined in code:

• CatalogMetaProperties.TABLE_PROPERTIES_PREFIX = "table." (CatalogMetaProperties.java:91)
• catalogUtil.mergeCatalogPropertiesToTable() extracts only keys starting with
  table. and strips the prefix (CatalogUtil.java:107-120)

Brief change log

• Added a hint and examples to the "Configure table properties" section in
  docs/admin-guides/managing-catalogs.md:
  • Added a {{< hint info >}} block clarifying that keys must be prefixed
    with table. and that the prefix is automatically stripped.
  • Added an example table mapping catalog property keys to their effective
    table property keys, including:
    • table.self-optimizing.enabled → self-optimizing.enabled
    • table.self-optimizing.group → self-optimizing.group
    • table.table-expire.enabled → table-expire.enabled
    • table.clean-orphan-file.enabled → clean-orphan-file.enabled
    • table.log-store.enabled → log-store.enabled
  • Linked to the Table configurations page for a complete
    list of available table properties.

How was this patch tested?

• Add some test cases that check the changes thoroughly including negative and positive cases if possible

• Add screenshots for manual tests if appropriate

  • Rendered the doc page locally with Hugo to verify the hint block and table display correctly.

• Run test locally before making a pull request

  • Only documentation files changed; no code or test impact.

Documentation

• Does this pull request introduce a new feature? (no)
• If yes, how is the feature documented? (not applicable)

[czy006]

Hi @Akeron-Zhu , thanks for the doc fix — I verified the mechanism against CatalogUtil.mergeCatalogPropertiesToTable() and all the example keys check out. LGTM with one minor nit:

The PR description mentions linking to the "Table configurations" page, but no such link was actually added in the diff. It would be helpful to add one so readers can find the full list of available table properties. One thing to note: the correct relative path from docs/admin-guides/managing-catalogs.md is ../user-guides/configurations.md — a link to ../configurations/ (as written in the description) would be broken, since there is no docs/configurations/ directory.

[Akeron-Zhu]

Hi @Akeron-Zhu , thanks for the doc fix — I verified the mechanism against CatalogUtil.mergeCatalogPropertiesToTable() and all the example keys check out. LGTM with one minor nit:

The PR description mentions linking to the "Table configurations" page, but no such link was actually added in the diff. It would be helpful to add one so readers can find the full list of available table properties. One thing to note: the correct relative path from docs/admin-guides/managing-catalogs.md is ../user-guides/configurations.md — a link to ../configurations/ (as written in the description) would be broken, since there is no docs/configurations/ directory.

done.

[zhoujinsong]

LGTM.

Thanks a lot for the work!