version 필드 타입

version 필드 타입

version 필드 타입은 Semantic Versioning(SemVer) 규격을 따르는 버전 문자열을 인덱싱하고 쿼리하기 위한 필드 타입이에요. 1.0.0, 2.1.0-alpha, 1.3.0+build.1 같은 버전 문자열을 올바르게 정렬하고 비교할 수 있습니다.

출처: 문서

본문

3.2 버전에서 도입되었어요.

version 필드 타입은 Semantic Versioning(SemVer) 규격을 따르는 버전 문자열을 인덱싱하고 쿼리하기 위해 설계된 필드 타입이에요. 이 필드 타입을 사용하면 1.0.0, 2.1.0-alpha, 1.3.0+build.1 같은 버전 문자열을 올바르게 정렬하고 비교할 수 있어요.

version 필드 타입이 제공하는 기능은 다음과 같아요.

  • major, minor, patch 구성 요소를 가진 시맨틱 버전 문자열을 올바르게 파싱해요.
  • -alpha, -beta, -rc.1 같은 사전 릴리스 식별자를 처리해요.
  • +build.123 같은 빌드 메타데이터를 수용하되 정렬에는 무시해요(SemVer 규격에 따라).
  • 버전을 시맨틱 버전 규칙에 따라 정렬해요(예: 1.0.0-alpha < 1.0.0-beta < 1.0.0).
  • range, term, terms, wildcard, prefix 등 다양한 쿼리 타입과 호환돼요.

버전 형식 (Version format)

버전 문자열은 시맨틱 버전 형식을 따라야 해요.

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

위 형식의 변수들은 다음과 같이 제공해야 해요.

구성 요소 필수/선택 설명 예시
major, minor, patch 필수 핵심 버전 번호를 나타내는 음수가 아닌 정수 1.2.3
pre-release 선택 점으로 구분된 영숫자 식별자로, 사전 릴리스 버전을 나타냄 -alpha, -beta.1, -rc.2
build-metadata 선택 점으로 구분된 영숫자 식별자로, 빌드 정보를 제공함(정렬에는 무시됨) +build.123, +20240815

예시 매핑 (Example mapping)

version 필드가 있는 인덱스를 생성하세요.

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

버전 데이터 인덱싱 (Indexing version data)

version 필드가 있는 문서를 인덱싱하세요.

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+20240815", "release_date": "2023-08-15", "description": "Build metadata release" }

버전 필드 쿼리하기 (Querying version fields)

version 필드 타입은 다양한 쿼리 타입을 지원해요.

Term 쿼리

특정 버전이 있는 문서를 찾으세요.

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

응답

{
  "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 쿼리

특정 범위 안에 있는 버전을 찾으세요.

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

응답

{
  "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 쿼리

여러 특정 버전과 일치하는 문서를 찾으세요.

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

Wildcard 쿼리

패턴과 일치하는 버전을 찾으세요.

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

Prefix 쿼리

특정 접두사를 가진 버전을 찾으세요.

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

버전으로 정렬하기 (Sorting by version)

버전으로 정렬하려면 요청에 sort 파라미터를 제공하세요. 버전은 시맨틱 버전 규칙에 따라 정렬돼요.

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

이 요청은 문서를 버전 순서로 반환해요. 사전 릴리스 버전이 해당 안정 버전보다 먼저 옵니다: 0.9.0, 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-beta, 1.0.0-rc.1, 1.0.0+20240815, 1.0.1, 1.1.0, 2.0.0.

버전 비교 규칙 (Version comparison rules)

version 필드는 시맨틱 버전 비교 규칙을 따릅니다.

  • major, minor, patch: 숫자로 비교해요(1.2.3 < 1.2.4 < 1.3.0 < 2.0.0).
  • 사전 릴리스 우선순위: 사전 릴리스 버전은 일반 버전보다 우선순위가 낮아요(1.0.0-alpha < 1.0.0).
  • 사전 릴리스 비교: 두 버전 모두 사전 릴리스일 때는 점으로 구분된 각 식별자를 사전순으로 비교해요(1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-beta).
  • 빌드 메타데이터 무시: 빌드 메타데이터는 버전 우선순위에 영향을 주지 않아요(정렬 목적으로는 1.0.0+build.1이 1.0.0+build.2와 동일해요).

제한 사항 (Limitations)

  • 버전 문자열은 시맨틱 버전 형식을 따라야 해요. 유효하지 않은 버전 문자열은 인덱싱을 실패시켜요.
  • 빌드 메타데이터는 수용되지만 비교와 정렬에서는 무시돼요.
  • 이 필드는 ^1.2.3이나 ~1.2.0 같은 고급 버전 범위 지정을 지원하지 않아요. 대신 range 쿼리를 사용하세요.

더 알아보기 (Learn more)