org.apache.lucene.index

Class CheckIndex

java.lang.Object

org.apache.lucene.index.CheckIndex

public class CheckIndex
extends Object

Basic tool and API to check the health of an index and write a new segments file that removes reference to problematic segments.

As this tool checks every byte in the index, on a large index it can take quite a long time to run.

WARNING: This API is experimental and might change in incompatible ways in the next release.

Please make a complete backup of your index before using this to fix your index!

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	CheckIndex.Status Returned from checkIndex() detailing the health and status of the index.

Constructor Summary

Constructors

Constructor and Description
CheckIndex(Directory dir) Create a new CheckIndex on the directory.

Method Summary

Methods

Modifier and Type	Method and Description
CheckIndex.Status	checkIndex() Returns a CheckIndex.Status instance detailing the state of the index.
CheckIndex.Status	checkIndex(List<String> onlySegments) Returns a CheckIndex.Status instance detailing the state of the index.
void	fixIndex(CheckIndex.Status result) Repairs the index using previously returned result from checkIndex().
boolean	getCrossCheckTermVectors() See setCrossCheckTermVectors(boolean).
boolean	getFailFast() See setFailFast(boolean).
static void	main(String[] args) Command-line interface to check and fix an index.
void	setCrossCheckTermVectors(boolean v) If true, term vectors are compared against postings to make sure they are the same.
void	setFailFast(boolean v) If true, just throw the original exception immediately when corruption is detected, rather than continuing to iterate to other segments looking for more corruption.
void	setInfoStream(PrintStream out) Set infoStream where messages should go.
void	setInfoStream(PrintStream out, boolean verbose) Set infoStream where messages should go.
static CheckIndex.Status.DocValuesStatus	testDocValues(AtomicReader reader, PrintStream infoStream, boolean failFast) Test docvalues.
static CheckIndex.Status.FieldNormStatus	testFieldNorms(AtomicReader reader, PrintStream infoStream, boolean failFast) Test field norms.
static CheckIndex.Status.TermIndexStatus	testPostings(AtomicReader reader, PrintStream infoStream) Test the term index.
static CheckIndex.Status.TermIndexStatus	testPostings(AtomicReader reader, PrintStream infoStream, boolean verbose, boolean failFast) Test the term index.
static CheckIndex.Status.StoredFieldStatus	testStoredFields(AtomicReader reader, PrintStream infoStream, boolean failFast) Test stored fields.
static CheckIndex.Status.TermVectorStatus	testTermVectors(AtomicReader reader, PrintStream infoStream) Test term vectors.
static CheckIndex.Status.TermVectorStatus	testTermVectors(AtomicReader reader, PrintStream infoStream, boolean verbose, boolean crossCheckTermVectors, boolean failFast) Test term vectors.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CheckIndex

public CheckIndex(Directory dir)

Create a new CheckIndex on the directory.

Method Detail

setCrossCheckTermVectors

public void setCrossCheckTermVectors(boolean v)

If true, term vectors are compared against postings to make sure they are the same. This will likely drastically increase time it takes to run CheckIndex!

getCrossCheckTermVectors

public boolean getCrossCheckTermVectors()

See setCrossCheckTermVectors(boolean).

setFailFast

public void setFailFast(boolean v)

If true, just throw the original exception immediately when corruption is detected, rather than continuing to iterate to other segments looking for more corruption.

getFailFast

public boolean getFailFast()

See setFailFast(boolean).

setInfoStream

public void setInfoStream(PrintStream out,
                 boolean verbose)

Set infoStream where messages should go. If null, no messages are printed. If verbose is true then more details are printed.

setInfoStream

public void setInfoStream(PrintStream out)

Set infoStream where messages should go. See setInfoStream(PrintStream,boolean).

checkIndex

public CheckIndex.Status checkIndex()
                             throws IOException

Returns a CheckIndex.Status instance detailing the state of the index.

As this method checks every byte in the index, on a large index it can take quite a long time to run.

WARNING: make sure you only call this when the index is not opened by any writer.

Throws:

IOException

checkIndex

public CheckIndex.Status checkIndex(List<String> onlySegments)
                             throws IOException

Returns a CheckIndex.Status instance detailing the state of the index.

Parameters:

onlySegments - list of specific segment names to check

As this method checks every byte in the specified segments, on a large index it can take quite a long time to run.

WARNING: make sure you only call this when the index is not opened by any writer.

Throws:

IOException

testFieldNorms

public static CheckIndex.Status.FieldNormStatus testFieldNorms(AtomicReader reader,
                                               PrintStream infoStream,
                                               boolean failFast)
                                                        throws IOException

Test field norms.

Throws:

IOException

WARNING: This API is experimental and might change in incompatible ways in the next release.

testPostings

public static CheckIndex.Status.TermIndexStatus testPostings(AtomicReader reader,
                                             PrintStream infoStream)
                                                      throws IOException

Test the term index.

Throws:

IOException

WARNING: This API is experimental and might change in incompatible ways in the next release.

testPostings

public static CheckIndex.Status.TermIndexStatus testPostings(AtomicReader reader,
                                             PrintStream infoStream,
                                             boolean verbose,
                                             boolean failFast)
                                                      throws IOException

Test the term index.

Throws:

IOException

WARNING: This API is experimental and might change in incompatible ways in the next release.

testStoredFields

public static CheckIndex.Status.StoredFieldStatus testStoredFields(AtomicReader reader,
                                                   PrintStream infoStream,
                                                   boolean failFast)
                                                            throws IOException

Test stored fields.

Throws:

IOException

WARNING: This API is experimental and might change in incompatible ways in the next release.

testDocValues

public static CheckIndex.Status.DocValuesStatus testDocValues(AtomicReader reader,
                                              PrintStream infoStream,
                                              boolean failFast)
                                                       throws IOException

Test docvalues.

Throws:

IOException

WARNING: This API is experimental and might change in incompatible ways in the next release.

testTermVectors

public static CheckIndex.Status.TermVectorStatus testTermVectors(AtomicReader reader,
                                                 PrintStream infoStream)
                                                          throws IOException

Test term vectors.

Throws:

IOException

WARNING: This API is experimental and might change in incompatible ways in the next release.

testTermVectors

public static CheckIndex.Status.TermVectorStatus testTermVectors(AtomicReader reader,
                                                 PrintStream infoStream,
                                                 boolean verbose,
                                                 boolean crossCheckTermVectors,
                                                 boolean failFast)
                                                          throws IOException

Test term vectors.

Throws:

IOException

WARNING: This API is experimental and might change in incompatible ways in the next release.

fixIndex

public void fixIndex(CheckIndex.Status result)
              throws IOException

Repairs the index using previously returned result from checkIndex(). Note that this does not remove any of the unreferenced files after it's done; you must separately open an IndexWriter, which deletes unreferenced files when it's created.

WARNING: this writes a new segments file into the index, effectively removing all documents in broken segments from the index. BE CAREFUL.

WARNING: Make sure you only call this when the index is not opened by any writer.

Throws:

IOException

main

public static void main(String[] args)
                 throws IOException,
                        InterruptedException

Command-line interface to check and fix an index.

Run it like this:

    java -ea:org.apache.lucene... org.apache.lucene.index.CheckIndex pathToIndex [-fix] [-verbose] [-segment X] [-segment Y]
    

• -fix: actually write a new segments_N file, removing any problematic segments
• -segment X: only check the specified segment(s). This can be specified multiple times, to check more than one segment, eg -segment _2 -segment _a. You can't use this with the -fix option.

WARNING: -fix should only be used on an emergency basis as it will cause documents (perhaps many) to be permanently removed from the index. Always make a backup copy of your index before running this! Do not run this tool on an index that is actively being written to. You have been warned!

Run without -fix, this tool will open the index, report version information and report any exceptions it hits and what action it would take if -fix were specified. With -fix, this tool will remove any segments that have issues and write a new segments_N file. This means all documents contained in the affected segments will be removed.

This tool exits with exit code 1 if the index cannot be opened or has any corruption, else 0.

Throws:

IOException

InterruptedException