Vector

Reference doc for the `sst.aws.Vector` component.

The Vector component lets you store and retrieve vector data in your app.

It uses an LLM to generate the embedding.
Stores it in a vector database powered by RDS Postgres Serverless v2.
Provides a SDK to ingest, retrieve, and remove the vector data.

Create the database

const vector = new sst.aws.Vector("MyVectorDB");

Change the model

Optionally, use a different model, like OpenAI’s text-embedding-3-small model. You’ll need to pass in your OpenAI API key.

new sst.aws.Vector("MyVectorDB", {
  openAiApiKey: new sst.aws.Secret("OpenAiApiKey").value,
  model: "text-embedding-3-small"
});

Link to a resource

You can link it to other resources, like a function or your Next.js app.

new sst.aws.Nextjs("MyWeb", {
  link: [vector]
});

Once linked, you can query it in your function code using the SDK.

import { VectorClient } from "sst";

const vector = VectorClient("MyVectorDB");

await vector.retrieve({
  text: "Some text to search for"
});

Constructor

new Vector(name, args?, opts?)

Parameters

name string
args? VectorArgs
opts? ComponentResourceOptions

VectorArgs

model?

Type Input<“amazon.titan-embed-text-v1” | “amazon.titan-embed-image-v1” | “text-embedding-ada-002” | “text-embedding-3-small” | “text-embedding-3-large”>

Default “amazon.titan-embed-text-v1”

The model used for generating the vectors. Supports AWS’ and OpenAI’s models.

To use OpenAI’s text-embedding-ada-002, text-embedding-3-small, or text-embedding-3-large model, you’ll need to pass in an openAiApiKey.

OpenAI’s text-embedding-3-large model produces embeddings with 3072 dimensions. This is scaled down to 2000 dimensions to store it in Postgres. The Postgres database in this component can store up to 2000 dimensions with a pgvector HNSW index.

{
  model: "amazon.titan-embed-image-v1"
}

openAiApiKey?

Type Input<string>

Your OpenAI API key. This is needed only if you’re using the text-embedding-ada-002, text-embedding-3-small, or text-embedding-3-small model.

{
  openAiApiKey: "<your-api-key>"
}

transform?

Type Object

postgres?

Transform how this component creates its underlying resources.

transform.postgres?

Type PostgresArgs | (args: PostgresArgs => void)

Transform the Postgres component.

Properties

ingestor

Type Output<string>

The name of the ingestor Lambda function.

remover

Type Output<string>

The name of the remover Lambda function.

retriever

Type Output<string>

The name of the retriever Lambda function.

SDK

The following are accessible through the SDK at runtime.

ingestor

Type string

The name of the ingestor Lambda function.

remover

Type string

The name of the remover Lambda function.

retriever

Type string

The name of the retriever Lambda function.

VectorClient

VectorClient(name)

Parameters

name T

Returns VectorClientResponse

Create a client to interact with the Vector database.

import { VectorClient } from "sst";
const client = VectorClient("MyVectorDB");

// Ingest a text into the vector db
await client.ingest({
  text: "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
  metadata: { type: "movie", genre: "comedy" },
});

// Retrieve embeddings similar to the provided text
const result = await client.retrieve({
  text: "Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
  include: { type: "movie" },
  exclude: { genre: "thriller" },
});

IngestEvent

Type Object

image?
metadata
text?

IngestEvent.image?

Type string

The base64 representation of the image used to generate the embedding vector. At least one of text or image must be provided.

{
  image: await fs.readFile("./file.jpg").toString("base64"),
}

IngestEvent.metadata

Type Record<string, any>

Metadata for the event in JSON format. This metadata will be used to filter when retrieving and removing embeddings.

{
  metadata: {
    type: "movie",
    id: "movie-123",
    name: "Spiderman",
  }
}

IngestEvent.text?

Type string

The text used to generate the embedding vector. At least one of text or image must be provided.

{
  text: "This is an example text.",
}

RemoveEvent

Type Object

include

RemoveEvent.include

Type Record<string, any>

The metadata used to filter the removal of embeddings. Only embeddings with metadata that match the provided fields will be removed.

To remove embeddings for movie with id “movie-123”:

{
  include: {
    id: "movie-123",
  }
}

To remove embeddings for all movies:

 {
  include: {
   type: "movie",
  }
 }

RetrieveEvent

Type Object

count?
exclude?
image?
include
text?
threshold?

RetrieveEvent.count?

Type number

Default 10

The number of results to return.

{
  count: 10,
}

RetrieveEvent.exclude?

Type Record<string, any>

Exclude embeddings with metadata that match the provided fields.

{
  include: {
    type: "movie",
    release: "2001",
  },
  exclude: {
    name: "Spiderman",
  }
}

This will match the embedding with metadata:

 {
   type: "movie",
   name: "A Beautiful Mind",
   release: "2001",
 }

But not the embedding with metadata:

 {
   type: "book",
   name: "Spiderman",
   release: "2001",
 }

RetrieveEvent.image?

Type string

The base64 representation of the image prompt used to retrive embeddings. At least one of text or image must be provided.

{
  image: await fs.readFile("./file.jpg").toString("base64"),
}

RetrieveEvent.include

Type Record<string, any>

The metadata used to filter the retrieval of embeddings. Only embeddings with metadata that match the provided fields will be returned.

{
  include: {
    type: "movie",
    release: "2001",
  }
}

This will match the embedding with metadata:

 {
   type: "movie",
   name: "Spiderman",
   release: "2001",
 }

But not the embedding with metadata:

 {
   type: "book",
   name: "Spiderman",
   release: "2001",
 }

RetrieveEvent.text?

Type string

The text prompt used to retrieve embeddings. At least one of text or image must be provided.

{
  text: "This is an example text.",
}

RetrieveEvent.threshold?

Type number

Default 0

The threshold of similarity between the prompt and the retrieved embeddings. Only embeddings with a similarity score higher than the threshold will be returned. Expected value is between 0 and 1.

0 means the prompt and the retrieved embeddings are completely different.
1 means the prompt and the retrieved embeddings are identical.

{
  threshold: 0.5,
}

RetrieveResponse

Type Object

metadata
score

RetrieveResponse.metadata

Type Record<string, any>

Metadata for the event in JSON format that was provided when ingesting the embedding.

RetrieveResponse.score

Type number

The similarity score between the prompt and the retrieved embedding.

VectorClientResponse

Type Object

ingest
remove
retrieve

VectorClientResponse.ingest

Type (event: IngestEvent) => Promise<void>

VectorClientResponse.remove

Type (event: RemoveEvent) => Promise<void>

VectorClientResponse.retrieve

Type (event: RetrieveEvent) => Promise<RetrieveResponse>