Laravel Pgvector Eloquent: Vector Similarity Search & HNSW Indexing in Laravel

Building AI-powered features, semantic search, and recommendation engines in Laravel usually meant relying on external vector databases like Pinecone or Weaviate. With PostgreSQL pgvector, you can store vector embeddings directly alongside your relational business data.

laravel-pgvector-eloquent is a clean, idiomatic Laravel package that provides first-class pgvector support for Eloquent models.

seotarek / laravel-pgvector-eloquent

Seamless PostgreSQL pgvector integration for Laravel Eloquent with cosine/L2 distance query scopes and HNSW indexing.

Laravel pgvector Eloquent 🐘⚡

Native PostgreSQL pgvector integration for Laravel 11 Eloquent models with custom vector casting, cosine distance scopes, and nearest-neighbor vector search.

Developed by Tarek Mohamed (@seotarek)

---

🚀 Installation

composer require seotarek/laravel-pgvector-eloquent

---

💻 Usage

1. In your Eloquent Model:

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Seotarek\Pgvector\Casts\VectorCast;
use Seotarek\Pgvector\Traits\HasVectors;

class Document extends Model
{
    use HasVectors;

    protected $casts = [
        'embedding' => VectorCast::class,
    ];
}

2. Semantic Search with Cosine Distance:

$userQueryEmbedding = [0.012, 0.451, -0.231, ...];

// Find 5 most semantically similar documents
$results = Document::whereNearest('embedding', $userQueryEmbedding, 5)->get();

---

📜 License

Open-source software licensed under the MIT License.

View on GitHub

---

⚡ Features

• Intuitive Query Scopes: Search using nearestNeighbors('embedding', $queryVector, distance: 'cosine').
• HNSW & IVFFlat Migration Helpers: Clean Blueprint macros to build high-performance vector indexes directly in Laravel migrations.
• Type-safe Vector Cast: Automatically serializes PHP arrays and float vectors to pgvector's native binary format.

---

💻 Eloquent Usage

use App\Models\Article;

// Find 5 most similar articles to an input embedding vector
$similarArticles = Article::query()
    ->nearestNeighbors('embedding', $queryEmbedding, distance: 'cosine')
    ->limit(5)
    ->get();

Star the package on GitHub:
👉 https://github.com/seotarek/laravel-pgvector-eloquent