# メタデータフィルタリング
<a name="s3-vectors-metadata-filtering"></a>

メタデータフィルタリングを使用すると、ベクトルにアタッチされた特定の属性に基づいてクエリ結果をフィルタリングできます。クエリオペレーションでメタデータフィルターを使用して、類似度基準と特定のメタデータ条件の両方に一致するベクトルを検索できます。

S3 Vectors は、フィルタリング可能なメタデータとフィルタリング不可能なメタデータの 2 種類のメタデータをサポートしています。主な違いは、フィルタリング可能なメタデータはクエリフィルターで使用できますが、サイズ制限はより厳しく、フィルタリング不可能なメタデータはフィルターでは使用できませんが、サイズ制限内に大量のデータを保存できることです。ベクトルあたりのサイズ制限やベクトルあたりの最大メタデータキーなど、メタデータ制限の詳細については、「[制限と制約](s3-vectors-limitations.md)」を参照してください。

S3 Vectors は、ベクトル検索とフィルター評価を連動させて実行します。S3 Vectors は、インデックス内の候補ベクトルを検索して上位 K 個の類似ベクトルを見つけ、同時に各候補ベクトルがメタデータフィルター条件と一致するかどうかを検証します。例えば、類似の映画の埋め込みを検索し、genre='mystery' でフィルタリングする場合、S3 Vectors は、ジャンルメタデータが「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)」を参照してください。

フィルタリング可能なメタデータでは、次のオペレーションを使用できます。


| オペレーター | 有効な入力タイプ | 説明 | 
| --- | --- | --- | 
| $eq | 文字列、数値、ブール値 | 単一値の完全一致比較。<br />配列メタデータ値と比較する場合、入力値が配列内の任意の要素と一致すると、true を返します。例えば、`{"category": {"$eq": "documentary"}}` はベクトルをメタデータ `"category": ["documentary", "romance"]` と一致させます。 | 
| $ne | 文字列、数値、ブール値 | 等しくない比較 | 
| $gt | Number | より大きい比較 | 
| $gte | Number | より大きいまたは同じ比較 | 
| $lt | Number | 未満の比較 | 
| $lte | Number | 未満または同じ比較 | 
| $in | プリミティブの空でない配列 | 配列内の任意の値に一致 | 
| $nin | プリミティブの空でない配列 | 配列内のどの値とも一致しない | 
| $exists | ブール値 | フィールドが存在するかどうかを確認する | 
| $and | フィルターの空でない配列 | 複数の条件の論理 AND | 
| $or | フィルターの空でない配列 | 複数の条件の論理 OR | 

## 有効なフィルタリング可能なメタデータの例
<a name="s3-vectors-metadata-filtering-examples"></a>

**単純な等価**  

```
{"genre": "documentary"}
```
このフィルターは、genre メタデータキーが「documentary」と等しいベクトルに一致します。演算子を指定しない場合、S3 Vectors は自動的に $eq 演算子を使用します。

**明示的な等価**  

```
// 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)」を参照してください。