# 元数据筛选
<a name="s3-vectors-metadata-filtering"></a>

元数据筛选支持您根据附加到向量的特定属性来筛选查询结果。可以将元数据筛选条件与查询操作结合使用，来查找既符合相似性标准又满足特定元数据条件的向量。

S3 Vectors 支持两种类型的元数据：可筛选的元数据和不可筛选的元数据。关键区别在于，可筛选的元数据可以在查询筛选条件中使用，但具有更严格的大小限制；而不可筛选的元数据不能在筛选条件中使用，但可以在其大小限制内存储更大的数据量。有关元数据限制（包括每个向量的大小限制和每个向量的最大元数据键数）的更多信息，请参阅[限制和局限性](s3-vectors-limitations.md)。

S3 Vectors 同时执行向量搜索和筛选条件评估。S3 Vectors 在索引中搜索候选向量，以找到前 K 个相似向量，同时验证每个候选向量是否符合元数据筛选条件。例如，如果您搜索相似的电影嵌入并按 genre=“mystery”进行筛选，则 S3 Vectors 仅返回 genre 元数据与“mystery”匹配的相似电影嵌入。与在向量搜索之后应用元数据筛选条件相比，这种筛选方法更有可能找到匹配的结果。注意：当向量索引包含的匹配结果非常少时，带筛选条件的查询返回的结果可能少于前 K 个。

**Topics**
+ [可筛选的元数据](#s3-vectors-metadata-filtering-filterable)
+ [有效可筛选元数据示例](#s3-vectors-metadata-filtering-examples)
+ [不可筛选的元数据](#s3-vectors-metadata-filtering-non-filterable)

## 可筛选的元数据
<a name="s3-vectors-metadata-filtering-filterable"></a>

可筛选的元数据支持您根据特定的元数据值来筛选查询结果。默认情况下，在相似性查询中所有元数据字段均为可筛选的，除非在创建向量索引时显式指定为不可筛选的。S3 Vectors 支持字符串、数字、布尔值和列表类型的元数据，每个向量都有大小限制。元数据类型非常适合要据以进行筛选的属性，例如类别、时间戳或状态值。

如果元数据大小超过支持的限制，[PutVectors](https://docs.aws.amazon.com/AmazonS3/latest/API/API_S3VectorBuckets_PutVectors.html) API 操作将返回 `400 Bad Request` 错误。有关每个向量的可筛选元数据大小限制的更多信息，请参阅[限制和局限性](s3-vectors-limitations.md)。

以下操作可用于可筛选的元数据。


| 运算符 | 有效输入类型 | 说明 | 
| --- | --- | --- | 
| \$1eq | 字符串、数字、布尔值 | 单个值的精确匹配比较。与数组元数据值进行比较时，如果输入值与数组中的任何元素匹配，则返回 true。例如，`{"category": {"$eq": "documentary"}}` 将与具有元数据 `"category": ["documentary", "romance"]` 的向量匹配。 | 
| \$1ne | 字符串、数字、布尔值 | “不等于”比较 | 
| \$1gt | 数字 | “大于”比较 | 
| \$1gte | 数字 | “大于或等于”比较 | 
| \$1lt | 数字 | “小于”比较 | 
| \$1lte | 数字 | “小于或等于”比较 | 
| \$1in | 基元的非空数组 | 匹配数组中的任何值 | 
| \$1nin | 基元的非空数组 | 不匹配数组中的任何值 | 
| \$1exists | 布尔值 | 检查字段是否存在 | 
| \$1and | 筛选条件的非空数组 | 多个条件的逻辑 AND | 
| \$1or | 筛选条件的非空数组 | 多个条件的逻辑 OR | 

## 有效可筛选元数据示例
<a name="s3-vectors-metadata-filtering-examples"></a>

**简单相等**  

```
{"genre": "documentary"}
```
此筛选条件匹配 genre 元数据键等于“documentary”的向量。当您未指定运算符时，S3 Vectors 会自动使用 \$1eq 运算符。

**显式相等**  

```
// Example: Exact match
{"genre": {"$eq": "documentary"}}
```

```
// Example: Not equal to
{"genre": {"$ne": "drama"}}
```

**数值比较**  

```
{"year": {"$gt": 2019}}
```

```
{"year": {"$gte": 2020}}
```

```
{"year": {"$lt": 2020}}
```

```
{"year": {"$lte": 2020}}
```

**数组运算**  

```
{"genre": {"$in": ["comedy", "documentary"]}}
```

```
{"genre": {"$nin": ["comedy", "documentary"]}}
```

**存在性检查**  

```
{"genre": {"$exists": true}}
```
`$exists` 筛选条件匹配具有“genre”元数据键的向量，而不考虑为该元数据键存储的值。

**逻辑运算**  

```
{"$and": [{"genre": {"$eq": "drama"}}, {"year": {"$gte": 2020}}]}
```

```
{"$or": [{"genre": {"$eq": "drama"}}, {"year": {"$gte": 2020}}]}
```

**价格范围（同一字段有多个条件）**  

```
{"price": {"$gte": 10, "$lte": 50}}
```

有关如何使用元数据筛选来查询向量的更多信息，请参阅[元数据筛选](s3-vectors.md#s3-vectors-filtering-metadata)。

## 不可筛选的元数据
<a name="s3-vectors-metadata-filtering-non-filterable"></a>

不可筛选的元数据不能在查询筛选条件中使用，但与可筛选元数据相比，可以存储更多的上下文数据。它非常适合存储大型文本分块、详细描述或其它上下文信息，这些信息不需要是可搜索的，但可以与查询结果一起返回。例如，可以将完整的文档文本、图片描述或详细的产品规格存储为不可筛选的元数据。

在创建向量索引期间，必须显式配置不可筛选的元数据键。一旦元数据键在创建索引期间被指定为不可筛选，以后就无法将其更改为可筛选。可以针对每个向量索引将多个元数据键配置为不可筛选，每个元数据键名称限制为 63 个字符。有关每个向量索引支持的最大不可筛选元数据键数量的更多信息，请参阅[限制和局限性](s3-vectors-limitations.md)。

尽管无法对不可筛选的元数据进行筛选，但可以使用 `return-metadata` 参数将其与查询结果一起检索。对于某些使用案例，可以使用不可筛选的元数据，如下所示。
+ 使用它可为应用程序提供上下文，而无需解析单独的数据来源。
+ 存储超过可筛选元数据大小限制的较大文本分块。
+ 使用 [ListVectors](https://docs.aws.amazon.com/AmazonS3/latest/API/API_S3VectorBuckets_ListVectors.html) API 操作将其包含在向量导出中。

有关配置不可筛选的元数据的更多信息，请参阅[在向量存储桶中创建向量索引](s3-vectors-create-index.md)。