Tous les produits
Search
Centre de documentation

AnalyticDB:Utiliser une table externe pour importer des données depuis OSS

Dernière mise à jour :Sep 23, 2026

AnalyticDB for PostgreSQL peut importer des données depuis Object Storage Service (OSS) en parallèle grâce à la fonctionnalité de table externe gpossext. Chaque nœud de calcul lit simultanément les objets OSS, ce qui rend cette approche considérablement plus rapide que l'insertion ligne par ligne pour les chargements de données massifs.

Cette fonctionnalité s'applique uniquement aux instances AnalyticDB for PostgreSQL V6.0. Pour la version V7.0, consultez la rubrique Utilisation des tables externes OSS pour l'importation et l'exportation de données .

Fonctionnement

La fonctionnalité gpossext étend AnalyticDB for PostgreSQL avec un gestionnaire de protocole oss://. Après l'installation de l'extension oss_ext, vous définissez une table externe en lecture qui correspond aux objets OSS. Lorsque vous exécutez INSERT INTO ... SELECT * FROM, chaque nœud de calcul lit un sous-ensemble d'objets OSS en parallèle via un mécanisme d'interrogation, puis redistribue les lignes vers les partitions de destination appropriées.

OSS

gpossext prend en charge la lecture des fichiers TEXT et CSV, avec ou sans compression GZIP.

La syntaxe utilisée pour créer et utiliser des tables externes est identique à celle de Greenplum Database, à l'exception de la syntaxe des paramètres liés à l'emplacement.

Prérequis

Avant de commencer, assurez-vous de disposer des éléments suivants :

  • Une instance AnalyticDB for PostgreSQL V6.0

  • Un bucket OSS situé dans la même région que votre instance

  • Un AccessKey ID et un AccessKey secret disposant d'un accès en lecture au bucket

  • Des données source déjà téléchargées sur OSS sous forme de fichiers TEXT ou CSV (non compressés ou compressés au format GZIP)

Importer des données depuis OSS

Étape 1 : Installer l'extension oss_ext

Exécutez l'instruction suivante dans chaque base de données nécessitant un accès à OSS :

CREATE EXTENSION IF NOT EXISTS oss_ext;

Étape 2 : Répartir les fichiers source pour des lectures parallèles

Chaque nœud de calcul utilise un mécanisme d'interrogation pour s'attribuer les objets OSS. Pour optimiser le débit, définissez le nombre d'objets OSS comme un multiple entier du nombre de nœuds de calcul de votre instance. Par exemple, si vous disposez de 4 nœuds de calcul, utilisez 4, 8 ou 12 objets.

Pour plus d'informations sur la répartition du travail entre les nœuds de calcul, consultez la section Présentation des tables externes OSS.

Étape 3 : Créer une table externe en lecture

CREATE [READABLE] EXTERNAL TABLE tablename
    ( columnname datatype [, ...] | LIKE othertable )
    LOCATION ('ossprotocol')
    FORMAT 'TEXT'
        [( [HEADER]
           [DELIMITER [AS] 'delimiter' | 'OFF']
           [NULL [AS] 'null string']
           [ESCAPE [AS] 'escape' | 'OFF']
           [NEWLINE [ AS ] 'LF' | 'CR' | 'CRLF']
           [FILL MISSING FIELDS] )]
       | 'CSV'
        [( [HEADER]
           [QUOTE [AS] 'quote']
           [DELIMITER [AS] 'delimiter']
           [NULL [AS] 'null string']
           [FORCE NOT NULL column [, ...]]
           [ESCAPE [AS] 'escape']
           [NEWLINE [ AS ] 'LF' | 'CR' | 'CRLF']
           [FILL MISSING FIELDS] )]
    [ ENCODING 'encoding' ]
    [ [LOG ERRORS [INTO error_table]] SEGMENT REJECT LIMIT count
           [ROWS | PERCENT] ]
ossprotocol:
    oss://oss_endpoint [prefix=prefix_name|dir=[folder/[folder/]...]/file_name|filepath=[folder/[folder/]...]/file_name]
     id=userossid key=userosskey bucket=ossbucket compressiontype=[none|gzip] async=[true|false]

Paramètres obligatoires

Paramètre description
oss://oss_endpoint Endpoint OSS au format oss://oss_endpoint. Exemple : oss://oss-cn-hangzhou.aliyuncs.com. Si votre instance AnalyticDB s'exécute sur un serveur Alibaba Cloud, utilisez un endpoint interne (l'URL de l'endpoint contient le mot-clé internal) afin d'éviter les frais de trafic Internet.
id Votre AccessKey ID. Consultez la rubrique Créer une paire de clés d'accès.
key Votre AccessKey secret. Consultez la rubrique Créer une paire de clés d'accès.
bucket Nom du bucket OSS. Créez le bucket avant d'exécuter l'importation.

Paramètres de chemin (mutuellement exclusifs — spécifiez-en exactement un)

Paramètre description
prefix Préfixe de chemin pour les objets OSS. Importe tous les objets dont les chemins commencent par le préfixe. Les expressions régulières ne sont pas prises en charge. Par exemple, prefix=test/filename/ importe uniquement test/filename/aa, tandis que prefix=test/filename importe test/filename, test/filenamexxx, test/filename/aa, test/filenameyyy/aa et test/filenameyyy/bb/aa.
dir Chemin du répertoire OSS. Le chemin doit se terminer par / (exemple : test/mydir/). Importe tous les objets situés directement dans le répertoire, à l'exclusion des sous-répertoires.
filepath Nom de l'objet contenant le chemin de l'objet OSS. Réservé aux tables externes en lecture.

Paramètres facultatifs

Paramètre Valeur par défaut description
FORMAT — Format de fichier : TEXT ou CSV.
ENCODING — Encodage des caractères des objets, tel que utf8.
compressiontype none Format de compression. Valeurs valides : none, gzip.
compressionlevel 6 Niveau de compression pour les fichiers écrits sur OSS. Valeurs valides : 1–9.
async true Active l'importation asynchrone à l'aide de threads auxiliaires. Définissez la valeur sur false ou f pour désactiver cette option. L'importation asynchrone consomme davantage de ressources matérielles que l'importation de données standard.
oss_connect_timeout 10 (secondes) Délai d'expiration de la connexion.
oss_dns_cache_timeout 60 (secondes) Délai d'expiration de la résolution DNS.
oss_speed_limit 1024 (octets/s) Taux de transmission minimal. Doit être configuré conjointement avec oss_speed_time.
oss_speed_time 15 (secondes) Durée maximale pendant laquelle le taux de transmission peut rester inférieur à oss_speed_limit avant qu'un délai d'expiration ne se produise. Doit être configuré conjointement avec oss_speed_limit. Avec les valeurs par défaut, un délai d'expiration se déclenche si le taux reste inférieur à 1 Ko/s pendant 15 secondes consécutives.
LOG ERRORS — Ignore les lignes dont l'importation échoue et les écrit dans error_table. Utilisez count pour définir le seuil de tolérance aux erreurs.

Étape 4 : (Facultatif) Vérifier que la table externe est lisible

Avant d'exécuter l'importation complète, confirmez que la table externe peut lire les données depuis OSS :

-- Check a sample of rows
SELECT * FROM <External table> LIMIT 10;

-- Inspect the query plan to confirm parallel reads
EXPLAIN INSERT INTO <Destination table> SELECT * FROM <External table>;

Le plan de requête doit afficher des nœuds External Scan s'exécutant sur tous les segments, confirmant ainsi que les nœuds de calcul liront les objets OSS en parallèle.

Étape 5 : Exécuter l'importation parallèle

INSERT INTO <Destination table> SELECT * FROM <External table>;

Chaque nœud de calcul lit les objets OSS qui lui sont attribués et insère les lignes dans la table de destination. Le nœud de mouvement de redistribution hache les lignes et les achemine vers les nœuds de calcul appropriés en fonction de la clé de distribution.

Exemple

Cet exemple importe des données boursières depuis OSS vers une table nommée example.

1. Installez l'extension.

CREATE EXTENSION IF NOT EXISTS oss_ext;

2. Créez la table de destination.

CREATE TABLE example
    (date text, time text, open float,
     high float, low float, volume int)
    DISTRIBUTED BY (date);

Pour optimiser les performances d'importation, utilisez un stockage orienté colonne avec compression. Par exemple, vous pouvez spécifier la clause suivante : WITH (APPENDONLY=true, ORIENTATION=column, COMPRESSTYPE=zlib, COMPRESSLEVEL=5, BLOCKSIZE=1048576). Pour plus d'informations, consultez la documentation relative à la commande CREATE TABLE.

3. Créez la table externe. Choisissez le paramètre de chemin correspondant à l'organisation de vos fichiers sur OSS.

Utilisation de prefix (importe tous les objets dont le chemin correspond au préfixe, prend en charge GZIP) :

CREATE READABLE EXTERNAL TABLE ossexample
    (date text, time text, open float, high float,
    low float, volume int)
    location('oss://oss-cn-hangzhou.aliyuncs.com
    prefix=osstest/example id=XXX
    key=XXX bucket=testbucket compressiontype=gzip')
    FORMAT 'csv' (QUOTE '''' DELIMITER E'\t')
    ENCODING 'utf8'
    LOG ERRORS SEGMENT REJECT LIMIT 5;

Utilisation de dir (importe tous les objets situés directement dans le répertoire, sans GZIP) :

CREATE READABLE EXTERNAL TABLE ossexample
    (date text, time text, open float, high float,
    low float, volume int)
    location('oss://oss-cn-hangzhou.aliyuncs.com
    dir=osstest/ id=XXX
    key=XXX bucket=testbucket')
    FORMAT 'csv'
    LOG ERRORS SEGMENT REJECT LIMIT 5;

Utilisation de filepath (importe l'objet spécifié) :

CREATE READABLE EXTERNAL TABLE ossexample
    (date text, time text, open float, high float,
    low float, volume int)
    location('oss://oss-cn-hangzhou.aliyuncs.com
    filepath=osstest/example.csv id=XXX
    key=XXX bucket=testbucket')
    FORMAT 'csv'
    LOG ERRORS SEGMENT REJECT LIMIT 5;

4. Importez les données.

INSERT INTO example SELECT * FROM ossexample;

Le plan de requête confirme que les quatre nœuds de calcul lisent les données depuis OSS en parallèle :

EXPLAIN INSERT INTO example SELECT * FROM ossexample;
                                            QUERY PLAN
-------------------------------------------------------------------------------------------------
 Insert (slice0; segments: 4)  (rows=250000 width=92)
   ->  Redistribute Motion 4:4  (slice1; segments: 4)  (cost=0.00..11000.00 rows=250000 width=92)
         Hash Key: ossexample.date
         ->  External Scan on ossexample  (cost=0.00..11000.00 rows=250000 width=92)
(4 rows)

Référence des formats TEXT et CSV

Les paramètres suivants contrôlent la manière dont gpossext analyse les fichiers TEXT et CSV. Spécifiez-les dans la clause FORMAT de votre instruction CREATE EXTERNAL TABLE.

  • \n : délimiteur de ligne (caractère de saut de ligne)

  • DELIMITER : séparateur de colonne. Si ce paramètre est spécifié, QUOTE doit également l'être. Choix courants : ,, |, \t.

  • QUOTE : entoure les valeurs de colonne contenant des caractères spéciaux. Doit différer de DELIMITER. Valeur par défaut : ". Les valeurs contenant des caractères QUOTE doivent également utiliser ESCAPE.

  • ESCAPE : placé avant tout caractère devant être traité comme un littéral. Valeur par défaut : identique à QUOTE. La barre oblique inverse (\) est également couramment utilisée.

Tous les caractères de contrôle doivent être codés sur un seul octet.

Caractères de contrôle par défaut

Caractère de contrôle TEXT CSV
DELIMITER \t (Tabulation) , (Virgule)
QUOTE " (Guillemet double) " (Guillemet double)
ESCAPE N/A " (Guillemet double)
NULL \N (Barre oblique inverse n) Chaîne vide sans guillemets

Dépannage

Examiner les erreurs d'importation

Si vous avez utilisé LOG ERRORS lors de la création de la table externe, récupérez les lignes ayant échoué à l'aide de la commande suivante :

SELECT * FROM gp_read_error_log('external_table_name');

Pour effacer le journal des erreurs après consultation :

SELECT gp_truncate_error_log('external_table_name');
Le journal des erreurs est supprimé automatiquement lorsque vous supprimez la table externe.

Interpréter les champs d'erreur du SDK

Les erreurs du SDK OSS dans le journal d'importation incluent les champs suivants :

Champ description
code Code d'état HTTP de la requête ayant échoué
error_code Code d'erreur OSS
error_msg Message d'erreur OSS
req_id UUID de la requête ayant échoué. Fournissez cet identifiant au support Alibaba Cloud lors du signalement de problèmes persistants.

Pour plus de détails sur les codes d'erreur OSS, consultez la rubrique Réponses d'erreur.

Résoudre les erreurs de délai d'expiration

Ajustez conjointement oss_speed_limit et oss_speed_time pour affiner le comportement des délais d'expiration. Pour la gestion générale des délais d'expiration OSS, consultez la rubrique Gestion des erreursGestion des erreurs.

Étapes suivantes