Charger des données à partir d'exportations Firestore

BigQuery accepte le chargement de données à partir des exportations Firestore créées à l'aide du service d'importation et d'exportation géré de Firestore. Le service d'importation et d'exportation géré permet d'exporter les documents Firestore dans un bucket Cloud Storage. Vous pouvez ensuite charger les données exportées dans une table BigQuery.

Remarque : Toutes les exportations Firestore ne peuvent pas être chargées. Référencez les limitations BigQuery pour créer une exportation Firestore qu'il est possible de charger dans une table BigQuery.

Limites

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

• Votre ensemble de données doit se trouver dans la même zone que le bucket Cloud Storage contenant vos fichiers d'exportation.
• Vous ne pouvez spécifier qu'un seul URI Cloud Storage, et celui-ci ne doit pas comporter de caractère générique.
• Pour qu'une exportation Firestore se charge correctement, les documents compris dans les données d'exportation doivent partager un même schéma comportant moins de 10 000 noms de champ uniques.
• Pour le stockage des données, vous pouvez créer une table ou écraser une table existante. Vous ne pouvez pas ajouter de données d'exportation Firestore à une table existante.
• Votre commande d'exportation doit spécifier un filtre collection-ids. Les données exportées sans filtre d'ID de collection spécifié ne peuvent pas être chargées dans BigQuery.

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 connaître 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 Firestore

Vous pouvez charger des données à partir d'un fichier de métadonnées d'exportation Firestore à l'aide de la console Google Cloud, de l'outil de ligne de commande bq ou de l'API.

Même si la terminologie Datastore est parfois utilisée dans la console Google Cloud et dans l'outil de ligne de commande bq, les procédures suivantes sont compatibles avec les fichiers d'exportation Firestore. Firestore et Datastore utilisent le même format d'exportation.

Remarque : Vous pouvez charger des champs spécifiques en utilisant l'option --projection_fields dans l'outil de ligne de commande bq ou en définissant la propriété projectionFields dans la configuration de la tâche load

Console

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

   Accéder à BigQuery

2. Dans le volet Explorateur, développez votre projet, puis sélectionnez un ensemble de données.
3. Dans la section Informations sur l'ensemble de données, cliquez sur Créer une table.
4. Dans le panneau Créer une table, spécifiez les détails suivants :
1. 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 Firestore doit se terminer par KIND_COLLECTION_ID.export_metadata. Par exemple, dans default_namespace_kind_Book.export_metadata, Book est l'ID de collection et default_namespace_kind_Book est le nom de fichier généré par Firestore. Si l'URI ne se termine pas par KIND_COLLECTION_ID.export_metadata, vous recevez le message d'erreur suivant : ne contient pas de métadonnées de sauvegarde valides. (code d'erreur : non valide).
      Remarque : N'utilisez pas le fichier se terminant par overall_export_metadata. Ce fichier n'est pas utilisable par BigQuery.
      
   2. Pour le champ Format de fichier, sélectionnez Sauvegarde Cloud Datastore. Firestore et Datastore utilisent le même format d'exportation.
2. 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.
3. Aucune action n'est nécessaire dans la section Schéma. Dans le cas d'une exportation Firestore, le schéma est obtenu automatiquement.
4. 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.
5. 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.
6. Cliquez sur Créer une table.

bq

Exécutez la commande bq load en définissant source_format sur DATASTORE_BACKUP. Spécifiez l'option --location et définissez la valeur correspondant à votre emplacement. Si vous comptez écraser une table existante, ajoutez l'option --replace.

Si vous ne souhaitez charger que certains champs, utilisez l'indicateur --projection_fields.

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

Remplacez l'élément suivant :

• LOCATION : votre position. L'option --location est facultative.
• FORMAT : DATASTORE_BACKUP. Il s'agit de l'option appropriée pour Firestore. Firestore et Datastore utilisent le même format d'exportation.
• DATASET : ensemble de données contenant la table dans laquelle vous chargez des données.
• TABLE : la table dans laquelle vous chargez les données. Si la table n'existe pas, elle est créée.
• PATH_TO_SOURCE : URI Cloud Storage.

Par exemple, la commande suivante charge le fichier d'exportation Firestore 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 Firestore à l'aide de l'API.

1. Créez une configuration de tâche de chargement (load) qui pointe vers les données source dans Cloud Storage.

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

3. Le nom du champ sourceUris doit être complet et respecter le format gs://BUCKET/OBJECT dans la configuration de la tâche de chargement. Le nom du fichier (objet) doit se terminer par KIND_NAME.export_metadata. Un seul URI est autorisé pour les exportations Firestore, et vous ne pouvez pas utiliser de caractère générique.

4. Spécifiez le format de données en définissant la propriété sourceFormat sur DATASTORE_BACKUP dans la configuration de la tâche de chargement. "Sauvegarde Datastore" est l'option appropriée pour Firestore. Firestore et Datastore utilisent le même format d'exportation.

5. Si vous ne souhaitez charger que certains champs, définissez la propriété projectionFields.

6. Si vous comptez écraser une table existante, spécifiez la disposition en écriture en définissant la propriété writeDisposition sur WRITE_TRUNCATE.

Python

Avant d'essayer cet exemple, suivez les instructions de configuration pour Python du 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 pour Python.

Pour vous authentifier auprès de BigQuery, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

# TODO(developer): Set table_id to the ID of the table to create.
table_id = "your-project.your_dataset.your_table_name"

# TODO(developer): Set uri to the path of the kind export metadata
uri = (
    "gs://cloud-samples-data/bigquery/us-states"
    "/2021-07-02T16:04:48_70344/all_namespaces/kind_us-states"
    "/all_namespaces_kind_us-states.export_metadata"
)

# TODO(developer): Set projection_fields to a list of document properties
#                  to import. Leave unset or set to `None` for all fields.
projection_fields = ["name", "post_abbr"]

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

job_config = bigquery.LoadJobConfig(
    source_format=bigquery.SourceFormat.DATASTORE_BACKUP,
    projection_fields=projection_fields,
)

load_job = client.load_table_from_uri(
    uri, table_id, job_config=job_config
)  # Make an API request.

load_job.result()  # Waits for the job to complete.

destination_table = client.get_table(table_id)
print("Loaded {} rows.".format(destination_table.num_rows))

Remarque : 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.

Options de Firestore

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

Option de la console Google Cloud	Option "bq"	Propriété de l'API BigQuery	Description
Non disponible	--projection_fields	projectionFields (Java, Python)	(Facultatif) Liste indiquant les champs de document à charger depuis une exportation Firestore, séparés par une virgule. Par défaut, BigQuery charge tous les champs. Les noms de champ sont sensibles à la casse, et tous les champs répertoriés doivent être présents dans l'exportation. Vous ne pouvez pas spécifier de chemins de champ dans un champ de mappage tel que map.foo.

Conversion des types de données

BigQuery convertit les données de chaque document présent dans les fichiers d'exportation Firestore en types de données BigQuery. Le tableau suivant décrit la conversion entre les types de données acceptés.

Type de données Firestore	Type de données BigQuery
Tableau	RECORD
Booléen	BOOLEAN
Référence	RECORD
Date et heure	TIMESTAMP
Plan	RECORD
Nombre à virgule flottante	FLOAT
Point géographique	RECORD [{"lat","FLOAT"}, {"long","FLOAT"}]
Entier	INTEGER
Chaîne	STRING (tronqué à 64 Ko)

Propriétés des clés Firestore

Chaque document présent dans Firestore possède une clé unique contenant des informations telles que son ID et son chemin d'accès. BigQuery crée un type de données RECORD (ou STRUCT) 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 Firestore.	STRING
__key__.id	ID du document, ou null si __key__.name est défini.	INTEGER
__key__.kind	ID de collection du document	STRING
__key__.name	Nom du document, ou null si __key__.id est défini.	STRING
__key__.namespace	Firestore n'accepte pas les espaces de noms personnalisés. L'espace de noms par défaut est représenté par une chaîne vide.	STRING
__key__.path	Chemin d'accès au document, constitué par la séquence du document et des paires identifiant les collections à partir de la collection racine. Exemple : "Country", "USA", "PostalCode", 10011, "Route", 1234.	STRING