Link Search Menu Expand Document Documentation Menu
Documentation

Version field type

Introduced 3.2

The version field type is designed for indexing and querying version strings that follow Semantic Versioning (SemVer) specifications. This field type enables proper ordering and comparison of version strings such as 1.0.0, 2.1.0-alpha, 1.3.0+build.1, and others.

The version field type provides the following functionality:

  • Correctly parses semantic version strings with major, minor, and patch components
  • Handles pre-release identifiers like -alpha, -beta, and -rc.1
  • Accepts build metadata like +build.123 but ignores it for ordering (per SemVer specification)
  • Versions are sorted according to semantic versioning rules (for example, 1.0.0-alpha < 1.0.0-beta < 1.0.0)
  • Compatible with various query types, including range, term, terms, wildcard, prefix, and more

Version format

Version strings must follow the semantic versioning format:

<major>.<minor>.<patch>[-<pre-release>][+<build-metadata>]

The variables in the preceding format must be provided as follows.

Component Required/Optional Description Example
major, minor, patch Required Non-negative integers representing the core version number 1.2.3
pre-release Optional Alphanumeric identifiers separated by dots, indicating a pre-release version -alpha, -beta.1, -rc.2
build-metadata Optional Alphanumeric identifiers separated by dots, providing build information (ignored for ordering) +build.123, +20230815

Example mapping

Create an index with a version field:

PUT test_versions
{
  "mappings": {
    "properties": {
      "app": {
        "type": "keyword"
      },
      "version": {
        "type": "version"
      },
      "release_date": {
        "type": "date"
      },
      "description": {
        "type": "text"
      }
    }
  }
}

Indexing version data

Index documents with version fields:

POST test_versions/_bulk
{ "index": {} }
{ "app": "AlphaApp", "version": "1.0.0", "release_date": "2023-01-01", "description": "Initial release" }
{ "index": {} }
{ "app": "AlphaApp", "version": "1.0.1", "release_date": "2023-02-15", "description": "Bug fix release" }
{ "index": {} }
{ "app": "AlphaApp", "version": "1.1.0", "release_date": "2023-05-10", "description": "Minor feature update" }
{ "index": {} }
{ "app": "AlphaApp", "version": "2.0.0", "release_date": "2024-01-01", "description": "Major release" }
{ "index": {} }
{ "app": "BetaApp", "version": "0.9.0", "release_date": "2022-12-01", "description": "Beta release" }
{ "index": {} }
{ "app": "BetaApp", "version": "1.0.0-alpha", "release_date": "2023-03-01", "description": "Alpha pre-release" }
{ "index": {} }
{ "app": "BetaApp", "version": "1.0.0-alpha.1", "release_date": "2023-03-10", "description": "Alpha patch" }
{ "index": {} }
{ "app": "BetaApp", "version": "1.0.0-beta", "release_date": "2023-04-01", "description": "Beta pre-release" }
{ "index": {} }
{ "app": "BetaApp", "version": "1.0.0-rc.1", "release_date": "2023-04-15", "description": "Release candidate" }
{ "index": {} }
{ "app": "BetaApp", "version": "1.0.0+20230815", "release_date": "2023-08-15", "description": "Build metadata release" }

Querying version fields

The version field type supports various query types.

Term query

Find documents with a specific version:

GET test_versions/_search
{
  "query": {
    "term": { "version": "1.0.1" }
  }
}

Response

{
  "took": 5,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 1.0466295,
    "hits": [
      {
        "_index": "test_versions",
        "_id": "cSWNQpcBY7cEASBv3Vr1",
        "_score": 1.0466295,
        "_source": {
          "app": "AlphaApp",
          "version": "1.0.1",
          "release_date": "2023-02-15",
          "description": "Bug fix release"
        }
      }
    ]
  }
}

Range query

Find versions within a specific range:

GET test_versions/_search
{
  "query": {
    "range": {
      "version": { "gte": "2.0.0" }
    }
  }
}

Response

{
  "took": 3,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 1,
    "hits": [
      {
        "_index": "test_versions",
        "_id": "cyWNQpcBY7cEASBv3Vr1",
        "_score": 1,
        "_source": {
          "app": "AlphaApp",
          "version": "2.0.0",
          "release_date": "2024-01-01",
          "description": "Major release"
        }
      }
    ]
  }
}

Terms query

Find documents matching multiple specific versions:

GET test_versions/_search
{
  "query": {
    "terms": {
      "version": ["1.0.0", "1.0.0-alpha"]
    }
  }
}

Wildcard query

Find versions matching a pattern:

GET test_versions/_search
{
  "query": {
    "wildcard": {
      "version": "1.2.0-*"
    }
  }
}

Prefix query

Find versions with a specific prefix:

GET test_versions/_search
{
  "query": {
    "prefix": {
      "version": {
        "value": "1.0.0-"
      }
    }
  }
}

Sorting by version

To sort by version, provide the sort parameter in the request. Versions are sorted according to semantic versioning rules:

GET test_versions/_search
{
  "query": { "match_all": {} },
  "sort": [
    { "version": { "order": "asc" } }
  ]
}

This request returns documents sorted in version order, with pre-release versions appearing before their corresponding stable versions: 0.9.0, 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-beta, 1.0.0-rc.1, 1.0.0+20230815, 1.0.1, 1.1.0, 2.0.0.

Version comparison rules

The version field follows semantic versioning comparison rules:

  1. major, minor, patch: Compared numerically (1.2.3 < 1.2.4 < 1.3.0 < 2.0.0).
  2. Pre-release precedence: Pre-release versions have lower precedence than normal versions (1.0.0-alpha < 1.0.0).
  3. Pre-release comparison: When both versions are pre-releases, they are compared lexically by each dot-separated identifier (1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-beta).
  4. Build metadata ignored: Build metadata does not affect version precedence (1.0.0+build.1 equals 1.0.0+build.2 for sorting purposes).

Parameters

The version field type accepts the following optional parameters.

Parameter Description
null_value A value to be substituted for any explicit null values. Must be a valid version string. Defaults to null, which means null fields are treated as missing.

Example with null_value

PUT software_with_nulls
{
  "mappings": {
    "properties": {
      "version": {
        "type": "version",
        "null_value": "0.0.0"
      }
    }
  }
}

Limitations

  • Version strings must follow the semantic versioning format. Invalid version strings will cause indexing to fail.
  • Build metadata is accepted but ignored during comparisons and sorting.
  • The field does not support advanced version range specifications like ^1.2.3 or ~1.2.0; use range queries instead.
350 characters left

Have a question? .

Want to contribute? or .