Prisma PGVector Client Extension

prisma-extension-pgvector is a wrapper around the pgvector-node package that provides a convenient, type-safe way to interact with databases which support the pgvector vector-similarity search for Postgres databases.

Learn more in the pgvector and pgvector-node docs.

Quick Start

1. Install dependencies

1npm i @prisma/client pgvector prisma-extension-pgvector
2npm i -D prisma
3npx prisma init

2. Add vector support to your prisma.schema

At the moment vector is a preview feature, so we need to enable it

1generator client {
2  provider = "prisma-client-js"
3  previewFeatures = ["postgresqlExtensions"]
4}
5
6datasource db {
7  provider = "postgresql"
8  url      = env("DATABASE_URL")
9  extensions = [vector]
10}

3. Add a vector field to your model

Or create a whole new model for your vectors.

1model Item {
2    id      String                  @id @default(cuid())
3    vector  Unsupported("vector")?
4}

Then create or update your client (usually prisma migrate dev).

4. Extend the client

Add the extension to your Prisma instantiation, and specify the name of the model which has the vector field, as well as the name of the field.

1const prisma = new PrismaClient().$extends(withPGVector({
2    modelName: 'item',
3    vectorFieldName: 'vector'
4}));

Schema

The model you use for the vector store must include an ID field, as with all Prisma models. Any ID usable for a generic Prisma model should be usable with prisma-extension-pgvector, but it must resolve to either a number or string type.

Additionally, the model must have a Vector Field of type Unsupported vector. The field may be optional in the schema, but one must be defined. You can also specify a Vector Field of specific or arbitary length. (e.g., vector Unsupported("vector") or vector Unsupported("vector(1536)")).

Note: While it is permissable to have the Vector Field as optional (e.g., vector Unsupported("vector")?), if you perform distance queries and some records in your database actually have no vector data, you may get unexpected results.

The documentation is built around the following schema:

1generator client {
2  provider = "prisma-client-js"
3  previewFeatures = ["postgresqlExtensions"]
4}
5
6datasource db {
7  provider = "postgresql"
8  url      = env("DATABASE_URL")
9  extensions = [vector]
10}
11
12model Vector {
13  id  Int @id @default(autoincrement())
14  metadata  Json?
15  testfield String?
16  embedding Unsupported("vector(3)")?
17}

Instantiating Prisma Client with pgvector extension

Installation requirements

In addition addition to the usual Prisma installation, and of course prisma-extension-pgvector, you will need to install pgvector.

1npm install prisma --save-dev
2npm install @prisma/client
3npm install pgvector
4npm install prisma-extension-pgvector

Instantiation arguments

When you instantiate a Prisma client with prisma-extension-pgvector, you need to specify which model has the Vector Field, the name of the Vector Field, and the name of the ID field (idFieldName is optional, and will default to id).

1import { PrismaClient } from '@prisma/client';
2import { withPGVector } from 'prisma-extension-pgvector';
3
4const prisma = new PrismaClient().$extends(withPGVector({
5    modelName: 'vector',
6    vectorFieldName: 'embedding',
7    idFieldName: 'id'
8}));

Queries

Model-specific methods for the unsupported vector field type are documented here. You can get an array of vectors from the database by id with, for example,

1const vectors = await prisma.vector.getVectorsById({
2  where: {
3    id: { in: [ 1 ] }
4  }
5})

You can also perform nearest a nearest neighbor search:

1const neighbors = await prisma.vector.findNearestNeighbors({
2  from: [1, 1, 1],
3  orderBy: 'L2'
4})

Valid distance metrics for orderBy are L2 (default), InnerProduct, Cosine, L1. See PGVector Querying.

Native Prisma methods

Some of the native Prisma client methods have been overridden to support the vector field. Full documentation is here.

Currently there is support for create, createManyAndReturn, and findMany.

Other native methods do not support the setting or retrieving of the vector field (yet!). For example, while you can createManyAndReturn, createMany will currently result in an error if you try and set your vector field.

If you have a need for one of the other ones to be supported, feel free to submit an issue, or, better, write one yourself!