Sanity Embeddings, Next.js projelerinize anlamsal arama (semantic search) eklemenin en kolay yollarından biridir. Dışarıdan karmaşık görünse de, bileşenleri anladığınızda oldukça basit olduğunu göreceksiniz. Bu yazı, Sanity'nin doğal Embeddings özelliğini ele alıyor; yani eski Embeddings Index API'sini değil. Eğer bir rehberde ayrı bir "embeddings-index" kaynağı oluşturmanız gerektiği yazıyorsa, o rehber güncel değildir. Sanity Embeddings, belge türlerinizi doğrudan veri kümenizde vektör indekslemesi için işaretlemenize olanak tanır. Embedding modeli ve vektör deposu Sanity tarafından yönetilir; ayrı bir servis yönetmenize gerek kalmaz. Sorgular, doğal dilde bir metin alıp anlamsal benzerliğe göre sıralanmış belgeler döndüren sanity.embeddings.query GROQ fonksiyonu ile yapılır. Bu özellik, 2026 ortası itibarıyla Growth ve Enterprise planlarında kullanılabilir.
Embeddings indeksini veri kümenizde ayarlamak için Manage → projeniz → Embeddings bölümüne gidin (veya Sanity Studio'daki Embeddings panelini kullanın). Bir indeks oluşturun, örneğin site_search adını verin ve hangi belge türlerinin ve alanlarının embed edileceğini seçin. Bir blog için genellikle post türünü ve title, excerpt, body alanlarını seçersiniz. Sanity, mevcut belgeleri otomatik olarak doldurur. Yeni ve güncellenen belgeler, dahili bir webhook aracılığıyla yayınlandığında yeniden embed edilir. Bu adım için kod yazmanıza gerek yoktur. Burada seçtiğiniz indeks adı (site_search), GROQ sorgusunda kullanacağınız isimdir.
Next.js route handler'ından embedding sorgulaması yapmak için bir API rotası oluşturun. Bu rota, arama terimini alır, Sanity'ye anlamsal sorgu gönderir ve JSON döndürür. Sunucu tarafında çalışan bir route handler kullanmak, Sanity read token'ınızı tarayıcıdan uzak tutar. Örnek kodda görüldüğü gibi, sanity.embeddings.query fonksiyonuna indeks adı, sorgu metni ve maksimum sonuç sayısı parametrelerini veriyorsunuz. Maksimum sonuç sayısını 4-8 gibi küçük tutmak, hız ve rate limit açısından önemlidir. useCdn: false olarak ayarlanmalıdır çünkü CDN kişiselleştirilmiş sorgu sonuçlarını sunmaz. Embeddings sorguları genel API yüzeyinde çalışmadığı için read token gereklidir.
Gelecekte Ne Bekleniyor?
Kullanıcı arayüzü tarafında ise bir 'use client' bileşeni oluşturuyoruz. Bu bileşen, kullanıcının yazdığı metni debounce ile route handler'a gönderir ve sonuçları görüntüler. Örnek SemanticSearch bileşeni, kullanıcı en az 3 karakter girdiğinde aramayı tetikler ve sonuçları liste halinde gösterir. Anlamsal arama, anahtar kelime tabanlı aramaya göre çok daha güçlüdür. Örneğin, kullanıcı "site hızı nasıl artırılır" yazdığında, anahtar kelime araması bunu "Core Web Vitals optimizasyonu" başlıklı bir makaleyle eşleştiremeyebilir. Ancak anlamsal arama, vektörler sayesinde anlamı yakaladığı için bu makaleyi getirecektir. Tek dezavantajı, GROQ embedding sorgusunun gecikmesinin biraz daha yüksek olmasıdır.
