MaxFrame expose deux niveaux de configuration : les indicateurs MaxCompute (paramètres SQL qui contrôlent l'exécution des tâches individuelles) et les options MaxFrame (paramètres d'exécution qui régissent les sessions, les ressources et le comportement du client). Ce guide présente ces deux niveaux : leur objectif, leurs valeurs par défaut et les cas dans lesquels il convient de les modifier.
Important
De nombreux indicateurs avancés nécessitent une autorisation préalable (whitelisting) pour prendre effet. Contactez le support technique MaxCompute avant de configurer les options expertes.
Comment définir les indicateurs
Définissez tous les indicateurs SQL MaxCompute dans le dictionnaire options.sql.settings. Configurez les options MaxFrame directement via options.<name>.
from maxframe import options
# MaxCompute SQL flags — set via options.sql.settings
options.sql.settings = {
"odps.sql.job.max.time.hours": 72,
"odps.session.image": "common",
"odps.sql.split.dop": '{"*":50000}',
"odps.sql.executionengine.batch.rowcount": 1024,
}
# MaxFrame options — set directly
options.session.logview_hours = 24
options.retry_times = 3
options.sql.enable_mcqa = TrueRechercher les indicateurs par problème
Utilisez ce tableau pour accéder rapidement aux indicateurs les plus pertinents selon le problème rencontré.
| Problème | Indicateurs pertinents |
|---|---|
| La division des tâches est lente | odps.sql.split.dop, odps.sql.split.cluster.parallel_explore |
| Erreurs de mémoire insuffisante (OOM) | odps.stage.mapper.mem, odps.stage.reducer.mem, odps.stage.joiner.mem, odps.sql.executionengine.batch.rowcount |
| Échec ou lenteur des brassages (shuffles) à grande échelle | fuxi_streamline_x_EnableNormalCheckpoint, fuxi_ShuffleService_client_CheckpointMaxCopy, odps.sql.sys.flag.fuxi_JobMaxInternalFolderSize |
| Déséquilibre des données (skew) dans GROUP BY ou JOIN | odps.stage.reducer.num, odps.stage.joiner.num |
| Une UDF (fonction définie par l'utilisateur) de longue durée est arrêtée de manière inattendue | odps.sql.runtime.flag.fuxi_EnableInstanceMonitor, fuxi_InstanceMonitorTimeout, odps.sql.udf.timeout, odps.function.timeout |
| Les statistiques de stockage en colonnes (CMF) ne sont pas générées après l'écriture dans des tables partitionnées dynamiques | Combinaison fixe pour les écritures de table et CMF |
| Échec de la tâche dû à des erreurs machine transitoires | odps.job.instance.retry.times |
| Les journaux Python UDF sont tronqués | odps.sql.runtime.flag.executionengine_PythonStdoutMaxsize |
| Besoin d'utiliser une image d'exécution spécifique ou une version MaxCompute particulière | odps.session.image, odps.task.major.version |
Indicateurs MaxCompute
Configurez les indicateurs suivants via options.sql.settings.
Concurrence et découpage
| Paramètre | Description | Valeur par défaut | Quand le modifier |
|---|---|---|---|
odps.sql.split.dop |
Définit le degré de parallélisme (DOP) pour la lecture des données, table par table, en s'appuyant sur les statistiques de stockage en colonnes (CMF). Cet indicateur est prioritaire sur split.size. Format : {"table_name": value}. Utilisez project.[schema.]table pour un nom complet. Utilisez {"*": value} pour cibler toutes les tables. Plage : 1–99999. |
Aucune | Lorsque vous traitez de grandes tables ou exécutez des tâches à grande échelle, activez explicitement ce paramètre pour obtenir une concurrence élevée. |
odps.stage.mapper.split.size |
En l'absence de CMF, divise les tâches en fonction de la taille de la table d'entrée en Mo. Plage : ≥1 Mo. | 256 Mo | Conservez la valeur par défaut. |
Ressources et mémoire
| Paramètre | Description | Valeur par défaut | Quand le modifier |
|---|---|---|---|
odps.stage.mapper.mem / odps.stage.reducer.mem / odps.stage.joiner.mem |
Mémoire allouée (en Mo) à un seul worker pour les étapes Mapper, Reducer et Joiner respectivement. Plage : 1024–12288 Mo. | 1024 Mo | Augmentez cette valeur lors du traitement de grands volumes de données, en présence de points chauds (hot spots) ou en cas d'erreurs OOM dues à des jointures complexes. |
odps.stage.reducer.num / odps.stage.joiner.num |
Nombre d'instances concurrentes pour les étapes Reduce et Join. Maximum : 10 000. | Calculé dynamiquement | Augmentez cette valeur pour les brassages à grande échelle (GROUP BY ou JOIN) ou lorsque le déséquilibre des données impose à une instance une charge disproportionnée. |
Sécurité du brassage et de la sortie
| Paramètre | Description | Valeur par défaut | Quand le modifier |
|---|---|---|---|
odps.sql.runtime.flag.fuxi_streamline_x_EnableNormalCheckpoint & fuxi_ShuffleService_client_CheckpointMaxCopy |
Active les sauvegardes pour la sortie intermédiaire du Mapper et définit le nombre de réplicas. | — | Pour les tâches de longue durée avec des brassages à grande échelle, définissez le nombre de réplicas sur 2 : "fuxi_ShuffleService_client_CheckpointMaxCopy": 2. Cela améliore considérablement la tolérance aux pannes et la stabilité de la lecture des données pendant le brassage. |
odps.sql.sys.flag.fuxi_JobMaxInternalFolderSize |
Taille totale maximale (en Mo) des données de brassage intermédiaires générées par une seule tâche. | — | Augmentez cette valeur si une tâche échoue avec l'erreur Internal data size exceeds limit lors d'un brassage sur une grande table. |
Stabilité du calcul et surveillance
| Paramètre | Description | Valeur par défaut | Quand le modifier |
|---|---|---|---|
odps.sql.runtime.flag.fuxi_EnableInstanceMonitor & fuxi_InstanceMonitorTimeout |
Active la surveillance par heartbeat pour l'ordonnanceur Fuxi et définit le délai d'expiration en secondes. À utiliser conjointement. Empêche le système de considérer une UDF de longue durée comme inactive et de la terminer. | — | Activez cette option lorsque des UDF de longue durée sont arrêtées à tort. Pour modifier fuxi_InstanceMonitorTimeout, contactez le support technique afin de l'ajouter à la liste d'autorisation. |
odps.job.instance.retry.times |
Nombre maximal de tentatives automatiques pour un seul worker après des échecs transitoires tels que des pannes machines. Valeur par défaut : 3. Maximum recommandé : 100. | 3 | Augmentez cette valeur pour les tâches qui échouent en raison d'erreurs d'infrastructure transitoires. Pour définir une valeur supérieure à la valeur par défaut, contactez le support technique afin d'ajouter le paramètre à la liste d'autorisation. |
odps.dag2.compound.config |
Configure la politique de réutilisation des workers. Définissez sur fuxi.worker.reuse.policy:NO_REUSE pour désactiver la réutilisation. |
— | Désactivez la réutilisation lorsqu'une UDF présente des risques de fuite de mémoire ou de pollution d'état, afin que chaque tâche démarre dans un environnement propre. Cela augmente légèrement la surcharge de démarrage des tâches. |
Efficacité d'exécution et optimisation
| Paramètre | Description | Valeur par défaut | Quand le modifier |
|---|---|---|---|
odps.sql.executionengine.batch.rowcount |
Taille du lot en lignes — unité de base pour le traitement interne des données. | 1024 | Réduisez cette valeur si une seule ligne est très volumineuse et provoque une erreur OOM. Augmentez-la pour les charges de travail de calcul simples afin d'améliorer le débit. |
odps.sql.runtime.flag.executionengine_EnableVectorizedExpr |
Active le moteur d'exécution vectorisé pour les expressions. | — | Activez cette option lorsque vous utilisez rand() ou exécutez des opérations intensives en calcul arithmétique. |
odps.optimizer.enable.conditional.mapjoin & odps.optimizer.cbo.rule.filter.black |
Utilisés conjointement pour désactiver HashJoin. Définissez cbo.rule.filter.black sur "hj". |
— | Option experte. Ne configurez pas sauf si vous comprenez parfaitement l'impact sur le plan d'exécution. |
odps.sql.split.cluster.parallel_explore |
Lit les informations CMF de manière concurrente pendant l'étape de division des tâches. | — | Activez cette option lorsque l'étape de division d'une tâche prend trop de temps. |
odps.sql.jobmaster.memory |
Taille de la mémoire (en Mo) pour le nœud Master de la tâche. | — | Augmentez cette valeur pour les tâches de brassage impliquant des tables très volumineuses. Par exemple, définissez-la sur 30 000 Mo. |
Sécurité des UDF et des fonctions
| Paramètre | Description | Valeur par défaut | Quand le modifier |
|---|---|---|---|
odps.sql.udf.timeout & odps.function.timeout |
Délai d'expiration (en secondes) pour l'exécution d'un lot de données dans une UDF ou une fonction. La valeur 0 n'a aucun effet. Plage : 1–3600 s. |
1800 s | — |
odps.sql.runtime.flag.executionengine_PythonStdoutMaxsize |
Longueur maximale (en Mo) des journaux envoyés vers stdout par les instructions print des UDF Python. Maximum : 100 Mo. | 20 Mo | Augmentez cette valeur lorsque les journaux des UDF Python sont tronqués. Contactez le support technique pour ajouter cet indicateur à la liste d'autorisation. |
Ressources et environnement
| Paramètre | Description | Valeur par défaut | Quand le modifier |
|---|---|---|---|
odps.session.image |
Spécifie l'environnement d'exécution. La valeur doit correspondre au nom d'une image personnalisée existante dans le projet MaxCompute du locataire actuel. | — | — |
odps.task.major.version |
Verrouille une tâche sur une version majeure spécifique de MaxCompute pour garantir la stabilité des fonctionnalités et du comportement. | — | Option experte. Ne configurez pas sauf si vous comprenez l'impact. |
odps.storage.orc.row.group.stride & odps.storage.meta.file.version |
Contrôlent respectivement la taille des groupes de lignes des fichiers ORC et la version des fichiers de métadonnées CMF. | — | Options expertes. Ne configurez pas sauf si vous comprenez les mécanismes sous-jacents. |
Autres indicateurs généraux
| Paramètre | Description | Valeur par défaut | Quand le modifier |
|---|---|---|---|
odps.sql.allow.fullscan |
Autorise une analyse complète de la table (full table scan) sur une table partitionnée sans condition de filtre de partition. | — | À activer avec prudence. Une analyse complète sur de grandes tables partitionnées peut entraîner des coûts élevés et des temps d'exécution longs. |
odps.sql.cfile2.field.maxsize |
Taille de stockage maximale (en octets) pour une seule colonne. Valeur par défaut : 8 388 608 (8 Mo). Maximum : 268 435 456 (256 Mo). | 8 388 608 (8 Mo) | Augmentez cette valeur lors du traitement de colonnes contenant du contenu très volumineux, tel que du texte long, du HTML ou des données encodées en Base64. |
odps.sql.job.max.time.hours |
Durée d'exécution maximale (en heures) pour l'ensemble de la tâche SQL. Maximum : 72 heures. | 24 h | — |
odps.sql.always.commit.result & odps.sql.runtime.flag.executionengine_EnableWorkerCommit |
Utilisés conjointement pour activer la validation partielle. Même si une tâche échoue en raison de certaines erreurs de traitement, les données traitées avec succès sont toujours validées. | — | À utiliser dans les pipelines ETL où un succès partiel est acceptable. |
Combinaison fixe pour les écritures de table et CMF
Lors de l'écriture dans des tables partitionnées dynamiques, appliquez conjointement les cinq indicateurs suivants. Cela garantit que les statistiques de stockage en colonnes (CMF) sont générées rapidement et correctement, ce qui est essentiel pour que les tâches en aval utilisent odps.sql.split.dop pour un découpage précis des données.
options.sql.settings = {
"odps.task.merge.enabled": "false",
"odps.sql.reshuffle.dynamicpt": "false",
"odps.sql.enable.dynaparts.stats.collection": "true",
"odps.optimizer.dynamic.partition.is.first.nth.value.split.enable": "false",
"odps.sql.stats.collection.aggressive": "true",
}Options MaxFrame
Configurez les options suivantes directement via options.<name>.
| Option | Description | Type | Valeur par défaut |
|---|---|---|---|
options.session.quota_name |
Quota à utiliser pour l'exécution des tâches. | str / None | None |
options.local_timezone |
Fuseau horaire local. Affecte le comportement par défaut des fonctions de date et d'heure. | str / None | None |
options.session.logview_hours |
Durée de conservation (en heures) des liens LogView. | int | 24 |
options.sql.enable_mcqa |
Indique s'il faut activer la fonctionnalité intégrée d'optimisation et d'accélération intelligente des requêtes de MaxCompute. | bool | True |
options.sql.generate_comments |
Ajoute automatiquement des commentaires aux instructions SQL générées pour la traçabilité. | bool | True |
options.sql.auto_use_common_image |
Configure automatiquement une image publique commune lorsque le système détecte que le code utilise des bibliothèques avec des dépendances supplémentaires. | bool | True |
options.session.max_alive_seconds |
Durée de vie maximale d'une session. | — | — |
options.session.max_idle_seconds |
Temps d'inactivité maximal d'une session. Si ce seuil est dépassé, la session est révoquée. Doit être inférieur ou égal à max_alive_seconds. |
— | — |
options.session.temp_table_lifecycle |
Cycle de vie par défaut (en jours) des tables temporaires créées par MaxFrame. | int | 1 |
options.session.auto_purge_temp_tables |
Nettoie automatiquement toutes les tables temporaires créées dans la session actuelle à la fin de celle-ci. | bool | False |
options.function.default_running_options |
Configuration des ressources par défaut pour les fonctions enregistrées avec le décorateur @remote. Clés : cpu, memory, gpu. |
dict | — |
options.dpe.settings = {"substep.public_network_whitelist": ["<ip_or_cidr>"]} |
Ajoute une liste d'autorisation d'accès au réseau public pour les UDF dans le moteur DPE. | — | — |
options.dpe.settings = {"substep.internal_network_whitelist": ["<ip_or_cidr>"]} |
Ajoute une liste d'autorisation d'accès au réseau interne pour les UDF dans le moteur DPE. | — | — |
Important
Avant de configurer des indicateurs avancés, en particulier ceux qui nécessitent une autorisation préalable (whitelisting) ou qui dépendent des statistiques CMF, contactez le support technique MaxCompute pour confirmer les prérequis et valider votre configuration.