Vector Semantic Search

---
name: laravel:vector-search
description: Add semantic search with native vector queries (Laravel 13+); pgvector similarity clauses, embedding workflows, and hybrid search patterns
---

# Semantic / Vector Search (Laravel 13+)

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)