Aggregate(집계)

Show:

Aggregate 엔드포인트는 버킷(bucket) 내 문서를 메타데이터 필드별로 그룹화하고, 각 고유 값의 개수를 반환합니다. 패싯(facet), 히스토그램(histogram), 카테고리 요약을 구축할 때 사용하세요.

참고: 이 엔드포인트는 하위 호환성을 위해 요청 본문에 collection을 사용합니다. 최신 Schift API에서는 같은 개념을 **bucket(버킷)**이라고 부릅니다.

POST /v1/aggregate

메타데이터 키별로 문서를 그룹화하고 개수를 셉니다.

요청 헤더

헤더	필수	설명
`Authorization`	예	Bearer API 키 (`Bearer $SCHIFT_API_KEY`).
`Content-Type`	예	반드시 `application/json`이어야 합니다.

요청 본문

매개변수	타입	필수	설명
`collection`	string	예	집계할 버킷(bucket) 이름입니다. 호환성을 위해 `collection`으로 유지됩니다.
`group_by`	string	예	그룹화할 메타데이터 키입니다.
`filter_key`	string	아니오	그룹화 전에 필터링할 메타데이터 키입니다. 선택 사항입니다.
`filter_value`	string	아니오	필터 키와 일치할 값입니다. 선택 사항입니다.

요청 예시

카테고리별 문서 개수를 집계합니다:

curl -X POST https://api.schift.io/v1/aggregate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -d '{
    "collection": "product-docs",
    "group_by": "category"
  }'

응답 본문

필드	타입	설명
`groups`	array	값(value)과 개수(count)를 담은 그룹 목록입니다.
`groups[].value`	string	그룹화된 값입니다.
`groups[].count`	integer	해당 그룹의 항목 개수입니다.
`total`	integer	모든 그룹의 총 개수입니다.

응답 예시

{
  "groups": [
    {
      "value": "Getting Started",
      "count": 12
    },
    {
      "value": "API Reference",
      "count": 28
    },
    {
      "value": "Troubleshooting",
      "count": 7
    }
  ],
  "total": 47
}

필터링된 집계

filter_key와 filter_value를 지정하면 그룹화 전에 문서를 미리 필터링할 수 있습니다. 메타데이터에 지정한 값이 포함된 문서만 집계에 포함됩니다.

curl -X POST https://api.schift.io/v1/aggregate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -d '{
    "collection": "product-docs",
    "group_by": "status",
    "filter_key": "category",
    "filter_value": "API Reference"
  }'

응답:

{
  "groups": [
    {
      "value": "published",
      "count": 22
    },
    {
      "value": "draft",
      "count": 6
    }
  ],
  "total": 28
}

오류

상태	의미	예시 응답
402	쿼리 할당량 초과 또는 사용 불가.	`{"detail": {"allowed": false, ...}}`
403	현재 요금제에서 쿼리 할당량 사용 불가.	`{"detail": "Query quota unavailable. Upgrade your plan."}`
404	지정한 컬렉션이나 버킷을 찾을 수 없음.	`{"detail": "Collection not found: product-docs"}`
501	설정된 벡터 백엔드가 집계를 지원하지 않음.	`{"detail": "Aggregate not supported by backend: <BackendName>"}`

API 버전

버전	상태	비고
`v1`	사용 중단	현재 엔드포인트입니다. `collection` 매개변수는 레거시 연동과의 호환성을 위해 유지됩니다.