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.

Built-in metadata attributes

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

Attribute	Description	Example
`filename`	The name of the file.	`guide.pdf` or `docs/getting-started/guide.pdf`
`folder`	The folder or prefix to the object.	For `docs/getting-started/guide.pdf`, the folder is `docs/getting-started/`
`timestamp`	Unix timestamp (milliseconds) when the object was last modified. Comparisons round down to seconds.	`1735689600000` (2025-01-01 00:00:00 UTC)

Custom metadata attributes

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.

Supported data types

Type	Description	Example values
`text`	String values (max 500 characters)	`"documentation"`, `"blog-post"`
`number`	Numeric values (parsed as float)	`2.5`, `100`, `-3.14`
`boolean`	Boolean values	`true`, `false`, `1`, `0`, `yes`, `no`
`datetime`	Date and time values	`"2026-01-15T00:00:00Z"`

Define a schema

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

Add custom metadata attributes to 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.

Re-indexing behavior

When you modify the custom_metadata schema:

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

Limitations

Constraint	Limit
Maximum custom fields	5 per AI Search instance
Maximum text value length	500 characters
Reserved field names	`timestamp`, `folder`, `filename`
Field name matching	Case-insensitive

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.