除了向查询提供输入向量外，您还可以按与每个向量关联的向量元数据进行过滤。查询结果将仅包含匹配 filter 条件的向量，这意味着 filter 首先应用，然后从过滤后的集合中取 topK 结果。
通过使用元数据过滤来限制查询范围，您可以按特定客户 ID、租户、产品类别或您与向量关联的任何其他元数据进行过滤。
Vectorize 默认支持 namespace 过滤，但要按向量的其他元数据属性过滤，您需要创建元数据索引。每个 Vectorize 索引最多可创建 10 个元数据索引。
支持 string、number 和 boolean 类型的属性元数据索引。请参阅创建元数据索引了解详情。
每个向量最多可存储 10KiB 元数据。请参阅 Vectorize 限制 了解完整限制列表。
对于 number 类型的元数据索引，索引数字精度为 float64。
对于 string 类型的元数据索引，每个向量在 UTF-8 字符边界处截断到该限制内最长格式良好的 UTF-8 子字符串，索引字符串数据的前 64B，因此向量可按每个索引属性的前 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值。字符串按字典序排序。 - 涉及大量向量（约 1000 万及以上）的范围查询可能会降低准确性。
Namespace 和元数据过滤都会缩小查询的向量搜索空间。评估两种过滤器类型时请考虑以下因素：
- Namespace 过滤器在元数据过滤器之前应用。
- 向量只能属于单个 namespace，受文档限制约束。向量元数据可包含多个键值对，最多 每个向量的元数据限制。元数据值支持不同类型（
string、boolean等），因此提供更大灵活性。
{ "streaming_platform": "netflix" }{ "someKey": { "$ne": "hbo" } }{ "someKey": { "$in": ["hbo", "netflix"] } }{ "someKey": { "$nin": ["hbo", "netflix"] } }{ "timestamp": { "$gte": 1734242400, "$lt": 1734328800 } }范围查询可以在字符串元数据字段上实现前缀搜索。这也类似于 starts_with 过滤器。
例如，以下过滤器匹配所有以 "net" 开头的值：
{ "someKey": { "$gte": "net", "$lt": "neu" } }{ "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=stringnpx 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"
}
}
]
}带 filter 属性的相同 query() 方法支持元数据过滤。
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 或之后创建的索引支持元数据过滤。之前创建的索引无法迁移以支持元数据过滤。