Struktur Data Kitab
Dokumen ini menjelaskan arsitektur basis data serta pemetaan model (model mapping) untuk modul kitab pada aplikasi Maktabah.
Lihat dokumen Optimasi Penyimpanan untuk rincian kompresi ZSTD dan desain FTS hemat ruang.
Ruang Lingkup
- Basis data utama pada
Source/Core/Database/ - Pemetaan model data pada
Source/Features/ - Transformasi teks:
shorts, pemetaantabaqa, kurung ayat{}, dan ZSTD - Alur pembaruan buku dan pembangunan ulang (rebuild) indeks FTS
Peta Basis Data
DatabaseManager membuka dua berkas basis data inti:
Files/main.sqlite(DatabaseManager.db)Files/special.sqlite(DatabaseManager.dbSpecial)
Selain itu, aplikasi menggunakan berkas basis data arsip per nomor:
N.sqlite(misalnya1.sqlite,2.sqlite) berisi konten kitab (b{bkid}) dan daftar isi / TOC (t{bkid}).N_fts.sqliteberisi indeks FTS5 terpadu (archive_ftsdanarchive_index) atau skema warisan per-kitab (b{bkid}_fts).
Basis data pengguna:
SearchResults.sqlite(hasil pencarian tersimpan / bookmarks)Annotations.sqlite(sorotan teks, garis bawah, dan catatan)
Skema Utama
1) main.sqlite
Tabel 0bok
Kolom yang digunakan aplikasi (lihat DatabaseManager):
bkid$\rightarrow$ ID bukucat$\rightarrow$ ID kategoribk$\rightarrow$ Judul bukuArchive$\rightarrow$ ID berkas arsip (N.sqlite)betaka$\rightarrow$ Metadata / bithoqoh kitabauthno$\rightarrow$ Relasi penulis ke tabelAuthinf$\rightarrow$ Informasi bukuTafseerNam$\rightarrow$ Nama tafsir (opsional)bVer/bver$\rightarrow$ Versi buku (digunakan oleh update manager)
Tabel 0cat
id$\rightarrow$ ID kategoriname$\rightarrow$ Nama kategoriLvl$\rightarrow$ Tingkat (level) kategori dalam hierarkicatord$\rightarrow$ Urutan tampilan kategori
2) special.sqlite
Tabel Auth
Digunakan untuk data penulis / pengarang:
authid,auth,inf,Lng,oVer(dan kolom lain sepertiHigriDsaat pembaruan data penulis).
Tabel shorts
Digunakan untuk ekspansi singkatan teks kitab:
Bk$\rightarrow$ ID bukuRamz$\rightarrow$ Token singkatanNass$\rightarrow$ Teks pengganti
Tabel rowa
Digunakan oleh modul biografi perawi hadis (Narrator):
id,name,AQUAL,ROTBA,R_ZAHBI,sheok,telmez,IsoName,TABAQA,WHO,birth,death
Tabel tarjamah
men_bdanmen_b_ftsmen_udanmen_u_fts
Tabel Quran
Qr(teks ayat)Sora(nama surah)
3) N.sqlite (Arsip Kitab)
Struktur tabel per buku:
b{bkid}: Konten utama (id,nass,page,part, serta opsionalsora,aya).t{bkid}: Daftar isi / TOC (id,tit,lvl,sub).
Catatan:
- Pada format terbaru, kolom
nassdisimpan sebagaiBLOBterkompresi ZSTD. - Data versi lama mungkin masih bertipe
TEXT; alur pembacaan telah menyediakan mekanisme fallback.
4) N_fts.sqlite
Mendukung dua format skema:
A. Format Modern: Unified FTS5 (Standar)
Seluruh buku di dalam satu berkas arsip disatukan ke dalam satu pasang tabel indeks terpadu:
archive_fts: Tabel virtual FTS5 tanpa duplikasi konten teks:archive_index: Tabel pemetaan metadata fisik kerowidbitwise:archive_metadata: Tabel pelacak versi skema (fts_version = 2).- Bitwise Packed RowID: $$\text{packedRowId} = (\text{bookId} \ll 32) \mid (\text{rowId} \ \& \ \text{0xFFFFFFFF})$$ Memungkinkan pencarian rentang kitab tunggal maupun multi-kitab memanfaatkan binary seek & early pruning SQLite FTS5 tanpa pemborosan ukuran berkas indeks.
B. Format Warisan: Per-Kitab FTS5 (Legacy Fallback)
Digunakan pada arsip versi lama yang belum dimigrasikan:
- Tabel virtual terpisah untuk setiap buku:
b{bkid}_ftsdengan kolomnass_clean(fts5,tokenize='unicode61'). rowidditetapkan sama denganidbaris asli pada tabelb{bkid}.
Pemetaan Basis Data ke Model
Perpustakaan (Library)
0cat$\rightarrow$CategoryData0bok$\rightarrow$BooksDataAuth$\rightarrow$Muallif
LibraryDataManager membangun struktur hierarki kategori (CategoryData.children) dan cache booksById.
Konten Kitab
b{bkid}$\rightarrow$BookContentt{bkid}$\rightarrow$TOC$\rightarrow$TOCNode
BookConnection membaca kolom nass, melakukan dekompresi ZSTD, kemudian mengembalikan objek BookContent.
Daftar Isi Kitab (BookConnection.buildTOCTree)
Karakteristik data bawaan Shamela:
- Struktur tabel
t{bkid}tidak selalu konsisten di setiap kitab. - Nilai
lvl/subterkadang tidak tersusun secara ideal. - Relasi induk-turunan (parent-child) tidak disimpan sebagai foreign key eksplisit.
Strategi yang digunakan adalah pendekatan heuristik bertahap:
- Mengambil data mentah TOC dari
t{bkid}dengan kueri:SELECT id, tit, COALESCE(lvl, 0), COALESCE(sub, 0) ORDER BY id
- Menginstansiasi seluruh objek
TOCNodepada pass pertama, kemudian mengelompokkannya ke dalamlevelStacks[level]. - Menentukan root node awal dari level 1 (
level == 1 && sub == 0). - Untuk setiap node dengan
level > 1, sistem mencari parent node kandidat dari level terdekat di atasnya:- Memeriksa level dari
currentLevel - 1turun hingga1. - Memilih parent terakhir dengan ketentuan
parent.id <= node.id.
- Memeriksa level dari
- Jika parent node tidak ditemukan, node tersebut dipromosikan menjadi root node (fallback agar konten tidak hilang dari antarmuka pengguna).
Catatan teknis:
- Mengandalkan asumsi bahwa urutan
idmerepresentasikan alur linier dokumen. - Promosi ke root node merupakan kompromi untuk memastikan seluruh bab tetap dapat diakses.
- Hasil struktur hierarki di-cache per buku via
tocTreeCacheguna menghindari kalkulasi berulang. - Pembatalan tugas dipantau secara berkala melalui
Task.isCancelled.
Rawi / Tarjamah
rowa$\rightarrow$Rowimen_b/men_u$\rightarrow$TarjamahMen- Konten dari
b{bkid}$\rightarrow$TarjamahResult
Model Rowi melakukan normalisasi data pada blok didSet (seperti aqual, rotba, sheok, telmez, who).
Pengelompokan Perawi Berdasarkan Tabaqa (RowiDataManager.loadData().groupByTabaqa())
Karakteristik data bawaan Shamela:
- Tabel
rowatidak memiliki kolom hierarki bertingkat sepertilvl. - Klasifikasi generasi perawi tersimpan pada kolom teks
TABAQAdengan format gabungan huruf, angka, dan teks.
Oleh karena itu, struktur perawi yang dibentuk berupa hierarki dua tingkat:
- Tingkat 1:
TabaqaGroup(kodeF..Pbeserta fallback). - Tingkat 2: Daftar entitas
Rowidi dalam grup terkait.
Alur pemrosesan:
loadData()memuat kolom dasar (id,TABAQA,IsoName) untuk seluruh perawi.- Setiap perawi dipetakan ke kode normal melalui
Rowi.getNormalizedTabaqaCode(). groupByTabaqa()membentuk kamus data[kode: [Rowi]].- Grup disusun berdasarkan urutan kode domain
orderedCodes = [F...P]. - Kode di luar rentang dimasukkan ke grup fallback (
Unknownatau kode mentah). - Setiap grup menerapkan pemuatan bertahap (pagination via
initialLoaddanloadMore) untuk menjaga efisiensi rendering antarmuka pengguna.
Alur Transformasi Teks
1) Dekompresi nass (ZSTD)
Alur Pembacaan Utama (Main Read Path) (BookConnection.getContent, getFirstContent, getContentByPage, dll.):
- Menjalankan kueri kolom
nasssebagaiBlob. - Mengonversi
Data(blob.bytes)$\rightarrow$ReusableFunc.decompressData. - Teks hasil dekompresi disimpan ke dalam
BookContent.nash.
Pada alur pencarian atau tarjamah, jika nass terbaca langsung sebagai String, sistem langsung menggunakan teks tersebut sebagai fallback.
2) Pemetaan Singkatan shorts
DatabaseManager.loadShortsForBook(_:) memuat peta Ramz -> Nass dari special.sqlite.
BookConnection.applyShortsMapping mengganti token singkatan secara berurutan mulai dari kunci (key) terpanjang.
Implikasi arsitektur:
- Ekspansi singkatan dieksekusi pada setiap pembacaan konten buku.
- Terdapat
shortsCacheper buku untuk meminimalkan kueri basis data berulang.
3) Kurung Teks Ayat {} dan Rendering Tipografi
Fungsi StringExt.cleanedText() dan cleanedTextWithRanges():
- Mengonversi literal
\\nmenjadi karakter baris baru (newline). - Menghapus karakter pemisah khusus (
¬,§). - Mengubah tanda kurung
{dan}menjadi kurung ayat Arab (﴿/﴾) sesuai font aktif. - Pada varian
cleanedTextWithRanges(), rentang teks di dalam kurung dicatat untuk kebutuhan penyorotan warna (syntax highlighting) pada UI.
4) Pemetaan tabaqa dan Simbol Perawi
RowiModel dan StringExt menangani:
- Ekspansi kode kitab hadis (
mappingRowiKutub). - Ekspansi singkatan tunggal (
C,E,W,#, dll.). - Konversi kode tabaqa (
F..P) ke label bahasa Arab. - Normalisasi pengelompokan perawi via
getNormalizedTabaqaCode().
Mekanisme Pencarian & FTS
Pencarian Kitab Umum
SearchEngine:
- Menyusun kueri FTS (mode
phrase,contains,or, ataunear). - Menghitung
COUNT(*)dari tabelb{bkid}_fts. - Mengambil data dalam batch menggunakan operasi join:
- Tabel FTS (
b{bkid}_fts) - Tabel konten utama (
b{bkid})
- Tabel FTS (
- Melakukan dekompresi ZSTD pada kolom
nasshasil join jika berupaBLOB.
Pencarian Tarjamah Perawi
TarjamahGlobalManager:
- Mengakses
men_bmelalui indeksmen_b_fts. - Mengakses
men_umelalui indeksmen_u_fts. - Mengambil konten referensi dari
b{bkid}berdasarkanid.
Pembaruan Buku dan Pembangunan Ulang Indeks
BookUpdateManager menjalankan alur pipeline berikut:
- Mengunduh metadata dan berkas buku baru.
- Membaca tabel
main_updateuntuk mendapatkan metadata (bkid,archive,bVer,link, dll.). - Mengonversi tabel
b{bkid}:- Menyalin ke tabel sementara.
- Mengompresi kolom
nassmenggunakan ZSTD (TEXT$\rightarrow$BLOB). - Mengubah nama tabel kembali ke
b{bkid}.
- Mengganti tabel target pada arsip:
b{bkid}t{bkid}
- Membangun ulang indeks FTS pada
N_fts.sqlite:- Menghapus dan membuat ulang (drop/create)
b{bkid}_fts. - Memasukkan data dengan
rowid = iddannass_clean = normalize_arabic(nass).
- Menghapus dan membuat ulang (drop/create)
- Memperbarui metadata
0bokserta nomor versi (bVer).
Basis Data Pengguna
Annotations.sqlite
Tabel annotations:
id: Pengenal unik anotasi (UUID).bkId: ID buku darimain.sqlite.contentId: ID konten buku dari berkasN.sqlite.startIndex,length: Indeks awal dan panjang rentang teks anotasi.startIndexDiac,lengthDiac: Indeks awal dan panjang rentang teks pada mode berharakat.color: Kode warna sorotan (hex).type: Tipe anotasi (highlight / underline).note: Teks catatan pengguna.createdAt: Waktu pembuatan anotasi (UNIX timestamp).context: Cuplikan teks kitab yang dianotasi.part: Nomor jilid/bagian.page: Nomor halaman.
Data ini dipetakan ke model Annotation.
SearchResults.sqlite
folders: Menyimpan struktur hierarki folder untuk hasil pencarian yang disimpan (bookmarks).results: Menyimpan entitas hasil pencarian (query,archive,bkId, daftarcontentId).
Data ini dipetakan ke model SavedResultsItem dan node tampilan hasil pencarian.
Catatan Implementasi Penting
- Pembacaan konten melakukan dekompresi ZSTD pada setiap pengambilan baris dan menyimpannya ke
BookPageCacheuntuk meminimalkan beban CPU berulang. - Ekspansi singkatan
shortsdilakukan setelah tahap dekompresi. - Fitur markah buku (bookmarks) diintegrasikan dengan modul penyimpanan hasil pencarian guna menjaga konsistensi arsitektur dan kemudahan pemeliharaan kode.
Berkas Referensi Terkait
DatabaseManager.swiftBookConnection.swiftBookUpdateManager.swiftAnnotationManager.swiftResultsHandler.swiftSearchEngine.swiftStringExt.swiftRowiDataManager.swiftTarjamahDataManager.swiftRowiModel.swiftAnnotations.swiftRowi.swift