Hi Dennis,
I like the proposal.
I think separating data plane discovery (/api/catalog) from admin
listing (/api/management) makes sense. Today an engine or tool has to
be given the catalog name out of band, which is "weird" given that
/config is already multi catalog :)
Keeping this distinct from the pruned management listCatalogs seems
right, since they serve different personas and return different
models.
I have a few questions and comments:
1. I prefer listAccessibleCatalogs. "Visible" could suggest a metadata
hiding feature, and "Available" doesn't say anything about the caller
access. "Accessible" matches the semantics of pruning by the caller
CatalogRole.
2. You describe pruning by the same access check as getConfig. I would
like the spec to say explicitly that a catalog is listed if and only
if getConfig would succeed for that caller. That keeps the two from
drifting apart and makes it clear that listing doesn't leak the
existence of catalogs that caller can't use.
3. Should the response support pageToken/pageSize from the start, like
the other list endpoints? It's cheaper to include now than to add
later, especially for platforms with a bunch of catalogs.
4. Returning only name is a good starting point. I would return object
(for instance {"catalogs": [{"name": "..."}]}) rather than a bare
string list, so we can add a getConfig style properties later without
a breaking change.
5. For the Shares API work, should catalogs that are accessible only
through a share, or external/federated catalogs, show up in this list?
It would be good to state the intended behavior, even if the answer is
"not now" :)
I will take a look on the PR.
Thanks!
Regards
JB
On Wed, Oct 28, 2026 at 6:20 AM Dennis Huo <[email protected]> wrote:
>
> Hi All,
>
> I'd like to propose a small extension under the polaris-catalog-service
> APIs: a way for a *data-plane* client to list the catalogs it can access.
>
> This relates to https://github.com/apache/polaris/issues/4573 as well as an
> emerging missing piece for the in-progress Polaris Shares API work.
>
> The basic problem is that today you already need to have the catalog name
> to configure an Iceberg REST Client. Even though IRC's /config endpoint is
> multi-catalog by nature, there's no analogous /catalogs endpoint yet in IRC.
>
> Polaris' current listCatalogs operation is semantically a *management*
> API's list, requiring a root-level CATALOG_LIST privilege and returning the
> full Catalog API model json in the responses, including the
> StorageConfiguration, for example.
>
> The proposal is to add GET /api/catalog/polaris/v1/catalogs, intended for a
> data-plane reader that doesn't necessarily have any management-level
> permissions, but has been granted a CatalogRole to "use" some catalogs. As
> a starting point, we'd only return the *name* of the catalog that needs to
> be passed to the "warehouse" field under the /config endpoint.
>
> This work *complements* the pruned management listCatalogs work related to
> https://github.com/apache/polaris/pull/4831 rather than replacing it. The
> key here is that despite being superficially similar to the admin-level
> listCatalogs, the two serve different personas:
>
> - Data-plane discovery (this proposal):
> - Batch form of: getConfig
> - Entries hold: name only (but may add properties normally returned by
> getConfig in the future)
> - Pruned by: the caller's getConfig access-check / assignment of a
> CatalogRole
> - For: engines, tools, user-facing UIs and platforms that mount remote
> catalogs
> - Pruned management listCatalogs:
> - Batch form of getCatalog
> - Entries hold: full Catalog API model
> - Pruned by: CATALOG_READ_PROPERTIES
> - For: administrative tools/consoles
>
> This also keeps a cleaner split of data-plane personas accessing the
> /api/catalog/ URL path, and only admin personas accessing the
> /api/management/ URL path.
>
> I've opened a draft PR for this spec extension here:
> https://github.com/apache/polaris/pull/5891
>
> The specific operation-name of the new operation is up for discussion - I'm
> proposing "listAccessibleCatalogs" as my preference. Others could be
> listVisibleCatalogs, listAvailableCatalogs, listConnectableCatalogs, etc.
>
> Would love to hear everyone's thoughts.
>
> Thanks!
> Dennis
