[DISCUSS] REST Spec: Clarify identifier uniqueness across catalog object types

[Steven Wu <st...@gmail.com>]

Hi all,

I'd like to discuss a minor inconsistency in the REST Catalog specification
regarding identifier uniqueness within a namespace.

*Background: Inconsistency in Conflict Descriptions*

The REST spec currently defines six write operations that return a 409
Conflict when an identifier already exists: createTable, registerTable,
renameTable, createView, renameView, and registerView.

However, the descriptions for *what* constitutes a conflict are not
consistent:

   - *Enforcing cross-type uniqueness* (table or view):
      - renameTable, renameView, registerView say: *"already exists as a
      table or view"*
   - *Only enforcing within the same type* (table or view only):
      - createTable, registerTable, createView say: *"table already exists"*
       / *"view already exists"*

This ambiguity leaves it unclear whether a catalog is allowed to have a
table and a view with the same name in the same namespace.

*Proposed Change*

I believe the intent is that identifiers *must* be unique across all
catalog object types within the same namespace (otherwise the rename
operations become impossible to reason about).

The proposed change makes this explicit in two ways:

   1. *New CatalogObjectType schema:* Enumerates the known catalog object
   types (table, view) and states the uniqueness invariant: *"Identifiers
   MUST be unique across all catalog object types within the same namespace; a
   table and a view with the same name in the same namespace are not allowed."*
   2. *Consistent 409 descriptions:* All six write operations will now
   reference CatalogObjectType and use uniform language: *"The identifier
   is already used by an existing catalog object (see CatalogObjectType)"*

This change is purely spec-clarification; it introduces no new behavior for
catalogs that already enforce cross-type uniqueness.

The proposed clarification is available here:
https://github.com/apache/iceberg/pull/15691
<https://www.google.com/url?source=gmail&sa=E&q=https://github.com/stevenzwu/iceberg/tree/rest-spec-clarify-id-conflict-requirement>

Thanks,
Steven

Re: [DISCUSS] REST Spec: Clarify identifier uniqueness across catalog object types

[Steven Wu <st...@gmail.com>]

I agree that the function clarification should be done in the function REST
spec PR from Huaxin,

My PR only addresses the inconsistency for existing table and view
endpoints. I addressed Dan's comment with the latest tweak of the error
messages. Please help take another look.
https://github.com/apache/iceberg/pull/15691/changes

On Wed, Mar 25, 2026 at 5:54 PM huaxin gao <hu...@gmail.com> wrote:

>  +1 on keeping functions separate from tables and views. It makes sense to
> allow a function and a table with the same name in the same namespace.
>
> Also +1 on Yufei's point: we should say this clearly in the spec. I can
> add a note in the function endpoint PR once we agree on this.
>
> Thanks,
>
> Huaxin
>
> On Wed, Mar 25, 2026 at 4:51 PM Yufei Gu <fl...@gmail.com> wrote:
>
>> +1 on clarifying that tables and views share a namespace, so their names
>> must be unique. It would also be helpful to explicitly state that UDFs can
>> coexist with tables and views under the same namespace using the same name.
>> Leaving this unspecified may lead to inconsistent behavior across catalog
>> implementations, as each may interpret the spec differently.
>>
>> Yufei
>>
>>
>> On Wed, Mar 25, 2026 at 2:37 PM Ryan Blue <rd...@gmail.com> wrote:
>>
>>> I think it's a good idea to update the spec to show that a conflict
>>> could be caused by a table in the view methods or a view in the table
>>> methods. I also think it is good to clarify the assumption that tables and
>>> views share a namespace, since we are talking about routes that will load
>>> either one by name and this is a critical part of that behavior. Before, we
>>> didn't have a clear reason to make this a requirement, so I think we left
>>> it unspecified.
>>>
>>> As for other objects, I don't think that it is a good idea to include
>>> functions. To me, those are separate objects that can coexist with the same
>>> name as Peter pointed out. And indexes are a bit too early to think about
>>> since they may be table-specific and not catalog-tracked objects.
>>>
>>> On Wed, Mar 25, 2026 at 7:55 AM Daniel Weeks <dw...@apache.org> wrote:
>>>
>>>> I would just add that this issue is largely isolated to the spec
>>>> definition and likely has little impact on the implementations.
>>>>
>>>> The various conflict responses (TableAlreadyExistsError,
>>>> ViewAlreadyExistsError, etc.) are all just slightly different flavors of
>>>> 409 CONFLICT that we send back to the client.  The only practical
>>>> difference is the text we send back.
>>>>
>>>> If we wanted to formalize the right response for the conflicting object
>>>> (not based on which route was used), we could change the responses to
>>>> "oneOf" and the spec would allow for representing the conflict accurately.
>>>> In practice, I think this is what some catalog implementations already do.
>>>>
>>>> -Dan
>>>>
>>>> On Tue, Mar 24, 2026 at 1:22 PM Steven Wu <st...@gmail.com> wrote:
>>>>
>>>>> Pasting Dan's questions from the voting thread
>>>>>
>>>>> > There's actually a more significant discrepancy in that the
>>>>> create/rename/register view can only return a ViewAlreadyExistsError even
>>>>> if it's a table and create/rename/register Table can only return a
>>>>> TableAlreadyExistsError even if it's a view.
>>>>> > I think clarifying the description doesn't really address this issue
>>>>> and functionally we've strictly defined two specific return types that are
>>>>> aligned with their specific load routes, but identifier uniqueness spans
>>>>> multiple.
>>>>>
>>>>> That is a valid point. We can probably define a new error like
>>>>> `IdentifierAlreadyExistError` with just an error message change, such as
>>>>> "The given identifier already exists."
>>>>>
>>>>> > I also don't know what else may collide (functions, indexes, etc.).
>>>>> Some of this might be engine specific.
>>>>>
>>>>> Most engines/databases seem to treat functions separately. Here is the
>>>>> AI research result.
>>>>> [image: image.png]
>>>>>
>>>>> Regarding index, I was thinking we can revisit once we have more
>>>>> clarify on its design and catalog storage.
>>>>>
>>>>> On Tue, Mar 24, 2026 at 5:57 AM Maximilian Michels <mx...@apache.org>
>>>>> wrote:
>>>>>
>>>>>> +1 for improving the error messages and restricting identifier
>>>>>> uniqueness to tables and views only. We could have also gone with "the
>>>>>> identifier already exists", but this is more nuanced.
>>>>>>
>>>>>> On Tue, Mar 24, 2026 at 10:17 AM Péter Váry <
>>>>>> peter.vary.apache@gmail.com> wrote:
>>>>>> >
>>>>>> > +1 on consistent "Conflict - The identifier already exists as a
>>>>>> table or view"
>>>>>> >
>>>>>> > Steven Wu <st...@gmail.com> ezt írta (időpont: 2026. márc.
>>>>>> 24., K, 6:30):
>>>>>> >>
>>>>>> >> Enforcing cross-type uniqueness (table or view):
>>>>>> >>
>>>>>> >> renameTable, renameView, registerView say: "already exists as a
>>>>>> table or view"
>>>>>> >>
>>>>>> >> Only enforcing within the same type (table or view only):
>>>>>> >>
>>>>>> >> createTable, registerTable, createView say: "table already exists"
>>>>>> / "view already exists"
>>>>>> >>
>>>>>> >>
>>>>>> >> I updated the PR to use the consistent wording "already exists as
>>>>>> a table or view" for the 409 conflict.
>>>>>> >>
>>>>>> >>
>>>>>> >> On Mon, Mar 23, 2026 at 8:30 AM Péter Váry <
>>>>>> peter.vary.apache@gmail.com> wrote:
>>>>>> >>>
>>>>>> >>> We need a `role` paired with the identifier to get the requested
>>>>>> object. The `role` in this case can be the same for tables, views and MVs
>>>>>> >>>
>>>>>> >>> Steven Wu <st...@gmail.com> ezt írta (időpont: 2026. márc.
>>>>>> 21., Szo, 22:08):
>>>>>> >>>>
>>>>>> >>>> > Do we really want to prevent creating a `rank` function if we
>>>>>> already have a table named `rank`?
>>>>>> >>>>
>>>>>> >>>> This is a good argument. I agree functions can be in a separate
>>>>>> dimension.
>>>>>> >>>>
>>>>>> >>>> Earlier, I was thinking from the perspective of a universal
>>>>>> batch load endpoint, where a client may send one catalog request for all
>>>>>> referenced objects (tables, views, MVs, functions). We can still make it
>>>>>> work if functions are separated out in the batch load request. Or we can
>>>>>> limit the universal batch load endpoint to tables, views, and MVs only.
>>>>>> >>>>
>>>>>> >>>> Clients may not need to load index objects separately. They can
>>>>>> be piggybacked during table loading.
>>>>>> >>>>
>>>>>> >>>> On Sat, Mar 21, 2026 at 12:38 AM Péter Váry <
>>>>>> peter.vary.apache@gmail.com> wrote:
>>>>>> >>>>>
>>>>>> >>>>> I think we definitely should discuss the global uniqueness in
>>>>>> details.
>>>>>> >>>>>
>>>>>> >>>>> Do we really want to prevent creating a `rank` function if we
>>>>>> already have a table named `rank`?
>>>>>> >>>>>
>>>>>> >>>>> I'm fully on board to avoid having the same name for a table
>>>>>> and a view, as they are fully interchangeable, but functions and indexes
>>>>>> could use the same name and the engines could decide which one to use based
>>>>>> on the context.
>>>>>> >>>>>
>>>>>> >>>>> So I think we need to seriously consider if we want to propose
>>>>>> restrictions like this.
>>>>>> >>>>>
>>>>>> >>>>> WDYT?
>>>>>> >>>>>
>>>>>> >>>>>
>>>>>> >>>>> On Fri, Mar 20, 2026, 15:19 Steven Wu <st...@gmail.com>
>>>>>> wrote:
>>>>>> >>>>>>
>>>>>> >>>>>> Hi Peter,
>>>>>> >>>>>>
>>>>>> >>>>>> I can understand the hesitation, especially considering the
>>>>>> new CatalogObjectType not used by the spec (except for the references in
>>>>>> the description text).
>>>>>> >>>>>>
>>>>>> >>>>>> I added it in this PR for the following reasons:
>>>>>> >>>>>> * Huaxin has a PR for functions [1], which will introduce a
>>>>>> new function object type in the catalog. I believe we want to enforce
>>>>>> uniqueness across all types: tables, views, and functions.
>>>>>> >>>>>> * index proposal also discussed the index object type in the
>>>>>> catalog. but this is a bit farther away.
>>>>>> >>>>>> * Events endpoint proposal also needs to introduce the
>>>>>> CatalogObjectType concept [2, 3].
>>>>>> >>>>>>
>>>>>> >>>>>> I am ok with removing it from this PR. We can add it later,
>>>>>> perhaps, in the events or function endpoint spec change.
>>>>>> >>>>>>
>>>>>> >>>>>> Thanks,
>>>>>> >>>>>> Steven
>>>>>> >>>>>>
>>>>>> >>>>>> [1] Function endpoint spec:
>>>>>> https://github.com/apache/iceberg/pull/15180
>>>>>> >>>>>> [2] Events endpoint spec:
>>>>>> https://github.com/apache/iceberg/pull/12584
>>>>>> >>>>>> [3] Events endpoint impl:
>>>>>> https://github.com/apache/iceberg/pull/14142
>>>>>> >>>>>>
>>>>>> >>>>>>
>>>>>> >>>>>>
>>>>>> >>>>>> On Fri, Mar 20, 2026 at 3:00 AM Péter Váry <
>>>>>> peter.vary.apache@gmail.com> wrote:
>>>>>> >>>>>>>
>>>>>> >>>>>>> Hi Steven,
>>>>>> >>>>>>> I completely agree that we should align the uniqueness
>>>>>> requirements between table and view creation.
>>>>>> >>>>>>> I’m a bit hesitant about introducing CatalogObjectType. It
>>>>>> makes sense if we expect to add more object types and want to enforce
>>>>>> uniqueness across them, but I’m not sure we need that level of generality
>>>>>> yet. Do you have something specific in mind that would require it?
>>>>>> >>>>>>> Thanks,
>>>>>> >>>>>>> Peter
>>>>>> >>>>>>>
>>>>>> >>>>>>> Steven Wu <st...@gmail.com> ezt írta (időpont: 2026.
>>>>>> márc. 19., Cs, 21:17):
>>>>>> >>>>>>>>
>>>>>> >>>>>>>> Hi all,
>>>>>> >>>>>>>>
>>>>>> >>>>>>>> I'd like to discuss a minor inconsistency in the REST
>>>>>> Catalog specification regarding identifier uniqueness within a namespace.
>>>>>> >>>>>>>>
>>>>>> >>>>>>>> Background: Inconsistency in Conflict Descriptions
>>>>>> >>>>>>>>
>>>>>> >>>>>>>> The REST spec currently defines six write operations that
>>>>>> return a 409 Conflict when an identifier already exists: createTable,
>>>>>> registerTable, renameTable, createView, renameView, and registerView.
>>>>>> >>>>>>>>
>>>>>> >>>>>>>> However, the descriptions for what constitutes a conflict
>>>>>> are not consistent:
>>>>>> >>>>>>>>
>>>>>> >>>>>>>> Enforcing cross-type uniqueness (table or view):
>>>>>> >>>>>>>>
>>>>>> >>>>>>>> renameTable, renameView, registerView say: "already exists
>>>>>> as a table or view"
>>>>>> >>>>>>>>
>>>>>> >>>>>>>> Only enforcing within the same type (table or view only):
>>>>>> >>>>>>>>
>>>>>> >>>>>>>> createTable, registerTable, createView say: "table already
>>>>>> exists" / "view already exists"
>>>>>> >>>>>>>>
>>>>>> >>>>>>>> This ambiguity leaves it unclear whether a catalog is
>>>>>> allowed to have a table and a view with the same name in the same namespace.
>>>>>> >>>>>>>>
>>>>>> >>>>>>>> Proposed Change
>>>>>> >>>>>>>>
>>>>>> >>>>>>>> I believe the intent is that identifiers must be unique
>>>>>> across all catalog object types within the same namespace (otherwise the
>>>>>> rename operations become impossible to reason about).
>>>>>> >>>>>>>>
>>>>>> >>>>>>>> The proposed change makes this explicit in two ways:
>>>>>> >>>>>>>>
>>>>>> >>>>>>>> New CatalogObjectType schema: Enumerates the known catalog
>>>>>> object types (table, view) and states the uniqueness invariant:
>>>>>> "Identifiers MUST be unique across all catalog object types within the same
>>>>>> namespace; a table and a view with the same name in the same namespace are
>>>>>> not allowed."
>>>>>> >>>>>>>> Consistent 409 descriptions: All six write operations will
>>>>>> now reference CatalogObjectType and use uniform language: "The identifier
>>>>>> is already used by an existing catalog object (see CatalogObjectType)"
>>>>>> >>>>>>>>
>>>>>> >>>>>>>> This change is purely spec-clarification; it introduces no
>>>>>> new behavior for catalogs that already enforce cross-type uniqueness.
>>>>>> >>>>>>>>
>>>>>> >>>>>>>> The proposed clarification is available here:
>>>>>> https://github.com/apache/iceberg/pull/15691
>>>>>> >>>>>>>>
>>>>>> >>>>>>>> Thanks,
>>>>>> >>>>>>>> Steven
>>>>>>
>>>>>

Re: [DISCUSS] REST Spec: Clarify identifier uniqueness across catalog object types

[huaxin gao <hu...@gmail.com>]

 +1 on keeping functions separate from tables and views. It makes sense to
allow a function and a table with the same name in the same namespace.

Also +1 on Yufei's point: we should say this clearly in the spec. I can add
a note in the function endpoint PR once we agree on this.

Thanks,

Huaxin

On Wed, Mar 25, 2026 at 4:51 PM Yufei Gu <fl...@gmail.com> wrote:

> +1 on clarifying that tables and views share a namespace, so their names
> must be unique. It would also be helpful to explicitly state that UDFs can
> coexist with tables and views under the same namespace using the same name.
> Leaving this unspecified may lead to inconsistent behavior across catalog
> implementations, as each may interpret the spec differently.
>
> Yufei
>
>
> On Wed, Mar 25, 2026 at 2:37 PM Ryan Blue <rd...@gmail.com> wrote:
>
>> I think it's a good idea to update the spec to show that a conflict
>> could be caused by a table in the view methods or a view in the table
>> methods. I also think it is good to clarify the assumption that tables and
>> views share a namespace, since we are talking about routes that will load
>> either one by name and this is a critical part of that behavior. Before, we
>> didn't have a clear reason to make this a requirement, so I think we left
>> it unspecified.
>>
>> As for other objects, I don't think that it is a good idea to include
>> functions. To me, those are separate objects that can coexist with the same
>> name as Peter pointed out. And indexes are a bit too early to think about
>> since they may be table-specific and not catalog-tracked objects.
>>
>> On Wed, Mar 25, 2026 at 7:55 AM Daniel Weeks <dw...@apache.org> wrote:
>>
>>> I would just add that this issue is largely isolated to the spec
>>> definition and likely has little impact on the implementations.
>>>
>>> The various conflict responses (TableAlreadyExistsError,
>>> ViewAlreadyExistsError, etc.) are all just slightly different flavors of
>>> 409 CONFLICT that we send back to the client.  The only practical
>>> difference is the text we send back.
>>>
>>> If we wanted to formalize the right response for the conflicting object
>>> (not based on which route was used), we could change the responses to
>>> "oneOf" and the spec would allow for representing the conflict accurately.
>>> In practice, I think this is what some catalog implementations already do.
>>>
>>> -Dan
>>>
>>> On Tue, Mar 24, 2026 at 1:22 PM Steven Wu <st...@gmail.com> wrote:
>>>
>>>> Pasting Dan's questions from the voting thread
>>>>
>>>> > There's actually a more significant discrepancy in that the
>>>> create/rename/register view can only return a ViewAlreadyExistsError even
>>>> if it's a table and create/rename/register Table can only return a
>>>> TableAlreadyExistsError even if it's a view.
>>>> > I think clarifying the description doesn't really address this issue
>>>> and functionally we've strictly defined two specific return types that are
>>>> aligned with their specific load routes, but identifier uniqueness spans
>>>> multiple.
>>>>
>>>> That is a valid point. We can probably define a new error like
>>>> `IdentifierAlreadyExistError` with just an error message change, such as
>>>> "The given identifier already exists."
>>>>
>>>> > I also don't know what else may collide (functions, indexes, etc.).
>>>> Some of this might be engine specific.
>>>>
>>>> Most engines/databases seem to treat functions separately. Here is the
>>>> AI research result.
>>>> [image: image.png]
>>>>
>>>> Regarding index, I was thinking we can revisit once we have more
>>>> clarify on its design and catalog storage.
>>>>
>>>> On Tue, Mar 24, 2026 at 5:57 AM Maximilian Michels <mx...@apache.org>
>>>> wrote:
>>>>
>>>>> +1 for improving the error messages and restricting identifier
>>>>> uniqueness to tables and views only. We could have also gone with "the
>>>>> identifier already exists", but this is more nuanced.
>>>>>
>>>>> On Tue, Mar 24, 2026 at 10:17 AM Péter Váry <
>>>>> peter.vary.apache@gmail.com> wrote:
>>>>> >
>>>>> > +1 on consistent "Conflict - The identifier already exists as a
>>>>> table or view"
>>>>> >
>>>>> > Steven Wu <st...@gmail.com> ezt írta (időpont: 2026. márc.
>>>>> 24., K, 6:30):
>>>>> >>
>>>>> >> Enforcing cross-type uniqueness (table or view):
>>>>> >>
>>>>> >> renameTable, renameView, registerView say: "already exists as a
>>>>> table or view"
>>>>> >>
>>>>> >> Only enforcing within the same type (table or view only):
>>>>> >>
>>>>> >> createTable, registerTable, createView say: "table already exists"
>>>>> / "view already exists"
>>>>> >>
>>>>> >>
>>>>> >> I updated the PR to use the consistent wording "already exists as a
>>>>> table or view" for the 409 conflict.
>>>>> >>
>>>>> >>
>>>>> >> On Mon, Mar 23, 2026 at 8:30 AM Péter Váry <
>>>>> peter.vary.apache@gmail.com> wrote:
>>>>> >>>
>>>>> >>> We need a `role` paired with the identifier to get the requested
>>>>> object. The `role` in this case can be the same for tables, views and MVs
>>>>> >>>
>>>>> >>> Steven Wu <st...@gmail.com> ezt írta (időpont: 2026. márc.
>>>>> 21., Szo, 22:08):
>>>>> >>>>
>>>>> >>>> > Do we really want to prevent creating a `rank` function if we
>>>>> already have a table named `rank`?
>>>>> >>>>
>>>>> >>>> This is a good argument. I agree functions can be in a separate
>>>>> dimension.
>>>>> >>>>
>>>>> >>>> Earlier, I was thinking from the perspective of a universal batch
>>>>> load endpoint, where a client may send one catalog request for all
>>>>> referenced objects (tables, views, MVs, functions). We can still make it
>>>>> work if functions are separated out in the batch load request. Or we can
>>>>> limit the universal batch load endpoint to tables, views, and MVs only.
>>>>> >>>>
>>>>> >>>> Clients may not need to load index objects separately. They can
>>>>> be piggybacked during table loading.
>>>>> >>>>
>>>>> >>>> On Sat, Mar 21, 2026 at 12:38 AM Péter Váry <
>>>>> peter.vary.apache@gmail.com> wrote:
>>>>> >>>>>
>>>>> >>>>> I think we definitely should discuss the global uniqueness in
>>>>> details.
>>>>> >>>>>
>>>>> >>>>> Do we really want to prevent creating a `rank` function if we
>>>>> already have a table named `rank`?
>>>>> >>>>>
>>>>> >>>>> I'm fully on board to avoid having the same name for a table and
>>>>> a view, as they are fully interchangeable, but functions and indexes could
>>>>> use the same name and the engines could decide which one to use based on
>>>>> the context.
>>>>> >>>>>
>>>>> >>>>> So I think we need to seriously consider if we want to propose
>>>>> restrictions like this.
>>>>> >>>>>
>>>>> >>>>> WDYT?
>>>>> >>>>>
>>>>> >>>>>
>>>>> >>>>> On Fri, Mar 20, 2026, 15:19 Steven Wu <st...@gmail.com>
>>>>> wrote:
>>>>> >>>>>>
>>>>> >>>>>> Hi Peter,
>>>>> >>>>>>
>>>>> >>>>>> I can understand the hesitation, especially considering the new
>>>>> CatalogObjectType not used by the spec (except for the references in the
>>>>> description text).
>>>>> >>>>>>
>>>>> >>>>>> I added it in this PR for the following reasons:
>>>>> >>>>>> * Huaxin has a PR for functions [1], which will introduce a new
>>>>> function object type in the catalog. I believe we want to enforce
>>>>> uniqueness across all types: tables, views, and functions.
>>>>> >>>>>> * index proposal also discussed the index object type in the
>>>>> catalog. but this is a bit farther away.
>>>>> >>>>>> * Events endpoint proposal also needs to introduce the
>>>>> CatalogObjectType concept [2, 3].
>>>>> >>>>>>
>>>>> >>>>>> I am ok with removing it from this PR. We can add it later,
>>>>> perhaps, in the events or function endpoint spec change.
>>>>> >>>>>>
>>>>> >>>>>> Thanks,
>>>>> >>>>>> Steven
>>>>> >>>>>>
>>>>> >>>>>> [1] Function endpoint spec:
>>>>> https://github.com/apache/iceberg/pull/15180
>>>>> >>>>>> [2] Events endpoint spec:
>>>>> https://github.com/apache/iceberg/pull/12584
>>>>> >>>>>> [3] Events endpoint impl:
>>>>> https://github.com/apache/iceberg/pull/14142
>>>>> >>>>>>
>>>>> >>>>>>
>>>>> >>>>>>
>>>>> >>>>>> On Fri, Mar 20, 2026 at 3:00 AM Péter Váry <
>>>>> peter.vary.apache@gmail.com> wrote:
>>>>> >>>>>>>
>>>>> >>>>>>> Hi Steven,
>>>>> >>>>>>> I completely agree that we should align the uniqueness
>>>>> requirements between table and view creation.
>>>>> >>>>>>> I’m a bit hesitant about introducing CatalogObjectType. It
>>>>> makes sense if we expect to add more object types and want to enforce
>>>>> uniqueness across them, but I’m not sure we need that level of generality
>>>>> yet. Do you have something specific in mind that would require it?
>>>>> >>>>>>> Thanks,
>>>>> >>>>>>> Peter
>>>>> >>>>>>>
>>>>> >>>>>>> Steven Wu <st...@gmail.com> ezt írta (időpont: 2026.
>>>>> márc. 19., Cs, 21:17):
>>>>> >>>>>>>>
>>>>> >>>>>>>> Hi all,
>>>>> >>>>>>>>
>>>>> >>>>>>>> I'd like to discuss a minor inconsistency in the REST Catalog
>>>>> specification regarding identifier uniqueness within a namespace.
>>>>> >>>>>>>>
>>>>> >>>>>>>> Background: Inconsistency in Conflict Descriptions
>>>>> >>>>>>>>
>>>>> >>>>>>>> The REST spec currently defines six write operations that
>>>>> return a 409 Conflict when an identifier already exists: createTable,
>>>>> registerTable, renameTable, createView, renameView, and registerView.
>>>>> >>>>>>>>
>>>>> >>>>>>>> However, the descriptions for what constitutes a conflict are
>>>>> not consistent:
>>>>> >>>>>>>>
>>>>> >>>>>>>> Enforcing cross-type uniqueness (table or view):
>>>>> >>>>>>>>
>>>>> >>>>>>>> renameTable, renameView, registerView say: "already exists as
>>>>> a table or view"
>>>>> >>>>>>>>
>>>>> >>>>>>>> Only enforcing within the same type (table or view only):
>>>>> >>>>>>>>
>>>>> >>>>>>>> createTable, registerTable, createView say: "table already
>>>>> exists" / "view already exists"
>>>>> >>>>>>>>
>>>>> >>>>>>>> This ambiguity leaves it unclear whether a catalog is allowed
>>>>> to have a table and a view with the same name in the same namespace.
>>>>> >>>>>>>>
>>>>> >>>>>>>> Proposed Change
>>>>> >>>>>>>>
>>>>> >>>>>>>> I believe the intent is that identifiers must be unique
>>>>> across all catalog object types within the same namespace (otherwise the
>>>>> rename operations become impossible to reason about).
>>>>> >>>>>>>>
>>>>> >>>>>>>> The proposed change makes this explicit in two ways:
>>>>> >>>>>>>>
>>>>> >>>>>>>> New CatalogObjectType schema: Enumerates the known catalog
>>>>> object types (table, view) and states the uniqueness invariant:
>>>>> "Identifiers MUST be unique across all catalog object types within the same
>>>>> namespace; a table and a view with the same name in the same namespace are
>>>>> not allowed."
>>>>> >>>>>>>> Consistent 409 descriptions: All six write operations will
>>>>> now reference CatalogObjectType and use uniform language: "The identifier
>>>>> is already used by an existing catalog object (see CatalogObjectType)"
>>>>> >>>>>>>>
>>>>> >>>>>>>> This change is purely spec-clarification; it introduces no
>>>>> new behavior for catalogs that already enforce cross-type uniqueness.
>>>>> >>>>>>>>
>>>>> >>>>>>>> The proposed clarification is available here:
>>>>> https://github.com/apache/iceberg/pull/15691
>>>>> >>>>>>>>
>>>>> >>>>>>>> Thanks,
>>>>> >>>>>>>> Steven
>>>>>
>>>>

Re: [DISCUSS] REST Spec: Clarify identifier uniqueness across catalog object types

[Yufei Gu <fl...@gmail.com>]

+1 on clarifying that tables and views share a namespace, so their names
must be unique. It would also be helpful to explicitly state that UDFs can
coexist with tables and views under the same namespace using the same name.
Leaving this unspecified may lead to inconsistent behavior across catalog
implementations, as each may interpret the spec differently.

Yufei


On Wed, Mar 25, 2026 at 2:37 PM Ryan Blue <rd...@gmail.com> wrote:

> I think it's a good idea to update the spec to show that a conflict
> could be caused by a table in the view methods or a view in the table
> methods. I also think it is good to clarify the assumption that tables and
> views share a namespace, since we are talking about routes that will load
> either one by name and this is a critical part of that behavior. Before, we
> didn't have a clear reason to make this a requirement, so I think we left
> it unspecified.
>
> As for other objects, I don't think that it is a good idea to include
> functions. To me, those are separate objects that can coexist with the same
> name as Peter pointed out. And indexes are a bit too early to think about
> since they may be table-specific and not catalog-tracked objects.
>
> On Wed, Mar 25, 2026 at 7:55 AM Daniel Weeks <dw...@apache.org> wrote:
>
>> I would just add that this issue is largely isolated to the spec
>> definition and likely has little impact on the implementations.
>>
>> The various conflict responses (TableAlreadyExistsError,
>> ViewAlreadyExistsError, etc.) are all just slightly different flavors of
>> 409 CONFLICT that we send back to the client.  The only practical
>> difference is the text we send back.
>>
>> If we wanted to formalize the right response for the conflicting object
>> (not based on which route was used), we could change the responses to
>> "oneOf" and the spec would allow for representing the conflict accurately.
>> In practice, I think this is what some catalog implementations already do.
>>
>> -Dan
>>
>> On Tue, Mar 24, 2026 at 1:22 PM Steven Wu <st...@gmail.com> wrote:
>>
>>> Pasting Dan's questions from the voting thread
>>>
>>> > There's actually a more significant discrepancy in that the
>>> create/rename/register view can only return a ViewAlreadyExistsError even
>>> if it's a table and create/rename/register Table can only return a
>>> TableAlreadyExistsError even if it's a view.
>>> > I think clarifying the description doesn't really address this issue
>>> and functionally we've strictly defined two specific return types that are
>>> aligned with their specific load routes, but identifier uniqueness spans
>>> multiple.
>>>
>>> That is a valid point. We can probably define a new error like
>>> `IdentifierAlreadyExistError` with just an error message change, such as
>>> "The given identifier already exists."
>>>
>>> > I also don't know what else may collide (functions, indexes, etc.).
>>> Some of this might be engine specific.
>>>
>>> Most engines/databases seem to treat functions separately. Here is the
>>> AI research result.
>>> [image: image.png]
>>>
>>> Regarding index, I was thinking we can revisit once we have more clarify
>>> on its design and catalog storage.
>>>
>>> On Tue, Mar 24, 2026 at 5:57 AM Maximilian Michels <mx...@apache.org>
>>> wrote:
>>>
>>>> +1 for improving the error messages and restricting identifier
>>>> uniqueness to tables and views only. We could have also gone with "the
>>>> identifier already exists", but this is more nuanced.
>>>>
>>>> On Tue, Mar 24, 2026 at 10:17 AM Péter Váry <
>>>> peter.vary.apache@gmail.com> wrote:
>>>> >
>>>> > +1 on consistent "Conflict - The identifier already exists as a table
>>>> or view"
>>>> >
>>>> > Steven Wu <st...@gmail.com> ezt írta (időpont: 2026. márc. 24.,
>>>> K, 6:30):
>>>> >>
>>>> >> Enforcing cross-type uniqueness (table or view):
>>>> >>
>>>> >> renameTable, renameView, registerView say: "already exists as a
>>>> table or view"
>>>> >>
>>>> >> Only enforcing within the same type (table or view only):
>>>> >>
>>>> >> createTable, registerTable, createView say: "table already exists" /
>>>> "view already exists"
>>>> >>
>>>> >>
>>>> >> I updated the PR to use the consistent wording "already exists as a
>>>> table or view" for the 409 conflict.
>>>> >>
>>>> >>
>>>> >> On Mon, Mar 23, 2026 at 8:30 AM Péter Váry <
>>>> peter.vary.apache@gmail.com> wrote:
>>>> >>>
>>>> >>> We need a `role` paired with the identifier to get the requested
>>>> object. The `role` in this case can be the same for tables, views and MVs
>>>> >>>
>>>> >>> Steven Wu <st...@gmail.com> ezt írta (időpont: 2026. márc.
>>>> 21., Szo, 22:08):
>>>> >>>>
>>>> >>>> > Do we really want to prevent creating a `rank` function if we
>>>> already have a table named `rank`?
>>>> >>>>
>>>> >>>> This is a good argument. I agree functions can be in a separate
>>>> dimension.
>>>> >>>>
>>>> >>>> Earlier, I was thinking from the perspective of a universal batch
>>>> load endpoint, where a client may send one catalog request for all
>>>> referenced objects (tables, views, MVs, functions). We can still make it
>>>> work if functions are separated out in the batch load request. Or we can
>>>> limit the universal batch load endpoint to tables, views, and MVs only.
>>>> >>>>
>>>> >>>> Clients may not need to load index objects separately. They can be
>>>> piggybacked during table loading.
>>>> >>>>
>>>> >>>> On Sat, Mar 21, 2026 at 12:38 AM Péter Váry <
>>>> peter.vary.apache@gmail.com> wrote:
>>>> >>>>>
>>>> >>>>> I think we definitely should discuss the global uniqueness in
>>>> details.
>>>> >>>>>
>>>> >>>>> Do we really want to prevent creating a `rank` function if we
>>>> already have a table named `rank`?
>>>> >>>>>
>>>> >>>>> I'm fully on board to avoid having the same name for a table and
>>>> a view, as they are fully interchangeable, but functions and indexes could
>>>> use the same name and the engines could decide which one to use based on
>>>> the context.
>>>> >>>>>
>>>> >>>>> So I think we need to seriously consider if we want to propose
>>>> restrictions like this.
>>>> >>>>>
>>>> >>>>> WDYT?
>>>> >>>>>
>>>> >>>>>
>>>> >>>>> On Fri, Mar 20, 2026, 15:19 Steven Wu <st...@gmail.com>
>>>> wrote:
>>>> >>>>>>
>>>> >>>>>> Hi Peter,
>>>> >>>>>>
>>>> >>>>>> I can understand the hesitation, especially considering the new
>>>> CatalogObjectType not used by the spec (except for the references in the
>>>> description text).
>>>> >>>>>>
>>>> >>>>>> I added it in this PR for the following reasons:
>>>> >>>>>> * Huaxin has a PR for functions [1], which will introduce a new
>>>> function object type in the catalog. I believe we want to enforce
>>>> uniqueness across all types: tables, views, and functions.
>>>> >>>>>> * index proposal also discussed the index object type in the
>>>> catalog. but this is a bit farther away.
>>>> >>>>>> * Events endpoint proposal also needs to introduce the
>>>> CatalogObjectType concept [2, 3].
>>>> >>>>>>
>>>> >>>>>> I am ok with removing it from this PR. We can add it later,
>>>> perhaps, in the events or function endpoint spec change.
>>>> >>>>>>
>>>> >>>>>> Thanks,
>>>> >>>>>> Steven
>>>> >>>>>>
>>>> >>>>>> [1] Function endpoint spec:
>>>> https://github.com/apache/iceberg/pull/15180
>>>> >>>>>> [2] Events endpoint spec:
>>>> https://github.com/apache/iceberg/pull/12584
>>>> >>>>>> [3] Events endpoint impl:
>>>> https://github.com/apache/iceberg/pull/14142
>>>> >>>>>>
>>>> >>>>>>
>>>> >>>>>>
>>>> >>>>>> On Fri, Mar 20, 2026 at 3:00 AM Péter Váry <
>>>> peter.vary.apache@gmail.com> wrote:
>>>> >>>>>>>
>>>> >>>>>>> Hi Steven,
>>>> >>>>>>> I completely agree that we should align the uniqueness
>>>> requirements between table and view creation.
>>>> >>>>>>> I’m a bit hesitant about introducing CatalogObjectType. It
>>>> makes sense if we expect to add more object types and want to enforce
>>>> uniqueness across them, but I’m not sure we need that level of generality
>>>> yet. Do you have something specific in mind that would require it?
>>>> >>>>>>> Thanks,
>>>> >>>>>>> Peter
>>>> >>>>>>>
>>>> >>>>>>> Steven Wu <st...@gmail.com> ezt írta (időpont: 2026.
>>>> márc. 19., Cs, 21:17):
>>>> >>>>>>>>
>>>> >>>>>>>> Hi all,
>>>> >>>>>>>>
>>>> >>>>>>>> I'd like to discuss a minor inconsistency in the REST Catalog
>>>> specification regarding identifier uniqueness within a namespace.
>>>> >>>>>>>>
>>>> >>>>>>>> Background: Inconsistency in Conflict Descriptions
>>>> >>>>>>>>
>>>> >>>>>>>> The REST spec currently defines six write operations that
>>>> return a 409 Conflict when an identifier already exists: createTable,
>>>> registerTable, renameTable, createView, renameView, and registerView.
>>>> >>>>>>>>
>>>> >>>>>>>> However, the descriptions for what constitutes a conflict are
>>>> not consistent:
>>>> >>>>>>>>
>>>> >>>>>>>> Enforcing cross-type uniqueness (table or view):
>>>> >>>>>>>>
>>>> >>>>>>>> renameTable, renameView, registerView say: "already exists as
>>>> a table or view"
>>>> >>>>>>>>
>>>> >>>>>>>> Only enforcing within the same type (table or view only):
>>>> >>>>>>>>
>>>> >>>>>>>> createTable, registerTable, createView say: "table already
>>>> exists" / "view already exists"
>>>> >>>>>>>>
>>>> >>>>>>>> This ambiguity leaves it unclear whether a catalog is allowed
>>>> to have a table and a view with the same name in the same namespace.
>>>> >>>>>>>>
>>>> >>>>>>>> Proposed Change
>>>> >>>>>>>>
>>>> >>>>>>>> I believe the intent is that identifiers must be unique across
>>>> all catalog object types within the same namespace (otherwise the rename
>>>> operations become impossible to reason about).
>>>> >>>>>>>>
>>>> >>>>>>>> The proposed change makes this explicit in two ways:
>>>> >>>>>>>>
>>>> >>>>>>>> New CatalogObjectType schema: Enumerates the known catalog
>>>> object types (table, view) and states the uniqueness invariant:
>>>> "Identifiers MUST be unique across all catalog object types within the same
>>>> namespace; a table and a view with the same name in the same namespace are
>>>> not allowed."
>>>> >>>>>>>> Consistent 409 descriptions: All six write operations will now
>>>> reference CatalogObjectType and use uniform language: "The identifier is
>>>> already used by an existing catalog object (see CatalogObjectType)"
>>>> >>>>>>>>
>>>> >>>>>>>> This change is purely spec-clarification; it introduces no new
>>>> behavior for catalogs that already enforce cross-type uniqueness.
>>>> >>>>>>>>
>>>> >>>>>>>> The proposed clarification is available here:
>>>> https://github.com/apache/iceberg/pull/15691
>>>> >>>>>>>>
>>>> >>>>>>>> Thanks,
>>>> >>>>>>>> Steven
>>>>
>>>

Re: [DISCUSS] REST Spec: Clarify identifier uniqueness across catalog object types

[Ryan Blue <rd...@gmail.com>]

I think it's a good idea to update the spec to show that a conflict
could be caused by a table in the view methods or a view in the table
methods. I also think it is good to clarify the assumption that tables and
views share a namespace, since we are talking about routes that will load
either one by name and this is a critical part of that behavior. Before, we
didn't have a clear reason to make this a requirement, so I think we left
it unspecified.

As for other objects, I don't think that it is a good idea to include
functions. To me, those are separate objects that can coexist with the same
name as Peter pointed out. And indexes are a bit too early to think about
since they may be table-specific and not catalog-tracked objects.

On Wed, Mar 25, 2026 at 7:55 AM Daniel Weeks <dw...@apache.org> wrote:

> I would just add that this issue is largely isolated to the spec
> definition and likely has little impact on the implementations.
>
> The various conflict responses (TableAlreadyExistsError,
> ViewAlreadyExistsError, etc.) are all just slightly different flavors of
> 409 CONFLICT that we send back to the client.  The only practical
> difference is the text we send back.
>
> If we wanted to formalize the right response for the conflicting object
> (not based on which route was used), we could change the responses to
> "oneOf" and the spec would allow for representing the conflict accurately.
> In practice, I think this is what some catalog implementations already do.
>
> -Dan
>
> On Tue, Mar 24, 2026 at 1:22 PM Steven Wu <st...@gmail.com> wrote:
>
>> Pasting Dan's questions from the voting thread
>>
>> > There's actually a more significant discrepancy in that the
>> create/rename/register view can only return a ViewAlreadyExistsError even
>> if it's a table and create/rename/register Table can only return a
>> TableAlreadyExistsError even if it's a view.
>> > I think clarifying the description doesn't really address this issue
>> and functionally we've strictly defined two specific return types that are
>> aligned with their specific load routes, but identifier uniqueness spans
>> multiple.
>>
>> That is a valid point. We can probably define a new error like
>> `IdentifierAlreadyExistError` with just an error message change, such as
>> "The given identifier already exists."
>>
>> > I also don't know what else may collide (functions, indexes, etc.).
>> Some of this might be engine specific.
>>
>> Most engines/databases seem to treat functions separately. Here is the AI
>> research result.
>> [image: image.png]
>>
>> Regarding index, I was thinking we can revisit once we have more clarify
>> on its design and catalog storage.
>>
>> On Tue, Mar 24, 2026 at 5:57 AM Maximilian Michels <mx...@apache.org>
>> wrote:
>>
>>> +1 for improving the error messages and restricting identifier
>>> uniqueness to tables and views only. We could have also gone with "the
>>> identifier already exists", but this is more nuanced.
>>>
>>> On Tue, Mar 24, 2026 at 10:17 AM Péter Váry <pe...@gmail.com>
>>> wrote:
>>> >
>>> > +1 on consistent "Conflict - The identifier already exists as a table
>>> or view"
>>> >
>>> > Steven Wu <st...@gmail.com> ezt írta (időpont: 2026. márc. 24.,
>>> K, 6:30):
>>> >>
>>> >> Enforcing cross-type uniqueness (table or view):
>>> >>
>>> >> renameTable, renameView, registerView say: "already exists as a table
>>> or view"
>>> >>
>>> >> Only enforcing within the same type (table or view only):
>>> >>
>>> >> createTable, registerTable, createView say: "table already exists" /
>>> "view already exists"
>>> >>
>>> >>
>>> >> I updated the PR to use the consistent wording "already exists as a
>>> table or view" for the 409 conflict.
>>> >>
>>> >>
>>> >> On Mon, Mar 23, 2026 at 8:30 AM Péter Váry <
>>> peter.vary.apache@gmail.com> wrote:
>>> >>>
>>> >>> We need a `role` paired with the identifier to get the requested
>>> object. The `role` in this case can be the same for tables, views and MVs
>>> >>>
>>> >>> Steven Wu <st...@gmail.com> ezt írta (időpont: 2026. márc.
>>> 21., Szo, 22:08):
>>> >>>>
>>> >>>> > Do we really want to prevent creating a `rank` function if we
>>> already have a table named `rank`?
>>> >>>>
>>> >>>> This is a good argument. I agree functions can be in a separate
>>> dimension.
>>> >>>>
>>> >>>> Earlier, I was thinking from the perspective of a universal batch
>>> load endpoint, where a client may send one catalog request for all
>>> referenced objects (tables, views, MVs, functions). We can still make it
>>> work if functions are separated out in the batch load request. Or we can
>>> limit the universal batch load endpoint to tables, views, and MVs only.
>>> >>>>
>>> >>>> Clients may not need to load index objects separately. They can be
>>> piggybacked during table loading.
>>> >>>>
>>> >>>> On Sat, Mar 21, 2026 at 12:38 AM Péter Váry <
>>> peter.vary.apache@gmail.com> wrote:
>>> >>>>>
>>> >>>>> I think we definitely should discuss the global uniqueness in
>>> details.
>>> >>>>>
>>> >>>>> Do we really want to prevent creating a `rank` function if we
>>> already have a table named `rank`?
>>> >>>>>
>>> >>>>> I'm fully on board to avoid having the same name for a table and a
>>> view, as they are fully interchangeable, but functions and indexes could
>>> use the same name and the engines could decide which one to use based on
>>> the context.
>>> >>>>>
>>> >>>>> So I think we need to seriously consider if we want to propose
>>> restrictions like this.
>>> >>>>>
>>> >>>>> WDYT?
>>> >>>>>
>>> >>>>>
>>> >>>>> On Fri, Mar 20, 2026, 15:19 Steven Wu <st...@gmail.com>
>>> wrote:
>>> >>>>>>
>>> >>>>>> Hi Peter,
>>> >>>>>>
>>> >>>>>> I can understand the hesitation, especially considering the new
>>> CatalogObjectType not used by the spec (except for the references in the
>>> description text).
>>> >>>>>>
>>> >>>>>> I added it in this PR for the following reasons:
>>> >>>>>> * Huaxin has a PR for functions [1], which will introduce a new
>>> function object type in the catalog. I believe we want to enforce
>>> uniqueness across all types: tables, views, and functions.
>>> >>>>>> * index proposal also discussed the index object type in the
>>> catalog. but this is a bit farther away.
>>> >>>>>> * Events endpoint proposal also needs to introduce the
>>> CatalogObjectType concept [2, 3].
>>> >>>>>>
>>> >>>>>> I am ok with removing it from this PR. We can add it later,
>>> perhaps, in the events or function endpoint spec change.
>>> >>>>>>
>>> >>>>>> Thanks,
>>> >>>>>> Steven
>>> >>>>>>
>>> >>>>>> [1] Function endpoint spec:
>>> https://github.com/apache/iceberg/pull/15180
>>> >>>>>> [2] Events endpoint spec:
>>> https://github.com/apache/iceberg/pull/12584
>>> >>>>>> [3] Events endpoint impl:
>>> https://github.com/apache/iceberg/pull/14142
>>> >>>>>>
>>> >>>>>>
>>> >>>>>>
>>> >>>>>> On Fri, Mar 20, 2026 at 3:00 AM Péter Váry <
>>> peter.vary.apache@gmail.com> wrote:
>>> >>>>>>>
>>> >>>>>>> Hi Steven,
>>> >>>>>>> I completely agree that we should align the uniqueness
>>> requirements between table and view creation.
>>> >>>>>>> I’m a bit hesitant about introducing CatalogObjectType. It makes
>>> sense if we expect to add more object types and want to enforce uniqueness
>>> across them, but I’m not sure we need that level of generality yet. Do you
>>> have something specific in mind that would require it?
>>> >>>>>>> Thanks,
>>> >>>>>>> Peter
>>> >>>>>>>
>>> >>>>>>> Steven Wu <st...@gmail.com> ezt írta (időpont: 2026. márc.
>>> 19., Cs, 21:17):
>>> >>>>>>>>
>>> >>>>>>>> Hi all,
>>> >>>>>>>>
>>> >>>>>>>> I'd like to discuss a minor inconsistency in the REST Catalog
>>> specification regarding identifier uniqueness within a namespace.
>>> >>>>>>>>
>>> >>>>>>>> Background: Inconsistency in Conflict Descriptions
>>> >>>>>>>>
>>> >>>>>>>> The REST spec currently defines six write operations that
>>> return a 409 Conflict when an identifier already exists: createTable,
>>> registerTable, renameTable, createView, renameView, and registerView.
>>> >>>>>>>>
>>> >>>>>>>> However, the descriptions for what constitutes a conflict are
>>> not consistent:
>>> >>>>>>>>
>>> >>>>>>>> Enforcing cross-type uniqueness (table or view):
>>> >>>>>>>>
>>> >>>>>>>> renameTable, renameView, registerView say: "already exists as a
>>> table or view"
>>> >>>>>>>>
>>> >>>>>>>> Only enforcing within the same type (table or view only):
>>> >>>>>>>>
>>> >>>>>>>> createTable, registerTable, createView say: "table already
>>> exists" / "view already exists"
>>> >>>>>>>>
>>> >>>>>>>> This ambiguity leaves it unclear whether a catalog is allowed
>>> to have a table and a view with the same name in the same namespace.
>>> >>>>>>>>
>>> >>>>>>>> Proposed Change
>>> >>>>>>>>
>>> >>>>>>>> I believe the intent is that identifiers must be unique across
>>> all catalog object types within the same namespace (otherwise the rename
>>> operations become impossible to reason about).
>>> >>>>>>>>
>>> >>>>>>>> The proposed change makes this explicit in two ways:
>>> >>>>>>>>
>>> >>>>>>>> New CatalogObjectType schema: Enumerates the known catalog
>>> object types (table, view) and states the uniqueness invariant:
>>> "Identifiers MUST be unique across all catalog object types within the same
>>> namespace; a table and a view with the same name in the same namespace are
>>> not allowed."
>>> >>>>>>>> Consistent 409 descriptions: All six write operations will now
>>> reference CatalogObjectType and use uniform language: "The identifier is
>>> already used by an existing catalog object (see CatalogObjectType)"
>>> >>>>>>>>
>>> >>>>>>>> This change is purely spec-clarification; it introduces no new
>>> behavior for catalogs that already enforce cross-type uniqueness.
>>> >>>>>>>>
>>> >>>>>>>> The proposed clarification is available here:
>>> https://github.com/apache/iceberg/pull/15691
>>> >>>>>>>>
>>> >>>>>>>> Thanks,
>>> >>>>>>>> Steven
>>>
>>

Re: [DISCUSS] REST Spec: Clarify identifier uniqueness across catalog object types

[Steven Wu <st...@gmail.com>]

> The various conflict responses (TableAlreadyExistsError,
ViewAlreadyExistsError, etc.) are all just slightly different flavors of
409 CONFLICT that we send back to the client.  The only practical
difference is the text we send back.

That is exactly right. This PR mainly clarifies that the catalog
implementation should honor the conflict check across tables and views for
those 6 endpoints.

> If we wanted to formalize the right response for the conflicting object
(not based on which route was used), we could change the responses to
"oneOf" and the spec would allow for representing the conflict accurately.
In practice, I think this is what some catalog implementations already do.

I am not sure we need "oneOf" here. E.g., if a registerView call fails with
409 because a table with the same name exists, the error message should
simply be "The requested view identifier already exists" regardless of
whether the existing object is a table or a view. I actually find the
summary descriptions in the two error objects pretty accurate. I updated
the PR to use them for the error message.
https://github.com/apache/iceberg/pull/15691/changes


On Wed, Mar 25, 2026 at 7:57 AM Daniel Weeks <dw...@apache.org> wrote:

> I would just add that this issue is largely isolated to the spec
> definition and likely has little impact on the implementations.
>
> The various conflict responses (TableAlreadyExistsError,
> ViewAlreadyExistsError, etc.) are all just slightly different flavors of
> 409 CONFLICT that we send back to the client.  The only practical
> difference is the text we send back.
>
> If we wanted to formalize the right response for the conflicting object
> (not based on which route was used), we could change the responses to
> "oneOf" and the spec would allow for representing the conflict accurately.
> In practice, I think this is what some catalog implementations already do.
>
> -Dan
>
> On Tue, Mar 24, 2026 at 1:22 PM Steven Wu <st...@gmail.com> wrote:
>
>> Pasting Dan's questions from the voting thread
>>
>> > There's actually a more significant discrepancy in that the
>> create/rename/register view can only return a ViewAlreadyExistsError even
>> if it's a table and create/rename/register Table can only return a
>> TableAlreadyExistsError even if it's a view.
>> > I think clarifying the description doesn't really address this issue
>> and functionally we've strictly defined two specific return types that are
>> aligned with their specific load routes, but identifier uniqueness spans
>> multiple.
>>
>> That is a valid point. We can probably define a new error like
>> `IdentifierAlreadyExistError` with just an error message change, such as
>> "The given identifier already exists."
>>
>> > I also don't know what else may collide (functions, indexes, etc.).
>> Some of this might be engine specific.
>>
>> Most engines/databases seem to treat functions separately. Here is the AI
>> research result.
>> [image: image.png]
>>
>> Regarding index, I was thinking we can revisit once we have more clarify
>> on its design and catalog storage.
>>
>> On Tue, Mar 24, 2026 at 5:57 AM Maximilian Michels <mx...@apache.org>
>> wrote:
>>
>>> +1 for improving the error messages and restricting identifier
>>> uniqueness to tables and views only. We could have also gone with "the
>>> identifier already exists", but this is more nuanced.
>>>
>>> On Tue, Mar 24, 2026 at 10:17 AM Péter Váry <pe...@gmail.com>
>>> wrote:
>>> >
>>> > +1 on consistent "Conflict - The identifier already exists as a table
>>> or view"
>>> >
>>> > Steven Wu <st...@gmail.com> ezt írta (időpont: 2026. márc. 24.,
>>> K, 6:30):
>>> >>
>>> >> Enforcing cross-type uniqueness (table or view):
>>> >>
>>> >> renameTable, renameView, registerView say: "already exists as a table
>>> or view"
>>> >>
>>> >> Only enforcing within the same type (table or view only):
>>> >>
>>> >> createTable, registerTable, createView say: "table already exists" /
>>> "view already exists"
>>> >>
>>> >>
>>> >> I updated the PR to use the consistent wording "already exists as a
>>> table or view" for the 409 conflict.
>>> >>
>>> >>
>>> >> On Mon, Mar 23, 2026 at 8:30 AM Péter Váry <
>>> peter.vary.apache@gmail.com> wrote:
>>> >>>
>>> >>> We need a `role` paired with the identifier to get the requested
>>> object. The `role` in this case can be the same for tables, views and MVs
>>> >>>
>>> >>> Steven Wu <st...@gmail.com> ezt írta (időpont: 2026. márc.
>>> 21., Szo, 22:08):
>>> >>>>
>>> >>>> > Do we really want to prevent creating a `rank` function if we
>>> already have a table named `rank`?
>>> >>>>
>>> >>>> This is a good argument. I agree functions can be in a separate
>>> dimension.
>>> >>>>
>>> >>>> Earlier, I was thinking from the perspective of a universal batch
>>> load endpoint, where a client may send one catalog request for all
>>> referenced objects (tables, views, MVs, functions). We can still make it
>>> work if functions are separated out in the batch load request. Or we can
>>> limit the universal batch load endpoint to tables, views, and MVs only.
>>> >>>>
>>> >>>> Clients may not need to load index objects separately. They can be
>>> piggybacked during table loading.
>>> >>>>
>>> >>>> On Sat, Mar 21, 2026 at 12:38 AM Péter Váry <
>>> peter.vary.apache@gmail.com> wrote:
>>> >>>>>
>>> >>>>> I think we definitely should discuss the global uniqueness in
>>> details.
>>> >>>>>
>>> >>>>> Do we really want to prevent creating a `rank` function if we
>>> already have a table named `rank`?
>>> >>>>>
>>> >>>>> I'm fully on board to avoid having the same name for a table and a
>>> view, as they are fully interchangeable, but functions and indexes could
>>> use the same name and the engines could decide which one to use based on
>>> the context.
>>> >>>>>
>>> >>>>> So I think we need to seriously consider if we want to propose
>>> restrictions like this.
>>> >>>>>
>>> >>>>> WDYT?
>>> >>>>>
>>> >>>>>
>>> >>>>> On Fri, Mar 20, 2026, 15:19 Steven Wu <st...@gmail.com>
>>> wrote:
>>> >>>>>>
>>> >>>>>> Hi Peter,
>>> >>>>>>
>>> >>>>>> I can understand the hesitation, especially considering the new
>>> CatalogObjectType not used by the spec (except for the references in the
>>> description text).
>>> >>>>>>
>>> >>>>>> I added it in this PR for the following reasons:
>>> >>>>>> * Huaxin has a PR for functions [1], which will introduce a new
>>> function object type in the catalog. I believe we want to enforce
>>> uniqueness across all types: tables, views, and functions.
>>> >>>>>> * index proposal also discussed the index object type in the
>>> catalog. but this is a bit farther away.
>>> >>>>>> * Events endpoint proposal also needs to introduce the
>>> CatalogObjectType concept [2, 3].
>>> >>>>>>
>>> >>>>>> I am ok with removing it from this PR. We can add it later,
>>> perhaps, in the events or function endpoint spec change.
>>> >>>>>>
>>> >>>>>> Thanks,
>>> >>>>>> Steven
>>> >>>>>>
>>> >>>>>> [1] Function endpoint spec:
>>> https://github.com/apache/iceberg/pull/15180
>>> >>>>>> [2] Events endpoint spec:
>>> https://github.com/apache/iceberg/pull/12584
>>> >>>>>> [3] Events endpoint impl:
>>> https://github.com/apache/iceberg/pull/14142
>>> >>>>>>
>>> >>>>>>
>>> >>>>>>
>>> >>>>>> On Fri, Mar 20, 2026 at 3:00 AM Péter Váry <
>>> peter.vary.apache@gmail.com> wrote:
>>> >>>>>>>
>>> >>>>>>> Hi Steven,
>>> >>>>>>> I completely agree that we should align the uniqueness
>>> requirements between table and view creation.
>>> >>>>>>> I’m a bit hesitant about introducing CatalogObjectType. It makes
>>> sense if we expect to add more object types and want to enforce uniqueness
>>> across them, but I’m not sure we need that level of generality yet. Do you
>>> have something specific in mind that would require it?
>>> >>>>>>> Thanks,
>>> >>>>>>> Peter
>>> >>>>>>>
>>> >>>>>>> Steven Wu <st...@gmail.com> ezt írta (időpont: 2026. márc.
>>> 19., Cs, 21:17):
>>> >>>>>>>>
>>> >>>>>>>> Hi all,
>>> >>>>>>>>
>>> >>>>>>>> I'd like to discuss a minor inconsistency in the REST Catalog
>>> specification regarding identifier uniqueness within a namespace.
>>> >>>>>>>>
>>> >>>>>>>> Background: Inconsistency in Conflict Descriptions
>>> >>>>>>>>
>>> >>>>>>>> The REST spec currently defines six write operations that
>>> return a 409 Conflict when an identifier already exists: createTable,
>>> registerTable, renameTable, createView, renameView, and registerView.
>>> >>>>>>>>
>>> >>>>>>>> However, the descriptions for what constitutes a conflict are
>>> not consistent:
>>> >>>>>>>>
>>> >>>>>>>> Enforcing cross-type uniqueness (table or view):
>>> >>>>>>>>
>>> >>>>>>>> renameTable, renameView, registerView say: "already exists as a
>>> table or view"
>>> >>>>>>>>
>>> >>>>>>>> Only enforcing within the same type (table or view only):
>>> >>>>>>>>
>>> >>>>>>>> createTable, registerTable, createView say: "table already
>>> exists" / "view already exists"
>>> >>>>>>>>
>>> >>>>>>>> This ambiguity leaves it unclear whether a catalog is allowed
>>> to have a table and a view with the same name in the same namespace.
>>> >>>>>>>>
>>> >>>>>>>> Proposed Change
>>> >>>>>>>>
>>> >>>>>>>> I believe the intent is that identifiers must be unique across
>>> all catalog object types within the same namespace (otherwise the rename
>>> operations become impossible to reason about).
>>> >>>>>>>>
>>> >>>>>>>> The proposed change makes this explicit in two ways:
>>> >>>>>>>>
>>> >>>>>>>> New CatalogObjectType schema: Enumerates the known catalog
>>> object types (table, view) and states the uniqueness invariant:
>>> "Identifiers MUST be unique across all catalog object types within the same
>>> namespace; a table and a view with the same name in the same namespace are
>>> not allowed."
>>> >>>>>>>> Consistent 409 descriptions: All six write operations will now
>>> reference CatalogObjectType and use uniform language: "The identifier is
>>> already used by an existing catalog object (see CatalogObjectType)"
>>> >>>>>>>>
>>> >>>>>>>> This change is purely spec-clarification; it introduces no new
>>> behavior for catalogs that already enforce cross-type uniqueness.
>>> >>>>>>>>
>>> >>>>>>>> The proposed clarification is available here:
>>> https://github.com/apache/iceberg/pull/15691
>>> >>>>>>>>
>>> >>>>>>>> Thanks,
>>> >>>>>>>> Steven
>>>
>>

Re: [DISCUSS] REST Spec: Clarify identifier uniqueness across catalog object types

[Daniel Weeks <dw...@apache.org>]

I would just add that this issue is largely isolated to the spec definition
and likely has little impact on the implementations.

The various conflict responses (TableAlreadyExistsError,
ViewAlreadyExistsError, etc.) are all just slightly different flavors of
409 CONFLICT that we send back to the client.  The only practical
difference is the text we send back.

If we wanted to formalize the right response for the conflicting object
(not based on which route was used), we could change the responses to
"oneOf" and the spec would allow for representing the conflict accurately.
In practice, I think this is what some catalog implementations already do.

-Dan

On Tue, Mar 24, 2026 at 1:22 PM Steven Wu <st...@gmail.com> wrote:

> Pasting Dan's questions from the voting thread
>
> > There's actually a more significant discrepancy in that the
> create/rename/register view can only return a ViewAlreadyExistsError even
> if it's a table and create/rename/register Table can only return a
> TableAlreadyExistsError even if it's a view.
> > I think clarifying the description doesn't really address this issue and
> functionally we've strictly defined two specific return types that are
> aligned with their specific load routes, but identifier uniqueness spans
> multiple.
>
> That is a valid point. We can probably define a new error like
> `IdentifierAlreadyExistError` with just an error message change, such as
> "The given identifier already exists."
>
> > I also don't know what else may collide (functions, indexes, etc.). Some
> of this might be engine specific.
>
> Most engines/databases seem to treat functions separately. Here is the AI
> research result.
> [image: image.png]
>
> Regarding index, I was thinking we can revisit once we have more clarify
> on its design and catalog storage.
>
> On Tue, Mar 24, 2026 at 5:57 AM Maximilian Michels <mx...@apache.org> wrote:
>
>> +1 for improving the error messages and restricting identifier
>> uniqueness to tables and views only. We could have also gone with "the
>> identifier already exists", but this is more nuanced.
>>
>> On Tue, Mar 24, 2026 at 10:17 AM Péter Váry <pe...@gmail.com>
>> wrote:
>> >
>> > +1 on consistent "Conflict - The identifier already exists as a table
>> or view"
>> >
>> > Steven Wu <st...@gmail.com> ezt írta (időpont: 2026. márc. 24.,
>> K, 6:30):
>> >>
>> >> Enforcing cross-type uniqueness (table or view):
>> >>
>> >> renameTable, renameView, registerView say: "already exists as a table
>> or view"
>> >>
>> >> Only enforcing within the same type (table or view only):
>> >>
>> >> createTable, registerTable, createView say: "table already exists" /
>> "view already exists"
>> >>
>> >>
>> >> I updated the PR to use the consistent wording "already exists as a
>> table or view" for the 409 conflict.
>> >>
>> >>
>> >> On Mon, Mar 23, 2026 at 8:30 AM Péter Váry <
>> peter.vary.apache@gmail.com> wrote:
>> >>>
>> >>> We need a `role` paired with the identifier to get the requested
>> object. The `role` in this case can be the same for tables, views and MVs
>> >>>
>> >>> Steven Wu <st...@gmail.com> ezt írta (időpont: 2026. márc. 21.,
>> Szo, 22:08):
>> >>>>
>> >>>> > Do we really want to prevent creating a `rank` function if we
>> already have a table named `rank`?
>> >>>>
>> >>>> This is a good argument. I agree functions can be in a separate
>> dimension.
>> >>>>
>> >>>> Earlier, I was thinking from the perspective of a universal batch
>> load endpoint, where a client may send one catalog request for all
>> referenced objects (tables, views, MVs, functions). We can still make it
>> work if functions are separated out in the batch load request. Or we can
>> limit the universal batch load endpoint to tables, views, and MVs only.
>> >>>>
>> >>>> Clients may not need to load index objects separately. They can be
>> piggybacked during table loading.
>> >>>>
>> >>>> On Sat, Mar 21, 2026 at 12:38 AM Péter Váry <
>> peter.vary.apache@gmail.com> wrote:
>> >>>>>
>> >>>>> I think we definitely should discuss the global uniqueness in
>> details.
>> >>>>>
>> >>>>> Do we really want to prevent creating a `rank` function if we
>> already have a table named `rank`?
>> >>>>>
>> >>>>> I'm fully on board to avoid having the same name for a table and a
>> view, as they are fully interchangeable, but functions and indexes could
>> use the same name and the engines could decide which one to use based on
>> the context.
>> >>>>>
>> >>>>> So I think we need to seriously consider if we want to propose
>> restrictions like this.
>> >>>>>
>> >>>>> WDYT?
>> >>>>>
>> >>>>>
>> >>>>> On Fri, Mar 20, 2026, 15:19 Steven Wu <st...@gmail.com> wrote:
>> >>>>>>
>> >>>>>> Hi Peter,
>> >>>>>>
>> >>>>>> I can understand the hesitation, especially considering the new
>> CatalogObjectType not used by the spec (except for the references in the
>> description text).
>> >>>>>>
>> >>>>>> I added it in this PR for the following reasons:
>> >>>>>> * Huaxin has a PR for functions [1], which will introduce a new
>> function object type in the catalog. I believe we want to enforce
>> uniqueness across all types: tables, views, and functions.
>> >>>>>> * index proposal also discussed the index object type in the
>> catalog. but this is a bit farther away.
>> >>>>>> * Events endpoint proposal also needs to introduce the
>> CatalogObjectType concept [2, 3].
>> >>>>>>
>> >>>>>> I am ok with removing it from this PR. We can add it later,
>> perhaps, in the events or function endpoint spec change.
>> >>>>>>
>> >>>>>> Thanks,
>> >>>>>> Steven
>> >>>>>>
>> >>>>>> [1] Function endpoint spec:
>> https://github.com/apache/iceberg/pull/15180
>> >>>>>> [2] Events endpoint spec:
>> https://github.com/apache/iceberg/pull/12584
>> >>>>>> [3] Events endpoint impl:
>> https://github.com/apache/iceberg/pull/14142
>> >>>>>>
>> >>>>>>
>> >>>>>>
>> >>>>>> On Fri, Mar 20, 2026 at 3:00 AM Péter Váry <
>> peter.vary.apache@gmail.com> wrote:
>> >>>>>>>
>> >>>>>>> Hi Steven,
>> >>>>>>> I completely agree that we should align the uniqueness
>> requirements between table and view creation.
>> >>>>>>> I’m a bit hesitant about introducing CatalogObjectType. It makes
>> sense if we expect to add more object types and want to enforce uniqueness
>> across them, but I’m not sure we need that level of generality yet. Do you
>> have something specific in mind that would require it?
>> >>>>>>> Thanks,
>> >>>>>>> Peter
>> >>>>>>>
>> >>>>>>> Steven Wu <st...@gmail.com> ezt írta (időpont: 2026. márc.
>> 19., Cs, 21:17):
>> >>>>>>>>
>> >>>>>>>> Hi all,
>> >>>>>>>>
>> >>>>>>>> I'd like to discuss a minor inconsistency in the REST Catalog
>> specification regarding identifier uniqueness within a namespace.
>> >>>>>>>>
>> >>>>>>>> Background: Inconsistency in Conflict Descriptions
>> >>>>>>>>
>> >>>>>>>> The REST spec currently defines six write operations that return
>> a 409 Conflict when an identifier already exists: createTable,
>> registerTable, renameTable, createView, renameView, and registerView.
>> >>>>>>>>
>> >>>>>>>> However, the descriptions for what constitutes a conflict are
>> not consistent:
>> >>>>>>>>
>> >>>>>>>> Enforcing cross-type uniqueness (table or view):
>> >>>>>>>>
>> >>>>>>>> renameTable, renameView, registerView say: "already exists as a
>> table or view"
>> >>>>>>>>
>> >>>>>>>> Only enforcing within the same type (table or view only):
>> >>>>>>>>
>> >>>>>>>> createTable, registerTable, createView say: "table already
>> exists" / "view already exists"
>> >>>>>>>>
>> >>>>>>>> This ambiguity leaves it unclear whether a catalog is allowed to
>> have a table and a view with the same name in the same namespace.
>> >>>>>>>>
>> >>>>>>>> Proposed Change
>> >>>>>>>>
>> >>>>>>>> I believe the intent is that identifiers must be unique across
>> all catalog object types within the same namespace (otherwise the rename
>> operations become impossible to reason about).
>> >>>>>>>>
>> >>>>>>>> The proposed change makes this explicit in two ways:
>> >>>>>>>>
>> >>>>>>>> New CatalogObjectType schema: Enumerates the known catalog
>> object types (table, view) and states the uniqueness invariant:
>> "Identifiers MUST be unique across all catalog object types within the same
>> namespace; a table and a view with the same name in the same namespace are
>> not allowed."
>> >>>>>>>> Consistent 409 descriptions: All six write operations will now
>> reference CatalogObjectType and use uniform language: "The identifier is
>> already used by an existing catalog object (see CatalogObjectType)"
>> >>>>>>>>
>> >>>>>>>> This change is purely spec-clarification; it introduces no new
>> behavior for catalogs that already enforce cross-type uniqueness.
>> >>>>>>>>
>> >>>>>>>> The proposed clarification is available here:
>> https://github.com/apache/iceberg/pull/15691
>> >>>>>>>>
>> >>>>>>>> Thanks,
>> >>>>>>>> Steven
>>
>

Re: [DISCUSS] REST Spec: Clarify identifier uniqueness across catalog object types

[Steven Wu <st...@gmail.com>]

Pasting Dan's questions from the voting thread

> There's actually a more significant discrepancy in that the
create/rename/register view can only return a ViewAlreadyExistsError even
if it's a table and create/rename/register Table can only return a
TableAlreadyExistsError even if it's a view.
> I think clarifying the description doesn't really address this issue and
functionally we've strictly defined two specific return types that are
aligned with their specific load routes, but identifier uniqueness spans
multiple.

That is a valid point. We can probably define a new error like
`IdentifierAlreadyExistError` with just an error message change, such as
"The given identifier already exists."

> I also don't know what else may collide (functions, indexes, etc.). Some
of this might be engine specific.

Most engines/databases seem to treat functions separately. Here is the AI
research result.
[image: image.png]

Regarding index, I was thinking we can revisit once we have more clarify on
its design and catalog storage.

On Tue, Mar 24, 2026 at 5:57 AM Maximilian Michels <mx...@apache.org> wrote:

> +1 for improving the error messages and restricting identifier
> uniqueness to tables and views only. We could have also gone with "the
> identifier already exists", but this is more nuanced.
>
> On Tue, Mar 24, 2026 at 10:17 AM Péter Váry <pe...@gmail.com>
> wrote:
> >
> > +1 on consistent "Conflict - The identifier already exists as a table or
> view"
> >
> > Steven Wu <st...@gmail.com> ezt írta (időpont: 2026. márc. 24., K,
> 6:30):
> >>
> >> Enforcing cross-type uniqueness (table or view):
> >>
> >> renameTable, renameView, registerView say: "already exists as a table
> or view"
> >>
> >> Only enforcing within the same type (table or view only):
> >>
> >> createTable, registerTable, createView say: "table already exists" /
> "view already exists"
> >>
> >>
> >> I updated the PR to use the consistent wording "already exists as a
> table or view" for the 409 conflict.
> >>
> >>
> >> On Mon, Mar 23, 2026 at 8:30 AM Péter Váry <pe...@gmail.com>
> wrote:
> >>>
> >>> We need a `role` paired with the identifier to get the requested
> object. The `role` in this case can be the same for tables, views and MVs
> >>>
> >>> Steven Wu <st...@gmail.com> ezt írta (időpont: 2026. márc. 21.,
> Szo, 22:08):
> >>>>
> >>>> > Do we really want to prevent creating a `rank` function if we
> already have a table named `rank`?
> >>>>
> >>>> This is a good argument. I agree functions can be in a separate
> dimension.
> >>>>
> >>>> Earlier, I was thinking from the perspective of a universal batch
> load endpoint, where a client may send one catalog request for all
> referenced objects (tables, views, MVs, functions). We can still make it
> work if functions are separated out in the batch load request. Or we can
> limit the universal batch load endpoint to tables, views, and MVs only.
> >>>>
> >>>> Clients may not need to load index objects separately. They can be
> piggybacked during table loading.
> >>>>
> >>>> On Sat, Mar 21, 2026 at 12:38 AM Péter Váry <
> peter.vary.apache@gmail.com> wrote:
> >>>>>
> >>>>> I think we definitely should discuss the global uniqueness in
> details.
> >>>>>
> >>>>> Do we really want to prevent creating a `rank` function if we
> already have a table named `rank`?
> >>>>>
> >>>>> I'm fully on board to avoid having the same name for a table and a
> view, as they are fully interchangeable, but functions and indexes could
> use the same name and the engines could decide which one to use based on
> the context.
> >>>>>
> >>>>> So I think we need to seriously consider if we want to propose
> restrictions like this.
> >>>>>
> >>>>> WDYT?
> >>>>>
> >>>>>
> >>>>> On Fri, Mar 20, 2026, 15:19 Steven Wu <st...@gmail.com> wrote:
> >>>>>>
> >>>>>> Hi Peter,
> >>>>>>
> >>>>>> I can understand the hesitation, especially considering the new
> CatalogObjectType not used by the spec (except for the references in the
> description text).
> >>>>>>
> >>>>>> I added it in this PR for the following reasons:
> >>>>>> * Huaxin has a PR for functions [1], which will introduce a new
> function object type in the catalog. I believe we want to enforce
> uniqueness across all types: tables, views, and functions.
> >>>>>> * index proposal also discussed the index object type in the
> catalog. but this is a bit farther away.
> >>>>>> * Events endpoint proposal also needs to introduce the
> CatalogObjectType concept [2, 3].
> >>>>>>
> >>>>>> I am ok with removing it from this PR. We can add it later,
> perhaps, in the events or function endpoint spec change.
> >>>>>>
> >>>>>> Thanks,
> >>>>>> Steven
> >>>>>>
> >>>>>> [1] Function endpoint spec:
> https://github.com/apache/iceberg/pull/15180
> >>>>>> [2] Events endpoint spec:
> https://github.com/apache/iceberg/pull/12584
> >>>>>> [3] Events endpoint impl:
> https://github.com/apache/iceberg/pull/14142
> >>>>>>
> >>>>>>
> >>>>>>
> >>>>>> On Fri, Mar 20, 2026 at 3:00 AM Péter Váry <
> peter.vary.apache@gmail.com> wrote:
> >>>>>>>
> >>>>>>> Hi Steven,
> >>>>>>> I completely agree that we should align the uniqueness
> requirements between table and view creation.
> >>>>>>> I’m a bit hesitant about introducing CatalogObjectType. It makes
> sense if we expect to add more object types and want to enforce uniqueness
> across them, but I’m not sure we need that level of generality yet. Do you
> have something specific in mind that would require it?
> >>>>>>> Thanks,
> >>>>>>> Peter
> >>>>>>>
> >>>>>>> Steven Wu <st...@gmail.com> ezt írta (időpont: 2026. márc.
> 19., Cs, 21:17):
> >>>>>>>>
> >>>>>>>> Hi all,
> >>>>>>>>
> >>>>>>>> I'd like to discuss a minor inconsistency in the REST Catalog
> specification regarding identifier uniqueness within a namespace.
> >>>>>>>>
> >>>>>>>> Background: Inconsistency in Conflict Descriptions
> >>>>>>>>
> >>>>>>>> The REST spec currently defines six write operations that return
> a 409 Conflict when an identifier already exists: createTable,
> registerTable, renameTable, createView, renameView, and registerView.
> >>>>>>>>
> >>>>>>>> However, the descriptions for what constitutes a conflict are not
> consistent:
> >>>>>>>>
> >>>>>>>> Enforcing cross-type uniqueness (table or view):
> >>>>>>>>
> >>>>>>>> renameTable, renameView, registerView say: "already exists as a
> table or view"
> >>>>>>>>
> >>>>>>>> Only enforcing within the same type (table or view only):
> >>>>>>>>
> >>>>>>>> createTable, registerTable, createView say: "table already
> exists" / "view already exists"
> >>>>>>>>
> >>>>>>>> This ambiguity leaves it unclear whether a catalog is allowed to
> have a table and a view with the same name in the same namespace.
> >>>>>>>>
> >>>>>>>> Proposed Change
> >>>>>>>>
> >>>>>>>> I believe the intent is that identifiers must be unique across
> all catalog object types within the same namespace (otherwise the rename
> operations become impossible to reason about).
> >>>>>>>>
> >>>>>>>> The proposed change makes this explicit in two ways:
> >>>>>>>>
> >>>>>>>> New CatalogObjectType schema: Enumerates the known catalog object
> types (table, view) and states the uniqueness invariant: "Identifiers MUST
> be unique across all catalog object types within the same namespace; a
> table and a view with the same name in the same namespace are not allowed."
> >>>>>>>> Consistent 409 descriptions: All six write operations will now
> reference CatalogObjectType and use uniform language: "The identifier is
> already used by an existing catalog object (see CatalogObjectType)"
> >>>>>>>>
> >>>>>>>> This change is purely spec-clarification; it introduces no new
> behavior for catalogs that already enforce cross-type uniqueness.
> >>>>>>>>
> >>>>>>>> The proposed clarification is available here:
> https://github.com/apache/iceberg/pull/15691
> >>>>>>>>
> >>>>>>>> Thanks,
> >>>>>>>> Steven
>

Re: [DISCUSS] REST Spec: Clarify identifier uniqueness across catalog object types

[Maximilian Michels <mx...@apache.org>]

+1 for improving the error messages and restricting identifier
uniqueness to tables and views only. We could have also gone with "the
identifier already exists", but this is more nuanced.

On Tue, Mar 24, 2026 at 10:17 AM Péter Váry <pe...@gmail.com> wrote:
>
> +1 on consistent "Conflict - The identifier already exists as a table or view"
>
> Steven Wu <st...@gmail.com> ezt írta (időpont: 2026. márc. 24., K, 6:30):
>>
>> Enforcing cross-type uniqueness (table or view):
>>
>> renameTable, renameView, registerView say: "already exists as a table or view"
>>
>> Only enforcing within the same type (table or view only):
>>
>> createTable, registerTable, createView say: "table already exists" / "view already exists"
>>
>>
>> I updated the PR to use the consistent wording "already exists as a table or view" for the 409 conflict.
>>
>>
>> On Mon, Mar 23, 2026 at 8:30 AM Péter Váry <pe...@gmail.com> wrote:
>>>
>>> We need a `role` paired with the identifier to get the requested object. The `role` in this case can be the same for tables, views and MVs
>>>
>>> Steven Wu <st...@gmail.com> ezt írta (időpont: 2026. márc. 21., Szo, 22:08):
>>>>
>>>> > Do we really want to prevent creating a `rank` function if we already have a table named `rank`?
>>>>
>>>> This is a good argument. I agree functions can be in a separate dimension.
>>>>
>>>> Earlier, I was thinking from the perspective of a universal batch load endpoint, where a client may send one catalog request for all referenced objects (tables, views, MVs, functions). We can still make it work if functions are separated out in the batch load request. Or we can limit the universal batch load endpoint to tables, views, and MVs only.
>>>>
>>>> Clients may not need to load index objects separately. They can be piggybacked during table loading.
>>>>
>>>> On Sat, Mar 21, 2026 at 12:38 AM Péter Váry <pe...@gmail.com> wrote:
>>>>>
>>>>> I think we definitely should discuss the global uniqueness in details.
>>>>>
>>>>> Do we really want to prevent creating a `rank` function if we already have a table named `rank`?
>>>>>
>>>>> I'm fully on board to avoid having the same name for a table and a view, as they are fully interchangeable, but functions and indexes could use the same name and the engines could decide which one to use based on the context.
>>>>>
>>>>> So I think we need to seriously consider if we want to propose restrictions like this.
>>>>>
>>>>> WDYT?
>>>>>
>>>>>
>>>>> On Fri, Mar 20, 2026, 15:19 Steven Wu <st...@gmail.com> wrote:
>>>>>>
>>>>>> Hi Peter,
>>>>>>
>>>>>> I can understand the hesitation, especially considering the new CatalogObjectType not used by the spec (except for the references in the description text).
>>>>>>
>>>>>> I added it in this PR for the following reasons:
>>>>>> * Huaxin has a PR for functions [1], which will introduce a new function object type in the catalog. I believe we want to enforce uniqueness across all types: tables, views, and functions.
>>>>>> * index proposal also discussed the index object type in the catalog. but this is a bit farther away.
>>>>>> * Events endpoint proposal also needs to introduce the CatalogObjectType concept [2, 3].
>>>>>>
>>>>>> I am ok with removing it from this PR. We can add it later, perhaps, in the events or function endpoint spec change.
>>>>>>
>>>>>> Thanks,
>>>>>> Steven
>>>>>>
>>>>>> [1] Function endpoint spec: https://github.com/apache/iceberg/pull/15180
>>>>>> [2] Events endpoint spec: https://github.com/apache/iceberg/pull/12584
>>>>>> [3] Events endpoint impl: https://github.com/apache/iceberg/pull/14142
>>>>>>
>>>>>>
>>>>>>
>>>>>> On Fri, Mar 20, 2026 at 3:00 AM Péter Váry <pe...@gmail.com> wrote:
>>>>>>>
>>>>>>> Hi Steven,
>>>>>>> I completely agree that we should align the uniqueness requirements between table and view creation.
>>>>>>> I’m a bit hesitant about introducing CatalogObjectType. It makes sense if we expect to add more object types and want to enforce uniqueness across them, but I’m not sure we need that level of generality yet. Do you have something specific in mind that would require it?
>>>>>>> Thanks,
>>>>>>> Peter
>>>>>>>
>>>>>>> Steven Wu <st...@gmail.com> ezt írta (időpont: 2026. márc. 19., Cs, 21:17):
>>>>>>>>
>>>>>>>> Hi all,
>>>>>>>>
>>>>>>>> I'd like to discuss a minor inconsistency in the REST Catalog specification regarding identifier uniqueness within a namespace.
>>>>>>>>
>>>>>>>> Background: Inconsistency in Conflict Descriptions
>>>>>>>>
>>>>>>>> The REST spec currently defines six write operations that return a 409 Conflict when an identifier already exists: createTable, registerTable, renameTable, createView, renameView, and registerView.
>>>>>>>>
>>>>>>>> However, the descriptions for what constitutes a conflict are not consistent:
>>>>>>>>
>>>>>>>> Enforcing cross-type uniqueness (table or view):
>>>>>>>>
>>>>>>>> renameTable, renameView, registerView say: "already exists as a table or view"
>>>>>>>>
>>>>>>>> Only enforcing within the same type (table or view only):
>>>>>>>>
>>>>>>>> createTable, registerTable, createView say: "table already exists" / "view already exists"
>>>>>>>>
>>>>>>>> This ambiguity leaves it unclear whether a catalog is allowed to have a table and a view with the same name in the same namespace.
>>>>>>>>
>>>>>>>> Proposed Change
>>>>>>>>
>>>>>>>> I believe the intent is that identifiers must be unique across all catalog object types within the same namespace (otherwise the rename operations become impossible to reason about).
>>>>>>>>
>>>>>>>> The proposed change makes this explicit in two ways:
>>>>>>>>
>>>>>>>> New CatalogObjectType schema: Enumerates the known catalog object types (table, view) and states the uniqueness invariant: "Identifiers MUST be unique across all catalog object types within the same namespace; a table and a view with the same name in the same namespace are not allowed."
>>>>>>>> Consistent 409 descriptions: All six write operations will now reference CatalogObjectType and use uniform language: "The identifier is already used by an existing catalog object (see CatalogObjectType)"
>>>>>>>>
>>>>>>>> This change is purely spec-clarification; it introduces no new behavior for catalogs that already enforce cross-type uniqueness.
>>>>>>>>
>>>>>>>> The proposed clarification is available here: https://github.com/apache/iceberg/pull/15691
>>>>>>>>
>>>>>>>> Thanks,
>>>>>>>> Steven

Re: [DISCUSS] REST Spec: Clarify identifier uniqueness across catalog object types

[Péter Váry <pe...@gmail.com>]

+1 on consistent "Conflict - The identifier already exists as a table or
view"

Steven Wu <st...@gmail.com> ezt írta (időpont: 2026. márc. 24., K,
6:30):

>
>    - *Enforcing cross-type uniqueness* (table or view):
>       - renameTable, renameView, registerView say: *"already exists as a
>       table or view"*
>    - *Only enforcing within the same type* (table or view only):
>       - createTable, registerTable, createView say: *"table already
>       exists"* / *"view already exists"*
>
>
> I updated the PR to use the consistent wording "already exists as a table
> or view" for the 409 conflict.
>
>
> On Mon, Mar 23, 2026 at 8:30 AM Péter Váry <pe...@gmail.com>
> wrote:
>
>> We need a `role` paired with the identifier to get the requested object.
>> The `role` in this case can be the same for tables, views and MVs
>>
>> Steven Wu <st...@gmail.com> ezt írta (időpont: 2026. márc. 21.,
>> Szo, 22:08):
>>
>>> > Do we really want to prevent creating a `rank` function if we already
>>> have a table named `rank`?
>>>
>>> This is a good argument. I agree functions can be in a separate
>>> dimension.
>>>
>>> Earlier, I was thinking from the perspective of a universal batch load
>>> endpoint, where a client may send one catalog request for all referenced
>>> objects (tables, views, MVs, functions). We can still make it work if
>>> functions are separated out in the batch load request. Or we can limit the
>>> universal batch load endpoint to tables, views, and MVs only.
>>>
>>> Clients may not need to load index objects separately. They can be
>>> piggybacked during table loading.
>>>
>>> On Sat, Mar 21, 2026 at 12:38 AM Péter Váry <pe...@gmail.com>
>>> wrote:
>>>
>>>> I think we definitely should discuss the global uniqueness in details.
>>>>
>>>> Do we really want to prevent creating a `rank` function if we already
>>>> have a table named `rank`?
>>>>
>>>> I'm fully on board to avoid having the same name for a table and a
>>>> view, as they are fully interchangeable, but functions and indexes could
>>>> use the same name and the engines could decide which one to use based on
>>>> the context.
>>>>
>>>> So I think we need to seriously consider if we want to propose
>>>> restrictions like this.
>>>>
>>>> WDYT?
>>>>
>>>>
>>>> On Fri, Mar 20, 2026, 15:19 Steven Wu <st...@gmail.com> wrote:
>>>>
>>>>> Hi Peter,
>>>>>
>>>>> I can understand the hesitation, especially considering the new
>>>>> *CatalogObjectType *not used by the spec (except for the references
>>>>> in the description text).
>>>>>
>>>>> I added it in this PR for the following reasons:
>>>>> * Huaxin has a PR for functions [1], which will introduce a new
>>>>> function object type in the catalog. I believe we want to enforce
>>>>> uniqueness across all types: tables, views, and functions.
>>>>> * index proposal also discussed the index object type in the catalog.
>>>>> but this is a bit farther away.
>>>>> * Events endpoint proposal also needs to introduce the
>>>>> *CatalogObjectType *concept [2, 3].
>>>>>
>>>>> I am ok with removing it from this PR. We can add it later, perhaps,
>>>>> in the events or function endpoint spec change.
>>>>>
>>>>> Thanks,
>>>>> Steven
>>>>>
>>>>> [1] Function endpoint spec:
>>>>> https://github.com/apache/iceberg/pull/15180
>>>>> [2] Events endpoint spec: https://github.com/apache/iceberg/pull/12584
>>>>> [3] Events endpoint impl: https://github.com/apache/iceberg/pull/14142
>>>>>
>>>>>
>>>>>
>>>>> On Fri, Mar 20, 2026 at 3:00 AM Péter Váry <
>>>>> peter.vary.apache@gmail.com> wrote:
>>>>>
>>>>>> Hi Steven,
>>>>>> I completely agree that we should align the uniqueness requirements
>>>>>> between table and view creation.
>>>>>> I’m a bit hesitant about introducing *CatalogObjectType*. It makes
>>>>>> sense if we expect to add more object types and want to enforce uniqueness
>>>>>> across them, but I’m not sure we need that level of generality yet. Do you
>>>>>> have something specific in mind that would require it?
>>>>>> Thanks,
>>>>>> Peter
>>>>>>
>>>>>> Steven Wu <st...@gmail.com> ezt írta (időpont: 2026. márc. 19.,
>>>>>> Cs, 21:17):
>>>>>>
>>>>>>> Hi all,
>>>>>>>
>>>>>>> I'd like to discuss a minor inconsistency in the REST Catalog
>>>>>>> specification regarding identifier uniqueness within a namespace.
>>>>>>>
>>>>>>> *Background: Inconsistency in Conflict Descriptions*
>>>>>>>
>>>>>>> The REST spec currently defines six write operations that return a 409
>>>>>>> Conflict when an identifier already exists: createTable,
>>>>>>> registerTable, renameTable, createView, renameView, and registerView
>>>>>>> .
>>>>>>>
>>>>>>> However, the descriptions for *what* constitutes a conflict are not
>>>>>>> consistent:
>>>>>>>
>>>>>>>    - *Enforcing cross-type uniqueness* (table or view):
>>>>>>>       - renameTable, renameView, registerView say: *"already exists
>>>>>>>       as a table or view"*
>>>>>>>    - *Only enforcing within the same type* (table or view only):
>>>>>>>       - createTable, registerTable, createView say: *"table already
>>>>>>>       exists"* / *"view already exists"*
>>>>>>>
>>>>>>> This ambiguity leaves it unclear whether a catalog is allowed to
>>>>>>> have a table and a view with the same name in the same namespace.
>>>>>>>
>>>>>>> *Proposed Change*
>>>>>>>
>>>>>>> I believe the intent is that identifiers *must* be unique across
>>>>>>> all catalog object types within the same namespace (otherwise the rename
>>>>>>> operations become impossible to reason about).
>>>>>>>
>>>>>>> The proposed change makes this explicit in two ways:
>>>>>>>
>>>>>>>    1. *New CatalogObjectType schema:* Enumerates the known catalog
>>>>>>>    object types (table, view) and states the uniqueness invariant: *"Identifiers
>>>>>>>    MUST be unique across all catalog object types within the same namespace; a
>>>>>>>    table and a view with the same name in the same namespace are not allowed."*
>>>>>>>    2. *Consistent 409 descriptions:* All six write operations will
>>>>>>>    now reference CatalogObjectType and use uniform language: *"The
>>>>>>>    identifier is already used by an existing catalog object (see
>>>>>>>    CatalogObjectType)"*
>>>>>>>
>>>>>>> This change is purely spec-clarification; it introduces no new
>>>>>>> behavior for catalogs that already enforce cross-type uniqueness.
>>>>>>>
>>>>>>> The proposed clarification is available here:
>>>>>>> https://github.com/apache/iceberg/pull/15691
>>>>>>> <https://www.google.com/url?source=gmail&sa=E&q=https://github.com/stevenzwu/iceberg/tree/rest-spec-clarify-id-conflict-requirement>
>>>>>>>
>>>>>>> Thanks,
>>>>>>> Steven
>>>>>>>
>>>>>>

Re: [DISCUSS] REST Spec: Clarify identifier uniqueness across catalog object types

[Steven Wu <st...@gmail.com>]

   - *Enforcing cross-type uniqueness* (table or view):
      - renameTable, renameView, registerView say: *"already exists as a
      table or view"*
   - *Only enforcing within the same type* (table or view only):
      - createTable, registerTable, createView say: *"table already exists"*
       / *"view already exists"*


I updated the PR to use the consistent wording "already exists as a table
or view" for the 409 conflict.


On Mon, Mar 23, 2026 at 8:30 AM Péter Váry <pe...@gmail.com>
wrote:

> We need a `role` paired with the identifier to get the requested object.
> The `role` in this case can be the same for tables, views and MVs
>
> Steven Wu <st...@gmail.com> ezt írta (időpont: 2026. márc. 21., Szo,
> 22:08):
>
>> > Do we really want to prevent creating a `rank` function if we already
>> have a table named `rank`?
>>
>> This is a good argument. I agree functions can be in a separate dimension.
>>
>> Earlier, I was thinking from the perspective of a universal batch load
>> endpoint, where a client may send one catalog request for all referenced
>> objects (tables, views, MVs, functions). We can still make it work if
>> functions are separated out in the batch load request. Or we can limit the
>> universal batch load endpoint to tables, views, and MVs only.
>>
>> Clients may not need to load index objects separately. They can be
>> piggybacked during table loading.
>>
>> On Sat, Mar 21, 2026 at 12:38 AM Péter Váry <pe...@gmail.com>
>> wrote:
>>
>>> I think we definitely should discuss the global uniqueness in details.
>>>
>>> Do we really want to prevent creating a `rank` function if we already
>>> have a table named `rank`?
>>>
>>> I'm fully on board to avoid having the same name for a table and a view,
>>> as they are fully interchangeable, but functions and indexes could use the
>>> same name and the engines could decide which one to use based on the
>>> context.
>>>
>>> So I think we need to seriously consider if we want to propose
>>> restrictions like this.
>>>
>>> WDYT?
>>>
>>>
>>> On Fri, Mar 20, 2026, 15:19 Steven Wu <st...@gmail.com> wrote:
>>>
>>>> Hi Peter,
>>>>
>>>> I can understand the hesitation, especially considering the new
>>>> *CatalogObjectType *not used by the spec (except for the references in
>>>> the description text).
>>>>
>>>> I added it in this PR for the following reasons:
>>>> * Huaxin has a PR for functions [1], which will introduce a new
>>>> function object type in the catalog. I believe we want to enforce
>>>> uniqueness across all types: tables, views, and functions.
>>>> * index proposal also discussed the index object type in the catalog.
>>>> but this is a bit farther away.
>>>> * Events endpoint proposal also needs to introduce the
>>>> *CatalogObjectType *concept [2, 3].
>>>>
>>>> I am ok with removing it from this PR. We can add it later, perhaps, in
>>>> the events or function endpoint spec change.
>>>>
>>>> Thanks,
>>>> Steven
>>>>
>>>> [1] Function endpoint spec:
>>>> https://github.com/apache/iceberg/pull/15180
>>>> [2] Events endpoint spec: https://github.com/apache/iceberg/pull/12584
>>>> [3] Events endpoint impl: https://github.com/apache/iceberg/pull/14142
>>>>
>>>>
>>>>
>>>> On Fri, Mar 20, 2026 at 3:00 AM Péter Váry <pe...@gmail.com>
>>>> wrote:
>>>>
>>>>> Hi Steven,
>>>>> I completely agree that we should align the uniqueness requirements
>>>>> between table and view creation.
>>>>> I’m a bit hesitant about introducing *CatalogObjectType*. It makes
>>>>> sense if we expect to add more object types and want to enforce uniqueness
>>>>> across them, but I’m not sure we need that level of generality yet. Do you
>>>>> have something specific in mind that would require it?
>>>>> Thanks,
>>>>> Peter
>>>>>
>>>>> Steven Wu <st...@gmail.com> ezt írta (időpont: 2026. márc. 19.,
>>>>> Cs, 21:17):
>>>>>
>>>>>> Hi all,
>>>>>>
>>>>>> I'd like to discuss a minor inconsistency in the REST Catalog
>>>>>> specification regarding identifier uniqueness within a namespace.
>>>>>>
>>>>>> *Background: Inconsistency in Conflict Descriptions*
>>>>>>
>>>>>> The REST spec currently defines six write operations that return a 409
>>>>>> Conflict when an identifier already exists: createTable,
>>>>>> registerTable, renameTable, createView, renameView, and registerView.
>>>>>>
>>>>>> However, the descriptions for *what* constitutes a conflict are not
>>>>>> consistent:
>>>>>>
>>>>>>    - *Enforcing cross-type uniqueness* (table or view):
>>>>>>       - renameTable, renameView, registerView say: *"already exists
>>>>>>       as a table or view"*
>>>>>>    - *Only enforcing within the same type* (table or view only):
>>>>>>       - createTable, registerTable, createView say: *"table already
>>>>>>       exists"* / *"view already exists"*
>>>>>>
>>>>>> This ambiguity leaves it unclear whether a catalog is allowed to have
>>>>>> a table and a view with the same name in the same namespace.
>>>>>>
>>>>>> *Proposed Change*
>>>>>>
>>>>>> I believe the intent is that identifiers *must* be unique across all
>>>>>> catalog object types within the same namespace (otherwise the rename
>>>>>> operations become impossible to reason about).
>>>>>>
>>>>>> The proposed change makes this explicit in two ways:
>>>>>>
>>>>>>    1. *New CatalogObjectType schema:* Enumerates the known catalog
>>>>>>    object types (table, view) and states the uniqueness invariant: *"Identifiers
>>>>>>    MUST be unique across all catalog object types within the same namespace; a
>>>>>>    table and a view with the same name in the same namespace are not allowed."*
>>>>>>    2. *Consistent 409 descriptions:* All six write operations will
>>>>>>    now reference CatalogObjectType and use uniform language: *"The
>>>>>>    identifier is already used by an existing catalog object (see
>>>>>>    CatalogObjectType)"*
>>>>>>
>>>>>> This change is purely spec-clarification; it introduces no new
>>>>>> behavior for catalogs that already enforce cross-type uniqueness.
>>>>>>
>>>>>> The proposed clarification is available here:
>>>>>> https://github.com/apache/iceberg/pull/15691
>>>>>> <https://www.google.com/url?source=gmail&sa=E&q=https://github.com/stevenzwu/iceberg/tree/rest-spec-clarify-id-conflict-requirement>
>>>>>>
>>>>>> Thanks,
>>>>>> Steven
>>>>>>
>>>>>

Re: [DISCUSS] REST Spec: Clarify identifier uniqueness across catalog object types

[Péter Váry <pe...@gmail.com>]

We need a `role` paired with the identifier to get the requested object.
The `role` in this case can be the same for tables, views and MVs

Steven Wu <st...@gmail.com> ezt írta (időpont: 2026. márc. 21., Szo,
22:08):

> > Do we really want to prevent creating a `rank` function if we already
> have a table named `rank`?
>
> This is a good argument. I agree functions can be in a separate dimension.
>
> Earlier, I was thinking from the perspective of a universal batch load
> endpoint, where a client may send one catalog request for all referenced
> objects (tables, views, MVs, functions). We can still make it work if
> functions are separated out in the batch load request. Or we can limit the
> universal batch load endpoint to tables, views, and MVs only.
>
> Clients may not need to load index objects separately. They can be
> piggybacked during table loading.
>
> On Sat, Mar 21, 2026 at 12:38 AM Péter Váry <pe...@gmail.com>
> wrote:
>
>> I think we definitely should discuss the global uniqueness in details.
>>
>> Do we really want to prevent creating a `rank` function if we already
>> have a table named `rank`?
>>
>> I'm fully on board to avoid having the same name for a table and a view,
>> as they are fully interchangeable, but functions and indexes could use the
>> same name and the engines could decide which one to use based on the
>> context.
>>
>> So I think we need to seriously consider if we want to propose
>> restrictions like this.
>>
>> WDYT?
>>
>>
>> On Fri, Mar 20, 2026, 15:19 Steven Wu <st...@gmail.com> wrote:
>>
>>> Hi Peter,
>>>
>>> I can understand the hesitation, especially considering the new
>>> *CatalogObjectType *not used by the spec (except for the references in
>>> the description text).
>>>
>>> I added it in this PR for the following reasons:
>>> * Huaxin has a PR for functions [1], which will introduce a new function
>>> object type in the catalog. I believe we want to enforce uniqueness across
>>> all types: tables, views, and functions.
>>> * index proposal also discussed the index object type in the catalog.
>>> but this is a bit farther away.
>>> * Events endpoint proposal also needs to introduce the
>>> *CatalogObjectType *concept [2, 3].
>>>
>>> I am ok with removing it from this PR. We can add it later, perhaps, in
>>> the events or function endpoint spec change.
>>>
>>> Thanks,
>>> Steven
>>>
>>> [1] Function endpoint spec: https://github.com/apache/iceberg/pull/15180
>>> [2] Events endpoint spec: https://github.com/apache/iceberg/pull/12584
>>> [3] Events endpoint impl: https://github.com/apache/iceberg/pull/14142
>>>
>>>
>>>
>>> On Fri, Mar 20, 2026 at 3:00 AM Péter Váry <pe...@gmail.com>
>>> wrote:
>>>
>>>> Hi Steven,
>>>> I completely agree that we should align the uniqueness requirements
>>>> between table and view creation.
>>>> I’m a bit hesitant about introducing *CatalogObjectType*. It makes
>>>> sense if we expect to add more object types and want to enforce uniqueness
>>>> across them, but I’m not sure we need that level of generality yet. Do you
>>>> have something specific in mind that would require it?
>>>> Thanks,
>>>> Peter
>>>>
>>>> Steven Wu <st...@gmail.com> ezt írta (időpont: 2026. márc. 19.,
>>>> Cs, 21:17):
>>>>
>>>>> Hi all,
>>>>>
>>>>> I'd like to discuss a minor inconsistency in the REST Catalog
>>>>> specification regarding identifier uniqueness within a namespace.
>>>>>
>>>>> *Background: Inconsistency in Conflict Descriptions*
>>>>>
>>>>> The REST spec currently defines six write operations that return a 409
>>>>> Conflict when an identifier already exists: createTable, registerTable
>>>>> , renameTable, createView, renameView, and registerView.
>>>>>
>>>>> However, the descriptions for *what* constitutes a conflict are not
>>>>> consistent:
>>>>>
>>>>>    - *Enforcing cross-type uniqueness* (table or view):
>>>>>       - renameTable, renameView, registerView say: *"already exists
>>>>>       as a table or view"*
>>>>>    - *Only enforcing within the same type* (table or view only):
>>>>>       - createTable, registerTable, createView say: *"table already
>>>>>       exists"* / *"view already exists"*
>>>>>
>>>>> This ambiguity leaves it unclear whether a catalog is allowed to have
>>>>> a table and a view with the same name in the same namespace.
>>>>>
>>>>> *Proposed Change*
>>>>>
>>>>> I believe the intent is that identifiers *must* be unique across all
>>>>> catalog object types within the same namespace (otherwise the rename
>>>>> operations become impossible to reason about).
>>>>>
>>>>> The proposed change makes this explicit in two ways:
>>>>>
>>>>>    1. *New CatalogObjectType schema:* Enumerates the known catalog
>>>>>    object types (table, view) and states the uniqueness invariant: *"Identifiers
>>>>>    MUST be unique across all catalog object types within the same namespace; a
>>>>>    table and a view with the same name in the same namespace are not allowed."*
>>>>>    2. *Consistent 409 descriptions:* All six write operations will
>>>>>    now reference CatalogObjectType and use uniform language: *"The
>>>>>    identifier is already used by an existing catalog object (see
>>>>>    CatalogObjectType)"*
>>>>>
>>>>> This change is purely spec-clarification; it introduces no new
>>>>> behavior for catalogs that already enforce cross-type uniqueness.
>>>>>
>>>>> The proposed clarification is available here:
>>>>> https://github.com/apache/iceberg/pull/15691
>>>>> <https://www.google.com/url?source=gmail&sa=E&q=https://github.com/stevenzwu/iceberg/tree/rest-spec-clarify-id-conflict-requirement>
>>>>>
>>>>> Thanks,
>>>>> Steven
>>>>>
>>>>

Re: [DISCUSS] REST Spec: Clarify identifier uniqueness across catalog object types

[Steven Wu <st...@gmail.com>]

> Do we really want to prevent creating a `rank` function if we already
have a table named `rank`?

This is a good argument. I agree functions can be in a separate dimension.

Earlier, I was thinking from the perspective of a universal batch load
endpoint, where a client may send one catalog request for all referenced
objects (tables, views, MVs, functions). We can still make it work if
functions are separated out in the batch load request. Or we can limit the
universal batch load endpoint to tables, views, and MVs only.

Clients may not need to load index objects separately. They can be
piggybacked during table loading.

On Sat, Mar 21, 2026 at 12:38 AM Péter Váry <pe...@gmail.com>
wrote:

> I think we definitely should discuss the global uniqueness in details.
>
> Do we really want to prevent creating a `rank` function if we already have
> a table named `rank`?
>
> I'm fully on board to avoid having the same name for a table and a view,
> as they are fully interchangeable, but functions and indexes could use the
> same name and the engines could decide which one to use based on the
> context.
>
> So I think we need to seriously consider if we want to propose
> restrictions like this.
>
> WDYT?
>
>
> On Fri, Mar 20, 2026, 15:19 Steven Wu <st...@gmail.com> wrote:
>
>> Hi Peter,
>>
>> I can understand the hesitation, especially considering the new
>> *CatalogObjectType *not used by the spec (except for the references in
>> the description text).
>>
>> I added it in this PR for the following reasons:
>> * Huaxin has a PR for functions [1], which will introduce a new function
>> object type in the catalog. I believe we want to enforce uniqueness across
>> all types: tables, views, and functions.
>> * index proposal also discussed the index object type in the catalog. but
>> this is a bit farther away.
>> * Events endpoint proposal also needs to introduce the
>> *CatalogObjectType *concept [2, 3].
>>
>> I am ok with removing it from this PR. We can add it later, perhaps, in
>> the events or function endpoint spec change.
>>
>> Thanks,
>> Steven
>>
>> [1] Function endpoint spec: https://github.com/apache/iceberg/pull/15180
>> [2] Events endpoint spec: https://github.com/apache/iceberg/pull/12584
>> [3] Events endpoint impl: https://github.com/apache/iceberg/pull/14142
>>
>>
>>
>> On Fri, Mar 20, 2026 at 3:00 AM Péter Váry <pe...@gmail.com>
>> wrote:
>>
>>> Hi Steven,
>>> I completely agree that we should align the uniqueness requirements
>>> between table and view creation.
>>> I’m a bit hesitant about introducing *CatalogObjectType*. It makes
>>> sense if we expect to add more object types and want to enforce uniqueness
>>> across them, but I’m not sure we need that level of generality yet. Do you
>>> have something specific in mind that would require it?
>>> Thanks,
>>> Peter
>>>
>>> Steven Wu <st...@gmail.com> ezt írta (időpont: 2026. márc. 19.,
>>> Cs, 21:17):
>>>
>>>> Hi all,
>>>>
>>>> I'd like to discuss a minor inconsistency in the REST Catalog
>>>> specification regarding identifier uniqueness within a namespace.
>>>>
>>>> *Background: Inconsistency in Conflict Descriptions*
>>>>
>>>> The REST spec currently defines six write operations that return a 409
>>>> Conflict when an identifier already exists: createTable, registerTable
>>>> , renameTable, createView, renameView, and registerView.
>>>>
>>>> However, the descriptions for *what* constitutes a conflict are not
>>>> consistent:
>>>>
>>>>    - *Enforcing cross-type uniqueness* (table or view):
>>>>       - renameTable, renameView, registerView say: *"already exists as
>>>>       a table or view"*
>>>>    - *Only enforcing within the same type* (table or view only):
>>>>       - createTable, registerTable, createView say: *"table already
>>>>       exists"* / *"view already exists"*
>>>>
>>>> This ambiguity leaves it unclear whether a catalog is allowed to have a
>>>> table and a view with the same name in the same namespace.
>>>>
>>>> *Proposed Change*
>>>>
>>>> I believe the intent is that identifiers *must* be unique across all
>>>> catalog object types within the same namespace (otherwise the rename
>>>> operations become impossible to reason about).
>>>>
>>>> The proposed change makes this explicit in two ways:
>>>>
>>>>    1. *New CatalogObjectType schema:* Enumerates the known catalog
>>>>    object types (table, view) and states the uniqueness invariant: *"Identifiers
>>>>    MUST be unique across all catalog object types within the same namespace; a
>>>>    table and a view with the same name in the same namespace are not allowed."*
>>>>    2. *Consistent 409 descriptions:* All six write operations will now
>>>>    reference CatalogObjectType and use uniform language: *"The
>>>>    identifier is already used by an existing catalog object (see
>>>>    CatalogObjectType)"*
>>>>
>>>> This change is purely spec-clarification; it introduces no new behavior
>>>> for catalogs that already enforce cross-type uniqueness.
>>>>
>>>> The proposed clarification is available here:
>>>> https://github.com/apache/iceberg/pull/15691
>>>> <https://www.google.com/url?source=gmail&sa=E&q=https://github.com/stevenzwu/iceberg/tree/rest-spec-clarify-id-conflict-requirement>
>>>>
>>>> Thanks,
>>>> Steven
>>>>
>>>

Re: [DISCUSS] REST Spec: Clarify identifier uniqueness across catalog object types

[Péter Váry <pe...@gmail.com>]

I think we definitely should discuss the global uniqueness in details.

Do we really want to prevent creating a `rank` function if we already have
a table named `rank`?

I'm fully on board to avoid having the same name for a table and a view, as
they are fully interchangeable, but functions and indexes could use the
same name and the engines could decide which one to use based on the
context.

So I think we need to seriously consider if we want to propose restrictions
like this.

WDYT?


On Fri, Mar 20, 2026, 15:19 Steven Wu <st...@gmail.com> wrote:

> Hi Peter,
>
> I can understand the hesitation, especially considering the new
> *CatalogObjectType *not used by the spec (except for the references in
> the description text).
>
> I added it in this PR for the following reasons:
> * Huaxin has a PR for functions [1], which will introduce a new function
> object type in the catalog. I believe we want to enforce uniqueness across
> all types: tables, views, and functions.
> * index proposal also discussed the index object type in the catalog. but
> this is a bit farther away.
> * Events endpoint proposal also needs to introduce the
> *CatalogObjectType *concept [2, 3].
>
> I am ok with removing it from this PR. We can add it later, perhaps, in
> the events or function endpoint spec change.
>
> Thanks,
> Steven
>
> [1] Function endpoint spec: https://github.com/apache/iceberg/pull/15180
> [2] Events endpoint spec: https://github.com/apache/iceberg/pull/12584
> [3] Events endpoint impl: https://github.com/apache/iceberg/pull/14142
>
>
>
> On Fri, Mar 20, 2026 at 3:00 AM Péter Váry <pe...@gmail.com>
> wrote:
>
>> Hi Steven,
>> I completely agree that we should align the uniqueness requirements
>> between table and view creation.
>> I’m a bit hesitant about introducing *CatalogObjectType*. It makes sense
>> if we expect to add more object types and want to enforce uniqueness across
>> them, but I’m not sure we need that level of generality yet. Do you have
>> something specific in mind that would require it?
>> Thanks,
>> Peter
>>
>> Steven Wu <st...@gmail.com> ezt írta (időpont: 2026. márc. 19., Cs,
>> 21:17):
>>
>>> Hi all,
>>>
>>> I'd like to discuss a minor inconsistency in the REST Catalog
>>> specification regarding identifier uniqueness within a namespace.
>>>
>>> *Background: Inconsistency in Conflict Descriptions*
>>>
>>> The REST spec currently defines six write operations that return a 409
>>> Conflict when an identifier already exists: createTable, registerTable,
>>> renameTable, createView, renameView, and registerView.
>>>
>>> However, the descriptions for *what* constitutes a conflict are not
>>> consistent:
>>>
>>>    - *Enforcing cross-type uniqueness* (table or view):
>>>       - renameTable, renameView, registerView say: *"already exists as
>>>       a table or view"*
>>>    - *Only enforcing within the same type* (table or view only):
>>>       - createTable, registerTable, createView say: *"table already
>>>       exists"* / *"view already exists"*
>>>
>>> This ambiguity leaves it unclear whether a catalog is allowed to have a
>>> table and a view with the same name in the same namespace.
>>>
>>> *Proposed Change*
>>>
>>> I believe the intent is that identifiers *must* be unique across all
>>> catalog object types within the same namespace (otherwise the rename
>>> operations become impossible to reason about).
>>>
>>> The proposed change makes this explicit in two ways:
>>>
>>>    1. *New CatalogObjectType schema:* Enumerates the known catalog
>>>    object types (table, view) and states the uniqueness invariant: *"Identifiers
>>>    MUST be unique across all catalog object types within the same namespace; a
>>>    table and a view with the same name in the same namespace are not allowed."*
>>>    2. *Consistent 409 descriptions:* All six write operations will now
>>>    reference CatalogObjectType and use uniform language: *"The
>>>    identifier is already used by an existing catalog object (see
>>>    CatalogObjectType)"*
>>>
>>> This change is purely spec-clarification; it introduces no new behavior
>>> for catalogs that already enforce cross-type uniqueness.
>>>
>>> The proposed clarification is available here:
>>> https://github.com/apache/iceberg/pull/15691
>>> <https://www.google.com/url?source=gmail&sa=E&q=https://github.com/stevenzwu/iceberg/tree/rest-spec-clarify-id-conflict-requirement>
>>>
>>> Thanks,
>>> Steven
>>>
>>

Re: [DISCUSS] REST Spec: Clarify identifier uniqueness across catalog object types

[Steven Wu <st...@gmail.com>]

Hi Peter,

I can understand the hesitation, especially considering the new
*CatalogObjectType *not used by the spec (except for the references in the
description text).

I added it in this PR for the following reasons:
* Huaxin has a PR for functions [1], which will introduce a new function
object type in the catalog. I believe we want to enforce uniqueness across
all types: tables, views, and functions.
* index proposal also discussed the index object type in the catalog. but
this is a bit farther away.
* Events endpoint proposal also needs to introduce the
*CatalogObjectType *concept
[2, 3].

I am ok with removing it from this PR. We can add it later, perhaps, in the
events or function endpoint spec change.

Thanks,
Steven

[1] Function endpoint spec: https://github.com/apache/iceberg/pull/15180
[2] Events endpoint spec: https://github.com/apache/iceberg/pull/12584
[3] Events endpoint impl: https://github.com/apache/iceberg/pull/14142



On Fri, Mar 20, 2026 at 3:00 AM Péter Váry <pe...@gmail.com>
wrote:

> Hi Steven,
> I completely agree that we should align the uniqueness requirements
> between table and view creation.
> I’m a bit hesitant about introducing *CatalogObjectType*. It makes sense
> if we expect to add more object types and want to enforce uniqueness across
> them, but I’m not sure we need that level of generality yet. Do you have
> something specific in mind that would require it?
> Thanks,
> Peter
>
> Steven Wu <st...@gmail.com> ezt írta (időpont: 2026. márc. 19., Cs,
> 21:17):
>
>> Hi all,
>>
>> I'd like to discuss a minor inconsistency in the REST Catalog
>> specification regarding identifier uniqueness within a namespace.
>>
>> *Background: Inconsistency in Conflict Descriptions*
>>
>> The REST spec currently defines six write operations that return a 409
>> Conflict when an identifier already exists: createTable, registerTable,
>> renameTable, createView, renameView, and registerView.
>>
>> However, the descriptions for *what* constitutes a conflict are not
>> consistent:
>>
>>    - *Enforcing cross-type uniqueness* (table or view):
>>       - renameTable, renameView, registerView say: *"already exists as a
>>       table or view"*
>>    - *Only enforcing within the same type* (table or view only):
>>       - createTable, registerTable, createView say: *"table already
>>       exists"* / *"view already exists"*
>>
>> This ambiguity leaves it unclear whether a catalog is allowed to have a
>> table and a view with the same name in the same namespace.
>>
>> *Proposed Change*
>>
>> I believe the intent is that identifiers *must* be unique across all
>> catalog object types within the same namespace (otherwise the rename
>> operations become impossible to reason about).
>>
>> The proposed change makes this explicit in two ways:
>>
>>    1. *New CatalogObjectType schema:* Enumerates the known catalog
>>    object types (table, view) and states the uniqueness invariant: *"Identifiers
>>    MUST be unique across all catalog object types within the same namespace; a
>>    table and a view with the same name in the same namespace are not allowed."*
>>    2. *Consistent 409 descriptions:* All six write operations will now
>>    reference CatalogObjectType and use uniform language: *"The
>>    identifier is already used by an existing catalog object (see
>>    CatalogObjectType)"*
>>
>> This change is purely spec-clarification; it introduces no new behavior
>> for catalogs that already enforce cross-type uniqueness.
>>
>> The proposed clarification is available here:
>> https://github.com/apache/iceberg/pull/15691
>> <https://www.google.com/url?source=gmail&sa=E&q=https://github.com/stevenzwu/iceberg/tree/rest-spec-clarify-id-conflict-requirement>
>>
>> Thanks,
>> Steven
>>
>

Re: [DISCUSS] REST Spec: Clarify identifier uniqueness across catalog object types

[Péter Váry <pe...@gmail.com>]

Hi Steven,
I completely agree that we should align the uniqueness requirements between
table and view creation.
I’m a bit hesitant about introducing *CatalogObjectType*. It makes sense if
we expect to add more object types and want to enforce uniqueness across
them, but I’m not sure we need that level of generality yet. Do you have
something specific in mind that would require it?
Thanks,
Peter

Steven Wu <st...@gmail.com> ezt írta (időpont: 2026. márc. 19., Cs,
21:17):

> Hi all,
>
> I'd like to discuss a minor inconsistency in the REST Catalog
> specification regarding identifier uniqueness within a namespace.
>
> *Background: Inconsistency in Conflict Descriptions*
>
> The REST spec currently defines six write operations that return a 409
> Conflict when an identifier already exists: createTable, registerTable,
> renameTable, createView, renameView, and registerView.
>
> However, the descriptions for *what* constitutes a conflict are not
> consistent:
>
>    - *Enforcing cross-type uniqueness* (table or view):
>       - renameTable, renameView, registerView say: *"already exists as a
>       table or view"*
>    - *Only enforcing within the same type* (table or view only):
>       - createTable, registerTable, createView say: *"table already
>       exists"* / *"view already exists"*
>
> This ambiguity leaves it unclear whether a catalog is allowed to have a
> table and a view with the same name in the same namespace.
>
> *Proposed Change*
>
> I believe the intent is that identifiers *must* be unique across all
> catalog object types within the same namespace (otherwise the rename
> operations become impossible to reason about).
>
> The proposed change makes this explicit in two ways:
>
>    1. *New CatalogObjectType schema:* Enumerates the known catalog object
>    types (table, view) and states the uniqueness invariant: *"Identifiers
>    MUST be unique across all catalog object types within the same namespace; a
>    table and a view with the same name in the same namespace are not allowed."*
>    2. *Consistent 409 descriptions:* All six write operations will now
>    reference CatalogObjectType and use uniform language: *"The identifier
>    is already used by an existing catalog object (see CatalogObjectType)"*
>
> This change is purely spec-clarification; it introduces no new behavior
> for catalogs that already enforce cross-type uniqueness.
>
> The proposed clarification is available here:
> https://github.com/apache/iceberg/pull/15691
> <https://www.google.com/url?source=gmail&sa=E&q=https://github.com/stevenzwu/iceberg/tree/rest-spec-clarify-id-conflict-requirement>
>
> Thanks,
> Steven
>