Rare terms 집계
Rare terms 집계
rare_terms 집계는 데이터셋에서 드물게 나타나는 term을 식별하는 버킷 집계예요. 가장 흔한 term을 찾는 terms 집계와 달리, rare_terms 집계는 가장 낮은 빈도로 나타나는 term을 찾아요. rare_terms 집계는 이상 탐지, 긴 꼬리(long-tail) 분석, 예외 보고 같은 애플리케이션에 적합해요.
반환된 값을 오름차순 개수로 정렬("order": {"count": "asc"})하여 terms로 드문 값을 검색할 수도 있어요. 하지만 여러 샤드가 관련될 때 부정확한 결과를 초래할 수 있으므로 이 방법은 권장하지 않아요. 전역적으로 드문 term은 개별 샤드마다 드문 것처럼 보이지 않거나 일부 샤드가 반환하는 가장 빈도가 낮은 결과에 완전히 없을 수도 있어요. 반대로 한 샤드에서 드물게 나타나는 term이 다른 샤드에서는 흔할 수도 있어요. 두 시나리오 모두에서 희귀 term이 샤드 수준 집계 중에 누락되어 전체 결과가 부정확해질 수 있어요. terms 집계 대신, 이런 경우를 더 정확하게 처리하도록 특별히 설계된 rare_terms 집계를 사용하는 것을 권장해요.
출처: 문서
본문
근사 결과 (Approximated results)
rare_terms 집계에 대한 정확한 결과를 계산하려면 모든 샤드의 값에 대한 완전한 맵을 컴파일해야 하므로 과도한 런타임 메모리가 필요해요. 그래서 rare_terms 집계 결과는 근사값이에요.
rare_terms 계산에서 대부분의 오류는 거짓 음성(false negatives) 또는 "누락된(missed)" 값이며, 이는 집계의 감지 테스트 민감도를 결정해요. rare_terms 집계는 적절한 민감도와 수용 가능한 메모리 사용의 균형을 이루기 위해 CuckooFilter 알고리즘을 사용해요. CuckooFilter 알고리즘에 대한 설명은 이 논문을 참고하세요.
민감도 제어 (Controlling sensitivity)
rare_terms 집계 알고리즘의 민감도 오류는 누락된 희귀 값의 비율, 즉 거짓 음성/대상 값으로 측정돼요. 예를 들어 집계가 희귀 값 5,000개가 있는 데이터셋에서 100개의 희귀 값을 누락하면 민감도 오류는 100/5000 = 0.02, 즉 2%예요.
rare_terms 집계의 precision 파라미터를 조정해 민감도와 메모리 사용 사이의 균형을 제어할 수 있어요.
다음 요인도 민감도-메모리 균형에 영향을 줘요:
- 고유 값의 총 개수
- 데이터셋에서 희귀 항목의 비율
다음 지침은 어떤 precision 값을 사용할지 결정하는 데 도움이 돼요.
메모리 사용 계산 (Calculating memory use)
런타임 메모리 사용은 절대적인 용어로, 일반적으로 RAM의 MB 단위로 설명돼요.
메모리 사용은 고유 항목 수에 따라 선형적으로 증가해요. 선형 배율 계수는 precision 파라미터에 따라 백만 개의 고유 값당 대략 1.0~2.5 MB로 다양해요. 기본 precision인 0.001의 경우 메모리 비용은 백만 고유 값당 약 1.75 MB예요.
민감도 오류 관리 (Managing sensitivity error)
민감도 오류는 고유 값의 총 개수에 따라 선형적으로 증가해요. 고유 값 수 추정에 대한 정보는 Cardinality aggregation을 참고하세요.
민감도 오류는 1,000만~2,000만 개의 고유 값이 있는 데이터셋에서도 기본 precision 기준으로 2.5%를 거의 초과하지 않아요. precision 0.00001의 경우 민감도 오류는 0.6%를 거의 넘지 않아요. 그러나 희귀 값의 절대 개수가 매우 적으면 오류율의 변동이 커질 수 있어요(희귀 값이 두 개뿐이라면 하나를 누락하면 50% 오류율이 됩니다).
다른 집계와의 호환성 (Compatibility with other aggregations)
rare_terms 집계는 breadth-first 수집 모드를 사용하며, 일부 하위 집계와 중첩 구성에서 depth-first 수집 모드를 요구하는 집계와는 호환되지 않아요.
OpenSearch에서 breadth-first 검색에 대한 자세한 내용은 Collect mode를 참고하세요.
파라미터 (Parameters)
rare_terms 집계는 다음 파라미터를 받아요.
| 파라미터 | 필수/선택 | 데이터 타입 | 설명 |
|---|---|---|---|
| field | 필수 | String | 희귀 term을 분석할 필드. 숫자 타입 또는 keyword 매핑이 있는 text 타입이어야 해요. |
| max_doc_count | 선택 | Integer | term이 희귀한 것으로 간주되기 위해 필요한 최대 문서 수. 기본값은 1이에요. 최대는 100이에요. |
| precision | 선택 | Integer | 희귀 term을 식별하는 데 사용되는 알고리즘의 정밀도를 제어해요. 값이 높을수록 더 정확한 결과를 제공하지만 더 많은 메모리를 소비해요. 기본값은 0.001이에요. 최소(가장 정밀, 허용 가능)는 0.00001이에요. |
| include | 선택 | Array/regex | 결과에 포함할 term. 정규 표현식 또는 값의 배열일 수 있어요. |
| exclude | 선택 | Array/regex | 결과에서 제외할 term. 정규 표현식 또는 값의 배열일 수 있어요. |
| missing | 선택 | String | 집계하는 필드에 값이 없는 문서에 사용할 값. |
예제 (Example)
다음 요청은 OpenSearch Dashboards 샘플 항공편 데이터에서 정확히 한 번만 나타나는 모든 목적지 공항 코드를 반환해요:
GET /opensearch_dashboards_sample_data_flights/_search
{
"size": 0,
"aggs": {
"rare_destination": {
"rare_terms": {
"field": "DestAirportID",
"max_doc_count": 1
}
}
}
}
예제 응답 (Example response)
응답은 데이터에서 정확히 한 번만 나타나는 기준을 충족하는 공항이 두 개 있음을 보여줘요:
{
"took": 12,
"timed_out": false,
"_shards": {
"total": 1,
"successful": 1,
"skipped": 0,
"failed": 0
},
"hits": {
"total": {
"value": 10000,
"relation": "gte"
},
"max_score": null,
"hits": []
},
"aggregations": {
"rare_destination": {
"buckets": [
{
"key": "ADL",
"doc_count": 1
},
{
"key": "BUF",
"doc_count": 1
}
]
}
}
}
문서 개수 제한 (Document count limit)
max_doc_count 파라미터를 사용해 rare_terms 집계가 반환할 수 있는 최대 문서 수를 지정해요. rare_terms가 반환하는 term 수에는 제한이 없으므로, max_doc_count 값이 크면 매우 큰 결과 집합을 반환할 수 있어요. 그래서 100이 허용 가능한 최대 max_doc_count예요.
다음 요청은 OpenSearch Dashboards 샘플 항공편 데이터에서 최대 두 번까지 나타나는 모든 목적지 공항 코드를 반환해요:
GET /opensearch_dashboards_sample_data_flights/_search
{
"size": 0,
"aggs": {
"rare_destination": {
"rare_terms": {
"field": "DestAirportID",
"max_doc_count": 2
}
}
}
}
응답은 이전 예제의 두 개를 포함해 2개 이하의 문서에 나타나는 기준을 충족하는 7개의 목적지 공항 코드가 있음을 보여줘요:
{
"took": 6,
"timed_out": false,
"_shards": {
"total": 1,
"successful": 1,
"skipped": 0,
"failed": 0
},
"hits": {
"total": {
"value": 10000,
"relation": "gte"
},
"max_score": null,
"hits": []
},
"aggregations": {
"rare_destination": {
"buckets": [
{
"key": "ADL",
"doc_count": 1
},
{
"key": "BUF",
"doc_count": 1
},
{
"key": "ABQ",
"doc_count": 2
},
{
"key": "AUH",
"doc_count": 2
},
{
"key": "BIL",
"doc_count": 2
},
{
"key": "BWI",
"doc_count": 2
},
{
"key": "MAD",
"doc_count": 2
}
]
}
}
}
필터링 (Filtering: include and exclude)
include와 exclude 파라미터를 사용해 rare_terms 집계가 반환하는 값을 필터링해요. 두 파라미터 모두 같은 집계에 포함될 수 있어요. exclude 필터가 우선하며, 명시적으로 포함되었는지와 무관하게 제외된 값은 결과에서 제거돼요.
include와 exclude의 인자는 문자열 리터럴을 포함한 정규 표현식(regex) 또는 배열일 수 있어요. regex와 배열 인자를 섞으면 오류가 발생해요. 예를 들어 다음 조합은 허용되지 않아요:
"rare_terms": {
"field": "DestAirportID",
"max_doc_count": 2,
"exclude": ["ABQ", "AUH"],
"include": "A.*"
}
예제: 필터링 (Example: Filtering)
다음 예제는 이전 예제를 수정해 "A"로 시작하는 모든 공항 코드를 포함하지만 "ABQ" 공항 코드는 제외해요:
GET /opensearch_dashboards_sample_data_flights/_search
{
"size": 0,
"aggs": {
"rare_destination": {
"rare_terms": {
"field": "DestAirportID",
"max_doc_count": 2,
"include": "A.*",
"exclude": "ABQ"
}
}
}
}
응답은 필터링 요구 사항을 충족하는 두 개의 공항 코드를 보여줘요:
{
"took": 4,
"timed_out": false,
"_shards": {
"total": 1,
"successful": 1,
"skipped": 0,
"failed": 0
},
"hits": {
"total": {
"value": 10000,
"relation": "gte"
},
"max_score": null,
"hits": []
},
"aggregations": {
"rare_destination": {
"buckets": [
{
"key": "ADL",
"doc_count": 1
},
{
"key": "AUH",
"doc_count": 2
}
]
}
}
}
예제: 배열 입력으로 필터링 (Example: Filtering with array input)
다음 예제는 OpenSearch Dashboards 샘플 항공편 데이터에서 최대 두 번까지 나타나는 모든 목적지 공항 코드를 반환하지만 제외할 공항 코드 배열을 지정해요:
GET /opensearch_dashboards_sample_data_flights/_search
{
"size": 0,
"aggs": {
"rare_destination": {
"rare_terms": {
"field": "DestAirportID",
"max_doc_count": 2,
"exclude": ["ABQ", "BIL", "MAD"]
}
}
}
}
응답은 제외된 공항 코드를 생략해요:
{
"took": 6,
"timed_out": false,
"_shards": {
"total": 1,
"successful": 1,
"skipped": 0,
"failed": 0
},
"hits": {
"total": {
"value": 10000,
"relation": "gte"
},
"max_score": null,
"hits": []
},
"aggregations": {
"rare_destination": {
"buckets": [
{
"key": "ADL",
"doc_count": 1
},
{
"key": "BUF",
"doc_count": 1
},
{
"key": "AUH",
"doc_count": 2
},
{
"key": "BWI",
"doc_count": 2
}
]
}
}
}