Download the PHP package x-laravel/embedding-qdrant-driver without Composer

x-laravel/embedding — Qdrant Driver

Qdrant vector database driver for x-laravel/embedding.

How It Works

• Implements SimilarityDriver — registers as the qdrant driver, similarity search runs entirely in Qdrant using its native ANN (Approximate Nearest Neighbor) engine
• Implements VectorStore — writes embeddings to both the SQL embeddings table (for Eloquent relationships) and the Qdrant collection (for search)
• Implements PayloadStore — keeps payload records in the SQL embeddables table and mirrors them onto the entity's Qdrant points, so payload filter: constraints run natively in Qdrant

Requirements

• PHP ^8.3
• Laravel ^12.0 | ^13.0
• x-laravel/embedding ^1.0
• Qdrant server (self-hosted or Qdrant Cloud)

Installation

The QdrantEmbeddingServiceProvider is auto-discovered and registers the qdrant driver automatically.

Setup

1. Configure x-laravel/embedding

Publish the config if you haven't already:

Set the similarity driver in config/embedding.php:

2. Configure Qdrant

Set the following environment variables:

Or publish the config to config/embedding-qdrant-driver.php for full customisation:

3. Create the SQL tables and the Qdrant collection

Migrations are not loaded automatically. Publish the core migrations (embeddings and embeddables tables) and this driver's Qdrant collection migration, then run them:

The embedding-qdrant tag also publishes config/embedding-qdrant-driver.php.

Note: The Qdrant collection is created with cosine similarity. The EMBEDDING_DIMENSIONS config value sets the vector size — it must match your AI model's output dimension.

4. Model

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

Usage

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

All methods set a similarity_score float attribute on each returned model. A threshold of 0.0 returns every match; a positive value is passed to Qdrant as score_threshold.

Payload filtering

Models using #[EmbedPayload] can filter similarity searches inside Qdrant:

How the payload reaches Qdrant:

• The SQL embeddables table stays the source of truth. QdrantPayloadStore extends the core DatabasePayloadStore: after writing the row it sets the same payload under the payload key of every Qdrant point of that entity (all slots), and removes that key when the row is deleted.
• QdrantVectorStore reads the entity's current embeddables row when it upserts a point, so a point written after the payload sync carries the payload too.
• The driver turns the filter into Qdrant conditions on payload.<key>: match.value for equality, match.any for IN, is_null for null, all ANDed in must. An empty array matches nothing.
• Qdrant matches by JSON type, so 34 never matches "34" and true never matches 1. Records without a payload row never match a filtered search.
• Hits are checked against the SQL tables before models are loaded: points whose embeddings row is gone, or (for a filtered search) whose embeddables row is gone, are dropped.

Filter keys must match ^[A-Za-z_][A-Za-z0-9_]*$. For large collections, create Qdrant payload indexes on embeddable_type, slot and the payload.<key> fields you filter on.

Note: Qdrant points are not deleted when their embeddings rows are: deleting a model, embedding:vector:clear and embedding:vector:clean remove SQL rows only, and embedding:payload:clear / embedding:payload:clean bypass the PayloadStore. Search results stay correct because hits are checked against SQL, but the stale points remain in the collection and count against limit. Run embedding:payload:sync --force after clearing payloads if you want Qdrant back in step.

Testing

License

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