[role="xpack"]
[testenv="basic"]
[[version]]
=== Version field type
++++
<titleabbrev>Version</titleabbrev>
++++

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
https://semver.org/[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

[source,console]
--------------------------------------------------
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
https://semver.org/[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.

[discrete]
[[version-params]]
==== Parameters for version fields

The following parameters are accepted by `version` fields:

[horizontal]

<<mapping-field-meta,`meta`>>::

    Metadata about the field.

[discrete]
==== Limitations

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.

