dhruvarya-db opened a new pull request, #18782: URL: https://github.com/apache/iceberg/pull/18782
## Why Add a new v2 load endpoint so that clients can load format version 4 tables. This change is outlined in the REST spec PR for format version 4, #17642. Only the v2 endpoint can return a version 4 table, so clients that know only versions 1 to 3 never get one. ## What changes The Java REST client now uses the v2 endpoint to load and refresh a table when the server lists v2 in its configuration response. If the server does not list v2, the client uses v1 as before. Commits always use v1. Servers that do not know about v2 see no change, and the default list of endpoints in the client does not change. If the server lists v2, the client does not need the v1 load endpoint. A subclass of `RESTSessionCatalog` can set a custom table path. For a custom path, refresh uses v1, because the client makes the v2 path from the standard v1 path. `CatalogHandlers.loadTable` is the v1 load handler that servers can use. It now rejects a version 4 table with the new `UnsupportedFormatVersionException`, and the error message tells the user to use v2. This exception is a subclass of `BadRequestException`, so the server sends HTTP 400. The new `CatalogHandlers.loadTableV2` handler returns tables at all format versions. A server that uses `CatalogHandlers` gets the v1 rule with no more changes. If such a server uses `loadTable` for version 4 tables now, it must use `loadTableV2` for the v2 endpoint. The Java client changes this error back to `UnsupportedFormatVersionException`, so code can find it without a check of the message. An old client that does not know the type gets `BadRequestException` with the same message. The reference test server uses these two handlers and lists v2. A v1 load of a version 4 table gets HTTP 400. Most test changes are mechanical: tests that check the load path now expect v2 instead of v1. Tests for HEAD requests, commits, and the legacy configuration do not change. ## Testing **New coverage** - `TestRESTCatalogV2LoadTable` is a new suite. It checks that the client loads and refreshes tables with format versions 1 to 4 through v2, and that commits use v1. - The same suite checks that a client that uses only v1 gets `UnsupportedFormatVersionException` for a version 4 table. - It also checks a server that lists only v2, a server that lists only v1, and the refresh path for a custom table path. - `TestCatalogHandlersLoadTable` is a new suite. It checks that `loadTable` returns tables with format versions 1 to 3 and rejects version 4, and that `loadTableV2` returns all versions. - `TestErrorHandlers` has new tests. They check that the client gets `UnsupportedFormatVersionException` for this error type, and `BadRequestException` for other HTTP 400 errors. - `TestResourcePaths` and `TestEndpoint` check the new path and the new endpoint. - The v2 tests fail if the client uses v1 instead of v2. The rejection tests fail if the server does not do the check. **Coverage from the current suites** The reference test server now lists v2, so the current REST suites use v2 for each load. These suites are `TestRESTCatalog`, `TestFreshnessAwareLoading`, `TestReferencedByQueryParam`, and the REST compatibility kit in `open-api`. All of them pass. --- **AI Disclosure** - Model: Claude Opus 5.5 - Platform/Tool: Claude Code - Human Oversight: [unknown - human to fill in] - Prompt Summary: Load and refresh REST tables through the v2 load endpoint when the server advertises it, falling back to v1, and make the REST test server serve format version 4 tables only through v2. This pull request and its description were written by Isaac. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
