Amazon S3 Vectors integration

Amazon S3 Vectors is cloud object storage with native support for storing and querying vectors. It is built for large vector datasets that do not need the high-throughput, low-latency profile of an in-memory vector database, and it requires no infrastructure to provision.

This page covers how to use the AmazonS3Vectors vector store from the langchain-aws package.

Setup

Installation

pip install -U langchain-aws

uv add langchain-aws

AmazonS3Vectors requires langchain-aws>=0.2.31.

Create a vector bucket

You must create an S3 vector bucket before using this store. The vector index is created for you on first write unless you pass create_index_if_not_exist=False.

aws s3vectors create-vector-bucket --vector-bucket-name my-vector-bucket

This requires the s3vectors:CreateVectorBucket permission. For more detail, see Getting started with S3 Vectors.

Credentials

The store uses the standard AWS credential chain. You can also pass region_name, credentials_profile_name, or an existing boto3 client.

Initialization

from langchain_aws import BedrockEmbeddings
from langchain_aws.vectorstores import AmazonS3Vectors

embeddings = BedrockEmbeddings(model_id="amazon.titan-embed-text-v2:0")

vector_store = AmazonS3Vectors(
    vector_bucket_name="my-vector-bucket",
    index_name="my-index",
    embedding=embeddings,
)

Index names must be 3 to 63 characters long, start and end with a letter or number, and contain only lowercase letters, numbers, hyphens and dots.

Manage vector store

Add items

from langchain_core.documents import Document

vector_store.add_documents(
    [
        Document("Star Wars", id="key1", metadata={"genre": "scifi"}),
        Document("Jurassic Park", id="key2", metadata={"genre": "scifi"}),
        Document("Finding Nemo", id="key3", metadata={"genre": "family"}),
    ]
)

You can also build the store and add texts in one call:

vector_store = AmazonS3Vectors.from_texts(
    ["hello", "developer", "wife"],
    vector_bucket_name="my-vector-bucket",
    index_name="my-index",
    embedding=embeddings,
)

Delete items

vector_store.delete(ids=["key1", "key2"])

Calling delete() without ids deletes the entire vector index and everything in it. Always pass ids unless you intend to drop the index.

Get items by ID

docs = vector_store.get_by_ids(["key1", "key3"])

If any requested ID is missing, get_by_ids raises ValueError and returns nothing, rather than returning the subset it found.

Query

Similarity search

results = vector_store.similarity_search("adventures in space", k=2)

for doc in results:
    print(doc.page_content)

Similarity search with score

The score returned is a distance, so lower values indicate a closer match.

results = vector_store.similarity_search_with_score("adventures in space", k=2)

for doc, score in results:
    print(score, doc.page_content)

Metadata filtering

Filters use the S3 Vectors filter syntax:

vector_store.similarity_search_with_score(
    "adventures in space",
    filter={"genre": {"$eq": "family"}},
)

See Metadata filtering for the supported operators.

Search by vector

results = vector_store.similarity_search_by_vector(embeddings.embed_query("space"), k=2)

Configuration

Distance metric

distance_metric accepts cosine (the default) or euclidean. It is fixed when the index is created, so changing it afterwards has no effect on an existing index.

vector_store = AmazonS3Vectors(
    vector_bucket_name="my-vector-bucket",
    index_name="my-index",
    embedding=embeddings,
    distance_metric="euclidean",
)

Non-filterable metadata

Metadata keys listed in non_filterable_metadata_keys are stored and returned with the document, but cannot be used in filters. Filtering on one raises a ValidationException. This is set when the index is created.

vector_store = AmazonS3Vectors(
    vector_bucket_name="my-vector-bucket",
    index_name="my-index",
    embedding=embeddings,
    non_filterable_metadata_keys=["raw_source"],
)

Page content storage

By default the document text is stored in metadata under the _page_content key. Set page_content_metadata_key to change that key, or to None to embed the text without storing it, in which case retrieved documents have an empty page_content. Metadata is subject to the S3 Vectors limitations and restrictions, including a 40 KB total metadata limit per vector.

Use as a retriever

retriever = vector_store.as_retriever(search_kwargs={"k": 2})
retriever.invoke("adventures in space")

API reference

For detailed documentation of all features and configuration options, see the AmazonS3Vectors API reference.

Connect these docs to your agent of choice via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Popular Providers

Integrations by component

Setup

Installation

Create a vector bucket

Credentials

Initialization

Manage vector store

Add items

Delete items

Get items by ID

Query

Similarity search

Similarity search with score

Metadata filtering

Search by vector

Configuration

Distance metric

Non-filterable metadata

Page content storage

Use as a retriever

API reference

​Setup

​Installation

​Create a vector bucket

​Credentials

​Initialization

​Manage vector store

​Add items

​Delete items

​Get items by ID

​Query

​Similarity search

​Similarity search with score

​Metadata filtering

​Search by vector

​Configuration

​Distance metric

​Non-filterable metadata

​Page content storage

​Use as a retriever

​API reference

Setup

Installation

Create a vector bucket

Credentials

Initialization

Manage vector store

Add items

Delete items

Get items by ID

Query

Similarity search

Similarity search with score

Metadata filtering

Search by vector

Configuration

Distance metric

Non-filterable metadata

Page content storage

Use as a retriever

API reference