AWS.S3Vectors reference

VectorBucket

Source: src/AWS/S3Vectors/VectorBucket.ts

An Amazon S3 Vectors bucket — durable storage for vector embeddings, queryable by similarity. Create one or more Indexes inside it to store and query vectors.

S3 Vectors is in preview; availability varies by region.

VectorBucket: Creating a Vector Bucket

Basic Vector Bucket

import * as S3Vectors from "alchemy/AWS/S3Vectors";

const bucket = yield* S3Vectors.VectorBucket("Embeddings", {});

Vector Bucket with KMS Encryption

const bucket = yield* S3Vectors.VectorBucket("Embeddings", {
  encryption: { sseType: "aws:kms", kmsKeyArn: key.keyArn },
});

VectorBucket: Bucket Policy

const bucket = yield* S3Vectors.VectorBucket("Embeddings", {
  vectorBucketName: "shared-embeddings",
  policy: [
    {
      Effect: "Allow",
      Principal: { AWS: "arn:aws:iam::123456789012:root" },
      Action: ["s3vectors:GetVectors", "s3vectors:QueryVectors"],
      Resource:
        "arn:aws:s3vectors:us-east-1:999999999999:bucket/shared-embeddings/index/*",
    },
  ],
});

Index

Source: src/AWS/S3Vectors/VectorIndex.ts

A vector index inside an S3 Vectors VectorBucket — stores vectors of a fixed dimension and answers similarity queries under a distance metric.

The index shape (data type, dimension, distance metric, non-filterable metadata keys) is fixed at create time; changing any of them replaces the index.

Index: Creating an Index

import * as S3Vectors from "alchemy/AWS/S3Vectors";

const bucket = yield* S3Vectors.VectorBucket("Embeddings", {});
const index = yield* S3Vectors.Index("Docs", {
  vectorBucketName: bucket.vectorBucketName,
  dimension: 1024,
  distanceMetric: "cosine",
});

Vectors

Source: src/AWS/S3Vectors/Vectors.ts

Read-write runtime binding for the S3 Vectors data plane — read and write vectors in a bound Index.

Bind an Index inside a function runtime to get a VectorsClient with put / query / get / list / delete. The binding grants read+write s3vectors:*Vectors actions scoped to exactly the bound index’s ARN. This is the natural read/write pairing for a vector store — the key enabler for building embedding search and RAG retrieval on top of S3 Vectors. For least privilege, prefer VectorsRead (query/get/list) or VectorsWrite (put/delete) where one direction suffices.

Vectors: Reading and Writing Vectors

// init
const vectors = yield* AWS.S3Vectors.Vectors(index);

// runtime — insert
yield* vectors.put({
  vectors: [
    { key: "doc-1", data: { float32: [0.1, 0.2, 0.3] } },
  ],
});

// runtime — query nearest neighbors
const result = yield* vectors.query({
  topK: 5,
  queryVector: { float32: [0.1, 0.2, 0.3] },
  returnDistance: true,
});

VectorsRead

Source: src/AWS/S3Vectors/VectorsRead.ts

Read-only runtime binding for the S3 Vectors data plane — query, get, and list vectors in a bound Index.

Grants only s3vectors:QueryVectors, s3vectors:GetVectors, and s3vectors:ListVectors on exactly the bound index’s ARN — the least-privilege choice for retrieval-only consumers (e.g. a RAG search endpoint that never writes embeddings). Provide the implementation with Effect.provide(AWS.S3Vectors.VectorsReadHttp).

VectorsRead: Reading Vectors

// init
const vectors = yield* AWS.S3Vectors.VectorsRead(index);

// runtime
const result = yield* vectors.query({
  topK: 5,
  queryVector: { float32: [0.1, 0.2, 0.3] },
  returnDistance: true,
});

VectorsWrite

Source: src/AWS/S3Vectors/VectorsWrite.ts

Write-only runtime binding for the S3 Vectors data plane — insert and delete vectors in a bound Index.

Grants only s3vectors:PutVectors and s3vectors:DeleteVectors on exactly the bound index’s ARN — the least-privilege choice for ingestion pipelines that write embeddings but never query them. Provide the implementation with Effect.provide(AWS.S3Vectors.VectorsWriteHttp).

VectorsWrite: Writing Vectors

// init
const vectors = yield* AWS.S3Vectors.VectorsWrite(index);

// runtime
yield* vectors.put({
  vectors: [{ key: "doc-1", data: { float32: [0.1, 0.2, 0.3] } }],
});