Plugin Map Visualization

Visualizza i risultati delle query su una mappa interattiva, direttamente in Beekeeper Studio. Usalo con qualsiasi set di risultati con coordinate, geometrie o nomi di luoghi e scegli come disegnarlo: punti, bolle dimensionate, marcatori numerati, cluster, heatmap, percorsi, linee di flusso o regioni colorate.

Demo: risultati delle query visualizzati come bolle, heatmap, cluster, stati USA, linee di viaggio e percorsi GPS

_{Accelerato 1,6×. Guarda il video a velocità normale.}

Installazione

Beekeeper Studio ha i plugin della community disattivati per impostazione predefinita. Attivali in user.config.ini (~/.config/beekeeper-studio/ su Linux, ~/Library/Application Support/beekeeper-studio/ su macOS, %APPDATA%\beekeeper-studio\ su Windows), poi riavvia l'app:

[pluginSystem]
disabled = false
communityDisabled = false

Quando il plugin sarà presente nel registro dei plugin, installa Map Visualization da Tools → Manage Plugins. Fino ad allora, compilalo e collegalo alla cartella dei plugin come descritto in Sviluppo.

Aprire una mappa

Dove	Cosa succede
Clic destro sull'angolo in alto a sinistra (o sull'intestazione di una colonna) di una griglia di risultati o della vista tabella → Plot on Map	Mappa le celle selezionate. Nessuna query viene rieseguita.
Clic destro nell'editor di query → Plot Query on Map	Esegue il testo selezionato (o la query sotto il cursore) e lo mappa.
Clic destro su una tabella nella barra laterale → View on Map	Esegue `SELECT * … LIMIT 10000` sulla tabella.
Menu a tendina della nuova scheda o Tools → New Map	Apre una scheda mappa con il suo campo query (Ctrl/Cmd+Enter la esegue).

I risultati della query compaiono anche nella tabella dei risultati in fondo alla scheda, così le righe grezze sono sempre a un clic di distanza.

Da dove arrivano le posizioni

Le colonne vengono rilevate automaticamente. Puoi modificare il rilevamento nel pannello Location.

Dati	Esempi
Colonne latitudine / longitudine	`lat`/`lng`, `latitude`/`longitude`, `pickup_lat`/`pickup_lon`, `storeLat`/`storeLng`; gradi decimali o DMS (`40°42'46"N`)
Metri Web Mercator	`x`/`y` in EPSG:3857, convertiti automaticamente
Colonne geometriche	PostGIS EWKB hex, WKB, WKT / EWKT, GeoJSON (testo o oggetti), binario MySQL / GeoPackage, oggetti `{lat, lng}` o `{x, y}`, punti GeoJSON di Mongo
Coordinate testuali	`"40.7128, -74.0060"`, `(40.7, -74.0)`, `S33.92 E18.42`
Geohash	`dr5regw3p`
Paesi	nomi, alias (`UK`, `South Korea`, `Côte d'Ivoire`), codici ISO alpha-2/3 o numerici
Stati USA	nomi, codici postali, codici FIPS
Città	`Paris`, `Paris, TX`, `London, Ontario`, eventualmente filtrate per colonne paese / stato; ~34k città, offline
CAP USA (ZIP)	`02134`, `02134-1234`, o numeri che hanno perso lo zero iniziale

Gli input imprecisi vengono gestiti con prudenza: le colonne lat/lng invertite vengono scambiate (con un avviso), i nomi di città ambigui corrispondono alla città più popolosa, i CAP senza un centroide esatto (caselle postali) ripiegano sulla loro area ZIP a 3 cifre e tutto ciò che non può essere posizionato viene conteggiato. Fai clic su “N senza posizione” nella barra di stato per vedere quelle righe nella tabella. Le geometrie proiettate in altri SRID vengono segnalate con il suggerimento di usare ST_Transform(geom, 4326).

Modi di disegnarla

Livello	Usalo per	Opzioni
Punti	Punti, bolle, marcatori numerati	Dimensione in base a una colonna (lineare, radice quadrata (fedele all'area) o logaritmica), limite dei valori anomali al 99° percentile, colore per categoria o numero (classi lineari, logaritmiche o per quantili; sequenziali o divergenti), etichette (numero di riga o una colonna), opacità
Cluster	Migliaia di punti sovrapposti	Conteggio per cluster, zoom per separarli
Heatmap	Densità, eventualmente ponderata da una colonna	Raggio, sfocatura, scala del peso. L'intensità è normalizzata per livello di zoom, così i punti caldi restano visibili a qualsiasi scala
Percorso	Tracce GPS, itinerari, visite in sequenza	Un percorso per ogni valore della colonna di raggruppamento, ordinato per qualsiasi colonna (orari, numeri di sequenza) o per ordine delle righe; marcatori di inizio / fine
Linee	Flussi origine → destinazione (viaggi, spedizioni)	Colonne di destinazione, curve o dritte, spessore e colore in base a una colonna
Regioni colorate	Mappe coropletiche di paesi o stati USA	Conta le righe o calcola somma / media / min / max di una colonna; scala di colore lineare, logaritmica o per quantili

Bolle dimensionate per popolazione e colorate per continente

Passa il mouse su un elemento per un riepilogo e fai clic per vedere la riga completa, con Show in table e Copy as JSON. Fai clic sulle categorie della legenda per nasconderle, o Alt-clic per mostrare solo quella categoria. Il pulsante tabella nella barra degli strumenti della mappa invia tutte le righe della vista corrente alla tabella dei risultati sottostante.

Ordini USA aggregati per stato

Corse in taxi disegnate come linee origine → destinazione

Mappe di base ed esportazione

Il plugin include una mappa offline: una mappa del mondo da 20 MB costruita con dati OpenStreetMap, così le mappe si disegnano senza connessione internet né server di tile di terze parti. Contiene paesi, regioni, città e strade principali, sufficienti per mappe dal livello nazionale a quello metropolitano; zoomando a livello di strada i dettagli finiscono e la barra di stato propone invece una mappa di base online.

L'elenco delle mappe di base è diviso in mappe Built in, che funzionano offline, e mappe Online, che scaricano i tile da un server. La mappa selezionata è contrassegnata come Offline o Online, con il server che usa.

Built in: Match app theme (predefinita) usa la mappa offline in versione chiara o scura; Country outlines è la mappa più semplice.
Online: strade, topografia e immagini satellitari Esri, OpenStreetMap, OpenTopoMap o qualsiasi URL di tile personalizzato {z}/{x}/{y}.
Esporta come PNG (mappa e legenda), copia l'immagine negli appunti o salva le righe mappate come GeoJSON.

Mappe offline più dettagliate

Detailed area → Load file… in Settings → Basemap aggiunge un file .pmtiles di mappa di base Protomaps sopra la mappa del mondo, ad esempio un estratto a livello di strada di una città o di un paese creato con la CLI pmtiles. Fuori dall'area del file la mappa del mondo viene mostrata come al solito.

# 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

Usa una build recente. I file con altri schemi di tile (OpenMapTiles, raster) vengono rifiutati.

Impostazioni, query e area visualizzata vengono salvate con la scheda. Una scheda ripristinata riesegue automaticamente la query solo se era già stata eseguita ed è una singola SELECT di sola lettura.

Problemi noti

Tre bug di Beekeeper Studio interessano questo plugin nella versione 6.1.5 e precedenti; le correzioni sono in attesa upstream:

Nella Community Edition, le schede dei plugin con un pannello dei risultati (come questa) vengono visualizzate alte solo circa 150px.
Plot Query on Map nel menu contestuale dell'editor di query non fa nulla (l'host non passa il testo della query).
Copy image fallisce con un errore; Save as PNG… funziona.

Nel frattempo gli altri punti di accesso funzionano.

Sviluppo

Requisiti: 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 crea un link simbolico di questa cartella nella directory dei plugin (~/.config/beekeeper-studio/plugins/bk-plugin-map-visualization su Linux). Il nome del link deve corrispondere all'id in 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/

Le tabelle di lookup in src/data/ sono generate da dataset pubblici:

# 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

La mappa del mondo offline in basemaps/ è una build Protomaps limitata allo zoom 6, senza i livelli di uso del suolo, copertura del suolo e POI (circa la metà delle dimensioni, e una mappa di dati non li disegna):

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

--maxzoom=5 produce una mappa da 5 MB con meno città e strade, se il download del plugin deve essere più leggero.

Rilascio

Esegui bin/make-release.sh. Suggerisce la versione successiva in base ai tag esistenti, imposta version in manifest.json e package.json, fa il commit e pubblica un tag corrispondente come v1.0.0. Il workflow di rilascio esegue i test, compila e crea una bozza di release GitHub con manifest.json e lo zip del plugin.

Fonti dei dati e licenze

Forme di paesi e stati da Natural Earth tramite world-atlas, e dallo US Census tramite us-atlas (pubblico dominio).
Centroidi dei CAP dal gazetteer ZCTA dello US Census Bureau (pubblico dominio).
La mappa offline è © contributori di OpenStreetMap (ODbL) e Natural Earth, da una build della mappa di base Protomaps, disegnata con protomaps-leaflet (BSD-3-Clause).
I tile delle mappe sono forniti dai rispettivi servizi (Esri, OpenStreetMap, OpenTopoMap) secondo i loro termini; l'attribuzione è mostrata sulla mappa.
Realizzato con Leaflet, Leaflet.markercluster e Leaflet.heat.

Questo plugin è distribuito con licenza GPL-3.0. Vedi LICENSE.

Map Visualization

Readme