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.

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

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 Cloud IAM prédéfinis suivants incluent les autorisations bigquery.tables.create et bigquery.tables.updateData :

  • bigquery.dataEditor
  • bigquery.dataOwner
  • bigquery.admin

Les rôles Cloud 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 bigquery.dataOwner permet à l'utilisateur de créer et de mettre à jour des tables dans l'ensemble de données via une tâche de chargement.

Pour en savoir plus sur les rôles et les autorisations IAM dans BigQuery, consultez la page 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 Cloud IAM prédéfini storage.objectViewer peut être accordé pour fournir les autorisations storage.objects.get et storage.objects.list.

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 l'UI Web de BigQuery, de l'outil de ligne de commande bq ou de l'API.

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

Console

  1. Ouvrez l'UI Web de BigQuery dans Cloud Console.
    Accéder à l'UI Web de BigQuery
  2. Dans la section Ressources du panneau de navigation, développez votre projet et sélectionnez un ensemble de données. Cliquez sur Créer une table. Le processus de chargement des données est identique au processus de création d'une table vide. Créer une table
  3. Dans la section Source de la page Créer une table :

    • Dans Créer une table à partir de, sélectionnez Cloud Storage.

    • Dans le champ de la source, saisissez l'URI Cloud Storage. Le bucket Cloud Storage doit se trouver au même emplacement que votre ensemble de données. L'URI de votre fichier d'exportation Firestore doit se terminer par [KIND_COLLECTION_ID].export_metadata. 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 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).

    • Dans le champ Format de fichier, sélectionnez Sauvegarde Datastore. Il s'agit de l'option appropriée pour Firestore. Firestore et Datastore utilisent le même format d'exportation.

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

    • Sous Nom de l'ensemble de données, sélectionnez l'ensemble de données approprié.

      Sélectionner un ensemble de données

    • Dans le champ Nom de la table, saisissez 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 Firestore, le schéma est obtenu automatiquement.

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

    Écraser la table

  7. Cliquez sur Créer une table.

UI classique

  1. Accédez à l'UI Web classique 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 la flèche vers le bas image de la flèche vers le bas puis sur Créer une table.
  3. Dans la section Données source 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 Cloud Storage. Dans le champ de la source, saisissez l'URI Cloud Storage. Le bucket Cloud Storage doit se trouver au même emplacement que votre ensemble de données. L'URI de votre fichier d'exportation Firestore doit se terminer par [KIND_COLLECTION_ID].export_metadata. 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 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).

    • Dans le champ Format de fichier, sélectionnez Sauvegarde Datastore. Il s'agit de l'option appropriée pour Firestore. Firestore et Datastore utilisent le même format d'exportation.

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

    • Pour le champ Nom de la table, sélectionnez l'ensemble de données approprié, puis saisissez le nom de la table que vous créez dans BigQuery dans le champ correspondant.
    • 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 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.

CLI

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]

où :

  • [LOCATION] correspond à votre zone. L'option --location est facultative.
  • [FORMAT] est DATASTORE_BACKUP. "Sauvegarde Datastore" est l'option appropriée pour Firestore. Firestore et 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 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.

Options de Firestore

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

Option CSV Option de l'UI classique Option 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 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.
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 Firestore en types de données BigQuery. Le tableau suivant décrit la conversion entre les types de données.

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
Cette page vous a-t-elle été utile ? Évaluez-la :

Envoyer des commentaires concernant…

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