Inti Mesin Pencari (Search Engine Core)
Dokumentasi ini membedah secara teknis arsitektur, desain konkurensi, dan komponen-komponen utama yang membangun fitur pencarian berkecepatan tinggi (Full-Text Search / FTS) di Maktabah.
Alur Arsitektur (Architecture Pipeline)
Diagram Interaksi Komponen
Diagram berikut menggambarkan interaksi antarkomponen di dalam modul SearchEngine, mulai dari penerimaan kueri hingga pengiriman hasil ke antarmuka pengguna:
flowchart TD
UI["UI / Callers (OptionSearchVC / SearchModeView)"] -->|"startSearch / cancel"| SE["SearchEngine (Facade)"]
SE -->|"buildFtsQuery"| FQP["FtsQueryParser"]
SE -->|"pause / resume"| PC["PauseController"]
SE -->|"spawn"| SW["SearchWorker (Per Archive)"]
SW -->|"waitIfPaused"| PC
SW -->|"supportsUnifiedFts?"| Mode{Skema FTS}
subgraph Unified ["Unified FTS5 Pipeline (Modern)"]
Mode -->|"Ya"| UQ["Multi-Tier Unified Query"]
UQ -->|"f.rowid BETWEEN min AND max"| UDB[("archive_fts JOIN archive_index")]
end
subgraph Legacy ["Per-Kitab Pipeline (Fallback)"]
Mode -->|"Tidak"| POOL["SQLiteConnectionPool"]
POOL -->|"executeParallelChunks"| SC["SQLiteConnection"]
SC -->|"b{id}_fts MATCH"| LDB[("b{id}_fts Tables")]
end
UDB -->|"emit packedRowId"| SRB["SearchResultBuffer (Adaptive Throttling)"]
LDB -->|"emit SearchResultItem"| SRB
SRB -->|"onResult (Batched)"| UI
UI -.->|"Lazy Render & Snippet"| SHR["SearchHitResolver (1000 LRU Cache)"]
classDef ui fill:#e040fb26,stroke:#c026d3,stroke-width:2px;
classDef vm fill:#3b82f626,stroke:#2563eb,stroke-width:2px;
classDef store fill:#22c55e26,stroke:#16a34a,stroke-width:2px;
classDef db fill:#f9731626,stroke:#ea580c,stroke-width:2px;
classDef event fill:#be185d26,stroke:#9d174d,stroke-width:2px,color:#9d174d;
class UI ui;
class SE,FQP,PC,SW,POOL,SC,SRB,SHR store;
class Mode vm;
class UDB,LDB db;
Konkurensi Pekerja (Worker Concurrency)
Pencarian dirancang agar berjalan secara paralel di tingkat berkas arsip basis data (1.sqlite s.d. 20.sqlite). Setiap SearchWorker mengelola pencarian untuk satu arsip secara terisolasi:
SearchEngine.startSearchmemicu proses pencarian di latar belakang menggunakanTask.detached.- Setiap
SearchWorkermelakukan verifikasi skema melaluisupportsUnifiedFts(pool)untuk mendeteksi apakah tabelarchive_ftsdanarchive_indextersedia. - Jalur Unified FTS (Modern):
- Jika
allowedTablesditentukan dan tidak ada satupun tabel yang beririsan dengan arsip ini, worker langsung keluar (short-circuit) tanpa menyentuh disk. - Kueri dieksekusi secara terpadu melalui multi-tier query strategy yang memanfaatkan bitwise binary range seek pada posting list FTS5.
- Hasil pencarian dikirimkan langsung ke
SearchResultBuffertanpa pemuatan teks berat di awal. - Jalur Per-Kitab (Legacy Fallback):
- Jika arsip belum dimigrasikan ke Unified FTS, worker mengumpulkan ID baris per tabel kitab (
b{id}_fts) lalu memecahnya ke dalam chunk paralel (executeParallelChunks) melaluiSQLiteConnectionPool. - Hasil dari seluruh worker disangga dan distabilkan alirannya oleh
SearchResultBuffersebelum dipancarkan ke antarmuka pengguna, menjamin UI tetap responsif pada 60/120 fps.
Metode Pause, Resume, dan Stop
Pengontrolan siklus hidup pencarian (Jeda, Lanjutkan, Hentikan) dikoordinasikan secara terpusat oleh PauseController, sebuah actor yang mengelola status isPaused dan daftar CheckedContinuation.
stateDiagram-v2
[*] --> Idle
Idle --> Running: startSearch()
Running --> Paused: pause() [CheckedContinuation]
Paused --> Running: resume() [cont.resume()]
Running --> Finished: All Chunks Completed
Running --> Stopped: stop() / Task.cancel()
Paused --> Stopped: stopAndResumeAll()
Finished --> [*]
Stopped --> [*]
- Pause (
pause()): MenandaiisPaused = true. Setiap kali memproses iterasi chunk, worker memanggilawait pauseController.waitIfPaused(). Jika pencarian dijeda, eksekusi tertahan karenaCheckedContinuationdimasukkan ke dalam antrean tanpa dilanjutkan (resume). - Resume (
resume()): MengubahisPaused = falselalu memanggilcont.resume()pada seluruh continuation yang tertahan, melepaskan penundaan eksekusi worker seketika. - Stop (
stopAndResumeAll()): Karena sebuah task tidak dapat merespons pembatalan (cancellation) saat berstatus suspended oleh continuation, pemanggilanstopwajib melanjutkan (resume) seluruh task yang tertahan sembari membatalkanTaskutama.
Prinsip Pemisahan Tanggung Jawab (Separation of Concerns)
Komponen pada mesin pencari dirancang dengan batas tanggung jawab yang jelas:
SearchEngine: Fasilitator utama (Facade). Mengatur siklus hidup tugas utama, mengelola daftar worker, dan meneruskan instruksi kontrol kePauseController.SearchWorker: Berfokus murni pada logika orkestrasi paralel (chunking) untuk satu berkas arsip / kelompok tabel.SQLiteConnection&SQLiteConnectionPool: Abstraksi koneksi thread-safe kelibsqlite3serta isolasi eksekusi prepared statements.FtsQueryParser: Utilitas stateless yang bertugas melakukan sanitasi, normalisasi akar kata (stemming) teks Arab, dan konversi format kueri FTS.PauseController: Mengelola logika penundaan asinkron melaluiCheckedContinuationdi lingkungan Swift Concurrency.
Bedah Komponen Teknis
Struct dan Class
SearchEngine (Actor)
Actor pengatur siklus hidup pencarian utama. Bertugas menerima permintaan, menyusun kueri FTS, mendelegasikan tugas ke worker, serta meneruskan callback hasil ke antarmuka pengguna.
actor SearchEngine {
private(set) var workers: [SearchWorker] = [] // (1)!
private let pauseController = PauseController()
private var searchTask: Task<Void, Never>?
private var isStopped = false
// ...
}
- Kumpulan worker yang dipetakan per ID arsip basis data.
Task Cancellation
SearchEngine mengelola siklus hidup task utamanya dalam properti searchTask, yang dapat dibatalkan melalui .cancel() saat operasi diinterupsi oleh pengguna.
SearchWorker (Class)
Class worker yang bertugas menjalankan kueri FTS pada satu berkas arsip basis data. Mengadopsi protocol Sendable penuh dengan perlindungan state internal menggunakan Synchronization.Mutex.
final class SearchWorker: Sendable {
let archiveId: String
let tables: [String]
let pool: SQLiteConnectionPool
let batchSize: Int
let queryLimit: String = "\nLIMIT 10000;"
private let schemaCache = Mutex<String??>(nil)
}
archiveId: Pengenal arsip basis data (misalnya"1").tables: Daftar nama tabel kitab yang berada di dalam arsip ini.pool: Connection Pool untuk eksekusi kueri konkuren.batchSize: Batas batch pengambilan konten baris kitab (nilai bawaan: 200).schemaCache: Cache skema FTS berbasisMutex<String??>. Worker memverifikasi apakah arsip menggunakan skema"fts_db"atau"main"sekali saja dan menyimpannya di memori, mengeliminasi kueri berulang kesqlite_masterpada setiap eksekusi pencarian.
Strategi Kueri Multi-Tier (Unified FTS)
Pada arsip yang mendukung Unified FTS (supportsUnifiedFts), SearchWorker mengelompokkan kueri ke dalam strategi berlapis (multi-tier) untuk memotong overhead I/O dan memaksimalkan antarmuka xFilter pada SQLite FTS5:
- Short-Circuit Evaluasi: Jika parameter
allowedTablesdiberikan namun tidak memuat satupun tabel dari arsip ini, worker langsung keluar tanpa menyentuh disk. - Tier 1 (Single Book Seek): Ketika pencarian ditargetkan hanya pada 1 buku, kueri FTS menggunakan batasan langsung
f.rowid BETWEEN minRowId AND maxRowIdpada bitwise packed rowid: SQLite FTS5 langsung melompat (binary seek) ke rentang rowid buku tersebut dan berhenti segera setelah mencapai batas akhir. - Tier 2 (2–5 Books Seek): Menggabungkan pencarian 2 s.d. 5 buku menggunakan
UNION ALLdi mana setiap buku memiliki klausaBETWEEN ? AND ?tersendiri. Ini membypass keterbatasan mesin FTS5 yang hanya mendukung satu batas rentangxFilterper query term. - Tier 3 (>5 Books / Bounding Box): Jika rentang ID buku berdekatan (
(maxBook - minBook) < 350), kueri menerapkan bounding-box rangeBETWEEN minGlobal AND maxGlobalditambah filterAND i.book_id IN (...). - Global Archive Query: Jika
allowedTables == nil(pencarian di seluruh perpustakaan), satu kueri FTS global dijalankan langsung melintasi tabelarchive_ftsdanarchive_index.
SQLiteConnection (Class)
Membungkus interaksi tingkat rendah C API dari libsqlite3. Class ini menyimpan opaque pointer koneksi basis data dan mengimplementasikan mekanisme statement cache.
final class SQLiteConnection: DBConnectionType, @unchecked Sendable {
private let db: OpaquePointer?
private var statementCache: [String: OpaquePointer] = [:]
private var cacheKeys: [String] = []
private let maxCacheSize = 50
private let executionLock = NSLock()
}
db: Pointer koneksi SQLite (bertipeOpaquePointer).statementCache: Cache untuk menyimpan prepared statements agar kueri yang dieksekusi berulang kali tidak perlu diuraikan ulang.cacheKeys&maxCacheSize: Mekanisme pengosongan cache (cache eviction) berbasis algoritma LRU (Least Recently Used).executionLock: Mutex (NSLock) untuk mencegah data race atauEXC_BAD_ACCESSsaat pemanggilan konkuren pada instance koneksi.
SQLiteConnectionPool (Actor)
Menyediakan kumpulan koneksi SQLite yang terisolasi untuk mendukung operasi chunking paralel pada worker.
connections: Kumpulan koneksi basis data (DBConnectionType). Saat worker memanggil fungsiread(at:), pool memilih koneksi menggunakan operasi modulo indeks (index % connections.count), menjamin rotasi penggunaan koneksi secara merata.
PauseController (Actor)
Mengelola status jeda (pause) dan lanjut (resume) secara thread-safe.
actor PauseController {
private var isPaused = false
private var continuations: [CheckedContinuation<Void, Never>] = []
// ...
}
isPaused: Penanda status apakah proses pencarian sedang dijeda.continuations: Array dariCheckedContinuationyang menahan eksekusi Task selama status jeda aktif.
SearchQueryOptions (Struct)
Membawa parameter kueri dari lapisan UI / ViewModel menuju SearchEngine.
struct SearchQueryOptions: Sendable {
var query: String = ""
var keywords: [String] = []
var allowedTables: Set<String>? = nil
var mode: SearchMode
var nearDistance: Int = 10
}
query: Teks kueri pencarian dari pengguna.keywords: Kata kunci alternatif apabila kueri utama kosong.allowedTables: Himpunan tabel yang difilter (jika bernilainil, pencarian mencakup seluruh tabel).mode: Tipe operasiSearchMode(phrase,contains,or,near).nearDistance: Batas toleransi jarak antarkata untuk operatorNEAR()(nilai bawaan: 10).
SafeCounter (Class)
Penghitung (counter) thread-safe menggunakan Synchronization.Mutex. Digunakan saat menghitung progres penyelesaian tabel lintas tugas konkuren.
final class SafeCounter: Sendable {
private let state = Mutex<Int>(0)
func increment() -> Int {
state.withLock { count in
count += 1
return count
}
}
}
SerialTaskQueue (Class)
Antrean asinkron untuk memastikan tugas-tugas dieksekusi secara sekuensial (satu per satu). Membantu menertibkan urutan mutasi state atau proses penulisan ke antarmuka dan disk.
final class SerialTaskQueue: Sendable {
private let tailState = Mutex<Task<Void, Never>?>(nil)
// ...
}
TOCLoaderRefCount (Actor)
Pengelola siklus hidup pemuatan daftar isi (Table of Contents / TOC). Dilengkapi mekanisme penyimpanan sementara (cache), eliminasi permintaan ganda (request deduplication), serta penghitungan referensi (reference counting).
actor TOCLoaderRefCount {
struct Entry {
var task: Task<[TOCNode], Error>
var consumers: Int
}
private var inFlight: [Int: Entry] = [:]
private let connFactory: @Sendable () -> BookConnection
private let treeCache = BookConnection.tocTreeCache
}
Entry: Menyimpan statusTaskaktif dan jumlah pemanggil (consumers).inFlight: Memastikan buku yang sama tidak memicu ekstraksi struktur TOC ganda secara bersamaan.
Enums & Event Types
SearchMode (Enum)
Menentukan operator logika pencarian yang diterapkan oleh FtsQueryParser:
phrase: Teks pencarian dibungkus tanda kutip ganda (contoh:"kata satu dua"), mencocokkan frasa secara persis.contains: Kata kunci digabungkan dengan operatorAND(contoh:"kata" AND "satu").or: Kata kunci digabungkan dengan operatorOR(contoh:"kata" OR "satu").near: Pencarian kedekatan antarkata menggunakanNEAR(kata satu dua, 10).
SQLValue (Enum)
Abstraksi tipe data aman untuk pengikatan parameter (parameter binding) pada SQLite:
Tipe Callback
Berbagai struktur callback digunakan sebagai antarmuka komunikasi:
SearchEngineCallbacks: Callback tingkat atas (onInitialize,onTableComplete,onResult).SearchWorkerCallbacks: Callback antara Engine dan Worker.SearchCallbacks: Digunakan untuk memantau progres pembacaan baris di tingkat internal tabel atau chunk.
Eksekusi Callback pada UI
Pastikan pembaruan antarmuka pengguna pada pemanggil (caller) diarahkan ke @MainActor karena fungsi callback dipancarkan dari background queue (Task.detached).
FtsQueryParser: Logika Kueri Lanjutan
FtsQueryParser memiliki logika khusus untuk mendeteksi perintah kueri manual pengguna yang memanfaatkan sintaks NEAR:
Jika pengguna menulis kueri secara eksplisit seperti kata NEAR/5 lain, parser langsung menerapkan operator tersebut dengan jarak spesifik 5.
Kueri teks disanitasi secara berantai:
text.trimmingCharacters(in: .whitespacesAndNewlines).normalizeArabic().stemArabicLight10()
Langkah ini membersihkan harakat, melakukan stemming awal pada kata Arab (seperti awalan "al-"), dan menghapus tanda baca agar selaras dengan konfigurasi tokenizer SQLite.