Charger des données à partir d'exportations Cloud Datastore

BigQuery accepte le chargement de données à partir des exportations Datastore créées à l'aide du service d'importation et d'exportation géré de Datastore. Le service d'importation et d'exportation géré permet d'exporter des entités Datastore dans un bucket Cloud Storage. Il suffit ensuite de charger l'exportation dans BigQuery en tant que table.

Pour apprendre à créer un fichier d'exportation Datastore, consultez la page Exporter et importer des entités de la documentation Cloud Datastore. Pour en savoir plus sur la planification des exportations, consultez la page Programmer une exportation.

Vous pouvez contrôler les propriétés que BigQuery doit charger en définissant la propriété projectionFields dans l'API ou en utilisant l'option --projection_fields dans l'outil de ligne de commande bq.

Si vous préférez éviter le processus de chargement, configurez l'exportation en tant que source de données externe afin de pouvoir l'interroger directement. Pour en savoir plus, consultez la page Sources de données externes.

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.

Limites

Lorsque vous chargez des données dans BigQuery à partir d'une exportation Datastore, tenez compte des restrictions suivantes :

Vous ne pouvez pas utiliser de caractère générique dans l'URI Cloud Storage lorsque vous spécifiez un fichier d'exportation Datastore.
Vous ne pouvez spécifier qu'un seul URI Cloud Storage lors du chargement de données à partir d'exportations Datastore.
Vous ne pouvez pas ajouter de données d'exportation Datastore à une table existante avec un schéma défini.
Pour qu'une exportation Datastore se charge correctement, les entités comprises dans les données d'exportation doivent partager un même schéma comportant moins de 10 000 noms de propriété uniques.
Les données exportées sans filtre d'entité spécifié ne peuvent pas être chargées dans BigQuery. La requête d'exportation doit inclure un ou plusieurs noms de genre dans le filtre d'entité.
La taille maximale du champ pour les exportations Datastore est de 64 Ko. Lorsque vous chargez une exportation Datastore, si le champ dépasse 64 Ko, il est tronqué.

Avant de commencer

Attribuez aux utilisateurs des rôles IAM (Identity and Access Management) incluant les autorisations nécessaires pour effectuer l'ensemble des tâches du présent document.

Autorisations requises

Pour charger des données dans BigQuery, vous devez disposer d'autorisations IAM pour exécuter une tâche de chargement et charger des données dans des tables et partitions BigQuery. Si vous chargez des données à partir de Cloud Storage, vous devez également disposer d'autorisations IAM pour accéder au bucket contenant vos données.

Autorisations pour charger des données dans BigQuery

Pour charger des données dans une nouvelle table ou partition BigQuery, ou pour ajouter ou écraser une table ou une partition existante, vous avez besoin des autorisations IAM suivantes :

bigquery.tables.create
bigquery.tables.updateData
bigquery.tables.update
bigquery.jobs.create

Chacun des rôles IAM prédéfinis suivants inclut les autorisations dont vous avez besoin pour charger des données dans une table ou une partition BigQuery :

roles/bigquery.dataEditor
roles/bigquery.dataOwner
roles/bigquery.admin (inclut l'autorisation bigquery.jobs.create)
bigquery.user (inclut l'autorisation bigquery.jobs.create)
bigquery.jobUser (inclut l'autorisation bigquery.jobs.create)

En outre, si vous disposez de l'autorisation bigquery.datasets.create, vous pouvez créer et mettre à jour des tables à l'aide d'une tâche de chargement dans les ensembles de données que vous créez.

Pour en savoir plus sur les rôles et les autorisations IAM dans BigQuery, consultez la page Rôles prédéfinis et autorisations.

Autorisations pour charger des données à partir de Cloud Storage

Pour obtenir les autorisations nécessaires pour charger des données à partir d'un bucket Cloud Storage, demandez à votre administrateur de vous accorder le rôle IAM Administrateur Storage (roles/storage.admin) sur le bucket. Pour en savoir plus sur l'attribution de rôles, consultez la section Gérer les accès.

Ce rôle prédéfini contient les autorisations requises pour charger des données à partir d'un bucket Cloud Storage. Pour afficher les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Vous devez disposer des autorisations suivantes pour charger des données à partir d'un bucket Cloud Storage :

storage.buckets.get
storage.objects.get
storage.objects.list (required if you are using a URI wildcard)

Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.

Charger des données du service d'exportation Datastore

Pour charger des données à partir d'un fichier de métadonnées d'exportation Datastore, procédez comme suit :

Console

Dans la console Google Cloud, accédez à la page BigQuery.

Accéder à BigQuery
Dans le volet Explorateur, développez votre projet, puis sélectionnez un ensemble de données.
Dans la section Informations sur l'ensemble de données, cliquez sur Créer une table.
Dans le panneau Créer une table, spécifiez les détails suivants :

Dans la section Source, sélectionnez Google Cloud Storage dans la liste Créer une table à partir de. Ensuite, procédez comme suit :
1. Sélectionnez un fichier dans le bucket Cloud Storage ou saisissez l'URI Cloud Storage. Vous ne pouvez pas inclure plusieurs URI dans la console Google Cloud. 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 souhaitez créer, ajouter ou écraser.
  L'URI de votre fichier d'exportation Datastore doit se terminer par KIND_NAME.export_metadata ou export[NUM].export_metadata. Par exemple, dans default_namespace_kind_Book.export_metadata, Book correspond au nom du genre et default_namespace_kind_Book au nom de fichier généré par Datastore.
2. Pour le champ Format de fichier, sélectionnez Sauvegarde Cloud Datastore.
Dans la section Destination, spécifiez les détails suivants :
1. Pour Ensemble de données, sélectionnez l'ensemble de données dans lequel vous souhaitez créer la table.
2. Dans le champ Table, saisissez le nom de la table que vous souhaitez créer.
3. Vérifiez que le champ Type de table est défini sur Table native.
Aucune action n'est nécessaire dans la section Schéma. Dans le cas d'une exportation Datastore, le schéma est obtenu automatiquement.
Facultatif : spécifiez les paramètres de partitionnement et de clustering. Pour en savoir plus, consultez les pages Créer des tables partitionnées et Créer et utiliser des tables en cluster.
Cliquez sur Options avancées et procédez comme suit :
- Sous 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.
- Si vous souhaitez ignorer les valeurs d'une ligne qui ne sont pas présentes dans le schéma de la table, sélectionnez Valeurs inconnues.
- 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 avec le paramètre source_format défini sur DATASTORE_BACKUP. Spécifiez l'option --location et définissez la valeur correspondant à votre emplacement.

bq --location=LOCATION load \
--source_format=FORMAT \
DATASET.TABLE \
PATH_TO_SOURCE

Remplacez les éléments suivants :

LOCATION : votre position. 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 sur asia-northeast1. Vous pouvez spécifier une valeur par défaut pour l'emplacement à l'aide du fichier .bigqueryrc.
FORMAT : DATASTORE_BACKUP.
DATASET : ensemble de données contenant la table dans laquelle vous chargez des données.
TABLE : table dans laquelle vous chargez les données. Si cette table n'existe pas, elle est créée.
PATH_TO_SOURCE : URI Cloud Storage.

Par exemple, la commande suivante charge le fichier d'exportation Datastore gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata dans une table nommée book_data. mybucket et mydataset ont été créés dans l'emplacement multirégional US.

bq --location=US load \
--source_format=DATASTORE_BACKUP \
mydataset.book_data \
gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata

API

Définissez les propriétés suivantes pour charger les données d'exportation Datastore à l'aide de l'API.

Créez une tâche de chargement qui pointe vers les données sources dans Cloud Storage.
Spécifiez votre emplacement dans la propriété location de la section jobReference de la ressource de tâche.
Les URI sources doivent être complets et respecter le format gs://[BUCKET]/[OBJECT]. Le nom du fichier (objet) doit se terminer par [KIND_NAME].export_metadata. Vous ne pouvez spécifier qu'un seul URI pour les exportations Datastore. En outre, celui-ci ne doit pas comporter de caractère générique.
Spécifiez le format de données en définissant la propriété configuration.load.sourceFormat sur DATASTORE_BACKUP.

Ajouter ou écraser une table avec des données Datastore

Lorsque vous chargez des données d'exportation Datastore dans BigQuery, vous pouvez créer une table pour stocker les données ou écraser une table existante. Vous ne pouvez pas ajouter de données d'exportation Datastore à une table existante.

Si vous tentez d'ajouter des données d'exportation Datastore à une table existante, le message d'erreur suivant s'affiche : Cannot append a datastore backup to a table that already has a schema. Try using the WRITE_TRUNCATE write disposition to replace the existing table.

Pour écraser une table existante avec des données d'exportation Datastore, procédez comme suit :

Console

Dans la console Google Cloud, accédez à la page BigQuery.

Accéder à BigQuery
Dans le volet Explorateur, développez votre projet, puis sélectionnez un ensemble de données.
Dans la section Informations sur l'ensemble de données, cliquez sur Créer une table.
Dans le panneau Créer une table, spécifiez les détails suivants :

Dans la section Source, sélectionnez Google Cloud Storage dans la liste Créer une table à partir de. Ensuite, procédez comme suit :
1. Sélectionnez un fichier dans le bucket Cloud Storage ou saisissez l'URI Cloud Storage. Vous ne pouvez pas inclure plusieurs URI dans la console Google Cloud. 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 souhaitez créer, ajouter ou écraser.
  L'URI de votre fichier d'exportation Datastore doit se terminer par KIND_NAME.export_metadata ou export[NUM].export_metadata. Par exemple, dans default_namespace_kind_Book.export_metadata, Book correspond au nom du genre et default_namespace_kind_Book au nom de fichier généré par Datastore.
2. Pour le champ Format de fichier, sélectionnez Sauvegarde Cloud Datastore.

Dans la section Destination, spécifiez les détails suivants :
1. Pour Ensemble de données, sélectionnez l'ensemble de données dans lequel vous souhaitez créer la table.
2. Dans le champ Table, saisissez le nom de la table que vous souhaitez créer.
3. Vérifiez que le champ Type de table est défini sur Table native.
Aucune action n'est nécessaire dans la section Schéma. Dans le cas d'une exportation Datastore, le schéma est obtenu automatiquement.

Facultatif : spécifiez les paramètres de partitionnement et de clustering. Pour en savoir plus, consultez les pages Créer des tables partitionnées et Créer et utiliser des tables en cluster. Vous ne pouvez pas convertir une table en table partitionnée ou en cluster en y ajoutant des données ou les écrasant. La console Google Cloud ne permet pas d'ajouter ni d'écraser des données dans des tables partitionnées ou en cluster lors d'une tâche de chargement.
Cliquez sur Options avancées et procédez comme suit :
- Sous Préférences d'écriture, choisissez Ajouter à la table ou Écraser la table.
- Si vous souhaitez ignorer les valeurs d'une ligne qui ne sont pas présentes dans le schéma de la table, sélectionnez Valeurs inconnues.
- 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 avec l'option --replace et le paramètre DATASTORE_BACKUP défini sur source_format. Spécifiez l'option --location et définissez la valeur correspondant à votre emplacement.

bq --location=LOCATION load \
--source_format=FORMAT \
--replace \
DATASET.TABLE \
PATH_TO_SOURCE

Remplacez les éléments suivants :

LOCATION : votre position. 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 sur asia-northeast1. Vous pouvez spécifier une valeur par défaut pour l'emplacement à l'aide du fichier .bigqueryrc.
FORMAT : DATASTORE_BACKUP.
DATASET : nom de l'ensemble de données contenant la table dans laquelle vous chargez des données.
TABLE : la table que vous écrasez.
PATH_TO_SOURCE : URI Cloud Storage.

bq load --source_format=DATASTORE_BACKUP \
--replace \
mydataset.book_data \
gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata

API

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

Créez une tâche de chargement qui pointe vers les données sources dans Cloud Storage.
Spécifiez votre emplacement dans la propriété location de la section jobReference de la ressource de tâche.
Les URI sources doivent être complets et respecter le format gs://[BUCKET]/[OBJECT]. Le nom du fichier (objet) doit se terminer par [KIND_NAME].export_metadata. Vous ne pouvez spécifier qu'un seul URI pour les exportations Datastore. En outre, celui-ci ne doit pas comporter de caractère générique.
Spécifiez le format de données en définissant la propriété configuration.load.sourceFormat sur DATASTORE_BACKUP.
Spécifiez la préférence d'écriture en définissant la propriété configuration.load.writeDisposition sur WRITE_TRUNCATE.

Options Datastore

Pour modifier la façon dont BigQuery analyse les données d'exportation Datastore, spécifiez l'option suivante :

Option de la console	Option de l'outil bq	Propriété de l'API BigQuery	Description
Non disponible	`--projection_fields`	projectionFields	Liste séparée par des virgules indiquant les propriétés d'entité à charger dans BigQuery à partir d'une exportation Datastore. Les noms de propriété sont sensibles à la casse et doivent être des propriétés de premier niveau. Si aucune propriété n'est spécifiée, BigQuery charge toutes les propriétés. Si une propriété nommée est introuvable dans l'exportation Datastore, une erreur "non valide" est renvoyée dans le résultat de la tâche. La valeur par défaut est ".

Conversion des types de données

BigQuery convertit les données de chaque entité dans les fichiers d'exportation Datastore en types de données BigQuery. Le tableau suivant décrit la conversion entre les types de données.

Type de données Datastore	Type de données BigQuery
Array	`ARRAY`
Blob	`BYTES`
Booléen	`BOOLEAN`
Date et heure	`TIMESTAMP`
Entité intégrée	`RECORD`
Nombre à virgule flottante	`FLOAT`
Point géographique	`RECORD` [{"lat","DOUBLE"}, {"long","DOUBLE"}]
Entier	`INTEGER`
Clé	`RECORD`
Null	`STRING`
Chaîne de texte	`STRING` (tronqué à 64 Ko)

Propriétés de la clé Datastore

Dans Datastore, chaque entité possède une clé unique contenant des informations telles que l'espace de noms et le chemin d'accès. BigQuery crée un type de données RECORD pour la clé, avec des champs imbriqués pour chaque information, comme décrit dans le tableau suivant.

Propriété de la clé	Description	Type de données BigQuery
`__key__.app`	Nom de l'application Datastore.	STRING
`__key__.id`	ID de l'entité, ou `null` si `__key__.name` est défini.	INTEGER
`__key__.kind`	Genre de l'entité.	STRING
`__key__.name`	Nom de l'entité, ou `null` si `__key__.id` est défini.	STRING
`__key__.namespace`	Si l'application Datastore utilise un espace de noms personnalisé, espace de noms de l'entité. Sinon, l'espace de noms par défaut est représenté par une chaîne vide.	STRING
`__key__.path`	Chemin ancestral aplati de l'entité, constitué de la séquence de paires genre-identifiant de l'entité racine à l'entité elle-même. Exemple : `"Country", "USA", "PostalCode", 10011, "Route", 1234`.	STRING