DocsDigest
Back to listLanguage: JA
OpenAICloudflare Developer PlatformMar 23, 2026, 12:00 AM

AI Search - Custom metadata filtering for AI Search

A condensed section focused on the key takeaways first.

Original Post
OpenAIClaude

Quick Digest

Summary

A condensed section focused on the key takeaways first.

openaienmodel: gpt-5-mini-2025-08-07

AI Search - Custom metadata filtering for AI Search

ai-searchmetadatafiltersr2apisearch

Key Points

  • Define up to 5 custom metadata fields
  • Supports text, number, and boolean types
  • Filter searches using custom fields (e.g., $gte)

Summary

AI Search now lets you define and use custom metadata fields to filter retrieval results. You can create up to 5 custom fields per AI Search instance (types: text, number, boolean), attach metadata at ingest, and include those fields in search filters alongside built-in attributes like folder and timestamp.

Key Points

  • Define custom metadata when creating an instance via the API using the custom_metadata array (max 5 fields). Example field entry: {"field_name": "category", "data_type": "text"}.
  • Supported data types: text, number, boolean.
  • Attach metadata depending on source:
    • R2: set S3-compatible custom headers x-amz-meta-* when uploading objects.
    • Website: add <meta> tags to HTML pages.
  • Filter search results by including custom fields in ai_search_options.retrieval.filters. Example filter snippet: "filters": { "category": "documentation", "version": { "$gte": 2.0 } }.
  • API calls require Authorization: Bearer {API_TOKEN} and Content-Type: application/json headers.

Practical notes for engineers

  • Each AI Search instance has a hard limit of 5 custom metadata fields; plan schema accordingly.
  • Use numeric operators (e.g., $gte) on number fields and boolean values for boolean fields.
  • Combine custom filters with existing filters (e.g., folder, timestamp) to narrow retrievals.
  • Example endpoints: create instance POST /accounts/{ACCOUNT_ID}/ai-search/instances with custom_metadata array; search POST /accounts/{ACCOUNT_ID}/ai-search/instances/{NAME}/search with ai_search_options.retrieval.filters.

Where to go next

Review your data ingestion path (R2 uploads or website pages) to ensure metadata is being written correctly, then update search queries to use the new filter fields.

Full Translation

Translations

A translation section that keeps the flow of the original article.

openaijamodel: gpt-5-mini-2025-08-07

AI Search - AI Search のカスタムメタデータフィルタリング

AI Search のカスタムメタデータフィルタリング

AI Search はカスタムメタデータによるフィルタリングをサポートするようになりました。category（カテゴリ）、version（バージョン）、あるいは任意に定義したカスタムフィールドなどに基づいて検索結果を絞り込むことができます。

カスタムメタデータスキーマを定義する

  • AI Search インスタンスごとに最大 5 個のカスタムメタデータフィールドを定義できます。各フィールドは名前とデータ型（text、number、boolean）を持ちます。

以下はインスタンス作成時の例です（curl）:

Terminal window
curl -X POST https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai-search/instances \ 
  -H "Content-Type: application/json" \ 
  -H "Authorization: Bearer {API_TOKEN}" \ 
  -d '{ "id": "my-instance", "type": "r2", "source": "my-bucket", "custom_metadata": [ { "field_name": "category", "data_type": "text" }, { "field_name": "version", "data_type": "number" }, { "field_name": "is_public", "data_type": "boolean" } ] }'

ドキュメントにメタデータを追加する

メタデータの付与方法はデータソースによって異なります。

  • R2 bucket: オブジェクトをアップロードする際に S3 互換のカスタムヘッダー（x-amz-meta-*）を使ってメタデータを設定します。詳しくは R2 custom metadata を参照してください。
  • Website: HTML ページに <meta> タグを追加してメタデータを設定します。詳しくは Website custom metadata を参照してください。

検索結果をフィルタリングする

定義したカスタムメタデータフィールドは、folder や timestamp のような組み込み属性と併せて検索クエリで指定できます。以下は検索リクエストの例です:

Terminal window
curl https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai-search/instances/{NAME}/search \ 
  -H "Content-Type: application/json" \ 
  -H "Authorization: Bearer {API_TOKEN}" \ 
  -d '{ "messages": [ { "content": "How do I configure authentication?", "role": "user" } ], "ai_search_options": { "retrieval": { "filters": { "category": "documentation", "version": { "$gte": 2.0 } } } } }'

詳細はメタデータフィルタリングのドキュメントを参照してください。