集計

Show:

Aggregateエンドポイントは、バケット内のドキュメントをメタデータフィールドでグループ化し、各異なる値のカウントを返します。ファセット、ヒストグラム、カテゴリサマリーを構築するために使用します。

注意: このエンドポイントは、後方互換性のためにリクエストボディでcollectionを使用します。新しいSchift APIでは、同じ概念はbucketと呼ばれます。

POST /v1/aggregate

メタデータキーでドキュメントをグループ化し、カウントします。

Request headers

Header	Required	Description
`Authorization`	Yes	Bearer API key (`Bearer $SCHIFT_API_KEY`).
`Content-Type`	Yes	Must be `application/json`.

Request body

Parameter	Type	Required	Description
`collection`	string	Yes	集計するバケット名。互換性のために`collection`として保持。
`group_by`	string	Yes	グループ化するメタデータキー。
`filter_key`	string	No	グループ化前にフィルタリングするためのオプションのメタデータキー。
`filter_value`	string	No	フィルタキーに一致するオプションの値。

Request example

カテゴリごとにドキュメントをカウントします:

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"
  }'

Response body

Field	Type	Description
`groups`	array	値とカウントを持つグループのリスト。
`groups[].value`	string	グループ化された値。
`groups[].count`	integer	このグループ内のアイテム数。
`total`	integer	すべてのグループの合計カウント。

Response example

{
  "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"
  }'

Response:

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

Errors

Status	Meaning	Example response
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 versions

Version	Status	Notes
`v1`	Deprecated	現在のエンドポイント。`collection`パラメータはレガシー統合との互換性のために保持されています。

集計