README

Portable vector columns, casts, and similarity queries for Laravel.

Requirements

PHP 8.3 or later
Laravel 11, 12, or 13
A supported database with its vector features enabled

Database	Vector storage and distance support	Notes
PostgreSQL	`vector` and pgvector cosine distance	Install the pgvector extension.
MySQL 9.0+	Native `VECTOR` and `VECTOR_DISTANCE`	Distance functions require MySQL HeatWave on OCI or MySQL AI.
MariaDB 11.7+	Native `VECTOR` and `VEC_DISTANCE_COSINE`	Uses MariaDB's vector functions.
SQL Server 2025 / Azure SQL	Native `VECTOR` and `VECTOR_DISTANCE`	Vector support depends on the server edition and update policy.
SingleStore	Vector values and `DOT_PRODUCT`	Cosine similarity is computed from dot products and vector magnitudes.
SQLite	BLOB storage and `vec_distance_cosine`	Load the `sqlite-vec` extension on each connection.

CI exercises vector columns and queries on SQLite, PostgreSQL, and MariaDB. Its MySQL Community job verifies vector storage and casts; MySQL distance functions require HeatWave on OCI or MySQL AI. SQL Server and SingleStore are covered by SQL-generation and cast-expression tests, not live database integration tests.

Install

composer require illuma-law/laravel-vector-schema

Laravel discovers the service provider automatically. It registers the vectorColumn, hnswIndex, and dropHnswIndex schema macros and the vector query macros.

Define a vector column

Use vectorColumn in a migration. Pass the vector dimension required by your embedding model.

use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;
use IllumaLaw\VectorSchema\VectorSchema;

VectorSchema::ensureExtension(); // Creates pgvector when using PostgreSQL.

Schema::create('documents', function (Blueprint $table): void {
    $table->id();
    $table->text('content');
    $table->vectorColumn('embedding', 3)->nullable();
    $table->timestamps();
});

Schema::table('documents', function (Blueprint $table): void {
    $table->hnswIndex('embedding'); // PostgreSQL only; ignored by other drivers.
});

Cast vectors to PHP arrays

use Illuminate\Database\Eloquent\Model;
use IllumaLaw\VectorSchema\Casts\VectorArray;

class Document extends Model
{
    protected $casts = [
        'embedding' => VectorArray::class,
    ];
}

$document = new Document;
$document->content = 'A short example';
$document->embedding = [0.1, 0.5, -0.3];
$document->save();

Search by cosine similarity

$queryVector = [0.1, 0.5, -0.3];

$documents = Document::query()
    ->whereHybridVectorSimilarTo(
        column: 'embedding',
        vector: $queryVector,
        minSimilarity: 0.7,
    )
    ->limit(10)
    ->get();

Other query macros are selectHybridVectorDistance, whereHybridVectorDistanceLessThan, and orderByHybridVectorDistance. Distances sort ascending for nearest-first results.

Run tests

composer install
composer test
composer analyse
composer format -- --test

See the changelog for release notes.

illuma-law / laravel-vector-schema

Package info

Security

Fund package maintenance!

Statistics