Version field type

The version field type is a specialization of the keyword field for handling software version values and to support specialized precedence rules for them. Precedence is defined following the rules outlined by Semantic Versioning, which for example means that major, minor and patch version parts are sorted numerically (i.e. "2.1.0" < "2.4.1" < "2.11.2") and pre-release versions are sorted before release versions (i.e. "1.0.0-alpha" < "1.0.0").

You index a version field as follows

response = client.indices.create(
  index: 'my-index-000001',
  body: {
    mappings: {
      properties: {
        my_version: {
          type: 'version'
        }
      }
    }
  }
)
puts response

PUT my-index-000001
{
  "mappings": {
    "properties": {
      "my_version": {
        "type": "version"
      }
    }
  }
}

The field offers the same search capabilities as a regular keyword field. It can e.g. be searched for exact matches using match or term queries and supports prefix and wildcard searches. The main benefit is that range queries will honor Semver ordering, so a range query between "1.0.0" and "1.5.0" will include versions of "1.2.3" but not "1.11.2" for example. Note that this would be different when using a regular keyword field for indexing where ordering is alphabetical.

Software versions are expected to follow the Semantic Versioning rules schema and precedence rules with the notable exception that more or less than three main version identifiers are allowed (i.e. "1.2" or "1.2.3.4" qualify as valid versions while they wouldn’t under strict Semver rules). Version strings that are not valid under the Semver definition (e.g. "1.2.alpha.4") can still be indexed and retrieved as exact matches, however they will all appear after any valid version with regular alphabetical ordering. The empty String "" is considered invalid and sorted after all valid versions, but before other invalid ones.

The following parameters are accepted by version fields:

This field type isn’t optimized for heavy wildcard, regex or fuzzy searches. While those type of queries work in this field, you should consider using a regular keyword field if you strongly rely on these kind of queries.

response = client.indices.create(
  index: 'idx',
  body: {
    mappings: {
      _source: {
        mode: 'synthetic'
      },
      properties: {
        versions: {
          type: 'version'
        }
      }
    }
  }
)
puts response

response = client.index(
  index: 'idx',
  id: 1,
  body: {
    versions: [
      '8.0.0-beta1',
      '8.5.0',
      '0.90.12',
      '2.6.1',
      '1.3.4',
      '1.3.4'
    ]
  }
)
puts response

PUT idx
{
  "mappings": {
    "_source": { "mode": "synthetic" },
    "properties": {
      "versions": { "type": "version" }
    }
  }
}
PUT idx/_doc/1
{
  "versions": ["8.0.0-beta1", "8.5.0", "0.90.12", "2.6.1", "1.3.4", "1.3.4"]
}

{
  "versions": ["0.90.12", "1.3.4", "2.6.1", "8.0.0-beta1", "8.5.0"]
}