laravel:vector-search

Use native vector query support to build semantic search on PostgreSQL + pgvector. Generate embeddings via the AI SDK and query them directly from the query builder.

Commands

# Migration: vector column (requires pgvector extension)
Schema::table('documents', function (Blueprint $table) {
    $table->vector('embedding', dimensions: 1536);
});

# Generate an embedding
use Illuminate\Support\Str;
$embedding = Str::of('Best wineries in Napa Valley')->toEmbeddings();

# Similarity search from the query builder
$documents = DB::table('documents')
    ->whereVectorSimilarTo('embedding', 'Best wineries in Napa Valley')
    ->limit(10)
    ->get();

Patterns

• Store embeddings alongside the source row; regenerate when source text changes (model observer or queued job)
• Always limit() similarity queries; unbounded vector scans are expensive
• Add a vector index (HNSW/IVFFlat) for large tables; measure recall vs speed trade-offs
• Combine vector similarity with conventional where filters (tenant, status, locale) to scope results
• Consider hybrid search: merge keyword matches with semantic results for better precision
• Keep embedding model/dimensions in config; changing models invalidates stored vectors

Testing

• Fake embedding generation in tests; assert stored dimensions and invalidation triggers
• Integration test similarity queries against a Postgres service with pgvector enabled (skip gracefully if unavailable)