フィルタリング

メタデータフィルタリングは、メタデータに基づいて検索結果を絞り込み、関連するコンテンツだけを取得します。フィルターは取得の前に適用されるため、必要なドキュメントだけをクエリします。

フィルタリングは、インデックス時に抽出したメタデータ属性を使います。カスタム属性の定義や組み込みメタデータ属性の使い方は、メタデータ属性を参照してください。

AI Search は、フィルター可能なプレフィックスより長い文字列値を保存できます。フィルターが照合するのは、インデックス済み文字列の先頭 64 UTF-8 バイトだけです。Vectorize は文字列配列を保存できますが、現時点では配列のインデックスやフィルターはできません。

Workers バインディングでメタデータフィルタリングを使う例です。

const instance = env.AI_SEARCH.get("my-instance");

const results = await instance.search({
	messages: [{ role: "user", content: "What is Cloudflare?" }],
	ai_search_options: {
		retrieval: {
			filters: {
				folder: "docs/getting-started/",
				timestamp: { $gte: 1735689600 },
			},
		},
	},
});

フィルター構文

フィルターは JSON オブジェクトです。キーはメタデータ属性名、値はフィルター条件です。

対応する演算子

演算子	説明
`$eq`	等しい
`$ne`	等しくない
`$in`	保存済みスカラーが、候補のスカラー値のいずれかに一致する
`$nin`	保存済みスカラーが、候補のスカラー値のいずれかに一致する場合は除外する
`$lt`	より小さい
`$lte`	以下
`$gt`	より大きい
`$gte`	以上

暗黙の `$eq`

演算子なしで値を直接渡すと、等価チェックとして扱われます。

{
	"ai_search_options": {
		"retrieval": {
			"filters": { "folder": "docs/getting-started/" }
		}
	}
}

これは次と同等です。

{
	"ai_search_options": {
		"retrieval": {
			"filters": { "folder": { "$eq": "docs/getting-started/" } }
		}
	}
}

範囲クエリ

上限と下限の演算子を組み合わせて、範囲でフィルターします。

{
	"ai_search_options": {
		"retrieval": {
			"filters": { "timestamp": { "$gte": 1735689600, "$lt": 1735900000 } }
		}
	}
}

複数条件（暗黙の AND）

複数のキーを指定すると、すべての条件に一致する必要があります。

{
	"ai_search_options": {
		"retrieval": {
			"filters": {
				"folder": "docs/getting-started/",
				"timestamp": { "$gte": 1735689600 }
			}
		}
	}
}

`$in` 演算子

保存済みのスカラーフィールドを、候補配列のいずれかの値と照合します。$in は保存済み配列の中は検索しません。

{
	"ai_search_options": {
		"retrieval": {
			"filters": { "folder": { "$in": ["docs/guides/", "docs/tutorials/"] } }
		}
	}
}

フォルダーの「前方一致」フィルター

範囲クエリを使い、フォルダーとそのサブフォルダー内のすべてのファイルをフィルターします。

次のファイル構成を例にします。

docs
- guide.pdf
- tutorials
  - getting-started
    - intro.pdf

{ "folder": "docs/" } は、そのフォルダー直下のファイル（guide.pdf など）だけに一致し、サブフォルダー内のファイルには一致しません。

docs/ で始まるすべてのファイルに一致させるには、範囲クエリを使います。

{
	"ai_search_options": {
		"retrieval": {
			"filters": { "folder": { "$gte": "docs/", "$lt": "docs0" } }
		}
	}
}

これが機能する理由は次のとおりです。

$gte は docs/ で始まるすべてのパスを含めます
docs0 に対する $lt は、docs/ で始まらないパスを除外します（ASCII では 0 が / の後ろに来るため）