Storing And Querying Vectors

Store and Query Vectors with Amazon S3 Vectors

Overview

Amazon S3 Vectors is a cost-effective AWS service for storing and querying vector embeddings at scale. Optimized for long-term storage with subsecond latency for cold queries, as low as 100ms for warm queries.

Decision Guide

• Hundreds/thousands of sustained queries per second (QPS): Wrong tool. Recommend OpenSearch.
• Hybrid search, aggregations, faceted search: Recommend OpenSearch with S3 Vectors as storage engine. For OpenSearch integration, search AWS docs for "Using S3 Vectors with OpenSearch Service".
• Tiered (bulk + hot): S3 Vectors for storage + OpenSearch Serverless for real-time. See references/limits-and-patterns.md.
• Cost-effective storage, infrequent queries, RAG: S3 Vectors is the right fit. Proceed.

For latest guidance, search AWS docs for "S3 Vectors best practices".

Common Tasks

Classify the request before starting:

• Simple query: Existing index, skip to Step 6
• Standard: You MUST list existing indexes first and suggest reusing if relevant. Else, new index + store vectors, follow Steps 2-6
• Migration or multi-tenant: Read references/limits-and-patterns.md first, then Steps 2-6

You MUST execute commands using AWS MCP server tools when connected. Fall back to AWS CLI only if AWS MCP is unavailable. You MUST explain each step to the user before executing.

1. Verify Dependencies

Constraints:

• You MUST check whether AWS MCP tools or AWS CLI is available and inform user if missing
• You MUST confirm target AWS region

2. Create a Vector Bucket

You MUST confirm bucket name with user. Names: 3-63 chars, lowercase letters, numbers, hyphens only. Encryption (SSE-S3 default or SSE-KMS for compliance) is immutable after creation.

aws s3vectors create-vector-bucket \
  --vector-bucket-name <BUCKET_NAME>

Constraints:

• You MUST explain encryption cannot be changed after creation
• For SSE-KMS, KMS key policy MUST grant kms:GenerateDataKey and kms:Decrypt to the S3 Vectors service principal indexing.s3vectors.amazonaws.com. You MUST use full KMS key ARN (not alias). See references/limits-and-patterns.md for command example.

3. Create a Vector Index

Every parameter is immutable after creation.

Pre-flight checklist (confirm ALL with user):

1. Dimension (required, integer 1-4096) -- MUST match embedding model output 2. Distance metric (required) -- cosine or euclidean. Use embedding model's recommended metric; 3. Non-filterable metadata keys (optional, max 10, 1-63 chars) -- Declare at creation or lose forever. For Bedrock Knowledge Bases integration, search AWS docs for "S3 Vectors Bedrock Knowledge Bases prerequisites" to get the required key names. 4. Encryption (optional) -- Inherits from bucket. Override per-index if needed.

aws s3vectors create-index \
  --vector-bucket-name <BUCKET_NAME> \
  --index-name <INDEX_NAME> \
  --dimension <DIM> \
  --distance-metric <cosine|euclidean> \
  --data-type float32 \
  --metadata-configuration '{"nonFilterableMetadataKeys":["<KEY1>","<KEY2>"]}'

Omit --metadata-configuration if no non-filterable keys are needed.

Index names: 3-63 chars, lowercase, numbers, hyphens, dots. Unique within bucket. Filterable metadata: 2 KB limit. Total metadata (filterable + non-filterable combined): 40 KB. See references/metadata-filtering.md.

4. Generate Embeddings (if needed)

Skip to Step 5 (store) or Step 6 (query) if user already has embeddings.

Constraints:

• You MUST ask which embedding model to use if not specified
• You MUST NOT assume a default model
• Dimension MUST match Step 3
• You MUST use the same model for both storing and querying

Generate embeddings with Bedrock invoke-model:

aws bedrock-runtime invoke-model \
  --model-id <MODEL_ID> \
  --content-type application/json \
  --cli-binary-format raw-in-base64-out \
  --body '{"inputText": "your text"}' \
  invoke-model-output.json

You MUST use --cli-binary-format raw-in-base64-out for CLI v2. Output file is required for CLI. The response key is model-dependent (e.g., embedding for Titan, embeddings for Cohere). For Titan, parse with json.load(open('invoke-model-output.json'))['embedding']. Use embedding array as float32 in put-vectors or query-vectors. For batch embedding generation, use AWS SDK or CLI.

5. Put Vectors

aws s3vectors put-vectors \
  --vector-bucket-name <BUCKET_NAME> \
  --index-name <INDEX_NAME> \
  --vectors '[{"key":"<ID>","data":{"float32":[<EMBEDDING>]},"metadata":{"topic":"science"}}]'

Constraints:

• You MUST NOT exceed 500 vectors per call
• You SHOULD batch vectors for cost optimization
• For bulk operations, You SHOULD use an SDK instead of CLI -- vector payloads may be too large for shell arguments
• You MUST implement retry with backoff on 429 TooManyRequestsException
• See references/limits-and-patterns.md for batch patterns

6. Query Vectors

Generate embedding if needed (Step 4), then query:

aws s3vectors query-vectors \
  --vector-bucket-name <BUCKET_NAME> \
  --index-name <INDEX_NAME> \
  --query-vector '{"float32":[<EMBEDDING>]}' \
  --top-k 10 \
  --return-distance

Optional: add --return-metadata and/or --filter '{"topic":{"$eq":"science"}}' (both require GetVectors permission). See references/metadata-filtering.md.

Example response body: {"vectors": [{"key": "id1", "distance": 0.45, "metadata": {"topic": "science"}}, ...], "distanceMetric": "cosine"}

Constraints:

• Using --filter or --return-metadata requires both s3vectors:QueryVectors AND s3vectors:GetVectors IAM permissions. Without GetVectors, these options return 403.

Troubleshooting

Additional Resources

• limits-and-patterns.md -- Multi-tenant patterns, batch ingestion, SSE-KMS, migration
• metadata-filtering.md -- Filter operators, non-filterable metadata, Bedrock KB keys

Patterns for S3 Vectors at Scale

For current limits: search AWS docs for "S3 Vectors limitations and restrictions"

When to Use S3 Vectors

Use S3 Vectors for large, long-term vector data that doesn't require the high-throughput performance of in-memory vector databases. S3 Vectors provides a cost-optimized data foundation with query performance optimized for long-term storage and infrequent access of data. You also benefit from a storage architecture with strong consistency guarantees, ensuring subsequent queries always include your most recently added data.

S3 Vectors delivers subsecond latency for infrequent queries and as low as 100ms for more frequent queries.

Multi-Tenant Patterns

Per-tenant index (recommended for isolation):

• Each tenant gets their own index within a shared vector bucket
• Queries naturally scoped to one tenant
• Easy to delete a tenant's data (delete the index)
• Use when: tenants need strict isolation, different schemas, or independent scaling

Single index with metadata filtering (simpler):

• All tenants share one index, filter by tenant_id metadata
• Simpler to manage, single query endpoint
• Use when: tenants have identical schemas and moderate scale
• Risk: noisy neighbor if one tenant dominates the index

Batch Ingestion Pattern

For large-scale ingestion (millions of vectors):

1. Batch vectors into groups of up to 500 per PutVectors call 2. Use parallel workers with backoff on ServiceUnavailableException 3. For sustained throughput beyond per-index limits, shard across multiple indexes 4. Search AWS docs for "S3 Vectors limitations and restrictions" for current per-call and per-second limits

SSE-KMS Encryption

To create a vector bucket with SSE-KMS:

aws s3vectors create-vector-bucket \
  --vector-bucket-name <BUCKET_NAME> \
  --encryption-configuration '{"sseType":"aws:kms","kmsKeyArn":"arn:aws:kms:<REGION>:<ACCOUNT>:key/<KEY_ID>"}'

You MUST use the full KMS key ARN (not alias or key ID). The KMS key policy MUST grant kms:GenerateDataKey and kms:Decrypt to the S3 Vectors service principal indexing.s3vectors.amazonaws.com. Encryption cannot be changed after bucket or index creation.

For full KMS policy examples, search AWS docs for "S3 Vectors data encryption KMS".

Migration Pattern

When migrating from another vector DB (pgVector, AOSS, etc.):

1. Create vector bucket and index matching source dimensions + distance metric 2. Export vectors from source (with metadata) 3. Batch PutVectors into S3 Vectors 4. Verify with QueryVectors using known test vectors 5. S3 Vectors only supports cosine and euclidean — if source used dotProduct, use cosine on normalized vectors as equivalent

Metadata Filtering

For full docs: search AWS docs for "S3 Vectors metadata filtering"

Filterable vs Non-filterable

• Filterable (default): All metadata is filterable unless explicitly declared otherwise.

Can be used in query --filter expressions. Limited to 2 KB per vector.

• Non-filterable: Declared at index creation via --metadata-configuration. Search AWS docs for "S3 Vectors non-filterable metadata" for JSON syntax.

Cannot be used in filters but can store larger data. Total metadata per vector (filterable + non-filterable combined) is limited to 40 KB. Ideal for text chunks, descriptions, raw content. Immutable — cannot change after index creation. Max 10 non-filterable keys per index.

Filter Operators

Filter Examples

Simple equality (implicit $eq):

{"genre": "documentary"}

Numeric range:

{"year": {"$gte": 2020, "$lte": 2024}}

Array match:

{"category": {"$in": ["science", "technology"]}}

Compound filter:

{"$and": [{"genre": {"$eq": "drama"}}, {"year": {"$gte": 2020}}]}

Existence check:

{"genre": {"$exists": true}}

Key Rules

• $eq is implicit — {"genre": "drama"} equals {"genre": {"$eq": "drama"}}
• $eq on array metadata matches if input matches ANY element in the array
• Filtering is applied during search (not post-filter). All returned results satisfy the filter, but fewer than top-K may be returned when few vectors match
• Query with filter requires both s3vectors:QueryVectors AND s3vectors:GetVectors