Chargement de données dans Amazon MCS avec cqlsh: idk.dev – Serveur d’impression

Le shell de langage de requête Cassandra (cqlsh) est un shell de ligne de commande open-source que vous pouvez utiliser pour exécuter des commandes CQL et effectuer des tâches d'administration de base de données, telles que la création et la modification de tables. Vous pouvez utiliser cqlsh pour commencer avec Amazon Managed Apache Cassandra Service (MCS) – une base de données compatible Cassandra évolutive, hautement disponible et gérée – en chargeant les données d'un fichier CSV dans vos tables Amazon MCS. Pour plus d'informations, consultez Qu'est-ce que le service Amazon Managed Apache Cassandra?

Cet article vous explique comment utiliser cqlsh pour charger des données dans une table Amazon MCS en utilisant le cqlsh COPY commander. Il partage également les meilleures pratiques pour la préparation des données et comment régler les performances du transfert de données via le COPIE paramètres de commande. Enfin, cet article explique comment configurer les paramètres de débit de lecture / écriture des tables Amazon MCS pour optimiser le processus de chargement des données.

Conditions préalables

Avant de commencer, vous avez besoin d'un compte AWS pour votre espace de clés et vos tables Amazon MCS. Assurez-vous que vous êtes connecté par programme et configurez correctement cqlsh. Pour obtenir des instructions, consultez Connexion par programme au service Amazon Managed Apache Cassandra.

Pour travailler à travers les exemples de cette publication, vous avez besoin d'un fichier CSV avec des données. Ce message fait référence à ce fichier CSV en tant que export_keyspace_table.csv, mais vous pouvez le remplacer par un autre nom. Assurez-vous que les en-têtes de colonne dans le fichier de données source CSV correspondent aux noms de colonne de la table cible. S'ils ne correspondent pas, vous devez mapper les en-têtes CSV aux colonnes du tableau, que cet article ne couvre pas.

Le code suivant crée des colonnes de table correspondantes:

CRÉER LA TABLE "ks.blogexample"
("id" int PRIMARY KEY, "columnvalue" text);

cat example.csv
id, valeur_colonne
1, valeur1
2, valeur2
3, valeur3

Création d'un fichier CSV source à partir de cqlsh COPY TO

Si vos données source se trouvent dans une base de données Apache Cassandra, vous pouvez utiliser la commande cqlsh COPY TO pour générer un fichier CSV. Voir le code suivant:

cqlsh localhost 9042 -u "cassandra" -p "cassandra" —exécute "COPY keyspace.table TO 'export_keyspace_table.csv' WITH HEADER = true"

Utiliser un CSV d'une autre source

Si vous utilisez une autre source de données pour créer un CSV, assurez-vous que la première ligne contient les noms des colonnes et que les données sont délimitées par une virgule (bien que cela ne soit pas obligatoire, cela vous permet d'utiliser les paramètres par défaut dans cqlsh COPY).

De plus, assurez-vous que toutes les valeurs de données sont des types de données Cassandra valides. Pour plus d'informations, consultez Types de données sur le site Web d'Apache Cassandra.

Création de la table cible

Si Apache Cassandra est la source de données d'origine, un moyen simple de créer les tables Amazon MCS (et de vous assurer que les en-têtes CSV correspondent) est de générer le CRÉER UNE TABLE de la table source. Voir le code suivant:

cqlsh localhost 9042 -u "cassandra" -p "cassandra" —exécute "DESCRIBE TABLE keyspace.table;”

Créez l'espace de clés et la table dans Amazon MCS si vous ne l'avez pas déjà fait. Vous utilisez cette table sur la cible de destination.

Préparer les données

Pour préparer les données source pour un transfert efficace, vous devez les randomiser. Ensuite, pour déterminer les valeurs des paramètres cqlsh et les paramètres de table, vous analysez les données.

Randomisation des données

le cqlsh COPIER DE La commande lit et écrit les données dans le même ordre qu'elles apparaissent dans le fichier CSV. Si vous utilisez le cqlsh COPIER VERS pour créer le fichier source, les données sont écrites dans l'ordre trié par clé dans le CSV. En interne, Amazon MCS partitionne les données à l'aide de clés de partition. Bien qu'Amazon MCS dispose d'une logique intégrée pour aider à équilibrer les demandes de charge pour la même clé de partition, le chargement des données est plus rapide et plus efficace si vous randomisez la commande, car vous pouvez profiter de l'équilibrage de charge intégré de l'écriture sur différentes partitions.

Pour répartir uniformément les écritures sur les partitions, vous devez randomiser les données dans le fichier source. Vous pouvez écrire une application pour ce faire ou utiliser un outil open source, tel que Shuf. Shuf est disponible gratuitement sur les distributions Linux, sur macOS en installant coreutils en homebrew, et sur Windows en utilisant Windows Subsystem for Linux (WSL).

Pour randomiser le fichier source sous Linux ou Windows, entrez le code suivant:

shuf -o keyspace.table.csv <export_keyspace.table.csv

Pour randomiser le fichier source sur macOS, entrez le code suivant:

gshuf -o keyspace.table.csv <export_keyspace.table.csv

Shuf réécrit les données dans un nouveau fichier CSV appelé keyspace.table.csv. Vous pouvez supprimer le fichier export_keyspace.table.csv; vous n'en avez plus besoin.

Analyser les données

Déterminez la taille moyenne et maximale des lignes en analysant les données. Vous effectuez cette opération pour les deux raisons suivantes:

• La taille moyenne des lignes permet de déterminer la quantité de données à transférer
• Vous pouvez vous assurer que toutes les lignes ont une taille inférieure à 1 Mo, ce qui correspond à la taille de ligne maximale dans Amazon MCS.

Ce quota fait référence à la taille de la ligne et non à la taille de la partition. Contrairement à Apache Cassandra, les partitions Amazon MCS peuvent être virtuellement illimitées. De plus, les clés de partition et les colonnes de cluster nécessitent un stockage supplémentaire pour l'indexation, que vous devez ajouter à la taille brute des lignes. Pour plus d'informations, voir Quotas.

La gestion des lignes supérieures à 1 Mo n'est pas une priorité pour cet article, mais si vous disposez de telles lignes, vous pouvez explorer l'une des options suivantes:

• Divisez les données en lignes plus petites (vous devrez peut-être utiliser plusieurs tables en fonction de vos modèles d'accès)
• Stockez les données dans un magasin d'objets, comme Amazon S3, et conservez une référence à l'objet dans Amazon MCS

Le code suivant utilise AWK pour analyser un fichier CSV et imprimer la taille de ligne moyenne et maximale:

awk -F, 'BEGIN samp = 10000; max = -1; if (NR> 1) len = length ($ 0); t + = len; avg = t / NR; max = (len> max? len : max) NR == samp exit END printf ("lignes:% d, moyenne:% d octets, max:% d octets n", NR, avg, max); 'keyspace.table .csv

Vous recevez la sortie suivante:

en utilisant 10 000 échantillons:
lignes: 10000, moyenne: 123 octets, max: 225 octets

Définition du mode de capacité de débit de la table

Avec Amazon MCS, vous ne payez que pour les ressources que vous utilisez. Amazon MCS propose deux modes de capacité de débit: à la demande et provisionné. Avec le mode à la demande, vous payez en fonction des lectures et écritures effectives de vos applications. Avec une capacité provisionnée, vous pouvez optimiser le coût des lectures et des écritures en définissant à l'avance la quantité de données que vos applications peuvent lire et écrire par seconde à partir des tables. Vous pouvez utiliser l'un ou l'autre mode pour charger des données dans vos tables. Pour plus d'informations, voir Mode de capacité de lecture / écriture.

Cet article vous explique comment régler cqlsh pour charger des données dans un intervalle de temps défini. Parce que vous savez combien de lectures et d'écritures vous effectuez à l'avance, utilisez le mode de capacité provisionnée. Une fois le transfert de données terminé, vous devez définir le mode de capacité pour qu'il corresponde aux modèles de trafic de votre application.

Avec le mode de capacité provisionnée, vous spécifiez à l'avance la capacité de lecture et d'écriture que vous souhaitez provisionner sur votre table. La capacité d'écriture est facturée toutes les heures et mesurée en unités de capacité d'écriture (WCU). Chaque WCU possède une capacité d'écriture suffisante pour prendre en charge l'écriture de 1 Ko de données par seconde. Lorsque vous chargez les données, le taux d'écriture doit être inférieur au nombre maximal de WCU (paramètre: write_capacity_units) défini sur la table cible. Par défaut, vous pouvez provisionner jusqu'à 40 000 WCU sur une table et 80 000 WCU sur toutes les tables de votre compte. Si vous avez besoin d'une capacité supplémentaire, vous pouvez demander une augmentation de quota via AWS Support.

Calcul du nombre moyen de WCU requis pour un insert

L'insertion de 1 Ko de données par seconde nécessite 1 WCU. Si votre fichier CSV contient 360 000 lignes et que vous souhaitez charger toutes les données en 1 heure, vous devez écrire 100 lignes par seconde (360 000 lignes / 60 minutes / 60 secondes = 100 lignes par seconde). Si chaque ligne contient jusqu'à 1 Ko de données, pour insérer 100 lignes par seconde, vous devez provisionner 100 WCU dans votre table. Si chaque ligne contient 1,5 Ko de données, vous avez besoin de deux WCU pour insérer une ligne par seconde; par conséquent, pour insérer 100 lignes par seconde, vous devez provisionner 200 WCU.

Pour déterminer le nombre de WCU dont vous avez besoin pour insérer une ligne par seconde, divisez la taille moyenne des lignes en octets par 1024 et arrondissez au nombre entier le plus proche.

Par exemple, si la taille moyenne des lignes est de 3 000 octets, vous avez besoin de trois WCU pour insérer une ligne par seconde:

ROUNDUP (3000/1024) = ROUNDUP (2,93) = 3 WCU.

Calcul du temps et de la capacité de chargement des données

Maintenant que vous connaissez la taille moyenne et le nombre de lignes de votre fichier CSV, vous pouvez calculer le nombre de WCU dont vous avez besoin pour charger les données dans un laps de temps donné, et le temps approximatif nécessaire pour charger toutes les données dans votre CSV en utilisant différents paramètres WCU.

Par exemple, si chaque ligne de votre fichier fait 1 Ko et que vous avez 1 000 000 lignes dans votre fichier CSV, pour charger les données en 1 heure, vous devez provisionner au moins 278 WCU dans votre table pour cette heure:

1000000 lignes * 1 Ko = 1000000 Ko
1000000 Ko / 3600 secondes = 277,8 Ko / seconde = 278 WCU

Configuration des paramètres de capacité provisionnée

Vous pouvez définir les paramètres de capacité d'écriture d'une table lorsque vous créez la table ou en utilisant le MODIFIER TABLE commander. La syntaxe pour modifier les paramètres de capacité provisionnée d'une table avec le paramètre MODIFIER TABLE est la suivante:

ALTER TABLE keyspace.table WITH custom_properties = 'capacity_mode': 'throughput_mode': 'PROVISIONED', 'read_capacity_units': 100, 'write_capacity_units': 278; 

Pour plus d'informations, voir ALTER TABLE dans le Guide du développeur Amazon MCS.

Configuration des paramètres COPY de cqlsh

Vous déterminez maintenant les valeurs des paramètres pour cqlsh COPY. le cqlsh COPY commande lit le fichier CSV que vous avez préparé précédemment et insère les données dans Amazon MCS à l'aide de CQL. cqlsh divise les lignes et distribue le INSÉRER opérations parmi un ensemble de travailleurs. Chaque travailleur établit une connexion avec Amazon MCS et envoie des requêtes INSERT le long de ce canal. le cqlsh COPY La commande n'a pas de logique interne pour répartir uniformément le travail entre ses employés, mais vous pouvez le configurer manuellement pour vous assurer que le travail est réparti uniformément. Commencez par passer en revue les paramètres clés de cqlsh:

• DELIMITER – Si vous avez utilisé un délimiteur autre qu'une virgule, vous pouvez définir ce paramètre, qui est par défaut virgule.
• INGÉRER – Le nombre cible de lignes cqlsh COPY tentatives de traitement par seconde. S'il n'est pas défini, il est par défaut de 100 000.
• NUMPROCESSES – Le nombre de processus de travail enfant créés par cqlsh pour traiter les demandes parallèles. Vous pouvez définir cela sur, tout au plus, num_cores - 1, où num_cores est le nombre de cœurs de traitement sur l'hôte exécutant cqlsh.
• MINBATCHSIZE et MAXBATCHSIZE – Lorsqu'un travailleur reçoit un morceau de travail, la taille du lot détermine le nombre d'insertions qui composent un morceau de travail. S'il n'est pas défini, cqlsh utilise des lots de 20, ce qui signifie qu'un morceau équivaut à 20 insertions.
• CHUNKSIZE – La taille de l'unité de travail qui passe à l'enfant travailleur. Par défaut, il est défini sur 1 000, ce qui signifie qu'un travailleur reçoit des morceaux de travail (en termes de lignes) comme CHUNKSIZE * MAXBATCHSIZE. Par défaut, chaque travailleur reçoit 20 000 lignes.
• MAXATTEMPTS – Le nombre maximum de fois pour réessayer un bloc de travail échoué. Une fois la tentative maximale atteinte, les enregistrements ayant échoué sont écrits dans un nouveau fichier CSV que vous pouvez réexécuter plus tard après avoir examiné l'échec.

Ensemble INGÉRER en fonction du nombre de WCU que vous avez provisionnés dans la table de destination cible. le INGÉRER du COPIE la commande n'est pas une limite; c'est une moyenne cible. Cela signifie qu'il peut (et le fait souvent) éclater au-dessus du nombre que vous avez défini. Pour autoriser les rafales et vous assurer qu'une capacité suffisante est en place pour gérer les demandes de chargement de données, définissez INGÉRER à 90% de la capacité d'écriture de la table:

INGÉRER = WCU * .90

Ensuite, définissez le NUMPROCESSES égal à un de moins que le nombre de cœurs sur votre système. Par exemple, si vous exécutez la charge de données à partir d'un hôte avec 16 cœurs de calcul, définissez NUMPROCESSES = 15.

Chaque processus crée un travailleur et chaque travailleur établit une connexion à Amazon MCS. Amazon MCS peut prendre en charge jusqu'à 3 000 requêtes CQL par seconde sur chaque connexion, ce qui signifie que vous devez vous assurer que chaque travailleur traite moins de 3 000 requêtes par seconde. Comme avec INGÉRER, les employés dépassent souvent le nombre que vous avez défini et ne sont pas limités par les secondes de l'horloge. Par conséquent, pour tolérer les rafales, définissez vos paramètres cqlsh pour cibler chaque travailleur traitant 2 500 demandes par seconde. Pour calculer la quantité de travail distribuée à un travailleur, divisez INGÉRER par NUMPROCESSES. Si INGÉRER / NUMPROCESSES est supérieur à 2500, abaissez le INGÉRER pour rendre cette formule vraie: INGÉRER / NUMPROCESSES <= 2 500.

Pour ce poste, supposez NUMPROCESSES est défini sur 4 (par défaut), il y a donc quatre travailleurs disponibles pour traiter votre chargement de données. cqlsh utilise la formule CHUNKSIZE * MAXBATCHSIZE pour créer des morceaux de travail (INSÉRER déclarations) à distribuer aux travailleurs. cqlsh ne répartit pas le travail de manière égale entre les travailleurs, vous devez donc définir CHUNKSIZE, MAXBATCHSIZE, et INGÉRER afin que les travailleurs ne restent pas inactifs.

Le code suivant utilise principalement les valeurs par défaut et a des travailleurs inactifs:

INGESTRATE = 10,000
NUMPROCESSES = 4 (par défaut)
CHUNKSIZE = 1000 (par défaut)
MAXBATCHSIZE. = 20 (par défaut)
Répartition du travail:
Connexion 1 / Travailleur 1: 10 000 demandes par seconde
Connexion 2 / Travailleur 2: 0 demandes par seconde
Connexion 3 / Travailleur 3: 0 demandes par seconde
Connexion 4 / Travailleur 4: 0 demandes par seconde

Dans l'exemple de code précédent, le premier travailleur obtient tout le travail et les autres restent inactifs. Ceci est dû au fait CHUNKSIZE (1 000) * MAXBATCHSIZE (20) = 20 000, ce qui est supérieur à INGÉRER (10 000). Avec ces paramètres, chaque travailleur est configuré pour traiter des blocs de 20 000 lignes. cqlsh est configuré pour extraire 10 000 lignes à la fois, en fonction de la INGÉRER réglage. Lorsque cqlsh retire 10 000 lignes du fichier CSV, le premier travailleur demande jusqu'à 20 000 lignes. Cqlsh envoie donc les 10 000 lignes au premier travailleur et ne laisse aucun travail aux autres travailleurs. En plus d'avoir une charge de travail déséquilibrée, le premier travailleur dépasse largement les 3 000 demandes par seconde maximum.

Vous pouvez répartir uniformément la charge entre les travailleurs et maintenir chaque travailleur au taux optimal de 2 500 demandes par seconde en modifiant les paramètres d'entrée. Voir le code suivant:

INGESTRATE = 10,000
NUMPROCESSES = 4 (par défaut)
CHUNKSIZE = 100
MAXBATCHSIZE. = 25
Répartition du travail:
Connexion 1 / Travailleur 1: 2 500 demandes par seconde
Connexion 2 / Travailleur 2: 2 500 demandes par seconde
Connexion 3 / Travailleur 3: 2 500 demandes par seconde
Connexion 4 / Travailleur 4: 2 500 demandes par seconde

Pour optimiser l'utilisation du trafic réseau pendant le chargement des données, choisissez une valeur pour MAXBATCHSIZE proche de la valeur maximale de 30. En changeant CHUNKSIZE à 100 et MAXBATCHSIZE à 25 ans, chaque travailleur reçoit désormais 2500 lignes (100 * 25), ce qui signifie que les 10000 lignes sont réparties de manière égale entre les quatre travailleurs (10000/2500 = 4).

Pour résumer, utilisez les formules suivantes lors de la définition cqlsh COPY paramètres:

• INGÉRER = write_capacity_units * .90
• NUMPROCESSES = 1-16 ou num_of_cores -1
• INGÉRER / NUMPROCESSES <= 2500 (cela doit être une vraie déclaration)
• MAXBATCHSIZE <= 30 (par défaut à 20; MCS accepte des lots jusqu'à 30)
• CHUNKSIZE = (INGÉRER / NUMPROCESSES) / MAXBATCHSIZE

Maintenant que vous avez calculé NUMPROCESSES, INGÉRER, et CHUNKSIZE, vous êtes prêt à charger vos données.

Exécution de la commande cqlsh COPY FROM

Pour exécuter le cqlsh COPIER DE , procédez comme suit:

1. Connectez-vous à Amazon MCS via cqlsh.
2. Basculez vers votre espace clé avec le code suivant:
3. Définissez la cohérence d'écriture sur LOCAL_QUORUM (pour la durabilité des données, Amazon MCS ne permet pas d'autres paramètres de cohérence d'écriture). Voir le code suivant:

   CONSISTENCY LOCAL_QUORUM;

4. Préparer votre cqlsh COPIER DE syntaxe. Voir l'exemple de code suivant:

   COPIEZ votremcstablename DE ‘./keyspace.table.csv 'AVEC HEADER = true ET INGESTRATE = ET NUMPROCESSES = ET MAXBATCHSIZE = 20 ET CHUNKSIZE =;

   cqlsh renvoie tous les paramètres que vous avez configurés.

5. Assurez-vous que les paramètres correspondent à votre saisie. Voir le code suivant:

   Options de lecture à partir de la ligne de commande: 'chunksize': '120', 'header': 'true', 'ingestrate': '36000', 'numprocesses': '15', 'maxbatchsize': '20'
   Utilisation de 15 processus enfants

   cqlsh affiche le nombre de lignes transférées et le taux actuel et moyen. Voir le code suivant:

   Traité: 57834 lignes; Taux: 6561 lignes / s; Moy. taux: 31751 lignes / s

   Ensuite, cqlsh traite votre fichier jusqu'à sa fin et fournit un résumé des statistiques de chargement des données (nombre de fichiers lus, runtime et lignes ignorées). Voir le code suivant:

   15556824 lignes importées de 1 fichiers en 8 minutes et 8.321 secondes (0 ignoré).

   Vous avez maintenant chargé vos données dans Amazon MCS.

Nettoyer

Maintenant que vous avez transféré vos données, ajustez les paramètres du mode de capacité pour qu'ils correspondent aux modèles de trafic habituels de votre application. Vous engagez des frais au taux horaire pour votre capacité provisionnée jusqu'à ce que vous la changiez.

Vérifiez le répertoire de votre fichier CSV source. Si des lignes ont été ignorées pendant le chargement des données, elles sont écrites dans un nouveau fichier CSV nommé import_yourcsvfilename.err.timestamp.csv. Si ce fichier existe et contient des données, ces lignes n'ont pas été transférées vers Amazon MCS. Pour réessayer ces lignes, vous pouvez réexécuter le processus. Si vous avez rencontré des erreurs pour d'autres raisons, ajustez les données avant de réessayer.

Erreurs courantes

Les raisons les plus courantes pour lesquelles les lignes ne sont pas chargées sont les erreurs de capacité et les erreurs d'analyse.

Si le client cqlsh reçoit trois erreurs consécutives de n'importe quel type d'un serveur, vous voyez le code suivant:

Échec de l'importation de 1 lignes: NoHostAvailable -, réessayera plus tard, essayez 3 sur 100

Le client tente ensuite de rétablir une connexion.

Résolution des erreurs de capacité

Le code suivant est une erreur de capacité (WriteTimeout):

Impossible d'importer 1 lignes: WriteTimeout - Erreur du serveur: code = 1100 [Coordinator node timed out waiting for replica nodes' responses] message = "L'opération a expiré - n'a reçu que 0 réponses." info = 'received_responses': 0, 'required_responses': 2, 'write_type': 'SIMPLE', 'cohérence': 'LOCAL_QUORUM', réessayera plus tard, essayez 1 sur 100

Étant donné qu'Apache Cassandra est un logiciel basé sur un cluster conçu pour fonctionner sur une flotte de nœuds, il n'a pas de messages d'exception liés aux fonctionnalités sans serveur telles que la capacité de débit. La plupart des pilotes ne comprennent que les codes d'erreur disponibles dans Apache Cassandra. Amazon MCS utilise donc le même ensemble de codes d'erreur pour maintenir la compatibilité.

Par exemple, Amazon MCS utilise le ReadTimeout et WriteTimeout exceptions pour indiquer quand une demande d'écriture échoue en raison d'une capacité de débit insuffisante. Pour aider à diagnostiquer les exceptions de capacité insuffisante, Amazon MCS publie WriteThrottleEvents et ReadThrottledEvents métriques dans Amazon CloudWatch.

Pour résoudre les erreurs de capacité insuffisante lors d'un chargement de données, réduisez le taux d'écriture par travailleur ou le taux d'ingestion total et réessayez les lignes.

Résolution des erreurs d'analyse

Le code suivant est une erreur d'analyse (Erreur d'analyse):

Impossible d'importer 1 lignes: ParseError - Invalid ... - 

Assurez-vous que les données que vous importez correspondent à votre schéma de table. cqlsh écrit des lignes contenant des erreurs d'analyse dans un fichier CSV. Essayez de prendre les données de ce fichier et d'utiliser un INSÉRER pour cette seule ligne afin que vous puissiez mieux voir le problème.

Résumé

Cet article a montré comment configurer cqlsh et Amazon MCS pour charger des données avec le cqlsh COPY et discuté des meilleures pratiques pour effectuer le transfert de données. Pour plus d'informations, consultez Qu'est-ce que le service Amazon Managed Apache Cassandra?

Si vous avez des questions ou des commentaires, veuillez laisser vos réflexions dans la section des commentaires.

à propos des auteurs

Steve Mayszak est directeur du développement logiciel avec Amazon Web Services.

Michael Raney est architecte de solutions avec Amazon Web Services.