Dokumentasi Deep-Dive: Indexing FTS dan Stemming
Dokumentasi ini membedah proses teknis pembuatan indeks Full-Text Search (FTS) secara menyeluruh saat sebuah kitab selesai diunduh maupun saat proses migrasi berlangsung.
Alur Arsitektur (Architecture Pipeline)
Berikut adalah diagram interaksi komponen yang merepresentasikan jalur integrasi dan indexing FTS:
flowchart TD
subgraph Ingestion ["Ingestion & Trigger"]
DLM["BookDownloadManager"] -->|"Download Selesai"| BAI["BookArchiveIntegrator"]
MIG["FtsMigrationManager"] -->|"Migrasi Versi < 2"| ADT["ArchiveDatabaseTools"]
end
BAI -->|"ensureBookIntegrated"| Phase{"IntegratePhase"}
Phase -->|".data"| Copy["Database Table Copy"]
Phase -->|".fts"| ADT
Copy -->|"copyTable"| DB_Archive[("archive_db<br/>(Tabel Kitab & TOC)")]
subgraph Pipeline ["Pipeline Indexing Unified FTS"]
ADT -.->|"1. Fetch Raw Text"| DB_Source[("source_db<br/>(Raw SQLite)")]
ADT -.->|"2. Preprocess"| Prep["stripSpanTags & newline replace"]
Prep -.->|"3. Normalisasi"| Stem["stemArabicLight10<br/>(Buang Harakat & Tasydid)"]
Stem -.->|"4. appendBookToUnifiedFTS"| DB_Fts[("fts_db<br/>(archive_fts & archive_index)")]
end
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 DLM,BAI,MIG,ADT,Copy,Prep,Stem store;
class DB_Archive,DB_Source,DB_Fts db;
class Phase vm;
Separation of Concerns (Prinsip Pemisahan Tanggung Jawab)
Desain arsitektur FTS Maktabah menerapkan pemisahan yang jelas antar-lapisan:
- Network & Cache Layer (
BookDownloadManager): Bertanggung jawab secara spesifik pada pengambilan data Zstd/SQLite dari jaringan dan dekompresi berkas. - Coordination Layer (
BookArchiveIntegrator,FtsMigrationManager): Mengatur waktu eksekusi integrasi dan indexing, sinkronisasi antar-Task/Thread, serta pelaporan progres. - Database & Core Engine (
ArchiveDatabaseTools): Menyediakan operasi primitif SQLite, kompresi blob, stemming teks Arab, dan pembuatan struktur tabel virtual FTS5.
Bedah Komponen Teknis
1. BookArchiveIntegrator (Class)
Komponen ini mengatur integrasi kitab individual yang baru selesai diunduh.
Struct & Class
actor BookArchiveSingleFlight {
static let shared = BookArchiveSingleFlight()
private var bookTasks: [Int: Task<Void, Error>] = [:]
private var archiveTail: [Int: Task<Void, Error>] = [:]
// (1)!
}
final class BookArchiveIntegrator: @unchecked Sendable {
static let shared = BookArchiveIntegrator()
private let pendingVacuumArchiveIds: Set<Int>
// (2)!
}
BookArchiveSingleFlightmemastikan deduplikasi (satu kitab tidak diindeks dua kali secara bersamaan) dan serialisasi per-arsip.- Menggunakan atribut
@unchecked Sendablekarena mutable state-nya dilindungi oleh struktur internal atau dijalankan pada antrean khusus.
Enum & Status
fts: Menandakan mesin sedang mem-parsing dan membuat indeks FTS.data: Menandakan mesin sedang menyalin tabel data utama.
enum BookArchiveIntegrateError: LocalizedError {
case invalidArchiveId(Int)
case sourceTableMissing(String)
case fileReplacementFailed(String)
}
- Menyimpan representasi error terstruktur dengan
LocalizedErrorsaat validasi sumber gagal atau pergantian berkas basis data bermasalah.
2. ArchiveDatabaseTools (Class)
Menangani operasi primitif SQLite, termasuk fase membaca baris teks, menjalankan stemming, dan menulisnya ke FTS5.
TableColumnInfo (Struct)
- Digunakan untuk introspeksi kolom dinamis, memastikan skema tabel
maindapat disalin secara akurat sebelum indexing.
Optimasi Khusus
-
String Interning & Binding Cepat:
static let sqliteTransient = unsafeBitCast( OpaquePointer(bitPattern: -1), to: sqlite3_destructor_type.self )Konstanta ini digunakan saat melakukan
sqlite3_bind_text. Dibandingkan membuat salinan string baru yang memakan memori RAM, sistem menggunakan pointerSQLITE_TRANSIENTagar lebih efisien. -
Penyisipan Cepat Skala Besar (
appendBookFast): Digunakan saat migrasi massal (FtsMigrationManager). Menerima pre-compiled prepared statements (insertIndexStmt,insertFtsStmt) yang dipakai berulang kali lintas kitab tanpa DDL check redundan ataupun delete scan, dieksekusi di bawah 1 transaksi tunggal. -
Penyisipan Terpadu (
appendBookToUnifiedFTS): Digunakan saat kitab baru selesai diunduh atau diimpor secara individual. Metode ini menginisialisasi skema Unified FTS bila belum ada, membersihkan entri kitab lama padaarchive_ftsdanarchive_indexberdasarkanbook_id, lalu menyisipkan baris halaman baru kearchive_indexdanarchive_ftsmenggunakan bitwise packed rowid(bookId << 32) | (rowId & 0xFFFFFFFF). -
Normalisasi Teks Arab Simetris: Teks dibersihkan menggunakan metode berantai
replacing("\n", with: " ").stripSpanTags(), lalu diproses oleh algoritmastemArabicLight10(). Algoritma ini menghapus harakat, tasydid, tatweel (ـ), serta menormalisasi alif/hamzah (أ/إ/آ/ٱ$\rightarrow$ا), ta' marbutah (ة$\rightarrow$ه), dan alif maqsurah (ى$\rightarrow$ي) agar simetris dengan kueri pengguna diFtsQueryParser.
3. FtsMigrationManager (Class)
Berperan ketika pengguna memutakhirkan aplikasi dan terdeteksi format FTS versi terdahulu (versi < 2).
MigrationPaths (Struct)
private struct MigrationPaths: Sendable {
let archiveOrig: String
let ftsOrig: String
let ftsWrite: String
}
- Menyimpan jalur awal arsip (dibuka secara langsung sebagai read-only) dan jalur target berkas FTS (
ftsWrite). TipeSendablememastikan data ini aman dikirim ke konkurensi diTaskGroup.
Optimasi Thread & SQLite
-
Concurrency Limits: Migrasi massal dibatasi lewat kalkulasi adaptif
maxConcurrent = min(4, max(2, ProcessInfo.processInfo.activeProcessorCount))agar tidak memicu peringatan keterbatasan memori (Memory Warning). -
Pragma Tuning & Zero-Copy Reading: Arsip sumber dibuka langsung dalam mode read-only dengan pemetaan memori (
PRAGMA main.mmap_size), sedangkan skemafts_dbyang di-attach dikonfigurasi secara spesifik:
4. BookDownloadManager (Class)
Mengelola perolehan data awal.
BundleBookIndexEntry (Struct)
struct BundleBookIndexEntry: Decodable {
let bkid: Int
let filename: String
let release: String
let sizeZst: Int64?
enum CodingKeys: String, CodingKey {
case bkid
case filename
case release
case sizeZst = "size_zst"
}
}
CodingKeysmemetakan nama key JSON eksternal (size_zst) ke format camelCase Swift (sizeZst).
Penanganan Khusus Platform (Platform Specific Handling)
Dalam hal manajemen latar belakang (background task), setiap sistem operasi ditangani secara spesifik:
Operasi latar belakang tidak membutuhkan pendaftaran eksplisit beginBackgroundTask karena macOS secara bawaan membiarkan proses Task berjalan hingga selesai atau aplikasi ditutup oleh pengguna.
Membutuhkan implementasi UIApplication.shared.beginBackgroundTask. Terdapat batasan waktu eksekusi latar belakang oleh iOS. Manajer juga mengatur isIdleTimerDisabled = true agar layar perangkat tidak masuk ke mode tidur (sleep) selama proses migrasi aktif.
Status Integrasi
Proses integrasi dan indexing dieksekusi secara otomatis usai integrasi arsip. Status dan cache kemudian disinkronkan melalui notifikasi UI.
Pencegahan Lonjakan Memori
Pertahankan blok pelindung autoreleasepool pada iterasi FTS agar memori tidak meningkat secara linear saat mengurai teks kitab berukuran besar.