Plugin Map Visualization

Affiche les résultats de tes requêtes sur une carte interactive, directement dans Beekeeper Studio. Pointe-le vers n’importe quel jeu de résultats contenant des coordonnées, des géométries ou des noms de lieux, et choisis comment l’afficher : points, bulles proportionnelles, marqueurs numérotés, clusters, cartes de chaleur, tracés, lignes de flux ou régions colorées.

Démo : résultats de requêtes affichés en bulles, carte de chaleur, clusters, États américains, lignes de trajets et tracés GPS

_{Accéléré 1,6×. Regarde la vidéo à vitesse normale.}

Installation

Beekeeper Studio est livré avec les plugins communautaires désactivés. Active-les dans user.config.ini (~/.config/beekeeper-studio/ sous Linux, ~/Library/Application Support/beekeeper-studio/ sous macOS, %APPDATA%\beekeeper-studio\ sous Windows), puis redémarre l’app :

[pluginSystem]
disabled = false
communityDisabled = false

Une fois le plugin listé dans le registre des plugins, installe Map Visualization depuis Tools → Manage Plugins. D’ici là, compile-le et lie-le dans le dossier des plugins comme expliqué dans Développement.

Ouvrir une carte

Où	Ce qui se passe
Clic droit sur le coin supérieur gauche (ou sur un en-tête de colonne) d’une grille de résultats ou d’une vue de tableau → Plot on Map	Affiche les cellules sélectionnées. Aucune requête n’est relancée.
Clic droit dans l’éditeur de requêtes → Plot Query on Map	Exécute le texte sélectionné (ou la requête sous le curseur) et l’affiche sur la carte.
Clic droit sur un tableau dans la barre latérale → View on Map	Exécute `SELECT * … LIMIT 10000` sur le tableau.
Menu déroulant de nouvel onglet ou Tools → New Map	Ouvre un onglet de carte avec son propre champ de requête (Ctrl/Cmd+Enter pour l’exécuter).

Les résultats apparaissent aussi dans le tableau de résultats en bas de l’onglet, donc les lignes brutes sont toujours à un clic.

D’où viennent les positions

Les colonnes sont détectées automatiquement. Tu peux modifier la détection dans le panneau Location.

Données	Exemples
Colonnes latitude / longitude	`lat`/`lng`, `latitude`/`longitude`, `pickup_lat`/`pickup_lon`, `storeLat`/`storeLng` ; degrés décimaux ou DMS (`40°42'46"N`)
Mètres Web Mercator	`x`/`y` en EPSG:3857, convertis automatiquement
Colonnes géométriques	PostGIS EWKB hex, WKB, WKT / EWKT, GeoJSON (texte ou objets), binaire MySQL / GeoPackage, objets `{lat, lng}` ou `{x, y}`, points GeoJSON Mongo
Coordonnées en texte	`"40.7128, -74.0060"`, `(40.7, -74.0)`, `S33.92 E18.42`
Geohashes	`dr5regw3p`
Pays	noms, alias (`UK`, `South Korea`, `Côte d'Ivoire`), codes ISO alpha-2/3 ou numériques
États américains	noms, codes postaux, codes FIPS
Villes	`Paris`, `Paris, TX`, `London, Ontario`, éventuellement affinées par des colonnes pays / État ; ~34k villes, hors ligne
Codes ZIP américains	`02134`, `02134-1234`, ou nombres ayant perdu le zéro initial

Les entrées approximatives sont traitées prudemment : les colonnes lat/lng inversées sont remises dans l’ordre (avec un avertissement), les noms de villes ambigus renvoient à la correspondance la plus peuplée, les codes ZIP sans centroïde exact (boîtes postales) se rabattent sur leur zone ZIP à 3 chiffres, et tout ce qui ne peut pas être placé est comptabilisé. Clique sur « N without a location » dans la barre d’état pour voir ces lignes dans le tableau. Les géométries projetées dans d’autres SRID sont signalées avec une suggestion d’utiliser ST_Transform(geom, 4326).

Modes d’affichage

Couche	Idéal pour	Options
Points	Points, bulles, marqueurs numérotés	Taille selon une colonne (linéaire, racine carrée (fidèle à l’aire) ou log), plafonnement des valeurs extrêmes au 99e percentile, couleur par catégorie ou valeur (classes linéaires, log ou quantiles ; séquentielles ou divergentes), étiquettes (numéro de ligne ou colonne), opacité
Clusters	Des milliers de points qui se chevauchent	Nombre par cluster, zoome pour les séparer
Carte de chaleur	Densité, éventuellement pondérée par une colonne	Rayon, flou, échelle de poids. L’intensité est normalisée par niveau de zoom pour que les points chauds restent visibles à toutes les échelles
Tracé	Traces GPS, itinéraires, visites ordonnées	Un tracé par valeur d’une colonne de regroupement, ordonné par n’importe quelle colonne (horodatages, numéros de séquence) ou par l’ordre des lignes ; marqueurs de début / fin
Lignes	Flux origine → destination (trajets, expéditions)	Colonnes de destination, lignes courbes ou droites, épaisseur et couleur selon une colonne
Régions colorées	Cartes choroplèthes des pays ou des États américains	Nombre de lignes ou somme / moyenne / min / max d’une colonne ; échelle de couleur linéaire, log ou par quantiles

Bulles dimensionnées selon la population et colorées par continent

Survole un élément pour voir un résumé et clique dessus pour la ligne complète, avec Show in table et Copy as JSON. Clique sur une catégorie de la légende pour la masquer, ou Alt-clic pour n’afficher qu’elle. Le bouton tableau de la barre d’outils de la carte envoie toutes les lignes de la vue actuelle dans le tableau de résultats en dessous.

Commandes aux États-Unis agrégées par État

Trajets en taxi affichés en lignes origine → destination

Fonds de carte et export

Le plugin inclut une carte hors ligne : une carte du monde de 20 Mo construite à partir des données OpenStreetMap, pour afficher des cartes sans connexion internet ni serveur de tuiles tiers. Elle contient pays, régions, villes et routes principales, ce qui suffit de l’échelle d’un pays à celle d’une agglomération ; au niveau de la rue, elle manque de détails et la barre d’état te propose alors un fond de carte en ligne.

La liste des fonds de carte est divisée entre les cartes Built in, qui fonctionnent hors ligne, et les cartes Online, qui téléchargent des tuiles depuis un serveur. La carte sélectionnée est indiquée Offline ou Online, avec le serveur utilisé.

Intégrées : Match app theme (par défaut) utilise la carte hors ligne en clair ou en sombre ; Country outlines est la carte la plus simple.
En ligne : rues, topographie et imagerie satellite Esri, OpenStreetMap, OpenTopoMap, ou n’importe quelle URL de tuiles {z}/{x}/{y} personnalisée.
Exporte en PNG (carte et légende), copie l’image dans le presse-papiers, ou enregistre les lignes affichées en GeoJSON.

Cartes hors ligne plus détaillées

Detailed area → Load file… dans Settings → Basemap ajoute un fichier .pmtiles de fond de carte Protomaps par-dessus la carte du monde, par exemple un extrait au niveau de la rue d’une ville ou d’un pays créé avec la CLI pmtiles. En dehors de la zone du fichier, la carte du monde s’affiche normalement.

# 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

Utilise une date de build récente. Les fichiers dans d’autres schémas de tuiles (OpenMapTiles, raster) sont refusés.

Les réglages, la requête et la vue sont enregistrés avec l’onglet. Un onglet restauré ne relance automatiquement sa requête que si elle avait déjà été exécutée et qu’il s’agit d’un unique SELECT en lecture seule.

Problèmes connus

Trois bugs de Beekeeper Studio affectent ce plugin en version 6.1.5 et antérieures ; les correctifs sont en attente côté upstream :

Dans la Community Edition, les onglets de plugin avec un panneau de résultats (comme celui-ci) ne font qu’environ 150px de haut.
Plot Query on Map dans le menu contextuel de l’éditeur de requêtes ne fait rien (l’hôte ne transmet pas le texte de la requête).
Copy image échoue avec une erreur ; Save as PNG… fonctionne.

Les autres points d’entrée fonctionnent en attendant.

Développement

Prérequis : 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 crée un lien symbolique de ce dossier dans le répertoire des plugins (~/.config/beekeeper-studio/plugins/bk-plugin-map-visualization sous Linux). Le nom du lien doit correspondre à l’id dans 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/

Les tables de correspondance dans src/data/ sont générées à partir de jeux de données publics :

# 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 carte du monde hors ligne dans basemaps/ est un build Protomaps limité au zoom 6, sans les couches d’occupation du sol, de couverture terrestre et de POI (environ deux fois plus léger, et une carte de données n’en a pas besoin) :

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

--maxzoom=5 donne une carte de 5 Mo avec moins de villes et de routes, si le téléchargement du plugin doit être plus léger.

Publication

Lance bin/make-release.sh. Il propose la prochaine version à partir des tags existants, définit version dans manifest.json et package.json, commite et pousse un tag correspondant comme v1.0.0. Le workflow de release teste, compile et crée un brouillon de release GitHub avec manifest.json et le zip du plugin.

Sources de données et licences

Contours des pays et des États issus de Natural Earth via world-atlas, et du US Census via us-atlas (domaine public).
Centroïdes des codes ZIP issus du gazetteer ZCTA du US Census Bureau (domaine public).
La carte hors ligne est © contributeurs OpenStreetMap (ODbL) et Natural Earth, issue d’un build de fond de carte Protomaps, affichée avec protomaps-leaflet (BSD-3-Clause).
Les tuiles sont fournies par leurs services respectifs (Esri, OpenStreetMap, OpenTopoMap) selon leurs propres conditions ; l’attribution est affichée sur la carte.
Construit avec Leaflet, Leaflet.markercluster et Leaflet.heat.

Ce plugin est distribué sous licence GPL-3.0. Voir LICENSE.

Map Visualization

Readme