View a markdown version of this page

Vector indexes - Amazon Simple Storage Service
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Vector indexes

Note

Choose your vector index configuration parameters carefully. After you create a vector index, you can't update the vector index name, dimension, distance metric, or non-filterable metadata keys. To change any of these values, you must create a new vector index.

Vector indexes are resources within vector buckets that store and organize vector data for efficient similarity search operations. When you create a vector index, you specify the distance metric (Cosine or Euclidean), the number of dimensions that a vector should have, and optionally a list of metadata keys that you want to exclude from filtering, or enable for full-text search.

For more information about vector index limits per bucket, vector limits per index, and dimension limits per vector, see Limitations and restrictions.

Each vector index has a unique Amazon Resource Name (ARN). The ARNs of vector indexes follow the following format:

arn:aws:s3vectors:region:account-id:bucket/bucket-name/index/index-name

Vector index naming requirements

  • Vector index names must be unique within the vector bucket.

  • Vector index names must be between 3 and 63 characters long.

  • Valid characters are lowercase letters (a-z), numbers (0-9), hyphens (-), and dots (.).

  • Vector index names must begin and end with a letter or number.

Dimension requirements

A dimension is the number of values in a vector. All vectors added to the index must have exactly this number of values.

  • A dimension must be an integer between 1 and 4096.

  • A larger dimension requires more storage space.

Distance metric options

Distance metric specifies how similarity between vectors is calculated. When creating vector embeddings, choose your embedding model's recommended distance metric for more accurate results.

  • Cosine – Measures the cosine of the angle between vectors. Best for normalized vectors and when direction matters more than magnitude.

  • Euclidean – Measures the straight-line distance between vectors. Best when both direction and magnitude are important.

Non-filterable metadata keys

Metadata keys allow you to attach additional information to your vectors as key-value pairs during storage and retrieval. By default, all metadata is filterable, so you can use it to filter query results. However, you can designate specific metadata keys as non-filterable when you want to store information with vectors without using it for filtering.

Unlike default metadata keys, these keys can't be used as query filters. Non-filterable metadata keys can be retrieved but can't be searched, queried, or filtered. You can only access it after finding the index.

Non-filterable metadata keys allow you to enrich vectors with additional context that you want to retrieve with search results but don't need for filtering. A common example of a non-filterable metadata key is when you embed text into vectors and want to include the original text itself as non-filterable metadata. This allows you to return the source text alongside vector search results without increasing your filterable metadata size limits. Other examples include storing creation timestamps, source URLs, or descriptive information purely for reference. Non-filterable metadata keys can be accessed when retrieving vectors but, unlike default metadata keys, these keys can't be used as query filters.

Requirements for non-filterable metadata keys are as follows.

  • Non-filterable metadata keys must be unique within the vector index.

  • Non-filterable metadata keys must be 1 to 63 characters long.

  • Non-filterable metadata keys can't be modified after the vector index is created.

  • S3 Vectors support up to 10 non-filterable metadata keys per index.

For more information about non-filterable metadata keys, see Non-filterable metadata.

You can enable full-text search on a metadata key. S3 Vectors builds a full-text search index over that key's values for BM25 (Best Matching 25) scoring, so you can run full-text and hybrid queries on the index. You configure full-text search keys in the index's metadata configuration, either when you create the index or on an existing index.

Requirements for full-text search metadata keys are as follows.

  • Full-text search is supported only on ENHANCED indexes. To use it on a CLASSIC index, upgrade the index first.

  • By default, S3 Vectors uses a standard analyzer. You can optionally choose a language-specific analyzer. S3 Vectors supports 10 languages.

  • You can't change an existing full-text search configuration, such as its analyzer, after you set it. To change it, remove the key and add it back.

  • For the size and number limits of searchable fields, see Limitations and restrictions.

For more information, see Configuring full-text search and Hybrid search with Amazon S3 Vectors.

Index mode

Each vector index has an index mode, which determines the query capabilities the index supports. The modes are ENHANCED and CLASSIC. We recommend ENHANCED for almost all workloads, because it gives you higher recall on filtered queries and additional filter operators. For what each mode supports, see Metadata filtering.

A new vector index inherits the default index mode of the vector bucket that contains it. A vector bucket created on or after September 30, 2026 has a default index mode of ENHANCED, and indexes in it cannot use CLASSIC. A vector bucket created before that date has a default index mode of CLASSIC, so that indexes you already had are unchanged and indexes you create in it later behave consistently with them.

You can read an index's mode with GetIndex and change it with UpdateIndexMode. You can read a bucket's default with GetVectorBucket and change it with PutVectorBucketDefaultIndexMode, which applies to indexes you create afterward. To move an existing index, see Changing a vector index's mode.