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
• Text values are truncated to 500 characters
• 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.

If file metadata exceeds size limits, the metadata is replaced with an error indicator:

{
	"file": { "error": "metadata is too large" }
}

To avoid this, keep individual metadata values concise.