npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

prisma-extension-pgvector

v0.11.0

Published

A PGVector extension for Prisma

Downloads

215

Readme

Prisma PGVector Client Extension

GitHub Actions Workflow Status

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

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

2. Add vector support to your prisma.schema

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

generator client {
  provider = "prisma-client-js"
  previewFeatures = ["postgresqlExtensions"]
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
  extensions = [vector]
}

3. Add a vector field to your model

Or create a whole new model for your vectors.

model Item {
    id      String                  @id @default(cuid())
    vector  Unsupported("vector")?
}

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.

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

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:

generator client {
  provider = "prisma-client-js"
  previewFeatures = ["postgresqlExtensions"]
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
  extensions = [vector]
}

model Vector {
  id  Int @id @default(autoincrement())
  metadata  Json?
  testfield String?
  embedding Unsupported("vector(3)")?
}

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.

npm install prisma --save-dev
npm install @prisma/client
npm install pgvector
npm 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).

import { PrismaClient } from '@prisma/client';
import { withPGVector } from 'prisma-extension-pgvector';

const prisma = new PrismaClient().$extends(withPGVector({
    modelName: 'vector',
    vectorFieldName: 'embedding',
    idFieldName: 'id'
}));

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,

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

You can also perform nearest a nearest neighbor search:

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

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!