コンテンツにスキップ

ファセット

Show:

注意: バケットファセットルートは非推奨であり、v2コンシューマーAPIの一部ではありません。新しい製品統合で使用しないでください。ファセットフィルタリングには、POST /v2/buckets/\{bucket_id\}/searchを使用し、ユーザーに見えるメタデータ述語をfiltersオブジェクトに渡してください。Schiftはファセットスタイルの集約とフィルタ発見を内部オペレーターの機能として保持しており、新しい消費者向けの公開APIサーフェスではありません。

API Versions

Version	Status	Notes
`v2`	Current	新しい統合には`POST /v2/buckets/\{bucket_id\}/search`と`filters`を使用してください。
`v1`	Deprecated	`POST /v1/buckets/\{bucket_id\}/facets`は既存のクライアントのために保持されており、公開OpenAPIスキーマからは非表示です。

POST /v1/buckets/{bucket_id}/facets

バケットの検索可能なコレクション全体でメタデータのキー/値のカーディナリティを集約します。レスポンスは、各要求されたフィールドの最も一般的な値を示し、フィルタードロップダウンを埋めるか、データセットのカバレッジを確認するために使用できます。

注意: このエンドポイントは公開スキーマから除外されています (include_in_schema=false)。新しいコードは直接呼び出すのではなく、v2バケット検索に移行するべきです。

Path parameters

Name	Type	Description
`bucket_id`	string	集約するバケットのUUIDまたはスラッグ。

Request headers

Header	Required	Description
`Authorization`	Yes	ベアラーAPIキー (`Bearer $SCHIFT_API_KEY`)。
`Content-Type`	Yes	`application/json`である必要があります。

Request body

Field	Type	Required	Default	Description
`fields`	array of string	Yes	—	集約するメタデータキー。最低1、最大20。空のリストは拒否されます。
`limit_per_field`	integer	No	`20`	フィールドごとに返す最大の異なる値の数。最低1、最大200。

Request example

curl -X POST https://api.schift.io/v1/buckets/product-docs/facets \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -d '{
    "fields": ["tag", "source_url"],
    "limit_per_field": 20
  }'

Response body

Field	Type	Description
`bucket_id`	string	解決されたバケット識別子。
`facets`	object	要求されたフィールド名を`{value, count}`ペアの配列にマップしたもの。
`facets[].value`	string	フィールドの異なるメタデータ値。
`facets[].count`	integer	その値に一致するチャンクの数。
`totals`	object	フィールド名をバケットの検索可能なコレクション全体で見られる値の総数にマップしたもの。

Response example

{
  "bucket_id": "product-docs",
  "facets": {
    "tag": [
      {"value": "urgent", "count": 142},
      {"value": "reviewed", "count": 87}
    ],
    "source_url": [
      {"value": "https://docs.example.com/enterprise", "count": 65}
    ]
  },
  "totals": {
    "tag": 229,
    "source_url": 312
  }
}

Error examples

Status	Meaning	Example response
403	現在のプランではクエリークォータが利用できません。	`{"detail": "Query quota unavailable. Upgrade your plan."}`
403	このバケットには検索可能なコレクションが存在しません。	`{"detail": "No searchable collections for this bucket"}`
404	指定されたバケットが見つかりませんでした。	`{"detail": "Bucket not found"}`

フィルターを使用したv2検索への移行

ファセットで値を発見する代わりに、新しい統合ではフィルター値を直接v2検索エンドポイントに送信するべきです:

curl -X POST https://api.schift.io/v2/buckets/product-docs/search \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "refund policy",
    "filters": {
      "status": "published",
      "product": "enterprise"
    }
  }'

完全な述語構文については、eq、in、like、prefix、範囲、およびクロスキー$orを含むFilter Operatorsを参照してください。

See also