Version field type
editVersion field type
editThe 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.
Parameters for version fields
editThe following parameters are accepted by version
fields:
Metadata about the field. |
Limitations
editThis 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.
Synthetic _source
editSynthetic _source
is Generally Available only for TSDB indices
(indices that have index.mode
set to time_series
). For other indices
synthetic _source
is in technical preview. Features in technical preview may
be changed or removed in a future release. Elastic will work to fix
any issues, but features in technical preview are not subject to the support SLA
of official GA features.
version
fields support synthetic _source
so long as they don’t
declare copy_to
.
Synthetic source always sorts version
fields and removes duplicates. For example:
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"] }
Will become:
{ "versions": ["0.90.12", "1.3.4", "2.6.1", "8.0.0-beta1", "8.5.0"] }