メタデータフィルタリング

クエリには入力ベクトルに加え、各ベクトルに付いたベクトルメタデータでも絞り込めます。クエリ結果には、filter 条件に一致するベクトルだけが含まれます。先に filter を適用し、絞り込んだ集合から topK 件を取ります。

メタデータフィルターでクエリ範囲を狭めれば、特定の顧客 ID、テナント、製品カテゴリなど、ベクトルに付けた任意のメタデータで絞り込めます。

メタデータインデックス

Vectorize は既定で名前空間による絞り込みに対応します。ベクトルの別のメタデータプロパティで絞り込むには、メタデータインデックスを作成します。Vectorize インデックスあたり、メタデータインデックスは最大 10 個まで作成できます。

string、number、boolean 型のプロパティ向けメタデータインデックスに対応しています。詳細はメタデータインデックスを作成するを参照してください。

ベクトルあたり最大 10KiB のメタデータを保存できます。制限の一覧は Vectorize の制限を参照してください。

number 型のメタデータインデックスでは、インデックスする数値の精度は float64 です。

string 型のメタデータインデックスでは、各ベクトルは文字列データの先頭 64B をインデックスします。切り捨ては UTF-8 の文字境界で行い、その上限内で最も長い整形式の UTF-8 部分文字列にします。そのため、インデックスした各プロパティについて、値の先頭 64B でフィルターできます。

対応する操作

query() メソッドの任意の filter プロパティで、メタデータフィルターを指定します。

演算子	説明
`$eq`	等しい
`$ne`	等しくない
`$in`	いずれかに含まれる
`$nin`	いずれにも含まれない
`$lt`	より小さい
`$lte`	以下
`$gt`	より大きい
`$gte`	以上

filter は空でないオブジェクトで、コンパクトな JSON 表現が 2048 バイト未満である必要があります。
filter オブジェクトのキーは空にできません。" | . を含められず（ドットはネスト用に予約）、$ で始められず、512 文字を超えられません。
$eq と $ne では、filter オブジェクトの非ネスト値は string、number、boolean、または null にできます。
$in と $nin では、filter オブジェクトの値は string、number、boolean、または null の配列にできます。
上限の範囲クエリ（$lt と $lte）は、同じフィルター内で下限の範囲クエリ（$gt と $gte）と組み合わせられます。ほかの組み合わせはできません。
範囲クエリ（$lt、$lte、$gt、$gte）では、filter オブジェクトの非ネスト値は string または number にできます。文字列は辞書順です。
ベクトル数が多い範囲クエリ（約 1,000 万件以上）では、精度が下がることがあります。

名前空間とメタデータフィルターの比較

名前空間とメタデータフィルターは、どちらもクエリのベクトル検索空間を狭めます。両方のフィルターを検討するときは、次の点を考慮してください。

名前空間フィルターは、メタデータフィルターより先に適用されます。
ベクトルが所属できる名前空間は 1 つで、記載の制限が適用されます。ベクトルメタデータには、ベクトルあたりのメタデータ上限まで複数のキーと値のペアを含められます。メタデータ値は型（string、boolean など）が違うため、より柔軟です。

有効な `filter` の例

暗黙の `$eq` 演算子

{ "streaming_platform": "netflix" }

明示的な演算子

{ "someKey": { "$ne": "hbo" } }

`$in` 演算子

{ "someKey": { "$in": ["hbo", "netflix"] } }

`$nin` 演算子

{ "someKey": { "$nin": ["hbo", "netflix"] } }

数値の範囲クエリ

{ "timestamp": { "$gte": 1734242400, "$lt": 1734328800 } }

文字列の範囲クエリ

範囲クエリは、文字列メタデータフィールドで プレフィックス検索 を実現できます。starts_with フィルターに近い動きです。

たとえば、次のフィルターは "net" で始まるすべての値に一致します。

{ "someKey": { "$gte": "net", "$lt": "neu" } }

複数キーによる暗黙の論理 `AND`

{ "pandas.nice": 42, "someKey": { "$ne": "someValue" } }

`.`（ドット）でネストを表すキー

{ "pandas.nice": 42 }

// looks for { "pandas": { "nice": 42 } }

例

メタデータを追加する

次のインデックス定義で:

npx wrangler vectorize create tutorial-index --dimensions=32 --metric=cosine

メタデータインデックスを作成します。

npx wrangler vectorize create-metadata-index tutorial-index --property-name=url --type=string

npx wrangler vectorize create-metadata-index tutorial-index --property-name=streaming_platform --type=string

メタデータは、ベクトルの挿入または upsert 時に追加できます。

const newMetadataVectors: Array<VectorizeVector> = [
	{
		id: "1",
		values: [32.4, 74.1, 3.2, ...],
		metadata: { url: "/products/sku/13913913", streaming_platform: "netflix" },
	},
	{
		id: "2",
		values: [15.1, 19.2, 15.8, ...],
		metadata: { url: "/products/sku/10148191", streaming_platform: "hbo" },
	},
	{
		id: "3",
		values: [0.16, 1.2, 3.8, ...],
		metadata: { url: "/products/sku/97913813", streaming_platform: "amazon" },
	},
	{
		id: "4",
		values: [75.1, 67.1, 29.9, ...],
		metadata: { url: "/products/sku/418313", streaming_platform: "netflix" },
	},
	{
		id: "5",
		values: [58.8, 6.7, 3.4, ...],
		metadata: { url: "/products/sku/55519183", streaming_platform: "hbo" },
	},
];

// Upsert vectors with added metadata, returning a count of the vectors upserted and their vector IDs
let upserted = await env.YOUR_INDEX.upsert(newMetadataVectors);

クエリの例

query() メソッドを使います。

let queryVector: Array<number> = [54.8, 5.5, 3.1, ...];
let originalMatches = await env.YOUR_INDEX.query(queryVector, {
	topK: 3,
	returnValues: true,
	returnMetadata: 'all',
});

メタデータフィルターなしの結果:

{
	"count": 3,
	"matches": [
		{
			"id": "5",
			"score": 0.999909486,
			"values": [58.79999923706055, 6.699999809265137, 3.4000000953674316],
			"metadata": {
				"url": "/products/sku/55519183",
				"streaming_platform": "hbo"
			}
		},
		{
			"id": "4",
			"score": 0.789848214,
			"values": [75.0999984741211, 67.0999984741211, 29.899999618530273],
			"metadata": {
				"url": "/products/sku/418313",
				"streaming_platform": "netflix"
			}
		},
		{
			"id": "2",
			"score": 0.611976262,
			"values": [15.100000381469727, 19.200000762939453, 15.800000190734863],
			"metadata": {
				"url": "/products/sku/10148191",
				"streaming_platform": "hbo"
			}
		}
	]
}

同じ query() メソッドに filter プロパティを付けると、メタデータフィルターを使えます。

let queryVector: Array<number> = [54.8, 5.5, 3.1, ...];
let metadataMatches = await env.YOUR_INDEX.query(queryVector, {
	topK: 3,
	filter: { streaming_platform: "netflix" },
	returnValues: true,
	returnMetadata: 'all',
});

メタデータフィルターありの結果:

{
	"count": 2,
	"matches": [
		{
			"id": "4",
			"score": 0.789848214,
			"values": [75.0999984741211, 67.0999984741211, 29.899999618530273],
			"metadata": {
				"url": "/products/sku/418313",
				"streaming_platform": "netflix"
			}
		},
		{
			"id": "1",
			"score": 0.491185264,
			"values": [32.400001525878906, 74.0999984741211, 3.200000047683716],
			"metadata": {
				"url": "/products/sku/13913913",
				"streaming_platform": "netflix"
			}
		}
	]
}

制限

現時点では、メタデータフィルターを使うには、ベクトルを挿入する前に Vectorize インデックスへメタデータインデックスを作成する必要があります。
メタデータフィルターに対応するのは、2023-12-06 以降に作成したインデックスだけです。それ以前に作成したインデックスは、メタデータフィルター対応へ移行できません。