レスポンスシェーピング

Show: All versions v2 only

レスポンスシェーピングを使用すると、バケット検索エンドポイントが返す内容と各結果のフォーマットを制御できます。フィールドを削減してペイロードを小さくしたり、フォーマットされた引用を挿入したり、取得したチャンクのグラフ隣接を引き込んだりするのに役立ちます。

Note: context、citations、status、operational_statusを含む完全に組み立てられた回答コンテキストには、Query & Search エンドポイントを使用してください。バケット検索エンドポイントは生のランク付けされたチャンクを返し、下流の組み立てを所有している場合に適しています。

API Versions

Version	Status	Notes
v2	Current	POST /v2/buckets/\{bucket_id\}/search. Use for all new integrations.
v1	Deprecated	POST /v1/buckets/\{bucket_id\}/search is kept for existing clients and returns Deprecation, Warning, and Link headers pointing to the v2 successor.

POST /v2/buckets/{bucket_id}/search

バケットを検索し、返されるチャンクを整形します。

Path parameters

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

Request headers

Header	Value
Authorization	Bearer $SCHIFT_API_KEY
Content-Type	application/json

Request body

Field	Type	Required	Default	Description
query	string	Yes	—	自然言語クエリ。最大8,192文字。
top_k	integer	No	10	返す結果の最大数（1–1000）。
mode	string	No	"hybrid"	"vector"または"hybrid"。
rerank	boolean	No	false	候補を再ランク付けするかどうか。
min_score	number	No	null	最小スコア閾値（0.0–1.0）。
include_fields	array of string	No	null	結果フィールドのホワイトリスト、例：["id", "score", "metadata.title"]。レガシーの生結果制御。
exclude_fields	array of string	No	null	結果フィールドのブラックリスト、例：["text", "metadata.source_url"]。レガシーの生結果制御。
citation_format	string	No	null	結果ごとのcitationのテンプレート、例："[\{title\}:p.\{page\}]"。レガシーの生結果制御。
expand_neighbors	object	No	null	各ヒットのグラフ隣接を取得します。neighbor expansionを参照。
expand_context	object	No	null	再ランク付け前に同一ドキュメントの隣接チャンクを追加します。
debug	boolean	No	false	詳細なデバッグタイミングとチャンクごとのスコアを含めます。

Response

Field	Type	Description
bucket_id	string	検索されたバケット。
query	string	実行されたクエリ。
search_id	string | null	サーバー生成の検索識別子。
results	array	関連性順に並べられた一致するチャンク。
results[].id	string	チャンク識別子。
results[].score	number	最終的な関連性スコア。
results[].text	string	チャンクテキスト。
results[].metadata	object	bucket_idとcollection_idを含むチャンクメタデータ。
results[].citation	string | null	citation_formatが設定されている場合のフォーマットされた引用。
results[].neighbors	array | null	expand_neighborsが設定されている場合のグラフ隣接。
degraded	boolean	応答が劣化モードで生成されたかどうか。
warnings	array	検索警告がある場合。
debug	object | null	debug: trueの場合のデバッグ情報。

Field projection

include_fieldsとexclude_fieldsは、各結果に表示されるキーを制御します。どちらもmetadata.titleのようなドットパスをサポートします。

• include_fieldsはキーをホワイトリスト化します。設定されている場合、リストされたトップレベルキーと要求されたメタデータサブキーのみが返されます。
• exclude_fieldsはキーをブラックリスト化します。設定されている場合、リストされたトップレベルキーとメタデータサブキーが削除されます。
• 両方が設定されている場合、include_fieldsが優先されます。

Note: id、score、textは常にデフォルトで埋め込まれ、プロジェクションがそれらを削除しても結果が有効であるようにします。

Citation formatting

citation_formatが提供されると、各結果に\{key\}トークンを置換して構築されたcitation文字列が付きます。トークンはまず結果から解決され、その後metadataから解決されます。不明なトークンは空文字列としてレンダリングされます。

例えば、メタデータが{"title": "Terms", "page": 3}でフォーマットが"[\{title\}:p.\{page\}]"の場合、引用は"[Terms:p.3]"になります。

Neighbor expansion

expand_neighborsは、各ヒットに接続されたグラフエッジを取得します。

Field	Type	Required	Default	Description
relations	array of string	No	null	これらの関係タイプにフィルタリングします。nullはすべてを意味します。
direction	string	No	"both"	"outgoing"、"incoming"、または"both"。
max_per_hit	integer	No	10	ヒットごとに返される最大エッジ数（1–100）。

返される各隣接には以下があります：

Field	Type	Description
id	string	隣接ノードID。
relation	string	関係タイプ、例：follows、has_child。
direction	string	"outgoing"または"incoming"。
weight	number	エッジの重み。

Example request

curl -X POST ${API_BASE_URL:-https://api.schift.io}/v2/buckets/product-docs/search \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "annual leave policy",
    "top_k": 5,
    "min_score": 0.7,
    "citation_format": "[{title}:p.{page}]",
    "expand_neighbors": {
      "relations": ["references", "has_child"],
      "direction": "both",
      "max_per_hit": 3
    },
    "debug": true
  }'

Example response

{
  "bucket_id": "product-docs",
  "query": "annual leave policy",
  "search_id": "search_0a1b2c3d4e5f",
  "results": [
    {
      "id": "chunk_01j8x9q2mvn9q",
      "score": 0.91,
      "text": "Full-time employees receive 20 days of paid annual leave per year.",
      "metadata": {
        "bucket_id": "product-docs",
        "collection_id": "col_123",
        "title": "Employee Handbook",
        "page": 12,
        "doc_type": "policy"
      },
      "citation": "[Employee Handbook:p.12]",
      "neighbors": [
        {
          "id": "chunk_01j8x9q2mvna0",
          "relation": "references",
          "direction": "outgoing",
          "weight": 1.0
        }
      ]
    }
  ],
  "degraded": false,
  "warnings": [],
  "debug": {
    "query_embedding_model": "schift-embed-v1",
    "search_method": "hybrid",
    "timing_ms": {
      "embedding": 23,
      "vector_search": 18,
      "bm25": 9,
      "hydration": 4,
      "total": 62
    },
    "results_detail": [
      {
        "chunk_id": "chunk_01j8x9q2mvn9q",
        "vector_score": 0.88,
        "bm25_score": 0.72,
        "rrf_score": 0.85,
        "final_score": 0.91,
        "source": "hybrid"
      }
    ]
  }
}

Error examples

// 400 Bad Request — missing query
{
  "detail": "query or query_vector is required"
}

// 400 Bad Request — invalid filter
{
  "detail": "Invalid filter: unsupported operator"
}

// 402 Payment Required — search quota exhausted
{
  "allowed": false,
  "reason": "quota_exceeded"
}

// 403 Forbidden — search quota unavailable
{
  "detail": "Search quota unavailable. Upgrade your plan."
}

// 404 Not Found
{
  "detail": "Bucket not found"
}

// 500 Internal Server Error
{
  "detail": "Bucket search failed"
}

Legacy v1 endpoint

POST /v1/buckets/\{bucket_id\}/searchは廃止予定です。同じペイロード形式を返しますが、以下のレスポンスヘッダーを追加します：

Header	Value
Deprecation	true
Warning	299 - "Deprecated search endpoint; migrate to /v2/buckets/\{bucket_id\}/search"
Link	</v2/buckets/\{bucket_id\}/search>; rel="successor-version"

See also

• バケット
• Query & Search
• Filter Operators
• Metadata
• Edges