Charger des fichiers CSV à partir de Cloud Storage
Lorsque vous chargez des données CSV depuis Cloud Storage, vous pouvez les placer dans une nouvelle table ou partition, les ajouter à une table ou une partition existante, ou bien les utiliser pour écraser une table ou une partition. Lorsque les données sont chargées dans BigQuery, elles sont converties au format en colonnes de Capacitor (format de stockage de BigQuery).
Lorsque vous chargez des données depuis Cloud Storage dans une table BigQuery, l'ensemble de données contenant la table doit se trouver dans le même emplacement régional ou multirégional que le bucket Cloud Storage.
Pour plus d'informations sur le chargement de données CSV à partir d'un fichier local, consultez la section Charger des données dans BigQuery à partir d'une source de données locale.
Limites
Lorsque vous chargez des données CSV depuis Cloud Storage dans BigQuery, tenez compte des points suivants :
- Les fichiers CSV ne prennent pas en charge les données imbriquées ou répétées.
- Si vous utilisez la compression gzip, BigQuery ne peut pas lire les données en parallèle. Le chargement de données CSV compressées dans BigQuery est plus lent que le chargement de données non compressées. Consultez la section Charger des données compressées et non compressées.
- Vous ne pouvez pas inclure à la fois des fichiers compressés et non compressés dans la même tâche de chargement.
- La taille maximale d'un fichier gzip est de 4 Go.
- Lorsque vous chargez des données CSV ou JSON, les valeurs des colonnes
DATE
doivent utiliser le tiret (-
) comme séparateur et la date doit avoir le format suivant :YYYY-MM-DD
(année-mois-jour). - Lorsque vous chargez des données JSON ou CSV, les valeurs des colonnes
TIMESTAMP
doivent utiliser le tiret (-
) comme séparateur pour la partie date de l'horodatage et la date doit être au format suivant :YYYY-MM-DD
(année-mois-jour). La partiehh:mm:ss
(heure-minute-seconde) de l'horodatage doit utiliser le signe deux-points (:
) comme séparateur.
Autorisations requises
Lorsque vous chargez des données dans BigQuery, vous avez besoin d'autorisations pour exécuter une tâche de chargement et charger des données dans des tables et partitions BigQuery nouvelles ou existantes. Si vous chargez des données à partir de Cloud Storage, vous devez également disposer d'autorisations pour accéder au bucket contenant vos données.
Autorisations BigQuery
Vous devez au moins disposer des autorisations suivantes pour charger des données dans BigQuery. Elles sont requises si vous chargez des données dans une nouvelle table ou partition, mais également si vous ajoutez ou écrasez une table ou une partition.
bigquery.tables.create
bigquery.tables.updateData
bigquery.jobs.create
Les rôles IAM prédéfinis suivants incluent les autorisations bigquery.tables.create
et bigquery.tables.updateData
:
bigquery.dataEditor
bigquery.dataOwner
bigquery.admin
Les rôles IAM prédéfinis suivants incluent les autorisations bigquery.jobs.create
:
bigquery.user
bigquery.jobUser
bigquery.admin
En outre, si un utilisateur possède les autorisations bigquery.datasets.create
, il obtient également un accès bigquery.dataOwner
à l'ensemble de données qu'il crée.
L'accès correspondant au rôle bigquery.dataOwner
permet à l'utilisateur de créer et de mettre à jour des tables dans l'ensemble de données à l'aide d'une tâche de chargement.
Pour en savoir plus sur les rôles et les autorisations IAM dans BigQuery, consultez la page sur le contrôle des accès.
Autorisations Cloud Storage
Pour charger des données à partir d'un bucket Cloud Storage, vous devez disposer des autorisations storage.objects.get
. Si vous utilisez un caractère générique dans l'URI, vous devez également disposer des autorisations storage.objects.list
.
Le rôle IAM prédéfini storage.objectViewer
peut être attribué afin d'octroyer les autorisations storage.objects.get
et storage.objects.list
.
Charger des données CSV dans une table
Vous pouvez charger des données CSV depuis Cloud Storage dans une nouvelle table BigQuery de plusieurs façons :
- À l'aide de Cloud Console
- En exécutant la commande
bq load
de l'outil de ligne de commandebq
- En appelant la méthode API
jobs.insert
et en configurant une tâcheload
- En utilisant les bibliothèques clientes
Pour charger des données CSV depuis Cloud Storage dans une nouvelle table BigQuery, procédez comme suit :
Console
Ouvrez la page "BigQuery" dans Cloud Console.
Dans le panneau Explorateur, développez votre projet et sélectionnez un ensemble de données.
Dans le panneau de détails, cliquez sur Create table (Créer une table).
Dans la section Source de la page Créer une table :
Pour le champ Créer une table à partir de, sélectionnez Cloud Storage.
Dans le champ de la source, recherchez ou saisissez l'URI Cloud Storage. Sachez que vous ne pouvez pas inclure plusieurs URI dans Cloud Console. En revanche, les caractères génériques sont acceptés. Le bucket Cloud Storage doit se trouver au même emplacement que l'ensemble de données contenant la table que vous créez.
Pour File format (Format de fichier), sélectionnez CSV.
Dans la section Destination de la page Create Table (Créer une table) :
Sous Dataset name (Nom de l'ensemble de données), sélectionnez l'ensemble de données approprié.
Vérifiez que Type de table est défini sur Table native.
Dans le champ Nom de la table, saisissez le nom de la table que vous créez dans BigQuery.
Dans la section Schéma, sous Détection automatique, cochez Schéma et paramètres d'entrée pour activer la détection automatique du schéma. Vous pouvez également saisir la définition du schéma manuellement de l'une des manières suivantes :
Activez l'option Modifier sous forme de texte et saisissez le schéma de la table sous forme de tableau JSON.
Utilisez l'option Add field (Ajouter un champ) pour saisir manuellement le schéma.
(Facultatif) Pour partitionner la table, choisissez vos options dans le champ Paramètres de partitionnement et de clustering :
- Pour créer une table partitionnée, cliquez sur Aucun partitionnement, sélectionnez Partition par champ, puis choisissez une colonne
DATE
ouTIMESTAMP
. Cette option n'est pas disponible si votre schéma n'inclut pas de colonneDATE
ouTIMESTAMP
. - Pour créer une table partitionnée par date d'ingestion, cliquez sur Aucun partitionnement, puis sélectionnez Partitionner par temps d'ingestion.
- Pour créer une table partitionnée, cliquez sur Aucun partitionnement, sélectionnez Partition par champ, puis choisissez une colonne
(Facultatif) Pour le champ Filtre de partitionnement, cochez la case Demander un filtre de partitionnement pour obliger les utilisateurs à inclure une clause
WHERE
spécifiant les partitions à interroger. Ce type de filtre peut contribuer à réduire les coûts et à améliorer les performances. Pour en savoir plus, consultez la section Interroger des tables partitionnées. Cette option n'est pas disponible si Aucun partitionnement est sélectionné.(Facultatif) Pour mettre une table en cluster, saisissez entre un et quatre noms de champs dans la zone Ordre de clustering.
(Facultatif) Cliquez sur Options avancées.
- Pour le champ Préférence d'écriture, laissez l'option Écrire si la table est vide sélectionnée. Cette option crée une table et y charge vos données.
- Pour le champ Nombre d'erreurs autorisées, acceptez la valeur par défaut
0
ou saisissez le nombre maximal de lignes contenant des erreurs qui peuvent être ignorées. Si le nombre de lignes contenant des erreurs dépasse cette valeur, la tâche renverra un messageinvalid
et échouera. - Sous Valeurs inconnues, cochez la case Ignorer les valeurs inconnues pour ignorer les valeurs d'une ligne qui ne sont pas présentes dans le schéma de la table.
- Sous Délimiteur de champ, sélectionnez le caractère qui sépare les cellules dans votre fichier CSV : Virgule, Tabulation, Barre verticale ou Personnalisé. Si vous sélectionnez Personnalisé, saisissez le délimiteur dans la zone Délimiteur de champ personnalisé. La valeur par défaut est Virgule.
- Sous Lignes d'en-tête à ignorer, saisissez le nombre de lignes d'en-tête à ignorer en haut du fichier CSV. La valeur par défaut est
0
. - Sous Nouvelles lignes entre guillemets, cochez Autoriser les nouvelles lignes entre guillemets pour autoriser les sections de données entre guillemets contenant des caractères de retour à la ligne dans un fichier CSV. La valeur par défaut est
false
. - Sous Lignes irrégulières, cochez Autoriser les lignes irrégulières pour accepter les lignes des fichiers CSV pour lesquelles il manque des colonnes facultatives finales. Les valeurs manquantes sont traitées comme des valeurs nulles. Si cette option n'est pas cochée, les enregistrements contenant des colonnes finales manquantes sont traités comme des enregistrements incorrects et, si le nombre d'enregistrements incorrects est trop élevé, une erreur "non valide" est renvoyée dans le résultat de la tâche. La valeur par défaut est
false
. - Pour le champ Chiffrement, cliquez sur Clé gérée par le client afin d'utiliser une clé Cloud Key Management Service. Si vous conservez le paramètre Clé gérée par Google, BigQuery chiffre les données au repos.
Cliquez sur Créer une table.
bq
Exécutez la commande bq load
, définissez CSV
à l'aide de l'option --source_format
et spécifiez un URI Cloud Storage.
Vous pouvez inclure un seul URI, une liste d'URI séparés par des virgules ou un URI contenant un caractère générique.
Fournissez le schéma de manière intégrée ou dans un fichier de définition de schéma, ou utilisez la détection automatique du schéma.
(Facultatif) Spécifiez l'option --location
et définissez la valeur correspondant à votre emplacement.
Les autres options facultatives sont les suivantes :
--allow_jagged_rows
: permet d'accepter les lignes dans les fichiers CSV pour lesquelles il manque des colonnes facultatives finales. Les valeurs manquantes sont traitées comme des valeurs nulles. Si cette option n'est pas cochée, les enregistrements contenant des colonnes finales manquantes sont traités comme des enregistrements incorrects et, si le nombre d'enregistrements incorrects est trop élevé, une erreur "non valide" est renvoyée dans le résultat de la tâche. La valeur par défaut estfalse
.--allow_quoted_newlines
: permet d'autoriser les sections de données entre guillemets contenant des caractères de retour à la ligne dans un fichier CSV. La valeur par défaut estfalse
.--field_delimiter
: caractère indiquant la délimitation entre les colonnes de données. Les options\t
ettab
sont autorisées pour les délimiteurs de tabulation. La valeur par défaut est,
.--null_marker
: chaîne personnalisée facultative qui représente une valeur NULL dans les données CSV.--skip_leading_rows
: spécifie le nombre de lignes d'en-tête à ignorer en haut du fichier CSV. La valeur par défaut est0
.--quote
: guillemet à utiliser pour délimiter les enregistrements. La valeur par défaut est"
. Pour ne spécifier aucun caractère de guillemet, utilisez une chaîne vide.--max_bad_records
: entier spécifiant le nombre maximal d'enregistrements incorrects autorisés avant l'échec total de la tâche. La valeur par défaut est0
. Au plus, cinq erreurs de n'importe quel type sont renvoyées, quelle que soit la valeur--max_bad_records
.--ignore_unknown_values
: si spécifié, permet d'autoriser et d'ignorer les valeurs supplémentaires non reconnues dans les données CSV ou JSON.--autodetect
: permet d'activer la détection automatique du schéma pour les données CSV et JSON.--time_partitioning_type
: active le partitionnement temporel sur une table et définit le type de partition. Les valeurs possibles sontHOUR
,DAY
,MONTH
etYEAR
. Cette option est facultative lorsque vous créez une table partitionnée sur une colonneDATE
,DATETIME
ouTIMESTAMP
. Le type de partition par défaut pour le partitionnement temporel estDAY
.--time_partitioning_expiration
: entier qui spécifie (en secondes) le délai au terme duquel une partition temporelle doit être supprimée. Le délai d'expiration correspond à la date UTC de la partition plus la valeur entière.--time_partitioning_field
: colonneDATE
ouTIMESTAMP
utilisée pour créer une table partitionnée. Si le partitionnement par date est activé sans cette valeur, une table partitionnée par date d'ingestion est créée.--require_partition_filter
: si cette option est activée, elle oblige les utilisateurs à inclure une clauseWHERE
spécifiant les partitions à interroger. Ce type de filtre peut contribuer à réduire les coûts et à améliorer les performances. Pour en savoir plus, consultez la section Interroger des tables partitionnées.--clustering_fields
: liste pouvant contenir jusqu'à quatre noms de colonne séparés par une virgule, et utilisée pour créer une table en cluster.--destination_kms_key
: clé Cloud KMS pour le chiffrement des données de la table.Pour plus d'informations sur la commande
bq load
, consultez les pages suivantes:Pour en savoir plus sur les tables partitionnées, consultez :
- Créer et utiliser des tables partitionnées
- Créer et utiliser des tables partitionnées par date d'ingestion
Pour en savoir plus sur les tables en cluster, consultez :
Pour en savoir plus sur le chiffrement d'une table, consultez :
Pour charger des données CSV dans BigQuery, saisissez la commande suivante :
bq --location=location load \ --source_format=format \ dataset.table \ path_to_source \ schema
Où :
- location correspond à votre emplacement. L'option
--location
est facultative. Par exemple, si vous utilisez BigQuery dans la région de Tokyo, vous pouvez définir la valeur de l'option surasia-northeast1
. Vous pouvez définir une valeur par défaut correspondant à l'emplacement à l'aide du fichier bigqueryrc. - format est
CSV
. - dataset est un ensemble de données existant.
- table est le nom de la table dans laquelle vous chargez des données.
- path_to_source est un URI Cloud Storage complet ou une liste d'URI séparés par une virgule. Les caractères génériques sont également acceptés.
- schema est un schéma valide. Ce schéma peut être un fichier JSON local ou il peut être intégré à la commande. Vous pouvez également utiliser l'option
--autodetect
au lieu de fournir une définition de schéma.
Exemples :
La commande suivante permet de charger les données de gs://mybucket/mydata.csv
dans la table mytable
de mydataset
. Le schéma est défini dans un fichier de schéma local nommé myschema.json
.
bq load \
--source_format=CSV \
mydataset.mytable \
gs://mybucket/mydata.csv \
./myschema.json
La commande suivante permet de charger les données de gs://mybucket/mydata.csv
dans la table mytable
de mydataset
. Le schéma est défini dans un fichier de schéma local nommé myschema.json
. Le fichier CSV comprend deux lignes d'en-tête.
Si --skip_leading_rows
n'est pas spécifié, le comportement par défaut consiste à supposer que le fichier ne contient pas d'en-têtes.
bq load \
--source_format=CSV \
--skip_leading_rows=2
mydataset.mytable \
gs://mybucket/mydata.csv \
./myschema.json
La commande suivante permet de charger les données de gs://mybucket/mydata.csv
dans la table partitionnée par date d'ingestion mytable
de mydataset
. Le schéma est défini dans un fichier de schéma local nommé myschema.json
.
bq load \
--source_format=CSV \
--time_partitioning_type=DAY \
mydataset.mytable \
gs://mybucket/mydata.csv \
./myschema.json
La commande suivante permet de charger les données de gs://mybucket/mydata.csv
dans la table partitionnée mytable
de mydataset
. La table est partitionnée en fonction de la colonne mytimestamp
. Le schéma est défini dans un fichier de schéma local nommé myschema.json
.
bq load \
--source_format=CSV \
--time_partitioning_field mytimestamp \
mydataset.mytable \
gs://mybucket/mydata.csv \
./myschema.json
La commande suivante permet de charger les données de gs://mybucket/mydata.csv
dans la table mytable
de mydataset
. Le schéma est détecté automatiquement.
bq load \
--autodetect \
--source_format=CSV \
mydataset.mytable \
gs://mybucket/mydata.csv
La commande suivante permet de charger les données de gs://mybucket/mydata.csv
dans la table mytable
de mydataset
. Le schéma est défini de manière intégrée au format field:data_type,field:data_type
.
bq load \
--source_format=CSV \
mydataset.mytable \
gs://mybucket/mydata.csv \
qtr:STRING,sales:FLOAT,year:STRING
La commande ci-dessous permet de charger les données de plusieurs fichiers de gs://mybucket/
dans la table mytable
de mydataset
. L'URI Cloud Storage utilise un caractère générique. Le schéma est détecté automatiquement.
bq load \
--autodetect \
--source_format=CSV \
mydataset.mytable \
gs://mybucket/mydata*.csv
La commande ci-dessous permet de charger les données de plusieurs fichiers de gs://mybucket/
dans la table mytable
de mydataset
. La commande inclut une liste d'URI Cloud Storage séparés par une virgule. Le schéma est défini dans un fichier de schéma local nommé myschema.json
.
bq load \
--source_format=CSV \
mydataset.mytable \
"gs://mybucket/00/*.csv","gs://mybucket/01/*.csv" \
./myschema.json
API
Créez une tâche de chargement (
load
) qui pointe vers les données sources dans Cloud Storage.(Facultatif) Spécifiez votre emplacement dans la propriété
location
de la sectionjobReference
de la ressource de tâche.La propriété
source URIs
doit être complète et respecter le formatgs://bucket/object
. Chaque URI peut contenir un caractère générique (*).Spécifiez le format de données CSV en définissant la propriété
sourceFormat
surCSV
.Pour vérifier l'état de la tâche, appelez
jobs.get(job_id*)
, où job_id correspond à l'ID de tâche renvoyé par la requête initiale.- Si la réponse est
status.state = DONE
, la tâche a bien été exécutée. - Si la propriété
status.errorResult
est présente, la requête a échoué. Cet objet inclura des informations décrivant le problème rencontré. Lorsqu'une requête échoue, aucune table n'est créée et aucune donnée n'est ajoutée. - Si la propriété
status.errorResult
est absente, la tâche a bien été exécutée. Toutefois, des erreurs non fatales, telles que des problèmes d'importation de lignes, ont pu se produire. Ces erreurs sont répertoriées dans la propriétéstatus.errors
de l'objet de tâche renvoyé.
- Si la réponse est
Remarques relatives à l'API :
Les tâches de chargement sont atomiques et cohérentes. En cas d'échec d'une tâche de chargement, aucune donnée n'est disponible. Si une tâche aboutit, toutes les données sont disponibles.
Nous vous recommandons de générer un ID unique et de le transmettre en tant que
jobReference.jobId
lorsque vous appelezjobs.insert
pour créer une tâche de chargement. Cette approche offre une protection plus robuste contre les pannes réseau, car le client peut lancer une requête ou effectuer de nouvelles tentatives en utilisant l'ID de tâche connu.L'appel de
jobs.insert
sur un ID de tâche donné est idempotent. En d'autres termes, vous pouvez effectuer autant de tentatives que vous le souhaitez avec le même ID de tâche. L'une de ces opérations tout au plus aboutira.
C#
Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour C# décrite dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery en langage C#.
Go
Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Go décrite dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery en langage Go.
Java
Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Java décrite dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery en langage Java.
Node.js
Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Node.js décrite dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery en langage Node.js.
PHP
Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour PHP dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery en langage PHP.
Python
Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Python décrite dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery en langage Python.
Utilisez la méthode Client.load_table_from_uri() pour charger des données à partir d'un fichier CSV dans Cloud Storage. Fournissez une définition de schéma explicite en définissant la propriété LoadJobConfig.schema sur une liste d'objets SchemaField.
Ruby
Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Ruby décrite dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery en langage Ruby.
Charger des données CSV dans une table utilisant un partitionnement temporel basé sur une colonne
Pour charger des données CSV à partir de Cloud Storage dans une table BigQuery qui utilise le partitionnement temporel basé sur une colonne :
Go
Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Go décrite dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery en langage Go.
Java
Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Java décrite dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery en langage Java.
Node.js
Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Node.js décrite dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery en langage Node.js.
Python
Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Python décrite dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Python.
Ajouter ou écraser des données dans une table avec des données CSV
Vous pouvez charger des données supplémentaires dans une table à partir de fichiers sources ou en ajoutant des résultats de requête.
Dans Cloud Console, utilisez l'option Préférence d'écriture pour spécifier l'action à entreprendre lorsque vous chargez des données à partir d'un fichier source ou d'un résultat de requête.
Vous disposez des options suivantes lorsque vous chargez des données supplémentaires dans une table :
Option de la console | Option de l'outil bq |
Propriété de l'API BigQuery | Description |
---|---|---|---|
Écrire si la table est vide | Aucune | WRITE_EMPTY |
N'écrit les données que si la table est vide. |
Ajouter à la table | --noreplace ou --replace=false . Si --[no]replace n'est pas spécifié, les données sont ajoutées par défaut. |
WRITE_APPEND |
(Par défaut) Ajoute les données à la fin de la table. |
Écraser la table | --replace ou --replace=true |
WRITE_TRUNCATE |
Efface toutes les données existantes d'une table avant d'écrire les nouvelles données. Cette action supprime également le schéma de la table et la clé Cloud KMS. |
Si vous chargez des données dans une table existante, la tâche de chargement peut les ajouter ou écraser la table.
Vous pouvez ajouter des données ou écraser une table de plusieurs façons :
- En utilisant Cloud Console
- En exécutant la commande
bq load
de l'outil de ligne de commandebq
- En appelant la méthode API
jobs.insert
et en configurant une tâcheload
- En utilisant les bibliothèques clientes
Console
Ouvrez la page "BigQuery" dans Cloud Console.
Dans le panneau Explorateur, développez votre projet et sélectionnez un ensemble de données.
Dans le panneau de détails, cliquez sur Create table (Créer une table).
Dans la section Source de la page Créer une table :
Pour le champ Create table from (Créer une table à partir de), sélectionnez Cloud Storage.
Dans le champ de la source, recherchez ou saisissez l'URI Cloud Storage. Sachez que vous ne pouvez pas inclure plusieurs URI dans Cloud Console. En revanche, les caractères génériques sont acceptés. Le bucket Cloud Storage doit se trouver au même emplacement que l'ensemble de données contenant la table à laquelle vous ajoutez des données ou que vous écrasez.
Pour File format (Format de fichier), sélectionnez CSV.
Dans la section Destination de la page Create Table (Créer une table) :
Sous Dataset name (Nom de l'ensemble de données), sélectionnez l'ensemble de données approprié.
Dans le champ Nom de la table, saisissez le nom de la table à laquelle vous ajoutez des données ou que vous écrasez dans BigQuery.
Vérifiez que Type de table est défini sur Table native.
Dans la section Schéma, sous Détection automatique, cochez Schéma et paramètres d'entrée pour activer la détection automatique du schéma. Vous pouvez également saisir la définition du schéma manuellement de l'une des manières suivantes :
Activez l'option Modifier sous forme de texte et saisissez le schéma de la table sous forme de tableau JSON.
Utilisez l'option Add field (Ajouter un champ) pour saisir manuellement le schéma.
Sous Paramètres de partitionnement et de clustering, conservez les valeurs par défaut. Vous ne pouvez pas convertir une table en table partitionnée ou en cluster en y ajoutant ou en y écrasant des données. Par ailleurs, Cloud Console n'accepte ni l'ajout, ni l'écrasement de données dans une table partitionnée ou en cluster lors d'une tâche de chargement.
Cliquez sur Advanced options (Options avancées).
- Sous Write preference (Préférences d'écriture), choisissez Append to table (Ajouter à la table) ou Overwrite table (Écraser la table).
- Pour le champ Nombre d'erreurs autorisées, acceptez la valeur par défaut
0
ou saisissez le nombre maximal de lignes contenant des erreurs qui peuvent être ignorées. Si le nombre de lignes contenant des erreurs dépasse cette valeur, la tâche renverra un messageinvalid
et échouera. - Sous Valeurs inconnues, cochez la case Ignorer les valeurs inconnues pour ignorer les valeurs d'une ligne qui ne sont pas présentes dans le schéma de la table.
- Sous Délimiteur de champ, sélectionnez le caractère qui sépare les cellules dans votre fichier CSV : Virgule, Tabulation, Barre verticale ou Personnalisé. Si vous sélectionnez Personnalisé, saisissez le délimiteur dans la zone Délimiteur de champ personnalisé. La valeur par défaut est Virgule.
- Sous Lignes d'en-tête à ignorer, saisissez le nombre de lignes d'en-tête à ignorer en haut du fichier CSV. La valeur par défaut est
0
. - Sous Nouvelles lignes entre guillemets, cochez Autoriser les nouvelles lignes entre guillemets pour autoriser les sections de données entre guillemets contenant des caractères de retour à la ligne dans un fichier CSV. La valeur par défaut est
false
. - Sous Lignes irrégulières, cochez Autoriser les lignes irrégulières pour accepter les lignes des fichiers CSV pour lesquelles il manque des colonnes facultatives finales. Les valeurs manquantes sont traitées comme des valeurs nulles. Si cette option n'est pas cochée, les enregistrements contenant des colonnes finales manquantes sont traités comme des enregistrements incorrects et, si le nombre d'enregistrements incorrects est trop élevé, une erreur "non valide" est renvoyée dans le résultat de la tâche. La valeur par défaut est
false
. Pour le champ Chiffrement, cliquez sur Clé gérée par le client afin d'utiliser une clé Cloud Key Management Service. Si vous conservez le paramètre Clé gérée par Google, BigQuery chiffre les données au repos.
Cliquez sur Créer une table.
bq
Exécutez la commande bq load
, définissez CSV
à l'aide de l'option --source_format
et spécifiez un URI Cloud Storage.
Vous pouvez inclure un seul URI, une liste d'URI séparés par des virgules ou un URI contenant un caractère générique.
Fournissez le schéma de manière intégrée ou dans un fichier de définition de schéma, ou utilisez la détection automatique du schéma.
Spécifiez l'option --replace
pour écraser la table. Utilisez l'option --noreplace
pour ajouter des données à la table. Si aucune option n'est spécifiée, les données sont ajoutées par défaut.
Il est possible de modifier le schéma de la table lorsque vous y ajoutez ou écrasez des données. Pour en savoir plus sur les modifications de schéma acceptées lors d'un chargement, consultez la page Modifier des schémas de table.
(Facultatif) Spécifiez l'option --location
et définissez la valeur correspondant à votre emplacement.
Les autres options facultatives sont les suivantes :
--allow_jagged_rows
: permet d'accepter les lignes dans les fichiers CSV pour lesquelles il manque des colonnes facultatives finales. Les valeurs manquantes sont traitées comme des valeurs nulles. Si cette option n'est pas cochée, les enregistrements contenant des colonnes finales manquantes sont traités comme des enregistrements incorrects et, si le nombre d'enregistrements incorrects est trop élevé, une erreur "non valide" est renvoyée dans le résultat de la tâche. La valeur par défaut estfalse
.--allow_quoted_newlines
: permet d'autoriser les sections de données entre guillemets contenant des caractères de retour à la ligne dans un fichier CSV. La valeur par défaut estfalse
.--field_delimiter
: caractère indiquant la délimitation entre les colonnes de données. Les options\t
ettab
sont autorisées pour les délimiteurs de tabulation. La valeur par défaut est,
.--null_marker
: chaîne personnalisée facultative qui représente une valeur NULL dans les données CSV.--skip_leading_rows
: spécifie le nombre de lignes d'en-tête à ignorer en haut du fichier CSV. La valeur par défaut est0
.--quote
: guillemet à utiliser pour délimiter les enregistrements. La valeur par défaut est"
. Pour ne spécifier aucun caractère de guillemet, utilisez une chaîne vide.--max_bad_records
: entier spécifiant le nombre maximal d'enregistrements incorrects autorisés avant l'échec total de la tâche. La valeur par défaut est0
. Au plus, cinq erreurs de n'importe quel type sont renvoyées, quelle que soit la valeur--max_bad_records
.--ignore_unknown_values
: si spécifié, permet d'autoriser et d'ignorer les valeurs supplémentaires non reconnues dans les données CSV ou JSON.--autodetect
: permet d'activer la détection automatique du schéma pour les données CSV et JSON.--destination_kms_key
: clé Cloud KMS pour le chiffrement des données de la table.
bq --location=location load \ --[no]replace \ --source_format=format \ dataset.table \ path_to_source \ schema
où :
- location correspond à votre emplacement.
L'option
--location
est facultative. Vous pouvez définir une valeur par défaut correspondant à l'emplacement en utilisant le fichier .bigqueryrc. - format est
CSV
. - dataset est un ensemble de données existant.
- table est le nom de la table dans laquelle vous chargez des données.
- path_to_source est un URI Cloud Storage complet ou une liste d'URI séparés par une virgule. Les caractères génériques sont également acceptés.
- schema est un schéma valide. Ce schéma peut être un fichier JSON local ou il peut être intégré à la commande. Vous pouvez également utiliser l'option
--autodetect
au lieu de fournir une définition de schéma.
Exemples :
La commande suivante permet de charger les données de gs://mybucket/mydata.csv
et d'écraser la table mytable
de mydataset
. Le schéma est défini à l'aide de la fonctionnalité de détection automatique du schéma.
bq load \
--autodetect \
--replace \
--source_format=CSV \
mydataset.mytable \
gs://mybucket/mydata.csv
La commande suivante permet de charger les données de gs://mybucket/mydata.csv
et d'ajouter des données à la table mytable
de mydataset
. Le schéma est défini à l'aide d'un fichier de schéma JSON (myschema.json
).
bq load \
--noreplace \
--source_format=CSV \
mydataset.mytable \
gs://mybucket/mydata.csv \
./myschema.json
API
Créez une tâche de chargement (
load
) qui pointe vers les données sources dans Cloud Storage.(Facultatif) Spécifiez votre emplacement dans la propriété
location
de la sectionjobReference
de la ressource de tâche.La propriété
source URIs
doit être complète et respecter le formatgs://bucket/object
. Vous pouvez inclure plusieurs URI sous la forme d'une liste d'éléments séparés par une virgule. Sachez que les caractères génériques sont également acceptés.Spécifiez le format de données en définissant la propriété
configuration.load.sourceFormat
surCSV
.Spécifiez la préférence d'écriture en définissant la propriété
configuration.load.writeDisposition
surWRITE_TRUNCATE
ouWRITE_APPEND
.
Go
Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Go décrite dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery en langage Go.
Java
Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Java décrite dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery en langage Java.
Node.js
Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Node.js décrite dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Node.js.
Pour remplacer les lignes d'une table existante, définissez la valeur writeDisposition
du paramètre metadata
sur 'WRITE_TRUNCATE'
.
Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour PHP décrite dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery en langage PHP.
Python
Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Python décrite dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery en langage Python.
Pour remplacer les lignes d'une table existante, définissez la propriété LoadJobConfig.write_disposition sur la constante SourceFormat WRITE_TRUNCATE
.
Charger des données CSV partitionnées avec Hive
BigQuery accepte le chargement de données CSV partitionnées avec Hive et stockées dans Cloud Storage. Il insère alors les colonnes de partitionnement Hive en tant que colonnes dans la table de destination gérée par BigQuery. Pour en savoir plus, consultez la page Charger des données partitionnées externes.
Informations sur le chargement des données CSV
Cette section décrit comment BigQuery gère les différentes options de mise en forme des fichiers CSV.
Encodage
BigQuery s'attend à ce que les données CSV soient encodées au format UTF-8. Si vous avez des fichiers CSV avec des données encodées au format ISO-8859-1 (également connu sous le nom de Latin-1), vous devez spécifier explicitement l'encodage afin que BigQuery puisse convertir correctement les données au format UTF-8.
Si vous ne spécifiez pas d'encodage, ou si vous spécifiez l'encodage UTF-8 alors que le fichier CSV n'est pas encodé dans ce format, BigQuery tente de convertir les données au format UTF-8. En règle générale, vos données sont chargées avec succès, mais ne correspondent peut-être pas à vos attentes octet par octet. Pour éviter cela, spécifiez l'encodage approprié à l'aide de l'option --encoding
.
Si BigQuery ne peut pas convertir un caractère autre que le caractère ASCII 0
, il le convertit en caractère de remplacement Unicode standard : �.
Délimiteurs de champs
Dans les fichiers CSV, les délimiteurs peuvent être n'importe quel caractère à un octet. Si le fichier source utilise l'encodage ISO-8859-1, tous les caractères peuvent être des délimiteurs. Si le fichier source utilise l'encodage UTF-8, n'importe quel caractère de la plage décimale 1-127 (U+0001-U+007F) peut être utilisé sans modification. Vous pouvez insérer un caractère ISO-8859-1 en dehors de cette plage en tant que délimiteur. BigQuery l'interprétera correctement. Toutefois, si vous utilisez un caractère à plusieurs octets comme délimiteur, certains octets seront interprétés de manière incorrecte comme faisant partie de la valeur du champ.
En règle générale, il est recommandé d'utiliser un délimiteur standard, tel qu'une tabulation, une barre verticale ou une virgule. La valeur par défaut est la virgule.
Types de données
Boolean. BigQuery peut analyser n'importe laquelle des paires suivantes pour les données booléennes : 1 ou 0, true ou false, t ou f, yes ou no, ou y ou n (tous non sensibles à la casse). La détection automatique de schéma détecte automatiquement l'un de ces éléments, sauf 0 et 1.
Date. les colonnes de type DATE doivent être au format YYYY-MM-DD
.
Datetime. les colonnes de type DATETIME doivent être au format YYYY-MM-DD
HH:MM:SS[.SSSSSS]
.
Time : les colonnes de type TIME doivent être au format HH:MM:SS[.SSSSSS]
.
Timestamp : BigQuery accepte différents formats d'horodatage. L'horodatage doit inclure une partie date et une partie heure.
La partie date peut être au format
YYYY-MM-DD
ouYYYY/MM/DD
.La partie horodatage doit être au format
HH:MM[:SS[.SSSSSS]]
(les secondes et les fractions de secondes sont facultatives).La date et l'heure doivent être séparées par un espace ou le caractère "T".
La date et l'heure peuvent également être suivies d'un décalage UTC ou de l'indicateur de zone UTC (
Z
). Pour en savoir plus, consultez la section Fuseaux horaires.
Par exemple, les valeurs d'horodatage suivantes sont valides :
- 2018-08-19 12:11
- 2018-08-19 12:11:35
- 2018-08-19 12:11:35.22
- 2018/08/19 12:11
- 2018-07-05 12:54:00 UTC
- 2018-08-19 07:11:35.220 -05:00
- 2018-08-19T12:11:35.220Z
Si vous fournissez un schéma, BigQuery accepte également l'epoch Unix comme valeur d'horodatage. Toutefois, la détection automatique de schéma ne détecte pas ce cas, et traite la valeur comme un type numérique ou une chaîne.
Exemples de valeurs d'horodatage avec l'epoch Unix :
- 1534680695
- 1.534680695e11
Options CSV
Pour modifier la façon dont BigQuery analyse les données CSV, spécifiez des options supplémentaires dans Cloud Console, l'outil de ligne de commande bq
ou l'API.
Pour plus d'informations sur le format CSV, consultez la RFC 4180.
Option CSV | Option de la console | Option de l'outil bq |
Propriété de l'API BigQuery | Description |
---|---|---|---|---|
Délimiteur de champ | Délimiteur de champ : virgule, tabulation, barre verticale, personnalisé | -F ou --field_delimiter |
fieldDelimiter |
(Facultatif) Le séparateur des champs dans un fichier CSV. Le séparateur peut être n'importe quel caractère ISO-8859-1 à un octet. Pour utiliser un caractère compris entre 128 et 255, vous devez encoder le caractère en UTF8. BigQuery convertit la chaîne selon l'encodage ISO-8859-1 et utilise le premier octet de la chaîne codée pour fractionner les données dans leur état binaire brut. BigQuery est également compatible avec la séquence d'échappement "\t" pour spécifier la tabulation comme séparateur. La valeur par défaut est une virgule (,). |
Lignes d'en-tête | Lignes d'en-tête à ignorer | --skip_leading_rows |
skipLeadingRows |
(Facultatif) Un entier indiquant le nombre de lignes d'en-tête dans les données sources. |
Nombre d'enregistrements incorrects autorisés | Nombre d'erreurs autorisées | --max_bad_records |
maxBadRecords |
(Facultatif) Nombre maximal d'enregistrements incorrects pouvant être ignorés par BigQuery lors de l'exécution de la tâche. Si le nombre d'enregistrements incorrects dépasse cette valeur, une erreur "non valide" est renvoyée dans le résultat de la tâche. La valeur par défaut est 0, ce qui nécessite que tous les enregistrements soient valides. |
Caractères de retour à la ligne | Autoriser les nouvelles lignes entre guillemets | --allow_quoted_newlines |
allowQuotedNewlines |
(Facultatif) Indique s'il faut autoriser les sections de données entre guillemets contenant des caractères de retour à la ligne dans un fichier CSV. La valeur par défaut est false. |
Valeurs NULL personnalisées | Aucun | --null_marker |
nullMarker |
(Facultatif) Spécifie une chaîne représentant une valeur nulle dans un fichier CSV. Par exemple, si vous spécifiez "\N", BigQuery interprète "\N" comme une valeur nulle lors du chargement d'un fichier CSV. La valeur par défaut est une chaîne vide. Si vous définissez cette propriété sur une valeur personnalisée, BigQuery génère une erreur si une chaîne vide est présente pour tous les types de données, à l'exception de STRING et BYTE. Pour les colonnes STRING et BYTE, BigQuery interprète la chaîne vide comme une valeur vide. |
Colonnes facultatives finales | Autoriser les lignes irrégulières | --allow_jagged_rows |
allowJaggedRows |
(Facultatif) Accepte les lignes pour lesquelles il manque des colonnes facultatives finales. Les valeurs manquantes sont traitées comme des valeurs nulles. Si la valeur est "false", les enregistrements contenant des colonnes finales manquantes sont traités comme des enregistrements incorrects et, s'il y a trop d'enregistrements incorrects, une erreur "non valide" est renvoyée dans le résultat de la tâche. La valeur par défaut est "false". Applicable uniquement au format CSV, ignoré pour les autres formats. |
Valeurs inconnues | Ignorer les valeurs inconnues | --ignore_unknown_values |
ignoreUnknownValues |
(Facultatif) Indique si BigQuery doit autoriser des valeurs supplémentaires qui ne sont pas représentées dans le schéma de la table. Si le champ est défini sur "true", les valeurs supplémentaires sont ignorées. Si la valeur est "false", les enregistrements comportant des colonnes supplémentaires sont traités comme des enregistrements incorrects et, si le nombre d'enregistrements incorrects est trop élevé, une erreur "non valide" est renvoyée dans le résultat de la tâche. La valeur par défaut est false. La propriété sourceFormat détermine ce que BigQuery considère comme une valeur supplémentaire :
|
Guillemets | Aucun | --quote |
quote |
(Facultatif) Valeur utilisée pour citer des sections de données dans un fichier CSV.
BigQuery convertit la chaîne selon l'encodage ISO-8859-1, puis utilise le premier octet de la chaîne encodée pour fractionner les données dans leur état binaire brut. La valeur par défaut est un guillemet double ('"'). Si vos données ne contiennent pas de sections entre guillemets, définissez la valeur de la propriété sur une chaîne vide. Si vos données contiennent des caractères de retour à la ligne entre guillemets, vous devez également définir la propriété allowQuotedNewlines sur true . Pour inclure le caractère spécifique de guillemet dans une valeur entre guillemets, faites précéder la valeur d'un guillemet supplémentaire. Par exemple, pour échapper le caractère par défaut ' " ', utilisez ' "" '. |
Encodage | Aucun | -E ou --encoding |
encoding |
(Facultatif) Encodage des caractères des données. Les valeurs acceptées sont UTF-8 ou ISO-8859-1. La valeur par défaut est UTF-8. BigQuery décode les données une fois que les données binaires brutes ont été fractionnées à l'aide des valeurs des propriétés quote et fieldDelimiter . |