Star-tree 필드 타입

star-tree 인덱스는 집계를 사전 계산해 집계 쿼리의 성능을 가속화해요. star-tree 인덱스가 인덱스 매핑의 일부로 구성되면 데이터가 실시간으로 수집되면서 star-tree 인덱스가 생성·유지 관리돼요.

쿼리된 필드가 star-tree 인덱스 차원 필드의 일부이고 집계가 star-tree 인덱스 메트릭 필드에 수행되는 경우, OpenSearch는 자동으로 star-tree 인덱스를 사용해 집계를 최적화해요. 쿼리 구문이나 요청 파라미터의 변경은 필요하지 않아요.

자세한 내용은 Star-tree index 문서를 참고하세요.

출처: 문서

본문

전제 조건 (Prerequisites)

star-tree 인덱스를 사용하려면 Enabling a star-tree index의 지침을 따르세요.

예시 (Examples)

다음 예시들은 star-tree 인덱스를 사용하는 방법을 보여줘요.

Star-tree 인덱스 매핑

mappings의 composite 섹션에 star-tree 인덱스 매핑을 정의해요.

다음 예시 API 요청은 request_aggs라는 해당 star-tree 인덱스를 만들어요. request_size와 latency 필드에 대한 메트릭 집계를 port와 status 필드에 대한 쿼리로 계산하려면 다음 매핑을 구성해요.

PUT logs
{
  "settings": {
    "index.number_of_shards": 1,
    "index.number_of_replicas": 0,
    "index.composite_index": true,
    "index.append_only.enabled": true
  },
  "mappings": {
    "composite": {
      "request_aggs": {
        "type": "star_tree",
        "config": {
          "max_leaf_docs": 10000,
          "skip_star_node_creation_for_dimensions": [
            "port"
          ],
          "date_dimension" : {
            "name": "@timestamp",
            "calendar_intervals": [
              "month",
              "day"
            ]
          },
          "ordered_dimensions": [
            {
              "name": "status"
            },
            {
              "name": "port"
            },
            {
              "name": "method"
            }
          ],
          "metrics": [
            {
              "name": "request_size",
              "stats": [
                "sum",
                "value_count",
                "min",
                "max"
              ]
            },
            {
              "name": "latency",
              "stats": [
                "sum",
                "value_count",
                "min",
                "max"
              ]
            }
          ]
        }
      }
    },
    "properties": {
      "@timestamp": {
        "format": "strict_date_optional_time||epoch_second",
        "type": "date"
      },
      "status": {
        "type": "integer"
      },
      "port": {
        "type": "integer"
      },
      "request_size": {
        "type": "integer"
      },
      "method" : {
        "type": "keyword"
      },
      "latency": {
        "type": "scaled_float",
        "scaling_factor": 10
      }
    }
  }
}

Star-tree 인덱스 구성 옵션

mappings 섹션의 다음 구성 옵션을 사용해 star-tree 구현을 사용자 지정할 수 있어요. 이 옵션들은 재색인(reindex) 없이는 수정할 수 없어요.

파라미터	설명
`ordered_dimensions`	star-tree 인덱스에서 메트릭이 집계될 기준이 되는 필드 목록이에요. 필수예요.
`date_dimension`	date dimension이 제공되면 star-tree 인덱스에서 메트릭이 집계될 기준이 되는 `ordered_dimensions`가 그 아래에 추가돼요. 선택 사항이에요.
`metrics`	집계를 수행하는 데 필요한 메트릭 필드 목록이에요. 필수예요.
`max_leaf_docs`	리프 노드가 가리킬 수 있는 star-tree 문서의 최대 수예요. 최대 문서 수에 도달하면 `ordered_dimension`의 다음 필드(있는 경우)의 고유 값에 따라 자식 노드가 생성돼요. 기본값은 10000이에요. 값이 낮을수록 저장 공간을 더 사용하지만 쿼리 성능은 더 빨라져요. 반대로 값이 높을수록 저장 공간은 덜 사용하지만 쿼리 성능은 더 느려져요. 자세한 내용은 Star-tree indexing structure를 참고하세요.
`skip_star_node_creation_for_dimensions`	star-tree 인덱스가 star 노드 생성을 건너뛸 차원 목록이에요. `true`일 때 쿼리 성능을 희생하는 대신 저장 크기를 줄여요. 기본값은 `false`예요. star 노드에 대한 자세한 내용은 Star-tree indexing structure를 참고하세요.

Ordered dimensions

ordered_dimensions 파라미터는 star-tree 인덱스에서 메트릭이 집계될 기준이 되는 필드를 포함해요. 쿼리의 모든 필드가 ordered_dimensions의 일부일 때만 star-tree 인덱스가 쿼리에 선택돼요.

ordered_dimesions 파라미터를 사용할 때는 다음 모범 사례를 따르세요.

차원의 순서가 중요해요. 효율적인 저장과 쿼리 프루닝을 위해 차원을 높은 카디널리티에서 낮은 카디널리티 순서로 정의할 수 있어요.
고카디널리티 필드를 차원으로 사용하지 마세요. 고카디널리티 필드는 저장 공간, 색인 처리량, 쿼리 성능에 부정적인 영향을 줘요.
star-tree 인덱스당 최소 2개, 최대 10개의 차원이 지원돼요.

ordered_dimensions 파라미터는 다음 필드 타입을 지원해요.

unsigned_long과 scaled_float을 제외한 모든 숫자 필드 타입
keyword
object
ip

ordered_dimensions 파라미터는 다음 속성을 지원해요.

파라미터	필수/선택	설명
`name`	필수	필드의 이름이에요. 필드 이름은 인덱스 매핑의 일부로서 properties 섹션에 있어야 해요. 관련 필드에 대해 `doc_values` 설정이 활성화되어 있는지 확인하세요.

Date dimension

date_dimension은 하나의 Date 필드를 지원하며, 일반적으로 고카디널리티를 가지므로 ordered dimensions 위에 항상 첫 번째 차원으로 배치돼요.

date_dimension은 다음 calendar interval 중 최대 3개를 지원해요.

year (of era)
quarter (of year)
month (of year)
week (of week-based year)
day (of month)
hour (of day)
half-hour (of day)
quarter-hour (of day)
minute (of hour)
second (of minute)

date 필드의 모든 값은 제공된 calendar interval과 연관된 세분성(granularity)에 따라 반올림돼요. 예를 들어:

기본 calendar_intervals는 minute과 half-hour예요.
쿼리 중에는 가장 가까운 세분화 간격이 자동으로 선택돼요. 예를 들어 calendar_intervals로 hour와 minute을 구성했고 쿼리가 월 단위 date histogram이라면, 쿼리가 최적화된 방식으로 결과를 계산하도록 hour 간격이 자동으로 선택돼요.
시간대 기반 쿼리를 지원하기 위해 :30은 half-hour 간격을, :15는 quarter-hour 간격을 나타내요.

Metrics

집계를 수행해야 하는 모든 메트릭 필드를 구성해요. 메트릭은 star-tree 인덱스 구성의 필수 부분이에요.

메트릭을 사용할 때는 다음 모범 사례를 따르세요.

현재 메트릭이 지원하는 필드는 unsigned_long을 제외한 모든 숫자 필드 타입이에요. 자세한 내용은 GitHub issue #15231을 참고하세요.
지원되는 메트릭 집계는 Min, Max, Sum, Avg, Value_count예요. Avg는 Sum과 Value_count에 기반한 파생 메트릭이며 쿼리가 실행될 때 색인되지 않아요. 나머지 기본 메트릭들은 색인돼요.
star-tree 인덱스당 최대 100개의 기본 메트릭이 지원돼요.
각 필드에 대해 Min, Max, Sum, Value_count를 메트릭으로 정의하면 다음 예시처럼 최대 25개의 필드를 구성할 수 있어요.

{
  "metrics": [
    {
      "name": "field1",
      "stats": [
        "sum",
        "value_count",
        "min",
        "max"
      ],
      ...,
      ...,
      "name": "field25",
      "stats": [
        "sum",
        "value_count",
        "min",
        "max"
      ]
    }
  ]
}

속성 (Properties)

metrics 파라미터는 다음 속성을 지원해요.

파라미터	필수/선택	설명
`name`	필수	필드의 이름이에요. 필드 이름은 인덱스 매핑의 일부로서 properties 섹션에 있어야 해요. 관련 필드에 대해 `doc_values` 설정이 활성화되어 있는지 확인하세요.
`stats`	선택	각 필드에 대해 계산되는 메트릭 집계 목록이에요. Min, Max, Sum, Avg, Value Count 중에서 선택할 수 있어요. 기본값은 Sum과 Value_count예요. Avg는 파생 메트릭 통계로, Sum과 Value_Count가 메트릭 stats의 일부로 있으면 쿼리에서 자동으로 지원돼요.

지원 쿼리와 집계

지원 쿼리와 집계에 대한 자세한 내용은 star-tree 인덱스의 지원 쿼리와 집계를 참고하세요.

다음 단계 (Next steps)

Star-tree index

더 알아보기 (Learn more)

OpenSearch 공식 문서