Skip to Content
ReferenceRAGPgVector

PG Vector Store ✅

The PgVector class provides vector search using PostgreSQL  with pgvector  extension. It provides robust vector similarity search capabilities within your existing PostgreSQL database.

Constructor Options ✅

connectionString:

string
PostgreSQL connection URL

schemaName?:

string
The name of the schema you want the vector store to use. Will use the default schema if not provided.

Constructor Examples ✅

You can instantiate PgVector in two ways:

import { PgVector } from '@kastrax/pg';
 
// Using a connection string (string form)
const vectorStore1 = new PgVector('postgresql://user:password@localhost:5432/mydb');
 
// Using a config object (with optional schemaName)
const vectorStore2 = new PgVector({
  connectionString: 'postgresql://user:password@localhost:5432/mydb',
  schemaName: 'custom_schema', // optional
});

Methods ✅

createIndex()

indexName:

string
Name of the index to create

dimension:

number
Vector dimension (must match your embedding model)

metric?:

'cosine' | 'euclidean' | 'dotproduct'
= cosine
Distance metric for similarity search

indexConfig?:

IndexConfig
= { type: 'ivfflat' }
Index configuration

buildIndex?:

boolean
= true
Whether to build the index

IndexConfig

type:

'flat' | 'hnsw' | 'ivfflat'
= ivfflat
Index type
string

flat:

flat
Sequential scan (no index) that performs exhaustive search.

ivfflat:

ivfflat
Clusters vectors into lists for approximate search.

hnsw:

hnsw
Graph-based index offering fast search times and high recall.

ivf?:

IVFConfig
IVF configuration
object

lists?:

number
Number of lists. If not specified, automatically calculated based on dataset size. (Minimum 100, Maximum 4000)

hnsw?:

HNSWConfig
HNSW configuration
object

m?:

number
Maximum number of connections per node (default: 8)

efConstruction?:

number
Build-time complexity (default: 32)

Memory Requirements

HNSW indexes require significant shared memory during construction. For 100K vectors:

  • Small dimensions (64d): ~60MB with default settings
  • Medium dimensions (256d): ~180MB with default settings
  • Large dimensions (384d+): ~250MB+ with default settings

Higher M values or efConstruction values will increase memory requirements significantly. Adjust your system’s shared memory limits if needed.

upsert()

indexName:

string
Name of the index to upsert vectors into

vectors:

number[][]
Array of embedding vectors

metadata?:

Record<string, any>[]
Metadata for each vector

ids?:

string[]
Optional vector IDs (auto-generated if not provided)

query()

indexName:

string
Name of the index to query

vector:

number[]
Query vector

topK?:

number
= 10
Number of results to return

filter?:

Record<string, any>
Metadata filters

includeVector?:

boolean
= false
Whether to include the vector in the result

minScore?:

number
= 0
Minimum similarity score threshold

options?:

{ ef?: number; probes?: number }
Additional options for HNSW and IVF indexes
object

ef?:

number
HNSW search parameter

probes?:

number
IVF search parameter

listIndexes()

Returns an array of index names as strings.

describeIndex()

indexName:

string
Name of the index to describe

Returns:

interface PGIndexStats {
  dimension: number;
  count: number;
  metric: "cosine" | "euclidean" | "dotproduct";
  type: "flat" | "hnsw" | "ivfflat";
  config: {
    m?: number;
    efConstruction?: number;
    lists?: number;
    probes?: number;
  };
}

deleteIndex()

indexName:

string
Name of the index to delete

updateIndexById()

indexName:

string
Name of the index containing the vector

id:

string
ID of the vector to update

update:

object
Update parameters
object

vector?:

number[]
New vector values

metadata?:

Record<string, any>
New metadata values

Updates an existing vector by ID. At least one of vector or metadata must be provided.

// Update just the vector
await pgVector.updateIndexById("my_vectors", "vector123", {
  vector: [0.1, 0.2, 0.3],
});
 
// Update just the metadata
await pgVector.updateIndexById("my_vectors", "vector123", {
  metadata: { label: "updated" },
});
 
// Update both vector and metadata
await pgVector.updateIndexById("my_vectors", "vector123", {
  vector: [0.1, 0.2, 0.3],
  metadata: { label: "updated" },
});

deleteIndexById()

indexName:

string
Name of the index containing the vector

id:

string
ID of the vector to delete

Deletes a single vector by ID from the specified index.

await pgVector.deleteIndexById("my_vectors", "vector123");

disconnect()

Closes the database connection pool. Should be called when done using the store.

buildIndex()

indexName:

string
Name of the index to define

metric?:

'cosine' | 'euclidean' | 'dotproduct'
= cosine
Distance metric for similarity search

indexConfig:

IndexConfig
Configuration for the index type and parameters

Builds or rebuilds an index with specified metric and configuration. Will drop any existing index before creating the new one.

// Define HNSW index
await pgVector.buildIndex("my_vectors", "cosine", {
  type: "hnsw",
  hnsw: {
    m: 8,
    efConstruction: 32,
  },
});
 
// Define IVF index
await pgVector.buildIndex("my_vectors", "cosine", {
  type: "ivfflat",
  ivf: {
    lists: 100,
  },
});
 
// Define flat index
await pgVector.buildIndex("my_vectors", "cosine", {
  type: "flat",
});

Response Types ✅

Query results are returned in this format:

interface QueryResult {
  id: string;
  score: number;
  metadata: Record<string, any>;
  vector?: number[]; // Only included if includeVector is true
}

Error Handling ✅

The store throws typed errors that can be caught:

try {
  await store.query({
    indexName: "index_name",
    queryVector: queryVector,
  });
} catch (error) {
  if (error instanceof VectorStoreError) {
    console.log(error.code); // 'connection_failed' | 'invalid_dimension' | etc
    console.log(error.details); // Additional error context
  }
}

Best Practices ✅

  • Regularly evaluate your index configuration to ensure optimal performance.
  • Adjust parameters like lists and m based on dataset size and query requirements.
  • Rebuild indexes periodically to maintain efficiency, especially after significant data changes.

Related ✅

Last updated on
CloudflareVectorLibSQLVector