Vos données se joignent à Overture sur un UUID, pas sur un nom

La ligne qui ancre ce billet sort d'une seule requête contre la version 2026-09-23.1 d'Overture Maps, lancée avec DuckDB 1.5.6 le 11 octobre 2026 : la place e13e7209-a09a-4cf7-9d45-0532936fcc4c, nommée Ashley Store, taxonomy primary furniture_store, confidence 1,0, à l'intérieur d'une bounding box tracée autour du lac Tahoe. Cette suite de chiffres hexadécimaux est un identifiant GERS issu du thème places, et tout ce que ce billet soutient découle de ce que cet identifiant permet à une jointure de faire.

Posons l'affirmation pour qu'un sceptique puisse s'y attaquer. Quand vous migrez vos propres tables vers Overture, le travail est de la résolution d'entités, et le livrable est une table de jointure versionnée qui relie vos clés de lignes aux identifiants GERS, et non un remplacement en bloc des clés que votre pipeline détient déjà. Si le plan de migration jette les identifiants de nœuds et de chemins OpenStreetMap sur lesquels le pipeline est né, vous obtenez un schéma qui a l'air migré. La traçabilité, elle, ne se reconstruit plus. Vous joignez. Vous ne remplacez pas.

Le nom seul est l'impasse dans laquelle votre plan de migration stationne

Ce dont vous avez besoin est une jointure, et les ordres de grandeur font la démonstration. La version 2026-09-23.1 porte 81 455 423 features de type place et 4 688 229 divisions, et la bounding box de Tahoe contient à elle seule 228 935 bâtiments. Quelque part là-dedans se trouve la cible de chaque ligne d'un référentiel de magasins, d'un registre d'actifs ou d'une table parcellaire.

Les façons d'improviser cette jointure échouent dans un ordre instructif. L'égalité de nom meurt la première, sur les chaînes de marques : le même nom de magasin apparaît dans deux centres commerciaux distants de quelques kilomètres, et une chaîne de caractères ne vous dira pas lequel. Nom plus distance d'édition trouve le centre voisin presque aussi souvent que la cible. Un découpage en geohash plus une distance à vol d'oiseau fonctionne jusqu'à ce qu'un parking commun place deux candidats à quelques mètres l'un de l'autre. Dans une boîte qui contient 228 935 bâtiments, ce cas est normal, pas marginal. Les correspondances exactes sur téléphone ou site web couvrent moins de lignes qu'il n'en faut, parce que bien des enregistrements ne portent ni l'un ni l'autre.

Le conflit sous-jacent oppose précision et couverture. Un seuil assez serré pour faire confiance à un appariement machine est assez large pour renvoyer un tiers de vos lignes au travail manuel. Cet arbitrage est survivable, mais seulement assumé, ligne par ligne, avec une trace de la décision. C'est autour de cette exigence que se construit le mécanisme gagnant.

GERS donne à chaque feature consolidée une clé avec un dossier de provenance

Trois faits de schéma, tous vérifiés contre la version 2026-09-23.1, portent l'argument.

Chaque feature des thèmes places, buildings et divisions porte un id de type uuid. Le format compte moins que la frappe : Overture attribue l'identifiant pendant la consolidation, si bien qu'il survit au remous des sources qui réécrit tout le reste de la feature. À côté s'installe un compteur version, et dans divisions ce compteur est par enregistrement : les sous-types county, locality, neighborhood, macrohood et microhood portent chacun leur propre champ version, de sorte que vous voyez qu'une limite jointie à la version précédente a bougé sans comparer une seule géométrie.

Puis le dossier. Chaque feature porte un tableau sources, et chaque entrée nomme un dataset, une license et un record_id. Pour une place dont le dataset est OSM, ce record_id est votre ancien identifiant de nœud ou de chemin. Rien dans une migration n'est obligé de le perdre. C'est l'issue de secours vers la provenance dérivée d'OSM, et la raison pour laquelle l'approche par table de jointure gagne le débat de traçabilité que votre ingénieur données allait ouvrir au troisième mois.

Une note d'honnêteté avant le flux de travail : stable veut dire stable par convention. La version 2026-09-23.1 en est elle-même la preuve, et la section des limites y revient avec des chiffres.

Interroger un rectangle, noter les candidats, accepter au-dessus d'un seuil, journaliser le reste

Voici le flux de travail sur la forme de problème annoncée. Prenons le référentiel de magasins d'une chaîne : quelques milliers de lignes portant nom, adresse postale, téléphone et un point géocodé, rattachées aujourd'hui à des chemins OSM parce que le pipeline y est né. La cible est Overture places, épinglée à la version 2026-09-23.1. Déroulons la jointure pour une ligne, le magasin dont le point géocodé tombe à quelques dizaines de mètres de la feature Ashley Store du début du billet.

Épinglez le nom de version dans la configuration avant toute requête, parce que chaque identifiant que vous vous apprêtez à stocker ne veut dire que ce que la version 2026-09-23.1 en dit. Puis préparez le vivier de candidats. La colonne struct bbox élague les fichiers Parquet par partition et les lignes par prédicat sans ouvrir une seule géométrie, de sorte que le vivier Tahoe coûte 2,77 secondes sur un portable et tient en 28 166 places candidates :

SELECT id,
       names.primary AS name,
       taxonomy.primary AS category,
       confidence,
       sources
FROM read_parquet(
  's3://overturemaps-us-west-2/release/2026-09-23.1/theme=places/type=place/*.parquet',
  hive_partitioning = 1
)
WHERE bbox.xmin >= -121.0 AND bbox.xmax <= -119.6
  AND bbox.ymin >= 38.7 AND bbox.ymax <= 39.5;

Notez ensuite le vivier contre votre ligne, sur des signaux qui échouent indépendamment : distance à vol d'oiseau entre votre point et la feature, accord entre votre catégorie et taxonomy.primary, similarité de nom, et tout signal dur que les deux côtés portent, comme un numéro de téléphone ou un site web. Une précaution tombe tout droit de l'échantillon. Dans le vivier Tahoe, 896 places sur 28 166, environ 3,2 %, n'ont pas de taxonomy.primary, si bien qu'une règle qui exige l'accord de catégorie les écarte en silence. La catégorie corrobore un appariement. Elle ne suffit jamais, seule, à en rejeter un.

Acceptez au-dessus d'un seuil. Nos valeurs de travail acceptent en machine un score composite de 0,92 ou mieux quand le candidat rival le plus proche traîne au moins 0,10 derrière, et envoient le reste en revue. Ces chiffres sont des points de départ, pas des lois. Le bon seuil pour votre table dépend du coût d'une fausse jointure, et c'est précisément la discussion que le journal de revue existe pour éclairer.

Journalisez le reste, toujours. La sortie du flux est une table :

join_gers_places
  your_key         the row key your pipeline already has
  gers_id          e13e7209-a09a-4cf7-9d45-0532936fcc4c
  release_id       2026-09-23.1
  score            0.0 to 1.0, the composite you computed
  reviewer_status  machine_accepted, human_accepted, or pending

La ligne qui a échoué au seuil n'est pas perdue ; c'est une file qu'un humain vide d'une traite. Pour le magasin du début du billet, la distance et l'accord de taxonomie règlent l'appariement, la confidence 1,0 calculée par Overture reste dans la ligne pour recoupement, et la vérification par téléphone n'a même pas à se déclencher. Rien dans le flux n'avait besoin de fuzzy matching pour survivre, parce que GERS a transformé le problème de la devinette en de la comptabilité.

Le gain discret se joue en amont, dans les flux que vous avez enchaînés

La plupart des équipes qui migrent portent plus de jeux de données qu'elles ne l'avouent. Un extrait de CRM, un flux POI acheté à un fournisseur et un cache dérivé d'OSM décrivent chacun, sous trois systèmes de clés privés, le même portefeuille de magasins, et la réconciliation par paires de ces flux est le projet qui ne s'expédie jamais.

Déroulez le flux ci-dessus contre chaque jeu séparément et la réconciliation s'effondre en un group by. Deux lignes issues de jeux différents qui résolvent vers le même identifiant GERS sont le même magasin. Quand les deux se contredisent sur le statut d'exploitation ou les horaires, la contradiction devient une ligne de rapport affublée d'une version et d'un score, au lieu d'une intuition dans un tableur. Quand vous avez besoin de la source d'origine, sources[].record_id vous tend l'enregistrement OSM du dessous pour réconcilier contre. Les jeux enchaînés cessent d'être un nœud parce que, pour la première fois, ils partagent une clé qu'aucun d'entre eux n'a émise.

Là où la jointure fait encore mal, et la parade pour chaque plaie

Quatre coûts apparaissent dans les migrations réelles, et chacun arrive avec sa parade.

Stable veut dire par convention, pas par nature. Les notes de version de 2026-09-23.1 documentent un changement de génération des UUID pour les features base et building_part, de sorte que ces features ont été réémises avec de nouveaux identifiants pendant que places gardait les siens. Tout ce qui était rattaché à un identifiant base ou building_part d'une version antérieure a dérivé, sans aucune édition amont à montrer du doigt. La parade est la discipline que ce billet applique depuis le début : la table de jointure est un cache, et elle se versionne par version. Portez release_id dans chaque ligne, recalculez les scores des types qu'une note de version touche, et comparez la table d'une version à l'autre avant que quoi que ce soit en aval ne la consomme.

Les adresses ne peuvent pas se joindre du tout. Le thème adresses embarque 474 millions de features dans la version 2026-09-23.1 et la documentation d'Overture le marque alpha, ce qui inclut l'absence d'identifiants GERS. Les enregistrements adressés, et la plupart des référentiels du commerce le sont, ne peuvent pas se résoudre comme les places. Rattachez-les plutôt par le bâtiment qui les abrite ou par la place la plus proche, gardez la chaîne d'adresse brute intacte pour l'audit, et revenez au thème quand les identifiants arriveront.

La fausse attache est le mode de défaillance discret. Une requête en rayon autour d'un centre commercial peut rendre une douzaine de candidats plausibles, et une ligne jointe à la mauvaise feature vaut pire qu'une ligne jointe à rien, parce que l'erreur se lit comme une vérité en aval, pour longtemps. Les colonnes sont la parade. score et reviewer_status sont obligatoires, et l'acceptation machine exige en plus une corroboration par signal dur comme un numéro de téléphone qui correspond. La file d'attente est une file avec un humain derrière, pas un dossier pour les lignes que l'on préfère ne pas regarder.

Les seuils se dégradent. Les catégories bougent, les chaînes ouvrent et ferment des magasins, et le composite qui était sûr à la version épinglée peut être faux à la suivante. Le versionnement de cache du premier mal couvre cela aussi, sur un calendrier : recalculez les scores à chaque ré-épinglage et laissez le diff, qui coûte une requête contre votre propre table, vous dire quelles lignes ont bougé.

La décision : garder les deux clés, versionner la table

Si votre plan de migration contient une étape nommée « jeter les identifiants OSM », coupez-la. Épinglez la version 2026-09-23.1, résolvez vos lignes en identifiants GERS par le flux ci-dessus, et laissez la table de jointure porter les deux espaces de clés avec un tampon de version et un statut de revue sur chaque ligne. Les identifiants sont stables par convention et bougent par notes de version, les adresses n'ont pas encore d'identifiants, et votre propre scoring est la pièce qui mérite le plus l'audit. Rien de tout cela ne plaide pour l'appariement par nom. Cela plaide pour des jointures avec reçus.

Les identifiants GERS ne remplacent pas vos clés. Ils leur donnent un endroit où atterrir.