Skip to content

Document extra Lucene 10 migration work #12

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
markrmiller merged 1 commit into from
Aug 1, 2025
Merged

Document extra Lucene 10 migration work #12

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 42 additions & 0 deletions lucene_10_migration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,12 @@
- **Lucene Change:** `MIGRATE.md` line 270.
- **Action Required:** Update imports and calls to use the `IndexSearcher` static methods.
- **Dependencies:** None
- [ ] **HIGH** IndexWriter block sort: configure parent field when using index sorting with document blocks.
- **Impact:** Without a parent field, document blocks may be reordered incorrectly.
- **Location:** Indexing configuration where `IndexWriterConfig#setIndexSort` is used with block indexing.
- **Lucene Change:** `MIGRATE.md` lines 47-53.
- **Action Required:** Set `IndexWriterConfig#setParentField` to the field marking parent documents.
- **Dependencies:** None

## API Updates
- [ ] **HIGH** Record classes: Access `TotalHits` and other converted records via accessor methods.
Expand Down Expand Up @@ -141,7 +147,25 @@
- **Lucene Change:** `MIGRATE.md` lines 676-684.
- **Action Required:** Replace with `LetterTokenizer` followed by `LowerCaseFilter` or custom filter chain.
- **Dependencies:** None
- [ ] **MEDIUM** ScoreCachingWrappingScorer now wraps LeafCollector instead of Scorable.
- **Impact:** Custom highlighters or collectors using this class must adapt to the new wrapper.
- **Location:** Plugins or extensions referencing `ScoreCachingWrappingScorer`.
- **Lucene Change:** `MIGRATE.md` lines 188-198.
- **Action Required:** Use `ScoreCachingWrappingScorer.wrap(LeafCollector)` and remove `Scorable` references.
- **Dependencies:** Removal of `Scorable#docID()`
- [ ] **MEDIUM** Normalizer and stemmer classes are package-private.
- **Impact:** Direct references to these classes or their constants will fail.
- **Location:** Custom analyzers referencing stemmer or normalizer constants.
- **Lucene Change:** `MIGRATE.md` lines 117-120.
- **Action Required:** Inline constant values or rely on public factory APIs.
- **Dependencies:** None

- [ ] **LOW** KnnVectorsReader no longer implements `Accountable`.
- **Impact:** Memory usage reporting via `Accountable` is unavailable.
- **Location:** `SchemaCodecFactory` and any custom codecs referencing `KnnVectorsReader`.
- **Lucene Change:** `MIGRATE.md` lines 258-261.
- **Action Required:** Remove reliance on `Accountable` for vector readers.
- **Dependencies:** None
## Behavioral Changes
- [ ] **HIGH** Faceting: `LongRangeFacetCounts#getTopChildren` and `DoubleRangeFacetCounts#getTopChildren` now return only the top‑n ranges.
- **Impact:** Range facet output may differ from 9.x behaviour.
Expand All @@ -161,6 +185,12 @@
- **Lucene Change:** `MIGRATE.md` lines 274‑278.
- **Action Required:** Explicitly enable throttling if required via configuration.
- **Dependencies:** None
- [ ] **MEDIUM** IOContext default read advice is now `RANDOM`.
- **Impact:** Default sequential read-ahead may change for `MMapDirectory`.
- **Location:** Any components using default `IOContext` for directory reads.
- **Lucene Change:** `CHANGES.txt` lines 592-604.
- **Action Required:** Set system property `-Dorg.apache.lucene.store.defaultReadAdvice=normal` if sequential behavior is preferred.
- **Dependencies:** None
- [ ] **LOW** Romanian analysis normalization changed; reindex Romanian text if relying on old behavior.
- **Impact:** Search results for Romanian text may differ.
- **Location:** Any cores using `RomanianAnalyzer`.
Expand All @@ -186,6 +216,12 @@
- **Lucene Change:** `MIGRATE.md` lines 93‑97.
- **Action Required:** Determinize automata before building queries where necessary.
- **Dependencies:** None
- [ ] **LOW** DataInput#readVLong may read negative values and up to 10 bytes.
- **Impact:** Custom `DataInput` implementations must handle 10-byte varints and negative numbers.
- **Location:** `JavaBinCodec`, snapshot metadata readers, and `CustomBufferedIndexInput`.
- **Lucene Change:** `MIGRATE.md` lines 22-27.
- **Action Required:** Review implementations for compatibility with new encoding.
- **Dependencies:** None
- [ ] **MEDIUM** RegExp complement syntax deprecated.
- **Impact:** Using `~` requires `RegExp.DEPRECATED_COMPLEMENT` flag or alternative patterns.
- **Location:** Custom `RegExp` constructions in query parsers.
Expand All @@ -212,6 +248,12 @@
- **Lucene Change:** `MIGRATE.md` lines 155‑160.
- **Action Required:** Replace with `-level 1/2/3` as appropriate.
- **Dependencies:** None
- [ ] **LOW** Configure JUL logging bridge for Lucene core.
- **Impact:** Lucene now emits logs via java.util.logging which may bypass existing log setups.
- **Location:** Logging configuration and InfoStream implementations.
- **Lucene Change:** `MIGRATE.md` lines 302-315.
- **Action Required:** Install a JUL-to-SLF4J or Log4j adapter to capture these logs.
- **Dependencies:** None

## Optional Enhancements
- [ ] **LOW** Evaluate new `SeededKnnVectorQuery` and quantized vector codecs for potential performance improvements.
Expand Down
Loading