[zipdoki]

Summary

Introduce top-K aggregation metadata on Group and expose a read endpoint listing tables that declare one.

A Group can now carry an Aggregations block. Today only topk is defined; the schema is designed so future aggregation kinds (e.g. HLL) can land as sibling fields without restructuring the payload.

GET /graph/v3/aggregations returns a flat list of (type, database, table) tuples for every table that declares an aggregation, filterable by ?type=. The aggregate/mutate flow that consumes this metadata is out of scope for this PR and will land separately.

Metadata example

A group inside a label creation payload:

{
  "groups": [
    {
      "group": "purchased_count",
      "type": "COUNT",
      "fields": [{"name": "_target"}],
      "directionType": "OUT",
      "aggregations": {
        "topk": [
          {
            "topk": "top_purchased",
            "entity": "_source",
            "ranges": "_target:eq:{_target}",
            "dimension": "_target",
            "refreshAfterMillis": 31536000000,
            "rank": "commerce.purchases__topk"
          }
        ]
      }
    }
  ]
}

Endpoint example

GET /graph/v3/aggregations

{
  "items": [
    { "type": "TOPK", "database": "commerce", "table": "purchases" }
  ]
}

GET /graph/v3/aggregations?type=TOPK filters to a single aggregation type.

Test plan

• ./gradlew :core:test --tests 'com.kakao.actionbase.core.metadata.common.AggregationsTest'
• ./gradlew :engine:test --tests 'com.kakao.actionbase.engine.service.AggregationServiceSpec'
• ./gradlew :engine:test --tests 'com.kakao.actionbase.v2.engine.entity.LabelEntityFunctionsSpec'
• ./gradlew :server:test --tests 'com.kakao.actionbase.server.api.graph.v3.metadata.MetadataAggControllerE2ETest'

AI Assistance

• This PR was written largely with AI assistance.
  • Tool / model: Claude Code (Opus 4.7)

[zipdoki]

Optimistic Merge