Problem
Son iki yıldır Manticore Search ile çalışıyorum, iki finansal veri platformunun arama katmanını oluşturuyorum. Geçtiğimiz bir yıl boyunca bu çalışma Laravel API’si olarak devam etti.
Manticore asla bir sorun olmadı. Hızlı ve stabil. Sorun, Manticore ile Laravel arasında bir boşluk olmasıydı.
Bu boşluğu doldurmak için zaten bir paket oluşturmuştum — laravel-manticore-search, Manticore’un HTTP/JSON API’si üzerinde akıcı bir yapı oluşturuyor. Çalışıyor ve hala kullanılıyor. Ancak bu, bir istemci sarıcı. Her özellik manuel olarak uygulanmak zorundaydı. Her yeni filtre veya facet, istemci etrafında daha fazla özel mimari anlamına geliyordu ve Laravel’in sunduğu modeller, migrations, pagination, casts gibi ücretsiz olan hiçbir özellik uygulanamıyordu.
Scout bu boşluğu kapatmıyor. Scout, size search() fonksiyonunu veriyor. Tam bir sorgu oluşturucu, indeksler için migration yok, senkronizasyon sizin probleminiz. Bu bir eleştiri değil — Scout, tamamen farklı API’lere sahip motorlar üzerinde soyutlama yapar, bu nedenle en düşük ortak paydaları ortaya koyar. Ancak ihtiyacım olan bu değildi.
İhtiyacım olan şeyi basitçe tanımlamak mümkün: Tak çalıştır bir şey. Laravel tarzında bir şey. Eloquent’i Manticore’a yönlendirmek ve Eloquent’i kullanmak istiyordum.
Fikir
Manticore, MySQL kablosu protokolü ile iletişim kuruyor. Kutudan çıktığı gibi, 9306 portunda. Bununla birlikte, herhangi bir MySQL istemcisi ile bağlanabilir ve SQL çalıştırabilirsiniz.
Bu portu iki yıl boyunca düşündüğümde, bunun Laravel için ne anlama geldiğini hiç düşünmemiştim.
Çünkü gerçek soru asla “Manticore’un istemcisi üzerinde Eloquent’i nasıl yeniden uygularım?” olmadı. Gerçek soru “Manticore grameri ne kadar ince olabilir?” idi.
Eğer Manticore MySQL protokol bağlantılarını kabul ediyorsa ve esasen MySQL SQL’ini destekliyorsa, o zaman bir Laravel database driver — özel bir bağlantı ve Manticore’un lehçesindeki tuhaflıkları yöneten bir gramer, size tüm çatı alt yapısını kazandırır. Yeniden uygulama değil. Kalıtım.
Bu laravel-manticore-eloquent: Manticore’un birinci sınıf bir Laravel veritabanı bağlantısı olarak kaydedilmesini sağlıyor.
Görünümü
composer require renatomaldonado/laravel-manticore-eloquent
php artisan vendor:publish --provider="ManticoreEloquent\ManticoreEloquentServiceProvider" --tag=config
Bir Manticore’de tamamen yaşayan bir model ManticoreModel‘den türetilir. Sonrasında, sadece Eloquent ile devam eder:
use ManticoreEloquent\Eloquent\ManticoreModel;
class Article extends ManticoreModel
{
protected $table = 'articles_rt';
protected $guarded = [];
protected $casts = [=> , => ];
}
Article::where(, true)
->match() // MATCH() — Manticore full-text
->orderBy(, )
->paginate();
Article::find(10);
Article::create([=> , => , => true]);
Eğer modeliniz zaten bir ilişkisel veritabanında yaşıyor ve yalnızca Manticore üzerinden sorgulamak istiyorsanız, bunun için bir trait bulunmaktadır:
class Company extends Model
{
use HasManticore;
public function searchableAs(): string
{
return ;
}
}
Company::query()->where(, 1)->first(); // relational DB
Company::manticore()->match()->paginate();
Migrations, ancak bir arama motoru için
Önceden en çok özlem duyduğum kısım burasıydı. Manticore gerçek zamanlı indeksleri, standart Laravel migrations ile oluşturuluyor — şema grameri Laravel sütun türlerini Manticore türlerine haritalıyor ve sadece Manticore’a özel olanları ekliyor:
Schema::connection()->create(, function (Blueprint $table) {
$table->text(); // full-text indexed
$table->string();
$table->integer();
$table->boolean();
$table->timestamp();
$table->mva(); // multi-value attribute
$table->floatVector( dims: 384); // vector column for KNN
$table->minInfixLen(2); // infix search
$table->morphology();
});
Arama şemanız, diğer şemanızın yanında sürümlendirilir. php artisan migrate bunu oluşturur.
Eloquent ile vektör araması
Manticore, KNN’yi yerel olarak destekliyor ve sürücü sadece SQL derleyerek Eloquent ile doğrudan uyum sağlıyor:
Article::manticore()
->knn( $queryVector, k: 10)
->selectRaw()
->get();
Embedding araması, paginate(), castlar ve Eloquent’in sunduğu her şey ile entegre. Yığın içinde ayrı bir vektör veritabanına ihtiyaç yok.
Diğer Manticore’e özgü yardımcılar, lehçenin geri kalanını kapsar: option() sıralayıcı ayarı için, facet(), highlight(), tam belge yeniden yazımları için replace(), ve maxMatches() — bu, Manticore’un varsayılan 1,000 satır sınırını aşarken otomatik olarak yükseltilir, böylece derin pagination doğal olarak çalışır.
Üretim ortamında
Bu bir hafta sonu deneyimi değil. Sürücü, bakımını yaptığım API’da üretim aşamasında çalışıyor. İlk tüketici, bir uyumluluk tarama hizmeti; varlık ve kişi isimlerini Manticore indeksleri ile eşleştiriyor.
Gerçek kullanım şu şekilde gözüküyor:
EntityStakeholderPerson::match($match, )
->when(filled($country), fn ($q) => $q->where(, $country))
->limit(20)
->option(, )
->get();
Buradaki $match, sorguya göre oluşturulan bir mutlak ifade — "john doe smith"/2 — bu sayede hatırlama yüksek kalır. Kullanım senaryolarına göre farklı sıralayıcılar kullanılabilir (varlıklar için bm25, kişiler için proximity_bm25), tamamen aynı derleyici yoluyla.
Üretim ortamında iki farklı model tasarımının zaman kazandırabileceği örnekler:
Konvansiyonlar için bir temel model. İndekslerimiz, proje bazında ön ekli ve ortam bazında son ekli, bu yüzden temel bir model bunu bir defada yönetiyor:
class BaseManticoreModel extends ManticoreModel
{
public function __construct(array $attributes = [])
{
$prefix = config();
$suffix = app()->isProduction() ? : ;
$this->table = $prefix.$this->table.$suffix;
parent::__construct();
}
public function getAttributeValue()
{
= parent::getAttributeValue();
if (is_string() && ! mb_check_encoding(, )) {
return mb_convert_encoding(, , );
}
return ;
}
}
Her somut model o zaman iki satırdır. Asıl amaç, gerçek Eloquent modellerine sahip olmaktır; bir arama istemcisi değil: çatı kalıpları bunun üzerine uygulanabilir.
Temasları net bir şekilde eşleştirmeyen kısımlar
MySQL kostümü giymiş bir arama motoru hâlâ bir arama motorudur. Genel hatlar:
- Hiçbir işlem yok, satır kilitleri yok. Manticore bu kavramlara sahip değil.
lockForUpdate() işlemi etkisizdir. Bu bağlantıda DB::transaction() mantığına güvenmeyin. -
UPDATE ile REPLACE arasındaki fark. Manticore’un UPDATE yalnızca öznitelik (metin olmayan) sütunları yerinde değiştirir. Tam bir belgenin yeniden yazılması için REPLACE INTO gerekir, bu nedenle derleyici, update()‘in her zaman çalışıyormuş gibi yapmaması için açık bir replace() sağlar. -
id özeldir. Manticore, belge kimliklerini kendine ait olarak yönetir. Migrations, belirttiğiniz id sütununu atlar. - JOIN’ler sınırlıdır. Manticore’daki çapraz indeks JOIN’leri kısıtlıdır. İndekslerinizi denormalize edin. İlişkilerinizi yanıt veren veritabanınızdaki ilişkileri sabit tutarak, hala elverişlidir.
- Emüle edilmiş hazırlık ayarları. Manticore’un sunucu tarafı hazırlanan ifadeler desteği sınırlıdır, bu nedenle sürücü PDO’nun emüle edilmiş hazırlıklarını zorlar — bağlamalar,
MATCH(?) dahil, istemci tarafında iç içe geçilir.
Bunların hiçbiri, arama iş yükleri için sorun değil. Bunlar yaklaşımın bedeli ve belgelendiği için kimse üretim ortamında fark etmiyor.
Denemek
PHP 8.1+, Laravel 10/11/12, CI’da 95% test kapsamı zorunlu. Eğer dil bilgisi farklarını bilmek isterseniz, tasarım notları docs/ARCHITECTURE.md içinde bulunmaktadır.
Repo: https://github.com/Renato27/laravel-manticore-eloquent
Gerçek bir iş yükü üzerinde çalıştırırsanız, neyin kırıldığını duyup duymak isterim. Özellikle, derleyicinin kabul etmediği SQL’lere dönüşen kenar durumlarının ilgimi çekiyor. Hatalar ve PR’lar açık.
Kaynak: Orijinal Makale
