AI Searchに大量の文書を登録すると、ページング一覧から特定文書を探す処理は遅く、誤操作もしやすい。exact keyフィルターは対象文書を直接絞れるが、keyの一意性はデータソース単位で考える必要がある。sourceなしの検索を管理操作へ使うと、同名keyの別文書を扱う危険がある。
何が変わったか
AI Searchのitems一覧APIにkeyフィルターが追加され、完全一致するobject keyで対象itemを検索できるようになった
| 項目 | 内容 |
|---|---|
| 対象 | AI Search |
| API・機能 | Items REST API |
| 変更種別 | API変更 |
| 重要度 | 中 |
| 対応期限 | 期限なし |
変更前後の差
従来は一覧、source、状態等の条件から対象itemを探索する必要があった。新しいkeyクエリは完全一致で検索できる。Cloudflareはkeyがデータソースをまたいで一意ではないため、sourceとの組み合わせを推奨している。
誰に影響するか
同期ジョブ、管理画面、失敗文書の再処理、特定文書削除、監査、RAG回答から原文状態へ遡る処理に影響する。外部入力からkeyを受け取るAPIでは、テナントとsourceの権限検証が必須である。
期限
既存APIを壊す変更ではなく、利用期限はない。探索コストが高い管理処理から段階導入できる。
必要な対応
内部の文書IDをsource + keyの複合キーとして扱う。keyのURLエンコード、大小文字、末尾スラッシュ、Unicode正規化を確認する。取得結果が0件・複数件の場合は更新や削除を実行しない。
実装・移行手順
- 現在のsource IDとobject keyの生成規則を棚卸しする
- 同じkeyを異なるsourceへ登録して挙動を確認する
- keyとsourceをURLエンコードして完全一致検索する
- 0件・1件・複数件の処理を分ける
- 削除・再取込前にitem IDとテナントを再照合する
- 監査ログへsource、key、item ID、操作者を記録する
失敗しやすい点
keyだけをグローバル一意とみなす、部分一致検索として使う、ユーザー入力を無検証で管理APIへ渡す、0件時に新規文書と断定することが失敗につながる。
リスク
別テナント文書の誤操作、同名keyの衝突、エンコード差による未検出、削除対象の取り違えがある。
評価方法
- key検索の0件率
- 複数件率
- 一覧走査からのレイテンシー削減
- 誤削除・誤再取込件数
- source未指定リクエスト数
- 監査ログ欠落率
ロールバック
新しいkey検索を停止し、item IDまたは既存のsource付き一覧検索へ戻す。更新・削除APIの実行前確認は残す。
編集部分析
exact keyは小さなAPI追加だが、文書ライフサイクル管理を安定させる。検索精度より管理対象の同一性を保証する機能として扱うべきである。
実務チェックリスト
- [ ] sourceとkeyを組み合わせた
- [ ] テナント権限を確認した
- [ ] エンコード差を試験した
- [ ] 複数件時に停止する
- [ ] 削除前にitem IDを再確認した
- [ ] 監査ログを残した