Plugin Map Visualization

Tampilkan hasil query di peta interaktif, langsung di dalam Beekeeper Studio. Arahkan ke result set apa pun yang berisi koordinat, geometri, atau nama tempat, lalu pilih cara menggambarnya: titik, gelembung berukuran, penanda bernomor, cluster, heatmap, jalur, garis aliran, atau wilayah berwarna.

Demo: menampilkan hasil query sebagai gelembung, heatmap, cluster, negara bagian AS, garis perjalanan, dan jalur GPS

_{Dipercepat 1.6×. Tonton video dengan kecepatan normal.}

Instalasi

Secara default, plugin komunitas dinonaktifkan di Beekeeper Studio. Aktifkan di user.config.ini (~/.config/beekeeper-studio/ di Linux, ~/Library/Application Support/beekeeper-studio/ di macOS, %APPDATA%\beekeeper-studio\ di Windows), lalu restart aplikasi:

[pluginSystem]
disabled = false
communityDisabled = false

Setelah plugin ini terdaftar di registry plugin, instal Map Visualization dari Tools → Manage Plugins. Sampai saat itu, build plugin ini lalu tautkan ke folder plugins seperti dijelaskan di bagian Pengembangan.

Membuka peta

Di mana	Yang terjadi
Klik kanan sudut kiri atas (atau header kolom) di grid hasil atau tampilan tabel → Plot on Map	Memetakan sel yang dipilih. Query tidak dijalankan ulang.
Klik kanan di editor query → Plot Query on Map	Menjalankan teks yang dipilih (atau query di posisi kursor) lalu memetakannya.
Klik kanan tabel di sidebar → View on Map	Menjalankan `SELECT * … LIMIT 10000` pada tabel tersebut.
Dropdown tab baru atau Tools → New Map	Membuka tab peta dengan kotak query sendiri (Ctrl/Cmd+Enter untuk menjalankannya).

Hasil query juga muncul di tabel hasil di bagian bawah tab, jadi baris mentahnya selalu bisa diakses dengan satu klik.

Asal data lokasi

Kolom terdeteksi secara otomatis. Hasil deteksi bisa diubah di panel Location.

Data	Contoh
Kolom latitude / longitude	`lat`/`lng`, `latitude`/`longitude`, `pickup_lat`/`pickup_lon`, `storeLat`/`storeLng`; derajat desimal atau DMS (`40°42'46"N`)
Meter Web Mercator	`x`/`y` dalam EPSG:3857, dikonversi otomatis
Kolom geometri	PostGIS EWKB hex, WKB, WKT / EWKT, GeoJSON (teks atau objek), biner MySQL / GeoPackage, objek `{lat, lng}` atau `{x, y}`, titik GeoJSON Mongo
Koordinat teks	`"40.7128, -74.0060"`, `(40.7, -74.0)`, `S33.92 E18.42`
Geohash	`dr5regw3p`
Negara	nama, alias (`UK`, `South Korea`, `Côte d'Ivoire`), kode ISO alpha-2/3 atau numerik
Negara bagian AS	nama, kode pos, kode FIPS
Kota	`Paris`, `Paris, TX`, `London, Ontario`, opsional dipersempit dengan kolom negara / negara bagian; ~34 ribu kota, offline
Kode ZIP AS	`02134`, `02134-1234`, atau angka yang nol di depannya hilang

Input yang kurang rapi ditangani dengan hati-hati: kolom lat/lng yang tertukar dibalik (dengan peringatan), nama kota yang ambigu diarahkan ke kota dengan populasi terbesar, kode ZIP tanpa centroid pasti (PO box) memakai area ZIP 3 digitnya, dan data yang tidak bisa dipetakan akan dihitung. Klik “N tanpa lokasi” di status bar untuk melihat baris-baris tersebut di tabel. Geometri terproyeksi dengan SRID lain dilaporkan beserta petunjuk untuk memakai ST_Transform(geom, 4326).

Cara menggambarnya

Layer	Cocok untuk	Opsi
Titik	Titik, gelembung, penanda bernomor	Ukuran berdasarkan kolom (linear, akar kuadrat (sesuai luas), atau log), batasi outlier di persentil ke-99, warna berdasarkan kategori atau angka (kelas linear, log, atau kuantil; sekuensial atau divergen), label (nomor baris atau kolom), opasitas
Cluster	Ribuan titik yang saling tumpang tindih	Jumlah per cluster, zoom in untuk memecahnya
Heatmap	Kepadatan, opsional diberi bobot dari kolom	Radius, blur, skala bobot. Intensitas dinormalisasi per level zoom agar titik panas tetap terlihat di skala apa pun
Jalur	Jejak GPS, rute, kunjungan berurutan	Satu jalur per kolom grup, diurutkan berdasarkan kolom apa pun (waktu, nomor urut) atau urutan baris; penanda awal / akhir
Garis	Aliran asal → tujuan (perjalanan, pengiriman)	Kolom tujuan, melengkung atau lurus, lebar dan warna berdasarkan kolom
Wilayah berwarna	Choropleth negara atau negara bagian AS	Hitung baris atau sum / average / min / max sebuah kolom; skala warna linear, log, atau kuantil

Gelembung berukuran sesuai populasi dan berwarna sesuai benua

Arahkan kursor ke sebuah tanda untuk melihat ringkasan, dan klik untuk melihat baris lengkapnya, dengan Show in table dan Copy as JSON. Kategori legenda bisa diklik untuk disembunyikan, atau Alt-klik untuk menampilkan kategori itu saja. Tombol tabel di toolbar peta mengirim semua baris di tampilan saat ini ke tabel hasil di bawahnya.

Pesanan di AS yang diagregasi per negara bagian

Perjalanan taksi digambar sebagai garis asal → tujuan

Basemap dan ekspor

Plugin ini dilengkapi peta offline: peta dunia 20 MB yang dibuat dari data OpenStreetMap, jadi peta tetap tampil tanpa koneksi internet atau tile server pihak ketiga. Peta ini memuat negara, wilayah, kota, dan jalan utama, cukup untuk peta skala negara hingga kawasan metro; saat di-zoom ke level jalan, detailnya tidak cukup, dan status bar akan menawarkan basemap online sebagai gantinya.

Daftar basemap dibagi menjadi peta Built in, yang berfungsi offline, dan peta Online, yang mengunduh tile dari tile server. Peta yang dipilih diberi label Offline atau Online, beserta server yang digunakan.

Built in: Match app theme (default) memakai peta offline dalam mode terang atau gelap; Country outlines adalah peta paling sederhana.
Online: Esri streets, topografi dan citra satelit, OpenStreetMap, OpenTopoMap, atau URL tile kustom {z}/{x}/{y}.
Ekspor sebagai PNG (peta dan legenda), salin gambar ke clipboard, atau simpan baris yang dipetakan sebagai GeoJSON.

Peta offline yang lebih detail

Detailed area → Load file… di Settings → Basemap menambahkan file .pmtiles basemap Protomaps di atas peta dunia, misalnya ekstrak level jalan untuk satu kota atau negara yang dibuat dengan CLI pmtiles. Di luar area file tersebut, peta dunia tampil seperti biasa.

# street detail for New York City (about 100 MB)
pmtiles extract https://build.protomaps.com/20261014.pmtiles nyc.pmtiles --bbox=-74.26,40.48,-73.69,40.92 --maxzoom=15

Gunakan tanggal build terbaru. File dengan skema tile lain (OpenMapTiles, raster) akan ditolak.

Pengaturan, query, dan viewport disimpan bersama tab. Tab yang dipulihkan hanya menjalankan ulang query-nya secara otomatis jika query itu pernah dijalankan dan berupa satu SELECT read-only.

Masalah yang diketahui

Ada tiga bug Beekeeper Studio yang memengaruhi plugin ini di versi 6.1.5 dan sebelumnya; perbaikannya sedang menunggu di upstream:

Di Community edition, tab plugin dengan panel hasil (seperti plugin ini) hanya tampil setinggi sekitar 150px.
Plot Query on Map di menu konteks editor query tidak berfungsi (host tidak meneruskan teks query).
Copy image gagal dengan error; Save as PNG… berfungsi.

Sementara itu, cara membuka peta lainnya tetap berfungsi.

Pengembangan

Kebutuhan: Beekeeper Studio 5.5+, Node.js 20.19+, Yarn 1.

yarn install
yarn dev        # links the plugin into Beekeeper Studio's plugins folder and hot-reloads
yarn test       # unit tests (vitest)
yarn build      # type-check + production build into dist/

yarn dev membuat symlink folder ini ke direktori plugins (~/.config/beekeeper-studio/plugins/bk-plugin-map-visualization di Linux). Nama link harus sama dengan id di manifest.json.

src/
  App.vue                 data sources, state, popups, export
  components/             settings panel, legend, icons
  lib/geo/                WKB / WKT / geohash / DMS parsing, regions, offline geocoding
  lib/detect.ts           column auto-detection
  lib/build.ts            rows -> plottable items (CRS, axis order, geocoding)
  lib/model.ts            sizes, colors, aggregates, legends
  lib/renderer.ts         Leaflet layers
  lib/pack.ts             offline map packs: validation, PMTiles source
  lib/offlineMap.ts       bundled world map + detailed area (IndexedDB), shared by all map tabs
  data/                   generated lookup tables (see below)
basemaps/world.pmtiles    the offline world map, bundled into dist/

Tabel lookup di src/data/ dibuat dari dataset publik:

# download cities15000.zip, countryInfo.txt and admin1CodesASCII.txt from https://download.geonames.org/export/dump/
# and 2023_Gaz_zcta_national.zip from the US Census gazetteer, unzip them into one folder, then:
yarn geodata /path/to/that/folder

Peta dunia offline di basemaps/ adalah build Protomaps yang dipotong hingga zoom 6, tanpa layer land use, land cover, dan POI (ukurannya jadi sekitar setengah, dan peta data memang tidak menggambarnya):

pmtiles extract https://build.protomaps.com/<YYYYMMDD>.pmtiles world-z6.pmtiles --maxzoom=6
yarn basemap world-z6.pmtiles basemaps/world.pmtiles

--maxzoom=5 menghasilkan peta 5 MB dengan lebih sedikit kota dan jalan, jika ukuran download plugin perlu lebih kecil.

Merilis

Jalankan bin/make-release.sh. Skrip ini menyarankan versi berikutnya berdasarkan tag yang ada, mengatur version di manifest.json dan package.json, melakukan commit, lalu push tag yang sesuai seperti v1.0.0. Workflow rilis akan menjalankan test, build, dan membuat draft rilis GitHub berisi manifest.json dan zip plugin.

Sumber data dan lisensi

Bentuk negara dan negara bagian dari Natural Earth melalui world-atlas, dan US Census melalui us-atlas (domain publik).
Centroid kode ZIP dari gazetteer ZCTA US Census Bureau (domain publik).
Peta offline © kontributor OpenStreetMap (ODbL) dan Natural Earth, dari build basemap Protomaps, digambar dengan protomaps-leaflet (BSD-3-Clause).
Tile peta disediakan oleh layanan masing-masing (Esri, OpenStreetMap, OpenTopoMap) sesuai ketentuan mereka; atribusi ditampilkan di peta.
Dibuat dengan Leaflet, Leaflet.markercluster, dan Leaflet.heat.

Plugin ini dilisensikan di bawah GPL-3.0. Lihat LICENSE.

Map Visualization

Readme