FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

fix(table): resolve index files by external path and bucket layout by JunRuiLee · Pull Request #752 · apache/paimon-rust · GitHub

fix(table): resolve index files by external path and bucket layout - #752

Open
JunRuiLee wants to merge 1 commit into
apache:mainfrom
JunRuiLee:feat/pk-scalar-pr1-index-paths
Open

fix(table): resolve index files by external path and bucket layout#752
JunRuiLee wants to merge 1 commit into
apache:mainfrom
JunRuiLee:feat/pk-scalar-pr1-index-paths

Conversation

JunRuiLee commented Aug 26, 2026
edited
Loading

Copy link
Copy Markdown
Contributor

What

Index files are always read from <table>/index/<file>, which ignores two things Java records and
honors:

  • _EXTERNAL_PATH — IndexFileMeta.SCHEMA field 5. Not decoded here at all, so it is also dropped
    when this crate rewrites an index manifest.
  • index-file-in-data-file-dir — when set, Java's indexFileFactory(partition, bucket) resolves an
    index file against the bucket's data-file directory instead of the table index/ directory.

Either one makes a table's index files unreadable. Observed as a primary-key vector search:
failed to open ANN index file '.../<table>/index/index-<uuid>-0' for range reads, while the file is
in the bucket directory.

How

Decode _EXTERNAL_PATH and add it to the write schema, add the index-file-in-data-file-dir option,
and route every index-file consumer through one resolver (table/index_file_path.rs) with two modes,
each mirroring the factory Java uses for that consumer:

mode consumers Java
global — always <table>/index data-evolution global index, vector and full-text search over it globalIndexFileFactory()
bucket-local — data-file directory when the option is set primary-key vector ANN segments, primary-key full-text archives, deletion vectors, dynamic-bucket hash index pathFactories.get(partition, bucket)

An explicit external path wins over both layouts, as in toPath(IndexFileMeta).

For the two index kinds this crate writes itself, reads and writes move together, so a file written
here is found again: the data-evolution writer resolves an existing deletion vector through the same
path when merging and writes a new one where the reader will look; the dynamic-bucket assigner resolves
per partition and bucket for both restore and commit (prepare_commit_index no longer takes an index
directory — three of its four implementations ignored it); and TableCommit::abort deletes where the
file was written, mirroring FileStoreCommitImpl.abort. Deleting is best-effort, so the old fixed path
leaked silently — and try_commit calls abort itself on failure, as do the C and Python bindings.

Bucket directories now come from one spec::bucket_path (Java FileStorePathFactory.bucketPath),
replacing four copies of the same expression: the layout is only correct while every producer and
consumer agrees byte for byte, and nothing else enforces that.

Two smaller consequences of making the option live:

  • It is now immutable, as in Java (@Immutable, rejected by SchemaManager.checkAlterTableOption).
    It selects where index files are written, so flipping it on a populated table would hide every index
    file the table has. It was inert here before, so altering it used to be a harmless no-op.
  • $physical_files_size counts an index- prefixed file in a bucket directory as an index file
    instead of dropping it, matching Java FileType.classify. Classification follows physical form, not
    the current option value. Two tests that asserted the old counts are corrected.

The BTree reader cache is keyed by the resolved path — with the bare file name, two entries sharing a
name but resolving to different locations would reuse each other's reader.

Out of scope

  • data-file.path-directory: unsupported crate-wide (bucket paths are rooted at the table for data
    files as much as index files), so honoring it belongs with data-file path handling.
  • Writing bucket-local index files to a configured external data path: this crate does not write
    data files there either. Reading a Java-written external index file works.
  • Referenced-file identity: index files are keyed by bare file name, as Java does in the
    higher-stakes direction (LocalOrphanFilesClean maps candidate deletions by Path.getName()), and
    all names are UUID-based, so collisions are not reachable.

Behavior change

A table created with the option set but written only by older paimon-rust has its index files under
<table>/index, because this crate ignored the option — such a table is already unreadable by Java.
After this PR Rust agrees with Java. No compatibility fallback on purpose: one would diverge from Java
and mask genuine missing-file errors.

Testing

New: abort deletes an index file in the bucket data-file directory, and one at an external path (both
verified to fail against the old path); ANN segment and full-text archive resolution with the option
set, through a real split whose bucket path is not derivable from the table root — the failure this PR
fixes, previously untested through a split; directory() agrees with resolve() in every mode; decode
tests for _EXTERNAL_PATH present, present-but-null, and absent from the writer schema; the option
cannot be altered.

Gates: cargo fmt --all -- --check clean; clippy -D warnings --all-targets clean for paimon,
paimon --features fulltext, paimon-datafusion, paimon-c (paimon-python needs Python ≥ 3.10,
unavailable locally); cargo test -p paimon --lib 2425 passed, 2500 with --features fulltext,
--tests all pass. paimon-datafusion 339 passed / 7 failed — all seven are TableNotExist for the
/tmp/paimon-warehouse fixtures that make docker-up provisions, unrelated to this change.

JunRuiLee force-pushed the feat/pk-scalar-pr1-index-paths branch 3 times, most recently from 8258587 to a45c3e2 Compare August 26, 2026 14:05
JunRuiLee closed this Aug 27, 2026
JunRuiLee reopened this Aug 27, 2026
JunRuiLee force-pushed the feat/pk-scalar-pr1-index-paths branch from a45c3e2 to 5290b66 Compare August 27, 2026 08:06
JunRuiLee marked this pull request as ready for review August 27, 2026 08:07
Index files were always read from `<table>/index/<file>`, ignoring both the
`_EXTERNAL_PATH` recorded in the index manifest and the
`index-file-in-data-file-dir` table option. A table that keeps index files
beside its bucket's data files fails to read them, e.g. a primary-key vector
search reports

    failed to open ANN index file
    '<table>/index/index-<uuid>-0' for range reads

while the file actually lives in the bucket directory.

Decode `_EXTERNAL_PATH` from the index manifest (Java `IndexFileMeta` SCHEMA
field 5) and add it to the write schema so a rewritten manifest keeps it — it is
currently dropped silently — add the `index-file-in-data-file-dir` option, and
resolve every index file through one place (`table/index_file_path.rs`) with two
modes:

  * global, always `<table>/index`: the data-evolution global index, and vector
    and full-text search over it;
  * bucket-local, the data-file directory when the option is set: primary-key
    vector ANN segments, primary-key full-text archives, deletion vectors, and
    the dynamic-bucket hash index.

Each mode mirrors the factory Java uses for that consumer:
`DataEvolutionGlobalIndexScanner` resolves through `globalIndexFileFactory`,
while `IndexFileHandler` resolves hash, deletion-vector and primary-key vector
files through `pathFactories.get(partition, bucket)`, which selects
`IndexInDataFileDirPathFactory` when the option is set. An explicit external path
wins over both layouts, as in `toPath(IndexFileMeta)`.

For the two index kinds this crate writes itself, deletion vectors and the hash
index, reads and writes move together, so a file written here is found again:

  * the data-evolution writer resolves an existing deletion vector through the
    same path when merging, and writes a new one where the reader will look;
  * the dynamic-bucket assigner resolves per partition and bucket for both
    restore and commit. `BucketAssigner::prepare_commit_index` no longer takes an
    index directory — three of its four implementations ignored it, and the
    fourth now derives the layout itself;
  * `TableCommit::abort` deletes a newly written index file where it was written,
    mirroring Java `FileStoreCommitImpl.abort`, which deletes through
    `indexFileFactory(partition, bucket)`. Deleting is best-effort, so the old
    fixed path leaked the file silently instead of failing.

A bucket directory comes from the split that references the file when a split is
at hand, and otherwise from the partition and bucket being committed. Both go
through one `spec::bucket_path`, mirroring Java `FileStorePathFactory.bucketPath`:
the layout is only correct while every producer and consumer of a bucket
directory agrees byte for byte, and nothing else enforces that.

The option is immutable, as in Java, where it is annotated `@Immutable` and
`SchemaManager.checkAlterTableOption` rejects altering it: it selects the
directory index files are written to, so flipping it on a populated table would
hide every index file already written.

`$physical_files_size` now counts an `index-` prefixed file in a bucket directory
as an index file rather than dropping it, matching Java `FileType.classify`,
which maps any `index-*` basename to `BUCKET_INDEX` regardless of directory.
Classification follows the file's physical form, not the current option value, so
a file stays recognizable after the setting it was written under changes.

The BTree reader cache is keyed by the resolved path so two entries sharing a
file name cannot reuse each other's reader.

`data-file.path-directory` remains unsupported, as it is throughout this crate:
bucket paths are rooted directly at the table for data files as much as for
index files, so honoring it belongs with data-file path handling rather than
here.
JunRuiLee force-pushed the feat/pk-scalar-pr1-index-paths branch from 5290b66 to af2167b Compare August 28, 2026 06:38
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant


Back | FazBrowse Home | New Git URL