Performance tuning

IndexWriter buffers new documents in memory and flushes a segment when the buffer fills. Drive that by bytes: set IndexWriterConfig.setRAMBufferSizeMB(…​) and leave setMaxBufferedDocs(…​) disabled. A bigger buffer means fewer, larger initial segments and therefore less merging downstream. 256—​512 MB is a common bulk-load figure; the ceiling is heap you can spare and the point past which merge parallelism, not flush frequency, is the bottleneck.

IndexWriter is thread-safe and built to be fed concurrently: it hands each calling thread its own document-writer state and flushes those independently. Open it once, share the single instance across your loader threads, and let it manage the parallelism. Opening a second writer on the same directory is not allowed (the write lock forbids it), and funnelling every addDocument through one synchronized caller throws the throughput away.

Merging competes with indexing for CPU and I/O. TieredMergePolicy (the default) and ConcurrentMergeScheduler expose the trade-off: during a big one-off load, raise setSegmentsPerTier / setMaxMergeAtOnce so small segments accumulate instead of being merged eagerly, and raise the scheduler’s setMaxMergesAndThreads(…​) if the target disk is fast enough to merge in parallel with the load. Restore the defaults afterwards so steady-state search does not degrade under a growing segment count.

writer.forceMerge(1) rewrites the whole index into a single segment. It makes searches and term-dictionary lookups as fast as they get and physically drops every deleted document, but it is expensive (it reads and rewrites the entire index) and the resulting huge segment is never chosen for natural merging again — so if writes resume you are left with one giant segment slowly filling with deletes. Run it once, after the final commit, on an index you will only search from now on.

The fastest way to build a large index on one machine is to build several smaller ones concurrently — separate directories, separate writers, no lock contention — and then fold them into one with IndexWriter.addIndexes(CodecReader…​). That call copies segments in at the byte level (no re-analysis), and the CodecReader wrapper can apply an index Sort or drop fields as it goes.

For the segment and merge-policy mechanics behind all of the above, see Indexing & merge policies.

Constructing an IndexSearcher per query, or reopening a DirectoryReader per query, throws away every warmed cache and every memory-mapped page you just paid for. Hold one searcher, serve all queries from it, and swap it for a fresh one only when new data must become visible. SearcherManager does exactly this: acquire() / release() around each request, maybeRefresh() on a schedule or after a commit.

Reopen frequency is the key dial — see Near-real-time search. Reopening every second or few seconds is fine; reopening on every write is not.

A freshly reopened reader has cold DocValues, cold norms, and an empty query cache; the first queries after each refresh pay for all of it. Pass a SearcherFactory that runs representative queries against the new searcher — touching the sort fields and facet fields — before SearcherManager publishes it, and set IndexWriterConfig.setMergedSegmentWarmer(…​) so freshly merged segments are warmed too.

MMapDirectory (the default on 64-bit platforms) maps index files into virtual memory and lets the operating system cache the hot pages. That cache lives outside the JVM heap, so an oversized heap starves the very cache that makes mmap fast. Give the JVM the heap it needs and no more — often well under half of RAM — and leave the rest for the page cache. Lucene 10’s MMapDirectory uses the Java 21 foreign-memory API and no longer suffers the per-mapping size limits of the old implementation.

See Directories & storage for the Directory implementations and their trade-offs.

Every IndexSearcher shares a process-wide LRUQueryCache that caches the doc-id set produced by a BooleanClause.Occur.FILTER query, per segment, and a UsageTrackingQueryCachingPolicy that only caches a query once it has been seen often enough and only on segments large enough to be worth it. You get this for free; the levers are its size and, rarely, replacing it.

Put binary conditions in a FILTER clause so they are cache-eligible and skip scoring — see Filtering & faceting.

Sorting or faceting needs a column of values per document. That is what the *DocValuesField types build at index time; reading them back is a memory-mapped columnar scan. Sorting that has to obtain values any other way is the slow path. Add the doc-values field alongside the indexed field when you index.

Counting every match is more work than finding the top N. TopScoreDocCollectorManager and TopFieldCollectorManager take a totalHitsThreshold: once that many hits are known, scoring can skip non-competitive documents (block-max WAND) and TopDocs.totalHits becomes a GREATER_THAN_OR_EQUAL_TO lower bound instead of an exact count. Use a small threshold (1000 is typical) unless the UI truly needs an exact result count.

IndexSearcher can also parallelise a single query across segments when constructed with an Executor; see Collectors & concurrent search.

A flush turns the RAM buffer into a searchable segment; a commit fsyncs and writes a new segments_N so the flushed data survives a crash; a merge folds small segments into larger ones in the background. Reopen frequency controls how quickly a flush becomes visible, commit frequency controls how much work a crash loses, and merge policy controls the steady-state segment count every query pays for.