apache / apache/iceberg

[REST API] Add `recursive=true` parameter for `/v1/{prefix}/namespaces` endpoint

Open
#13,453 3 comments 5 reactions 0 assignees View on GitHub
proposal
Dominant language
Java
Stars
9.2k
Forks
3.5k
Avg merge
2d 11h
Merged PRs (30d)
132

Description

### Proposed Change

The `/v1/{prefix}/namespaces` endpoint is currently set up in such a way that it only lists the top-level namespaces, or if `parent` is set, it will list the namespaces directly under that namespace.

If we want to be sure that we have retrieved all namespaces, we need to issue a request for *every* namespace that is returned to be sure that they have no additional nested namespaces.

The idea behind the `recursive=true` parameter is that the server does this traversal in a single request, reducing round trip times.
This shouldn't be an issue, because the `Namespace` object that is returned already contains the full list of `items` that make up the full path of the namespace.

An alternative (but worse) solution, to make sure we don't need to make `parent=` requests for *every* namespace just to verify that there are no additional namespaces, is to indicate in the `ListNamespacesResponse` or `Namespace` object that a namespace is nested.
That way the client does not need to make requests that end up in an empty result.

### Proposal document

_No response_

### Specifications

- [ ] Table
- [ ] View
- [x] REST
- [ ] Puffin
- [ ] Encryption
- [ ] Other

Contributor guide

Open the contributing guide

Research direction

Start by locating the REST implementation for /v1/{prefix}/namespaces and review how parent filtering currently works. Then inspect the Namespace and ListNamespacesResponse shapes; done means recursive=true returns namespaces at all nesting levels in one request while existing behavior remains available.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
api
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.