fix: block stale index entries after partial-schema merge_insert by westonpace · Pull Request #6514 · lance-format/lance

westonpace · 2026-04-14T13:48:56Z

Summary

A partial-schema merge_insert that modifies indexed columns drops the affected fragments from the index's fragment_bitmap but leaves stale entries in the index data (btree, vector, inverted). Subsequent queries that use the index find rows via both the stale entries AND the unindexed-fragment scan, producing duplicates or errors.
Adds an invalidated_fragment_bitmap field to IndexMetadata (proto + Rust) that tracks fragments removed from the bitmap during prune_updated_fields_from_indices. At query time, all rows from these fragments are blocked by the deletion mask / prefilter so stale index entries are ignored. The bitmap is cleared when the index is rebuilt.
Fixes three error categories seen in production with partial-schema merge_insert + btree index:
- Ambiguous merge inserts: multiple source rows match the same target row (221 occurrences)
- fragment id N does not exist in the dataset (114 occurrences)
- Attempt to merge two RecordBatch with different sizes: N != 0 (165 occurrences)
Also fixes duplicate results in vector search and full text search after partial-schema merge_insert

Test plan

5 new regression tests covering all error categories:
- test_partial_merge_insert_stale_index_ambiguous — second partial merge_insert finds same rows via stale btree + unindexed scan
- test_partial_merge_insert_stale_index_fragment_not_exist — partial merge + update-all + partial merge hits deleted fragment
- test_partial_merge_insert_stale_index_batch_size_mismatch — partial merge + partial update + partial merge hits deleted rows
- test_partial_merge_insert_stale_vector_index_duplicates — KNN search returns duplicate rows after partial merge
- test_partial_merge_insert_stale_fts_index_duplicates — FTS search returns duplicate rows after partial merge
All 131 existing merge_insert tests pass
Transaction, conflict resolver, scalar index, and lance-table format tests pass
Clippy clean

Closes #6283

🤖 Generated with Claude Code

codecov · 2026-04-14T14:18:31Z

Codecov Report

❌ Patch coverage is 95.97198% with 23 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
rust/lance/src/dataset/write/merge_insert.rs	98.72%	2 Missing and 4 partials ⚠️
rust/lance-table/src/format/index.rs	84.00%	1 Missing and 3 partials ⚠️
rust/lance/src/dataset/optimize/remapping.rs	50.00%	3 Missing ⚠️
rust/lance/src/dataset/transaction.rs	87.50%	0 Missing and 3 partials ⚠️
rust/lance/src/index/prefilter.rs	78.57%	1 Missing and 2 partials ⚠️
rust/lance/src/io/exec/scalar_index.rs	81.81%	1 Missing and 1 partial ⚠️
rust/lance-table/src/io/manifest.rs	75.00%	0 Missing and 1 partial ⚠️
rust/lance/src/io/commit.rs	0.00%	0 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

westonpace · 2026-04-14T16:23:31Z

This feature has come up once or twice before. Is there a reason this couldn't be implemented at the object_store level? For example, I think you could enable something like https://github.com/foyer-rs/foyer with an object_store->opendal->foyer path? Then the lance change would just be adding easier ways to enable it? For example, a special URI or methods on the dataset open?

Or is this cache doing something more than pure data caching of the object_store layer?

justinrmiller · 2026-04-14T22:09:55Z

@@ -132,6 +142,11 @@ impl DeepSizeOf for IndexMetadata {
                .map(|fragment_bitmap| fragment_bitmap.serialized_size())
                .unwrap_or(0)
            + self.files.deep_size_of_children(context)


is line 144 sort of a no-op at this point? The last line is all that will be returned right and it doesn't make use of line 144?

These lines are all added together (there is a + at the start of line 145)

justinrmiller

Just a couple of comments to consider.

justinrmiller · 2026-04-14T22:20:58Z

                    created_at: curr_index_meta.created_at,
                    base_id: None,
                    files: curr_index_meta.files.clone(),
+                    invalidated_fragment_bitmap: None,


For Keep, should invalidated_fragment_bitmap be preserved?

Good point. Actually, we can go ahead and keep the bitmap in both cases in compaction. I've updated the code. I went ahead and added a unit test as well. If an fragment becomes invalidated we remove it from the index's fragment bitmap and this will prevent the fragment from compacting with other fragments so we should be safe on compaction.

justinrmiller · 2026-04-14T22:24:50Z

+    /// Perform a partial-schema merge_insert (only id + value_a) targeting specific id ranges.
+    /// This causes touched fragments to drop from the index bitmap while btree data retains
+    /// stale entries.
+    async fn partial_merge_insert(


invalidated_fragment_bitmap grows unbounded until a full rebuild right? Could that ever become an issue?

It will never be larger than the number of fragments in the dataset which is reasonably bounded. In general, an index with any invalidated fragments is going to perform slightly worse than one without because we have to do the masking. That masking will be slightly more expensive when there are more fragments.

until a full rebuild

It will be cleared on an index update (optimize indices), not just a full rebuild.

LuQQiu

Generally looks good, besides the key problems @justinrmiller pointed out

LuQQiu · 2026-04-14T23:13:48Z

+            && let Err(e) = bitmap.serialize_into(&mut invalidated_fragment_bitmap)
+        {
+            log::error!("Failed to serialize invalidated fragment bitmap: {}", e);
+            invalidated_fragment_bitmap.clear();


not propograte the error?

Ah, yeah, this is dangerous. I guess it was copying the logic from above. Still seems we should error in both cases. We will just need to convert this into a TryFrom

I have converted it to a TryFrom

A partial-schema merge_insert that modifies indexed columns drops the affected fragments from the index's fragment_bitmap but leaves stale entries in the index data (btree, vector, inverted). Subsequent queries that use the index find rows via the stale entries AND via the unindexed-fragment scan, producing duplicates or errors. Add an `invalidated_fragment_bitmap` field to IndexMetadata that tracks fragments removed from the bitmap. At query time, all rows from these fragments are blocked by the deletion mask / prefilter so stale index entries are ignored. The bitmap is cleared when the index is rebuilt. Fixes three error categories seen in production: - "Ambiguous merge inserts: multiple source rows match the same target row" - "fragment id N does not exist in the dataset" - "Attempt to merge two RecordBatch with different sizes: N != 0" Also fixes duplicate results in vector search and full text search after partial-schema merge_insert. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

westonpace · 2026-04-15T17:13:52Z

Merge pending vote on #6529

github-actions Bot added the bug Something isn't working label Apr 14, 2026

westonpace force-pushed the fix-index-corruption-partial-schema-merge branch 5 times, most recently from df35c75 to 663bdbd Compare April 14, 2026 21:19

westonpace marked this pull request as ready for review April 14, 2026 21:21

justinrmiller reviewed Apr 14, 2026

View reviewed changes

westonpace force-pushed the fix-index-corruption-partial-schema-merge branch from 663bdbd to 92b17e9 Compare April 14, 2026 22:16

github-actions Bot added python java labels Apr 14, 2026

justinrmiller reviewed Apr 14, 2026

View reviewed changes

LuQQiu approved these changes Apr 14, 2026

View reviewed changes

jackye1995 approved these changes Apr 15, 2026

View reviewed changes

westonpace force-pushed the fix-index-corruption-partial-schema-merge branch 2 times, most recently from d0e534e to d3fd26b Compare April 15, 2026 13:16

westonpace force-pushed the fix-index-corruption-partial-schema-merge branch from d3fd26b to 498c428 Compare April 15, 2026 13:50

justinrmiller approved these changes Apr 15, 2026

View reviewed changes

westonpace mentioned this pull request Apr 16, 2026

bug(python): After building the index, executing create_scalar_index multiple times with merge_insert will result in an error. lancedb/lancedb#3280

Open

Conversation

westonpace commented Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

codecov Bot commented Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

westonpace commented Apr 14, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

justinrmiller left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

LuQQiu left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

westonpace commented Apr 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

westonpace commented Apr 14, 2026 •

edited

Loading

codecov Bot commented Apr 14, 2026 •

edited

Loading