Vector

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

• It uses a vector database powered by RDS Postgres Serverless v2.
• Provides a SDK to query, put, and remove the vector data.

Create the database

sst.config.ts

const vector = new sst.aws.Vector("MyVectorDB", {
  dimension: 1536
});

Link to a resource

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

sst.config.ts

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

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

app/page.tsx

import { VectorClient } from "sst";

await VectorClient("MyVectorDB").query({
  vector: [32.4, 6.55, 11.2, 10.3, 87.9]
});

---

Constructor

new Vector(name, args, opts?)

Parameters

• name string

• args VectorArgs

• opts? ComponentResourceOptions

VectorArgs

dimension

Type Input<number>

The dimension size of each vector.

The maximum supported dimension is 2000. To store vectors with greater dimension, use dimensionality reduction to reduce the dimension to 2000 or less. OpenAI supports dimensionality reduction automatically when generating embeddings.

Caution

Changing the dimension will cause the data to be cleared.

{
  dimension: 1536
}

transform?

Type Object

• postgres?

Transform how this component creates its underlying resources.

transform.postgres?

Type PostgresArgs | (args: PostgresArgs, opts: ComponentResourceOptions, name: string) => void

Transform the Postgres component.

Properties

clusterID

Type Output<string>

The ID of the RDS Postgres Cluster.

nodes

Type Object

• postgres

The underlying resources this component creates.

nodes.postgres

Type Postgres

The Postgres database.

SDK

Use the SDK in your runtime to interact with your infrastructure.

---

VectorClient

VectorClient(name)

Parameters

• name string

Returns VectorClientResponse

Create a client to interact with the Vector database.

src/lambda.ts

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

Store a vector into the db

src/lambda.ts

await client.put({
  vector: [32.4, 6.55, 11.2, 10.3, 87.9],
  metadata: { type: "movie", genre: "comedy" },
});

Query vectors that are similar to the given vector

src/lambda.ts

const result = await client.query({
  vector: [32.4, 6.55, 11.2, 10.3, 87.9],
  include: { type: "movie" },
  exclude: { genre: "thriller" },
});

PutEvent

Type Object

• metadata

• vector

PutEvent.metadata

Type Record<string, any>

Metadata for the event as JSON. This will be used to filter when querying and removing vectors.

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

PutEvent.vector

Type number[]

The vector to store in the database.

{
  vector: [32.4, 6.55, 11.2, 10.3, 87.9]
}

QueryEvent

Type Object

• count?

• exclude?

• include

• threshold?

• vector

QueryEvent.count?

Type number

Default 10

The number of results to return.

{
  count: 10
}

QueryEvent.exclude?

Type Record<string, any>

Exclude vectors with metadata that match the provided fields.

Given this filter.

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

This will match a vector with metadata:

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

But not a vector with the metadata:

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

QueryEvent.include

Type Record<string, any>

The metadata used to filter the vectors. Only vectors that match the provided fields will be returned.

Given this filter.

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

It will match a vector with the metadata:

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

But not a vector with this metadata:

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

QueryEvent.threshold?

Type number

Default 0

The threshold of similarity between the prompt and the queried vectors. Only vectors with a similarity score higher than the threshold will be returned.

This will return values is between 0 and 1.

• 0 means the prompt and the queried vectors are completely different.
• 1 means the prompt and the queried vectors are identical.

{
  threshold: 0.5
}

QueryEvent.vector

Type number[]

The vector used to query the database.

{
  vector: [32.4, 6.55, 11.2, 10.3, 87.9]
}

QueryResponse

Type Object

• results Object[]

  • metadata

  • score

QueryResponse.results

Type Object[]

List of results matching the query.

QueryResponse.results[].metadata

Type Record<string, any>

Metadata for the event that was provided when storing the vector.

QueryResponse.results[].score

Type number

The similarity score between the prompt and the queried vector.

RemoveEvent

Type Object

• include

RemoveEvent.include

Type Record<string, any>

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

To remove vectors for movie with id movie-123:

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

To remove vectors for all movies:

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

VectorClientResponse

Type Object

• put

• query

• remove

VectorClientResponse.put

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

Store a vector into the database.

src/lambda.ts

await client.put({
  vector: [32.4, 6.55, 11.2, 10.3, 87.9],
  metadata: { type: "movie", genre: "comedy" },
});

VectorClientResponse.query

Type (event: QueryEvent) => Promise<QueryResponse>

Query vectors that are similar to the given vector

src/lambda.ts

const result = await client.query({
  vector: [32.4, 6.55, 11.2, 10.3, 87.9],
  include: { type: "movie" },
  exclude: { genre: "thriller" },
});

VectorClientResponse.remove

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

Remove vectors from the database.

src/lambda.ts

await client.remove({
  include: { type: "movie" },
});

Methods

static get

Vector.get(name, clusterID)

Parameters

• name string

  The name of the component.

• clusterID Input<string>

  The RDS cluster id of the existing Vector database.

Returns Vector

Reference an existing Vector database with the given name. This is useful when you create a Vector database in one stage and want to share it in another. It avoids having to create a new Vector database in the other stage.

Tip

You can use the static get method to share Vector databases across stages.

Imagine you create a vector database in the dev stage. And in your personal stage frank, instead of creating a new database, you want to share the same database from dev.

sst.config.ts

const vector = $app.stage === "frank"
  ? sst.aws.Vector.get("MyVectorDB", "app-dev-myvectordb")
  : new sst.aws.Vector("MyVectorDB", {
      dimension: 1536
    });

Here app-dev-myvectordb is the ID of the underlying Postgres cluster created in the dev stage. You can find this by outputting the cluster ID in the dev stage.

sst.config.ts

return {
  cluster: vector.clusterID
};

Note

The Vector component creates a Postgres cluster and lambda functions for interfacing with the VectorDB. The static get method only shares the underlying Postgres cluster. Each stage will have its own lambda functions.