Parquet Files

SQL Database Reader dapat menjawab pertanyaan dari folder berisi file Parquet di server Anda sendiri. File di-query di tempatnya oleh On-Premise Data Gateway dengan mesin DuckDB, sehingga agent bisa menjawab "berapa pengiriman tiap hub di bulan Oktober?" dari ekspor data lake tanpa file pernah keluar dari jaringan Anda.

Kapan digunakan

Pilih file Parquet bila data Anda memang sudah berbentuk Parquet — hasil ekspor Spark, Databricks, Fabric, BigQuery atau pipeline data — dan Anda tidak ingin memuatnya ke database hanya supaya bisa dibaca agent.

Parquet hanya tersedia lewat gateway. Memindai file butuh CPU dan memori yang cukup besar, dan menjalankannya di hardware Anda membuat biaya maupun datanya tetap di sisi Anda.

Bagaimana file menjadi tabel

Arahkan gateway ke satu folder. Di dalamnya:

/srv/parquet/
  shipments/                     → tabel "shipments"
    year=2025/month=10/*.parquet     folder partisi menjadi kolom year dan month
  vendors/vendors.parquet        → tabel "vendors"
  hubs.parquet                   → tabel "hubs"
  _temporary/   .cache/          diabaikan (nama berawalan _ atau .)

• Setiap subfolder yang berisi file .parquet, sedalam apa pun, menjadi satu tabel. File dengan kolom yang berbeda tetapi cocok digabung berdasarkan nama kolom.
• Setiap file .parquet yang langsung berada di folder itu menjadi satu tabel.
• Folder partisi bernama seperti year=2025 menjadi kolom biasa. Pertanyaan yang memfilternya membaca lebih sedikit file, jadi susunan year/month membuat jawaban tetap cepat.
• Nama tabel huruf kecil, dan karakter selain huruf, angka dan _ diganti _ (Order Items menjadi order_items).
• File baru di folder yang sudah ada langsung terbaca di pertanyaan berikutnya. Folder atau kolom baru muncul setelah Refresh Schema di tab Tables.

Mendeskripsikan tabel (opsional)

File Parquet tidak membawa deskripsi. Anda bisa menambahkannya di Qlar pada tab Tables, atau memberi gateway file tabel kecil supaya deskripsi ikut terbawa bersama skema:

{
  "tables": {
    "shipments": {
      "description": "Satu baris per pengiriman, dipartisi per tahun dan bulan",
      "columns": { "cost_idr": "Biaya kirim dalam Rupiah", "sla_days": "Janji hari pengiriman" }
    },
    "branches": { "path": "hubs.parquet", "description": "Daftar cabang" }
  },
  "exclude": ["staging"]
}

Simpan di folder Parquet dan set PARQUET_TABLES_FILE=tables.json di .env gateway. File ini juga bisa mengganti nama tabel (path menunjuk folder, file atau glob di dalam folder), mengecualikan tabel, atau mematikan penemuan otomatis.

Relasi antartabel

Parquet tidak punya primary key maupun foreign key, jadi Qlar tidak melihat relasi dengan sendirinya. Tambahkan sebagai virtual foreign key — misalnya shipments.hub_id → hubs.hub_id — supaya pertanyaan yang menggabungkan tabel di-join dengan benar.

Cara menyiapkan

1. Pilih Parquet on your server

Buka plugin SQL Database Reader dari Tools → Plugins. Di Where does your data come from?, pada grup Files, pilih Parquet on your server (bertanda Stays on your network). Langkah berikutnya adalah langkah gateway; tidak ada kredensial yang perlu diisi.

2. Hubungkan gateway

Klik Connect a new gateway, pilih Docker atau Python (pip), lalu jalankan perintah yang tampil di server tempat file berada. Perintah itu sudah berisi kode enrolment sekali pakai dan memasang mesin Parquet.

Dengan Docker, ganti /path/to/parquet dengan folder Anda. Folder di-mount read-only — gateway tidak pernah perlu menulis ke sana:

docker run -d --name qlar-gateway --restart unless-stopped \
  --env-file .env -v "$PWD/state:/state" -v "/srv/parquet:/data:ro" \
  ghcr.io/qlar-ai/qlar-data-gateway:0.3.0 enroll

Dengan pip, qlar-gateway enroll menanyakan sumber datanya: jawab parquet lalu isi foldernya.

3. Setujui fingerprint

Bandingkan fingerprint yang dicetak gateway dengan yang tampil di Qlar, lalu klik Approve, sama seperti gateway database. Tombol Test pada gateway melaporkan mesin dan jumlah tabel yang ditemukan, misalnya DuckDB v1.2.0 - 3 tables in /data.

4. Muat dan deskripsikan tabel

Di langkah Tables, muat tabel, centang yang boleh dipakai agent, tambahkan deskripsi dan virtual foreign key, lalu simpan. Setelah itu semuanya — function settings, query testing, row-level security dan log — bekerja sama seperti database.

Resource dan batas

Gateway menjalankan DuckDB di dalam prosesnya sendiri. Pengaturan berikut di .env gateway menentukan seberapa banyak resource server yang boleh dipakai:

Pertanyaan yang query-nya butuh memori melebihi batas, atau melewati timeout, dijawab dengan pesan bahwa permintaannya terlalu berat — persempit periodenya atau minta ringkasan, bukan semua baris.

Keamanan

• Gateway yang menentukan file mana yang ada dan apa nama tiap tabel. Qlar hanya bisa meminta tabel-tabel itu berdasarkan nama.
• Setiap query harus berupa satu SELECT. Fungsi yang membaca file lain (read_csv, read_parquet, glob …), path file, dan perintah yang menulis, meng-attach atau memasang sesuatu ditolak sebelum dijalankan.
• Mesin DuckDB dikunci ke folder Parquet: tidak ada file lain yang bisa dibuka dan kunci itu tidak bisa dimatikan oleh query.
• Tetap berikan gateway akses read-only ke folder (:ro di Docker, atau service account tanpa izin tulis). Gateway memberi peringatan saat start bila ia bisa menulis ke sana.
• Setiap query dicatat di audit log lokal gateway, di server Anda.

Halaman Terkait

• On-Premise Data Gateway
• Virtual Foreign Keys
• Configure Tables and Columns
• Excel File Source