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, HasSegID, 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`
  - HasSegID --> `Int8`
  - 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.
  - HasSegID is nonzero if the segment has an identifier. Otherwise, when it is 0 the identifier is `null` and no SegID is written. Null only happens for Lucene 4.x segments referenced in commits.
  - 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 and 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 and Description
    --- | ---
    `int` | `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 int` | `VERSION_50` The file format version for the segments_N codec header, since 5.0+
    `static int` | `VERSION_51` The file format version for the segments_N codec header, since 5.1+
    `static int` | `VERSION_53` Adds the `Version` that committed this segments_N file, as well as the `Version` of the oldest segment, since 5.3+

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SegmentInfos()` Sole constructor.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and 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.
    `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.
    `static PrintStream` | `getInfoStream()` Returns `infoStream`.
    `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 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 String` | `getLastCommitSegmentsFileName(Directory directory)` Get the filename of the segments_N file for the most recent commit to the index in this Directory.
    `static String` | `getLastCommitSegmentsFileName(String[] files)` Get the filename of the segments_N file for the most recent commit in the list of index files.
    `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 SegmentInfos` | `readCommit(Directory directory, ChecksumIndexInput input, long generation)` Read the commit from the provided `ChecksumIndexInput`.
    `static SegmentInfos` | `readCommit(Directory directory, String segmentFileName)` Read a particular segmentFileName.
    `static SegmentInfos` | `readLatestCommit(Directory directory)` Find the latest commit (`segments_N file`) and load all `SegmentCommitInfo`s.
    `void` | `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(Directory directory, 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 Detail

    - #### VERSION_50

          public static final int VERSION_50

      The file format version for the segments_N codec header, since 5.0+
      See Also:
        Constant Field Values

    - #### VERSION_51

          public static final int VERSION_51

      The file format version for the segments_N codec header, since 5.1+
      See Also:
        Constant Field Values

    - #### VERSION_53

          public static final int VERSION_53

      Adds the `Version` that committed this segments_N file, as well as the `Version` of the oldest segment, since 5.3+
      See Also:
        Constant Field Values

    - #### counter

          public int 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 Detail

    - #### SegmentInfos

          public SegmentInfos()

      Sole constructor. Typically you call this and then use `or #readCommit(Directory,String)` to populate each `SegmentCommitInfo`. Alternatively, you can add/remove your own `SegmentCommitInfo`s.

  - ### Method Detail

    - #### 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,
                                                      ChecksumIndexInput input,
                                                      long generation)
                                               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`

    - #### write

          public void write(Directory directory,
                            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 void 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.

Copyright © 2000-2019 Apache Software Foundation. All Rights Reserved.