メタデータ属性

メタデータ属性を使うと、インデックスしたドキュメントを整理し、AI の応答を導く文脈を渡せます。このページでは、組み込みのメタデータ属性とカスタムメタデータのスキーマを扱います。クエリ時にこれらの属性で検索結果をフィルタするには、フィルタリング を参照してください。

AI Search は、インデックスしたドキュメントから次のメタデータ属性を自動で抽出します。

カスタムメタデータを使うと、検索結果のフィルタ用に追加フィールドを定義できます。ドキュメントに構造化メタデータを付け、カテゴリ、バージョン、任意のカスタムフィールドでクエリをフィルタできます。

カスタムメタデータを抽出するには、先に AI Search の設定で custom_metadata フィールドを使いスキーマを定義します。スキーマは、抽出するフィールドとそのデータ型を指定します。

custom_metadata: [
	{ field_name: "category", data_type: "text" },
	{ field_name: "version", data_type: "number" },
	{ field_name: "is_public", data_type: "boolean" },
];

スキーマの制約:

• AI Search インスタンスあたり、カスタムメタデータフィールドは最大 5 つです
• フィールド名は大文字と小文字を区別せず、小文字で保存します
• フィールド名に予約名は使えません: timestamp、folder、filename
• スキーマを変更すると、全ドキュメントの再インデックスが始まります

カスタムメタデータ属性の付け方は、データソースによって異なります。

• R2 bucket: S3 互換のカスタムヘッダー（x-amz-meta-*）でメタデータを設定します。例は R2 のカスタムメタデータ を参照してください。
• Website: HTML ページに <meta> タグを追加します。詳細は Web サイトのカスタムメタデータ を参照してください。
• 組み込みストレージ: Items API でファイルをアップロードするときにメタデータを付けます。

custom_metadata スキーマを変更すると、次の処理が行われます。

1. 新しいフィールドが検索インデックスに追加されます。
2. 削除したフィールドは検索インデックスから消えます。
3. 全ドキュメントの再インデックスが始まります。
4. 既存のベクトルは、新しいメタデータ構造で更新されます。

AI Search は、各ベクトルのメタデータを、共有の 10 KiB コンパクト JSON UTF-8 エンベロープに保存します。エンベロープには、フィールド名、JSON 構文、必須の AI Search システムメタデータ、顧客メタデータが含まれます。フィールドごとの上限ではありません。

設定したカスタムフィールドは、宣言していないソースメタデータより優先されます。AI Search はメタデータを決定的に組み立て、収まる完全な値を残します。容量が残っている場合、設定した文字列値は UTF-8 の文字境界で切り詰められます。必須の AI Search メタデータは常に保持します。

インデックスした各文字列のうち、フィルタできるのは先頭 64 UTF-8 バイトだけです。より長い文字列も保存できますが、先頭 64 バイト以降はフィルタできません。Vectorize の詳細は 上限 と メタデータフィルタリング を参照してください。