INTEGRITY Документация

← Cloudflare Vectorize / vectorize / reference

Фильтрация метаданных

Помимо входного вектора запроса, вы также можете выполнять фильтрацию по метаданные вектора связанных с каждым вектором. Результаты запроса будут включать только векторы, соответствующие filter критериям, что означает, что filter применяется первым, а topK результаты берутся из отфильтрованного набора.

Используя фильтрацию по метаданным для ограничения области запроса, вы можете фильтровать по конкретным ID клиентов, арендатору, категории продукта или любым другим метаданным, связанным с вашими векторами.

Индексы метаданных

Vectorize поддерживает пространство имён фильтрацию по умолчанию, но для фильтрации по другому свойству метаданных ваших векторов потребуется создать индекс метаданных. Вы можете создать до 10 индексов метаданных на один индекс Vectorize.

Индексы метаданных для свойств типа string, number и boolean поддерживаются. Подробнее см. в Создание индексов метаданных для получения подробностей.

На один вектор можно сохранить до 10 КиБ метаданных. См. Ограничения Vectorize для получения полного списка ограничений.

Для индексов метаданных типа number, точность индексируемых чисел соответствует float64.

Для индексов метаданных типа string, каждый вектор индексирует первые 64 байта строковых данных, усечённых по границам символов UTF-8 до самой длинной корректной подстроки UTF-8 в пределах этого лимита, поэтому векторы можно фильтровать по первым 64 байтам значения для каждого индексируемого свойства.

Поддерживаемые операции

Необязательный filter свойство у query() метод задаёт фильтры метаданных:

Оператор Описание
$eq Equals
$ne Не равно
$in В
$nin Не входит в
$lt Меньше
$lte Меньше или равно
$gt Больше
$gte Больше или равно

Пространство имён в сравнении с фильтрацией по метаданным

Оба пространства имён и фильтрация по метаданным сужают пространство векторного поиска для запроса. При оценке обоих типов фильтров учитывайте следующее:

Действителен 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"
			}
		}
	]
}

Ограничения