
L’évolution des schémas consiste à faire changer la structure d’un jeu de données de manière contrôlée, à mesure que ses producteurs et ses consommateurs évoluent. Ajouter un champ, renommer une colonne ou modifier un type peut affecter un lecteur qui attend encore les données d’hier. L’objectif est de préserver les contrats que vous souhaitez prendre en charge et de rendre explicites les changements incompatibles.
Un fichier qui s’ouvre sans erreur peut tout de même produire un résultat faux. Dans l’exemple ci-dessous, un lecteur combine deux fichiers Parquet après le renommage d’une colonne de montant. La requête réussit, mais son total omet la moitié du montant attendu. Des contrôles explicites côté consommateur détectent le changement avant ce calcul.
Ce guide porte sur les jeux de données constitués de fichiers. Il utilise DuckDB pour tester d’anciens et de nouveaux lecteurs avec de petits fichiers Parquet, puis explique comment ces contrôles orientent une mise en service. Les mêmes questions se posent dans les flux d’événements et les bases de données, même si leurs mécanismes de compatibilité diffèrent.
Un contrat de données utile décrit les noms, les types, les valeurs requises, les identifiants, les unités et le sens des données manquantes. Il identifie aussi le producteur et les consommateurs qui doivent continuer à fonctionner. Une version de schéma désigne un contrat documenté ; une simple étiquette de version ne rend pas un changement compatible.
Notre exemple comporte une chaîne order_id et un entier cents. Le contrat précise que les montants sont exprimés en centimes de dollar américain, positifs ou nuls, et que les identifiants sont non vides et uniques dans chaque fichier d’entrée. La deuxième version ajoute une chaîne nullable region. Pour un ancien fichier sans ce champ, le nouveau lecteur renvoie NULL, qui signifie ici « indisponible ». Il n’invente pas de région et n’assimile pas une donnée manquante à une chaîne vide.
La compatibilité sémantique nécessite un examen distinct. Si la valeur 100 passe de « 100 centimes » à « 100 dollars », son nom et son type entier peuvent rester identiques tandis que le rapport devient faux. Ni un contrôle de type ni une conversion réussie ne permettent de découvrir l’unité voulue par le producteur.
Selon les directions décrites dans la documentation de compatibilité de Confluent, la compatibilité descendante signifie qu’un nouveau lecteur peut consommer d’anciennes données ; la compatibilité ascendante signifie qu’un ancien lecteur peut consommer de nouvelles données. La compatibilité complète exige les deux. Les règles détaillées dépendent du format et de la politique du lecteur.
Dans cet exemple, l’ancien lecteur ne sélectionne que les deux champs d’origine. Le nouveau gère explicitement l’absence de région. Ces choix donnent la matrice suivante :
| Lecteur | Fichier | Comportement observé |
|---|---|---|
| Ancien lecteur | Schéma d’origine | Lit l’identifiant et le montant en centimes |
| Ancien lecteur | Région nullable ajoutée | Ignore la région et lit ses champs requis |
| Nouveau lecteur | Schéma d’origine | Fournit NULL pour la région absente |
| Nouveau lecteur | Région nullable ajoutée | Lit la région, y compris un NULL explicite |
Cela ne signifie pas que tout ajout de champ facultatif est universellement compatible. Un consommateur qui rejette les champs inconnus, utilise la position des colonnes ou exige une région renseignée a d’autres besoins. Testez les lecteurs réellement exploités. Si vous conservez de nombreuses versions historiques, ne vérifier que la version immédiatement précédente laisse aussi les données plus anciennes sans contrôle.
Vérifié le 17 novembre 2026 : la démonstration et 18 tests locaux ont réussi sous Windows avec Python 3.12.14 et DuckDB 2.0.0. Ils couvrent les projections explicites, les deux sens de compatibilité, l’ordre des champs, le renommage, la suppression, les types, les valeurs manquantes, les identifiants répétés, la combinaison de fichiers et la conservation des octets d’entrée. Aucun stockage distant, registre de schémas, moteur de format de table, déploiement ou test de performance n’a été utilisé.
Dans un nouvel environnement virtuel Python 3.12, installez la version indiquée du paquet :
python -m pip install duckdb==2.0.0
Enregistrez le code suivant dans schema_demo.py. Il crée des fichiers de test synthétiques maîtrisés dans un dossier temporaire, puis les supprime à la fin. L’interface Parquet de DuckDB écrit les fichiers, inspecte leurs types et lit les colonnes par leur nom. Les chemins de fichiers sont passés comme paramètres ; le seul mappage de champ repose sur une liste explicite de noms autorisés.
"""Local Parquet compatibility lab using trusted, synthetic fixtures."""
from pathlib import Path
from tempfile import TemporaryDirectory
import duckdb
def write_fixture(connection, path, query):
if path.exists():
raise FileExistsError(path)
connection.sql(query).write_parquet(str(path))
def fixtures(connection, root):
queries = {
"v1": """SELECT * FROM (VALUES
('a', 1200::BIGINT), ('b', 800::BIGINT)) t(order_id, cents)""",
"v2": """SELECT * FROM (VALUES
('c', 1500::BIGINT, 'CH'), ('d', 500::BIGINT, NULL))
t(order_id, cents, region)""",
"reordered": """SELECT region, cents, order_id FROM (VALUES
('c', 1500::BIGINT, 'CH'), ('d', 500::BIGINT, NULL))
t(order_id, cents, region)""",
"renamed": """SELECT * FROM (VALUES
('c', 1500::BIGINT, 'CH'), ('d', 500::BIGINT, NULL))
t(order_id, amount_minor, region)""",
"text_amount": "SELECT 'c' AS order_id, '1500' AS cents",
"removed": "SELECT 'c' AS order_id",
}
paths = {name: root / (name + ".parquet") for name in queries}
for name, query in queries.items():
write_fixture(connection, paths[name], query)
return paths
def read_orders(connection, path, with_region=False, value_column="cents"):
"""Example consumer policy, not a general schema compatibility checker."""
if value_column not in {"cents", "amount_minor"}:
raise ValueError("unsupported field mapping")
description = connection.execute(
"DESCRIBE SELECT * FROM read_parquet(?)", [str(path)]).fetchall()
types = {row[0]: row[1] for row in description}
required = {"order_id": "VARCHAR", value_column: "BIGINT"}
if any(types.get(name) != kind for name, kind in required.items()):
raise ValueError("required field missing or type differs")
region = ""
if with_region:
if "region" in types and types["region"] != "VARCHAR":
raise ValueError("region must be VARCHAR when present")
region = ", region" if "region" in types else ", NULL::VARCHAR AS region"
# Only allowlisted identifiers enter this SQL. File paths are bound values.
rows = connection.execute(
f'SELECT order_id, "{value_column}" AS cents{region} '
'FROM read_parquet(?) ORDER BY order_id', [str(path)]).fetchall()
seen = set()
for row in rows:
key, cents = row[:2]
if not key or key in seen or cents is None or cents < 0:
raise ValueError("invalid order ID or amount")
seen.add(key)
return rows
def main():
with TemporaryDirectory(prefix="schema-lab-") as temp:
connection = duckdb.connect()
try:
paths = fixtures(connection, Path(temp))
assert read_orders(connection, paths["v2"]) == [("c", 1500), ("d", 500)]
legacy = read_orders(connection, paths["v1"], with_region=True)
assert legacy == [("a", 1200, None), ("b", 800, None)]
print("Old reader + added field: accepted")
print("New reader + old file: region is NULL")
for name in ["renamed", "text_amount", "removed"]:
try:
read_orders(connection, paths[name])
except ValueError:
print(f"Old reader + {name}: rejected")
else:
raise AssertionError("expected a contract rejection")
adapted = read_orders(connection, paths["renamed"], True, "amount_minor")
assert adapted == [("c", 1500, "CH"), ("d", 500, None)]
print("Explicit rename adapter: accepted")
# A successful union can still hide a missing required value.
mixed = connection.execute(
"SELECT order_id, cents, amount_minor FROM read_parquet(?, "
"union_by_name=true) ORDER BY order_id",
[[str(paths["v1"]), str(paths["renamed"])]],
).fetchall()
assert mixed == [("a", 1200, None), ("b", 800, None),
("c", None, 1500), ("d", None, 500)]
subtotal = connection.execute(
"SELECT sum(cents) FROM read_parquet(?, union_by_name=true)",
[[str(paths["v1"]), str(paths["renamed"])]],
).fetchone()[0]
assert subtotal == 2000
print(f"Naive mixed-file SUM(cents): {subtotal}; intended total: 4000")
finally:
connection.close()
if __name__ == "__main__":
main()
Lancez-le avec :
python schema_demo.py
Voici la sortie observée :
Old reader + added field: accepted
New reader + old file: region is NULL
Old reader + renamed: rejected
Old reader + text_amount: rejected
Old reader + removed: rejected
Explicit rename adapter: accepted
Naive mixed-file SUM(cents): 2000; intended total: 4000
Les deux versions de fichiers contiennent des identifiants de commande différents, ce qui permet aussi de les utiliser comme deux lots dans l’expérience de combinaison. Chaque lot totalise 2 000 centimes. Les autres fichiers isolent un changement d’ordre, un renommage, un montant stocké en texte et la suppression d’un champ. Ce sont des variations contrôlées, pas une migration de données métier réelles.
Le lecteur applique une politique applicative volontairement limitée : les identifiants doivent être de type VARCHAR et les montants de type BIGINT. Il rejette la chaîne "1500", même si une conversion distincte pourrait la convertir en nombre. Une colonne INTEGER nécessiterait aussi une modification explicite de la politique. Ce choix empêche une conversion automatique de décider silencieusement du contrat, mais il est plus strict que certains lecteurs valides.
L’exemple charge ces petits résultats en mémoire et vérifie l’unicité dans un seul fichier. Il ne contrôle pas l’unicité à l’échelle d’un jeu de données entier et ne traite pas de grandes entrées de façon progressive. Adaptez ces limites à votre charge avant d’utiliser le lecteur comme traitement de validation en production.
| Changement | Ce que l’exemple établit | Décision avant mise en service |
|---|---|---|
| Ajouter une région nullable | Les deux lecteurs fonctionnent selon leurs politiques explicites | Convenir du sens d’une région manquante |
| Réordonner les colonnes | Les projections nommées préservent les valeurs et l’ordre de sortie | Vérifier séparément les consommateurs qui utilisent les positions |
| Renommer cents | Les deux lecteurs rejettent l’absence du nom d’origine | Utiliser un adaptateur lié à la version ou migrer les consommateurs |
| Supprimer un champ requis | Le lecteur rejette le fichier | Conserver le champ ou introduire un contrat incompatible |
| Stocker les montants en texte | La politique de type exact les rejette | Définir les règles de conversion et de rejet avant le changement |
| Changer d’unité sans modifier le schéma | La validation structurelle ne détecte pas le sens voulu | Examiner la sémantique et rapprocher des résultats représentatifs |
L’adaptateur de renommage associe amount_minor au champ de sortie cents du lecteur. Ce mappage est valable ici parce que le fichier conserve le sens « centimes de dollar américain ». Il serait incorrect si le nouveau champ contenait une autre devise ou unité. Si une transition écrit temporairement les deux noms, définissez lequel fait autorité et rejetez les désaccords plutôt que de choisir la première valeur disponible.
La nullabilité demande la même attention. Un champ nullable autorise les valeurs manquantes ; une valeur par défaut fournit une valeur choisie selon une règle définie. Remplacer tous les montants absents par zéro peut transformer des données incomplètes en rapport plausible mais faux. L’exemple rejette NULL dans son champ de montant requis.
L’option union_by_name de DuckDB réunit les noms de colonnes des fichiers et remplit les champs absents avec NULL. Dans l’expérience de renommage, cents et amount_minor deviennent deux colonnes distinctes. Le nouveau lot contient donc NULL dans cents, bien que ses montants existent sous l’autre nom.
La requête renvoie les quatre lignes. Cependant, SUM ignore les valeurs NULL : SUM(cents) renvoie donc 2 000 au lieu des 4 000 attendus. Un contrôle du nombre de lignes réussirait. La vérification des valeurs requises et le rapprochement avec un total attendu indépendant révèlent le problème.
Validez chaque entrée selon sa version déclarée avant de la combiner. Lorsqu’une migration nécessite un adaptateur, appliquez-le explicitement et contrôlez son résultat. Évitez un motif de fichiers trop large qui mélange discrètement anciennes et nouvelles données, sorties partielles ou fichiers abandonnés. L’exemple fournit une liste exacte de fichiers pour rendre visibles les entrées de l’expérience.
Pour un changement additif, il est souvent possible de mettre à jour les lecteurs d’abord, afin qu’ils acceptent anciennes et nouvelles données, puis les producteurs qui émettent le nouveau champ. Confirmez cet ordre avec la matrice de compatibilité au lieu de supposer qu’il convient à tout changement.
Revenir en arrière ne consiste pas toujours à rétablir le code précédent. Si un producteur a déjà écrit des données qu’un ancien lecteur ne comprend pas, ne restaurer que ce lecteur peut aggraver l’incident. Testez si la reprise exige de sélectionner un ancien jeu de données, d’appliquer un adaptateur ou de réparer les nouvelles sorties. Pour les reprises historiques, consignez l’intervalle et la version source, puis rapprochez les données reconstruites avant de remplacer une livraison existante.
Un registre de schémas peut enregistrer les versions et vérifier des règles de compatibilité configurées pour les formats de messages pris en charge. Il ne remplace pas les contrôles métier portant sur la devise, l’unicité ou le total attendu d’un rapport. La source Confluent citée plus haut décrit les règles d’un registre ; ce laboratoire n’en utilise pas.
Un format de table ajoute une autre couche. Apache Iceberg, par exemple, suit les colonnes au moyen d’identifiants uniques et gère les modifications de schéma prises en charge dans les métadonnées de la table. Lire directement une collection de fichiers Parquet par nom n’applique pas automatiquement les règles d’évolution de cette table. Utilisez un lecteur compatible lorsque vous dépendez de ses métadonnées. Aucun comportement Iceberg n’a été testé ici.
Les bases de données ont leurs propres contraintes de migration et de réplication. La réplication logique PostgreSQL ne réplique pas les commandes DDL : la coordination des schémas reste donc un travail distinct. Le guide de réplication logique PostgreSQL traite ce cas propre à la base de données. Placez la validation au niveau où vos producteurs et consommateurs échangent réellement leurs données.
Compute avec Hivenet fournit une infrastructure CPU pour les traitements de validation et de transformation exploités par le client. Le stockage objet avec Hivenet fournit un stockage compatible S3 pour les jeux de données terminés et leurs fichiers associés. Les règles de schéma, les manifestes, les migrations des lecteurs et la coordination des livraisons restent dans votre application.
Pour choisir l’infrastructure, réunissez un jeu de données représentatif, les versions de lecteurs prises en charge, les contrôles attendus, la fréquence de livraison et les besoins de conservation. Mesurez la mémoire et la durée de validation, puis testez l’envoi réel et la mise à disposition des fichiers aux lecteurs. L’exemple local démontre les comportements indiqués sur les fichiers ; il ne valide pas un déploiement cloud et ne suppose pas qu’un bucket compatible S3 fournisse un registre de schémas ou une couche de tables transactionnelles.
Choisissez une charge de travail d’IA, de calcul ou de stockage à tester sur Hivenet, ou échangez avec notre équipe sur sa mise en production.