Vector search

Semantic search via embeddings, built into Convex. Pair with OpenAI / other embedding providers.

Convex includes native vector search — no Pinecone or Qdrant required for most apps.

Setup

1. Add a vector index to the schema

convex/schema.ts

documents: defineTable({
  title:     v.string(),
  body:      v.string(),
  ownerId:   v.id("users"),
  embedding: v.array(v.number()),
})
  .vectorIndex("by_embedding", {
    vectorField:  "embedding",
    dimensions:   1536,             // OpenAI text-embedding-3-small
    filterFields: ["ownerId"],
  })

2. Embed and store

convex/documents.ts

import { action } from "./_generated/server";
import { api } from "./_generated/api";

export const indexDocument = action({
  args: { id: v.id("documents") },
  handler: async (ctx, { id }) => {
    const doc = await ctx.runQuery(api.documents.get, { id });
    if (!doc) return;

    const embedding = await embedText(`${doc.title}\n\n${doc.body}`);
    await ctx.runMutation(api.documents.setEmbedding, { id, embedding });
  },
});

3. Search

convex/documents.ts

export const search = action({
  args: { query: v.string(), ownerId: v.id("users") },
  handler: async (ctx, { query, ownerId }) => {
    const queryEmbedding = await embedText(query);

    const results = await ctx.vectorSearch("documents", "by_embedding", {
      vector: queryEmbedding,
      limit:  10,
      filter: q => q.eq("ownerId", ownerId),
    });

    // results: [{ _id, _score }, ...]
    const docs = await Promise.all(
      results.map(r => ctx.runQuery(api.documents.get, { id: r._id }))
    );
    return docs.filter(Boolean);
  },
});

Embedding providers

Common choices:

Provider	Model	Dimensions
OpenAI	text-embedding-3-small	1536
OpenAI	text-embedding-3-large	3072
Cohere	embed-v3-english	1024
Voyage AI	voyage-2	1024

Pick one and stick with it — mixing dimensions across the same index doesn’t work.

Tips

Re-embed when content changes. If you edit a document’s body, queue a re-embed (typically via a scheduled action or directly in the mutation that updated the body).

Use filter fields aggressively. Vector search returns the most-similar items; filter to the right scope (per-user, per-team) before vector matching.

Related

Schema

Vector index syntax.

OpenAI

Embedding provider.

AI chatbot recipe

RAG pattern using vector search.