Facets

The Facets API returns the top-N values (with counts) for each metadata key in a bucket. Use it to populate filter dropdowns, show dataset shape, or detect dirty data.

Request

bashPOST /v1/buckets/{bucket_id}/facets

Example

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

Response

json{
  "bucket_id": "bkt_abc",
  "facets": {
    "tag":      [{"value": "urgent", "count": 142}, {"value": "draft", "count": 87}],
    "doc_type": [{"value": "policy", "count": 320}, {"value": "spec", "count": 145}],
    "source_url": [...]
  },
  "totals": {"tag": 229, "doc_type": 465, "source_url": 712}
}