Aller au contenu

Premier Notebook

Ce guide vous accompagne dans l'exécution du notebook de démo bancaire AKKO, qui crée des tables Iceberg, génère des données synthétiques et démontre la fédération Trino.

Ouvrir JupyterHub

  1. Rendez-vous sur https://lab.akko.local
  2. Connectez-vous en tant qu'alice (alice123)
  3. Attendez que votre serveur notebook démarre (environ 30 secondes la première fois)

Ouvrir la Démo Bancaire

Dans l'explorateur de fichiers JupyterLab, naviguez vers :

notebooks/getting-started/01-akko-banking-demo.ipynb

Les notebooks sont en lecture seule

Le répertoire notebooks/ est monté en lecture seule depuis l'hôte. Pour modifier un notebook, copiez-le d'abord dans votre répertoire personnel :

!cp notebooks/getting-started/01-akko-banking-demo.ipynb ~/my-banking-demo.ipynb

Puis ouvrez la copie depuis votre répertoire personnel.

Ce que Fait le Notebook

La démo bancaire simule une banque de détail avec 5 agences françaises, 200 clients et 1 000 transactions. Elle sollicite l'ensemble de la pile AKKO dans un seul notebook :

Étape 1 -- Session Spark Connect

Se connecte à Spark via le protocole gRPC (sc://spark-connect:15002). Il s'agit d'une session Spark distante -- aucune installation Spark locale n'est nécessaire. Le notebook crée le namespace iceberg.analytics.

spark = SparkSession.builder \
    .remote("sc://spark-connect:15002") \
    .getOrCreate()

Étape 2 -- Créer les Tables Iceberg

Quatre tables sont créées dans le namespace iceberg.analytics, stockées au format Iceberg sur object storage (stockage objet compatible S3), avec le catalogue géré par Apache Polaris :

Table Lignes Partitionnée Par Description
advisors 15 -- Conseillers bancaires avec spécialité et agence
customers 200 segment Clients (particulier, entreprise, premium)
accounts ~350 account_type Comptes courant, épargne, investissement
transactions 1000 months(transaction_date) 6 mois d'opérations carte, virement, dépôt

Étape 3 -- Vérifier les Données

Le notebook affiche le nombre de lignes pour les quatre tables et montre un échantillon de données pour chacune.

Étape 4 -- Voyage dans le Temps Iceberg

Démontre l'historique des snapshots Iceberg. Chaque INSERT crée un nouveau snapshot, et vous pouvez interroger n'importe quelle version historique des données :

SELECT snapshot_id, committed_at, operation
FROM iceberg.analytics.transactions.snapshots
ORDER BY committed_at

Limitation Spark Connect

Les tables de métadonnées Iceberg (comme .snapshots) doivent être interrogées avec .show() au lieu de .collect() en mode Spark Connect, en raison d'un problème de sérialisation SerializedLambda.

Étape 5 -- Fédération Trino

La requête phare : une jointure fédérée sur deux sources de données différentes dans une seule instruction SQL :

  • Tables Iceberg (customers, accounts, transactions) stockées sur object storage
  • Table PostGIS (agences avec coordonnées géospatiales) stockée dans PostgreSQL
SELECT
    b.name AS branch, b.city,
    COUNT(DISTINCT c.customer_id) AS customer_count,
    COUNT(t.transaction_id) AS transaction_count,
    ROUND(SUM(ABS(t.amount)), 2) AS total_volume
FROM postgresql.geospatial.branches b
JOIN iceberg.analytics.customers c ON c.branch_id = b.id
JOIN iceberg.analytics.accounts a ON a.customer_id = c.customer_id
JOIN iceberg.analytics.transactions t ON t.account_id = a.account_id
WHERE a.status = 'active'
GROUP BY b.name, b.city
ORDER BY total_volume DESC

Cette requête est exécutée par Trino, qui fédère de manière transparente le catalogue Iceberg (via Polaris REST) et le catalogue PostgreSQL.

Étape 6 -- Requêtes SQL pour Superset

Le notebook affiche des requêtes SQL prêtes à l'emploi que vous pouvez coller dans le SQL Lab de Superset, incluant des KPI, des ventilations mensuelles du volume, des catégories de dépenses, et la requête fédérée de revenus par agence.

Exécuter Cellule par Cellule

Sélectionnez la première cellule et appuyez sur ++shift+enter++ pour l'exécuter. Continuez à travers chaque cellule dans l'ordre. L'ensemble du notebook prend environ 2 à 3 minutes à compléter.

Exécutez les cellules dans l'ordre

Chaque cellule dépend des précédentes. Ne sautez pas de cellules et ne les exécutez pas dans le désordre, car les cellules suivantes font référence aux tables créées par les cellules précédentes.

Résultat attendu à l'étape de vérification :

========================================
  AKKO Banking -- Iceberg Tables
========================================
  advisors             :     15 rows
  customers            :    200 rows
  accounts             :   ~350 rows
  transactions         :   1000 rows
========================================

Après l'Exécution du Notebook

Une fois le notebook terminé avec succès, les données sont disponibles partout dans la plateforme :

  • Trino -- Interrogez les tables iceberg.analytics.* via l'interface Trino ou n'importe quel client SQL
  • Superset -- Le tableau de bord auto-provisionné affiche désormais des données en direct. Rendez-vous dans Dashboards > AKKO Banking Overview et rafraîchissez
  • Autres notebooks -- Tous les notebooks qui interrogent iceberg.analytics.* verront les données
  • OpenMetadata -- Si le profil governance est actif, le catalogue peut ingérer ces tables pour la gestion des métadonnées

Récapitulatif de l'Architecture

  Notebook (Spark Connect)         PostgreSQL
         |                        +--------------------+
         | gRPC :15002            | geospatial         |
         v                        |   .branches (5)    |
  Spark Connect --> Polaris       +--------+-----------+
         |              |                  |
         v              v                  |
       object storage (S3)                          |
    +---------------+                      |
    |  analytics     |                     |
    |  .advisors     |                     |
    |  .customers    |                     |
    |  .accounts     |                     |
    |  .transactions |                     |
    +------+---------+                     |
           |                               |
    +------v-------------------------------v--+
    |              TRINO (fédération)          |
    +------------------+-----------------------+
                       |
                +------v------+
                |   SUPERSET  |
                |  Tableau de |
                |    bord     |
                +-------------+

Explorer les Autres Notebooks

AKKO est livré avec 14 notebooks organisés par catégorie. Après avoir terminé la démo bancaire, essayez ceux-ci :

Premiers Pas

# Notebook Description
01 akko-banking-demo Modèle de données bancaire, Spark Connect, fédération Trino (ce guide)
03 spark-iceberg-demo Exploration approfondie des fonctionnalités Iceberg (évolution de schéma, partitionnement, voyage dans le temps)

IA

# Notebook Description
02 rag-pipeline-demo Pipeline RAG avec Ollama, pgvector et LangChain
13 akko-jupyter-ai-demo Intégration Jupyter AI avec des LLM locaux via Ollama

Analytique

# Notebook Description
04 akko-duckdb-analytics Analytique en processus avec DuckDB sur des données Iceberg
07 akko-r-analytics Kernel R : analytique tidyverse sur les données bancaires
08 akko-julia-dataframes Kernel Julia : DataFrames.jl sur les données bancaires
11 akko-polars-analytics Bibliothèque DataFrame Polars pour l'analytique rapide

Ingénierie

# Notebook Description
05 akko-dbt-transforms Transformations dbt sur les tables Iceberg
06 akko-data-quality Contrôles et validation de la qualité des données
10 akko-polaris-catalog-admin Administration du catalogue Polaris via l'API REST

Visualisation

# Notebook Description
09 akko-geospatial-analysis Analyse géospatiale PostGIS avec les localisations d'agences
12 akko-altair-visualization Graphiques interactifs Altair/Vega

Rapports

Fichier Description
04-akko-banking-report.qmd Rapport Quarto rendu en HTML, servi à https://docs.akko.local/reports/

Numérotation des notebooks

Les notebooks sont numérotés dans l'ordre de lecture suggéré. Commencez par le 01 (ce guide), puis essayez le 02 (RAG) ou le 03 (exploration approfondie d'Iceberg) selon vos intérêts.

Prochaines Étapes