x-laravel/embedding — MySQL 9 Driver

MySQL HeatWave native vector driver for x-laravel/embedding.

How It Works

• Implements SimilarityDriver — registers as the mysql driver, similarity search runs entirely in MySQL using VEC_DISTANCE_COSINE
• Implements VectorStore — writes embeddings via INSERT ... ON DUPLICATE KEY UPDATE with STRING_TO_VECTOR(), reads via a VECTOR_TO_STRING global scope
• Translates payload filter: constraints to type-strict JSON_EXTRACT / JSON_TYPE SQL against the embeddables table

Requirements

• PHP ^8.3
• Laravel ^12.0 | ^13.0
• x-laravel/embedding ^1.0
• MySQL HeatWave — VEC_DISTANCE_COSINE is not available in MySQL Community Edition; this driver requires MySQL HeatWave

Installation

composer require x-laravel/embedding-mysql-driver

The MysqlEmbeddingServiceProvider is auto-discovered and registers the mysql driver automatically.

Setup

1. Configure x-laravel/embedding

Publish the config if you haven't already:

php artisan vendor:publish --tag=embedding-config

Set the similarity driver and database connection in config/embedding.php:

'database' => [
    'connection' => env('EMBEDDINGS_DATABASE_CONNECTION', env('DB_CONNECTION', 'mysql')),
    'embeddings_table' => env('EMBEDDINGS_DB_TABLE', 'embeddings'),
    'embeddables_table' => env('EMBEDDABLES_DB_TABLE', 'embeddables'),
],

'similarity' => [
    'driver' => env('EMBEDDING_SIMILARITY_DRIVER', 'mysql'),
],

2. Create the tables

This driver ships its own MySQL-native migrations that replace the default ones from x-laravel/embedding: embeddings with a VECTOR(1536) column and embeddables with a native JSON payload column.

Publish and run the migrations (migrations are not loaded automatically — publish the driver migrations, not the core ones):

php artisan vendor:publish --tag=embedding-mysql-migrations
php artisan migrate

The published files are plain migrations in database/migrations/ — customise the DDL there if needed before running migrate.

Note: VEC_DISTANCE_COSINE is only available on MySQL HeatWave, not MySQL Community Edition. For production, add a VECTOR INDEX on the vector column after publishing the migration.

3. Model

Follow the standard x-laravel/embedding setup. No MySQL-specific changes are needed on your models.

use XLaravel\Embedding\Attributes\EmbedOn;
use XLaravel\Embedding\Concerns\Embeddable;
use XLaravel\Embedding\Contracts\HasEmbeddings;

#[EmbedOn(['title', 'body'])]
class Post extends Model implements HasEmbeddings
{
    use Embeddable;

    public function toEmbeddingText(string $slot = 'default'): string
    {
        return $this->title.' '.$this->body;
    }
}

Usage

The driver is transparent — use the standard x-laravel/embedding API:

Post::similarToText('web framework', limit: 10);
Post::similarTo($vector, limit: 10, threshold: 0.8);
Post::rankByRelevance($posts, 'web framework');

$post->mostSimilar(limit: 5);
$post->similarityTo($otherPost);

All methods set a similarity_score float attribute on each returned model.

Payload filtering

Models using #[EmbedPayload] can filter similarity searches at the database level. The driver translates filter: to a whereExists subquery against embeddables: every condition checks the value's JSON_TYPE and compares it with CAST(? AS JSON), so comparisons are type-strict (34 never matches "34", true never matches 1) and strings compare case-sensitively:

use XLaravel\Embedding\Attributes\EmbedPayload;

#[EmbedOn('name')]
#[EmbedPayload(['province_id', 'category_id', 'active'])]
class Venue extends Model implements HasEmbeddings { ... }

Venue::similarTo($vector, limit: 300, filter: ['province_id' => 34]);            // equality
Venue::similarToText('kebap', filter: ['category_id' => [3, 7]]);                // IN
$venue->mostSimilar(limit: 5, filter: ['province_id' => 34, 'active' => true]);  // AND

Note: MySQL returns TINYINT(1) columns as integers. Add a boolean cast to boolean payload fields on your models — otherwise the payload stores 1 instead of true, and filter: ['active' => true] stops matching.

Testing

Tests require a MySQL HeatWave instance. The docker-compose.yml uses mysql:9.1.0 for CI convenience but VEC_DISTANCE_COSINE tests will fail against Community Edition — run them against a real HeatWave instance.

# Build first (once per PHP version)
DOCKER_BUILDKIT=0 docker compose --profile php83 build

# Run tests
docker compose --profile php83 up
docker compose --profile php84 up
docker compose --profile php85 up

License

This package is open-sourced software licensed under the MIT license.