Module org.elasticsearch.server
Package org.elasticsearch.index

Record Class IndexVersion

java.lang.Object
java.lang.Record
org.elasticsearch.index.IndexVersion
All Implemented Interfaces:
Comparable<IndexVersion>, VersionId<IndexVersion>, ToXContent, ToXContentFragment
public record IndexVersion(int id, org.apache.lucene.util.Version luceneVersion) extends Record implements VersionId<IndexVersion>, ToXContentFragment
The index version.

Prior to 8.8.0, the node Version was used everywhere. This class separates the index format version from the running node version.

Each index version constant has an id number, which for versions prior to 8.9.0 is the same as the release version for backwards compatibility. In 8.9.0 this is changed to an incrementing number, disconnected from the release version.

Each version constant has a unique id string. This is not actually stored in the index, but is there to ensure each index version is only added to the source file once. This string needs to be unique (normally a UUID, but can be any other unique nonempty string). If two concurrent PRs add the same index version, the different unique ids cause a git conflict, ensuring the second PR to be merged must be updated with the next free version first. Without the unique id string, git will happily merge the two versions together, resulting in the same index version being used across multiple commits, causing problems when you try to upgrade between those two merged commits.

Version compatibility

The earliest compatible version is hardcoded in the MINIMUM_COMPATIBLE field. Previously, this was dynamically calculated from the major/minor versions of Version, but IndexVersion does not have separate major/minor version numbers. So the minimum compatible version is hard-coded as the index version used by the first version of the previous major release. MINIMUM_COMPATIBLE should be updated appropriately whenever a major release happens.

Adding a new version

A new index version should be added every time a change is made to the serialization protocol of one or more classes. Each index version should only be used in a single merged commit (apart from BwC versions copied from Version).

To add a new index version, add a new constant at the bottom of the list that is one greater than the current highest version, ensure it has a unique id, and update the current() constant to point to the new version.

Reverting an index version

If you revert a commit with an index version change, you must ensure there is a new index version representing the reverted change. Do not let the index version go backwards, it must always be incremented.

  • Field Details

  • Constructor Details

    • IndexVersion

      public IndexVersion(int id, org.apache.lucene.util.Version luceneVersion)
      Creates an instance of a IndexVersion record class.
      Parameters:
      id - the value for the id record component
      luceneVersion - the value for the luceneVersion record component

  • Method Details

    • readVersion

      public static IndexVersion readVersion(StreamInput in) throws IOException
      Throws:
      IOException

    • fromId

      public static IndexVersion fromId(int id)

    • writeVersion

      public static void writeVersion(IndexVersion version, StreamOutput out) throws IOException
      Throws:
      IOException

    • min

      public static IndexVersion min(IndexVersion version1, IndexVersion version2)
      Returns the minimum version of version1 and version2

    • max

      public static IndexVersion max(IndexVersion version1, IndexVersion version2)
      Returns the maximum version of version1 and version2

    • current

      public static IndexVersion current()
      Returns the most recent index version. This should be the index version with the highest id.

    • isLegacyIndexVersion

      public boolean isLegacyIndexVersion()

    • getMinimumCompatibleIndexVersion

      public static IndexVersion getMinimumCompatibleIndexVersion(int versionId)

    • toXContent

      public XContentBuilder toXContent(XContentBuilder builder, ToXContent.Params params) throws IOException
      Specified by:
      toXContent in interface ToXContent
      Throws:
      IOException

    • toString

      public String toString()
      Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.
      Specified by:
      toString in class Record
      Returns:
      a string representation of this object

    • equals

      public boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. Reference components are compared with Objects::equals(Object,Object); primitive components are compared with '=='.
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • hashCode

      public int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • id

      public int id()
      Returns the value of the id record component.
      Specified by:
      id in interface VersionId<IndexVersion>
      Returns:
      the value of the id record component

    • luceneVersion

      public org.apache.lucene.util.Version luceneVersion()
      Returns the value of the luceneVersion record component.
      Returns:
      the value of the luceneVersion record component