Pgvector Scout Laravel Package

Getting Started

Start by installing the package and publishing its config:

composer require benbjurstrom/pgvector-scout
php artisan vendor:publish --tag="pgvector-scout-config"
php artisan vendor:publish --tag="scout-config"

Configure an embedding index (e.g., openai) in config/pgvector-scout.php, set SCOUT_DRIVER=pgvector, and install pgvector in PostgreSQL (via CREATE EXTENSION IF NOT EXISTS vector;). Then, run php artisan scout:index openai to generate the migration, and php artisan migrate. Finally, add HasEmbeddings and Searchable traits to your model, define searchableAs() and toSearchableArray()—and you're ready to embed and search.

Implementation Patterns

• Automatic syncing: Scout observers automatically trigger embedding generation on model saved, updated, and deleted events—no manual intervention needed.
• Multiple indexes: Define several indexes (e.g., openai, gemini, ollama) for different model sizes or providers. Use searchableAs() in your model to bind it to a specific index.
• Embedding reuse: To find similar items, reuse an existing embedding: $similar = Model::search($vector)->get();.
• Efficient filtering: Use whereSearchable() to pre-filter via regular Eloquent conditions before vector comparison, drastically reducing compute cost for large tables:

  Model::search('query')
      ->whereSearchable(fn($q) => $q->where('status', 'active'))
      ->get();
  

• Observability: Hook into the EmbeddingSaved event for logging, metrics, or external notification of embedding operations.
• Hybrid search: Combine Scout’s vector search with traditional where filters and orderBy on non-vector columns after the vector scan (e.g., post-filter by relevance score or date).

Gotchas and Tips

• Dimension mismatch: Ensure your dimensions in config/pgvector-scout.php exactly match the provider’s output (e.g., OpenAI text-embedding-3-small defaults to 1536; overriding to 256 requires explicit reduction via the provider API). Mismatched dimensions cause silent query errors or corrupted results.
• Handler state: Handlers are resolved per-index at runtime. If swapping providers, ensure all config keys (url, api_key, model) are updated and credentials are valid. Test with the fake index first.
• Soft deletes: The package supports Scout’s soft-deletes behavior out of the box—embeddings are removed on delete(), but you must use SoftDeletes on your model. Verify scout:sync-indexes isn’t skipping soft-deleted records.
• Query performance: For large datasets, always use whereSearchable() to narrow the candidate set. pgvector’s index scan (ANN) is efficient, but full scans on millions of rows still dominate latency.
• Version stability: As of v0.3.x, breaking changes are rare, but the package is still maturing—check changelogs for subtle API shifts (e.g., whereHasMorph refactor in v0.3.0).
• Testing tip: Use the fake index for unit tests to avoid real API calls—define a custom handler that returns predictable vectors in config/pgvector-scout.php during testing environment.
• Debugging: Enable Scout logging temporarily with Scout::filterUsing(fn ($builder) => $builder->tap(fn ($q) => dump($q->toSql()))); to inspect generated SQL—including <-> cosine distance comparisons.