orc external table - MaxCompute - Centre de documentation Alibaba Cloud

Contraintes

Les tables externes OSS ne prennent pas en charge la propriété cluster.
La taille d'un fichier unique ne peut pas dépasser 2 Go. Vous devez fractionner les fichiers dont la taille est supérieure à 2 Go.
MaxCompute et OSS doivent se trouver dans la même région.
Types de données pris en charge.
Formats de compression pris en charge.
Évolution du schéma prise en charge.

Description des permissions

Lorsque vous accédez aux tables externes OSS, les données sont consultées via le rôle spécifié dans le paramètre odps.properties.rolearn, que vous utilisiez un compte Alibaba Cloud, un utilisateur RAM ou un rôle RAM. Par conséquent, vous devez créer un rôle RAM, lui accorder les permissions d'accès au bucket OSS cible, puis configurer l'ARN du rôle dans le paramètre odps.properties.rolearn. Pour plus d'informations, consultez la section Paramètres.
Vous pouvez autoriser l'accès depuis le même compte ou entre différents comptes selon vos besoins métier. Nous vous recommandons d'utiliser une politique d'autorisation personnalisée pour un contrôle d'accès plus granulaire. Pour plus d'informations, consultez la section Autorisation pour les sources de données externes.

Créer une table externe

Syntaxe

Si le schéma du fichier ORC et celui de la table externe ne correspondent pas, MaxCompute gère les différences comme suit :

Moins de colonnes dans le fichier que dans la table : Les colonnes manquantes sont remplies par la valeur NULL.
Plus de colonnes dans le fichier que dans la table : Les colonnes supplémentaires sont ignorées.
Incompatibilité de type : Le type STRING peut lire des données INT à partir de fichiers ORC, mais cette pratique n'est pas recommandée. Lorsqu'une colonne INT lit des données STRING, les valeurs non numériques sont converties en NULL et les valeurs numériques sont acceptées.

Utilisez la syntaxe simplifiée ou la syntaxe complète pour créer une table externe ORC.

Syntaxe simplifiée (recommandée)

Utilisez cette syntaxe lorsque vous souhaitez que MaxCompute gère automatiquement l'autorisation à l'aide du rôle RAM par défaut.

CREATE EXTERNAL TABLE [IF NOT EXISTS] <mc_oss_extable_name>
(
  <col_name> <data_type>,
  ...
)
[COMMENT <table_comment>]
[PARTITIONED BY (<col_name> <data_type>, ...)]
STORED AS orc
LOCATION '<oss_location>';

Syntaxe complète

CREATE EXTERNAL TABLE [IF NOT EXISTS] <mc_oss_extable_name>
(
  <col_name> <data_type>,
  ...
)
[COMMENT <table_comment>]
[PARTITIONED BY (<col_name> <data_type>, ...)]
ROW FORMAT SERDE 'org.apache.hadoop.hive.ql.io.orc.OrcSerde'
WITH serdeproperties(
    'odps.properties.rolearn'='acs:ram::<uid>:role/<role_name>'
)
STORED AS orc
LOCATION '<oss_location>'
tblproperties (
    '<xxx>'='<yyy>'
);

Paramètres courants

Pour plus d'informations sur les paramètres courants, consultez la section Paramètres de la syntaxe de base.

Paramètres spécifiques au format

WITH serdeproperties

Propriété

Cas d'utilisation

Valeur

Valeur par défaut

mcfed.orc.schema.resolution

Les fichiers ORC d'une même table externe ont des schémas incohérents.

name — mappe les colonnes par nom.

position — mappe les colonnes par position.

tblproperties

Propriété	Cas d'utilisation	Description	Valeur	Valeur par défaut
`mcfed.orc.compress`	Écrire des données ORC dans OSS avec un format compressé. Aucune configuration de paramètre supplémentaire n'est requise lors de la lecture de fichiers compressés.	Algorithme de compression pour les fichiers de sortie ORC.	`SNAPPY`, `ZLIB` ou `ZSTD`	Aucune
`odps.external.data.output.prefix` (également `odps.external.data.prefix`)	Ajouter un préfixe personnalisé aux fichiers de sortie.	Chaîne de préfixe. Caractères autorisés : lettres, chiffres et traits de soulignement (a–z, A–Z, 0–9, _). Longueur : 1 à 10 caractères.	Exemple : `mc_`	Aucune
`odps.external.data.enable.extension`	Contrôler si les fichiers de sortie incluent une extension de fichier.	`True` affiche l'extension ; `False` la masque.	`True` ou `False`	`False`
`odps.external.data.output.suffix`	Ajouter un suffixe personnalisé aux fichiers de sortie.	Chaîne de suffixe. Caractères autorisés : lettres, chiffres et traits de soulignement.	Exemple : `_hangzhou`	Aucune
`odps.external.data.output.explicit.extension`	Ajouter une extension personnalisée aux fichiers de sortie. Cette option est prioritaire sur `odps.external.data.enable.extension`.	Chaîne d'extension. Caractères autorisés : lettres, chiffres et traits de soulignement. Longueur : 1 à 10 caractères.	Exemple : `jsonl`	Aucune
odps.ext.column.mapping	Ajoutez cette propriété lorsque les noms de champs dans les fichiers de données OSS contiennent des caractères spéciaux.	Cette propriété définit des mappages de noms de colonnes personnalisés. Par exemple, si les champs du fichier OSS sont id BIGINT, $_test DOUBLE et =name STRING, définissez la valeur du paramètre sur t_test:$_test,t_name:=_name lors de la création de la table externe. Vous devez uniquement spécifier les mappages pour les champs contenant des caractères spéciaux.	Aucune valeur fixe	Aucune
odps.ext.column.mapping.delimiters (À utiliser uniquement lorsque les caractères des noms de colonnes entrent en conflit avec les délimiteurs par défaut dans les mappages de noms de colonnes. Généralement non recommandé.)	Ajoutez cette propriété lorsque les noms de colonnes contiennent les caractères spéciaux `:` ou `,`	Cette propriété personnalise les délimiteurs intra-groupe et inter-groupe pour les paires clé-valeur. La valeur doit contenir exactement deux caractères : le premier caractère sert de délimiteur clé-valeur, et le second caractère sert de délimiteur entre les différentes paires clé-valeur.	Aucune valeur fixe. Exemple : `=\|.`	Valeur par défaut : `':,'` Par défaut, `':'` est utilisé comme délimiteur entre les clés et les valeurs. La virgule `','` est utilisée comme délimiteur entre les différentes paires clé-valeur. Les espaces de début et de fin dans les clés et les valeurs sont supprimés lors de l'analyse.
`mcfed.orc.batch.size`	Optimiser l'utilisation de la mémoire et le débit de traitement.	Nombre de lignes traitées par lot (taille du lot ORC).	Entier non négatif	`1000`

Liste blanche et liste noire

Les tables externes OSS MaxCompute prennent en charge le filtrage par liste blanche et liste noire. En définissant les paramètres de liste blanche et de liste noire dans tblproperties, vous pouvez filtrer les fichiers à lire depuis un répertoire. Pour plus de détails, consultez la section Liste blanche et liste noire.

Écrire des données

Pour plus de détails sur la syntaxe d'écriture dans MaxCompute, consultez la section Syntaxe d'écriture.

Interroger des données

Consultez la section Syntaxe de requête pour plus de détails sur la syntaxe SELECT.
Consultez la section Optimisation des requêtes pour plus de détails sur l'optimisation des plans de requête.
Activer le pushdown de prédicat

Le pushdown de prédicat (PPD) améliore les performances des requêtes sur les tables externes ORC en poussant les conditions de filtre vers la couche d'analyse des données. Le PPD nécessite le mode natif (odps.ext.oss.orc.native=true).

Ajoutez les instructions suivantes avant votre requête SQL :
```
-- Enable the ORC native reader
SET odps.ext.oss.orc.native=true;

-- Enable ORC predicate pushdown
SET odps.storage.orc.use.predicate.pushdown=true;
```

Exemple

Cet exemple crée une table externe ORC avec compression SNAPPY, ajoute une partition existante, lit des données et écrit une nouvelle ligne.

Prérequis

Vous avez créé un projet MaxCompute.
Vous avez préparé un bucket et un répertoire OSS. Pour plus d'informations, consultez les sections Créer un bucket et Gérer les répertoires.

Assurez-vous que votre bucket se trouve dans la même région que votre projet MaxCompute.
Accordez les permissions.
1. Vous disposez des permissions nécessaires pour accéder à OSS. Vous pouvez accéder à une table externe OSS en utilisant un compte Alibaba Cloud, un utilisateur RAM ou un rôle RAM. Pour plus d'informations sur l'octroi des permissions, consultez la section Autorisation en mode STS pour OSS.
2. Vous disposez de la permission CreateTable dans le projet MaxCompute. Pour plus d'informations sur les permissions liées aux tables, consultez la section Permissions MaxCompute.

Étape 1 : Préparer le fichier de données

En utilisant les données d'exemple fournies, créez le chemin de dossier orc_snappy/dt=20250526 dans le bucket oss-mc-test. Téléchargez le fichier snappy dans le dossier de partition dt=20250526.

Étape 2 : Créer la table externe

CREATE EXTERNAL TABLE orc_data_type_snappy
(
    vehicleId INT,
    recordId INT,
    patientId INT,
    calls INT,
    locationLatitute DOUBLE,
    locationLongitude DOUBLE,
    recordTime STRING,
    direction STRING
)
PARTITIONED BY (dt STRING)
ROW FORMAT SERDE 'org.apache.hadoop.hive.ql.io.orc.OrcSerde'
WITH serdeproperties (
    'odps.properties.rolearn'='acs:ram::<uid>:role/<role_name>'
)
STORED AS ORC
LOCATION 'oss://oss-cn-hangzhou-internal.aliyuncs.com/oss-mc-test/orc_snappy/'
tblproperties (
    'mcfed.orc.compress'='SNAPPY'
);

Étape 3 : Ajouter les partitions existantes

Pour les tables externes partitionnées, exécutez MSCK REPAIR TABLE pour enregistrer les partitions OSS existantes dans MaxCompute. Pour la syntaxe complète, consultez la section Ajout de partitions à une table externe OSS.

MSCK REPAIR TABLE orc_data_type_snappy ADD PARTITIONS;

Étape 4 : Lire les données

SELECT * FROM orc_data_type_snappy WHERE dt = '20250526' LIMIT 10;

La requête renvoie :

+------------+------------+------------+------------+------------------+-------------------+----------------+------------+------------+
| vehicleid  | recordid   | patientid  | calls      | locationlatitute | locationlongitude | recordtime     | direction  | dt         |
+------------+------------+------------+------------+------------------+-------------------+----------------+------------+------------+
| 1          | 12         | 76         | 1          | 46.81006         | -92.08174         | 9/14/2014 0:10 | SW         | 20250526   |
| 1          | 1          | 51         | 1          | 46.81006         | -92.08174         | 9/14/2014 0:00 | S          | 20250526   |
| 1          | 2          | 13         | 1          | 46.81006         | -92.08174         | 9/14/2014 0:01 | NE         | 20250526   |
| 1          | 3          | 48         | 1          | 46.81006         | -92.08174         | 9/14/2014 0:02 | NE         | 20250526   |
| 1          | 4          | 30         | 1          | 46.81006         | -92.08174         | 9/14/2014 0:03 | W          | 20250526   |
| 1          | 5          | 47         | 1          | 46.81006         | -92.08174         | 9/14/2014 0:04 | S          | 20250526   |
| 1          | 6          | 9          | 1          | 46.81006         | -92.08174         | 9/14/2014 0:05 | S          | 20250526   |
| 1          | 7          | 53         | 1          | 46.81006         | -92.08174         | 9/14/2014 0:06 | N          | 20250526   |
| 1          | 8          | 63         | 1          | 46.81006         | -92.08174         | 9/14/2014 0:07 | SW         | 20250526   |
| 1          | 9          | 4          | 1          | 46.81006         | -92.08174         | 9/14/2014 0:08 | NE         | 20250526   |
| 1          | 10         | 31         | 1          | 46.81006         | -92.08174         | 9/14/2014 0:09 | N          | 20250526   |
+------------+------------+------------+------------+------------------+-------------------+----------------+------------+------------+

Étape 5 : Écrire des données

INSERT INTO orc_data_type_snappy PARTITION (dt = '20250526')
  VALUES (1, 16, 76, 1, 46.81006, -92.08174, '9/14/2014 0:10', 'SW');

-- Verify the inserted row
SELECT * FROM orc_data_type_snappy WHERE dt = '20250526' AND recordid = 16;

La requête renvoie :

+------------+------------+------------+------------+------------------+-------------------+----------------+------------+------------+
| vehicleid  | recordid   | patientid  | calls      | locationlatitute | locationlongitude | recordtime     | direction  | dt         |
+------------+------------+------------+------------+------------------+-------------------+----------------+------------+------------+
| 1          | 16         | 76         | 1          | 46.81006         | -92.08174         | 9/14/2014 0:10 | SW         | 20250526   |
+------------+------------+------------+------------+------------------+-------------------+----------------+------------+------------+

Types de données pris en charge

Pour obtenir la liste complète des types de données MaxCompute, consultez les rubriques Type de données version 1.0 et Type de données version 2.0.

MaxCompute prend en charge deux modes pour la lecture des tables externes ORC :

Mode JNI (SET odps.ext.oss.orc.native=false;) : prend en charge les opérations de lecture et d'écriture.
Mode natif (SET odps.ext.oss.orc.native=true;) : prend uniquement en charge les opérations de lecture.

Type de données

Mode JNI (lecture et écriture)

Mode natif (lecture uniquement)

TINYINT

Oui

SMALLINT

Oui

INT

Oui

BIGINT

Oui

BINARY

Oui

FLOAT

Oui

DOUBLE

Oui

DECIMAL(précision, échelle)

Oui

VARCHAR(n)

Oui

CHAR(n)

Oui

STRING

Oui

DATE

Oui

DATETIME

Non

Oui

TIMESTAMP

Non

TIMESTAMP_NTZ

Oui

Non

BOOLEAN

Oui

ARRAY

Oui

MAP

Oui

STRUCT

Oui

JSON

Non

Formats de compression pris en charge

Pour lire ou écrire des fichiers ORC compressés, ajoutez la propriété mcfed.orc.compress à la section with serdeproperties lors de la création de la table. Pour plus d'informations, consultez la section WITH serdeproperties.

Propriétés de compression

Lecture

Écriture

ZSTD

Oui

SNAPPY（SnappyRawCodec）

Oui

SNAPPY（SnappyCodec）

Oui

Non

ZLIB

Oui

Évolution du schéma prise en charge

Les tables externes ORC prennent en charge deux méthodes pour mapper les colonnes de la table aux champs du fichier ORC : le mappage basé sur la position et le mappage basé sur le nom.

Mappage basé sur la position (par défaut) : définissez 'mcfed.orc.schema.resolution'='position' ou omettez la propriété. Les colonnes sont appariées selon leur ordre ; l'ordre des colonnes de la table doit donc correspondre exactement à l'ordre des champs dans le fichier ORC.
Mappage basé sur le nom : définissez 'mcfed.orc.schema.resolution'='name'. Les colonnes sont appariées par nom, indépendamment de l'ordre.

Remarque

Le tableau ci-dessous indique quelles opérations de modification de schéma sont compatibles avec chaque méthode de mappage. « Compatible » signifie que les nouvelles données écrites et les données historiques peuvent être lues correctement après l'opération.

Modification du schéma	Mode de mappage	Pris en charge	Description	Compatibilité des données
Ajouter une colonne	Par position	Oui	Les nouvelles colonnes sont ajoutées à la fin. Il n'est pas possible de spécifier la position. Les valeurs par défaut des colonnes ajoutées s'appliquent uniquement aux données écrites par MaxCompute après la modification.	Les nouvelles données correspondant au schéma mis à jour peuvent être lues normalement. Les données historiques écrites avant la modification sont lues à l'aide du nouveau schéma. Par exemple, après l'ajout d'une colonne, les lignes historiques ne contenant pas la nouvelle colonne renvoient NULL pour cette colonne.
Ajouter une colonne	Par nom	Oui
Supprimer une colonne	Par position	Non	Déconseillé. Le mappage basé sur la position exige que l'ordre des colonnes dans le DDL corresponde à celui du fichier. Après la suppression d'une colonne, les schémas du DDL et du fichier divergent, ce qui provoque des erreurs de lecture.	Les nouvelles données correspondant au schéma mis à jour peuvent être lues normalement. Les données historiques écrites avant la modification sont lues à l'aide du nouveau schéma. Par exemple, après la suppression d'une colonne, les données historiques contenant toujours la colonne supprimée provoquent des erreurs de lecture.
Supprimer une colonne	Par nom	Oui	Le mappage basé sur le nom apparie les colonnes par nom, indépendamment de l'ordre des colonnes.	Compatible
Modifier l'ordre des colonnes	Par position	Non	Déconseillé. Le mappage basé sur la position exige que l'ordre des colonnes dans le DDL corresponde à celui du fichier. Après le réordonnancement des colonnes, les schémas du DDL et du fichier divergent, ce qui provoque des erreurs de lecture.	Les nouvelles données correspondant au schéma mis à jour peuvent être lues normalement. Les données historiques écrites avant la modification sont lues à l'aide du nouveau schéma. Par exemple, après le réordonnancement des colonnes, les données historiques conservent l'ordre d'origine, ce qui entraîne un décalage entre le schéma et les données.
Modifier l'ordre des colonnes	Par nom	Oui	Le mappage basé sur le nom apparie les colonnes par nom, indépendamment de l'ordre des colonnes.	Compatible
Modifier le type de données d'une colonne	Par position	Oui	Pour connaître les conversions de type autorisées, consultez la rubrique Modifier le type de données d'une colonne.	Compatible
Modifier le type de données d'une colonne	Par nom	Oui		Compatible
Renommer une colonne	Par position	Oui		Compatible
Renommer une colonne	Par nom	Non	Déconseillé. Le mappage basé sur le nom apparie les colonnes par nom. Après le renommage d'une colonne, les fichiers existants utilisant le nom d'origine ne peuvent plus être appariés.	Les nouvelles données correspondant au schéma mis à jour peuvent être lues normalement. Les données historiques écrites avant la modification sont lues à l'aide du nouveau schéma. Par exemple, après le renommage d'une colonne, si le schéma du fichier ORC utilise toujours le nom d'origine, la colonne renvoie NULL lors de la lecture.
Modifier le commentaire d'une colonne	Par position	Oui	Le commentaire doit être une chaîne valide ne dépassant pas 1 024 octets.	Compatible
Modifier le commentaire d'une colonne	Par nom	Oui		Compatible
Modifier la possibilité de valeur NULL d'une colonne	Par position	Non	Les colonnes acceptent les valeurs NULL par défaut.	Sans objet
Modifier la possibilité de valeur NULL d'une colonne	Par nom	Non	Les colonnes acceptent les valeurs NULL par défaut.	Sans objet