Amazon S3 Vectors Movies Demo

The Amazon S3 Vectors Movies Demo is a Next.js application that searches a catalogue of 4,799 films by describing a plot, mood, or premise instead of typing a title, using Amazon S3 Vectors as the nearest-neighbour index and Amazon Titan Text Embeddings V2 for the vectors.

What is the Amazon S3 Vectors Movies Demo?

It is a reference demo built by Vercel that pairs AWS Amazon S3 Vectors with a Next.js frontend to run semantic movie search. You type free text into a search box; the app embeds the query and asks the S3 Vectors index for its nearest neighbours by cosine distance, returning the closest films. Data comes from the TMDB 5000 Movie Dataset (4,799 titles), and the app connects to AWS through Vercel OIDC Federation rather than hardcoded access keys.

Key Features

• Semantic vector search — a query like dinosaurs escape and hunt people returns Jurassic Park first, followed by Jurassic Park III and The Lost World, even though the phrase appears nowhere in the titles or plot summaries.
• Precomputed embeddings — a committed 19 MB embeddings.bin file is generated by pnpm db:precompute and checked in, so builds stay fast and deterministic.
• 1024-dimension Titan V2 vectors — the app chose 1024 dimensions over 512 (MRR 0.47) and 256 (0.37), reaching 11 of 12 correct on its relevance set with an MRR of 0.68.
• Titles excluded from embeddings — only plot summary and genres are embedded, which lifted top-8 recall from 9/12 to 11/12; titles remain as display metadata.
• Keyless AWS access — OIDC Federation supplies credentials, and the index is tagged with the install's VercelInstallId because the provisioned role only authorises tagged indexes.
• Vercel AI Gateway for embedding — the integration role lacks bedrock:InvokeModel, so Titan is reached through AI Gateway behind one function in lib/ai/embeddings.ts.
• Non-filterable overview metadata — plot summaries are declared non-filterable at index creation to stay under the 2 KB filterable-metadata cap.
• Build-time setup and seeding — vercel.json runs db:setup && db:seed, both idempotent (existing index counts as success; seeds upsert by vector key).

How does the Amazon S3 Vectors Movies Demo work?

1. Deploy with the Vercel button, which clones the repo, creates a project, sets up the AWS integration, and provisions an S3 vector bucket.
2. Locally, run vercel link, vercel env pull, pnpm install, pnpm db:setup, pnpm db:seed, and pnpm dev.
3. At request time the search box embeds your query and queries the index for nearest neighbours.

Who should use the Amazon S3 Vectors Movies Demo?

• Next.js developers evaluating S3 Vectors as a managed vector store for a search feature.
• Vercel users who want a working example of OIDC Federation with AWS instead of stored access keys.
• ML engineers tuning retrieval who want a documented relevance comparison of embedding dimensions and text fields.

What can you do with the Amazon S3 Vectors Movies Demo?

• Prototype semantic search: clone, deploy, and get a working vector index plus 4,799 seeded movies without writing index-creation code.
• Tune retrieval quality: adapt lib/ai/embeddings.ts and the index configuration to test which text fields and dimensions help your own corpus.
• Study IAM tagging requirements: use lib/db/setup.ts as a reference for copying bucket tags onto a newly created index.

Pros and cons

• Every search costs one embedding and one vector query, and nothing authenticates the q parameter.
• The index name is identical across environments, so preview deployments re-seed the index production reads unless you set S3_VECTOR_INDEX_NAME.
• The OIDC token written by vercel env pull is short-lived and needs re-pulling after a few hours.

FAQ

Does the app need hardcoded AWS access keys?

No. It authenticates through Vercel OIDC Federation, and the embedding calls go through Vercel AI Gateway using the same OIDC token because the provisioned role grants only S3 Vectors actions.

Why are movie titles not embedded?

Titles and taglines are short and carry disproportionate weight, pulling results toward films whose titles share words with the query. Dropping them raised top-8 recall from 9/12 to 11/12 on the project's relevance set.

Why does the index need a tag?

The provisioned role only authorises CreateIndex when the request tags the new index with the install's VercelInstallId, and that tag is required on every read and write. Missing it returns an AccessDenied that never mentions tags.