Skip to content

非公式本サイトは非公式の日本語ドキュメントであり、Cloudflare 公式サイトではありません。最新情報はdevelopers.cloudflare.comをご確認ください。

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

最終更新 Markdown で表示Agent セットアップ

クエリには入力ベクトルに加え、各ベクトルに付いた ベクトルメタデータ でも絞り込めます。クエリ結果には、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 以降に作成したインデックスだけです。それ以前に作成したインデックスは、メタデータフィルター対応へ移行できません。

役に立ちましたか？