# Laravel:vector Search

> Add semantic search with native vector queries (Laravel 13+); pgvector similarity clauses, embedding workflows, and hybrid search patterns

- Skill: `jpcaparas/laravel-vector-search` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jpcaparas/laravel-vector-search`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jpcaparas/laravel-vector-search/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: jpcaparas (https://skillmd.com/u/jpcaparas)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jpcaparas/laravel-vector-search

---


# 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)