Hologres:EXTERNAL_FILES

Configuration des autorisations

La fonction EXTERNAL_FILES accède à OSS via un rôle RAM. Suivez les étapes ci-dessous avant d'utiliser EXTERNAL_FILES.

Étape 1 : Créer un rôle RAM

1. Connectez-vous à la console RAM et accédez à Rôles RAM.

2. Cliquez sur Create Role.

3. Dans la boîte de dialogue, définissez Trusted Entity Type sur Cloud Service et Trusted Entity sur Real-time Data Warehouse Hologres.

4. Saisissez un nom de rôle et finalisez la création.

Étape 2 : Accorder des autorisations OSS au rôle

Attachez une stratégie OSS au rôle RAM selon les opérations requises :

• Lire des données : attachez la stratégie AliyunOSSReadOnlyAccess.

• Écrire des données : attachez la stratégie AliyunOSSFullAccess.

Étape 3 : Accorder l'autorisation GrantAssumeRole aux utilisateurs RAM

Ignorez cette étape si l'utilisateur qui exécute le code SQL est un compte Alibaba Cloud. Pour les utilisateurs RAM, accordez-leur l'autorisation GrantAssumeRole comme suit :

1. Dans la console RAM, accédez à Policies et cliquez sur Create Policy.

2. Basculez vers l'éditeur Script Editor et collez le code JSON suivant. Remplacez <RoleARN> par l'ARN du rôle créé. Pour trouver l'ARN, consultez la rubrique FAQ sur les rôles RAM et les jetons STS.

   {
     "Version": "1",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": "hologram:GrantAssumeRole",
         "Resource": "<RoleARN>"
       }
     ]
   }

3. Attachez cette stratégie à l'utilisateur :

   • Pour un utilisateur RAM : accédez à Users > Permissions > Add Permissions.

   • Pour un rôle RAM : accédez à Roles > Permissions > Add Permissions.

SELECT * FROM EXTERNAL_FILES(
    path = 'oss://bucket/path',
    format = 'csv|parquet|orc',
    oss_endpoint = 'oss_endpoint',
    role_arn = 'acs:ram::xxx:role/xxx'
    [, other parameters...]
) [AS (col1 type1, col2 type2, ...)]

INSERT INTO target_table
SELECT * FROM EXTERNAL_FILES(
    path = 'oss://bucket/path',
    format = 'csv|parquet|orc',
    oss_endpoint = 'oss_endpoint',
    role_arn = 'acs:ram::xxx:role/xxx'
    [, other parameters...]
) [AS (col1 type1, col2 type2, ...)]

INSERT INTO EXTERNAL_FILES(
    path = 'oss://bucket/path',
    format = 'csv',
    oss_endpoint = 'oss_endpoint',
    role_arn = 'acs:ram::xxx:role/xxx'
    [, other parameters...]
) SELECT * FROM source_table;

Paramètres communs

Caractères génériques pris en charge dans path

Paramètres de lecture

Paramètres d'écriture

Interroger un fichier CSV

Interrogez un fichier CSV avec inférence automatique du schéma :

SELECT * FROM EXTERNAL_FILES(
    path = 'oss://mybucket/data/',
    format = 'csv',
    csv_skip_header = 'true',
    csv_delimiter = ',',
    oss_endpoint = 'oss-cn-hangzhou-internal.aliyuncs.com',
    role_arn = 'acs:ram::123456789:role/hologres-role'
);

Interrogez un fichier CSV avec un schéma spécifié manuellement :

SELECT * FROM EXTERNAL_FILES(
    path = 'oss://mybucket/data/',
    format = 'csv',
    csv_skip_header = 'true',
    oss_endpoint = 'oss-cn-hangzhou-internal.aliyuncs.com',
    role_arn = 'acs:ram::123456789:role/hologres-role'
) AS (id int, name text, amount decimal(10,2));

Interroger un fichier Parquet

SELECT * FROM EXTERNAL_FILES(
    path = 'oss://mybucket/parquet_data/',
    format = 'parquet',
    oss_endpoint = 'oss-cn-hangzhou-internal.aliyuncs.com',
    role_arn = 'acs:ram::123456789:role/hologres-role'
);

Interroger un fichier ORC

SELECT * FROM EXTERNAL_FILES(
    path = 'oss://mybucket/orc_data/',
    format = 'orc',
    oss_endpoint = 'oss-cn-hangzhou-internal.aliyuncs.com',
    role_arn = 'acs:ram::123456789:role/hologres-role'
);

Importer des données dans une table Hologres

-- Create the target table
CREATE TABLE orders (
    order_id int,
    customer_name text,
    amount decimal(10,2),
    PRIMARY KEY(order_id)
);

-- Import data from OSS
INSERT INTO orders
SELECT * FROM EXTERNAL_FILES(
    path = 'oss://mybucket/orders/',
    format = 'csv',
    csv_skip_header = 'true',
    oss_endpoint = 'oss-cn-hangzhou-internal.aliyuncs.com',
    role_arn = 'acs:ram::123456789:role/hologres-role'
) AS (order_id int, customer_name text, amount decimal(10,2));

Exporter des données vers OSS

Exportez vers plusieurs fichiers avec une limite de taille par fichier :

INSERT INTO EXTERNAL_FILES(
    path = 'oss://mybucket/export/',
    format = 'csv',
    oss_endpoint = 'oss-cn-hangzhou-internal.aliyuncs.com',
    role_arn = 'acs:ram::123456789:role/hologres-role',
    target_file_size_mb = '100'
) SELECT * FROM orders;

Exportez toutes les données vers un seul fichier :

INSERT INTO EXTERNAL_FILES(
    path = 'oss://mybucket/export/',
    format = 'csv',
    oss_endpoint = 'oss-cn-hangzhou-internal.aliyuncs.com',
    role_arn = 'acs:ram::123456789:role/hologres-role',
    single_file = 'true'
) SELECT * FROM orders;

Utiliser un groupe de ressources serverless

SET hg_computing_resource = 'serverless';

SELECT * FROM EXTERNAL_FILES(
    path = 'oss://mybucket/data/',
    format = 'csv',
    oss_endpoint = 'oss-cn-hangzhou-internal.aliyuncs.com',
    role_arn = 'acs:ram::123456789:role/hologres-role'
);

Inférence automatique

Si vous omettez la clause AS, Hologres déduit automatiquement le schéma :

• Parquet et ORC : le schéma est déduit à partir des métadonnées du fichier.

• CSV avec ligne d'en-tête : le schéma est déduit à partir de l'en-tête et du contenu des données. Définissez csv_skip_header = 'true' afin que la ligne d'en-tête ne soit pas lue comme des données.

• CSV sans ligne d'en-tête : tous les fichiers du chemin doivent présenter une structure de colonnes identique.

Hologres analyse jusqu'à schema_deduce_file_num fichiers (valeur par défaut : 5) et fusionne l'ensemble des schémas découverts.

Comportement en cas de non-concordance du schéma

Lorsque le schéma déduit ou spécifié ne correspond pas exactement au contenu du fichier, Hologres gère les divergences comme suit :

Exemple : interrogation de fichiers avec des colonnes non concordantes

Supposons que vous disposiez de deux fichiers CSV dans le même chemin :

orders_jan.csv — 3 colonnes : order_id, customer_name, amount

orders_feb.csv — 4 colonnes : order_id, customer_name, amount, region

Lorsque vous interrogez le chemin sans spécifier de schéma, Hologres fusionne les deux schémas. Les lignes issues de orders_jan.csv renvoient NULL dans la colonne region :

SELECT * FROM EXTERNAL_FILES(
    path = 'oss://mybucket/orders/',
    format = 'csv',
    csv_skip_header = 'true',
    oss_endpoint = 'oss-cn-hangzhou-internal.aliyuncs.com',
    role_arn = 'acs:ram::123456789:role/hologres-role'
);

Pour éviter les valeurs NULL inattendues, spécifiez explicitement le schéma à l'aide de la clause AS, ou assurez-vous que tous les fichiers partagent la même structure de colonnes.

Mappage des types

Mappage des types ORC

Les types ORC UNION , STRUCT et MAP ne sont pas pris en charge.

Mappage des types Parquet

Les types Parquet STRUCT et MAP ne sont pas pris en charge.