Skip to content

Add location utilities for v4 relative paths #1123

Open

Description

@xndai

Format v4 allows relative paths in metadata location fields, resolved against the table location (Paths in Metadata, apache/iceberg#15630). iceberg-cpp has LocationUtil::ParseScheme but nothing to tell absolute paths from relative ones, resolve relative paths, or relativize paths when writing. The v4 metadata, manifest and catalog work needs these first.

Proposal: add three helpers to LocationUtil, following Java's LocationUtil (apache/iceberg#16174, apache/iceberg#17807):

  • HasScheme(location): strict RFC 3986 scheme detection, which is the spec's test for an absolute path.
  • ResolveLocation(table_location, path): absolute paths are returned unchanged; relative paths are joined to the table location with /. There is no ./.. normalization and no URI parsing, so encoded characters are kept as they are.
  • RelativizeLocation(table_location, path): returns the part after <table location>/ if the path is under the table location, otherwise the path unchanged.

One difference from Java: if the table location ends in /, no second separator is added. The spec already recommends that a table location not end in /, and S3 treats // as part of the object key.

Out of scope: using the helpers in metadata, manifests or catalogs, and adding a scheme to scheme-less paths in pre-v4 tables. Both are follow-ups. Tests cover every example in the spec's path resolution table, plus edge cases: trailing slashes, sibling prefixes such as /t vs /t2, different schemes, escaped characters, and relativize-then-resolve round trips. Part of #1107.

Activity

  1. added a commit that references this issue on Nov 14, 2026
    4d2ac7a
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions