Hologres:Dépannage des erreurs d'intégration MaxCompute

Hologres par rapport à MaxCompute

Tables externes par rapport aux tables internes

• Les tables externes accèdent directement aux données de MaxCompute sans les stocker localement. Aucun index n'est utilisé — le calcul repose uniquement sur le CPU. Cette approche convient mieux aux petits jeux de données avec un faible nombre de requêtes par seconde (QPS).

• Les tables internes stockent les données dans Hologres avec prise en charge complète des index. Importez les données pour les requêtes complexes, les mises à jour fréquentes ou les scénarios à fort QPS.

Privilège SELECT manquant sur une table MaxCompute

You have NO privilege 'odps:Select' on {table}

ou :

You have NO privilege 'MaxCompute:Select' on {table}

Cause : Votre compte ne dispose pas de l'autorisation SELECT sur la table MaxCompute.

Solution : Demandez à un administrateur MaxCompute d'accorder le privilège SELECT sur la table. Pour plus de détails, consultez la rubrique Autorisations MaxCompute.

Privilège SELECT manquant sur une table inter-projets

You have NO privilege 'odps:Select' on {table}

Cette erreur survient également lors de l'interrogation d'une table MaxCompute inter-projets, même avec un contrôle d'accès basé sur des packages.

Cause : Hologres doit connaître le contexte du projet MaxCompute à utiliser pour l'autorisation dans les scénarios inter-projets.

Solution : Définissez le nom du projet actuel avant d'exécuter votre requête :

-- For Hologres V0.8+:
set hg_experimental_odps_current_project_name = 'holoprojectname';

-- For Hologres V0.7:
set seahawks.seahawks_internal_current_odps_project = 'holoprojectname';

Incohérence des libellés de sensibilité au niveau des colonnes

The sensitive label of column '{column}' is 2, but your effective label is 0

Cause : Votre compte dispose d'autorisations uniquement sur certaines colonnes de la table MaxCompute. Les versions de Hologres antérieures à la V0.8 ne prenaient pas entièrement en charge les autorisations au niveau des colonnes.

Solution : Choisissez l'une des options suivantes :

• Mettez à niveau vers la version V0.8 ou ultérieure (recommandé). Ces versions gèrent correctement les autorisations au niveau des colonnes.

• Modifiez votre requête pour inclure uniquement les colonnes auxquelles votre compte peut accéder.

• Demandez des autorisations pour toutes les colonnes. Consultez la rubrique Autorisations MaxCompute.

• Solution de contournement pour les anciennes versions : Définissez les paramètres GUC (Grand Unified Configuration) suivants avant d'exécuter votre requête :

set hg_experimental_enable_odps_executor = on;
set hg_experimental_enable_query_master = on;

Si vous utilisez une version plus récente et que cette erreur persiste, il peut s'agir d'un défaut. Utilisez cette solution de contournement alternative :

set hg_experimental_enable_MaxCompute_executor = on;
set hg_experimental_enable_query_master = on;

Privilège LIST manquant (HoloWeb ou DataStudio)

You have NO privilege 'odps:List' on {project}

Cause : La création d'une table externe via HoloWeb ou DataStudio nécessite l'autorisation List dans MaxCompute pour afficher les tables disponibles.

Solution :

• Demandez à un administrateur MaxCompute d'accorder l'autorisation List. Consultez la rubrique Autorisations MaxCompute.

• Sinon, créez la table externe directement avec une instruction SQL CREATE FOREIGN TABLE, qui ne nécessite pas l'autorisation List. Consultez la rubrique Accélération des requêtes sur les données MaxCompute basée sur les tables externes.

Accès refusé par la liste blanche IP

Access denied by project ip white list

Cause : Le projet MaxCompute cible a activé une liste blanche IP, et l'adresse IP du serveur HoloWeb (sourceIP dans le message d'erreur) ne figure pas sur cette liste.

Solution : Ajoutez l'adresse sourceIP issue du message d'erreur à la liste blanche IP du projet MaxCompute cible.

Table externe temporaire résiduelle lors de l'importation d'une table partitionnée MaxCompute depuis HoloWeb

L'importation en un clic d'une table partitionnée MaxCompute depuis HoloWeb s'arrête avec l'erreur suivante :

ERROR: relation "tmp_foreign_XXX" already exists

tmp_foreign_XXX correspond au nom de la table externe temporaire indiqué dans le message d'erreur.

Cause : HoloWeb crée une table externe temporaire nommée tmp_foreign_XXX pour lire les données source lors d'une importation en un clic. Si l'importation échoue ou est interrompue, la table externe temporaire reste dans la base de données. La tentative d'importation suivante échoue alors, car une table portant le même nom existe déjà.

Solution :

1. Vérifiez si la table externe temporaire résiduelle contient encore des données. Remplacez tmp_foreign_XXX par le nom de la table indiqué dans le message d'erreur.

   SELECT * FROM tmp_foreign_XXX LIMIT 1;

2. Traitez le résultat :

   • Si la table ne renvoie aucune ligne, ou si ses données ont déjà atteint la table de destination, supprimez la table résiduelle :

     DROP TABLE tmp_foreign_XXX;

   • Si la table contient encore des lignes, confirmez que les données ont bien atteint la table de destination, puis supprimez la table résiduelle.

3. Relancez l'importation en un clic de la table partitionnée MaxCompute dans HoloWeb.

Compte absent du projet MaxCompute

You don't exist in project {project}

Cause : Votre compte n'a pas été ajouté en tant que membre au projet MaxCompute spécifié.

Solution : Vérifiez que le nom du projet indiqué dans l'erreur est correct. Si c'est le cas, demandez à un administrateur MaxCompute d'ajouter votre compte au projet. Consultez la rubrique Présentation des autorisations.

Autorisation de rôle de chiffrement manquante

query next from foreign table executor failed validate userinfo

Cause : Le rôle AliyunHologresEncryptionDefaultRole n'a pas été accordé à Hologres. Cette erreur peut également apparaître de manière intermittente en raison de la mise en cache si l'autorisation a été accordée il y a moins de trois heures.

Solution : Accordez la stratégie AliyunHologresEncryptionDefaultRolePolicy au compte. Consultez la rubrique Interrogation des données MaxCompute chiffrées.

Fichier non ORC

status { code: SERVER_INTERNAL_ERROR message: "hos_exception: Invalid argument: not an ORC file" }

Cause : Les tables externes Hologres ne peuvent pas accéder aux tables MaxCompute pendant le chargement en flux actif, car les données ne sont pas encore au format ORC.

Solution : Ajoutez les paramètres GUC suivants avant votre instruction SQL :

set hg_experimental_enable_access_odps_with_table_api = on;
set hg_experimental_enable_access_odps_orc_via_holo = off;

Incompatibilité de schéma ORC pour le type DECIMAL

Open ORC file failed for schema mismatch. Reader schema

Cause : Le format de stockage pour DECIMAL dans la table ORC MaxCompute a changé, généralement après l'ajout d'un nouveau champ DECIMAL ou une modification de la configuration canary.

Solution :

• Exécutez la commande suivante dans MaxCompute et réimportez les données :

set MaxCompute.storage.orc.enable.binary.decimal = false;

• Ou modifiez le type DECIMAL en DOUBLE dans la table MaxCompute et actualisez les données.

Dépassement de capacité Timestamp

Timestamp overflow detected while converting timestamp from orc VectorBatch to arrow

Cause : La table MaxCompute contient des données TIMESTAMP chargées via Tunnel avec une précision à la nanoseconde, ce que Hologres ne prend pas en charge.

Solution :

• Convertissez le type TIMESTAMP en DATETIME dans MaxCompute.

• Ou mettez à niveau votre instance Hologres vers la version V1.1.70 ou ultérieure.

Évolution du schéma non activée

failed to import foreign schema: Failed to get MaxCompute table: Not enable schema evolution

Cause : Le schéma de la table MaxCompute a été modifié (colonnes ajoutées ou supprimées), passant dans un état d'évolution de schéma que Hologres ne peut pas lire.

Solution :

1. Mettez à niveau votre instance Hologres vers la version V1.3 ou ultérieure.

2. Exécutez la commande IMPORT FOREIGN SCHEMA pour actualiser le schéma de la table externe après une modification du schéma de la table MaxCompute.

3. Si l'erreur persiste, recréez la table MaxCompute, puis la table externe.

Table transactionnelle (ACID) non prise en charge

failed to import foreign schema: Failed to get MaxCompute table: Not enable acid table

Cause : La table MaxCompute est une table transactionnelle (ACID).

Solution : Convertissez la table en une table MaxCompute standard. Les tables transactionnelles ne sont pas prises en charge.

Limite de partitions dépassée (512)

Specified partitions count in MaxCompute table: exceeds the limitation of 512

ou :

Build desc failed: Exceeds the partition limitation of 512, current match {n} partitions

Cause : Par défaut, Hologres analyse un maximum de 512 partitions par requête sur une table externe.

Solution :

• Ajoutez un filtre de partition à votre requête pour réduire le nombre de partitions analysées.

• Importez les données dans une table interne, qui n'a aucune limite de partition. Consultez la rubrique Importation de données depuis MaxCompute à l'aide de SQL.

• Ajustez la limite de partitions avec un paramètre GUC. La valeur par défaut est 512 et le maximum est 1024. Définir cette valeur trop haut peut dégrader les performances des requêtes.

-- For V1.1 and later:
set hg_foreign_table_max_partition_limit = 128;

-- For V0.10:
set hg_experimental_foreign_table_max_partition_limit = 128;

Limite de taille d'analyse dépassée (200 Go)

Build desc failed: Exceeds the scan limitation of 200 GB, current scan {n} GB

Cause : Hologres limite par défaut les analyses de données des tables externes à 200 Go par requête. Cela s'applique aux partitions analysées, et non aux données totales stockées.

Solution :

• Ajoutez des filtres pour réduire les partitions accessibles, en maintenant les données analysées sous 200 Go.

• Importez les données dans Hologres avant d'effectuer des requêtes. Consultez la rubrique Importation de données depuis MaxCompute à l'aide de SQL.

• (Non recommandé) Augmentez la limite d'analyse. Remplacez la valeur par la taille requise en Go. Une augmentation excessive de cette limite peut dégrader les performances et provoquer des erreurs OOM (mémoire insuffisante).

set hg_experimental_foreign_table_max_scan_size = 400;

Ressources épuisées (serveur occupé)

Request denied, may caused by server busy

Cause : Les ressources pour les requêtes sur les tables externes sont épuisées.

Solution :

• Optimisez votre SQL. Consultez la rubrique Optimisation des performances des requêtes pour les tables externes MaxCompute.

• Réduisez le DOP (Degree of Parallelism). Le DOP contrôle la concurrence pour la lecture des données de la table externe par nœud d'exécution. Valeur par défaut : 256, plage : 0–1024. Une valeur trop élevée risque de provoquer des erreurs OOM ; une valeur trop basse dégrade les performances.

-- Check the current DOP:
show hg_foreign_table_executor_max_dop;

-- Set it to half the current value (example):
set hg_foreign_table_executor_max_dop = 18;

• Importez les données dans une table interne. Les tables internes prennent en charge les index pour de meilleures performances de requête. Consultez la rubrique Importation de données depuis MaxCompute à l'aide de SQL.

Limite de mémoire dépassée lors de l'importation

Query executor exceeded total memory limitation {limit}: {used} bytes used

Cause : La requête a dépassé la limite de mémoire de calcul. Chaque nœud Hologres dispose de 64 Go de mémoire, divisée approximativement en trois tiers : calcul, mise en cache et métadonnées.

Solution : Essayez ces étapes dans l'ordre :

1. Vérifiez le plan d'exécution. Exécutez explain analyze <sql>; pour examiner les nombres de lignes. Si certaines tables n'ont pas de statistiques à jour, l'optimiseur peut choisir un ordre de jointure sous-optimal. Exécutez analyze <tablename>; sur toutes les tables impliquées pour mettre à jour les statistiques.

2. Réduisez la taille du lot. Les tables larges ou les lignes volumineuses peuvent épuiser la mémoire par lot. Réduisez le nombre de lignes par lot :

      set hg_experimental_query_batch_size = 1024;  -- Default: 8192
      insert into holo_table select * from mc_table;

3. Réduisez le DOP d'importation. Le paramètre hg_foreign_table_executor_max_dop est défini par défaut sur le nombre d'unités de calcul (CU) de l'instance. Définissez une valeur plus petite lors de l'importation :

      set hg_foreign_table_executor_max_dop = 8;
      insert into holo_table select * from mc_table;

4. Dédupliquez les données. Avec insert on conflict, les doublons excessifs augmentent la pression sur la mémoire. Dédupliquez les données dans MaxCompute avant l'importation. Consultez la rubrique Fusion de plusieurs lignes de données en une seule ligne.

5. Mettez à niveau Hologres. À partir de la version V1.1.24, Hologres ajuste dynamiquement l'allocation de mémoire pour le calcul. Consultez la rubrique Mise à niveau de l'instance.

6. Augmentez la capacité de l'instance. Si toutes les autres approches échouent, augmentez les ressources de l'instance. Consultez la rubrique Mise à niveau.

Type de table CFile non pris en charge

query next from foreign table executor failed, GetRecordBatch() is not implemented

Cause : La table MaxCompute est une table de type CFile, que Hologres ne prend pas en charge via le chemin d'accès par défaut.

Solution : Ajoutez le paramètre GUC suivant avant votre instruction SQL :

set hg_experimental_enable_access_odps_with_table_api = on;

Données Streaming Tunnel non lisibles

Query next from foreign table executor failed, not implemented

Cause : La table MaxCompute a été chargée via Streaming Tunnel (tunnel.createStreamUploadSession). Des paramètres GUC spécifiques sont requis pour lire ces données.

Solution (Hologres V1.3 et versions ultérieures) : Ajoutez les paramètres suivants avant votre requête :

set hg_experimental_enable_access_odps_with_table_api = on;
set hg_experimental_enable_access_odps_orc_via_holo = off;

Solution de contournement pour les versions antérieures à la V1.3 : Arrêtez le chargement en flux dans MaxCompute, puis fusionnez les données :

set odps.merge.task.mode = sql;
set odps.merge.lock.expire.time = 0;
ALTER TABLE tablename [PARTITION] MERGE SMALLFILES;

Vues MaxCompute non prises en charge

Build desc failed: failed to check permission: Currently not supported table type "view"

Cause : Hologres ne prend pas en charge les vues MaxCompute en tant que tables externes.

Échec de récupération des métadonnées (Pangu)

Build desc failed: failed to get foreign table split: MaxCompute-0010000: System internal error - get input pangu dir meta fail

Cause : La configuration Hologres pour la lecture depuis MaxCompute n'a pas été mise à jour rapidement.

Solution : Attendez quelques minutes et réessayez. Si le problème persiste, contactez le support technique.

Connexion RPC fermée en raison de petits fichiers

Build desc failed: failed to get foreign table split: ERPC_ERROR_CONNECTION_CLOSED

Cause : La table MaxCompute contient trop de petits fichiers, ce qui entraîne le dépassement de la limite RPC de 1 Go pour la demande de métadonnées.

Solution :

• Fusionnez les petits fichiers dans MaxCompute :

set MaxCompute.merge.task.mode = sql;
set MaxCompute.merge.lock.expire.time = 0;
ALTER TABLE <tablename> [PARTITION] MERGE SMALLFILES;

• Mettez à niveau vers Hologres V0.10.21 ou version ultérieure, où ce problème est corrigé. Consultez la rubrique Mise à niveau de l'instance.

• Si le volume de données est faible, importez les données dans Hologres. Contactez le support technique MaxCompute si le problème persiste.

Échec d'accès aux données MaxCompute chiffrées

status { code: SERVER_INTERNAL_ERROR message: "hos_exception: IO error: Failed to execute pangu open normal file, err: PanguParameterInvalidException" }

Cause : HQE ne peut pas accéder aux données MaxCompute chiffrées sur Pangu.

Solution : Basculez le moteur d'exécution vers SQE, qui peut accéder aux données chiffrées. Définissez ceci au niveau de la base de données (s'applique aux nouvelles connexions) :

ALTER DATABASE <dbname> SET hg_experimental_enable_access_odps_orc_via_holo = false;

Ou au niveau de la session :

SET hg_experimental_enable_access_odps_orc_via_holo = false;

Ralentissement des requêtes après l'évolution du schéma de la table externe

Cause : Hologres utilise HQE pour accélérer les requêtes sur les tables externes par défaut. Après une modification du schéma MaxCompute, Hologres revient à SQE, qui est plus lent.

Solution :

1. Interrogez la table hologres.hg_query_log pour identifier les requêtes lentes.

2. Vérifiez le champ engine_type. S'il indique SQE, la baisse de performance est causée par le basculement du moteur.

3. Recréez la table externe concernée avec le schéma mis à jour dans Hologres.

Requêtes lentes sur les tables externes (général)

Optimisez vos instructions SQL. Consultez la rubrique Optimisation des performances des requêtes pour les tables externes MaxCompute.