Amazon S3 Vectors の filterable metadata が 40 KB に拡張されたので試してみた

Amazon S3 Vectors の filterable metadata が 40 KB に拡張されたので試してみた

1 ベクトルあたりの上限が 2 KB から 40 KB に引き上げられました。新しいバケットのインデックスで約 38 KB を書き込み、短い属性と 2,000 バイトの属性のどちらでも絞り込めたので、その手順と結果を紹介します。
2026.11.22

はじめに

2026年11月20日に、Amazon S3 Vectors の filterable metadata の上限が、1 ベクトルあたり 2 KB から 40 KB に拡張されました。新しいベクトルバケット(2026年9月30日以降に作成したもの)のインデックスでは、この上限が既定で使えます。

https://aws.amazon.com/about-aws/whats-new/2026/11/amazon-s3-vectors-raises-filterable-metadata-40kb-per-vector/

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 近いメタデータは、複数のキーに分けて持たせます。

https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-vectors-limitations.html

値が 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 に変更する方法は、次のドキュメントに記載されています。

https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-vectors-index-mode.html

まとめ

ENHANCED のインデックスで、S3 Vectors に約 38 KB の filterable metadata を書き込めることを確認できました。

S3 Vectors ハイブリッド検索(ベクトル+全文)も利用可能になりました。
従来、filterable metadata 2 KB の上限などを理由に、S3 Vectors の採用を見送られていた場合、今回のアップデート含めて改めて評価頂くことをおすすめします。

https://dev.classmethod.jp/articles/s3-vectors-hybrid-search-try/

この記事をシェアする

AWSのお困り事はクラスメソッドへ

関連記事