DEV Community: Neil Charlton

Intro to Embeddings and Vector Storage with pgvector

Neil Charlton — Wed, 21 May 2025 11:18:46 +0000

I recently found myself exploring the world of vector search—specifically, whether to use pgvector (a PostgreSQL extension) or a dedicated vector database like Pinecone, Weaviate, Milvus, or Qdrant. Here's a detailed, first-person account of what I learned, the trade-offs, and how I approached the problem for my own project.

Understanding the Options

pgvector is an open-source extension for PostgreSQL that lets you store and search vector data (like embeddings from machine learning models) right inside your existing database. In contrast, a dedicated vector database is built from the ground up for storing, indexing, and searching high-dimensional vectors at scale.

Use Cases: When Does Each Make Sense?

When pgvector Shines

For me, pgvector was appealing because I already had a PostgreSQL database running my application. It's perfect if you want to:

Add vector search to an existing app without introducing a new system.
Prototype or experiment with ML features like semantic search or recommendations.
Run hybrid queries that mix vector search with classic SQL (e.g., "find similar posts, but only those by user X").
Rely on strong transactional guarantees (ACID) for both relational and vector data.

When a Dedicated Vector DB is Better

If you're dealing with:

Millions or billions of vectors and need lightning-fast, scalable search.
Real-time applications (like chatbots or image search) where latency is critical.
Advanced features like distributed indexing, hybrid search, or multi-modal data (text, image, audio).
The need for managed, cloud-native solutions with auto-scaling and high availability.

Then a dedicated vector database is likely the way to go.

Advantages and Disadvantages

pgvector: The Good and the Not-So-Good

Advantages:

Simplicity—no new infrastructure, just PostgreSQL.
Full ACID compliance, so data stays in sync.
Cost-effective for small/medium workloads.
Easy integration with existing tools and workflows.
Effortless hybrid queries with SQL.

Disadvantages:

Not as fast or scalable for huge datasets.
Fewer indexing options for approximate nearest neighbor (ANN) search.
Vector search can compete with other database workloads.
Lacks some advanced features found in dedicated vector DBs.

Dedicated Vector DB: Pros and Cons

Advantages:

Blazing performance at scale.
Designed for billions of vectors and high query throughput.
Advanced indexing algorithms (HNSW, IVF, PQ, etc.).
Rich feature set: metadata filtering, hybrid search, multi-tenancy.
Many offer fully managed, cloud-native services.

Disadvantages:

Adds operational complexity (another system to manage).
Syncing data between systems can be tricky if you need strong consistency.
Managed services can get expensive.
New APIs and concepts to learn.

My Scenario: Posts and Comments in PostgreSQL

I have a PostgreSQL database with a posts table and a comments table (each comment belongs to a post). I wanted to track trends and perform similarity searches on data I've scraped from online sources.

My Approach

Start with pgvector: Since my data volume was modest and I wanted to keep things simple, I decided to try pgvector first.
Install and Configure pgvector:

   CREATE EXTENSION vector;

Add Embedding Columns:

   ALTER TABLE posts ADD COLUMN embedding vector(1536); -- Assuming OpenAI embeddings
   ALTER TABLE comments ADD COLUMN embedding vector(1536);

Generate Embeddings: I used a model (like OpenAI's text-embedding-ada-002) to generate embeddings for each post and comment.
Indexing: I created an IVF index to speed up similarity searches:

   CREATE INDEX ON posts USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);
   CREATE INDEX ON comments USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);

Similarity Search: I could now find similar posts:

   SELECT
       id,
       title
   FROM
       posts
   ORDER BY
       embedding <#> (SELECT embedding FROM posts WHERE id = 123)
   LIMIT 10;

Trend Tracking: I used SQL to cluster similar posts/comments and analyze trends over time.

Monitoring and Scaling

I kept an eye on query latency and resource usage. If performance ever became an issue (as my data grew), I knew I could transition to a dedicated vector database or use a hybrid approach (PostgreSQL for relational data, vector DB for embeddings).

How I Chose the Embedding Size

The embedding size depends on the model you use. For example:

OpenAI's text-embedding-ada-002: 1536 dimensions.
Sentence Transformers (like all-mpnet-base-v2): 768 dimensions.

I checked the model documentation or ran a quick test to inspect the output shape. If storage or performance became a concern, I considered dimensionality reduction (like PCA), but always balanced that against potential accuracy loss.

Combining Post and Comment Embeddings

I also explored creating an aggregate embedding for each post, combining the post content and all its comments:

CREATE TABLE post_aggregate_embeddings (
    post_id INTEGER PRIMARY KEY REFERENCES posts(id),
    embedding vector(1536) -- Adjust size as needed
);

-- Create an index for efficient similarity searches
CREATE INDEX ON post_aggregate_embeddings USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);

This enabled:

Semantic search across the entire conversation (not just the post).
Trend analysis based on discussion topics.
Anomaly detection (e.g., when comments deviate from the post's topic).

I could then query for similar discussions:

SELECT
    p.id,
    p.title
FROM
    posts p
JOIN
    post_aggregate_embeddings pae ON p.id = pae.post_id
ORDER BY
    pae.embedding <#> (SELECT embedding FROM post_aggregate_embeddings WHERE post_id = 123)
LIMIT 10;

The trade-off was increased complexity and the need to update the aggregate embedding whenever comments changed.

Similarity Metrics: Which One Should I Use?

pgvector supports several similarity metrics:

Euclidean Distance (<->):

   SELECT id, title FROM posts
   ORDER BY embedding <-> (SELECT embedding FROM posts WHERE id = 123)
   LIMIT 10;

Finds posts similar in both topic and length/detail.

Inner Product (<#>):

   SELECT id, title FROM posts
   ORDER BY embedding <#> (SELECT embedding FROM posts WHERE id = 123) DESC
   LIMIT 10;

Finds posts most relevant to a normalized query. Note the DESC keyword since larger inner product means greater similarity.

Cosine Distance:

   SELECT id, title FROM posts
   ORDER BY embedding <=> (SELECT embedding FROM posts WHERE id = 123)
   LIMIT 10;

Finds posts about the same topic, regardless of length.

My rule of thumb:

Use cosine distance for most semantic search tasks, Euclidean if you care about content length, and inner product for search/recommendation with normalized queries.

Practical Use Cases in My System

Euclidean Distance: Recommending posts that are similar in both topic and depth/detail to a given post.
Inner Product: Finding posts most relevant to a user's search query, regardless of post length.
Cosine Distance: Clustering or recommending posts purely based on topic similarity, ignoring length.

My Recommendation

If you're already using PostgreSQL and your vector data isn't massive, start with pgvector. It's simple, cost-effective, and integrates seamlessly with your existing stack. Monitor performance as your data grows. If you hit bottlenecks, consider a dedicated vector database or a hybrid approach.

By starting small and iterating, you'll gain valuable insights into your needs and be better equipped to scale when the time comes.

If you have a similar use case or want to discuss your specific scenario, feel free to reach out! I'm always happy to share what I've learned or help you brainstorm the best approach.

When to Split React Reducers: A Practical Guide

Neil Charlton — Wed, 19 Mar 2025 18:48:44 +0000

Managing state in React applications can quickly become complex, especially as your application grows. One of the most common questions developers face is when and how to split their reducers. Let's dive into this topic with real-world examples and practical advice.

The Single Reducer Pattern: When It Works and When It Doesn't

Let's start with a common scenario: an e-commerce dashboard that manages both UI state (like modal visibility, selected tabs) and data state (product inventory, orders). Initially, you might start with a single reducer:

type DashboardState = {
  // UI State
  isProductModalOpen: boolean;
  selectedTab: 'inventory' | 'orders' | 'analytics';
  sidebarCollapsed: boolean;

  // Data State
  products: Product[];
  orders: Order[];
  loadingProducts: boolean;
  loadingOrders: boolean;
  error: string | null;
};

const dashboardReducer = (state: DashboardState, action: DashboardAction): DashboardState => {
  switch (action.type) {
    case 'TOGGLE_PRODUCT_MODAL':
      return { ...state, isProductModalOpen: !state.isProductModalOpen };
    case 'SET_SELECTED_TAB':
      return { ...state, selectedTab: action.payload };
    case 'FETCH_PRODUCTS_START':
      return { ...state, loadingProducts: true };
    case 'FETCH_PRODUCTS_SUCCESS':
      return { 
        ...state, 
        products: action.payload,
        loadingProducts: false,
        error: null
      };
    // ... many more cases
  }
};

This quickly becomes hard to manage for several specific reasons:

The state shape becomes increasingly complex and intertwined, making it difficult to understand which parts of the state are related to UI and which are related to data.
The reducer function grows larger, often exceeding 200-300 lines of code, making it harder to maintain and test.
Different team members working on different features might create conflicts when modifying the same reducer file.
Type definitions become unwieldy as you add more state properties.

Splitting by Concern: UI vs. Data

A better approach is to split the reducer based on concerns. Here's how we can separate UI state from data state:

// uiReducer.ts
type UIState = {
  isProductModalOpen: boolean;
  selectedTab: 'inventory' | 'orders' | 'analytics';
  sidebarCollapsed: boolean;
};

const uiReducer = (state: UIState, action: UIAction): UIState => {
  switch (action.type) {
    case 'TOGGLE_PRODUCT_MODAL':
      return { ...state, isProductModalOpen: !state.isProductModalOpen };
    case 'SET_SELECTED_TAB':
      return { ...state, selectedTab: action.payload };
    case 'TOGGLE_SIDEBAR':
      return { ...state, sidebarCollapsed: !state.sidebarCollapsed };
    default:
      return state;
  }
};

// dataReducer.ts
type DataState = {
  products: Product[];
  orders: Order[];
  loadingProducts: boolean;
  loadingOrders: boolean;
  error: string | null;
};

const dataReducer = (state: DataState, action: DataAction): DataState => {
  switch (action.type) {
    case 'FETCH_PRODUCTS_START':
      return { ...state, loadingProducts: true };
    case 'FETCH_PRODUCTS_SUCCESS':
      return {
        ...state,
        products: action.payload,
        loadingProducts: false,
        error: null
      };
    case 'FETCH_PRODUCTS_ERROR':
      return {
        ...state,
        loadingProducts: false,
        error: action.payload
      };
    // ... other data-related cases
    default:
      return state;
  }
};

When to Split Further: Domain-Driven Separation

As your application grows, you might find that even the data reducer becomes too large. This is particularly true when you're dealing with multiple domains in your application. Let's consider when you should split the data reducer further:

When different teams are working on different features
When state updates in one domain rarely affect other domains
When testing becomes complicated due to the size of the reducer
When you notice performance issues due to frequent updates

Here's an example of splitting the data reducer by domain:

// productReducer.ts
type ProductState = {
  items: Product[];
  loading: boolean;
  error: string | null;
  categories: Category[];
};

const productReducer = (state: ProductState, action: ProductAction): ProductState => {
  switch (action.type) {
    case 'FETCH_PRODUCTS_START':
      return { ...state, loading: true };
    case 'UPDATE_PRODUCT_INVENTORY':
      return {
        ...state,
        items: state.items.map(product =>
          product.id === action.payload.id
            ? { ...product, inventory: action.payload.inventory }
            : product
        )
      };
    // ... other product-specific cases
  }
};

// orderReducer.ts
type OrderState = {
  orders: Order[];
  loading: boolean;
  error: string | null;
  activeFilters: OrderFilter[];
};

const orderReducer = (state: OrderState, action: OrderAction): OrderState => {
  switch (action.type) {
    case 'UPDATE_ORDER_STATUS':
      return {
        ...state,
        orders: state.orders.map(order =>
          order.id === action.payload.orderId
            ? { ...order, status: action.payload.status }
            : order
        )
      };
    // ... other order-specific cases
  }
};

Real-World Benefits of Splitting Reducers

Improved Performance: When you split reducers, React can optimize re-renders better. For example, if you update the UI state (like toggling a modal), components that only depend on order data won't re-render.
Better Testing: Smaller, focused reducers are easier to test. You can write specific tests for UI behavior without worrying about data state:

describe('uiReducer', () => {
  it('should toggle product modal', () => {
    const initialState = { isProductModalOpen: false, selectedTab: 'inventory', sidebarCollapsed: false };
    const action = { type: 'TOGGLE_PRODUCT_MODAL' as const };

    const newState = uiReducer(initialState, action);
    expect(newState.isProductModalOpen).toBe(true);
  });
});

Easier Maintenance: When bugs occur, it's easier to isolate the problem to a specific reducer. If there's an issue with order status updates, you know exactly where to look.
Better Type Safety: TypeScript types become more focused and manageable:

type ProductAction =
  | { type: 'FETCH_PRODUCTS_START' }
  | { type: 'FETCH_PRODUCTS_SUCCESS'; payload: Product[] }
  | { type: 'UPDATE_PRODUCT_INVENTORY'; payload: { id: string; inventory: number } };

// Instead of one large union type for all actions
type DashboardAction = ProductAction | OrderAction | UIAction; // This becomes unwieldy

When Not to Split Reducers

While splitting reducers has many benefits, there are cases where it might not be necessary:

In small applications with limited state
When state updates frequently need to coordinate between different domains
When the overhead of managing multiple reducers outweighs the benefits

The key is to find the right balance for your specific use case. Start with a single reducer, and split when you notice:

The reducer file exceeding 200 lines
Multiple developers frequently conflicting in the same file
Testing becoming difficult
Performance issues related to unnecessary re-renders

Remember, the goal of splitting reducers is to make your application more maintainable, performant, and easier to understand. Don't split just for the sake of splitting – let your application's needs guide your decision.

Taming the useEffect Beast: Common Issues and Solutions

Neil Charlton — Mon, 03 Mar 2025 08:01:53 +0000

Hey there, fellow React developer! If you've ever found yourself scratching your head over a mysterious infinite loop or wondering why your component is behaving like it has a mind of its own, chances are you've fallen into one of the many useEffect traps. Let's walk through some common issues and how to solve them in a TypeScript-friendly way.

The Infinite Loop of Doom

We've all been there. You set up what seems like a perfectly reasonable useEffect, and suddenly your application is making API calls faster than you can say "React."

// 🚫 Danger Zone
const MyComponent = () => {
  const [data, setData] = useState<string[]>([]);

  useEffect(() => {
    // This will run on every render!
    fetchData().then(result => setData(result));
  }); // Missing dependency array

  return <div>{data.join(', ')}</div>;
};

The problem? We're missing the dependency array, so this effect runs after every render. And since it updates state, it triggers another render, creating our infinite loop.

The fix is simple:

// ✅ Fixed version
useEffect(() => {
  fetchData().then(result => setData(result));
}, []); // Empty dependency array means "run once on mount"

The Stale Closure Conundrum

This one's sneaky. You've got a function in your effect that uses some prop or state, but it's always using an old value:

// 🚫 Danger Zone
type Props = {
  initialCount: number
}

export const Counter = ({ initialCount }: Props) => {
  const [count, setCount] = useState(initialCount);

  useEffect(() => {
    const timer = setInterval(() => {
      console.log(`Current count is: ${count}`);
      setCount(count + 1); // This will always use the initial value of count!
    }, 1000);

    return () => clearInterval(timer);
  }, []); // count is missing from dependencies

  return <div>{count}</div>;
};

The issue here is that our interval callback "closes over" the initial value of count. Even though count changes on the screen, inside our interval it's stuck in time.

Here's how to fix it:

// ✅ Fixed version
useEffect(() => {
  const timer = setInterval(() => {
    setCount(prevCount => prevCount + 1); // Use the functional update form
  }, 1000);

  return () => clearInterval(timer);
}, []); // Now we don't need count in dependencies

The Dependency Array Dilemma

TypeScript can actually help us here! The ESLint plugin for React hooks will warn you when you're missing dependencies:

// 🚫 TypeScript will warn about this
interface UserProps {
  userId: string;
}
export const UserProfile = ({ userId }: UserProps) => {
  const [profile, setProfile] = useState<UserProfile | null>(null);

  useEffect(() => {
    fetchUserProfile(userId).then(setProfile);
  }, []); // ESLint will warn: 'userId' is missing in dependencies

  return <div>{profile?.name}</div>;
};

The solution is to include all dependencies:

// ✅ Fixed version
useEffect(() => {
  fetchUserProfile(userId).then(setProfile);
}, [userId]); // Now the effect will re-run when userId changes

The Cleanup Catastrophe

Forgetting to clean up after yourself can lead to memory leaks and weird bugs:

// 🚫 Danger Zone
export const NotificationComponent = () => {
  useEffect(() => {
    const subscription = subscribeToNotifications(notification => {
      console.log(notification);
    });
    // No cleanup!
  }, []);

  return <div>Notification Listener</div>;
};

Always return a cleanup function when you're setting up subscriptions, timers, or event listeners:

// ✅ Fixed version
useEffect(() => {
  const subscription = subscribeToNotifications(notification => {
    console.log(notification);
  });

  return () => {
    subscription.unsubscribe(); // Clean up when component unmounts
  };
}, []);

The Object/Array Dependency Trap

This one's particularly nasty. You include an object or array in your dependency array, but it's recreated on every render:

// 🚫 Danger Zone
interface TodoProps {
  userId: string;
}

export const TodoList = ({ userId }: TodoProps) => {
  const [todos, setTodos] = useState<Todo[]>([]);

  // This object is recreated on every render
  const options = { includeCompleted: true };

  useEffect(() => {
    fetchTodos(userId, options).then(setTodos);
  }, [userId, options]); // options is always "new", so effect always runs

  return <div>{todos.map(todo => <TodoItem key={todo.id} todo={todo} />)}</div>;
};

There are two ways to fix this:

// ✅ Solution 1: Move the object inside the effect
useEffect(() => {
  const options = { includeCompleted: true };
  fetchTodos(userId, options).then(setTodos);
}, [userId]);

// ✅ Solution 2: Memoize the object with useMemo
const options = useMemo(() => ({ 
  includeCompleted: true 
}), []);

useEffect(() => {
  fetchTodos(userId, options).then(setTodos);
}, [userId, options]);

The Type-Safe Effect with TypeScript

Let's make our effects more type-safe with TypeScript:

// Define proper types for your data and functions
interface User {
  id: string;
  name: string;
  email: string;
}

// Type your state properly
const [user, setUser] = useState<User | null>(null);
const [loading, setLoading] = useState<boolean>(true);
const [error, setError] = useState<Error | null>(null);

// Type your effect callback parameters
useEffect(() => {
  const fetchUser = async (id: string): Promise<void> => {
    try {
      setLoading(true);
      const response = await fetch(`/api/users/${id}`);
      if (!response.ok) {
        throw new Error('Failed to fetch user');
      }
      const userData: User = await response.json();
      setUser(userData);
    } catch (err) {
      setError(err instanceof Error ? err : new Error('Unknown error'));
    } finally {
      setLoading(false);
    }
  };

  fetchUser(userId);
}, [userId]);

The Custom Hook Solution

When effects get complex, consider extracting them into custom hooks:

// A custom hook to fetch user data
function useUser(userId: string): {
  user: User | null;
  loading: boolean;
  error: Error | null;
} {
  const [user, setUser] = useState<User | null>(null);
  const [loading, setLoading] = useState<boolean>(true);
  const [error, setError] = useState<Error | null>(null);

  useEffect(() => {
    let isMounted = true;

    const fetchUser = async (): Promise<void> => {
      try {
        setLoading(true);
        const response = await fetch(`/api/users/${userId}`);
        if (!response.ok) {
          throw new Error('Failed to fetch user');
        }
        const userData: User = await response.json();

        // Prevent state updates if component unmounted
        if (isMounted) {
          setUser(userData);
          setLoading(false);
        }
      } catch (err) {
        if (isMounted) {
          setError(err instanceof Error ? err : new Error('Unknown error'));
          setLoading(false);
        }
      }
    };

    fetchUser();

    // Cleanup function to prevent state updates after unmount
    return () => {
      isMounted = false;
    };
  }, [userId]);

  return { user, loading, error };
}

// Now your component is much cleaner
export const UserProfile = ({ userId }: UserProps) => {
  const { user, loading, error } = useUser(userId);

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  if (!user) return <div>No user found</div>;

  return (
    <div>
      <h3>{user.name}</h3>
      <p>{user.email}</p>
    </div>
  );
};

Final Thoughts

The useEffect hook is incredibly powerful, but with great power comes great responsibility. By understanding these common pitfalls and their solutions, you'll be well on your way to writing cleaner, more predictable React components.

Remember, TypeScript is your friend here! It can catch many dependency issues before they become runtime problems. And when in doubt, extract complex logic into custom hooks to keep your components clean and focused.

Happy coding, and may your effects always run exactly when you expect them to!

Type Guards Using Type Predicates in TypeScript

Neil Charlton — Sun, 02 Mar 2025 09:20:08 +0000

Type predicates are a powerful feature in TypeScript that allow you to create custom type guards to narrow down types in your code. Here's a simple tutorial on how to use them effectively.

What are Type Predicates?

A type predicate is a special return type for a function that tells TypeScript that the function is checking whether a variable is of a specific type. The syntax is:

function isType(param: SomeType | OtherType): param is SomeType {
  // logic to determine if param is SomeType
}

Basic Example

Let's start with a simple example:

// Define two types
interface Fish {
  swim: () => void;
}

interface Bird {
  fly: () => void;
}

// Create a type predicate function
function isFish(pet: Fish | Bird): pet is Fish {
  return (pet as Fish).swim !== undefined;
}

// Use the type predicate to narrow down types
function moveAnimal(animal: Fish | Bird) {
  if (isFish(animal)) {
    // TypeScript knows animal is Fish here
    animal.swim();
  } else {
    // TypeScript knows animal is Bird here
    animal.fly();
  }
}

Step-by-Step Guide

Define Your Types First, define the types you want to distinguish between:

interface Circle {
  kind: "circle";
  radius: number;
}

interface Square {
  kind: "square";
  sideLength: number;
}
type Shape = Circle | Square;

Create a Type Predicate Function Create a function that returns a type predicate:

function isCircle(shape: Shape): shape is Circle {
  return shape.kind === "circle";
}

The shape is Circle part is the type predicate. It tells TypeScript that if this function returns true, the parameter is of type Circle.

Use the Type Predicate for Type Narrowing Now you can use your predicate function to narrow types:

function getArea(shape: Shape) {
  if (isCircle(shape)) {
    // TypeScript knows shape is Circle here
    return Math.PI * shape.radius ** 2;
  } else {
    // TypeScript knows shape is Square here
    return shape.sideLength ** 2;
  }
}

Using Type Predicates with Arrays

Type predicates are especially useful when filtering arrays:

Copy Code
const shapes: Shape[] = [
  { kind: "circle", radius: 5 },
  { kind: "square", sideLength: 10 },
  { kind: "circle", radius: 3 }
];

// Filter to get only circles
const circles: Circle[] = shapes.filter(isCircle);

// You can also define inline predicates
const squares: Square[] = shapes.filter((shape): shape is Square => shape.kind === "square");

More Advanced Example: Complex Type Predicates

You can create more complex type predicates that check multiple conditions:

interface User {
  name: string;
  email?: string;
  phone?: string;
}

// Check if a user has complete contact information
function hasContactInfo(user: User): user is User & { email: string; phone: string } {
  return typeof user.email === "string" && typeof user.phone === "string";
}

function contactUser(user: User) {
  if (hasContactInfo(user)) {
    // TypeScript knows user has both email and phone here
    sendEmail(user.email);
    sendSMS(user.phone);
  } else {
    // Handle incomplete contact info
  }
}

Best Practices

Keep predicates simple: Focus on checking one specific aspect of a type.
Use descriptive names: Name your predicate functions clearly (e.g., isCircle, hasContactInfo).
Avoid side effects: Type predicates should be pure functions without side effects.
Consider using discriminated unions: They work well with type predicates.
By using type predicates, you can write more type-safe code that's also more readable and maintainable.