Embeddings Pattern | Bootspring Docs

Generate and manage vector embeddings for semantic search, similarity matching, and retrieval-augmented generation (RAG).

Overview#

Embeddings convert text into numerical vectors that capture semantic meaning. Similar texts produce similar vectors, enabling semantic search, recommendations, and RAG applications.

When to use:

Semantic search (find similar content by meaning)
RAG applications (knowledge bases, document Q&A)
Recommendation systems
Content deduplication
Clustering and classification

Key features:

OpenAI embedding models
PostgreSQL vector storage with pgvector
Semantic similarity search
Text chunking strategies
Batch processing

Code Example#

OpenAI Embeddings#

// lib/embeddings.ts
import OpenAI from 'openai'

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY
})

export async function getEmbedding(text: string) {
  const response = await openai.embeddings.create({
    model: 'text-embedding-3-small',
    input: text
  })

  return response.data[0].embedding
}

export async function getEmbeddings(texts: string[]) {
  const response = await openai.embeddings.create({
    model: 'text-embedding-3-small',
    input: texts
  })

  return response.data.map((d) => d.embedding)
}

Store with Prisma + pgvector#

// lib/embeddings.ts
import { prisma } from '@/lib/db'

export async function storeDocument(
  content: string,
  metadata: Record<string, any>
) {
  const embedding = await getEmbedding(content)

  await prisma.$executeRaw`
    INSERT INTO documents (content, metadata, embedding)
    VALUES (${content}, ${metadata}::jsonb, ${embedding}::vector)
  `
}

Semantic Search#

// lib/embeddings.ts
export async function semanticSearch(
  query: string,
  limit = 5
) {
  const queryEmbedding = await getEmbedding(query)

  const results = await prisma.$queryRaw`
    SELECT
      id,
      content,
      metadata,
      1 - (embedding <=> ${queryEmbedding}::vector) as similarity
    FROM documents
    ORDER BY embedding <=> ${queryEmbedding}::vector
    LIMIT ${limit}
  `

  return results
}

Text Chunking Strategy#

// lib/chunking.ts
export function chunkText(
  text: string,
  chunkSize = 1000,
  overlap = 200
) {
  const chunks: string[] = []
  let start = 0

  while (start < text.length) {
    const end = Math.min(start + chunkSize, text.length)
    chunks.push(text.slice(start, end))
    start += chunkSize - overlap
  }

  return chunks
}

// Index a document with chunking
export async function indexDocument(content: string, docId: string) {
  const chunks = chunkText(content)

  for (let i = 0; i < chunks.length; i++) {
    await storeDocument(chunks[i], {
      source: 'document',
      documentId: docId,
      chunkIndex: i
    })
  }
}

Database Schema#

-- Enable pgvector extension
CREATE EXTENSION IF NOT EXISTS vector;

-- Create documents table with vector column
CREATE TABLE documents (
  id SERIAL PRIMARY KEY,
  content TEXT NOT NULL,
  metadata JSONB,
  embedding vector(1536),
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Create index for fast similarity search
CREATE INDEX ON documents
USING ivfflat (embedding vector_cosine_ops)
WITH (lists = 100);

Prisma Schema with pgvector#

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

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

model Document {
  id        String   @id @default(cuid())
  content   String
  metadata  Json?
  embedding Unsupported("vector(1536)")?
  createdAt DateTime @default(now())
}

Usage Instructions#

Set up pgvector: Enable the pgvector extension in your PostgreSQL database
Generate embeddings: Use OpenAI's embedding API to convert text to vectors
Store embeddings: Save vectors alongside your content in the database
Create indexes: Add IVFFlat or HNSW indexes for fast similarity search
Search semantically: Query using cosine distance for relevant results

Best Practices#

Choose the right model - text-embedding-3-small is cost-effective; text-embedding-3-large offers higher quality
Chunk appropriately - Keep chunks between 500-1500 characters with overlap
Use overlap - 10-20% overlap prevents losing context at chunk boundaries
Batch requests - Process multiple texts in single API calls to reduce latency
Cache embeddings - Store embeddings to avoid regenerating for unchanged content
Index wisely - Use IVFFlat for faster queries, HNSW for better recall
Normalize vectors - Ensure consistent similarity scores by normalizing

RAG - Use embeddings for retrieval-augmented generation
Semantic Search - Full-text and vector search
Database Patterns - Prisma setup and queries