Le schéma d'Overture se lit en un après-midi

La release 2026-09-23.1 d'Overture Maps a supprimé la colonne categories de chacune des 81 455 423 mentions de lieu du jeu de données. Tout pipeline qui la lisait a cessé de tourner le jour où la release est sortie. Les colonnes qui l'ont remplacée sont mieux conçues que celle qu'elles enterrent. La suppression ouvre néanmoins cette promenade dans le schéma, parce qu'elle fixe les règles du jeu avant le moindre nom de colonne. Overture est une donnée excellente, versionnée comme du logiciel, remous compris.

L'affirmation que ce billet entreprend de gagner : un ingénieur qui manie le SQL sans jamais avoir ouvert Overture peut lire, en un après-midi avec DuckDB, chaque colonne qui orientera une décision d'ingénierie. Nous avons lancé les requêtes ci-dessous le 11 octobre 2026, avec DuckDB 1.5.6 et ses extensions spatial et httpfs, contre la release 2026-09-23.1, et chaque chiffre de ce billet descend de cette exécution. Le schéma est bien plus grand que votre projet et bien plus plat qu'il n'y paraît. Une courte liste de noms de colonnes porte les décisions, le reste est une documentation que vous DESCRIBEz seulement quand un bug vous y envoie.

Épinglez l'ID de release, parce que les colonnes bougent

La suppression de categories en apporte la preuve, alors tirez la leçon opérationnelle avant la visite du schéma. L'identifiant de release vit dans votre chemin Parquet comme une chaîne littérale, et le garder là rend chaque décompte et chaque jointure reproductibles. Épingler ne coûte rien aujourd'hui et achète un diff connu demain, parce qu'Overture publie tous les mois et qu'une reconstruction dans six mois peut renommer une colonne que vous aviez réservée pour la vie. C'est l'argument que ce blog tenait en août au sujet des fournisseurs de cartographie : la couture qu'on construit avant d'en avoir besoin est celle qui tient. Quand un changement de schéma tombe quand même, la question la moins chère de votre boîte à outils s'appelle DESCRIBE. Elle demande à la couche de stockage ce qu'elle contient réellement :

DESCRIBE SELECT * FROM read_parquet(
  's3://overturemaps-us-west-2/release/2026-09-23.1/theme=places/type=place/*.parquet',
  hive_partitioning = 1
);

Passez cette commande une fois par type, pour la release que vous épinglez. Contre la release 2026-09-23.1, elle affiche 18 colonnes de premier niveau pour places, 24 pour buildings et 21 pour les segments de transportation. Ces trois tables sont celles où vivent la plupart des projets géo. Nous les prenons dans l'ordre, un exemple de ligne à la fois, en commençant par le thème que tout le monde ouvre d'abord.

Un lieu est joignable avant d'être fiable

Voici la ligne d'exemple de ce billet, un magasin de meubles au lac Tahoe. Le prédicat porte sur la structure bbox plutôt que sur la géométrie, si bien que la requête élimine des fichiers Parquet avant d'analyser quoi que ce soit :

SELECT
  id,
  names."primary"     AS name,
  taxonomy."primary"  AS category,
  confidence,
  websites
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
  AND names."primary" = 'Ashley Store';

Ce que la release 2026-09-23.1 a renvoyé :

colonne	valeur
id	e13e7209-a09a-4cf7-9d45-0532936fcc4c
name	Ashley Store
category	furniture_store
confidence	1.0

L'id est un UUID conçu pour rester d'une release à l'autre, et GERS est le mécanisme derrière cette promesse. Traitez-le comme la clé étrangère de tout votre projet : du lieu au bâtiment, ou de la release de ce mois à celle du mois précédent. confidence est le curseur de confiance. Un 1.0 est le maximum que la colonne offre. La longue traîne des lieux générés ou appariés par machine vit bien plus bas, et la ligne de rendu que vous choisissez reste une décision produit que le schéma ne truquera pas pour vous. names est une structure elle aussi, avec le libellé principal, un libellé common et des règles régionales.

taxonomy est la structure en laquelle la colonne categories s'est muée : une catégorie principale, une liste hierarchy d'ancêtres au-dessus d'elle et une liste alternates à côté. basic_category se tient à côté, et les deux vocabulaires ne sont pas interchangeables ; la dernière section de ce billet parle des lignes où la principale manque entièrement.

Les colonnes qui décident de ce que vous pouvez faire d'une ligne arrivent en tableaux. websites, emails, phones, socials et addresses sont toutes des listes, parce que des commerces réels publient plusieurs de chacune. brand porte une référence Wikidata plus des noms, si bien qu'une chaîne de franchises se replie en une seule identité sans appariement de chaînes. sources[] est le contrat juridique et de fraîcheur : chaque entrée porte une licence et un update_time. Les deux décident ensemble si vous avez le droit de republier la ligne, et à quel point elle est déjà périmée. operating_status ferme la boucle, parce qu'un magasin de meubles parfaitement fiable qui a baissé le rideau l'an dernier reste une mauvaise donnée sur votre carte.

La hauteur transforme les bâtiments en jeu de données

Le même rectangle du Tahoe contient 228 935 polygones de bâtiments dans la release 2026-09-23.1, et les compter a pris 37,1 secondes à notre exécution. Ce chrono est l'astuce discrète du schéma. Le prédicat a couru sur la colonne structurelle bbox, qui élague des groupes de lignes du Parquet avant que la moindre géométrie soit analysée. Filtrez sur bbox et laissez geometry tranquille, et la plupart de vos requêtes Overture héritent de la même vitesse.

La structure verticale est ce qui mue ces polygones en matière d'ingénierie. height et min_height alimentent l'extrusion et le travail d'ombre. num_floors et is_underground couvrent les bâtiments qui publient des étages sans mètres. Quand un décompte d'étages existe sans hauteur, nous bouchons le trou à trois mètres par étage, une heuristique que nos propres commentaires de code assument. subtype et class portent la classification, et la liste des classes continue de s'allonger. La release 2026-09-23.1 a ajouté une classe shelter, selon les notes de version.

Les moteurs de rendu reçoivent leur propre contrat dans les attributs de façade et de toit : facade_color, facade_material, roof_shape, roof_material, roof_orientation, roof_height, et leurs voisins. Les pipelines qui ne transportent que de la géométrie peuvent tous les ignorer. Cette asymétrie est l'argument du DESCRIBE d'abord : ne chargez que les colonnes que votre charge de travail paie, et sautez le contrat de style si personne ne rend.

Les segments portent des règles, pas seulement des formes

106 242 segments de transportation occupaient le même rectangle, et ce décompte est revenu en 18,0 secondes. Si places est le thème que l'on essaie d'abord, segments est celui qui change l'architecture. Un segment enregistre ce que le trafic a le droit de faire avec un bout de route, pas seulement où la route se trouve.

subclass et subclass_rules se lisent ensemble. La subclass nomme le genre de route, et les règles accrochent des conditions à ce genre, avec des entrées value et between qui bornent là où chacune s'applique. Les speed_limits arrivent en paires min/max avec une unité explicite, donc aucune chaîne d'outils n'improvise une conversion. access_restrictions décide de qui peut aller où. road_surface et road_flags décrivent l'état physique et administratif de la chaussée. routes porte l'appartenance signée à des réseaux (name, network, ref) pour les écussons, et destinations garde la signalétique qu'un routeur devrait répéter à une sortie.

La géométrie attend au bas de la liste des colonnes, et c'est la seule partie que le nom du thème laissait deviner. Tout ce qui est au-dessus est une table de règles.

896 lieux du Tahoe sans catégorie principale, et votre code doit s'y attendre

Voici la limite promise. Parmi les 28 166 lieux que notre filtre bbox a renvoyés de la release 2026-09-23.1, 896 n'ont aucune taxonomy."primary" du tout, 3,2 % de l'échantillon. Le code qui lit la principale suppose que NULL veut dire « commerce non classé », alors qu'il veut dire « colonne absente ». Une colonne absente empoisonne les filtres en aval en silence. Écrivez le repli avant que la première jointure ne fasse confiance à une catégorie :

SELECT
  id,
  COALESCE(taxonomy."primary", basic_category) AS category
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;

Le repli fonctionne parce que basic_category est renseignée sur ces lignes, mais c'est un vocabulaire différent, alors notez quelle colonne a nourri chaque résultat et gardez vos agrégats par catégorie capables de le dire. L'équité coupe dans l'autre sens aussi : 3,2 %, c'est un rectangle d'une seule release. Mesurez votre propre part avant d'hériter de la nôtre.

Deux limites de plus que nous épinglons plutôt que de taire. Le thème addresses porte encore un drapeau alpha dans la documentation, et ses 474 millions de features n'ont pas encore d'identifiants GERS, si bien que le travail d'adressage ne devrait pas s'y ancrer. Et le changement de génération des UUID au sein de cette même release a fait bouger certains identifiants building_part, selon les notes de version. Chaque montée de release revérifie donc vos jointures contre les nouveaux IDs.

L'après-midi, dans l'ordre

Si vous démarrez un pipeline Overture ce trimestre, voici l'ordre que nous adopterions. Épinglez l'identifiant de release littéral dans chaque chemin Parquet. DESCRIBEz les trois types avant d'écrire le premier SELECT. Placez le COALESCE entre la taxonomy et chaque consommateur dès le premier jour. Stockez l'identifiant de release à côté de chaque ligne que vous persistez.

Rien de tout cela n'est une connaissance profonde d'Overture. Tout tient dans un après-midi, et Overture publie un exemple build-a-map qui occupe votre deuxième heure, de la requête DuckDB aux tuiles tippecanoe jusqu'à une carte MapLibre.

Le schéma n'est pas la partie difficile d'un projet Overture. Le lire trop tard l'est.

AngoraTek accompagne les équipes qui chargent les releases d'Overture et survivent à leurs changements de schéma. [Écrivez-nous](/fr/#contact) si votre pipeline aurait dû lire taxonomy en septembre.