
Amazon S3 Vectors の filterable metadata が 40 KB に拡張されたので試してみた
はじめに
2026年11月20日に、Amazon S3 Vectors の filterable metadata の上限が、1 ベクトルあたり 2 KB から 40 KB に拡張されました。新しいベクトルバケット(2026年9月30日以降に作成したもの)のインデックスでは、この上限が既定で使えます。
filterable metadata は、QueryVectors の filter に使えるメタデータです。この記事では、新しいバケットのインデックスで約 38 KB の filterable metadata を使う手順を紹介します。あわせて、既存のインデックスで 40 KB の上限を使う方法が載っているドキュメントも紹介します。
検証環境
- リージョン: 東京(ap-northeast-1)
- AWS CLI: 2.42.1
- インデックス: float32、4 次元、cosine
- メタデータ設定:
--metadata-configurationを指定しないため、全キーが filterable
バケットとインデックスの作成
インデックスのモードは指定せず、任意のバケット名でバケットとインデックスを作成します。
aws s3vectors create-vector-bucket --vector-bucket-name amzn-s3-demo-vector-bucket
aws s3vectors create-index --vector-bucket-name amzn-s3-demo-vector-bucket --index-name idx-40kb --data-type float32 --dimension 4 --distance-metric cosine
バケットの defaultIndexMode と、インデックスの indexMode を確認します。filterable metadata を 40 KB まで使うには、インデックスが ENHANCED である必要があります。
aws s3vectors get-vector-bucket --vector-bucket-name amzn-s3-demo-vector-bucket
{
"vectorBucket": {
"vectorBucketName": "amzn-s3-demo-vector-bucket",
"defaultIndexMode": "ENHANCED"
}
}
aws s3vectors get-index --vector-bucket-name amzn-s3-demo-vector-bucket --index-name idx-40kb
{
"index": {
"vectorBucketName": "amzn-s3-demo-vector-bucket",
"indexName": "idx-40kb",
"dataType": "float32",
"dimension": 4,
"distanceMetric": "cosine",
"indexMode": "ENHANCED"
}
}
検証用データ
文字列の値は 1 つあたり 2 KB までです。40 KB 近いメタデータは、複数のキーに分けて持たせます。
値が 2,000 バイトの文字列のキーを 19 個(pad_01 から pad_19)用意し、絞り込み用の短いキー category と tenant を加えました。合計 21 キーで約 38 KB です。バイト数は、メタデータを空白なしの JSON にしたときの UTF-8 の長さです。
ベクトルは次の 3 件です。
- big-manual-a: メタデータ約 38 KB(category は manual、tenant は a)
- big-faq-a: メタデータ約 38 KB(category は faq、tenant は a)
- small-manual-b: メタデータ 34 バイト(category は manual、tenant は b)
次の gen_vectors.py で、カレントディレクトリに vectors.json を作ります。
gen_vectors.py
#!/usr/bin/env python3
"""filterable metadata が約 38 KB のベクトルを含む vectors.json を生成する。
1 値あたり 2,000 バイトの文字列キー pad_01..pad_19 を重ねて約 38 KB にする。
末尾に絞り込み用の短いキー(category, tenant)を置く。
"""
import json
PAD_KEYS = 19
PAD_BYTES = 2000 # 1 値の上限 2 KB 以内
def pad(n: int, doc: str) -> str:
head = f"{doc}-pad{n:02d}-"
return head + "x" * (PAD_BYTES - len(head))
def big(key: str, data, category: str, tenant: str) -> dict:
md = {f"pad_{i:02d}": pad(i, key) for i in range(1, PAD_KEYS + 1)}
md["category"] = category
md["tenant"] = tenant
return {"key": key, "data": {"float32": data}, "metadata": md}
vectors = [
big("big-manual-a", [0.1, 0.2, 0.3, 0.4], "manual", "a"),
big("big-faq-a", [0.2, 0.1, 0.4, 0.3], "faq", "a"),
{
"key": "small-manual-b",
"data": {"float32": [0.4, 0.3, 0.2, 0.1]},
"metadata": {"category": "manual", "tenant": "b"},
},
]
with open("vectors.json", "w") as f:
json.dump(vectors, f)
for v in vectors:
size = len(json.dumps(v["metadata"], separators=(",", ":")).encode())
print(f'{v["key"]}: metadata {size} bytes ({size/1024:.1f} KiB)')
python3 gen_vectors.py
書き込みと保存の確認
vectors.json を、追加のパラメータなしで put-vectors に渡します。
aws s3vectors put-vectors --vector-bucket-name amzn-s3-demo-vector-bucket --index-name idx-40kb --vectors file://vectors.json
何も出力されず、正常に終了しました。
続いて get-vectors で保存内容を取得し、check_stored.py でメタデータのバイト数とキー数を数え、内容が vectors.json と一致するかを確認します。
check_stored.py
import json
import sys
got = {v["key"]: v["metadata"] for v in json.load(open(sys.argv[1]))["vectors"]}
src = {v["key"]: v["metadata"] for v in json.load(open(sys.argv[2]))}
for k in src:
size = len(json.dumps(got[k], separators=(",", ":")).encode())
print(f"{k}: stored_metadata_bytes={size} keys={len(got[k])} identical_to_put={got[k] == src[k]}")
aws s3vectors get-vectors --vector-bucket-name amzn-s3-demo-vector-bucket --index-name idx-40kb --keys big-manual-a big-faq-a small-manual-b --return-metadata --no-return-data --output json > get-vectors.json
python3 check_stored.py get-vectors.json vectors.json
big-manual-a: stored_metadata_bytes=38262 keys=21 identical_to_put=True
big-faq-a: stored_metadata_bytes=38259 keys=21 identical_to_put=True
small-manual-b: stored_metadata_bytes=34 keys=2 identical_to_put=True
絞り込み検索
フィルタなしと 3 種類のフィルタで query-vectors を実行し、返ってくるベクトルのキーを比べます。クエリベクトルは query-vector.json に保存します。
{"float32":[0.1,0.2,0.3,0.4]}
filter-category.json の内容です。
{"category": {"$eq": "manual"}}
filter-and.json の内容です。
{"$and": [{"category": {"$eq": "manual"}}, {"tenant": {"$eq": "a"}}]}
filter-pad19.json は、big-faq-a の pad_19 の値(2,000 バイト)を $eq に指定したものです。次のコマンドで作れます。
python3 -c 'import json; print(json.dumps({"pad_19": {"$eq": "big-faq-a-pad19-".ljust(2000, "x")}}), end="")' > filter-pad19.json
<filter-file> を各フィルタのファイル名に置き換えて実行します。表の「なし」は、--filter を外して実行した結果です。
aws s3vectors query-vectors --vector-bucket-name amzn-s3-demo-vector-bucket --index-name idx-40kb --top-k 10 --query-vector file://query-vector.json --return-distance --no-return-metadata --filter file://<filter-file>
| フィルタ | 返ったベクトルのキー | 件数 |
|---|---|---|
| なし | big-manual-a, big-faq-a, small-manual-b | 3 |
| filter-category.json | big-manual-a, small-manual-b | 2 |
| filter-and.json | big-manual-a | 1 |
| filter-pad19.json | big-faq-a | 1 |
メタデータが約 38 KB のベクトルを、短い値の category と tenant でも、2,000 バイトの値の pad_19 でも絞り込めました。
既存インデックスで使う場合
2026年9月30日より前に作成したバケットの CLASSIC のインデックスを ENHANCED に変更する方法は、次のドキュメントに記載されています。
まとめ
ENHANCED のインデックスで、S3 Vectors に約 38 KB の filterable metadata を書き込めることを確認できました。
S3 Vectors ハイブリッド検索(ベクトル+全文)も利用可能になりました。
従来、filterable metadata 2 KB の上限などを理由に、S3 Vectors の採用を見送られていた場合、今回のアップデート含めて改めて評価頂くことをおすすめします。









