Add spec support for credential refresh on staged tables #15280
+73
−5
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Extends the REST Catalog OpenAPI spec to support credential refresh for staged tables by introducing a staging session identifier, following the same pattern as
planIdfor scan planning credential refresh. This addresses an earlier issue raised in community: #13554createTable(POST): Whenstage-createis true, theLoadTableResultresponse may now include an optionalstaging-sessionfield — an opaque session identifier for subsequent credential refresh.loadTable(GET): Accepts an optionalstagingSessionquery parameter to load a staged table and refresh credentials when used withX-Iceberg-Access-Delegation: vended-credentials.loadCredentials(GET): Accepts an optionalstagingSessionquery parameter to refresh credentials for a staged table. Mutually exclusive withplanId(returns 400 if both are provided).staging-sessionquery parameter defined incomponents/parameters.staging-sessionfield added to theLoadTableResultschema.Behavior
When
stagingSessionis provided:When
stagingSessionis omitted, standard committed table lookup by name is performed.Backward Compatibility
These changes are fully backward compatible:
stagingSessionparameter, maintaining current behavior.stagingSessionand will function as they do today.Design
This follows the same pattern as the existing scan planning credential refresh (
planIdquery parameter), where an ID returned from an initial request facilitates stateful credential refreshes for long-running asynchronous operations.Detailed design: https://docs.google.com/document/d/1R1K6X7qYqvIFkPG3m1neV5Mvy8rwWJvhSFr8DgJgQ-E/edit?tab=t.0