table externe orc - MaxCompute - Centre de documentation Alibaba Cloud

Limites

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. Fractionnez 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 autorisations

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. Créez un rôle RAM, accordez-lui les autorisations nécessaires pour accéder au compartiment OSS cible, puis configurez l'ARN de ce rôle dans le paramètre odps.properties.rolearn. Pour plus d'informations, consultez la section Paramètres.
Vous pouvez autoriser l'accès au sein du même compte ou entre différents comptes selon vos besoins métier. Nous vous recommandons d'utiliser une stratégie 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 provenant de fichiers ORC, mais cette pratique n'est pas recommandée. Lors de la lecture de données STRING avec le type INT, les valeurs non numériques sont converties en NULL, tandis que 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 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 présentent 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 au format compressé. Aucune configuration de paramètre supplémentaire n'est requise pour lire les 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 sert de délimiteur clé-valeur, et le second 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 de 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 compartiment OSS et un répertoire. Pour plus d'informations, consultez les sections Créer un compartiment et Gérer les répertoires.

Assurez-vous que votre compartiment se trouve dans la même région que votre projet MaxCompute.
Accordez les autorisations.
1. Vous disposez des autorisations 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 autorisations, consultez la section Autorisation en mode STS pour OSS.
2. Vous disposez de l'autorisation CreateTable dans le projet MaxCompute. Pour plus d'informations sur les autorisations liées aux tables, consultez la section Autorisations 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 compartiment 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 des 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 des 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 sections 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 en charge uniquement 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. 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 par position et le mappage par nom.

Mappage par position (par défaut) : Définissez 'mcfed.orc.schema.resolution'='position' ou omettez la propriété. Les colonnes sont appariées selon leur ordre, de sorte que l'ordre des colonnes de la table doit correspondre exactement à l'ordre des champs dans le fichier ORC.
Mappage par 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. La position ne peut pas être spécifiée. 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 en utilisant le nouveau schéma. Par exemple, après l'ajout d'une colonne, les lignes historiques qui ne contiennent pas la nouvelle colonne renvoient NULL pour cette colonne.
Ajouter une colonne	Par nom	Oui
Supprimer une colonne	Par position	Non	Non recommandé. Le mappage par 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 en utilisant le nouveau schéma. Par exemple, après la suppression d'une colonne, les données historiques qui contiennent toujours la colonne supprimée provoquent des erreurs de lecture.
Supprimer une colonne	Par nom	Oui	Le mappage par nom associe les colonnes par nom, indépendamment de l'ordre des colonnes.	Compatible
Modifier l'ordre des colonnes	Par position	Non	Non recommandé. Le mappage par 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 en utilisant le 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ésalignement entre le schéma et les données.
Modifier l'ordre des colonnes	Par nom	Oui	Le mappage par nom associe 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 section 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	Non recommandé. Le mappage par nom associe les colonnes par nom. Après le renommage d'une colonne, les fichiers existants qui utilisent le nom d'origine ne peuvent plus correspondre.	Les nouvelles données correspondant au schéma mis à jour peuvent être lues normalement. Les données historiques écrites avant la modification sont lues en utilisant le 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 nullabilité d'une colonne	Par position	Non	Les colonnes sont nullable par défaut.	Sans objet
Modifier la nullabilité d'une colonne	Par nom	Non	Les colonnes sont nullable par défaut.	Sans objet