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

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

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 qui vous permettent de procéder au chargement 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 l'article Contrôle des 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.liststorage.objects.list.

Le rôle IAM prédéfini storage.objectViewer peut être autorisé à fournir des autorisations storage.objects.get et storage.objects.list.

Limites

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

  • Votre ensemble de données doit se trouver dans la même zone régionale ou multirégionale 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 Cloud 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 les données d'exportation Cloud Firestore à une table existante.
  • Si vous prévoyez de charger une exportation Cloud Firestore dans BigQuery, vous devez spécifier un filtre collection-ids dans votre commande d'exportation. Les données que vous exportez sans spécifier de filtre d'ID de collection ne peuvent pas être chargées dans BigQuery.

Charger les données du service d'exportation Cloud Firestore

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

Même si la terminologie Cloud Datastore est parfois utilisée dans l'interface utilisateur ou dans les commandes, les procédures suivantes sont compatibles avec les fichiers d'exportation Cloud Firestore. Les produits Cloud Firestore et Cloud Datastore utilisent le même format d'exportation.

Interface utilisateur Web classique

  1. Accédez à l'interface utilisateur Web de BigQuery.
    Accéder à l'UI Web de BigQuery
  2. Dans le panneau de navigation, passez la souris sur un ensemble de données, cliquez sur l'icône de flèche vers le bas image de la flèche vers le bas et cliquez sur Créer une nouvelle table.
  3. Dans la section Données sources de la page Créer une table :

    • Laissez l'option Créer à partir de la source sélectionnée.
    • Dans le champ Emplacement, sélectionnez Google Cloud Storage et, dans le champ "Source", saisissez l'URI Cloud Storage. Le bucket Cloud Storage doit être situé dans le même emplacement que votre ensemble de données. L'URI du fichier d'exportation Cloud Firestore doit se terminer par [KIND_COLLECTION_ID].export_metadata. Par exemple : default_namespace_kind_Book.export_metadata. Dans cet exemple, Book est l'ID de collection et default_namespace_kind_Book est le nom de fichier généré par Cloud Firestore.

      Vérifiez que [KIND_COLLECTION_ID] est spécifié dans votre URI Cloud Storage. Si vous spécifiez l'URI sans [KIND_COLLECTION_ID], vous obtenez l'erreur suivante : does not contain valid backup metadata.. (error code: invalid).

    • Pour le champ Format de fichier, sélectionnez Sauvegarde Cloud Datastore. "Sauvegarde Cloud Datastore" est l'option appropriée pour Cloud Firestore. Les produits Cloud Firestore et Cloud Datastore utilisent le même format d'exportation.

  4. Dans la section Table de destination de la page Créer une table :

    • Pour Nom de la table, sélectionnez 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 Type de table est défini sur Table native.
  5. Aucune action n'est nécessaire dans la section Schéma. Dans le cas d'une exportation Cloud Firestore, le schéma est obtenu automatiquement.

  6. Sélectionnez les éléments pertinents dans la section Options. Si vous comptez écraser une table existante, définissez Préférence d'écriture sur Écraser la table.

  7. Cliquez sur Créer une table.

Ligne de commande

Utilisez la commande bq load en définissant source_format sur DATASTORE_BACKUP. Spécifiez l'indicateur --location et définissez la valeur sur votre emplacement. Si vous comptez écraser une table existante, ajoutez l'indicateur --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]

où :

  • [LOCATION] correspond à votre emplacement. L'indicateur --location est facultatif.
  • [FORMAT] prend la valeur DATASTORE_BACKUP. "Sauvegarde Cloud Datastore" est l'option appropriée pour Cloud Firestore. Les produits Cloud Firestore et Cloud Datastore utilisent le même format d'exportation.
  • [DATASET] est l'ensemble de données qui contient la table dans laquelle vous chargez les données.
  • [TABLE] est la table dans laquelle vous chargez les données. Si cette table n'existe pas, elle est créée.
  • [PATH_TO_SOURCE] est l'URI Cloud Storage.

Par exemple, la commande suivante charge le fichier d'exportation Cloud 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 la zone multirégionale 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 Cloud Firestore à 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 de tâche.

  3. 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. Un seul URI est autorisé pour les exportations Cloud 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é configuration.load.sourceFormat sur DATASTORE_BACKUP. "Sauvegarde Cloud Datastore Backup" est l'option appropriée pour Cloud Firestore. Les produits Cloud Firestore et Cloud Datastore utilisent le même format d'exportation.

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

  6. Si vous comptez écraser une table existante, spécifiez la préférence d'écriture en définissant la propriété configuration.load.writeDisposition sur WRITE_TRUNCATE.

Options de Cloud Firestore

Pour modifier la façon dont BigQuery analyse les données d'exportation Cloud Firestore, spécifiez les options suivantes :

Option CSV Option de l'UI Web Indicateur de la CLI Propriété de l'API BigQuery Description
Champs de projection Aucune --projection_fields projectionFields (Facultatif) Liste indiquant les champs de document à charger depuis une exportation Cloud 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 d'accès de champ, comme map.foo, dans un champ de mappage.
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.

Conversion des types de données

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

Type de données Cloud 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 relatives aux clés Firestore

Chaque document présent dans Cloud Firestore possède une clé unique contenant des informations telles que son ID et son chemin d'accès. Pour traiter cette clé, BigQuery crée une structure de données du type RECORD (ou STRUCT) contenant des champs imbriqués pour les différentes informations, comme indiqué dans le tableau suivant.

Propriété de la clé Description Type de données BigQuery
__key__.app Nom de l'application Cloud 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 Cloud Firestore ne prend pas en charge 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 du document, constitué par la séquence du document et des paires champ-valeur identifiant les collections à partir de la collection racine. Par exemple : "Country", "USA", "PostalCode", 10011, "Route", 1234. STRING
Cette page vous a-t-elle été utile ? Évaluez-la :

Envoyer des commentaires concernant…

Besoin d'aide ? Consultez notre page d'assistance.