Package org.apache.lucene.index

# Class SegmentInfos

java.lang.Object
org.apache.lucene.index.SegmentInfos

All Implemented Interfaces:
  `Cloneable`, `Iterable<SegmentCommitInfo>`

public final class SegmentInfos extends Object implements Cloneable, Iterable<SegmentCommitInfo>
A collection of segmentInfo objects with methods for operating on those segments in relation to the file system.

The active segments in the index are stored in the segment info file, `segments_N`. There may be one or more `segments_N` files in the index; however, the one with the largest generation is the active one (when older segments_N files are present it's because they temporarily cannot be deleted, or a custom `IndexDeletionPolicy` is in use). This file lists each segment by name and has details about the codec and generation of deletes.

Files:

- `segments_N`: Header, LuceneVersion, Version, NameCounter, SegCount, MinSegmentLuceneVersion, <SegName, SegID, SegCodec, DelGen, DeletionCount, FieldInfosGen, DocValuesGen, UpdatesFiles>SegCount, CommitUserData, Footer

Data types:

- Header --> `IndexHeader`
- LuceneVersion --> Which Lucene code `Version` was used for this commit, written as three `vInt`: major, minor, bugfix
- MinSegmentLuceneVersion --> Lucene code `Version` of the oldest segment, written as three `vInt`: major, minor, bugfix; this is only written only if there's at least one segment
- NameCounter, SegCount, DeletionCount --> `Int32`
- Generation, Version, DelGen, Checksum, FieldInfosGen, DocValuesGen --> `Int64`
- SegID --> `Int8ID_LENGTH`
- SegName, SegCodec --> `String`
- CommitUserData --> `Map<String,String>`
- UpdatesFiles --> Map<`Int32`, `Set<String>`>
- Footer --> `CodecFooter`

Field Descriptions:

- Version counts how often the index has been changed by adding or deleting documents.
- NameCounter is used to generate names for new segment files.
- SegName is the name of the segment, and is used as the file name prefix for all of the files that compose the segment's index.
- DelGen is the generation count of the deletes file. If this is -1, there are no deletes. Anything above zero means there are deletes stored by `LiveDocsFormat`.
- DeletionCount records the number of deleted documents in this segment.
- SegCodec is the `name` of the Codec that encoded this segment.
- SegID is the identifier of the Codec that encoded this segment.
- CommitUserData stores an optional user-supplied opaque Map<String,String> that was passed to `IndexWriter.setLiveCommitData(Iterable)`.
- FieldInfosGen is the generation count of the fieldInfos file. If this is -1, there are no updates to the fieldInfos in that segment. Anything above zero means there are updates to fieldInfos stored by `FieldInfosFormat` .
- DocValuesGen is the generation count of the updatable DocValues. If this is -1, there are no updates to DocValues in that segment. Anything above zero means there are updates to DocValues stored by `DocValuesFormat`.
- UpdatesFiles stores the set of files that were updated in that segment per field.

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

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `SegmentInfos.FindSegmentsFile<T>`
  Utility class for executing code that needs to do something with the current segments file.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `long`
  `counter`
  Used to name new segments.
  `Map<String,String>`
  `userData`
  Opaque Map<String, String> that user can specify during IndexWriter.commit
  `long`
  `version`
  Counts how often the index has been changed.
  `static final int`
  `VERSION_74`
  The version at the time when 8.0 was released.
  `static final int`
  `VERSION_86`
  The version that recorded SegmentCommitInfo IDs

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `SegmentInfos(int indexCreatedVersionMajor)`
  Sole constructor.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `add(SegmentCommitInfo si)`
  Appends the provided `SegmentCommitInfo`.
  `void`
  `addAll(Iterable<SegmentCommitInfo> sis)`
  Appends the provided `SegmentCommitInfo`s.
  `List<SegmentCommitInfo>`
  `asList()`
  Returns all contained segments as an unmodifiable `List` view.
  `void`
  `changed()`
  Call this before committing if changes have been made to the segments.
  `void`
  `clear()`
  Clear all `SegmentCommitInfo`s.
  `SegmentInfos`
  `clone()`
  Returns a copy of this instance, also copying each SegmentInfo.
  `final void`
  `commit(Directory dir)`
  Writes and syncs to the Directory dir, taking care to remove the segments file on exception
  `Collection<String>`
  `files(boolean includeSegmentsFile)`
  Returns all file names referenced by SegmentInfo.
  `static long`
  `generationFromSegmentsFileName(String fileName)`
  Parse the generation off the segments file name and return it.
  `Version`
  `getCommitLuceneVersion()`
  Returns which Lucene `Version` wrote this commit, or null if the version this index was written with did not directly record the version.
  `long`
  `getGeneration()`
  Returns current generation.
  `byte[]`
  `getId()`
  Since Lucene 5.0, every commit (segments_N) writes a unique id.
  `int`
  `getIndexCreatedVersionMajor()`
  Return the version major that was used to initially create the index.
  `static PrintStream`
  `getInfoStream()`
  Returns `infoStream`.
  `static long`
  `getLastCommitGeneration(String[] files)`
  Get the generation of the most recent commit to the list of index files (N in the segments_N file).
  `static long`
  `getLastCommitGeneration(Directory directory)`
  Get the generation of the most recent commit to the index in this directory (N in the segments_N file).
  `static String`
  `getLastCommitSegmentsFileName(String[] files)`
  Get the filename of the segments_N file for the most recent commit in the list of index files.
  `static String`
  `getLastCommitSegmentsFileName(Directory directory)`
  Get the filename of the segments_N file for the most recent commit to the index in this Directory.
  `long`
  `getLastGeneration()`
  Returns last succesfully read or written generation.
  `Version`
  `getMinSegmentLuceneVersion()`
  Returns the version of the oldest segment, or null if there are no segments.
  `String`
  `getSegmentsFileName()`
  Get the segments_N filename in use by this segment infos.
  `Map<String,String>`
  `getUserData()`
  Return `userData` saved with this commit.
  `long`
  `getVersion()`
  version number when this SegmentInfos was generated.
  `SegmentCommitInfo`
  `info(int i)`
  Returns `SegmentCommitInfo` at the provided index.
  `Iterator<SegmentCommitInfo>`
  `iterator()`
  Returns an unmodifiable `Iterator` of contained segments in order.
  `static final SegmentInfos`
  `readCommit(Directory directory, String segmentFileName)`
  Read a particular segmentFileName.
  `static final SegmentInfos`
  `readCommit(Directory directory, String segmentFileName, int minSupportedMajorVersion)`
  Read a particular segmentFileName, as long as the commit's `getIndexCreatedVersionMajor()` is strictly greater than the provided minimum supported major version.
  `static final SegmentInfos`
  `readCommit(Directory directory, ChecksumIndexInput input, long generation)`
  Read the commit from the provided `ChecksumIndexInput`.
  `static final SegmentInfos`
  `readCommit(Directory directory, ChecksumIndexInput input, long generation, int minSupportedMajorVersion)`
  Read the commit from the provided `ChecksumIndexInput`.
  `static final SegmentInfos`
  `readLatestCommit(Directory directory)`
  Find the latest commit (`segments_N file`) and load all `SegmentCommitInfo`s.
  `static final SegmentInfos`
  `readLatestCommit(Directory directory, int minSupportedMajorVersion)`
  Find the latest commit (`segments_N file`) and load all `SegmentCommitInfo`s, as long as the commit's `getIndexCreatedVersionMajor()` is strictly greater than the provided minimum supported major version.
  `boolean`
  `remove(SegmentCommitInfo si)`
  Remove the provided `SegmentCommitInfo`.
  `static void`
  `setInfoStream(PrintStream infoStream)`
  If non-null, information about retries when loading the segments file will be printed to this.
  `void`
  `setNextWriteGeneration(long generation)`
  Set the generation to be used for the next commit
  `void`
  `setUserData(Map<String,String> data, boolean doIncrementVersion)`
  Sets the commit data.
  `int`
  `size()`
  Returns number of `SegmentCommitInfo`s.
  `String`
  `toString()`
  Returns readable description of this segment.
  `int`
  `totalMaxDoc()`
  Returns sum of all segment's maxDocs.
  `void`
  `updateGeneration(SegmentInfos other)`
  Carry over generation numbers from another SegmentInfos
  `void`
  `write(IndexOutput out)`
  Write ourselves to the provided `IndexOutput`

  ### Methods inherited from class java.lang.Object

  `equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

  ### Methods inherited from interface java.lang.Iterable

  `forEach, spliterator`

- ## Field Details

  - ### VERSION_74

    public static final int VERSION_74
    The version at the time when 8.0 was released.
    See Also:
      - Constant Field Values

  - ### VERSION_86

    public static final int VERSION_86
    The version that recorded SegmentCommitInfo IDs
    See Also:
      - Constant Field Values

  - ### counter

    public long counter
    Used to name new segments.

  - ### version

    public long version
    Counts how often the index has been changed.

  - ### userData

    public Map<String,String> userData
    Opaque Map<String, String> that user can specify during IndexWriter.commit

- ## Constructor Details

  - ### SegmentInfos

    public SegmentInfos(int indexCreatedVersionMajor)
    Sole constructor.
    Parameters:
      `indexCreatedVersionMajor` - the Lucene version major at index creation time, or 6 if the index was created before 7.0

- ## Method Details

  - ### info

    public SegmentCommitInfo info(int i)
    Returns `SegmentCommitInfo` at the provided index.

  - ### getLastCommitGeneration

    public static long getLastCommitGeneration(String[] files)
    Get the generation of the most recent commit to the list of index files (N in the segments_N file).
    Parameters:
      `files` - -- array of file names to check

  - ### getLastCommitGeneration

    public static long getLastCommitGeneration(Directory directory) throws IOException
    Get the generation of the most recent commit to the index in this directory (N in the segments_N file).
    Parameters:
      `directory` - -- directory to search for the latest segments_N file
    Throws:
      `IOException`

  - ### getLastCommitSegmentsFileName

    public static String getLastCommitSegmentsFileName(String[] files)
    Get the filename of the segments_N file for the most recent commit in the list of index files.
    Parameters:
      `files` - -- array of file names to check

  - ### getLastCommitSegmentsFileName

    public static String getLastCommitSegmentsFileName(Directory directory) throws IOException
    Get the filename of the segments_N file for the most recent commit to the index in this Directory.
    Parameters:
      `directory` - -- directory to search for the latest segments_N file
    Throws:
      `IOException`

  - ### getSegmentsFileName

    public String getSegmentsFileName()
    Get the segments_N filename in use by this segment infos.

  - ### generationFromSegmentsFileName

    public static long generationFromSegmentsFileName(String fileName)
    Parse the generation off the segments file name and return it.

  - ### getId

    public byte[] getId()
    Since Lucene 5.0, every commit (segments_N) writes a unique id. This will return that id

  - ### readCommit

    public static final SegmentInfos readCommit(Directory directory, String segmentFileName) throws IOException
    Read a particular segmentFileName. Note that this may throw an IOException if a commit is in process.
    Parameters:
      `directory` - -- directory containing the segments file
      `segmentFileName` - -- segment file to load
    Throws:
      `CorruptIndexException` - if the index is corrupt
      `IOException` - if there is a low-level IO error

  - ### readCommit

    public static final SegmentInfos readCommit(Directory directory, String segmentFileName, int minSupportedMajorVersion) throws IOException
    Read a particular segmentFileName, as long as the commit's `getIndexCreatedVersionMajor()` is strictly greater than the provided minimum supported major version. If the commit's version is older, an `IndexFormatTooOldException` will be thrown. Note that this may throw an IOException if a commit is in process.
    Throws:
      `IOException`

  - ### readCommit

    public static final SegmentInfos readCommit(Directory directory, ChecksumIndexInput input, long generation) throws IOException
    Read the commit from the provided `ChecksumIndexInput`.
    Throws:
      `IOException`

  - ### readCommit

    public static final SegmentInfos readCommit(Directory directory, ChecksumIndexInput input, long generation, int minSupportedMajorVersion) throws IOException
    Read the commit from the provided `ChecksumIndexInput`.
    Throws:
      `IOException`

  - ### readLatestCommit

    public static final SegmentInfos readLatestCommit(Directory directory) throws IOException
    Find the latest commit (`segments_N file`) and load all `SegmentCommitInfo`s.
    Throws:
      `IOException`

  - ### readLatestCommit

    public static final SegmentInfos readLatestCommit(Directory directory, int minSupportedMajorVersion) throws IOException
    Find the latest commit (`segments_N file`) and load all `SegmentCommitInfo`s, as long as the commit's `getIndexCreatedVersionMajor()` is strictly greater than the provided minimum supported major version. If the commit's version is older, an `IndexFormatTooOldException` will be thrown.
    Throws:
      `IOException`

  - ### write

    public void write(IndexOutput out) throws IOException
    Write ourselves to the provided `IndexOutput`
    Throws:
      `IOException`

  - ### clone

    public SegmentInfos clone()
    Returns a copy of this instance, also copying each SegmentInfo.
    Overrides:
      `clone` in class `Object`

  - ### getVersion

    public long getVersion()
    version number when this SegmentInfos was generated.

  - ### getGeneration

    public long getGeneration()
    Returns current generation.

  - ### getLastGeneration

    public long getLastGeneration()
    Returns last succesfully read or written generation.

  - ### setInfoStream

    public static void setInfoStream(PrintStream infoStream)
    If non-null, information about retries when loading the segments file will be printed to this.

  - ### getInfoStream

    public static PrintStream getInfoStream()
    Returns `infoStream`.
    See Also:
      - `setInfoStream(java.io.PrintStream)`

  - ### updateGeneration

    public void updateGeneration(SegmentInfos other)
    Carry over generation numbers from another SegmentInfos
    NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

  - ### setNextWriteGeneration

    public void setNextWriteGeneration(long generation)
    Set the generation to be used for the next commit

  - ### files

    public Collection<String> files(boolean includeSegmentsFile) throws IOException
    Returns all file names referenced by SegmentInfo. The returned collection is recomputed on each invocation.
    Throws:
      `IOException`

  - ### commit

    public final void commit(Directory dir) throws IOException
    Writes and syncs to the Directory dir, taking care to remove the segments file on exception

    Note: `changed()` should be called prior to this method if changes have been made to this `SegmentInfos` instance

    Throws:
      `IOException`

  - ### toString

    public String toString()
    Returns readable description of this segment.
    Overrides:
      `toString` in class `Object`

  - ### getUserData

    public Map<String,String> getUserData()
    Return `userData` saved with this commit.
    See Also:
      - `IndexWriter.commit()`

  - ### setUserData

    public void setUserData(Map<String,String> data, boolean doIncrementVersion)
    Sets the commit data.

  - ### totalMaxDoc

    public int totalMaxDoc()
    Returns sum of all segment's maxDocs. Note that this does not include deletions

  - ### changed

    public void changed()
    Call this before committing if changes have been made to the segments.

  - ### iterator

    public Iterator<SegmentCommitInfo> iterator()
    Returns an unmodifiable `Iterator` of contained segments in order.
    Specified by:
      `iterator` in interface `Iterable<SegmentCommitInfo>`

  - ### asList

    public List<SegmentCommitInfo> asList()
    Returns all contained segments as an unmodifiable `List` view.

  - ### size

    public int size()
    Returns number of `SegmentCommitInfo`s.

  - ### add

    public void add(SegmentCommitInfo si)
    Appends the provided `SegmentCommitInfo`.

  - ### addAll

    public void addAll(Iterable<SegmentCommitInfo> sis)
    Appends the provided `SegmentCommitInfo`s.

  - ### clear

    public void clear()
    Clear all `SegmentCommitInfo`s.

  - ### remove

    public boolean remove(SegmentCommitInfo si)
    Remove the provided `SegmentCommitInfo`.

    WARNING: O(N) cost

  - ### getCommitLuceneVersion

    public Version getCommitLuceneVersion()
    Returns which Lucene `Version` wrote this commit, or null if the version this index was written with did not directly record the version.

  - ### getMinSegmentLuceneVersion

    public Version getMinSegmentLuceneVersion()
    Returns the version of the oldest segment, or null if there are no segments.

  - ### getIndexCreatedVersionMajor

    public int getIndexCreatedVersionMajor()
    Return the version major that was used to initially create the index. This version is set when the index is first created and then never changes. This information was added as of version 7.0 so older indices report 6 as a creation version.