
DuckDB permet d’interroger des fichiers Parquet locaux avec SQL sans les charger d’abord dans une base persistante. C’est utile pour un traitement de reporting sur une VM CPU : sélectionner les colonnes nécessaires, filtrer les lignes, calculer un résultat et écrire un fichier plus petit pour l’étape suivante.
Ce guide crée deux petits fichiers Parquet, récapitule les commandes payées par région et vérifie que l’export correspond au résultat de la requête. Il examine aussi un plan de requête et précise ce que ce plan ne prouve pas. Les exemples ont passé 18 vérifications sous Windows avec CPython 3.12.14 et DuckDB 2.0.0 le 12 novembre 2026. Il s’agit de vérifications de justesse, pas d’un benchmark sous Linux ou sur une VM Hivenet.
Dans cet exemple, DuckDB s’exécute dans le processus Python. Aucun serveur de base de données n’est à provisionner et l’analyse lit directement les fichiers Parquet. La connexion temporaire contient les données de travail ; les fichiers d’entrée et le résultat exporté restent sur disque après sa fermeture.
Cette approche convient à la vérification d’un export quotidien, à la réduction de fichiers d’événements en un rapport ou à la préparation d’un résultat analytique. Si votre objectif est plutôt un traitement reproductible qui charge des enregistrements dans PostgreSQL, notre guide ETL en Python, en anglais, couvre ce parcours différent.
Parquet organise les données par colonne. DuckDB peut transmettre la sélection des colonnes et certains filtres au lecteur Parquet, comme l’explique la documentation du lecteur, en anglais. Le travail réellement évité dépend des fichiers, de leurs métadonnées et de la requête. Un format de fichier ne garantit pas, à lui seul, un traitement rapide.
Utilisez Python 3.11 ou une version ultérieure dans un environnement virtuel activé, en suivant les prérequis Python de DuckDB, en anglais. Fixez la version pour reproduire l’exemple :
python -m pip install duckdb==2.0.0
Créez un dossier de travail et enregistrez-y les trois fichiers suivants : fixture.sql, summary.sql et run_demo.py. L’exemple nécessite uniquement DuckDB et la bibliothèque standard de Python. Il génère des données fictives localement, sans télécharger de données métier ni se connecter à un stockage cloud.
Enregistrez ce bloc dans fixture.sql. Les dix commandes comprennent deux montants inconnus, un véritable zéro et une commande annulée. Les montants utilisent un type décimal exact plutôt qu’un type à virgule flottante binaire. Les deux fichiers ont le même schéma.
CREATE TABLE orders_source (
order_id INTEGER, region VARCHAR,
amount DECIMAL(10, 2), status VARCHAR
);
INSERT INTO orders_source VALUES
(1, 'eu', 12.50, 'paid'),
(2, 'us', 20.00, 'paid'),
(3, 'eu', NULL, 'paid'),
(4, 'eu', 0.00, 'paid'),
(5, 'eu', 7.25, 'canceled'),
(6, 'eu', 30.00, 'paid'),
(7, 'us', 5.00, 'paid'),
(8, 'eu', 2.50, 'paid'),
(9, 'apac',9.00, 'paid'),
(10,'eu', NULL, 'paid');
COPY (SELECT * FROM orders_source WHERE order_id <= 5)
TO 'orders/part-1.parquet' (FORMAT PARQUET, COMPRESSION ZSTD);
COPY (SELECT * FROM orders_source WHERE order_id > 5)
TO 'orders/part-2.parquet' (FORMAT PARQUET, COMPRESSION ZSTD);
DROP TABLE orders_source;
La table source temporaire sert uniquement à générer les données fictives. Elle est supprimée avant l’analyse : la requête suivante doit donc lire les fichiers. Pour un traitement réel, vous partiriez de fichiers Parquet existants et sauteriez cette étape de génération.
Enregistrez ce bloc dans summary.sql. Le motif de fichiers combine les deux entrées, le filtre retire la commande annulée et le regroupement produit une ligne par région.
SELECT region,
count(*) AS paid_rows,
count(amount) AS known_amounts,
sum(amount) AS known_total
FROM read_parquet('orders/*.parquet')
WHERE status = 'paid'
GROUP BY region
ORDER BY region
count(*) compte toutes les lignes payées. count(amount) compte celles dont le montant est connu. sum(amount) additionne les montants connus. Cette distinction conserve la différence entre zéro et une donnée manquante, au lieu de transformer silencieusement un montant inconnu en zéro. Consultez la sémantique de NULL, en anglais, pour adapter la requête.
Le résultat est donc un total connu, sans garantie que tous les montants payés sont renseignés. Si tous les montants d’un groupe sont NULL, leur somme reste NULL. Décidez si cette situation doit faire échouer un rapport de production ou être signalée par un indicateur de complétude.
Enregistrez ce bloc dans run_demo.py. Il crée un nouveau dossier de sortie, exécute la génération et la requête, écrit summary.parquet, relit ce fichier et conserve le plan d’une requête plus ciblée.
import argparse
import os
from pathlib import Path
import duckdb
SOURCE = Path(__file__).resolve().parent
def main():
parser = argparse.ArgumentParser()
parser.add_argument("output", nargs="?", default="duckdb-parquet-demo")
args = parser.parse_args()
output = Path(args.output).resolve()
# Refuse an existing directory rather than overwrite its files.
output.mkdir()
os.chdir(output)
Path("orders").mkdir()
summary = (SOURCE / "summary.sql").read_text(encoding="utf-8").strip()
projection = """
SELECT order_id, amount
FROM read_parquet('orders/*.parquet')
WHERE region = 'eu' AND status = 'paid' AND amount >= 10
ORDER BY order_id
"""
with duckdb.connect(":memory:") as con:
con.execute((SOURCE / "fixture.sql").read_text(encoding="utf-8"))
rows = con.execute(summary).fetchall()
print("region | paid_rows | known_amounts | known_total")
for region, count, known, total in rows:
print(f"{region} | {count} | {known} | {total:.2f}")
con.execute(
"COPY (" + summary + ") TO 'summary.parquet' "
"(FORMAT PARQUET, COMPRESSION ZSTD)"
)
restored = con.execute(
"SELECT * FROM read_parquet('summary.parquet') ORDER BY region"
).fetchall()
if restored != rows:
raise RuntimeError("Export does not match the query result")
plan = con.execute("EXPLAIN " + projection).fetchone()[1]
Path("plan.txt").write_text(plan, encoding="utf-8")
print("Round trip: matched")
print("Filtered orders:", con.execute(projection).fetchall())
print("Saved: summary.parquet and plan.txt")
if __name__ == "__main__":
main()
Depuis le dossier contenant les trois fichiers, lancez :
python run_demo.py
Le script crée duckdb-parquet-demo dans le répertoire de travail courant. Il refuse de réutiliser un dossier de sortie existant : pour un second lancement, fournissez un nouveau nom comme argument positionnel. Il ne supprime ni ne remplace les fichiers d’une exécution précédente.
Sortie capturée dans l’environnement testé :
region | paid_rows | known_amounts | known_total
apac | 1 | 1 | 9.00
eu | 6 | 4 | 45.00
us | 2 | 2 | 25.00
Round trip: matched
Filtered orders: [(1, Decimal('12.50')), (6, Decimal('30.00'))]
Saved: summary.parquet and plan.txt
Le résultat EU contient six lignes payées, mais seulement quatre montants connus, pour un total de 45,00. Toutes régions confondues, on compte neuf lignes payées, sept montants connus et un total connu de 79,00. Ces valeurs ont été vérifiées indépendamment du résultat SQL. Les deux fichiers Parquet d’entrée sont également restés identiques, octet par octet, après l’analyse.
L’export utilise COPY TO, documenté en anglais, avec la compression Zstandard. Il est placé hors du dossier orders/, pour éviter que le prochain motif d’entrée lise le rapport comme un fichier source supplémentaire. Séparez les entrées brutes des sorties dérivées dans un traitement récurrent.
fetchall() est pratique pour ce rapport de trois lignes. Pour un résultat volumineux, exportez directement depuis la requête plutôt que de matérialiser toutes les lignes en objets Python uniquement pour les écrire.
Le script sélectionne aussi les identifiants et les montants des commandes EU payées d’au moins 10. Voici la sortie de son EXPLAIN :
╭─ Order By ────────────────╮
│ Order By: order_id ASC │
│ ~2 rows │
╰─────────────┬─────────────╯
╭─ Projection ┴─────────────╮
│ Projections: order_id, │
│ amount │
│ ~2 rows │
╰─────────────┬─────────────╯
╭─ Read Parquet ────────────╮
│ Function: READ_PARQUET │
│ Projections: amount, │
│ order_id │
│ Filters: region = 'eu', │
│ status = 'paid', │
│ amount >= 10.00 │
│ ~2 rows │
╰───────────────────────────╯
Le lecteur Parquet affiche les colonnes de sortie sélectionnées et les prédicats sur la région, le statut et le montant. Cela montre que le planificateur place ces prédicats dans la lecture. Ce n’est pas une mesure des octets évités, des groupes de lignes ignorés, du temps écoulé ou du gain apporté par un cœur CPU supplémentaire.
EXPLAIN, documenté en anglais, affiche le plan sans exécuter la requête ; son exécution séparée dans le script renvoie les commandes 1 et 6. Les nombres précédés d’un tilde restent des estimations, même lorsqu’ils correspondent aux données de cet exemple. Utilisez un profil d’exécution et des données représentatives avant d’affirmer un gain de performance.
Un motif de fichiers est pratique, mais il sélectionne ce qui correspond au moment de l’exécution. Pour un rapport reproductible, conservez la liste des fichiers d’entrée et contrôlez la fin de leur écriture par les producteurs. Inclure deux fois le même fichier peut compter ses lignes deux fois ; cela a été vérifié avec un autre petit jeu de données. SQL ne déduit pas que deux chemins représentent un doublon accidentel.
Examinez les schémas avant de combiner des exports. Si un nouveau fichier ajoute une colonne, union_by_name = true permet de réunir les colonnes par nom et de remplir une colonne absente avec NULL. Une vérification séparée a confirmé ce comportement. Cette option ne décide pas si un champ renommé conserve le même sens ni si des types incompatibles doivent être acceptés. Les conseils Parquet, en anglais, décrivent l’option et les compromis liés aux groupes de lignes.
Dans la configuration testée, le lecteur signale une erreur lorsque le motif ne correspond à aucun fichier. Gardez cet échec visible si une livraison vide rendrait le rapport trompeur. Une requête réussie sur les mauvais fichiers est plus difficile à détecter qu’une erreur explicite d’entrée manquante.
Une instance CPU de Compute with Hivenet peut héberger ce type d’analyse locale sans GPU. Considérez la VM comme un environnement où exécuter et mesurer la charge, sans supposer que toute collection de fichiers Parquet conviendra à une configuration donnée.
Commencez avec des fichiers de taille représentative et relevez le temps écoulé, le pic de mémoire du processus, l’espace disque temporaire et la taille du résultat. Gardez de la place pour le système, les entrées, la sortie et les traitements intermédiaires. Assurez-vous de pouvoir récupérer les données sources avant de faire du disque de la VM leur seule copie.
Le guide de réglage des charges DuckDB, en anglais, couvre le nombre de threads, les groupes de lignes et le recours au disque temporaire. Ajouter des threads n’améliore pas toujours une requête, et la prise en charge de volumes dépassant la mémoire ne garantit pas la réussite de toute combinaison de jointures et d’agrégats. Cet exemple ne teste ni le débordement sur disque ni la montée en charge CPU.
Pour le premier traitement de production, conservez un périmètre aussi précis : des entrées connues, des colonnes et des filtres explicites, un agrégat vérifié et un fichier de sortie séparé. Ajoutez la planification, le stockage objet distant ou une base en aval lorsque le besoin de reporting le justifie.
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.