IAli
Tüm Yazılar
SQLite FTS5 ile Sıfır Bağımlılıklı Tam Metin Arama Mimarisi

SQLite FTS5 ile Sıfır Bağımlılıklı Tam Metin Arama Mimarisi

Harici arama motorlarına gerek duymadan SQLite FTS5 ve BM25 ile mikrosaniye düzeyinde gecikmeyle tam metin arama altyapısı nasıl kurulur?

Modern web projelerinde arama özelliği eklenmek istendiğinde akla ilk gelen çözüm Algolia, Elasticsearch, Typesense veya Meilisearch gibi harici servisler kurmaktır. Bu harici arama motorları devasa veri setlerinde başarılı olsa da küçük ve orta ölçekli sistemlerde ciddi mimari karmaşıklık yaratır. 1 vCPU ve 1 GB RAM kapasiteli mütevazı bir sanal sunucuda ayrı bir Java veya Rust arama süreci çalıştırmak yüzlerce megabayt belleği tüketir, sunucu maliyetini katlar ve yedekleme döngülerini zorlaştırır.

Oysa SQLite motorunun içinde yerleşik olarak gelen FTS5 (Full-Text Search 5) uzantısı, sıfır ağ gecikmesi ve sıfır ek bellek yüküyle profesyonel bir tam metin arama deneyimi sunar. Bu makalede harici hiçbir arka plan servisi kurmadan, doğrudan uygulamanın bellek alanında (in-process) BM25 algoritmasıyla sıralanan ve mikro saniyeler mertebesinde sonuç döndüren bir arama mimarisini en ince ayrıntısına kadar inceleyeceğiz.


1. FTS5 Nedir ve Nasıl Çalışır?

SQLite FTS5, ilişkisel veritabanı tablolarının üzerine inşa edilen sanal bir tablo (virtual table) modülüdür. Standart bir SQL sorgusunda kullanılan LIKE '%kelime%' ifadesi, ilgili sütundaki tüm satırları baştan sona tarayan tam tablo taraması (full table scan) yapar. Tablonuzda binlerce satır ve uzun teknik makaleler olduğunda LIKE sorguları disk G/Ç kuyruğunu kilitler ve sorgu süreleri saniyeleri bulur.

FTS5 ise arama yapılacak metinleri ters indeks (inverted index) yapısına dönüştürür.

TEXT
[Kelime Havuzu]           [Belge Konumları ve Frekanslar]
"linux"          --->     Doc#1 (Pozisyon: 12), Doc#4 (Pozisyon: 85)
"çekirdek"       --->     Doc#1 (Pozisyon: 13), Doc#2 (Pozisyon: 4)
"performans"     --->     Doc#2 (Pozisyon: 10), Doc#5 (Pozisyon: 22)

Ters indeks yapısı sayesinde kullanıcı bir terim arattığında veritabanı tablonun tamamını okumaz. Doğrudan terimin bulunduğu B-Tree yaprağına erişir ve ilgili belge kimliklerini mikro saniyeler içinde çeker.

FTS3/FTS4 ile FTS5 Arasındaki Farklar

SQLite uzun yıllardır FTS modüllerine sahiptir, ancak FTS5 sürümü mimari açıdan köklü yenilikler getirmiştir:

  1. Dahili BM25 Desteği: FTS3 ve FTS4 sürümlerinde alaka düzeyi (relevance) sıralaması için özel C fonksiyonları yazmak gerekiyordu. FTS5, endüstri standardı Okapi BM25 sıralama algoritmasını yerleşik bir fonksiyon olarak sunar.
  2. Kayıpsız Sıkıştırma ve Küçük Boyut: İndeks verileri disk üzerinde LZ4 benzeri hızlı sıkıştırma algoritmalarıyla saklanır, bu da indeks boyutunu geleneksel tablolara göre yarı yarıya düşürür.
  3. Gelişmiş Tokenizer Seçenekleri: Unicode karakter setleri, aksan temizleme ve Türkçe gibi dillere özgü harf dönüşümleri yerleşik olarak desteklenir.
  4. Harici İçerik (External Content) Desteği: FTS5 tablosu metnin kopyasını kendi içinde tutmak zorunda değildir. Asıl tablodaki verilere referans vererek disk israfını önleyebilir.

2. Sanal Tablo Tasarımı ve Tokenizer Yapılandırması

Türkçe içerik barındıran bir platformda en sık karşılaşılan problem harf duyarlılığı ve yumuşatma karakterleridir. Kullanıcı "bellek" yazdığında "Bellek", "çöp" yazdığında "cop" kelimelerinin de eşleşmesi beklenir.

FTS5 tablosunu oluştururken unicode61 tokenizer motorunu ve remove_diacritics 2 parametresini kullanırız:

SQL
CREATE VIRTUAL TABLE IF NOT EXISTS posts_fts USING fts5(
  id UNINDEXED,
  title,
  description,
  body_markdown,
  tokenize = 'unicode61 remove_diacritics 2'
);

Parametrelerin Mimari Anlamı

  • id UNINDEXED: Yazının benzersiz kimlik değeridir. UNINDEXED belirteci, bu sütunun metin araması için indekslenmeyeceğini belirtir. Böylece gereksiz kelime ayrıştırması engellenir ve disk alanı korunur.
  • title, description, body_markdown: Arama motorunun tarayacağı metin sütunlarıdır.
  • tokenize = 'unicode61 remove_diacritics 2': Unicode 6.1 standardına göre metni kelimelere böler. remove_diacritics 2 ayarı ise tüm Latin ve Türk alfabesindeki aksanlı harfleri normalize eder. Bu sayede arama kutusuna yazılan sorgu ile makaledeki metin kusursuz eşleşir.

3. Otomatik Senkronizasyon ve Tetikleyici (Trigger) Mimarisi

İçerik yönetim sistemlerinde asıl tabloya yeni bir yazı eklendiğinde, var olan yazı güncellendiğinde veya silindiğinde FTS5 tablosunun anında senkronize olması gerekir. Bu işlemi uygulama seviyesinde kod yazarak yapmak yerine SQLite tetikleyicilerine (triggers) devretmek veri tutarlılığını garanti altına alır.

İşte sıfır veri kaybı sağlayan üretim seviyesi tetikleyici tanımları:

SQL
-- 1. Yeni Yazı Eklendiğinde FTS5 Tablosunu Güncelle
CREATE TRIGGER IF NOT EXISTS posts_ai AFTER INSERT ON posts BEGIN
  INSERT INTO posts_fts(id, title, description, body_markdown)
  VALUES (new.id, new.title, new.description, new.body_markdown);
END;

-- 2. Yazı Silindiğinde FTS5 Kaydını Temizle
CREATE TRIGGER IF NOT EXISTS posts_ad AFTER DELETE ON posts BEGIN
  DELETE FROM posts_fts WHERE id = old.id;
END;

-- 3. Yalnızca İçerik Değiştiğinde FTS5 Tablosunu Güncelle
DROP TRIGGER IF EXISTS posts_au;
CREATE TRIGGER posts_au AFTER UPDATE OF title, description, body_markdown ON posts BEGIN
  DELETE FROM posts_fts WHERE id = old.id;
  INSERT INTO posts_fts(id, title, description, body_markdown)
  VALUES (new.id, new.title, new.description, new.body_markdown);
END;

Kritik Mimari Detay: UPDATE OF Filtresi

Üçüncü tetikleyicide yer alan AFTER UPDATE OF title, description, body_markdown ifadesi hayati önem taşır. Eğer düz bir AFTER UPDATE ON posts tetikleyicisi tanımlarsanız, her sayfa ziyaretinde view_count veya reaksiyon sayısı arttığında SQLite devasa makale metnini FTS5 tablosundan silip tekrar indekslemeye çalışır.

Bu durum yüksek trafikte veritabanında kilitlenmelere (locking), WAL dosyasının kontrolsüz büyümesine ve disk G/Ç patlamalarına yol açar. Yalnızca başlık, özet ve gövde metni güncellendiğinde FTS5 tablosunu tetikleyerek işlemci yükünü sıfıra indirmiş oluruz.


4. BM25 Alaka Düzeyi Sıralaması ve Kolon Ağırlıklandırma

Bir kullanıcı arama yaptığında başlıkta geçen bir kelime, makalenin 3000 kelimelik gövdesinde tesadüfen geçen bir kelimeden çok daha önemlidir.

SQLite FTS5, arama sonuçlarını sıralamak için yerleşik bm25() fonksiyonunu sunar. BM25 algoritması, terim sıklığı (TF) ve ters belge sıklığı (IDF) ilkelerine dayanarak her sonuca matematiksel bir alaka puanı atar.

SQL
SELECT 
  p.id, 
  p.slug, 
  p.title, 
  p.description,
  snippet(posts_fts, -1, '[[', ']]', '...', 16) AS snippet,
  bm25(posts_fts, 5.0, 3.0, 1.0) AS rank
FROM posts_fts
JOIN posts p ON p.id = posts_fts.id
WHERE posts_fts MATCH ?
  AND (p.status = 'published' OR p.status = 'scheduled')
  AND p.publish_at <= datetime('now')
ORDER BY rank ASC
LIMIT 10;

Kolon Ağırlık Katsayıları

bm25(posts_fts, 5.0, 3.0, 1.0) fonksiyonuna verilen argümanlar tablodaki sütunların önem katsayılarıdır:

  • 5.0 (title): Başlıkta bulunan eşleşmelere 5 kat ağırlık verilir.
  • 3.0 (description): Makale özetinde geçen terimler 3 kat puan alır.
  • 1.0 (body_markdown): Gövde metnindeki eşleşmeler temel katsayı ile hesaplanır.

SQLite BM25 fonksiyonunda negatif değerler daha yüksek alakayı temsil eder, bu nedenle sıralama her zaman ORDER BY rank ASC şeklinde küçükten büyüğe doğru yapılır.


5. Anlık Alıntı ve Vurgulama: snippet() Fonksiyonu

Kullanıcıların aradıkları sonucun neden listelendiğini anlamaları için arama motorlarının eşleşen kelimenin etrafındaki cümleyi göstermesi gerekir. FTS5 bu işlemi snippet() fonksiyonu ile donanım hızında gerçekleştirir:

SQL
snippet(posts_fts, 2, '<mark>', '</mark>', '...', 16)
  • Argüman 1 (posts_fts): FTS tablosu referansı.
  • Argüman 2 (2 veya -1): Alıntının hangi sütundan çekileceği. -1 verildiğinde en yüksek alaka puanına sahip sütun otomatik seçilir.
  • Argüman 3 ve 4 ('', ''): Eşleşen kelimelerin başına ve sonuna eklenecek vurgu etiketleri.
  • Argüman 5 ('...'): Metnin kırpıldığı yerlere konulacak elips işareti.
  • Argüman 6 (16): Alıntıda yer alacak maksimum kelime sayısı.

Bu fonksiyon sayesinde harici metin ayrıştırma kütüphanelerine gerek kalmadan kullanıcıya doğrudan Google tarzı bağlamsal arama sonuçları sunulur.


6. Güvenlik: FTS5 Sorgularını Temizleme (Sanitization)

FTS5 sorgu dili çift tırnak, yıldız (*), AND, OR, NOT ve parantez gibi özel mantıksal operatörleri destekler. Kullanıcı arama kutusuna tek bir tırnak işareti veya dengesiz bir parantez yazdığında SQLite sözdizimi hatası (syntax error) vererek işlemi durdurur.

Bu hatayı engellemek ve kötü niyetli sorgu manipülasyonlarının önüne geçmek için kullanıcı girdisi veritabanına iletilmeden önce katı bir temizleme filtresinden geçirilmelidir:

TypeScript
export function sanitizeFts5Query(rawQuery: string): string {
  if (!rawQuery || typeof rawQuery !== "string") return "";

  // Kontrol karakterlerini ve tehlikeli operatörleri ayıkla
  const cleaned = rawQuery
    .replace(/[^\p{L}\p{N}\s]/gu, " ")
    .trim()
    .replace(/\s+/g, " ");

  const terms = cleaned.split(" ").filter((t) => t.length >= 2);
  if (terms.length === 0) return "";

  // Her terime önek arama karakteri (*) ekleyerek anlık tamamlama sağla
  return terms
    .slice(0, 5)
    .map((t) => `"${t}"*`)
    .join(" AND ");
}

Bu fonksiyon kullanıcının yazdığı her terimi tırnak içine alarak operatör çakışmalarını önler ve sonuna yıldız ekleyerek kelimenin kökünden eşleşmesini sağlar.


7. Bellek ve Performans Karşılaştırması

1 GB RAM ve 1 vCPU kapasiteli sunucularda çalışan sistemler için bellek optimizasyonu hayati önemdedir. Aşağıdaki tablo farklı arama mimarilerinin kaynak tüketimlerini özetlemektedir:

Çözüm RAM Tüketimi Ek Süreç / Daemon Tipik Yanıt Süresi Bakım ve Yedekleme
Elasticsearch 512 MB – 1.5 GB Java JVM Süreci 15 – 35 ms Ayrı indeks snapshot yönetimi
Meilisearch 180 MB – 400 MB Bağımsız Rust Süreci 5 – 12 ms Ek veri dizini ve port yönetimi
Algolia 0 MB (Bulut) Yok (Harici API) 80 – 200 ms (Ağ) Aylık fatura ve veri gizliliği
SQLite FTS5 0 MB (Yerleşik) Yok (In-Process) 0.2 – 1.5 ms Tek bir blog.db dosyasında

SQLite FTS5, uygulamanın kendi bellek alanı içinde çalıştığı için herhangi bir TCP soket bağlantısı veya HTTP istek ek yükü oluşturmaz. Arama sorgusu doğrudan disk ve işletim sistemi sayfa önbelleği üzerinden mikro saniyeler içinde tamamlanır.


8. Mimari Sonuç ve Öneriler

Büyük hacimli ve dağıtık veri tabanlarında özel arama kümeleri kaçınılmazdır. Ancak blog platformları, dokümantasyon portalları, kurumsal bilgi tabanları ve yüz binlerce kayıt barındıran teknik içerik sistemlerinde SQLite FTS5 tartışmasız en yalın ve verimli çözümdür.

Tek bir dosya üzerinde sıfır ağ gecikmesiyle çalışan, BM25 ile alaka düzeyini hesaplayan ve Unicode karakterleri sorunsuzca ayrıştıran bu mimari, sunucu kaynaklarını korurken kullanıcıya kusursuz bir arama hızı sunar.

Sistemin 1 GB RAM kapasiteli bir VPS üzerindeki genel çalışma dinamikleri için 1 GB VPS'te Next.js, SQLite ve Caddy Blog Mimarisi rehberimizi, B-Tree ve disk bloklarının derinlemesine analizi içinse LSM-Tree ve B-Tree: Veritabanı Depolama Motorlarının Analizi makalemizi inceleyebilirsiniz.

Yazıyı Değerlendir

0 tepki

Fikirlerinizi tek tıkla paylaşarak geri bildirim bırakın.

Bu teknik notu çevrenizle paylaşın

Ali Purtaş

@alipurtas • Hey, This is Ali!

İletişime Geç

Kendi halinde yazılım geliştiren bir öğrenci. Sistemler kuruyor, deniyor, bozuyor ve öğrendiği gerçek çözümleri burada belgeliyor.

Konu Kümesi & Önerilen Yazılar

İç Bağlantılı Mimari
Yorumlar yükleniyor...