DataWorks:Utiliser les tables dynamiques Hologres

Étape 1 : Préparer les données sources

Préparez une table source dans votre base de données Hologres. Exécutez les instructions SQL suivantes pour créer une table de commandes nommée orders et insérer des données initiales :

-- Create the source table and enable Binlog to support incremental refresh
CREATE TABLE orders (
    order_id INT PRIMARY KEY,
    user_id INT,
    user_name TEXT,
    price FLOAT,
    order_time TIMESTAMPTZ
) WITH (
    binlog_level = 'replica', -- Key setting: enable Binlog
    binlog_ttl = '86400'      -- Binlog retention period in seconds, for example, one day
);
-- Insert initial data
INSERT INTO orders VALUES 
(1, 101, 'Alice', 99.9, NOW()),
(2, 102, 'Bob', 19.5, NOW()),
(3, 101, 'Alice', 25.0, NOW());

Étape 2 : Accéder à la page de création de table dynamique

Accédez à la page de création de table dynamique pour la base de données Hologres cible. Pour plus d'informations, reportez-vous à la section Accéder à la page de création de table dynamique.

Étape 3 : Définir la logique de requête et exécuter la précompilation

1. Saisissez les informations de base :

   • Dynamic table name : Entrez un nom de table unique, par exemple dt_user_orders_agg.

   • Description : Indiquez l'objectif de la table, par exemple « Statistiques de commandes agrégées par utilisateur ».

2. Dans la section Field Information, sous l'onglet Data Generation SQL, rédigez la requête SELECT qui définit la logique des données de la table dynamique :

   SELECT 
       user_id,
       user_name,
       COUNT(*) AS order_count,
       SUM(price) AS total_price
   FROM public.orders
   GROUP BY user_id, user_name;

   Remarque

   Saisissez uniquement l'instruction SELECT. Vous n'avez pas besoin d'inclure la commande DDL CREATE DYNAMIC TABLE. Le système analyse l'instruction DDL complète à partir de votre configuration et l'affiche dans la zone DDL à droite.

3. Cliquez sur Precompile au-dessus de l'éditeur SQL.

   La précompilation est une étape obligatoire. Une fois la précompilation réussie, le système liste les modes d'actualisation pris en charge et analyse les colonnes de sortie de la table dynamique. En cas d'échec, le système renvoie la cause spécifique. Modifiez l'instruction SQL selon le message affiché, puis relancez la précompilation. Pour savoir ce que vérifie la précompilation et comment interpréter son résultat, consultez la section Annexe : référence de configuration.

4. (Facultatif) Cliquez sur l'onglet Field Details pour afficher toutes les colonnes, leurs types de données et leurs propriétés de non-nullité analysées par le système. Ajoutez un commentaire pour chaque colonne dans la colonne Description afin de faciliter la lecture des métadonnées.

Pour cet exemple, l'onglet Field Details affiche quatre colonnes : user_id (entier), user_name (texte), order_count (bigint) et total_price (double precision). Toutes les colonnes sont non nulles.

Cet exemple n'utilise ni les paramètres de partitionnement ni les paramètres avancés. Pour une description des paramètres, consultez la section Annexe : référence de configuration.

Étape 4 : Configurer la politique d'actualisation des données

Une fois la précompilation réussie, le panneau Refresh Policy situé à droite de la page devient modifiable.

Sélectionnez la politique d'actualisation adaptée à votre scénario. Auto-Refresh est l'option par défaut recommandée lorsque vous n'avez pas besoin d'imposer un mode d'actualisation spécifique. Incremental Refresh force exclusivement l'actualisation incrémentielle, tandis que Full Refresh s'applique lorsque la table source ne possède ni clé primaire ni Binlog. Cet exemple utilise Incremental Refresh car le scénario exige une synchronisation des données à faible latence.

Pour une description complète de chaque paramètre, consultez les sections Annexe : référence de configuration et Modes d'actualisation et ressources Hologres.

• Basic Parameters :

  • Table Type : Comme aucune colonne de partition n'est sélectionnée, le système identifie la table comme une Non-Partitioned Table.

  • Refresh Policy : Sélectionnez Incremental Refresh.

  • Refresh trigger method : Conservez l'option Hologres auto refresh, qui est la seule valeur prise en charge.

  • Automatically Refresh Data : Conservez la valeur par défaut Yes.

  • Data Freshness : Définissez ce paramètre sur 5 minutes. La latence de la table dynamique par rapport à la table source restera ainsi toujours inférieure à 5 minutes.

  • Base Table Consumption Mode for Incremental Refresh : Sélectionnez stream.

  • Hologres computing resources : Sélectionnez Serverless resources afin que les tâches d'actualisation ne consomment pas les ressources de votre propre instance.

• Advanced Parameters (facultatif) : Conservez les valeurs par défaut dans cet exemple. Pour définir des paramètres GUC spécifiques, consultez la rubrique Paramètres GUC.

Étape 5 : Publier la table dynamique

1. Après avoir confirmé que toutes les configurations sont correctes, cliquez sur Publish en haut de la page.

2. Dans la boîte de dialogue de confirmation qui s'affiche, cliquez à nouveau sur Publish.

La table dynamique Hologres est créée et publiée. Lorsque des données sont insérées ou mises à jour dans la table source orders, la table dynamique dt_user_orders_agg met à jour ses résultats agrégés en environ 5 minutes.

Étape 6 : Vérifier l'actualisation

Insérez ou mettez à jour des lignes dans la table source orders. Une fois la fenêtre de fraîcheur des données configurée de 5 minutes écoulée, interrogez la table dt_user_orders_agg. Les résultats agrégés incluent les nouvelles données. Pour vérifier si les tâches d'actualisation s'exécutent comme prévu, consultez la section Afficher et surveiller les tables dynamiques.

Étape 1 : Préparer les données sources

Créez une table source nommée users qui enregistre les informations d'inscription des utilisateurs. La table doit contenir une colonne d'horodatage pour servir de base au partitionnement.

-- Create the user registration table and enable Binlog
CREATE TABLE users (
    user_id INT PRIMARY KEY,
    user_name TEXT,
    region TEXT,
    registration_time TIMESTAMPTZ  -- User registration time, of the TIMESTAMPTZ type
) WITH (
    binlog_level = 'replica',
    binlog_ttl = '86400'
);
-- Insert test data. Replace the dates with the current data timestamp.
INSERT INTO users VALUES 
(1, 'Alice', 'CN-Hangzhou', '2026-02-27 10:00:00+08'),
(2, 'Bob', 'CN-Shanghai', '2026-02-27 14:30:00+08'),
(3, 'Charlie', 'CN-Beijing', (NOW() - INTERVAL '1 day')::TIMESTAMPTZ);

Dans ces données d'exemple, Alice et Bob sont inscrits à la date actuelle, tandis que Charlie s'est inscrit la veille. Ces deux dates d'inscription illustrent la répartition des enregistrements entre les partitions journalières.

Étape 2 : Accéder à la page de création de table dynamique

Accédez à la page de création de table dynamique pour la base de données Hologres cible. Pour plus d'informations, reportez-vous à la section Accéder à la page de création de table dynamique.

Étape 3 : Définir la logique de requête et exécuter la précompilation

1. Saisissez les informations de base :

   • Dynamic table name : dwd_user_new_user_detail_di

   • Description : Statistiques détaillées des nouveaux utilisateurs quotidiens

2. Rédigez une instruction SQL qui extrait tous les enregistrements d'utilisateurs de la table users. Vous n'avez pas besoin de filtrer manuellement le temps dans la clause WHERE, car le mécanisme de partitionnement de la table dynamique gère cela automatiquement.

   SELECT 
       user_id,
       user_name,
       region,
       registration_time, -- Keep the original precise time column for queries
       CAST(registration_time AS DATE) AS ds -- [Key] Cast the timestamp to the DATE type to use as the partition key
   FROM public.users;

3. Cliquez sur Precompile. Une fois la précompilation réussie, le système analyse les informations des colonnes.

Étape 4 : Sélectionner la colonne de partition

La sélection d'une colonne de partition est l'étape qui transforme la table dynamique en table partitionnée.

1. Dans la section Partition Field Information, cliquez sur la liste déroulante Partition Column.

2. Sélectionnez la nouvelle colonne ds comme colonne de partition.

Après avoir sélectionné la colonne de partition, DataWorks identifie la table comme une table partitionnée et affiche les éléments de configuration liés au partitionnement.

Étape 5 : Configurer les politiques de partition et d'actualisation

Pour une description complète de chaque paramètre, consultez les sections Annexe : référence de configuration et Propriétés de partition Hologres.

• Partition Configurations :

  • Partition Properties : Le système affiche automatiquement l'option Logical Partition.

  • Partition Format : Sélectionnez yyyy-mm-dd pour créer des partitions par jour, ce qui correspond aux valeurs DATE de la clé de partition ds.

  • Partition Refresh Scope : Définissez ce paramètre sur 7 jours.

  • Partition Management > Partition Retention Period : Définissez ce paramètre sur 30 jours.

• Refresh Policy Configurations :

  • Refresh Policy : Sélectionnez Auto-Refresh pour permettre à Hologres de choisir entre l'actualisation incrémentielle et l'actualisation complète.

  • Refresh trigger method : Conservez l'option Hologres auto refresh, qui est la seule valeur prise en charge.

  • Data Freshness : Définissez ce paramètre sur 10 minutes.

  • Hologres computing resources : Sélectionnez Serverless resources.

Étape 6 : Publier la table dynamique

Cliquez sur Publish en haut de la page.

Étape 7 : Afficher les partitions et vérifier les données

1. Développez la table dwd_user_new_user_detail_di. Les sous-tables de partition créées en fonction de la date apparaissent, telles que 2026-02-27.

2. Dans un nœud SQL Hologres, insérez de nouvelles données pour la journée en cours dans la table users :

   INSERT INTO users VALUES (4, 'David', 'CN-Shenzhen', '2026-02-27 18:00:00+08');

3. Attendez environ 10 minutes que l'actualisation automatique s'exécute. Pour vérifier le résultat immédiatement, actualisez plutôt la partition manuellement :

   REFRESH DYNAMIC TABLE dwd_user_new_user_detail_di PARTITION (ds = '2026-02-27');

4. Interrogez les données en utilisant la nouvelle clé de partition ds, ce qui est plus efficace :

   -- Efficient query: filter directly on the partition key
   SELECT * FROM dwd_user_new_user_detail_di WHERE ds = '2026-02-27';

La requête renvoie les enregistrements dont l'heure d'inscription correspond à la date interrogée, y compris le nouvel utilisateur David (user_id=4, CN-Shenzhen). Chaque enregistrement renvoyé contient les colonnes user_id, user_name, region, registration_time et ds, et la valeur ds de chaque enregistrement correspond à la date interrogée. Charlie (user_id=3, CN-Beijing) s'est inscrit la veille, donc cet enregistrement appartient à la partition du jour précédent et n'est pas renvoyé par la requête.

Afficher les informations statiques

Les éléments suivants sur la page de détails décrivent comment la table dynamique est définie :

• Details : Les informations de schéma de la table, telles que la liste des colonnes, les types de données et la clé primaire.

• Basic information : Les configurations principales de la table, telles que le propriétaire, la logique d'actualisation des données (SQL) et la politique d'actualisation.

• DDL : L'instruction DDL complète qui crée la table dynamique. Vous pouvez copier cette instruction pour migrer ou reproduire la table.

Surveiller les tâches d'actualisation

Cliquez sur l'onglet Output information pour surveiller le statut d'actualisation de la table dynamique.

• Data refresh : Si une tâche d'actualisation est en cours d'exécution, cette zone affiche des informations en temps réel sur la tâche, telles que le PID, l'ID de requête, le statut et la durée d'exécution.

• Output History : Cette zone enregistre l'historique de chaque tâche d'actualisation. Le tableau suivant décrit les champs de chaque enregistrement.

Contrôler l'actualisation d'une table dynamique

Les boutons d'action suivants sont disponibles sur l'onglet Output information :

• Pause Refresh / Recovery Refresh : Arrête temporairement ou reprend l'actualisation automatique Hologres.

• Manual Refresh : Déclenche manuellement une tâche d'actualisation pour mettre à jour les données immédiatement.

• Convert to Full Table : Change le mode d'actualisation de la table dynamique en Full Refresh et arrête l'actualisation automatique. Ce bouton n'apparaît que lorsque la politique d'actualisation de la table dynamique est Auto-Refresh ou Incremental Refresh.

Modifier une table dynamique

Localisez la table dynamique dans le module Data Directory, puis cliquez sur Edit dans le coin supérieur droit de la page de détails pour ouvrir la page d'édition. La plupart des éléments de configuration peuvent être modifiés. Pour connaître les paramètres modifiables, consultez la documentation Hologres : Modifier une table dynamique.

Supprimer une table dynamique

Dans la liste des tables dynamiques du module Data Directory, faites un clic droit sur la table cible et sélectionnez Delete.

Informations sur les colonnes et colonne de partition

• Informations sur les colonnes (SQL) — La requête SELECT qui définit la source de données de la table dynamique. La précompilation est une étape obligatoire.

• Colonne de partition

  • Non sélectionnée : Crée une table non partitionnée.

  • Une colonne de type heure ou date sélectionnée : Crée une table partitionnée. Le système bascule automatiquement en mode de configuration de table partitionnée.

Configurations d'actualisation des données

Configurations de partition

Les éléments de configuration suivants n'apparaissent qu'après avoir sélectionné une colonne de partition. Les tables dynamiques de la nouvelle version utilisent toutes des partitions logiques.

• Format de partition — (Obligatoire) Définit comment les partitions sont générées à partir des valeurs de la colonne de partition. Par exemple, si le type de colonne est TIMESTAMPTZ et que vous sélectionnez le format yyyy-mm-dd, les partitions sont créées par jour.

• Étendue d'actualisation des partitions — Définit la plage de partitions actives pour l'actualisation automatique. Par exemple, si vous définissez la plage sur les 7 derniers jours, Hologres actualise automatiquement uniquement les partitions des 7 derniers jours. Les partitions plus anciennes ne sont plus actualisées automatiquement, ce qui permet d'économiser des ressources.

• Gestion des partitions (réduit par défaut)

  • Période de rétention des partitions — Définit la durée de vie (TTL) d'une partition. Les partitions expirées sont supprimées automatiquement.

  • Période de rétention du stockage chaud pour les données de partition — Fonctionne avec le stockage hiérarchisé chaud et froid pour définir la durée pendant laquelle les données de partition restent dans le stockage chaud (SSD).

Paramètres avancés (propriétés de table)

Les propriétés physiques suivantes s'appliquent à la table dynamique elle-même et sont similaires aux paramètres d'une table Hologres classique.