元数据过滤 #
什么是元数据过滤？ #
元数据过滤允许你在向量搜索时，根据向量的元数据进行精确过滤，只返回符合条件的结果。
text
┌─────────────────────────────────────────────────────────────┐
│ 元数据过滤流程 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 查询向量 过滤条件 返回结果 │
│ │
│ [0.1, 0.2, ...] ───────────────> 相似 + 符合条件 │
│ │ │ │ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ 向量 │ │ 元数据 │ │ 过滤后 │ │
│ │ 相似性 │ + │ 条件 │ = │ 的相似 │ │
│ │ 搜索 │ │ 过滤 │ │ 结果 │ │
│ └─────────┘ └─────────┘ └─────────┘ │
│ │
│ 示例： │
│ 查询向量 + {"category": "tech", "year": {"$gte": 2023}} │
│ = 返回科技类别且 2023 年后的相似向量 │
│ │
└─────────────────────────────────────────────────────────────┘
元数据类型 #
text
┌─────────────────────────────────────────────────────────────┐
│ 支持的元数据类型 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 字符串（String）： │
│ { "title": "Pinecone 教程", "category": "database" } │
│ │
│ 数字（Number）： │
│ { "views": 1000, "rating": 4.5, "year": 2024 } │
│ │
│ 布尔值（Boolean）： │
│ { "published": true, "featured": false } │
│ │
│ 字符串列表（List of Strings）： │
│ { "tags": ["AI", "ML", "database"] } │
│ │
│ 限制： │
│ - 单个元数据最大 40KB │
│ - 字符串值最大 1000 字符 │
│ - 列表最多 1000 个元素 │
│ │
└─────────────────────────────────────────────────────────────┘
过滤操作符 #
比较操作符 #
text
┌─────────────────────────────────────────────────────────────┐
│ 比较操作符 │
├─────────────────────────────────────────────────────────────┤
│ │
│ $eq（等于） │
│ { "category": { "$eq": "technology" } } │
│ 简写: { "category": "technology" } │
│ │
│ $ne（不等于） │
│ { "status": { "$ne": "deleted" } } │
│ │
│ $gt（大于） │
│ { "views": { "$gt": 1000 } } │
│ │
│ $gte（大于等于） │
│ { "rating": { "$gte": 4.0 } } │
│ │
│ $lt（小于） │
│ { "price": { "$lt": 100 } } │
│ │
│ $lte（小于等于） │
│ { "year": { "$lte": 2023 } } │
│ │
└─────────────────────────────────────────────────────────────┘
数组操作符 #
text
┌─────────────────────────────────────────────────────────────┐
│ 数组操作符 │
├─────────────────────────────────────────────────────────────┤
│ │
│ $in（在列表中） │
│ { "category": { "$in": ["tech", "science", "AI"] } } │
│ │
│ $nin（不在列表中） │
│ { "status": { "$nin": ["deleted", "archived"] } } │
│ │
│ 注意： │
│ - $in 和 $nin 适用于字符串和数字 │
│ - 列表最多 100 个元素 │
│ │
└─────────────────────────────────────────────────────────────┘
逻辑操作符 #
text
┌─────────────────────────────────────────────────────────────┐
│ 逻辑操作符 │
├─────────────────────────────────────────────────────────────┤
│ │
│ $and（且） │
│ { │
│ "$and": [ │
│ { "category": "tech" }, │
│ { "views": { "$gte": 1000 } } │
│ ] │
│ } │
│ │
│ $or（或） │
│ { │
│ "$or": [ │
│ { "author": "John" }, │
│ { "author": "Jane" } │
│ ] │
│ } │
│ │
│ $not（非） │
│ { │
│ "$not": { "category": "spam" } │
│ } │
│ │
└─────────────────────────────────────────────────────────────┘
基本过滤示例 #
单条件过滤 #
python
from pinecone import Pinecone
pc = Pinecone(api_key="your-api-key")
index = pc.Index("my-index")
results = index.query(
vector=query_vector,
top_k=10,
filter={
"category": "technology"
},
include_metadata=True
)
多条件过滤 #
python
results = index.query(
vector=query_vector,
top_k=10,
filter={
"category": "technology",
"views": {"$gte": 1000},
"published": True
},
include_metadata=True
)
范围过滤 #
python
results = index.query(
vector=query_vector,
top_k=10,
filter={
"year": {"$gte": 2020, "$lte": 2024},
"rating": {"$gte": 4.0}
},
include_metadata=True
)
列表过滤 #
python
results = index.query(
vector=query_vector,
top_k=10,
filter={
"category": {"$in": ["technology", "science", "AI"]},
"tags": {"$in": ["tutorial", "guide"]}
},
include_metadata=True
)
复杂过滤示例 #
组合逻辑条件 #
python
results = index.query(
vector=query_vector,
top_k=10,
filter={
"$and": [
{
"$or": [
{"category": "technology"},
{"category": "science"}
]
},
{"views": {"$gte": 500}},
{
"$not": {"status": "archived"}
}
]
},
include_metadata=True
)
多层嵌套条件 #
python
results = index.query(
vector=query_vector,
top_k=10,
filter={
"$and": [
{
"$or": [
{
"$and": [
{"category": "technology"},
{"level": "advanced"}
]
},
{
"$and": [
{"category": "science"},
{"level": "beginner"}
]
}
]
},
{"published": True}
]
},
include_metadata=True
)
排除条件 #
python
results = index.query(
vector=query_vector,
top_k=10,
filter={
"$and": [
{"category": {"$in": ["tech", "science"]}},
{"status": {"$nin": ["deleted", "archived", "draft"]}},
{"author": {"$ne": "spam_user"}}
]
},
include_metadata=True
)
实际应用场景 #
电商商品搜索 #
python
def search_products(query_vector, filters=None, top_k=20):
default_filters = {
"in_stock": True,
"price": {"$lte": 1000}
}
if filters:
default_filters.update(filters)
results = index.query(
vector=query_vector,
top_k=top_k,
filter=default_filters,
include_metadata=True
)
return results
results = search_products(
query_vector,
filters={
"category": {"$in": ["electronics", "computers"]},
"brand": {"$in": ["Apple", "Samsung", "Sony"]},
"rating": {"$gte": 4.0}
}
)
内容推荐系统 #
python
def get_recommendations(user_vector, user_preferences, top_k=10):
filters = {
"published": True,
"language": user_preferences.get("language", "en"),
"$or": [
{"category": {"$in": user_preferences.get("interests", [])}},
{"tags": {"$in": user_preferences.get("interests", [])}}
]
}
if user_preferences.get("min_rating"):
filters["rating"] = {"$gte": user_preferences["min_rating"]}
results = index.query(
vector=user_vector,
top_k=top_k,
filter=filters,
include_metadata=True
)
return results
多租户数据隔离 #
python
def query_tenant_data(tenant_id, query_vector, filters=None, top_k=10):
tenant_filter = {"tenant_id": tenant_id}
if filters:
tenant_filter = {
"$and": [
{"tenant_id": tenant_id},
filters
]
}
results = index.query(
vector=query_vector,
top_k=top_k,
filter=tenant_filter,
include_metadata=True
)
return results
时间范围过滤 #
python
from datetime import datetime, timedelta
def search_recent_content(query_vector, days=30, top_k=10):
cutoff_date = (datetime.now() - timedelta(days=days)).strftime("%Y-%m-%d")
results = index.query(
vector=query_vector,
top_k=top_k,
filter={
"published_date": {"$gte": cutoff_date},
"status": "published"
},
include_metadata=True
)
return results
性能优化 #
过滤优先原则 #
text
┌─────────────────────────────────────────────────────────────┐
│ 性能优化建议 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. 使用过滤减少搜索空间 │
│ │
│ 不推荐： │
│ results = index.query(vector=v, top_k=100) │
│ filtered = [r for r in results if condition] │
│ │
│ 推荐： │
│ results = index.query( │
│ vector=v, │
│ top_k=10, │
│ filter=condition │
│ ) │
│ │
│ 2. 选择性过滤 │
│ │
│ - 使用高选择性的过滤条件 │
│ - 先过滤掉大部分不相关数据 │
│ - 减少向量相似度计算量 │
│ │
│ 3. 索引元数据 │
│ │
│ - 常用于过滤的字段放在元数据中 │
│ - 避免存储过大的元数据 │
│ │
└─────────────────────────────────────────────────────────────┘
过滤条件设计 #
python
def optimized_search(query_vector, categories, min_views, top_k=10):
filters = {
"category": {"$in": categories},
"views": {"$gte": min_views},
"status": "published"
}
results = index.query(
vector=query_vector,
top_k=top_k,
filter=filters,
include_metadata=True
)
return results
过滤工具类 #
python
class MetadataFilterBuilder:
def __init__(self):
self.conditions = []
def eq(self, field, value):
self.conditions.append({field: value})
return self
def ne(self, field, value):
self.conditions.append({field: {"$ne": value}})
return self
def gt(self, field, value):
self.conditions.append({field: {"$gt": value}})
return self
def gte(self, field, value):
self.conditions.append({field: {"$gte": value}})
return self
def lt(self, field, value):
self.conditions.append({field: {"$lt": value}})
return self
def lte(self, field, value):
self.conditions.append({field: {"$lte": value}})
return self
def in_list(self, field, values):
self.conditions.append({field: {"$in": values}})
return self
def not_in(self, field, values):
self.conditions.append({field: {"$nin": values}})
return self
def build(self):
if len(self.conditions) == 0:
return {}
elif len(self.conditions) == 1:
return self.conditions[0]
else:
return {"$and": self.conditions}
filter_builder = MetadataFilterBuilder()
filters = (filter_builder
.eq("category", "technology")
.gte("views", 1000)
.in_list("tags", ["AI", "ML"])
.build()
)
results = index.query(
vector=query_vector,
top_k=10,
filter=filters
)
Node.js 示例 #
javascript
const { Pinecone } = require('@pinecone-database/pinecone');
async function metadataFilterExample() {
const pc = new Pinecone({
apiKey: process.env.PINECONE_API_KEY
});
const index = pc.index('my-index');
const results = await index.query({
vector: [0.1, 0.2, 0.3],
topK: 10,
includeMetadata: true,
filter: {
$and: [
{ category: { $in: ['technology', 'science'] } },
{ views: { $gte: 1000 } },
{ published: true }
]
}
});
console.log(`找到 ${results.matches.length} 个结果`);
results.matches.forEach(match => {
console.log(`ID: ${match.id}`);
console.log(`Score: ${match.score}`);
console.log(`Category: ${match.metadata.category}`);
console.log('---');
});
}
metadataFilterExample();
下一步 #
现在你已经掌握了元数据过滤，接下来学习 集成应用，了解如何将 Pinecone 与 OpenAI、LangChain 等工具集成！
最后更新：2026-04-04