Commande COPY depuis Amazon S3

Pour charger des données à partir de fichiers situés dans un ou plusieurs compartiments S3, utilisez la clause FROM pour indiquer comment la commande COPY localise les fichiers dans Amazon S3. Vous pouvez fournir le chemin d’objet aux fichiers de données dans le cadre de la clause FROM, ou vous pouvez fournir l’emplacement d’un fichier manifeste qui contient une liste de chemins d’objets Amazon S3. L’exécution de la commande COPY à partir d’Amazon S3 utilise une connexion HTTPS. Assurez-vous que les plages d’adresses IP S3 sont ajoutées à votre liste des autorisations. Pour plus d’informations sur les plages d’adresses IP S3 requises, consultez Isolement de réseau.

Important

Si les compartiments Amazon S3 contenant les fichiers de données ne résident pas dans la même région AWS que votre cluster, vous devez utiliser le paramètre REGION pour spécifier la région dans laquelle les données se trouvent.

Syntaxe

FROM { 's3://objectpath' | 's3://manifest_file' }
authorization
| MANIFEST
| ENCRYPTED
| REGION [AS] 'aws-region'
| optional-parameters

Exemples

L’exemple suivant utilise un chemin d’objet pour charger les données à partir d’Amazon S3.

copy customer
from 's3://mybucket/customer' 
iam_role 'arn:aws:iam::0123456789012:role/MyRedshiftRole';

L’exemple suivant utilise un fichier manifeste pour charger les données à partir d’Amazon S3.

copy customer
from 's3://mybucket/cust.manifest' 
iam_role 'arn:aws:iam::0123456789012:role/MyRedshiftRole'
manifest;      

Paramètres

FROM

Source des données à charger. Pour plus d’informations sur l’encodage du fichier Amazon S3, consultez Paramètres de conversion de données.

’s3://copy_from_s3_objectpath’

Spécifie le chemin d’accès aux objets Amazon S3 contenant les données (par exemple 's3://mybucket/custdata.txt'). Le paramètre s3://copy_from_s3_objectpath peut faire référence à un seul fichier ou à un ensemble d’objets ou de dossiers ayant le même préfixe de clé. Par exemple, le nom custdata.txt est un préfixe de clé qui fait référence à un certain nombre de fichiers physiques : custdata.txt, custdata.txt.1, custdata.txt.2, custdata.txt.bak et ainsi de suite. Le préfixe de clé peut également faire référence à un certain nombre de dossiers. Par exemple, 's3://mybucket/custfolder' fait référence aux dossiers custfolder, custfolder_1, custfolder_2 et ainsi de suite. Si un préfixe de clé fait référence à plusieurs dossiers, tous les fichiers dans les dossiers sont chargés. Si un préfixe de clé correspond à un fichier et à un dossier, par exemple custfolder.log, COPY tente de charger le fichier également. Si un préfixe de clé risque d’entraîner le chargement de fichiers indésirables par COPY, utilisez un fichier manifeste. Pour plus d’informations, consultez copy_from_s3_manifest_file, ci-après.

Important

Si le compartiment S3 contenant les fichiers de données ne réside pas dans la même région AWS que votre cluster, vous devez utiliser le paramètre pour spécifier la région REGION dans laquelle les données se trouvent.

Pour plus d'informations, consultez Chargement des données à partir d’Amazon S3.

’s3://copy_from_s3_manifest_file’

Spécifie la clé de l’objet Amazon S3 d’un fichier manifeste qui répertorie les fichiers de données à charger. L’argument ’s3://copy_from_s3_manifest_file’ doit explicitement faire référence à un seul fichier, par exemple, 's3://mybucket/manifest.txt'. Il ne peut pas faire référence à un préfixe de clé.

Le manifeste est un fichier texte au format JSON qui répertorie l’URL de chaque fichier qui doit être chargé à partir d’Amazon S3. L’URL inclut le nom du compartiment et le chemin d’objet complet du fichier. Les fichiers qui sont spécifiés dans le manifeste peuvent être dans des compartiments distincts, mais tous les compartiments doivent être dans la même région AWS que le cluster Amazon Redshift. Si un fichier est répertorié deux fois, le fichier est chargé deux fois. L’exemple suivant illustre le format JSON pour un manifeste qui charge trois fichiers.

{
  "entries": [
    {"url":"s3://mybucket-alpha/custdata.1","mandatory":true},
    {"url":"s3://mybucket-alpha/custdata.2","mandatory":true},
    {"url":"s3://mybucket-beta/custdata.1","mandatory":false}
  ]
}

Les guillemets doubles sont nécessaires et doivent être des guillemets simples (0x22), ni culbutés, ni courbes. Chaque entrée dans le manifeste peut éventuellement inclure un indicateur mandatory. Si mandatory est défini sur true, la commande COPY s’arrête si elle ne trouve pas le fichier pour cette entrée ; dans le cas contraire, la commande COPY se poursuit. La valeur par défaut de mandatory est false.

Lors du chargement des fichiers de données au format ORC or Parquet, le champ meta est obligatoire, comme illustré dans l’exemple suivant.

{  
   "entries":[  
      {  
         "url":"s3://mybucket-alpha/orc/2013-10-04-custdata",
         "mandatory":true,
         "meta":{  
            "content_length":99
         }
      },
      {  
         "url":"s3://mybucket-beta/orc/2013-10-05-custdata",
         "mandatory":true,
         "meta":{  
            "content_length":99
         }
      }
   ]
}

Le fichier manifeste ne doit pas être chiffré ou compressé, même si les options ENCRYPTED, GZIP, LZOP, BZIP2 ou ZSTD sont spécifiées. La commande COPY renvoie une erreur si le fichier manifeste spécifié est introuvable ou si le fichier manifeste n’est pas correctement formé.

Si un fichier manifeste est utilisé, le paramètre MANIFEST doit être spécifié avec la commande COPY. Si le paramètre MANIFEST n’est pas spécifié, la commande COPY présume que le fichier spécifié avec FROM est un fichier de données.

Pour plus d'informations, consultez Chargement des données à partir d’Amazon S3.

authorization

La commande COPY a besoin de l’autorisation pour accéder aux données dans une autre ressource AWS, y compris Amazon S3, Amazon EMR, Amazon DynamoDB et Amazon EC2. Vous pouvez fournir cette autorisation en faisant référence à un rôle AWS Identity and Access Management (IAM) qui est attaché à votre cluster (contrôle d’accès basé sur les rôles) ou en fournissant les informations d’identification d’accès d’un utilisateur (contrôle d’accès basé sur la clé). Pour plus de sécurité et de flexibilité, nous recommandons d’utiliser contrôle d’accès basé sur les rôles IAM. Pour plus d'informations, consultez Paramètres d’autorisation.

MANIFEST

Spécifie qu’un manifeste est utilisé pour identifier les fichiers de données à charger à partir d’Amazon S3. Si le paramètre MANIFEST est utilisé, la commande COPY charge des données depuis les fichiers répertoriés dans le manifeste référencé par ’s3://copy_from_s3_manifest_file’. Si le fichier manifeste n’est pas trouvé ou est dans un format incorrect, la commande COPY échoue. Pour plus d'informations, consultez Utilisation d’un manifeste pour spécifier les fichiers de données.

ENCRYPTED

Une clause qui spécifie que les fichiers d’entrée sur Amazon S3 sont chiffrés à l’aide du chiffrement côté client avec des clés gérées par le client. Pour plus d'informations, consultez Chargement de fichiers de données chiffrés à partir d’Amazon S3. N’indiquez pas ENCRYPTED si les fichiers d’entrée sont chiffrés à l’aide du chiffrement côté serveur Amazon S3 (SSE-KMS ou SSE-S3). La commande COPY lit automatiquement les fichiers chiffrés côté serveur.

Si vous spécifiez le paramètre ENCRYPTED, vous devez également spécifier le paramètre MASTER_SYMMETRIC_KEY ou inclure la valeur master_symmetric_key dans la chaîne CREDENTIALS.

Si les fichiers chiffrés sont en format compressé, ajoutez le paramètre GZIP LZOP, BZIP2 ou ZSTD.

Les fichiers manifestes et les fichiers JSONPaths ne doivent pas être chiffrés, même si l’option ENCRYPTED est spécifiée.

MASTER_SYMMETRIC_KEY ’root_key’

La clé symétrique racine qui a été utilisée pour chiffrer les fichiers de données sur Amazon S3. Si la clé MASTER_SYMMETRIC_KEY est spécifiée, le paramètre ENCRYPTED doit également être spécifié. La clé MASTER_SYMMETRIC_KEY ne peut pas être utilisée avec le paramètre CREDENTIALS. Pour plus d'informations, consultez Chargement de fichiers de données chiffrés à partir d’Amazon S3.

Si les fichiers chiffrés sont en format compressé, ajoutez le paramètre GZIP LZOP, BZIP2 ou ZSTD.

REGION [AS] ’aws-region’

Spécifie la région AWS où se trouvent les données sources. REGION est nécessaire pour exécuter la commande COPY depuis un compartiment Amazon S3 ou une table DynamoDB lorsque la ressource AWS qui contient les données ne se trouve pas dans la même région que le cluster Amazon Redshift.

La valeur pour aws_region doit correspondre à une région répertoriée dans le tableau Régions et points de terminaison Amazon Redshift.

Si le paramètre REGION est spécifié, toutes les ressources, y compris un fichier manifeste ou plusieurs compartiments Amazon S3, doivent se trouver dans la région spécifiée.

Note

Le transfert de données entre les régions engage des frais supplémentaires pour le compartiment Amazon S3 ou la table DynamoDB qui contient les données. Pour plus d’informations sur la tarification, consultez Transfert de données sortantes entre Amazon S3 et une autre région AWS sur la page Tarification Amazon S3 et Transfert de données sortantes sur la page Tarification Amazon DynamoDB.

Par défaut, la commande COPY part du principe que les données se trouvent dans la même région que le cluster Amazon Redshift.

Paramètres facultatifs

Vous pouvez éventuellement spécifier les paramètres suivants avec la commande COPY à partir d’Amazon S3 :

• Options de mappage de colonnes

• Paramètres du format de données

• Paramètres de conversion de données

• Opérations de chargement de données

Paramètres non pris en charge

Vous ne pouvez pas utiliser les paramètres suivants avec la commande COPY à partir d’Amazon S3 :

• SSH

• READRATIO