Performance of stored field compression in Lucene 4.1+

Starting at version 4.1 of the Apache Lucene search library, compression of stored fields is enabled by default. The basic idea is that with some refinements to how compression is handled, disk I/O will often end up costing more time than the extra CPU cycles required to decompress data when retrieving documents from search results. This suits the most common usage scenarios of Lucene well, but is not always a win. Depending on factors such as server hardware and index update frequency, it may hurt performance if you have many small stored fields and/or your on disk index fits nicely in available OS cache memory in uncompressed form.

If you just need to know how to to disable stored field compression, you can skip directly to the solution.


We use the Lucene heavily in our Java-based CMS solution. It’s mostly about indexing metadata, which is used for lookups and all kinds of listing queries. We gain flexibility and great speed by using Lucene instead querying the database through a SQL interface (the authoritive source of basically the same set of metadata that we index). Up to this point, things look pretty standard.

Our use of Lucene may be considered atypical, though. We do not index full text content (instead dedicated Apache Solr instances are used for that purpose), and we do not use scoring. Our metadata queries use pure boolean algebra and filters on typed data fields, and most use some defined sorting order (but never score). These queries are usually not based on human input, but rather pre-coded, configured or built dynamically by the system. Some searches will fetch a significant amount of documents from the result set, and also a significant amount of fields from each of those docs. In addition, we have lower level Lucene customizations like filters, callback based API for walking the index with no limits on number of retrievable matches and conversion of queries to filters for speed.

Migrating from Lucene 3 to 4 resulted in performance reduction

Last year, we did a major upgrade from Lucene 3.6.2 to Lucene 4.9. Testing had not revealed much difference in performance, but when it all went into production, we saw a noticeable increase in CPU usage on our application servers. Logs showed that searches took more time than with the previous Lucene 3 based release. (You may now argue that our performance testing was not thorough enough, and you would be right, but that is beside the point.)

After investigating thread dumps of busy JVMs, we discovered that many threads were often in Lucene code, and then in a decompresssing stage for stored field retrieval. This was consistently the case, and we figured it had to be the cause of the increase in CPU usage.

Solution: disable stored field compression

With many small stored fields that are often retrieved in search results and indices which fit in OS cache memory, compression yielded worse performance for us. Unfortunately there is no simple config option to adjust this feature in Lucene 4.X* and it requires swapping out a codec format class.
*I have not yet investigated if this is the case with Lucene 5.X.

You need to provide a custom codec class to your IndexWriter in order to disable stored field compression. There is a class called FilterCodec in the Lucene API which wraps a base codec class instance and delegates by default. It can be extended to allow overriding methods that provide specific parts or formats of a codec. In this case we need only change the stored fields format.

Create a custom codec class:

import org.apache.lucene.codecs.FilterCodec;
import org.apache.lucene.codecs.StoredFieldsFormat;
import org.apache.lucene.codecs.lucene40.Lucene40StoredFieldsFormat;
import org.apache.lucene.codecs.lucene410.Lucene410Codec;

public final class Lucene410CodecWithNoFieldCompression extends FilterCodec {

    private final StoredFieldsFormat storedFieldsFormat;

    public Lucene410CodecWithNoFieldCompression() {
        super("Lucene410CodecWithNoFieldCompression", new Lucene410Codec());
        storedFieldsFormat = new Lucene40StoredFieldsFormat();

    public StoredFieldsFormat storedFieldsFormat() {
        return storedFieldsFormat;

This custom  org.apache.lucene.codecs.Codec subclass uses Lucene410Codec as basis, but swaps out the stored fields format with Lucene40StoredFieldsFormat, which does not employ compression.

Set this codec class in your IndexWriterConfig instance:

IndexWriterConfig cfg = new IndexWriterConfig(Version.LATEST, someAnalyzer);
cfg.setCodec(new Lucene410CodecWithNoFieldCompression());

IndexWriter myWriter = new IndexWriter(someDirectory, cfg);

This takes care of the index writing part, and segments written by myWriter will not use compression for stored fields. However, Lucene also needs to be able to open and read index segments created by this writer, which in principle uses an entirely new custom codec. Lucene locates codec classes on the classpath through Java service provider interface (SPI) mechanism, where codecs are identified by name. Our custom codec uses the name "Lucene410CodecWithNoFieldCompression" (passed to the FilterCodec superclass constructor in the example class above).

Make the class available through SPI by creating a file:
with the following contents:

This file itself should be available in the classpath, e.g. in your appliaction jar or war file. Lucene will now be able to open and read index segments created by myWriter.

You should be aware that generic Lucene tools such as Luke will not be able to open indices created with your custom codec, since it is unknown to them. You can however provide the codec class by adding it their classpath, along with the SPI metadata file (assuming the tool is Java-based).

Difference in performance and size

We observed a clear reduction on server load average on our busiest site, and most queries have had their total execution time reduced. On the extreme side, some heavy data report queries that iterate many index documents had their total execution time reduced by up to 75%. We suspect this to be caused by access of small stored fields for many docs, which was hit pretty badly by compression. As for size, one of our larger indices grew by only 80% without compression, which is no problem for us.


  1. Blog posts Efficient compressed stored fields with Lucene and Stored fields compression in Lucene 4.1 by Adrien Grand.