Metadata attributes

Use metadata attributes to organize your indexed documents and provide context to guide AI responses. This page covers built-in metadata attributes and custom metadata schemas. To filter search results by these attributes at query time, refer to Filtering.

AI Search automatically extracts the following metadata attributes from your indexed documents:

Custom metadata allows you to define additional fields for filtering search results. You can attach structured metadata to documents and filter queries by attributes such as category, version, or any custom field.

Before custom metadata can be extracted, define a schema in your AI Search configuration using the custom_metadata field. The schema specifies which fields to extract and their data types.

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

Schema constraints:

• Maximum of 5 custom metadata fields per AI Search instance
• Field names are case-insensitive and stored as lowercase
• Field names cannot use reserved names: timestamp, folder, filename
• Changing the schema triggers a full re-index of all documents

How you attach custom metadata attributes depends on your data source:

• R2 bucket: Set metadata using S3-compatible custom headers (x-amz-meta-*). Refer to R2 custom metadata for examples.
• Website: Add <meta> tags to your HTML pages. Refer to Website custom metadata for details.
• Built-in storage: Attach metadata when uploading files through the Items API.

When you modify the custom_metadata schema:

1. New fields are added to the search index.
2. Removed fields are deleted from the search index.
3. A full re-index is triggered for all documents.
4. Existing vectors are updated with the new metadata structure.

AI Search stores metadata for each vector in a shared 10 KiB compact JSON UTF-8 envelope. The envelope includes field names, JSON syntax, required AI Search system metadata, and customer metadata. It is not a per-field limit.

Configured custom fields take priority over undeclared source metadata. AI Search assembles metadata deterministically, retaining complete values that fit. When capacity remains, configured string values can be truncated on UTF-8 character boundaries. Required AI Search metadata is always preserved.

Only the first 64 UTF-8 bytes of each indexed string are filterable. Longer strings can be stored, but bytes after the first 64 are not filterable. For Vectorize details, refer to Limits and Metadata filtering.