フィルター演算子

Show: All versions v2 only

フィルター演算子を使用すると、メタデータの述語によってバケット検索結果を絞り込むことができます。v2バケット検索リクエストボディでは、filterオブジェクト内に渡します。単純なスカラー値は完全一致のショートカットであり、値を演算子オブジェクトでラップすることで、より豊かな述語を表現できます。

注意: メタデータの値は文字列として保存および比較されます。ブール値は"true"/"false"となり、数値は一致前に文字列に変換されます。

APIバージョン

Version	Status	Notes
v2	Current	POST /v2/buckets/\{bucket_id\}/search。すべての新しい統合に使用します。
v1	Deprecated	POST /v1/buckets/\{bucket_id\}/searchは既存のクライアントのために保持されており、v2の後継を指すDeprecation、Warning、Linkヘッダーを返します。

レガシーv1エンドポイント

POST /v1/buckets/\{bucket_id\}/searchは非推奨であり、このページで文書化されているのと同じfilter演算子を受け入れます。新しい統合はPOST /v2/buckets/\{bucket_id\}/searchを使用してください。

演算子

Operator	Type	Example	Notes
eq	any	{"eq": "urgent"}	完全一致。トップレベルのeqはエンジンの高速パスに下げられます。
ne	any	{"ne": "draft"}	不一致。ポストフィルターとして適用されます。
like	string	{"like": "%legal%"}	SQL LIKE: %は任意のシーケンスに一致し、_は1文字に一致します。\% / \_はリテラルです。大文字小文字を区別しません。
prefix	string	{"prefix": "2024-"}	始まり一致。大文字小文字を区別しません。
in	array	{"in": ["a", "b"]}	メンバーシップテスト。最大100エントリ。
gt / gte	number / ISO date	{"gte": 0.8}	より大きい（または等しい）。
lt / lte	number / ISO date	{"lt": 100}	より小さい（または等しい）。
exists	boolean	{"exists": true}	フィールドの存在: trueは存在し非空を意味し、falseは欠落または空を意味します。

各演算子オブジェクトは正確に1つのキーを含む必要があります。単一のフィルターキーは一度に1つの演算子しか使用できません。

クロスキーOR ($or)

異なるメタデータキー間の論理和を表現するには$orを使用します。$orはサブフィルタ辞書のリストを受け入れ、最大3レベルまでネストできます。

{
  "filter": {
    "doc_type": "policy",
    "$or": [
      {"severity": "high"},
      {"priority": {"in": ["P0", "P1"]}}
    ]
  }
}

トップレベルのキーは依然としてANDです。この例では、doc_type = "policy" AND (severity = "high" OR priority ∈ {"P0", "P1"})に一致するドキュメントを検索します。各アームは完全なサブフィルターであり、任意の演算子を使用できます。単一の$orリストは最大16アームをサポートします。

セマンティクス

• filter内のトップレベルキーは結合的（AND）です。
• 同じキーのORはin演算子を使用し、クロスキーORは$orを使用します。
• 完全一致キーはベクトルエンジンにプッシュされてプルーニングされます。演算子キーは返された候補に対してサーバー側で評価されるため、エンジンの高速パスはそのままです。

安全制限

Limit	Value
Max filter JSON size (internal filter query param)	8 KB
Max filter nesting depth	16
like / prefix pattern length	256 characters
like wildcard count (% + _)	16
in list length	100 entries
$or nesting depth	3 levels
$or arms per list	16

パターンはアンカー付きの大文字小文字を区別しない正規表現に変換され、すべての正規表現メタ文字がエスケープされるため、SQLインジェクションの表面はありません。

POST /v2/buckets/{bucket_id}/search

テキストクエリとメタデータフィルターを使用してバケットを検索します。

パスパラメータ

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

リクエストボディ

Field	Type	Required	Default	Description
query	string	Yes	—	自然言語クエリ。最大8,192文字。
top_k	integer	No	10	返す結果の最大数。
filter	object	No	null	メタデータの述語。単純な値は完全一致であり、演算子オブジェクトは上記の演算子を使用します。
mode	string	No	"hybrid"	"vector"または"hybrid"。
rerank	boolean	No	false	候補を再ランク付けするかどうか。
min_score	number	No	null	最小スコアのしきい値（0.0–1.0）。

リクエスト例

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": "fire safety inspection cycle",
    "top_k": 10,
    "filter": {
      "tag": "urgent",
      "source_url": {"like": "%fire-safety%"},
      "filename": {"prefix": "2024-"},
      "doc_type": {"in": ["policy", "spec"]},
      "score": {"gte": 0.8},
      "stage": {"ne": "draft"},
      "author": {"exists": true},
      "$or": [
        {"severity": "high"},
        {"priority": {"in": ["P0", "P1"]}}
      ]
    }
  }'

レスポンス

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	チャンクメタデータ。
results[].citation	string | null	要求された場合のフォーマットされた引用。
degraded	boolean	応答が劣化モードで生成されたかどうか。
warnings	array	検索警告がある場合。

レスポンス例

{
  "bucket_id": "product-docs",
  "query": "fire safety inspection cycle",
  "search_id": "srch_01j8x9q2mvk8r",
  "results": [
    {
      "id": "chunk_01j8x9q2mvn9q",
      "score": 0.91,
      "text": "Annual fire safety inspections must follow the 2024 inspection cycle.",
      "metadata": {
        "doc_type": "policy",
        "filename": "2024-fire-safety.pdf",
        "tag": "urgent",
        "author": "safety-team"
      },
      "citation": "[1] 2024-fire-safety.pdf, p. 4"
    }
  ],
  "degraded": false,
  "warnings": []
}

エラー例

// 400 Bad Request — invalid operator combination
{
  "detail": "FilterOperator must have exactly one of eq/ne/like/prefix/in/gt/gte/lt/lte/exists"
}

// 400 Bad Request — unsupported filter key
{
  "detail": "Invalid filter: unsupported metadata key 'internal_tag'"
}

// 413 Payload Too Large — filter exceeds size limit
{
  "detail": "filter parameter exceeds 8KB"
}

// 413 Payload Too Large — filter too deeply nested
{
  "detail": "filter JSON exceeds nesting depth"
}

// 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 'product-docs' not found"
}

参照

• バケット
• Query & Search
• Facets
• Metadata