Amazon S3 Vectors Store
⚠️ Amazon S3 Vectors is a Preview service. Preview features may change or be removed without notice and are not covered by AWS SLAs. Behavior, limits, and regional availability can change at any time. This library may introduce breaking changes to stay aligned with AWS.
The S3Vectors
class provides vector search using Amazon S3 Vectors (Preview) . It stores vectors in vector buckets and performs similarity search in vector indexes, with JSON-based metadata filters.
Installation
npm install @mastra/s3vectors
Usage Example
import { S3Vectors } from "@mastra/s3vectors";
const store = new S3Vectors({
vectorBucketName: process.env.S3_VECTORS_BUCKET_NAME!, // e.g. "my-vector-bucket"
clientConfig: {
region: process.env.AWS_REGION!, // credentials use the default AWS provider chain
},
// Optional: mark large/long-text fields as non-filterable at index creation time
nonFilterableMetadataKeys: ["content"],
});
// Create an index (names are normalized: "_" → "-" and lowercased)
await store.createIndex({
indexName: "my_index",
dimension: 1536,
metric: "cosine", // "euclidean" also supported; "dotproduct" is NOT supported
});
// Upsert vectors (ids auto-generated if omitted). Date values in metadata are serialized to epoch ms.
const ids = await store.upsert({
indexName: "my_index",
vectors: [
[0.1, 0.2 /* … */],
[0.3, 0.4 /* … */],
],
metadata: [
{ text: "doc1", genre: "documentary", year: 2023, createdAt: new Date("2024-01-01") },
{ text: "doc2", genre: "comedy", year: 2021 },
],
});
// Query with metadata filters (implicit AND is canonicalized)
const results = await store.query({
indexName: "my-index",
queryVector: [0.1, 0.2 /* … */],
topK: 10, // Service-side limits may apply (commonly 30)
filter: { genre: { $in: ["documentary", "comedy"] }, year: { $gte: 2020 } },
includeVector: false, // set true to include raw vectors (may trigger a secondary fetch)
});
// Clean up resources (closes the underlying HTTP handler)
await store.disconnect();
Constructor Options
vectorBucketName:
clientConfig?:
nonFilterableMetadataKeys?:
Methods
createIndex()
Creates a new vector index in the configured vector bucket. If the index already exists, the call validates the schema and becomes a no-op (existing metric and dimension are preserved).
indexName:
dimension:
metric?:
upsert()
Adds or replaces vectors (full-record put). If ids
are not provided, UUIDs are generated.
indexName:
vectors:
metadata?:
ids?:
query()
Searches for nearest neighbors with optional metadata filtering.
indexName:
queryVector:
topK?:
filter?:
includeVector?:
Scoring: Results include
score = 1/(1 + distance)
so that higher is better while preserving the underlying distance ranking.
describeIndex()
Returns information about the index.
indexName:
Returns:
interface IndexStats {
dimension: number;
count: number; // computed via ListVectors pagination (O(n))
metric: "cosine" | "euclidean";
}
deleteIndex()
Deletes an index and its data.
indexName:
listIndexes()
Lists all indexes in the configured vector bucket.
Returns: Promise<string[]>
updateVector()
Updates a vector or metadata for a specific ID within an index.
indexName:
id:
update:
update.vector?:
update.metadata?:
deleteVector()
Deletes a specific vector by ID.
indexName:
id:
disconnect()
Closes the underlying AWS SDK HTTP handler to free sockets.
Response Types
Query results are returned in this format:
interface QueryResult {
id: string;
score: number; // 1/(1 + distance)
metadata: Record<string, any>;
vector?: number[]; // Only included if includeVector is true
}
Filter Syntax
S3 Vectors supports a strict subset of operators and value types. The Mastra filter translator:
- Canonicalizes implicit AND:
{a:1,b:2}
→{ $and: [{a:1},{b:2}] }
. - Normalizes Date values to epoch ms for numeric comparisons and array elements.
- Disallows Date in equality positions (
field: value
or$eq/$ne
); equality values must be string | number | boolean. - Rejects null/undefined for equality; array equality is not supported (use
$in
/$nin
). - Only
$and
/$or
are allowed as top-level logical operators. - Logical operators must contain field conditions (not direct operators).
Supported operators:
- Logical:
$and
,$or
(non-empty arrays) - Basic:
$eq
,$ne
(string | number | boolean) - Numeric:
$gt
,$gte
,$lt
,$lte
(number orDate
→ epoch ms) - Array:
$in
,$nin
(non-empty arrays of string | number | boolean;Date
→ epoch ms) - Element:
$exists
(boolean)
Unsupported / disallowed (rejected): $not
, $nor
, $regex
, $all
, $elemMatch
, $size
, $text
, etc.
Examples:
// Implicit AND
{ genre: { $in: ["documentary", "comedy"] }, year: { $gte: 2020 } }
// Explicit logicals and ranges
{
$and: [
{ price: { $gte: 100, $lte: 1000 } },
{ $or: [{ stock: { $gt: 0 } }, { preorder: true }] }
]
}
// Dates in range (converted to epoch ms)
{ timestamp: { $gt: new Date("2024-01-01T00:00:00Z") } }
Non-filterable keys: If you set
nonFilterableMetadataKeys
at index creation, those keys are stored but cannot be used in filters.
Error Handling
The store throws typed errors that can be caught:
try {
await store.query({
indexName: "index-name",
queryVector: queryVector,
});
} catch (error) {
if (error instanceof VectorStoreError) {
console.log(error.code); // 'connection_failed' | 'invalid_dimension' | etc
console.log(error.details); // Additional error context
}
}
Environment Variables
Typical environment variables when wiring your app:
S3_VECTORS_BUCKET_NAME
: Your S3 vector bucket name (used to populatevectorBucketName
).AWS_REGION
: AWS region for the S3 Vectors bucket.- AWS credentials: via the standard AWS SDK provider chain (
AWS_ACCESS_KEY_ID
,AWS_SECRET_ACCESS_KEY
,AWS_PROFILE
, etc.).
Best Practices
- Choose the metric (
cosine
oreuclidean
) to match your embedding model;dotproduct
is not supported. - Keep filterable metadata small and structured (string/number/boolean). Store large text (e.g.,
content
) as non-filterable. - Use dotted paths for nested metadata and explicit
$and
/$or
for complex logic. - Avoid calling
describeIndex()
on hot paths—count
is computed with paginatedListVectors
(O(n)). - Use
includeVector: true
only when you need raw vectors.