pgvector-node

pgvector support for Node.js, Deno, and Bun (and TypeScript)

Supports node-postgres, Knex.js, Objection.js, Kysely, Sequelize, pg-promise, Prisma, Postgres.js, Slonik, TypeORM, MikroORM, Drizzle ORM, and Bun SQL

Installation

Run:

1npm install pgvector

And follow the instructions for your database library:

• node-postgres
• Knex.js
• Objection.js
• Kysely
• Sequelize
• pg-promise
• Prisma
• Postgres.js
• Slonik
• TypeORM
• MikroORM
• Drizzle ORM
• Bun SQL

Or check out some examples:

• Embeddings with OpenAI
• Binary embeddings with Cohere
• Sentence embeddings with Transformers.js
• Hybrid search with Transformers.js
• Sparse search with Text Embeddings Inference
• Morgan fingerprints with RDKit.js
• Recommendations with Disco
• Horizontal scaling with Citus
• WebAssembly with PGLite
• Bulk loading with COPY

node-postgres

Enable the extension

1await client.query('CREATE EXTENSION IF NOT EXISTS vector');

Register the types for a client

1import pgvector from 'pgvector/pg';
2
3await pgvector.registerTypes(client);

or a pool

1pool.on('connect', async function (client) {
2  await pgvector.registerTypes(client);
3});

Create a table

1await client.query('CREATE TABLE items (id bigserial PRIMARY KEY, embedding vector(3))');

Insert a vector

1await client.query('INSERT INTO items (embedding) VALUES ($1)', [pgvector.toSql([1, 2, 3])]);

Get the nearest neighbors to a vector

1const result = await client.query('SELECT * FROM items ORDER BY embedding <-> $1 LIMIT 5', [pgvector.toSql([1, 2, 3])]);

Add an approximate index

1await client.query('CREATE INDEX ON items USING hnsw (embedding vector_l2_ops)');
2// or
3await client.query('CREATE INDEX ON items USING ivfflat (embedding vector_l2_ops) WITH (lists = 100)');

Use vector_ip_ops for inner product and vector_cosine_ops for cosine distance

See a full example

Knex.js

Import the library

1import pgvector from 'pgvector/knex';

Enable the extension

1await knex.schema.createExtensionIfNotExists('vector');

Create a table

1await knex.schema.createTable('items', (table) => {
2  table.increments('id');
3  table.vector('embedding', 3);
4});

Insert vectors

1const newItems = [
2  {embedding: pgvector.toSql([1, 2, 3])},
3  {embedding: pgvector.toSql([4, 5, 6])}
4];
5await knex('items').insert(newItems);

Get the nearest neighbors to a vector

1const items = await knex('items')
2  .orderBy(knex.l2Distance('embedding', [1, 2, 3]))
3  .limit(5);

Also supports maxInnerProduct, cosineDistance, l1Distance, hammingDistance, and jaccardDistance

Add an approximate index

1await knex.schema.alterTable('items', function (table) {
2  table.index(knex.raw('embedding vector_l2_ops'), 'index_name', 'hnsw');
3});

Use vector_ip_ops for inner product and vector_cosine_ops for cosine distance

See a full example

Objection.js

Import the library

1import pgvector from 'pgvector/objection';

Enable the extension

1await knex.schema.createExtensionIfNotExists('vector');

Create a table

1await knex.schema.createTable('items', (table) => {
2  table.increments('id');
3  table.vector('embedding', 3);
4});

Insert vectors

1const newItems = [
2  {embedding: pgvector.toSql([1, 2, 3])},
3  {embedding: pgvector.toSql([4, 5, 6])}
4];
5await Item.query().insert(newItems);

Get the nearest neighbors to a vector

1import { l2Distance } from 'pgvector/objection';
2
3const items = await Item.query()
4  .orderBy(l2Distance('embedding', [1, 2, 3]))
5  .limit(5);

Also supports maxInnerProduct, cosineDistance, l1Distance, hammingDistance, and jaccardDistance

Add an approximate index

1await knex.schema.alterTable('items', function (table) {
2  table.index(knex.raw('embedding vector_l2_ops'), 'index_name', 'hnsw');
3});

Use vector_ip_ops for inner product and vector_cosine_ops for cosine distance

See a full example

Kysely

Enable the extension

1await sql`CREATE EXTENSION IF NOT EXISTS vector`.execute(db);

Create a table

1await db.schema.createTable('items')
2  .addColumn('id', 'serial', (cb) => cb.primaryKey())
3  .addColumn('embedding', sql`vector(3)`)
4  .execute();

Insert vectors

1import pgvector from 'pgvector/kysely';
2
3const newItems = [
4  {embedding: pgvector.toSql([1, 2, 3])},
5  {embedding: pgvector.toSql([4, 5, 6])}
6];
7await db.insertInto('items').values(newItems).execute();

Get the nearest neighbors to a vector

1import { l2Distance } from 'pgvector/kysely';
2
3const items = await db.selectFrom('items')
4  .selectAll()
5  .orderBy(l2Distance('embedding', [1, 2, 3]))
6  .limit(5)
7  .execute();

Also supports maxInnerProduct, cosineDistance, l1Distance, hammingDistance, and jaccardDistance

Get items within a certain distance

1const items = await db.selectFrom('items')
2  .selectAll()
3  .where(l2Distance('embedding', [1, 2, 3]), '<', 5)
4  .execute();

Add an approximate index

1await db.schema.createIndex('index_name')
2  .on('items')
3  .using('hnsw')
4  .expression(sql`embedding vector_l2_ops`)
5  .execute();

Use vector_ip_ops for inner product and vector_cosine_ops for cosine distance

See a full example

Sequelize

Enable the extension

1await sequelize.query('CREATE EXTENSION IF NOT EXISTS vector');

Register the types

1import { Sequelize } from 'sequelize';
2import pgvector from 'pgvector/sequelize';
3
4pgvector.registerTypes(Sequelize);

Add a vector field

1const Item = sequelize.define('Item', {
2  embedding: {
3    type: DataTypes.VECTOR(3)
4  }
5}, ...);

Insert a vector

1await Item.create({embedding: [1, 2, 3]});

Get the nearest neighbors to a vector

1import { l2Distance } from 'pgvector/sequelize';
2
3const items = await Item.findAll({
4  order: l2Distance('embedding', [1, 1, 1], sequelize),
5  limit: 5
6});

Also supports maxInnerProduct, cosineDistance, l1Distance, hammingDistance, and jaccardDistance

Add an approximate index

1const Item = sequelize.define('Item', ..., {
2  indexes: [
3    {
4      fields: ['embedding'],
5      using: 'hnsw',
6      operator: 'vector_l2_ops'
7    }
8  ]
9});

Use vector_ip_ops for inner product and vector_cosine_ops for cosine distance

See a full example

pg-promise

Enable the extension

1await db.none('CREATE EXTENSION IF NOT EXISTS vector');

Register the types

1import pgpromise from 'pg-promise';
2import pgvector from 'pgvector/pg-promise';
3
4const initOptions = {
5  async connect(e) {
6    await pgvector.registerTypes(e.client);
7  }
8};
9const pgp = pgpromise(initOptions);

Create a table

1await db.none('CREATE TABLE items (id bigserial PRIMARY KEY, embedding vector(3))');

Insert a vector

1await db.none('INSERT INTO items (embedding) VALUES ($1)', [pgvector.toSql([1, 2, 3])]);

Get the nearest neighbors to a vector

1const result = await db.any('SELECT * FROM items ORDER BY embedding <-> $1 LIMIT 5', [pgvector.toSql([1, 2, 3])]);

Add an approximate index

1await db.none('CREATE INDEX ON items USING hnsw (embedding vector_l2_ops)');
2// or
3await db.none('CREATE INDEX ON items USING ivfflat (embedding vector_l2_ops) WITH (lists = 100)');

Use vector_ip_ops for inner product and vector_cosine_ops for cosine distance

See a full example

Prisma

Note: prisma migrate dev does not support pgvector indexes

Import the library

1import pgvector from 'pgvector';

Add the extension to the 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}

Add a vector column to the schema

1model Item {
2  id        Int                       @id @default(autoincrement())
3  embedding Unsupported("vector(3)")?
4}

Insert a vector

1const embedding = pgvector.toSql([1, 2, 3])
2await prisma.$executeRaw`INSERT INTO items (embedding) VALUES (${embedding}::vector)`

Get the nearest neighbors to a vector

1const embedding = pgvector.toSql([1, 2, 3])
2const items = await prisma.$queryRaw`SELECT id, embedding::text FROM items ORDER BY embedding <-> ${embedding}::vector LIMIT 5`

See a full example (and the schema)

Postgres.js

Import the library

1import pgvector from 'pgvector';

Enable the extension

1await sql`CREATE EXTENSION IF NOT EXISTS vector`;

Create a table

1await sql`CREATE TABLE items (id bigserial PRIMARY KEY, embedding vector(3))`;

Insert vectors

1const newItems = [
2  {embedding: pgvector.toSql([1, 2, 3])},
3  {embedding: pgvector.toSql([4, 5, 6])}
4];
5await sql`INSERT INTO items ${ sql(newItems, 'embedding') }`;

Get the nearest neighbors to a vector

1const embedding = pgvector.toSql([1, 2, 3]);
2const items = await sql`SELECT * FROM items ORDER BY embedding <-> ${ embedding } LIMIT 5`;

Add an approximate index

1await sql`CREATE INDEX ON items USING hnsw (embedding vector_l2_ops)`;
2// or
3await sql`CREATE INDEX ON items USING ivfflat (embedding vector_l2_ops) WITH (lists = 100)`;

Use vector_ip_ops for inner product and vector_cosine_ops for cosine distance

See a full example

Slonik

Import the library

1import pgvector from 'pgvector';

Enable the extension

1await pool.query(sql.unsafe`CREATE EXTENSION IF NOT EXISTS vector`);

Create a table

1await pool.query(sql.unsafe`CREATE TABLE items (id serial PRIMARY KEY, embedding vector(3))`);

Insert a vector

1const embedding = pgvector.toSql([1, 2, 3]);
2await pool.query(sql.unsafe`INSERT INTO items (embedding) VALUES (${embedding})`);

Get the nearest neighbors to a vector

1const embedding = pgvector.toSql([1, 2, 3]);
2const items = await pool.query(sql.unsafe`SELECT * FROM items ORDER BY embedding <-> ${embedding} LIMIT 5`);

Add an approximate index

1await pool.query(sql.unsafe`CREATE INDEX ON items USING hnsw (embedding vector_l2_ops)`);
2// or
3await pool.query(sql.unsafe`CREATE INDEX ON items USING ivfflat (embedding vector_l2_ops) WITH (lists = 100)`);

Use vector_ip_ops for inner product and vector_cosine_ops for cosine distance

See a full example

TypeORM

Import the library

1import pgvector from 'pgvector';

Enable the extension

1await AppDataSource.query('CREATE EXTENSION IF NOT EXISTS vector');

Create a table

1await AppDataSource.query('CREATE TABLE item (id bigserial PRIMARY KEY, embedding vector(3))');

Define an entity

1@Entity()
2class Item {
3  @PrimaryGeneratedColumn()
4  id: number
5
6  @Column()
7  embedding: string
8}

Insert a vector

1const itemRepository = AppDataSource.getRepository(Item);
2await itemRepository.save({embedding: pgvector.toSql([1, 2, 3])});

Get the nearest neighbors to a vector

1const items = await itemRepository
2  .createQueryBuilder('item')
3  .orderBy('embedding <-> :embedding')
4  .setParameters({embedding: pgvector.toSql([1, 2, 3])})
5  .limit(5)
6  .getMany();

See a full example

MikroORM

Enable the extension

1await em.execute('CREATE EXTENSION IF NOT EXISTS vector');

Define an entity

1import { VectorType } from 'pgvector/mikro-orm';
2
3@Entity()
4class Item {
5  @PrimaryKey()
6  id: number;
7
8  @Property({type: VectorType})
9  embedding: number[];
10}

Insert a vector

1em.create(Item, {embedding: [1, 2, 3]});

Get the nearest neighbors to a vector

1import { l2Distance } from 'pgvector/mikro-orm';
2
3const items = await em.createQueryBuilder(Item)
4  .orderBy({[l2Distance('embedding', [1, 2, 3])]: 'ASC'})
5  .limit(5)
6  .getResult();

Also supports maxInnerProduct, cosineDistance, l1Distance, hammingDistance, and jaccardDistance

See a full example

Drizzle ORM

Drizzle ORM 0.31.0+ has built-in support for pgvector :tada:

Enable the extension

1await client`CREATE EXTENSION IF NOT EXISTS vector`;

Add a vector field

1import { vector } from 'drizzle-orm/pg-core';
2
3const items = pgTable('items', {
4  id: serial('id').primaryKey(),
5  embedding: vector('embedding', {dimensions: 3})
6});

Also supports halfvec, bit, and sparsevec

Insert vectors

1const newItems = [
2  {embedding: [1, 2, 3]},
3  {embedding: [4, 5, 6]}
4];
5await db.insert(items).values(newItems);

Get the nearest neighbors to a vector

1import { l2Distance } from 'drizzle-orm';
2
3const allItems = await db.select()
4  .from(items)
5  .orderBy(l2Distance(items.embedding, [1, 2, 3]))
6  .limit(5);

Also supports innerProduct, cosineDistance, l1Distance, hammingDistance, and jaccardDistance

See a full example

Bun SQL

Import the library

1import pgvector from 'pgvector';

Enable the extension

1await sql`CREATE EXTENSION IF NOT EXISTS vector`;

Create a table

1await sql`CREATE TABLE items (id bigserial PRIMARY KEY, embedding vector(3))`;

Insert vectors

1const newItems = [
2  {embedding: pgvector.toSql([1, 2, 3])},
3  {embedding: pgvector.toSql([4, 5, 6])}
4];
5await sql`INSERT INTO items ${sql(newItems)}`;

Get the nearest neighbors to a vector

1const embedding = pgvector.toSql([1, 2, 3]);
2const items = await sql`SELECT * FROM items ORDER BY embedding <-> ${embedding} LIMIT 5`.values();

Add an approximate index

1await sql`CREATE INDEX ON items USING hnsw (embedding vector_l2_ops)`;
2// or
3await sql`CREATE INDEX ON items USING ivfflat (embedding vector_l2_ops) WITH (lists = 100)`;

Use vector_ip_ops for inner product and vector_cosine_ops for cosine distance

See a full example

Reference

Sparse Vectors

Create a sparse vector from an array

1const vec = new SparseVector([1, 0, 2, 0, 3, 0]);

Or a map of non-zero elements

1const vec = new SparseVector({0: 1, 2: 2, 4: 3}, 6);
2// or
3const map = new Map();
4map.set(0, 1);
5map.set(2, 2);
6map.set(4, 3);
7const vec = new SparseVector(map, 6);

Note: Indices start at 0

Get the number of dimensions

1const dim = vec.dimensions;

Get the indices of non-zero elements

1const indices = vec.indices;

Get the values of non-zero elements

1const values = vec.values;

Get an array

1const arr = vec.toArray();

History

View the changelog

Contributing

Everyone is encouraged to help improve this project. Here are a few ways you can help:

• Report bugs
• Fix bugs and submit pull requests
• Write, clarify, or fix documentation
• Suggest or add new features

To get started with development:

1git clone https://github.com/pgvector/pgvector-node.git
2cd pgvector-node
3npm install
4createdb pgvector_node_test
5npx prisma migrate dev
6npm test

To run an example:

1cd examples/loading
2npm install
3createdb pgvector_example
4node example.js