This is an automated email from the ASF dual-hosted git repository.
jerryshao pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/gravitino.git
The following commit(s) were added to refs/heads/main by this push:
new ecd99f8d2d [MINOR] docs(kafka): Document dotted topic name limitation
(#13469)
ecd99f8d2d is described below
commit ecd99f8d2d78f544df4a0889d581494080af46b2
Author: roryqi <[email protected]>
AuthorDate: Thu Sep 24 10:00:54 2026 +0800
[MINOR] docs(kafka): Document dotted topic name limitation (#13469)
### What changes were proposed in this pull request?
Document the Kafka topic name limitation when authorization is enabled:
- Loading a topic whose name contains `.` returns `400 Bad Request`.
- One dotted topic causes the entire topic list request to fail.
- Rename or recreate the topic without dots as a workaround.
### Why are the changes needed?
Gravitino uses `.` as the qualified metadata object name separator and
cannot authorize a topic whose
local name contains a dot. This behavior and its effect on topic listing
should be clearly documented.
Related: #12977
### Does this PR introduce _any_ user-facing change?
Yes. The Kafka catalog documentation now describes the dotted topic name
limitation and its
workaround. There is no API or behavior change.
### How was this patch tested?
- Ran `./gradlew :docs:build`.
- Ran `git diff --check`.
---------
Co-authored-by: Copilot Autofix powered by AI
<[email protected]>
---
docs/kafka-catalog.md | 7 +++++++
docs/security/access-control.md | 20 ++++++++++++++++++--
docs/tables-and-views.md | 4 ++++
3 files changed, 29 insertions(+), 2 deletions(-)
diff --git a/docs/kafka-catalog.md b/docs/kafka-catalog.md
index 6cabf2abeb..103aced176 100644
--- a/docs/kafka-catalog.md
+++ b/docs/kafka-catalog.md
@@ -48,6 +48,13 @@ Refer to [Schema
operation](./manage-messaging-metadata-using-gravitino.md#schem
- The Kafka catalog supports creating, updating, deleting, and listing topics.
+::::caution Topic names containing dots
+When authorization is enabled, topic names containing dots are unsupported,
and one such topic can
+cause the entire topic list request to fail. See
+[Names containing dots](./security/access-control.md#names-containing-dots)
for details and the
+workaround.
+::::
+
### Topic Properties
| Property name | Description | Default
value |
Required |
diff --git a/docs/security/access-control.md b/docs/security/access-control.md
index 397a923a9b..deb942227f 100755
--- a/docs/security/access-control.md
+++ b/docs/security/access-control.md
@@ -73,6 +73,21 @@ Everything Gravitino manages is an object with a type and a
name. The name is th
below the metalake, so a table is `{catalog}.{schema}.{table}`, and requests
identify an object by
both type and name, since the same name can exist at more than one type.
+##### Local names containing one or more dots {#names-containing-dots}
+
+::::caution
+When authorization is enabled, Gravitino cannot authorize a federated object
whose local name
+contains one or more dots (`.`), because dots separate the components of a
qualified metadata object name.
+Loading such an object returns `400 Bad Request`. If a connector returns one
of these objects in a
+list, Gravitino rejects the entire list request with `400 Bad Request` and
identifies the unsupported
+name instead of returning a partial result. Consequently, one object with a
dotted name can prevent
+all sibling objects from appearing in list APIs.
+
+Rename or recreate the object in the source system with a name that does not
contain dots before
+using it with authorization. When authorization is disabled, existing source
objects whose names
+are supported by the connector can still be listed and loaded.
+::::
+
Access to an object is controlled by privileges, granted through roles, and by
ownership. Ownership
behaves like a privilege that arrives with the object rather than one you
grant, and it carries the
administrative rights, altering, dropping, and transferring, that no privilege
name covers.
@@ -144,8 +159,9 @@ Note the third case. Granting `SELECT_TABLE` on a schema
covers every table in t
its own it authorizes nothing, because the traversal privileges are still
missing.
A failed check returns `403 Forbidden`. Some read paths return `404 Not Found`
instead, so that a
-caller cannot infer the existence of an object they are not entitled to see.
List operations do not
-fail; they return only the entries the caller is entitled to see.
+caller cannot infer the existence of an object they are not entitled to see.
List operations
+normally do not fail; they return only the entries the caller is entitled to
see. An object whose
+name contains a dot is an exception, as described in [Names containing
dots](#names-containing-dots).
#### Allow and Deny
diff --git a/docs/tables-and-views.md b/docs/tables-and-views.md
index caf0c89e0d..f2f3b44a72 100644
--- a/docs/tables-and-views.md
+++ b/docs/tables-and-views.md
@@ -16,6 +16,10 @@ Creating a table through Gravitino creates it in the source
system, and listing
source at request time, so a table created directly in Hive appears the next
time Gravitino is
asked.
+When authorization is enabled, a table whose local name contains one or more
dots is an exception:
+it can cause the entire table list request to fail. See
+[Local names containing one or more
dots](./security/access-control.md#names-containing-dots).
+
What Gravitino adds is a single shape across all of them. The same call
describes a Hive table and
an Iceberg table, columns carry the same type system, and tags, policies,
ownership, and statistics
attach the same way regardless of the system underneath.
