8장. Aggregations — 검색 엔진 위의 분석 엔진

검색이 "어느 문서가 맞는가"를 묻는다면, 집계는 "이 문서들의 분포와 추세는 어떠한가"를 답합니다. Kibana 대시보드의 거의 모든 차트가 이 위에 서 있습니다 — 그리고 그 숫자, 가끔은 근사치입니다.

8.1 집계의 세 종류와 트리 구조

핵심은 bucket 안에 자식 집계를 중첩해 트리를 만들 수 있다는 점입니다. SQL의 GROUP BY + 집계 함수 + 윈도우 함수가 하나의 JSON 트리로 표현된다고 생각하면 됩니다.

8.2 Metric — 숫자를 뽑는 집계

GET /sales/_search
{
  "size": 0,
  "aggs": {
    "avg_price":     { "avg": { "field": "price" } },
    "total_revenue": { "sum": { "field": "price" } },
    "price_stats":   { "stats": { "field": "price" } },   // count·min·max·avg·sum 한 번에
    "unique_users":  { "cardinality": { "field": "user_id" } }
  }
}

percentiles(TDigest 기반 근사)로 p50/p95/p99 지연시간을, top_hits로 각 버킷의 대표 문서를 뽑을 수 있습니다. top_hits는 SQL의 ROW_NUMBER() OVER (PARTITION BY …)에 가장 가까운 도구입니다.

8.3 Bucket — 문서를 그룹으로 나누는 집계

가장 자주 쓰는 둘만 확실히 잡으면 됩니다: 그룹핑의 terms, 시계열의 date_histogram.

// 브랜드별 Top 10 — 매출순 정렬은 자식 metric으로
"by_brand": {
  "terms": {
    "field": "brand",
    "size":  10,
    "order": { "total_revenue": "desc" }
  },
  "aggs": {
    "total_revenue": { "sum": { "field": "price" } }
  }
}

// 일별 매출 그래프 — 시계열의 표준 형태
"sales_over_time": {
  "date_histogram": {
    "field": "ordered_at",
    "calendar_interval": "1d",
    "time_zone": "Asia/Seoul",       // 기본 UTC! 반드시 명시
    "min_doc_count": 0,               // 데이터 없는 날도 0으로
    "extended_bounds": { "min": "2026-01-01", "max": "2026-06-30" }
  }
}

그 밖에: range(사용자 정의 구간), histogram(숫자 균등 구간), filters(이름 붙은 필터 버킷), nested(nested 필드 진입용) 등이 있습니다.

8.4 terms 집계는 왜 부정확할 수 있는가 — 분산의 대가

공식 문서가 직접 경고합니다: "the doc_count values for a terms aggregation may be approximate." ES에서 가장 자주 오해되는 부분입니다. 원인은 데이터가 여러 샤드에 분산되어 있다는 사실 그 자체입니다.

1. 각 샤드는 자기 데이터에서 상위 shard_size개 버킷만 추려 coordinating node로 보냅니다
2. coordinating node가 부분 결과를 합산해 최종 상위 size개를 결정합니다

문제는 어떤 term이 샤드마다 순위가 다를 때 발생합니다. 애니메이션으로 봅시다.

"by_brand": {
  "terms": {
    "field":      "brand",
    "size":       10,
    "shard_size": 100,                 // 기본 size*1.5+10 → 키우면 정확도↑
    "show_term_doc_count_error": true   // 버킷별 오차 상한 포함
  }
}
// 응답: "doc_count_error_upper_bound": 14  ← 0이면 신뢰 가능

8.5 composite — 버킷의 페이지네이션

terms는 모든 버킷을 한 번에 계산해 반환하므로, 고유값이 수십만 개인 필드(예: user_id)에 쓰면 메모리가 폭발합니다. 이때의 답이 composite — 정렬된 버킷을 after_key 커서로 페이지 단위로 순회합니다.

제약도 있습니다: composite 안에서는 자식 metric 기준 order를 쓸 수 없고(키 순서 고정), 한 요청에 composite 하나만 넣을 수 있습니다.

8.6 Pipeline — 시계열 분석의 마무리

pipeline 집계는 다른 집계의 결과를 입력으로 받습니다. 시계열 대시보드의 "전일 대비 증감", "7일 이동평균"이 전부 이것입니다. 실전 예제로 마무리합니다.

GET /sales/_search
{
  "size": 0,
  "track_total_hits": false,
  "query": {
    "bool": {
      "filter": [                              // 7장: 점수 불필요 → filter (캐시)
        { "term":  { "status": "completed" } },
        { "range": { "ordered_at": { "gte": "now-90d/d" } } }
      ]
    }
  },
  "aggs": {
    "daily_sales": {
      "date_histogram": {
        "field": "ordered_at",
        "calendar_interval": "1d",
        "time_zone": "Asia/Seoul",
        "min_doc_count": 0
      },
      "aggs": {
        "revenue": { "sum": { "field": "price" } },
        "7d_moving_avg": {
          "moving_fn": {                       // moving_avg는 deprecated
            "buckets_path": "revenue",
            "window": 7,
            "script": "MovingFunctions.unweightedAvg(values)"
          }
        },
        "revenue_diff": {
          "derivative": { "buckets_path": "revenue" }   // 전일 대비 증감
        }
      }
    }
  }
}

✍️ 이해도 체크