Skip to content

REST: Add ETag and conditional GET support for loadView #15946

@laserninja

Description

@laserninja

Proposed Change

The loadTable endpoint (GET /v1/{prefix}/namespaces/{namespace}/tables/{table}) supports conditional requests via the If-None-Match request header and returns an ETag response header (spec lines 965–977). When the table metadata hasn't changed, the server returns 304 Not Modified, saving serialization and transfer costs. The Java reference client (RESTSessionCatalog) implements this with a Caffeine-backed RESTTableCache that stores (sessionId, TableIdentifier) → (table, eTag) mappings.

However, the loadView endpoint (GET /v1/{prefix}/namespaces/{namespace}/views/{view}) has no equivalent support:

  1. Spec gap: The loadView operation (rest-catalog-open-api.yaml, line ~1580) defines no If-None-Match header parameter and no 304 response. The LoadViewResponse response object (line ~4953) has no etag header, whereas LoadTableResponse (line ~4943) and CommitTableResponse (line ~4974) both include one.

  2. Client gap: RESTSessionCatalog.loadView() (line ~1427 in RESTSessionCatalog.java) always issues a full GET with no headers and no caching. There is no RESTViewCache equivalent to the existing RESTTableCache.

Views are increasingly used for cross-engine SQL compatibility layers and can have substantial metadata (multiple version entries, representations, schema history). Workloads that repeatedly resolve or validate views pay the full round-trip cost every time.

Proposed spec changes:

  • Add an optional If-None-Match header parameter to the loadView GET operation, matching the existing pattern on loadTable.
  • Add a 304 Not Modified response to the loadView GET operation.
  • Add an etag response header to LoadViewResponse, matching LoadTableResponse and CommitTableResponse.
  • Optionally add an etag response header to the replaceView (POST) response, matching commitTable, so the cache can be primed on writes.

Backward compatibility:

  • If-None-Match is an optional header; servers that don't support it simply ignore it and return 200 as today.
  • Clients that don't send the header see no behavioral change.

Willingness to contribute

  • I can contribute this improvement/feature independently
  • I would be willing to contribute this improvement/feature with guidance from the Iceberg community
  • I cannot contribute this improvement/feature at this time

Proposal document

No response

Specifications

  • Table
  • View
  • REST
  • Puffin
  • Encryption
  • Other

Metadata

Metadata

Assignees

No one assigned

    Labels

    proposalIceberg Improvement Proposal (spec/major changes/etc)

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions