Charger des données JSON depuis Google Cloud Storage

Charger des fichiers JSON depuis Cloud Storage

Lorsque vous chargez des données JSON délimitées par un retour à la ligne à partir de Cloud Storage, vous pouvez charger ces données dans une nouvelle table ou une nouvelle partition ; vous pouvez également les ajouter à une partition existante ou écraser des données dans une partition existante. 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 JSON à 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 JSON depuis Cloud Storage dans BigQuery, tenez compte des points suivants :

  • Les données JSON doivent être délimitées par un retour à la ligne.
  • Si vous utilisez la compression gzip, BigQuery ne peut pas lire les données en parallèle. Le chargement de données JSON compressées dans BigQuery est plus lent que le chargement de données non compressées.
  • BigQuery ne prend pas en charge les cartes ou les dictionnaires en JSON. Par exemple, "product_categories": {"my_product": 40.0} n'est pas valide, mais "product_categories": {"column1": "my_product" , "column2": 40.0} est valide.
  • 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 partie hh:mm:ss (heure-minute-seconde) de l'horodatage doit utiliser deux points (:) comme séparateur.

Autorisations requises

Lorsque vous chargez des données dans BigQuery, vous avez besoin d'autorisations au niveau du projet ou de l'ensemble de données afin de pouvoir charger des données dans des tables et partitions BigQuery nouvelles ou existantes. Si vous chargez des données depuis Cloud Storage, vous devez également avoir accès au bucket contenant vos données.

Autorisations BigQuery

Lorsque vous chargez des données dans BigQuery depuis Cloud Storage, vous devez disposer du rôle bigquery.dataOwner ou bigquery.dataEditor au niveau du projet ou de l'ensemble de données. Les deux rôles permettent aux utilisateurs et aux groupes de charger les données dans une nouvelle table, de les ajouter à une table existante ou de les utiliser pour écraser une table.

L'attribution des rôles au niveau du projet donne à l'utilisateur ou au groupe la possibilité de charger les données dans les tables de chaque ensemble de données du projet. L'attribution des rôles au niveau de l'ensemble de données permet à l'utilisateur ou au groupe de charger les données uniquement dans les tables de cet ensemble de données.

Pour en savoir plus sur la configuration de l'accès aux ensembles de données, consultez la section Appliquer des contrôles d'accès aux ensembles de données. Pour plus d'informations sur les rôles IAM dans BigQuery, consultez la section Contrôle d'accès.

Autorisations Cloud Storage

Pour charger les données d'un bucket Cloud Storage, vous devez disposer des autorisations storage.objects.get au niveau du projet ou du bucket concerné. 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 accordé pour attribuer les autorisations storage.objects.get et storage.objects.list.

Charger des données JSON dans une nouvelle table

Pour charger des données JSON délimitées par retour à la ligne à partir de Google Cloud Storage dans une nouvelle table BigQuery :

Interface utilisateur Web

  1. Accédez à l'interface utilisateur Web de BigQuery.
    Accéder à l'interface utilisateur Web de BigQuery

  2. Dans le panneau de navigation, passez la souris sur un ensemble de données. Ensuite, cliquez sur l'icône représentant une flèche vers le bas image de la flèche vers le bas, puis sur Create new table (Créer une table). Le processus de chargement des données est identique à celui permettant de créer une table vide.

  3. Dans la section Source Data (Données sources) de la page Create Table (Créer une table), procédez comme suit :

    • Pour le paramètre Location (Emplacement), sélectionnez Google Cloud Storage. Dans le champ "Source", indiquez le paramètre URI Cloud Storage. Notez que vous ne pouvez pas inclure plusieurs URI dans l'interface utilisateur Web de BigQuery. 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 JSON (Newline Delimited) (JSON (délimité par retour à la ligne)).
  4. Dans la section Destination Table (Table de destination) de la page Create Table (Créer une table), procédez comme suit :
    • Pour le paramètre Table Name (Nom de la table), choisissez l'ensemble de données approprié, puis saisissez dans le champ le nom de la table que vous créez dans BigQuery.
    • Vérifiez que le paramètre Table type (Type de table) est défini sur Native table (Table native{).
  5. Dans la section Schema (Schéma), entrez la définition du schéma.

    • Pour les fichiers JSON, vous pouvez cocher l'option Auto-detect (Détection automatique) pour activer la détection automatique de schémas.

      lien vers la détection automatique

    • Vous pouvez également saisir les informations du schéma manuellement en utilisant les méthodes suivantes :

      • En cliquant sur Edit as text (Modifier sous forme de texte), puis en saisissant le schéma de la table en tant que tableau JSON :

        Ajouter un schéma en tant que tableau JSON

      • En utilisant Add Field (Ajouter un champ) pour saisir manuellement le schéma :

        Ajouter un schéma en utilisant l'ajout de champs

  6. Sélectionnez les éléments applicables dans la section Options, puis cliquez sur Create Table (Créer une table). Pour plus d'informations sur les options disponibles, consultez la section Options JSON.

Ligne de commande

Utilisez la commande bq load, indiquez NEWLINE_DELIMITED_JSON pour source_format et spécifiez un paramètre 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.

Spécifiez l'indicateur --location et définissez la valeur sur votre emplacement.

bq --location=[LOCATION] load --source_format=[FORMAT] [DATASET].[TABLE] [PATH_TO_SOURCE] [SCHEMA]

où :

  • [LOCATION] correspond à votre emplacement. L'indicateur --location est facultatif si vos données se trouvent dans l'emplacement multirégional US ou EU. Par exemple, si vous utilisez BigQuery dans la région de Tokyo, définissez la valeur de l'indicateur sur asia-northeast1. Vous pouvez spécifier une valeur par défaut pour l'emplacement à l'aide du fichier .bigqueryrc.
  • [FORMAT] est NEWLINE_DELIMITED_JSON.
  • [DATASET] est un ensemble de données existant.
  • [TABLE] est le nom de la table dans laquelle vous chargez les données.
  • [PATH_TO_SOURCE] correspond à un URI Cloud Storage complet ou à une liste d'URI séparés par des virgules. Les caractères génériques sont également autorisés.
  • [SCHEMA] est un schéma valide. Ce schéma peut être un fichier JSON local ou il peut être saisi en ligne dans la commande. Vous pouvez également utiliser l'indicateur --autodetect au lieu de fournir une définition de schéma.

En outre, vous pouvez ajouter des indicateurs pour les options JSON, qui vous permettent de contrôler la manière dont BigQuery analyse vos données.

Exemples :

  • La commande suivante permet de charger les données de gs://mybucket/mydata.json dans la table mytable de mydataset. Le schéma est défini dans un fichier de schéma local nommé myschema.json. mybucket et mydataset ont été créés dans l'emplacement multirégional US.

    bq --location=US load --source_format=NEWLINE_DELIMITED_JSON mydataset.mytable gs://mybucket/mydata.json ./myschema.json
    
  • La commande suivante permet de charger les données de gs://mybucket/mydata.json dans la table mytable de mydataset. Le schéma est défini en ligne au format [FIELD]:[DATA_TYPE], [FIELD]:[DATA_TYPE]. mybucket et mydataset ont été créés dans l'emplacement multirégional US.

    bq --location=US load --source_format=NEWLINE_DELIMITED_JSON mydataset.mytable gs://mybucket/mydata.json qtr:STRING,sales:FLOAT,year:STRING
    

    Lorsque vous spécifiez le schéma sur la ligne de commande, vous ne pouvez pas inclure de type RECORD (STRUCT), ni de description de champ, ni spécifier le mode de champ. Tous les modes sont définis comme NULLABLE par défaut. Pour inclure des descriptions de champs, des modes et des types RECORD, fournissez un fichier de schéma JSON.

  • La commande suivante permet de charger les données de gs://mybucket/mydata.json dans la table mytable de mydataset. Le schéma est défini à l'aide de la fonctionnalité de détection automatique de schéma. mybucket et mydataset ont été créés dans l'emplacement multirégional US.

    bq --location=US load --autodetect --source_format=NEWLINE_DELIMITED_JSON mydataset.mytable gs://mybucket/mydata.json
    
  • La commande suivante 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 et le schéma est défini à l'aide de la fonctionnalité de détection automatique de schéma. mybucket et mydataset ont été créés dans la région asia-northeast1.

    bq --location=asia-northeast1 load --autodetect --source_format=NEWLINE_DELIMITED_JSON mydataset.mytable gs://mybucket/mydata*.json
    
  • La commande suivante 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 des virgules et le schéma est défini à l'aide de la fonctionnalité de détection automatique de schéma. mybucket et mydataset ont été créés dans la région asia-northeast1.

    bq --location=asia-northeast1 load --autodetect --source_format=NEWLINE_DELIMITED_JSON mydataset.mytable "gs://mybucket/myfile.json,gs://mybucket/myfile2.json"
    

API

Définissez les propriétés suivantes pour charger les données JSON délimitées par retour à la ligne à l'aide de l'API.

  1. Créez une tâche de chargement qui pointe vers les données sources dans Google Cloud Storage.

  2. Spécifiez votre emplacement dans la propriété location de la section jobReference de la ressource associée à la tâche.

  3. Les URI sources doivent être complets et respecter le format gs://[BUCKET]/[OBJECT]. Chaque URI peut contenir un caractère générique (*).

  4. Spécifiez le format de données en définissant la propriété configuration.load.sourceFormat sur NEWLINE_DELIMITED_JSON.

  5. Pour vérifier l'état de la tâche, appelez jobs.get([JOB_ID]*), où [JOB_ID] correspond à l'ID de la tâche renvoyée par la requête initiale.

    • Si 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. Les erreurs non fatales sont répertoriées dans la propriété status.errors de l'objet Tâche renvoyé.

Remarques relatives à l'API :

  • Les tâches de chargement sont atomiques et cohérentes. Si une tâche de chargement échoue, aucune donnée n'est disponible. Si une tâche aboutit, toutes les données sont disponibles.

  • Il est recommandé de générer un ID unique et de le transmettre en tant que jobReference.jobId lorsque vous appelez jobs.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 cet exemple, suivez les instructions de configuration de C# décrites dans le guide de démarrage rapide de BigQuery : Utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery C#.

Utilisez la méthode BigQueryClient.CreateLoadJob() pour démarrer une tâche de chargement à partir de Cloud Storage. Pour utiliser JSON délimité par retour à la ligne, créez un objet CreateLoadJobOptions et définissez sa propriété SourceFormat sur FileFormat.NewlineDelimitedJson.
var gcsURI = "gs://cloud-samples-data/bigquery/us-states/us-states.json";

var dataset = client.CreateDataset(datasetId);

var schema = new TableSchemaBuilder {
    { "name", BigQueryDbType.String },
    { "post_abbr", BigQueryDbType.String }
}.Build();

var jobOptions = new CreateLoadJobOptions()
{
    SourceFormat = FileFormat.NewlineDelimitedJson
};

var loadJob = client.CreateLoadJob(gcsURI, dataset.GetTableReference(tableId),
    schema, jobOptions);

loadJob.PollUntilCompleted();

Go

Avant d'essayer cet exemple, suivez les instructions de configuration de Go décrites dans le guide de démarrage rapide de BigQuery : Utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Go.

Pour charger des données à partir d'un fichier JSON délimité par retour à la ligne à partir de Cloud Storage, fournissez la définition de schéma explicite du fichier :

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states.json")
gcsRef.SourceFormat = bigquery.JSON
gcsRef.Schema = bigquery.Schema{
	{Name: "name", Type: bigquery.StringFieldType},
	{Name: "post_abbr", Type: bigquery.StringFieldType},
}
loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
loader.WriteDisposition = bigquery.WriteEmpty

job, err := loader.Run(ctx)
if err != nil {
	return err
}
status, err := job.Wait(ctx)
if err != nil {
	return err
}

if status.Err() != nil {
	return fmt.Errorf("Job completed with error: %v", status.Err())
}

Si la détection automatique du schéma est sélectionnée, BigQuery déduira le schéma à partir d'un échantillon des données d'entrée :

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states.json")
gcsRef.SourceFormat = bigquery.JSON
gcsRef.AutoDetect = true
loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
loader.WriteDisposition = bigquery.WriteEmpty

job, err := loader.Run(ctx)
if err != nil {
	return err
}
status, err := job.Wait(ctx)
if err != nil {
	return err
}

if status.Err() != nil {
	return fmt.Errorf("Job completed with error: %v", status.Err())
}

Java

Avant d'essayer cet exemple, suivez les instructions de configuration de Java décrites dans le guide de démarrage rapide de BigQuery : Utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Java.

Utilisez la méthode LoadJobConfiguration.builder (tableId, sourceUri) pour démarrer une tâche de chargement à partir de Cloud Storage. Pour utiliser JSON délimité par retour à la ligne, utilisez LoadJobConfiguration.setFormatOptions (FormatOptions.json ()).

String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.json";
TableId tableId = TableId.of(datasetName, tableName);
// Table field definition
Field[] fields =
    new Field[] {
      Field.of("name", LegacySQLTypeName.STRING),
      Field.of("post_abbr", LegacySQLTypeName.STRING)
    };
// Table schema definition
Schema schema = Schema.of(fields);
LoadJobConfiguration configuration =
    LoadJobConfiguration.builder(tableId, sourceUri)
        .setFormatOptions(FormatOptions.json())
        .setCreateDisposition(CreateDisposition.CREATE_IF_NEEDED)
        .setSchema(schema)
        .build();
// Load the table
Job loadJob = bigquery.create(JobInfo.of(configuration));
loadJob = loadJob.waitFor();
// Check the table
System.out.println("State: " + loadJob.getStatus().getState());
return ((StandardTableDefinition) bigquery.getTable(tableId).getDefinition()).getNumRows();

Python

Avant d'essayer cet exemple, suivez les instructions de configuration de Python décrites dans le guide de démarrage rapide de BigQuery : Utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Python.

Utilisez la méthode Client.load_table_from_uri () pour démarrer une tâche de chargement à partir de Cloud Storage. Pour utiliser JSON délimité par retour à la ligne, définissez la propriété LoadJobConfig.source_format sur la chaîne NEWLINE_DELIMITED_JSON et passez la configuration de la tâche en tant qu'argument de job_config sur la méthode load_table_from_uri().

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_id = 'my_dataset'

dataset_ref = client.dataset(dataset_id)
job_config = bigquery.LoadJobConfig()
job_config.schema = [
    bigquery.SchemaField('name', 'STRING'),
    bigquery.SchemaField('post_abbr', 'STRING')
]
job_config.source_format = bigquery.SourceFormat.NEWLINE_DELIMITED_JSON
uri = 'gs://cloud-samples-data/bigquery/us-states/us-states.json'

load_job = client.load_table_from_uri(
    uri,
    dataset_ref.table('us_states'),
    location='US',  # Location must match that of the destination dataset.
    job_config=job_config)  # API request

assert load_job.job_type == 'load'

load_job.result()  # Waits for table load to complete.

assert load_job.state == 'DONE'
assert client.get_table(dataset_ref.table('us_states')).num_rows > 0

Pour activer la détection automatique de schéma, définissez la propriété LoadJobConfig.autodetect sur True.

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_id = 'my_dataset'

dataset_ref = client.dataset(dataset_id)
job_config = bigquery.LoadJobConfig()
job_config.autodetect = True
job_config.source_format = bigquery.SourceFormat.NEWLINE_DELIMITED_JSON
uri = 'gs://cloud-samples-data/bigquery/us-states/us-states.json'
load_job = client.load_table_from_uri(
    uri,
    dataset_ref.table('us_states'),
    job_config=job_config)  # API request

assert load_job.job_type == 'load'

load_job.result()  # Waits for table load to complete.

assert load_job.state == 'DONE'
assert client.get_table(dataset_ref.table('us_states')).num_rows == 50

Ruby

Avant d'essayer cet exemple, suivez les instructions de configuration de Ruby décrites dans le guide de démarrage rapide de BigQuery : Utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Ruby.

Utilisez la méthode Dataset.load_job () pour démarrer une tâche de chargement à partir de Cloud Storage. Pour utiliser JSON délimité par retour à la ligne, définissez le paramètre de format sur "json".

# project_id = "Your Google Cloud project ID"
# dataset_id = "ID of the dataset to create table in"

require "google/cloud/bigquery"

bigquery     = Google::Cloud::Bigquery.new project: project_id
dataset      = bigquery.dataset dataset_id
table_id     = "us_states"
storage_path = "gs://cloud-samples-data/bigquery/us-states/us-states.json"

puts "Importing data from Cloud Storage file: #{storage_path}"
load_job = dataset.load_job table_id, storage_path, format: "json" do |schema|
  schema.string "name"
  schema.string "post_abbr"
end

puts "Waiting for load job to complete: #{load_job.job_id}"
load_job.wait_until_done!

puts "Data imported"

Pour activer la détection automatique de schéma, définissez le paramètre autodetect sur true.

# project_id = "Your Google Cloud project ID"
# dataset_id = "ID of the dataset to create table in"

require "google/cloud/bigquery"

bigquery     = Google::Cloud::Bigquery.new project: project_id
dataset      = bigquery.dataset dataset_id
table_id     = "us_states"
storage_path = "gs://cloud-samples-data/bigquery/us-states/us-states.json"

puts "Importing data from Cloud Storage file: #{storage_path}"
load_job = dataset.load_job table_id,
                            storage_path,
                            format: "json",
                            autodetect: true

puts "Waiting for load job to complete: #{load_job.job_id}"
load_job.wait_until_done!

puts "Data imported"

Charger des données JSON imbriquées et répétées

BigQuery prend en charge le chargement de données imbriquées et répétées à partir de formats source prenant en charge des schémas basés sur des objets, tels que JSON, Avro, Cloud Firestore et Cloud Datastore.

Un objet JSON, y compris d'éventuels champs imbriqués/répétés, doit apparaître sur chaque ligne.

Exemple

L'exemple suivant montre des exemples de données imbriquées/répétées. La table contient des informations sur des personnes. Elle comporte les champs suivants :

  • id
  • first_name
  • last_name
  • dob (date de naissance)
  • addresses (champ imbriqué et répété)
    • addresses.status (actuel ou précédent)
    • addresses.address
    • addresses.city
    • addresses.state
    • addresses.zip
    • addresses.numberOfYears (années à l'adresse)

Le fichier de données JSON ressemblerait à ce qui suit. Notez que le champ d'adresse contient un tableau de valeurs (indiqué par [ ]).

{"id":"1","first_name":"John","last_name":"Doe","dob":"1968-01-22","addresses":[{"status":"current","address":"123 First Avenue","city":"Seattle","state":"WA","zip":"11111","numberOfYears":"1"},{"status":"previous","address":"456 Main Street","city":"Portland","state":"OR","zip":"22222","numberOfYears":"5"}]}
{"id":"2","first_name":"Jane","last_name":"Doe","dob":"1980-10-16","addresses":[{"status":"current","address":"789 Any Avenue","city":"New York","state":"NY","zip":"33333","numberOfYears":"2"},{"status":"previous","address":"321 Main Street","city":"Hoboken","state":"NJ","zip":"44444","numberOfYears":"3"}]}

Le schéma de la table devrait ressembler à ceci :

[
    {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
    },
    {
        "name": "first_name",
        "type": "STRING",
        "mode": "NULLABLE"
    },
    {
        "name": "last_name",
        "type": "STRING",
        "mode": "NULLABLE"
    },
    {
        "name": "dob",
        "type": "DATE",
        "mode": "NULLABLE"
    },
    {
        "name": "addresses",
        "type": "RECORD",
        "mode": "REPEATED",
        "fields": [
            {
                "name": "status",
                "type": "STRING",
                "mode": "NULLABLE"
            },
            {
                "name": "address",
                "type": "STRING",
                "mode": "NULLABLE"
            },
            {
                "name": "city",
                "type": "STRING",
                "mode": "NULLABLE"
            },
            {
                "name": "state",
                "type": "STRING",
                "mode": "NULLABLE"
            },
            {
                "name": "zip",
                "type": "STRING",
                "mode": "NULLABLE"
            },
            {
                "name": "numberOfYears",
                "type": "STRING",
                "mode": "NULLABLE"
            }
        ]
    }
]

Pour plus d'informations sur la spécification d'un schéma imbriqué et répété, voir Utiliser des champs imbriqués et répétés.

Ajouter ou écraser des données dans une table avec des données JSON

Vous pouvez charger des données supplémentaires dans une table à partir de fichiers sources ou en ajoutant des résultats de requête. Si le schéma des données ne correspond pas au schéma de la table ou de la partition de destination, vous pouvez mettre à jour le schéma lorsque vous y ajoutez des données ou lorsque vous le remplacez.

Si vous mettez à jour le schéma lors de l'ajout de données, BigQuery vous permet d'effectuer les opérations suivantes :

  • Ajouter des champs
  • Changer des champs REQUIRED en NULLABLE

Si vous écrasez une table, le schéma est toujours remplacé. Les mises à jour de schéma ne sont pas limitées lorsque vous écrasez une table.

Dans l'interface utilisateur Web de BigQuery, vous devez utiliser 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. La CLI et l'API incluent les options ci-dessous.

Option de l'interface utilisateur Web Indicateur de la CLI Propriété de l'API BigQuery Description
Écrire si le tableau est vide Aucun WRITE_EMPTY N'écrit les données que si la table est vide.
Ajouter au tableau --noreplace ou --replace=false ; si l'indicateur --[no]replace n'est pas spécifié, les données sont ajoutées par défaut. WRITE_APPEND (Valeur par défaut) Ajoute les données à la fin de la table.
Écraser le tableau --replace ou --replace=true WRITE_TRUNCATE Efface toutes les données existantes d'une table avant d'écrire les nouvelles données.

Pour charger des données JSON depuis Google Cloud Storage, puis les ajouter à une table BigQuery ou les utiliser pour écraser une table BigQuery, procédez comme suit :

Interface utilisateur Web

  1. Accédez à l'interface utilisateur Web de BigQuery.
    Accéder à l'interface utilisateur Web de BigQuery

  2. Dans le panneau de navigation, passez la souris sur un ensemble de données. Ensuite, cliquez sur l'icône représentant une flèche vers le bas image de la flèche vers le bas, puis sur Create new table (Créer une table). Le processus de chargement des données est identique à celui permettant de créer une table vide.

  3. Dans la section Source Data (Données sources) de la page Create Table (Créer une table), procédez comme suit :

    • Pour le paramètre Location (Emplacement), sélectionnez Google Cloud Storage. Dans le champ "Source", indiquez le paramètre URI Cloud Storage. Notez que vous ne pouvez pas inclure plusieurs URI dans l'interface utilisateur. 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 JSON (Newline Delimited) (JSON (délimité par retour à la ligne)).
  4. Dans la section Destination Table (Table de destination) de la page Create Table (Créer une table), procédez comme suit :
    • Pour le paramètre Table name (Nom de la table), choisissez l'ensemble de données approprié, puis saisissez dans le champ le nom de la table à laquelle vous ajoutez des données ou que vous écrasez.
    • Vérifiez que le paramètre Table type (Type de table) est défini sur Native table (Table native{).
  5. Dans la section Schema (Schéma), entrez la définition du schéma. Pour mettre à jour le schéma, vous pouvez ajouter de nouveaux champs ou modifier (assouplir) les champs en les faisant passer de REQUIRED à NULLABLE.

    • Pour les fichiers JSON, vous pouvez cocher l'option Auto-detect (Détection automatique) pour activer la détection automatique de schémas.

      lien vers la détection automatique

    • Vous pouvez également saisir les informations du schéma manuellement en utilisant les méthodes suivantes :

      • En cliquant sur Edit as text (Modifier sous forme de texte), puis en saisissant le schéma de la table en tant que tableau JSON :

        Ajouter un schéma en tant que tableau JSON

      • En utilisant Add Field (Ajouter un champ) pour saisir manuellement le schéma :

        Ajouter un schéma en utilisant l'ajout de champs

  6. Dans la section Options, pour l'option Write preference (Préférence d'écriture), choisissez Write if empty (Écrire si le tableau est vide), Append to table (Ajouter à la table) ou Overwrite table (Écraser la table).

    Ajouter un schéma en utilisant l'ajout de champs

  7. Cliquez sur Create a Table (Créer une table).

Ligne de commande

Saisissez la commande bq load avec l'indicateur --replace pour écraser la table. Spécifiez l'indicateur --location et définissez la valeur sur votre emplacement. Utilisez l'indicateur --noreplace pour ajouter des données à la table. Si aucun indicateur n'est spécifié, les données sont ajoutées par défaut.

Lorsque vous ajoutez ou écrasez une table, vous pouvez utiliser l'indicateur --schema_update_option pour mettre à jour le schéma de la table de destination avec le schéma des nouvelles données. Les options suivantes peuvent être utilisées avec l'indicateur --schema_update_option :

  • ALLOW_FIELD_ADDITION : ajoute de nouveaux champs au schéma ; ces nouveaux champs ne peuvent pas être REQUIRED.
  • ALLOW_FIELD_RELAXATION : change les champs obligatoires en champs pouvant être vides ; répétez cette option pour spécifier une liste de valeurs.

bq --location=[LOCATION] load --[no]replace [DATASET].[TABLE] [PATH_TO_SOURCE] [SCHEMA]

où :

  • [LOCATION] correspond à votre emplacement. L'indicateur --location est facultatif si vos données se trouvent dans l'emplacement multirégional US ou EU. Vous pouvez spécifier une valeur par défaut pour l'emplacement à l'aide du fichier .bigqueryrc.
  • [DATASET] est un ensemble de données existant.
  • [TABLE] est le nom de la table dans laquelle vous chargez les données.
  • [PATH_TO_SOURCE] correspond à un URI Cloud Storage complet ou à une liste d'URI séparés par des virgules. Les caractères génériques sont également autorisés.
  • [SCHEMA] est un schéma valide. Ce schéma peut être un fichier JSON local ou il peut être saisi en ligne dans la commande. Vous pouvez également utiliser l'indicateur --autodetect au lieu de fournir une définition de schéma.

En outre, vous pouvez ajouter des indicateurs pour les options JSON, qui vous permettent de contrôler la manière dont BigQuery analyse vos données.

Exemples :

  • La commande suivante permet de charger les données de gs://mybucket/mydata.json en écrasant une table nommée mytable dans mydataset. Le schéma est défini à l'aide de la détection automatique de schéma. mybucket et mydataset ont été créés dans l'emplacement multirégional US.

    bq --location=US load --autodetect --replace --source_format=NEWLINE_DELIMITED_JSON mydataset.mytable gs://mybucket/mydata.json
    
  • La commande suivante permet de charger les données de gs://mybucket/mydata.json en ajoutant des données à une table nommée mytable dans mydataset. Le schéma est défini à l'aide d'un fichier de schéma JSON nommé myschema.json. mybucket et mydataset ont été créés dans l'emplacement multirégional US.

    bq --location=US load --autodetect --noreplace --source_format=NEWLINE_DELIMITED_JSON mydataset.mytable gs://mybucket/mydata.json ./myschema.json
    
  • La commande suivante permet de charger les données de gs://mybucket/mydata.json en ajoutant des données à une table nommée mytable dans mydataset. Un fichier de schéma JSON local nommé myschema.json est utilisé. La définition de schéma contient de nouveaux champs non présents dans la table de destination. mybucket et mydataset ont été créés dans la région asia-northeast1.

    bq --location=asia-northeast1 load --noreplace --schema_update_option=ALLOW_FIELD_ADDITION --source_format=NEWLINE_DELIMITED_JSON mydataset.mytable gs://mybucket/mydata.json ./myschema.json
    
  • La commande suivante permet de charger les données de gs://mybucket/mydata.csv en ajoutant des données à une table nommée mytable dans mydataset. Un fichier de schéma JSON local nommé myschema.json est utilisé. La définition de schéma permet de changer (assouplir) deux champs REQUIRED en NULLABLE. mybucket et mydataset ont été créés dans la région asia-northeast1.

    bq --location=asia-northeast1 load --noreplace --schema_update_option=ALLOW_FIELD_RELAXATION --source_format=NEWLINE_DELIMITED_JSON mydataset.mytable gs://mybucket/mydata.json ./myschema.json
    

API

Définissez les propriétés suivantes pour charger des données JSON à l'aide de l'API.

  1. Créez une tâche de chargement qui pointe vers les données sources dans Google Cloud Storage.

  2. Spécifiez votre emplacement dans la propriété location de la section jobReference de la ressource associée à la tâche.

  3. Les URI sources doivent être complets et respecter le format gs://[BUCKET]/[OBJECT]. Vous pouvez inclure plusieurs URI sous la forme d'une liste d'éléments séparés par une virgule. Notez que les caractères génériques sont également acceptés lorsque vous chargez des données CSV depuis Google Cloud Storage.

  4. Spécifiez le format de données en définissant la propriété configuration.load.sourceFormat sur NEWLINE_DELIMITED_JSON.

  5. Spécifiez la préférence d'écriture en définissant la propriété configuration.load.writeDisposition sur WRITE_TRUNCATE, WRITE_APPEND ou WRITE_EMPTY.

  6. Pour mettre à jour le schéma dans votre tâche de chargement, définissez la propriété configuration.load.schemaUpdateOptions sur ALLOW_FIELD_ADDITION ou ALLOW_FIELD_RELAXATION.

Python

Avant d'essayer cet exemple, suivez les instructions de configuration de Python décrites dans le guide de démarrage rapide de BigQuery : Utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Python.

Pour ajouter des lignes à une table existante, définissez la propriété LoadJobConfig.write_disposition sur la chaîne WRITE_APPEND.

# from google.cloud import bigquery
# client = bigquery.Client()
# table_ref = client.dataset('my_dataset').table('existing_table')

previous_rows = client.get_table(table_ref).num_rows
assert previous_rows > 0

job_config = bigquery.LoadJobConfig()
job_config.write_disposition = bigquery.WriteDisposition.WRITE_APPEND
job_config.source_format = bigquery.SourceFormat.NEWLINE_DELIMITED_JSON
uri = 'gs://cloud-samples-data/bigquery/us-states/us-states.json'
load_job = client.load_table_from_uri(
    uri,
    table_ref,
    job_config=job_config)  # API request

assert load_job.job_type == 'load'

load_job.result()  # Waits for table load to complete.

assert load_job.state == 'DONE'
assert client.get_table(table_ref).num_rows == previous_rows + 50

Pour remplacer les lignes d'une table existante, définissez la propriété LoadJobConfig.write_disposition sur la chaîne WRITE_TRUNCATE.

# from google.cloud import bigquery
# client = bigquery.Client()
# table_ref = client.dataset('my_dataset').table('existing_table')

previous_rows = client.get_table(table_ref).num_rows
assert previous_rows > 0

job_config = bigquery.LoadJobConfig()
job_config.write_disposition = bigquery.WriteDisposition.WRITE_TRUNCATE
job_config.source_format = bigquery.SourceFormat.NEWLINE_DELIMITED_JSON
uri = 'gs://cloud-samples-data/bigquery/us-states/us-states.json'
load_job = client.load_table_from_uri(
    uri,
    table_ref,
    job_config=job_config)  # API request

assert load_job.job_type == 'load'

load_job.result()  # Waits for table load to complete.

assert load_job.state == 'DONE'
assert client.get_table(table_ref).num_rows == 50

Ruby

Avant d'essayer cet exemple, suivez les instructions de configuration de Ruby décrites dans le guide de démarrage rapide de BigQuery : Utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Ruby.

Pour ajouter des lignes à une table existante, définissez le paramètre write de Table.load_job () sur "WRITE_APPEND".

# project_id = "Your Google Cloud project ID"
# dataset_id = "ID of the dataset containing table"
# table_id   = "ID of the table to append data into"

require "google/cloud/bigquery"

bigquery = Google::Cloud::Bigquery.new project: project_id
dataset  = bigquery.dataset dataset_id
table    = dataset.table table_id

storage_path = "gs://cloud-samples-data/bigquery/us-states/us-states.json"

puts "Importing data from Cloud Storage file: #{storage_path}"
load_job = table.load_job storage_path,
                          format: "json",
                          write: "WRITE_APPEND"

puts "Waiting for load job to complete: #{load_job.job_id}"
load_job.wait_until_done!

puts "Data imported"

Pour remplacer les lignes d'une table existante, définissez le paramètre write de Table.load_job () sur "WRITE_TRUNCATE".

# project_id = "Your Google Cloud project ID"
# dataset_id = "ID of the dataset containing table"
# table_id   = "ID of the table to append data into"

require "google/cloud/bigquery"

bigquery = Google::Cloud::Bigquery.new project: project_id
dataset  = bigquery.dataset dataset_id
table    = dataset.table table_id

storage_path = "gs://cloud-samples-data/bigquery/us-states/us-states.json"

puts "Importing data from Cloud Storage file: #{storage_path}"
load_job = table.load_job storage_path,
                          format: "json",
                          write: "WRITE_TRUNCATE"

puts "Waiting for load job to complete: #{load_job.job_id}"
load_job.wait_until_done!

puts "Data imported"

Options JSON

Pour modifier la façon dont BigQuery analyse les données JSON, spécifiez des options supplémentaires dans l'interface utilisateur, la CLI ou l'API.

Option JSON Option de l'interface utilisateur Web Indicateur de la CLI Propriété de l'API BigQuery Description
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.
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 traite comme une valeur supplémentaire : CSV : colonnes finales ; JSON : valeurs nommées ne correspondant à aucun nom de colonne
Cette page vous a-t-elle été utile ? Évaluez-la :

Envoyer des commentaires concernant…