Autres options de configuration

Sur cette page, vous trouverez des descriptions des options que vous pouvez spécifier pour le connecteur Amazon Redshift Spark.

Taille maximale des colonnes de chaînes

Redshift crée des colonnes de chaîne sous forme de colonnes de texte lors de la création de tables, qui sont stockées en tant que VARCHAR(256). Si vous souhaitez que les colonnes prennent en charge de plus grandes tailles, vous pouvez utiliser maxlength pour spécifier la longueur maximale des colonnes de chaîne. Voici un exemple qui montre comment spécifier maxlength.

columnLengthMap.foreach { case (colName, length) =>
  val metadata = new MetadataBuilder().putLong("maxlength", length).build()
  df = df.withColumn(colName, df(colName).as(colName, metadata))
}

Type de colonne

Pour définir un type de colonne, utilisez le champ redshift_type.

columnTypeMap.foreach { case (colName, colType) =>
  val metadata = new MetadataBuilder().putString("redshift_type", colType).build()
  df = df.withColumn(colName, df(colName).as(colName, metadata))
}

Codage par compression sur une colonne

Pour utiliser un encodage de compression spécifique sur une colonne, utilisez le champ d'encodage. Pour obtenir la liste complète des encodages de compression pris en charge, consultez Encodages de compression.

Description d'une colonne

Pour définir une description, utilisez le champ description.

Authentification entre Redshift et Amazon S3

Par défaut, le résultat est déchargé sur Amazon S3 au format Parquet. Pour décharger le résultat sous forme de fichier texte séparé par une barre verticale, spécifiez l'option suivante.

.option("unload_s3_format", "TEXT")

Déclarations push down

Paramètre	Obligatoire	Par défaut	Description
spark.datasource.redshift.community.autopushdown.lazyMode	Non	True	Spécifie si le connecteur doit exécuter lentement les instructions pushdown Redshift. S'il a pour valeur true, le connecteur Spark récupère tous les modèles et informations associés avant d'exécuter la requête, ce qui permet généralement d'obtenir de meilleures performances. S'il a pour valeur false, le connecteur Spark exécute les instructions pushdown immédiatement dans le thread principal du pilote Spark et il est sérialisé entre les expressions.

Paramètres du connecteur

La carte des paramètres ou OPTIONS dans Spark SQL prend en charge les paramètres suivants.

Paramètre	Obligatoire	Par défaut	Description
dbtable	Oui, sauf si la requête est spécifiée	N/A	La table à partir duquel créer ou lire dans Redshift. Ce paramètre est requis lors du réenregistrement de données dans Redshift.
query	Oui, sauf si dbtable est spécifié	N/A	La requête à partir de laquelle lire dans Redshift.
utilisateur	Non	N/A	Le nom d'utilisateur Redshift. Doit être utilisé avec le paramètre de mot de passe. Valide uniquement si l'utilisateur et le mot de passe ne sont pas des paramètres dans l'URL. Utiliser les deux entraînera une erreur.
mot de passe	Non	N/A	Le mot de passe Redshift. Doit être utilisé avec le paramètre utilisateur. Valide uniquement si l'utilisateur et le mot de passe ne sont pas des paramètres dans l'URL. Utiliser les deux entraînera une erreur.
url	Non	N/A	Une URL JDBC. Le format est le suivant : jdbc:subprotocol://host:port/database?user=username&password=password. Le sous-protocole peut être postgresql ou Redshift, en fonction du pilote JDBC que vous avez chargé. Notez qu'un pilote compatible avec Redshift doit se trouver dans le chemin de classe et correspondre à cette URL. L'hôte et le port doivent pointer vers le nœud principal Redshift. Vous devez donc configurer les groupes de sécurité and/or VPC pour autoriser l'accès depuis votre application de pilote. Database est le nom de la base de données Redshift. L'utilisateur et le mot de passe sont des informations d'identification pour accéder à la base de données. Ils doivent être intégrés à cette URL pour JDBC, et votre compte utilisateur doit disposer des autorisations nécessaires pour accéder à la table.
aws_iam_role	Uniquement si vous utilisez des rôles IAM pour autoriser les opérations Redshift COPY/UNLOAD	N/A	ARN entièrement spécifié du rôle IAM attaché au cluster Redshift.
forward_spark_s3_credentials	Non	False	Indique si cette bibliothèque doit découvrir automatiquement les informations d'identification que Spark utilise pour se connecter à Amazon S3 et s'il faut transmettre ces informations d'identification à Redshift via le pilote JDBC. Ces informations d'identification sont envoyées dans le cadre de la requête JDBC. Nous vous recommandons donc d'activer le chiffrement SSL avec une connexion JDBC lorsque vous utilisez cette option.
temporary_aws_access_key_id	Non	N/A	AWS clé d'accès. Vous devez disposer d'autorisations d'écriture sur le compartiment S3.
temporary_aws_secret_access_key	Non	N/A	AWS une clé d'accès secrète correspondant à la clé d'accès.
temporary_aws_session_token	Non	N/A	AWS jeton de session correspondant à la clé d'accès fournie.
tempdir	Non	N/A	Emplacement accessible en écriture dans Amazon S3. Utilisé pour décharger des données lors de la lecture et charger les données Avro dans Redshift lors de l'écriture. Si vous utilisez une source de données Redshift pour Spark dans le cadre d'un pipeline ETL normal, il peut être utile de définir une politique de cycle de vie sur un compartiment et de l'utiliser comme emplacement temporaire pour ces données.
jdbcdriver	Non	Déterminé par le sous-protocole de l'URL JDBC	Nom de classe du pilote JDBC à utiliser. Cette classe doit se trouver sur le chemin de classe. Dans la plupart des cas, il ne devrait pas être nécessaire de spécifier cette option, car le nom de classe du pilote approprié doit être automatiquement déterminé par le sous-protocole de l'URL JDBC.
diststyle	Non	Even	Styles de distribution Redshift à utiliser lors de la création d'une table. Les options valides sont EVEN, KEY ou ALL. Lorsque vous utilisez KEY, vous devez également définir une clé de distribution avec l'option distkey.
distkey	Non, sauf si vous utilisez DISTSTYLE_KEY	N/A	Nom d'une colonne de la table à utiliser comme clé de distribution lors de la création d'une table.
sortkeyspec	Non	N/A	Une définition complète des clés de tri Redshift.
include_column_list	Non	False	Indique si cette bibliothèque doit extraire automatiquement les colonnes du schéma et les ajouter à la commande COPY conformément aux options de mappage de colonnes.
description	Non	N/A	Description de la table. La description est définie avec la commande SQL COMMENT et apparaît dans la plupart des outils de requête. Consultez les métadonnées description pour définir des descriptions sur des colonnes individuelles.
preactions	Non	N/A	Une liste délimitée par des points-virgules de commandes SQL à exécuter avant de charger la commande COPY. Il peut être utile d'exécuter des commandes DELETE ou similaires avant de charger de nouvelles données. Si la commande contient %s, le nom de la table sera formaté avant l'exécution (si vous utilisez une table intermédiaire). Si cette commande échoue, elle est traitée comme une exception. Si vous utilisez une table intermédiaire, les modifications seront annulées et la table de sauvegarde sera restaurée si les actions préalables échouent.
extracopyoptions	Non	N/A	Liste d'options supplémentaires à ajouter à la commande Redshift COPY lors du chargement de données (par exemple TRUNCATECOLUMNS ou MAXERROR n). Consultez Paramètres facultatifs pour obtenir la liste complète des paramètres disponibles. Notez que ces options étant ajoutées à la fin de la commande COPY, vous ne pouvez utiliser que les options qui ont du sens à la fin de la commande. Cela devrait couvrir la plupart des cas d'utilisation possibles.
sse_kms_key	Non	N/A	L'ID de AWS KMS clé à utiliser pour le chiffrement côté serveur dans S3 lors de l'opération Redshift UNLOAD plutôt que le chiffrement par défaut. AWS Le rôle IAM Redshift doit avoir accès à la clé KMS pour écrire avec elle et le rôle IAM Spark doit avoir accès à la clé pour les opérations de lecture. La lecture des données chiffrées ne nécessite aucune modification (AWS gère cela) tant que le rôle IAM de Spark dispose des droits d'accès appropriés.
tempformat	Non	AVRO	Format dans lequel enregistrer les fichiers temporaires dans Amazon S3 lors de l'écriture dans Redshift. Les valeurs valides sont AVRO, CSV et CSV GZIP (CSV compressé).
csvnullstring (expérimental)	Non	Null	La valeur de chaîne à écrire pour les valeurs nulles lors de l'utilisation de tempformat CSV. Il doit s'agir d'une valeur qui n'apparaît pas dans vos données réelles.
autopushdown	Non	True	Indique s'il faut appliquer le pushdown des prédicats et des requêtes en capturant et en analysant les plans logiques de Spark pour les opérations SQL. Les opérations sont traduites en une requête SQL, puis exécutées dans Redshift pour améliorer les performances.
autopushdown.s3_result_cache	Non	False	Mettez en cache la requête SQL pour décharger les données du mappage des chemins Amazon S3 en mémoire, afin que la même requête n'ait pas besoin de s'exécuter à nouveau dans la même session Spark. Uniquement pris en charge lorsque la fonction autopushdown est activée. Nous ne recommandons pas d'utiliser ce paramètre lorsque vous mélangez des opérations de lecture et d'écriture, car les résultats mis en cache peuvent contenir des informations périmées.
unload_s3_format	Non	Parquet	Format utilisé pour décharger les résultats de la requête. Les options valides sont Parquet et Text, qui indiquent de décharger les résultats de la requête dans un format de texte séparé par une barre verticale.
extraunloadoptions	Non	N/A	Options supplémentaires à ajouter à la commande Redshift UNLOAD. Le fonctionnement de toutes les options n'est pas garanti, car certaines d'entre elles peuvent entrer en conflit avec d'autres options définies dans le connecteur.
copydelay	Non	30 000	Le délai (en ms) entre les tentatives pour les opérations COPY de Redshift.
copyretrycount	Non	2	Nombre de tentatives d'opérations Redshift COPY.
tempdir_region	Non	N/A	La AWS région où tempdir se trouve. La définition de cette option améliore les performances du connecteur pour les interactions avec tempdir et fournit automatiquement cette valeur dans le cadre des opérations COPY et UNLOAD au cours des opérations de lecture et d'écriture du connecteur. Ce paramètre est recommandé dans les situations suivantes : 1) Lorsque le connecteur fonctionne en dehors de AWS, la découverte automatique des régions échouera et affectera négativement les performances du connecteur. 2) Quand tempdir se trouve dans une autre région que le cluster Redshift, car l'utilisation de ce paramètre évite d'avoir à fournir la région manuellement à l'aide des paramètres extracopyoptions et extraunloadoptions. tempdir ne peut se trouver dans une autre région que le cluster Redshift lors de l'utilisation de PARQUET en tant que tempformat même si cela utilise ce paramètre. 3) Lorsque le connecteur fonctionne dans une région différente de tempdir, car cela améliore les performances d'accès du connecteur à tempdir.
secret.id	Non	N/A	Nom ou ARN de votre secret stocké dans AWS Secrets Manager. Vous pouvez utiliser ce paramètre pour fournir automatiquement les informations d'identification Redshift, mais uniquement si les informations d'identification d'utilisateur, de mot de passe et DbUser ne sont pas transmises dans l'URL JDBC ni sous la forme d'autres options.
secret.region	Non	N/A	AWS Région principale, telle que USA Est (Virginie du Nord), dans laquelle rechercher la secret.id valeur. Si vous ne spécifiez pas cette région, le connecteur essaiera d'utiliser la chaîne de fournisseur d'informations d'identification par défaut pour résoudre la région de secret.id. Dans certains cas, par exemple si vous utilisez le connecteur en dehors d'AWS, le connecteur ne pourra pas trouver la région. Nous recommandons l'utilisation de ce paramètre dans les situations suivantes : 1) Lorsque le connecteur fonctionne en dehors de AWS, la découverte automatique des régions échouera et empêchera l'authentification avec Redshift Lorsque le connecteur s'exécute dans une région différente de secret.id, car cela améliore les performances d'accès du secret du connecteur.
secret. vpcEndpointUrl	Non	N/A	URL du point de terminaison PrivateLink DNS à utiliser AWS Secrets Manager lors du remplacement de la chaîne de fournisseurs d'informations d'identification par défaut.
secret. vpcEndpointRegion	Non	N/A	La région du point de terminaison PrivateLink DNS à utiliser AWS Secrets Manager lors du remplacement de la chaîne de fournisseurs d'informations d'identification par défaut.
jdbc.*	Non	N/A	Paramètres supplémentaires à transmettre au pilote JDBC sous-jacent quand le caractère générique est le nom du paramètre JDBC, tels que jdbc.ssl. Notez que le préfixe jdbc sera supprimé avant d'être transmis au pilote JDBC. Pour voir toutes les options possibles pour le pilote JDBC Redshift, voir Options pour la configuration du pilote JDBC version 2.x.
étiquette	Non	" "	Identifiant à inclure dans le groupe de requêtes défini lors de l'exécution de requêtes avec le connecteur. Doit comporter 100 caractères ou moins, et tous les caractères doivent être des unicodeIdentifierParts valides. Si votre identifiant comporte plus de 100 caractères, l'excédent est supprimé. Lors de l'exécution d'une requête avec le connecteur, le groupe de requêtes est défini sous la forme d'une chaîne au format JSON, telle que {"spark-redshift-connector":{"svc":"","ver":"5.1.0-amzn-1-spark_3.3","op":"Read","lbl":""}}`) . Cette option remplace la valeur de la clé lbl.

Note

Remerciement : cette documentation contient des exemples de code et de langage développés par l'Apache Software Foundation dans le cadre de la licence Apache 2.0.