REBUILD - Hologres - Centre de documentation Alibaba Cloud

Syntaxe

Format de l'instruction

ASYNC REBUILD TABLE [ IF EXISTS ] <table_name>
    [ WITH ( <rebuild_parameter> [= <value>] [, ... ] )]  
    <action> [, ... ];
WHERE action IS ONE OF:
    ADD [ COLUMN ] <column_name> <data_type> [ column_constraint [ ... ] ]
    ALTER [ COLUMN ] <column_name> [ SET DATA ] TYPE <data_type> [ USING <expression> ]
    ALTER [ COLUMN ] <column_name> SET DEFAULT <expression>
    ALTER [ COLUMN ] <column_name> DROP DEFAULT
    ALTER [ COLUMN ] <column_name> { SET | DROP } NOT NULL
    ALTER PRIMARY KEY (<column_name> [, ...])
    TO [LOGICAL] PARTITION [BY LIST(<column_name> [, <column_name>])]
    SET ( <parameter> [= <value>] [, ... ] )
WHERE rebuild_parameter IS ONE OF:
    keep_source
    binlog_mode
    rebuild_guc_<guc_name> = '<guc_value>'

Paramètres

Paramètre	Sous-élément	Description
ASYNC		Indique que la tâche REBUILD s'exécute de manière asynchrone. Une fois la tâche lancée, un `query_id` est renvoyé. Ce `query_id` permet de surveiller l'état d'exécution de la tâche. L'exécution synchrone n'est actuellement pas prise en charge.
table_name		Nom de la table cible à reconstruire.
column_name		Nom de la colonne de la table cible.
data_type		Type de données de la colonne.
action	ADD COLUMN	Ajoute une colonne. Vous pouvez ajouter des colonnes NOT NULL et définir des valeurs par défaut.
	ALTER COLUMN TYPE	Modifie le type de données d'une colonne.
	ALTER COLUMN SET/DROP DEFAULT	Définit ou supprime la valeur par défaut d'une colonne. Les valeurs NULL présentes dans les données existantes restent inchangées.
	ALTER COLUMN SET/DROP NOT NULL	Applique ou retire la contrainte NOT NULL sur une colonne.
	ALTER PRIMARY KEY	Modifie la clé primaire de la table. En cas de conflit de données avec la nouvelle clé primaire, une erreur survient lors de l'exécution asynchrone. Surveillez régulièrement l'état d'avancement de la tâche.
	TO [LOGICAL] PARTITION	Convertit la table en table partitionnée logique ou physique. Les scénarios suivants sont pris en charge : Conversion d'une table standard en table partitionnée physique. Spécifiez une clé de partition. Conversion d'une table standard en table partitionnée logique. Spécifiez une clé de partition. Modification de la clé de partition d'une table partitionnée physique. Conversion d'une table partitionnée physique en table partitionnée logique. La modification de la clé de partition est optionnelle. La conversion d'une table partitionnée logique en table partitionnée physique est impossible.
	SET ( <parameter> [= <value>])	Modifie les propriétés de la table. Cas d'usage courants : Modification de la clé de distribution (`distribution_key`). Modification de la clé de segment (`event_time_column`). Modification de l'index de clustering (`clustering_key`). Modification du format de stockage de la table (`orientation`). La conversion entre stockage orienté ligne, orienté colonne et hybride ligne-colonne est possible. Modification du `table_group` auquel appartient la table. Toutes les autres propriétés de table peuvent également être modifiées. Pour modifier les index bitmap (`bitmap_columns`) ou les colonnes d'encodage de dictionnaire (`dictionary_encoding_columns`), utilisez l'instruction ALTER TABLE. REBUILD n'est pas nécessaire.
WITH (<rebuild_parameter> [= <value>])		Définit les paramètres liés à la tâche REBUILD. Paramètres courants : keep_source : Aucune valeur requise. Si ce paramètre est spécifié, la table d'origine n'est pas supprimée mais renommée sous la forme `tmp_rebuild_old_<query_id>_<unique_id>_<table_name>`. binlog_mode : Aucune valeur requise. Permet de reconstruire une table pour laquelle Binlog est activé. Afin d'éviter toute perte de données Binlog, suivez impérativement les étapes décrites dans la section Exemples. `rebuild_guc_hg_computing_resource='serverless'` : Utilise des ressources Serverless pour exécuter la tâche REBUILD. Cela évite de consommer les ressources de votre instance et améliore la stabilité de la tâche. `rebuild_guc_<guc_name>='<guc_value>'` : D'autres paramètres GUC peuvent être définis ici. Pour plus d'informations, consultez Paramètres GUC.

Précautions

Seule l'exécution asynchrone (ASYNC) est prise en charge, ce qui évite d'occuper une connexion de manière prolongée.
Après l'envoi d'une tâche REBUILD, l'instruction renvoie un query_id. Utilisez ce query_id pour consulter l'état d'exécution de la tâche REBUILD. Si aucun query_id n'est renvoyé rapidement après l'envoi, cela peut indiquer qu'un grand nombre de tâches asynchrones sont déjà en cours d'exécution sur l'instance. Nous vous recommandons d'attendre que le query_id soit retourné avant de vérifier l'état de la tâche.
L'utilisation de la fonctionnalité REBUILD pour modifier les paramètres d'une table implique une redistribution sous-jacente des données, ce qui consomme des ressources de calcul. Par conséquent, exécutez les tâches REBUILD pendant les heures creuses ou utilisez des ressources de calcul serverless afin de garantir la stabilité de vos activités.
Pendant une tâche REBUILD, la table passe temporairement en lecture seule et les écritures sont bloquées. À partir de Hologres V4.1, REBUILD utilise la technologie Dynamic Table pour les mises à jour incrémentielles, réduisant ainsi considérablement la durée de l'état lecture seule. Cette optimisation s'applique uniquement si la table remplit les conditions suivantes. Dans le cas contraire, la table reste en lecture seule pendant toute la durée de la tâche.
- La table cible doit posséder une clé primaire avant la reconstruction, et la nouvelle clé primaire doit contenir toutes les colonnes de la clé primaire d'origine.
- La table cible doit utiliser un stockage orienté colonne ou un stockage hybride ligne-colonne avant la reconstruction.
- La table cible ne doit pas contenir de colonnes générées après la reconstruction.
- Si la table cible est une table partitionnée physique avant la reconstruction, sa clé de partition doit rester inchangée après celle-ci.
- Si la table cible devient une table partitionnée logique après la reconstruction, elle ne peut avoir qu'une seule clé de partition.
Afin de réduire la charge système, regroupez plusieurs modifications au sein d'une même tâche REBUILD.
Une fois une table partitionnée physique reconstruite, ses propriétés de gestion dynamique des partitions ne sont pas héritées. Reconfigurez-les une fois la tâche terminée. Ces propriétés incluent :
- La propriété auto_partitioning de la table partitionnée parente.
- Les propriétés des partitions enfants, telles que keep_alive.
- Après la reconstruction d'une table partitionnée physique, les propriétés définies indépendamment sur ses partitions enfants ne sont pas conservées. Les partitions enfants héritent alors de toutes les propriétés de la table parente, notamment bitmap_columns et dictionary_encoding_columns.
REBUILD n'est pas pris en charge pour les types de tables suivants :
- Tables possédant des propriétés de colonne spécifiques (comme l'optimisation du stockage colonnaire pour les colonnes JSONB) ou des contraintes de colonne (telles que les colonnes vectorielles).
- Tables disposant d'un index texte intégral ou d'un index secondaire global.
- Tables contenant des colonnes de type Serial ou Bigserial.
- Tables ayant des dépendances envers Dynamic Table ou des vues matérialisées. Les tables dépendant de vues standard sont en revanche prises en charge.

Exemples

Reconstruction d'une table sans Binlog

-- Create a table and import data.
CREATE TABLE rebuild_test (
    a TEXT,
    b TEXT,
    ds TEXT
);
INSERT INTO rebuild_test VALUES ('1', '1', '2025-04-01'), ('2', '2', '2025-04-02'), ('3', '3', '2025-04-03');
-- Add a NOT NULL column with a default value.
ASYNC REBUILD TABLE rebuild_test ADD COLUMN c text NOT NULL DEFAULT 'a';
-- Change the primary key to column a.
ASYNC REBUILD TABLE rebuild_test ALTER PRIMARY KEY (a);
-- Use Serverless resources to run the REBUILD task, set the distribution_key and clustering_key, and change to row-column hybrid storage.
ASYNC REBUILD TABLE rebuild_test 
WITH (
    rebuild_guc_hg_computing_resource = 'serverless'
)
SET (
    distribution_key = 'a',
    clustering_key = 'a',
    orientation = 'row,column'
);
-- Convert the non-partitioned table to a logical partitioned table, set the partition key to ds, and add a NOT NULL constraint to the ds column.
ASYNC REBUILD TABLE rebuild_test 
    ALTER COLUMN ds SET NOT NULL,
    TO LOGICAL PARTITION BY LIST(ds);

Reconstruction d'une table avec Binlog

L'instruction REBUILD ne conserve pas les données historiques du Binlog. Par conséquent, il est impossible d'exécuter REBUILD par défaut sur une table où Binlog est activé. Spécifiez le paramètre binlog_mode et suivez les étapes ci-dessous afin de vous assurer que le consommateur en aval a bien traité toutes les données Binlog existantes.

Exécutez l'instruction REBUILD.

ASYNC REBUILD TABLE rebuild_test 
WITH (
  binlog_mode
)
<YOUR_ACTION>;

Pour une tâche REBUILD utilisant le paramètre binlog_mode, la tâche se met automatiquement en pause une fois l'étape set_readonly terminée. Interrogez son avancement à l'aide de l'instruction SQL suivante. À ce stade, la table est en lecture seule : aucune écriture supplémentaire n'est possible et aucune nouvelle donnée Binlog n'est générée.

postgres=# SELECT step, status, progress FROM hologres.rebuild_progress('<query_id>');
             step              | status | progress 
-------------------------------+--------+----------
 prepare                       | done   | 1/1
 create_tmp_table              | done   | 1/1
 get_src_table_snapshot        | done   | 1/1
 insert                        | done   | 1/1
 set_readonly                  | done   | 1/1
 check_snapshot                |        | 0/1
 re-insert                     |        | -
 check_additional_child_table  |        | -
 create_additional_child_table |        | -
 insert_additional_child_table |        | -
 swap                          |        | 0/1
(11 rows)

Attendez que les clients en aval terminent la consommation des données Binlog existantes, puis arrêtez ces tâches de consommation. Exécutez ensuite manuellement l'instruction SQL suivante pour reprendre la tâche REBUILD.
```
RESUME '<query_id>';
```
Une fois la tâche REBUILD terminée, Binlog est automatiquement activé pour la nouvelle table. Redémarrez la tâche de consommation du Binlog en aval en mode sans état, et consommez le Binlog de la nouvelle table à partir de lsn = 0.

Conversion d'une table standard en table liquide

À partir de Hologres V4.2, vous pouvez utiliser REBUILD pour convertir une table standard en table liquide, ou inversement.

--- Convert a regular table to a liquid table.
ASYNC REBUILD TABLE normal_table 
SET (
  liquid_table = 'true'
);

--- Convert a liquid table to a regular table.
ASYNC REBUILD TABLE liquid_table 
SET (
  liquid_table = 'false'
);

Surveillance et exploitation

Consulter l'état d'exécution d'une tâche REBUILD

Les tâches REBUILD s'exécutent de manière asynchrone. Lorsqu'une tâche est envoyée avec succès, l'instruction renvoie un statut de réussite ainsi qu'un query_id. Interrogez la vue système hologres.rebuild_progress pour surveiller l'état des sous-tâches asynchrones. L'opération REBUILD n'est terminée que lorsque toutes les sous-tâches ont réussi. Exécutez la commande suivante :

SELECT * FROM hologres.rebuild_progress('<rebuild_query_id>');

Le tableau suivant décrit les colonnes de cette table système.

Nom de la colonne	Description
job_name	Identifiant query_id de la tâche REBUILD.
step_id	Identifiant de l'étape. Les sous-tâches de REBUILD s'exécutent séquentiellement selon ces identifiants.
step	Nom de l'étape : prepare : Préparation de la tâche. create_tmp_table : Création d'une table temporaire. get_src_table_snapshot : Obtention d'un snapshot des données de la table d'origine. insert : Importation des données historiques dans la table temporaire. set_readonly : Passage de la table à reconstruire en mode lecture seule. Les écritures de données sont interrompues. check_snapshot : Vérification de la correspondance entre le snapshot actuel et celui obtenu lors de l'étape get_src_table_snapshot. En cas de différence, l'étape `re-insert` est exécutée. re-insert : Importation des données incrémentielles. check_additional_child_table : Vérification de la création éventuelle de nouvelles tables enfants par les utilisateurs depuis le début de REBUILD. Cette étape concerne uniquement les tables partitionnées physiques. create_additional_child_table : Création des nouvelles tables enfants potentielles pour la table temporaire. Cette étape concerne uniquement les tables partitionnées physiques. insert_additional_child_table : Importation des données historiques dans les nouvelles tables enfants temporaires. Cette étape concerne uniquement les tables partitionnées physiques. swap : Remplacement de la table d'origine par la table temporaire.
status	État de la sous-tâche. done : Terminée. doing : En cours. NULL : Cette étape n'a pas besoin d'être exécutée, ou il est actuellement impossible de déterminer si elle doit l'être. error : Échec de l'exécution. Consultez le message d'erreur dans le champ message.
progress	Progression de la sous-tâche, affichée au format `m/n`, où m représente le nombre de sous-étapes terminées et n le total. Le nombre total (n) correspond souvent au nombre de partitions de la table.
start_time	Heure de début de la sous-tâche.
end_time	Heure de fin de la sous-tâche.
queryid	Identifiant query_id de la sous-tâche.
pid	Identifiant du processus de service.
message	Message associé à la sous-tâche. Si une erreur survient, le message correspondant est enregistré dans ce champ.

Arrêter et redémarrer des tâches REBUILD

Suspendez une tâche asynchrone REBUILD.
```
SUSPEND '<query_id>';
```
Reprenez la tâche asynchrone marquée comme CANCEL.
```
RESUME '<query_id>';
```

Exceptions liées aux tâches REBUILD

Si une tâche REBUILD est interrompue par une erreur ou suspendue manuellement, vous pouvez soit la reprendre avec la commande RESUME, soit l'arrêter définitivement et nettoyer l'environnement en suivant ces étapes :

Exécutez la commande suivante pour supprimer les tables temporaires créées pendant le processus REBUILD.
```
CALL hg_clean_rebuild_tmp_tables('<query_id>');
```
Si la table a été placée en lecture seule, exécutez la commande appropriée pour rétablir l'accès en écriture.
- Pour les versions de Hologres antérieures à la V4.1, exécutez la commande suivante.
```
ALTER TABLE <table_name> SET (readonly = false);
```
- Pour Hologres V4.1 et versions ultérieures, exécutez la commande suivante.
```
ALTER TABLE <table_name> RESET (ddl_options,write_options);
```