diff --git a/_mappings/supported-field-types/index.md b/_mappings/supported-field-types/index.md index 9f361acf9b..7a7cdfe004 100644 --- a/_mappings/supported-field-types/index.md +++ b/_mappings/supported-field-types/index.md @@ -31,6 +31,7 @@ You can specify data types for your fields when creating a mapping. The followin | [`wildcard`]({{site.url}}{{site.baseurl}}/mappings/supported-field-types/wildcard/) | Enables efficient substring and regex matching. | | [`token_count`]({{site.url}}{{site.baseurl}}/mappings/supported-field-types/token-count/) | Stores the number of tokens after analysis. | | [`constant_keyword`]({{site.url}}{{site.baseurl}}/mappings/supported-field-types/constant-keyword/) | Uses the same value for all documents in the index. | +| [`version`]({{site.url}}{{site.baseurl}}/mappings/supported-field-types/version/) | A semantic version string that follows semantic versioning specification. | ## Numeric field types diff --git a/_mappings/supported-field-types/version.md b/_mappings/supported-field-types/version.md new file mode 100644 index 0000000000..4960fa97bd --- /dev/null +++ b/_mappings/supported-field-types/version.md @@ -0,0 +1,307 @@ +--- +layout: default +title: Version +parent: Supported field types +nav_order: 75 +redirect_from: + - /opensearch/supported-field-types/version/ + - /field-types/supported-field-types/version/ +--- + +# Version field type +**Introduced 3.2** +{: .label .label-purple } + +The `version` field type is designed for indexing and querying version strings that follow [Semantic Versioning (SemVer)](https://semver.org/) 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`, `-rc.1` +- Accepts build metadata like `+build.123` but ignores it for ordering (per SemVer specification) +- Versions are sorted according to semantic versioning rules (e.g., `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: + +``` +..[-][+] +``` + +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: + +```json +PUT test_versions +{ + "mappings": { + "properties": { + "app": { + "type": "keyword" + }, + "version": { + "type": "version" + }, + "release_date": { + "type": "date" + }, + "description": { + "type": "text" + } + } + } +} +``` +{% include copy-curl.html %} + + +## Indexing version data + +Index documents with version fields: + +```json +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" } +``` +{% include copy-curl.html %} + +## Querying version fields + +The version field type supports various query types. + +### Term query + +Find documents with a specific version: + +```json +GET test_versions/_search +{ + "query": { + "term": { "version": "1.0.1" } + } +} +``` +{% include copy-curl.html %} + +#### Response + +```json +{ + "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: + +```json +GET test_versions/_search +{ + "query": { + "range": { + "version": { "gte": "2.0.0" } + } + } +} +``` +{% include copy-curl.html %} + +#### Response + +```json +{ + "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: + +```json +GET test_versions/_search +{ + "query": { + "terms": { + "version": ["1.0.0", "1.0.0-alpha"] + } + } +} +``` +{% include copy-curl.html %} + +### Wildcard query + +Find versions matching a pattern: + +```json +GET test_versions/_search +{ + "query": { + "wildcard": { + "version": "1.2.0-*" + } + } +} +``` +{% include copy-curl.html %} + +### Prefix query + +Find versions with a specific prefix: + +```json +GET test_versions/_search +{ + "query": { + "prefix": { + "version": { + "value": "1.0.0-" + } + } + } +} +``` +{% include copy-curl.html %} + +## Sorting by version + +To sort by version, provide the `sort` parameter in the request. Versions are sorted according to semantic versioning rules: + +```json +GET test_versions/_search +{ + "query": { "match_all": {} }, + "sort": [ + { "version": { "order": "asc" } } + ] +} +``` +{% include copy-curl.html %} + +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 + +```json +PUT software_with_nulls +{ + "mappings": { + "properties": { + "version": { + "type": "version", + "null_value": "0.0.0" + } + } + } +} +``` +{% include copy-curl.html %} + +## Limitations + +- Version strings must follow the semantic versioning format. Invalid version strings will cause indexing to fail. +- Build metadata (part after `+`) 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]({{site.url}}{{site.baseurl}}/query-dsl/term/range/) instead.