AI untuk Dokumentasi Query SQL: Hemat Waktu Handover

AI bisa bikin dokumentasi query SQL dalam 2 menit kalau prompt kamu berisi tiga hal: query lengkapnya, konteks bisnis singkat, dan format output yang kamu mau.

Tanpa tiga itu, hasilnya generic. AI bakal nulis "query ini melakukan agregasi data penjualan", kalimat yang nggak nolongin siapa-siapa.

Tutorial ini ngasih alur lengkapnya, dari query mentah sampai dokumentasi yang bisa langsung ditempel di repo atau Notion tim kamu.

Kenapa dokumentasi query itu masalah?

Kamu nulis query 180 baris dengan 6 CTE, jalan sempurna, hasilnya masuk dashboard. Tiga bulan kemudian kamu pindah tim.

Orang berikutnya buka file itu, dan nggak ada satu pun komentar di dalamnya. Kolom flag_2 itu apa? Kenapa ada filter WHERE kode NOT IN (7, 13)?

Dia bakal chat kamu. Dan kamu udah lupa juga.

Dokumentasi itu kerjaan yang semua orang setuju penting dan hampir nggak ada yang ngerjain. Bukan karena males. Tapi karena nulisnya lama.

Query yang bakal kita dokumentasikan

Aku pakai query dari dataset toko_berkah. Panjangnya sedang, ada 2 CTE, cukup buat ngeliat pola kerjanya.

WITH transaksi_bersih AS (
    SELECT
        transaksi_id,
        pelanggan_id,
        tanggal,
        kota,
        qty * harga_satuan AS nilai
    FROM transaksi
    WHERE status = 'selesai'
      AND qty > 0
),
agregat_pelanggan AS (
    SELECT
        pelanggan_id,
        kota,
        COUNT(*) AS jumlah_order,
        SUM(nilai) AS total_belanja,
        MAX(tanggal) AS transaksi_terakhir
    FROM transaksi_bersih
    GROUP BY pelanggan_id, kota
)
SELECT
    kota,
    COUNT(*) AS jumlah_pelanggan,
    ROUND(AVG(total_belanja)) AS rata_belanja,
    SUM(CASE WHEN jumlah_order >= 3 THEN 1 ELSE 0 END) AS pelanggan_loyal
FROM agregat_pelanggan
GROUP BY kota
ORDER BY rata_belanja DESC;

Prompt template buat dokumentasi query

Ini template yang paling konsisten hasilnya. Tempel apa adanya, ganti bagian dalam kurung siku.

Kamu analis data senior. Dokumentasikan query SQL di bawah ini.

KONTEKS BISNIS:
- Tabel `transaksi` = catatan transaksi toko online, 1 baris = 1 item terjual
- Kolom `status` bisa berisi: selesai, batal, pending
- Query ini dipakai buat dashboard mingguan tim marketing

FORMAT OUTPUT yang aku mau:
1. TUJUAN — satu paragraf, kenapa query ini ada
2. TABEL SUMBER — daftar tabel + kolom yang dipakai
3. ALUR — penjelasan per CTE, satu kalimat masing-masing
4. DATA DICTIONARY — tabel berisi kolom output, tipe data, dan definisinya
5. CATATAN — asumsi atau hal yang perlu diwaspadai

ATURAN:
- Kalau ada kolom yang maknanya nggak jelas dari nama atau konteks,
  tulis "PERLU KONFIRMASI" — jangan nebak
- Bahasa Indonesia, langsung ke poin

QUERY:
[tempel query di sini]

Bagian ATURAN yang paling penting. Tanpa instruksi "jangan nebak", AI bakal ngarang makna kolom dengan percaya diri.

Cara minta komentar inline

Dokumentasi terpisah bagus, tapi komentar di dalam file SQL lebih sering kebaca. Prompt keduanya:

Kembalikan query yang sama persis — jangan ubah satu karakter pun
dari logikanya, jangan rapikan format, jangan ganti alias.

Yang boleh kamu tambahin cuma komentar SQL (--):
- Satu komentar di atas tiap CTE, jelasin apa yang dia hasilkan
- Satu komentar di tiap filter WHERE yang nggak jelas alasannya
- Jangan komentari hal yang udah jelas dari kodenya

Query:
[tempel query]

Hasilnya kira-kira gini:

-- Buang transaksi batal & baris qty nol, hitung nilai per baris
WITH transaksi_bersih AS (
    SELECT
        transaksi_id,
        pelanggan_id,
        tanggal,
        kota,
        qty * harga_satuan AS nilai
    FROM transaksi
    -- Cuma transaksi selesai yang dihitung ke omzet
    WHERE status = 'selesai'
      AND qty > 0
),
-- Rangkum per pelanggan: berapa kali order & total belanjanya
agregat_pelanggan AS (
    SELECT
        pelanggan_id,
        kota,
        COUNT(*) AS jumlah_order,
        SUM(nilai) AS total_belanja,
        MAX(tanggal) AS transaksi_terakhir
    FROM transaksi_bersih
    GROUP BY pelanggan_id, kota
)
-- Output akhir: profil pelanggan per kota + hitungan pelanggan loyal
SELECT
    kota,
    COUNT(*) AS jumlah_pelanggan,
    ROUND(AVG(total_belanja)) AS rata_belanja,
    -- Loyal = pernah order 3x atau lebih
    SUM(CASE WHEN jumlah_order >= 3 THEN 1 ELSE 0 END) AS pelanggan_loyal
FROM agregat_pelanggan
GROUP BY kota
ORDER BY rata_belanja DESC;

Kalau kamu belum familiar sama CASE WHEN atau SUM, komentar kayak gini yang bikin query lama tetap kebaca.

Data dictionary: bagian yang paling sering dicari orang

Waktu orang lain buka query kamu, pertanyaan pertama mereka biasanya: kolom rata_belanja ini udah termasuk ongkir atau belum?

Jadi bagian ini yang perlu paling detail.

Kolom output	Tipe	Definisi
kota	text	Kota pengiriman, diambil dari kolom kota di tabel transaksi
jumlah_pelanggan	integer	Pelanggan unik yang punya minimal 1 transaksi selesai di kota itu
rata_belanja	integer	Rata-rata total belanja seumur hidup per pelanggan. Belum termasuk ongkir dan diskon.
pelanggan_loyal	integer	Pelanggan dengan 3 transaksi selesai atau lebih. Ambang 3 ini keputusan tim marketing, bukan standar industri

Kalimat "belum termasuk ongkir dan diskon" itu yang nyelametin orang berikutnya dari salah kesimpulan. AI nggak bakal tau itu. Kamu yang harus nulis.

Contoh kasus: berapa waktu yang dihemat

Aku coba ukur di query toko_berkah versi lengkap: 180 baris, 6 CTE, 4 JOIN.

Nulis dokumentasi manual dari nol: sekitar 45 menit. Kebanyakan waktunya habis buat baca ulang query sendiri dan inget-inget kenapa filter tertentu ada di situ.

Pakai prompt template di atas: draft jadi dalam 2 menit. Verifikasi manual (baca hasilnya, benerin 3 makna kolom yang salah tebak, tambah 2 catatan asumsi): 11 menit.

Total 13 menit vs 45 menit. Hemat sekitar 32 menit per query.

Dari 6 CTE yang dijelasin AI, 5 benar sempurna. Yang salah satu: AI nebak kolom kode_sumber itu "kode kategori produk", padahal aslinya kode channel akuisisi. Nama kolomnya memang ambigu. AI nggak punya cara tau.

Kesalahan umum

Percaya penjelasan makna bisnis dari AI mentah-mentah. AI benar soal sintaks, sering salah soal arti. Kolom status_2 di perusahaan kamu artinya apa? Cuma kamu yang tau.

Nempel query yang ada data sensitif. Kalau di WHERE clause ada nomor rekening atau NIK, ganti dulu jadi placeholder.

Nggak ngasih konteks tabel. Prompt tanpa konteks bisnis ngasih dokumentasi yang cuma nerjemahin SQL ke Bahasa Indonesia. Itu nggak berguna. Orang yang baca query udah bisa baca SQL.

Biarin AI merapikan query kamu. Minta komentar, dapat query yang formatnya berubah semua. Diff-nya jadi 180 baris. Selalu instruksikan "jangan ubah satu karakter pun dari logikanya".

Dokumentasi sekali, nggak pernah diupdate. Query berubah, dokumentasi ketinggalan. Masukin langkah "update komentar" ke checklist pull request kamu.

FAQ

Apakah aman menempelkan query SQL ke ChatGPT atau Claude?

Tergantung isinya. Query yang cuma berisi nama tabel dan kolom umumnya aman. Yang nggak boleh: query dengan data nasabah di WHERE clause, kredensial koneksi, atau nama tabel yang membocorkan rahasia bisnis. Kalau ragu, ganti nama sensitif jadi generik sebelum kamu tempel.

Berapa akurat AI dalam menjelaskan query SQL?

Buat sintaks dan alur teknis, akurasinya tinggi. Buat makna bisnisnya, akurasinya jatuh. AI nggak tau bahwa kolom 'status_2' di perusahaan kamu artinya 'sudah dibayar tapi belum dikirim'. Verifikasi makna bisnis selalu jadi tugas kamu.

Format dokumentasi query seperti apa yang paling berguna saat handover?

Empat bagian: satu paragraf tujuan, daftar tabel sumber, komentar per blok CTE, dan tabel data dictionary buat kolom output. Bagian yang paling sering dicari adalah data dictionary. Orang mau tau kolom 'net_revenue' itu udah dikurangi diskon atau belum.

Apakah AI bisa nulis komentar inline langsung di file SQL?

Bisa. Minta AI kembalikan query yang sama persis tanpa mengubah logikanya, tapi dengan komentar dua strip di atas tiap CTE dan tiap filter yang nggak jelas. Bandingkan hasilnya dengan versi asli sebelum di-commit.

Berapa waktu yang dihemat pakai AI buat dokumentasi query?

Dari yang aku ukur, dokumentasi query 180 baris dengan 6 CTE makan 40-50 menit kalau manual. Pakai AI dengan prompt yang benar, draftnya jadi dalam 2 menit dan verifikasi manualnya sekitar 10 menit. Sekitar 30 menit hemat per query.

Coba di query kamu sendiri

Prompt harus punya konteks bisnis, bukan cuma query mentah. Instruksikan AI nulis "PERLU KONFIRMASI" buat kolom yang ambigu. Ini yang mencegah dia ngarang. Data dictionary bagian yang paling sering dibaca orang, jadi tulis paling detail di situ.

Ambil satu query paling panjang di repo kamu hari ini, tempel ke template di atas, lihat hasilnya.

Panduan prompting resmi buat kasus teknis bisa kamu baca di dokumentasi prompt engineering OpenAI. Kalau kamu masih bangun fondasi SQL-nya, mulai dari panduan CTE di SQL dan glossary CTE.