Créer des ensembles de données externes Spanner

Ce document explique comment créer un ensemble de données externe (également appelé ensemble de données fédéré) dans BigQuery associé à une base de données existante dans Spanner.

Un ensemble de données externe est une connexion entre BigQuery et une source de données externe au niveau de l'ensemble de données. Il vous permet d'interroger les données transactionnelles dans les bases de données Spanner avec Google SQL sans avoir à copier ni à importer toutes les données de Spanner vers le stockage BigQuery. Ces résultats de requête sont stockés dans BigQuery.

Les tables d'un ensemble de données externe sont renseignées automatiquement à partir des tables de la source de données externe correspondante. Vous pouvez interroger ces tables directement dans BigQuery, mais vous ne pouvez pas les modifier, les ajouter ni les supprimer. Cependant, toutes les mises à jour que vous effectuez dans la source de données externe sont automatiquement répercutées dans BigQuery.

Lorsque vous interrogez Spanner, les résultats de la requête sont enregistrés par défaut dans des tables temporaires. Vous pouvez également les enregistrer en tant que nouvelle table BigQuery, les joindre à d'autres tables ou les fusionner avec des tables existantes à l'aide de DML.

Autorisations requises

Pour obtenir l'autorisation dont vous avez besoin pour créer un ensemble de données externe, demandez à votre administrateur de vous accorder le rôle IAM Utilisateur BigQuery (roles/bigquery.user). Pour en savoir plus sur l'attribution de rôles, consultez la page Gérer l'accès aux projets, aux dossiers et aux organisations.

Ce rôle prédéfini contient l'autorisation bigquery.datasets.create, qui est requise pour créer un ensemble de données externe.

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

Pour plus d'informations sur les rôles et les autorisations IAM dans BigQuery, consultez la page Présentation d'IAM.

Utiliser une connexion CLOUD_RESOURCE

Les ensembles de données externes Spanner peuvent éventuellement utiliser une connexion CLOUD_RESOURCE pour interagir avec votre base de données Spanner. Vous pouvez ainsi autoriser un utilisateur à accéder aux données Spanner via BigQuery, sans lui donner un accès direct à la base de données Spanner. Étant donné que le compte de service de la connexion CLOUD_RESOURCE gère la récupération des données de Spanner, il vous suffit d'accorder aux utilisateurs l'accès à l'ensemble de données externe Spanner.

Avant de créer des ensembles de données externes Spanner avec une connexion CLOUD_RESOURCE, procédez comme suit:

Créer une connexion

Vous pouvez créer ou utiliser une connexion CLOUD_RESOURCE existante pour vous connecter à Spanner. Pour créer la connexion à la ressource Cloud, suivez les étapes décrites sur la page Créer une connexion à une ressource Cloud.

Une fois la connexion créée, ouvrez-la et, dans le volet Informations de connexion, copiez l'ID du compte de service. Vous aurez besoin de cet ID lorsque vous configurerez les autorisations pour la connexion. Lorsque vous créez une ressource de connexion, BigQuery crée un compte de service système unique et l'associe à la connexion.

Configurer l'accès

Vous devez accorder à la nouvelle connexion un accès en lecture à votre instance ou base de données Spanner. Il est recommandé d'utiliser le rôle IAM prédéfini Lecteur de bases de données Cloud Spanner avec DataBoost (roles/spanner.databaseReaderWithDataBoost).

Pour accorder l'accès à des rôles au niveau de la base de données pour le compte de service que vous avez copié précédemment à partir de la connexion, procédez comme suit:

  1. Accédez à la page Instances de Spanner.

    Accéder à la page Instances

  2. Cliquez sur le nom de l'instance contenant votre base de données pour accéder à la page Détails de l'instance.

  3. Dans l'onglet Vue d'ensemble, cochez la case correspondant à votre base de données.
    Le panneau d'information apparaît.

  4. Cliquez sur Ajouter un compte principal.

  5. Dans le panneau Ajouter des comptes principaux, dans Nouveaux comptes principaux, saisissez l'ID du compte de service que vous avez copié précédemment.

  6. Dans le champ Sélectionner un rôle, sélectionnez Lecteur de base de données Cloud Spanner avec le rôle DataBoost.

  7. Cliquez sur Enregistrer.

Créer un ensemble de données externe

Pour créer un ensemble de données externe, procédez comme suit:

Console

  1. Ouvrez la page BigQuery dans la console Google Cloud .

    Accéder à la page "BigQuery"

  2. Dans le panneau Explorer, sélectionnez le projet dans lequel vous souhaitez créer l'ensemble de données.

  3. Développez l'option Actions, puis cliquez sur Créer un ensemble de données.

  4. Sur la page Créer un ensemble de données, procédez comme suit :

    • Pour Dataset ID (ID de l'ensemble de données), renseignez un ensemble de données unique.
    • Dans Type d'emplacement, choisissez un emplacement pour l'ensemble de données, par exemple us-central1 ou us multirégional. Une fois l'ensemble de données créé, l'emplacement ne peut plus être modifié.

    • Pour Ensemble de données externe, procédez comme suit :

      • Cochez la case Associer à un ensemble de données externe.
      • Dans le champ Type d'ensemble de données externe, sélectionnez Spanner.
      • Dans le champ Source externe, saisissez l'identifiant complet de votre base de données Spanner au format suivant: projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE. Par exemple : projects/my_project/instances/my_instance/databases/my_database.
      • Vous pouvez éventuellement saisir le nom d'un rôle de base de données Spanner dans Rôle de base de données. Pour en savoir plus, consultez les rôles de base de données utilisés pour créer des connexions Spanner.
      • Vous pouvez également cocher la case Utiliser une connexion à une ressource cloud pour créer l'ensemble de données externe avec une connexion.

    • Ne modifiez pas les autres paramètres.

  5. Cliquez sur Créer l'ensemble de données.

SQL

Utilisez l'instruction LDD (langage de définition de données) CREATE EXTERNAL SCHEMA.

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

    Accéder à BigQuery

  2. Dans l'éditeur de requête, saisissez l'instruction suivante :

    CREATE EXTERNAL SCHEMA DATASET_NAME
  OPTIONS (
    external_source = 'SPANNER_EXTERNAL_SOURCE',
    location = 'LOCATION');
/*
  Alternatively, create with a connection:
*/
CREATE EXTERNAL SCHEMA DATASET_NAME
  WITH CONNECTION PROJECT_ID.LOCATION.CONNECTION_NAME
  OPTIONS (
    external_source = 'SPANNER_EXTERNAL_SOURCE',
    location = 'LOCATION');

    Remplacez les éléments suivants :

    • DATASET_NAME : nom de votre nouvel ensemble de données dans BigQuery.
    • SPANNER_EXTERNAL_SOURCE: nom complet de la base de données Spanner, avec un préfixe identifiant la source, au format suivant: google-cloudspanner://[DATABASE_ROLE@]/projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE. Exemples : google-cloudspanner://admin@/projects/my_project/instances/my_instance/databases/my_database ou google-cloudspanner:/projects/my_project/instances/my_instance/databases/my_database.
    • LOCATION: emplacement de votre nouvel ensemble de données dans BigQuery, par exemple, us-central1. Une fois que vous avez créé un ensemble de données, vous ne pouvez plus modifier son emplacement.
    • (Facultatif)CONNECTION_NAME: nom de votre connexion de ressources Cloud.

  3. Cliquez sur Exécuter.

Pour en savoir plus sur l'exécution des requêtes, consultez Exécuter une requête interactive.

bq

Dans un environnement de ligne de commande, créez un ensemble de données externe à l'aide de la commande bq mk:

bq --location=LOCATION mk --dataset \
    --external_source SPANNER_EXTERNAL_SOURCE \
    DATASET_NAME

Vous pouvez également créer une connexion:

bq --location=LOCATION mk --dataset \
    --external_source SPANNER_EXTERNAL_SOURCE \
    --connection_id PROJECT_ID.LOCATION.CONNECTION_NAME \
    DATASET_NAME

Remplacez les éléments suivants :

  • LOCATION : emplacement de votre nouvel ensemble de données dans BigQuery, par exemple, us-central1. Une fois que vous avez créé un ensemble de données, vous ne pouvez plus modifier son emplacement. Vous pouvez définir une valeur d'emplacement par défaut à l'aide du fichier .bigqueryrc.
  • SPANNER_EXTERNAL_SOURCE: nom complet de la base de données Spanner, avec un préfixe identifiant la source, au format suivant: google-cloudspanner://[DATABASE_ROLE@]/projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE. Par exemple, google-cloudspanner://admin@/projects/my_project/instances/my_instance/databases/my_database ou google-cloudspanner:/projects/my_project/instances/my_instance/databases/my_database.
  • DATASET_NAME : nom de votre nouvel ensemble de données dans BigQuery. Pour créer un ensemble de données dans un projet autre que votre projet par défaut, ajoutez l'ID du projet au nom de l'ensemble de données de la manière suivante : PROJECT_ID:DATASET_NAME.
  • (Facultatif)CONNECTION_NAME: nom de votre connexion de ressources Cloud.

Terraform

Utilisez la ressource google_bigquery_dataset.

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.

L'exemple suivant crée un ensemble de données externe Spanner:

resource "google_bigquery_dataset" "default" {
  dataset_id    = "my_external_dataset"
  friendly_name = "My external dataset"
  description   = "This is a test description."
  location      = "US"
  external_dataset_reference {
    # The full identifier of your Spanner database.
    external_source = "google-cloudspanner:/projects/my_project/instances/my_instance/databases/my_database"
    # Must be empty for a Spanner external dataset.
    connection = ""
  }
}

Pour appliquer votre configuration Terraform dans un projet Google Cloud , suivez les procédures des sections suivantes.

Préparer Cloud Shell

  1. Lancez Cloud Shell.

  2. Définissez le projet Google Cloud par défaut dans lequel vous souhaitez appliquer vos configurations Terraform.

    Vous n'avez besoin d'exécuter cette commande qu'une seule fois par projet et vous pouvez l'exécuter dans n'importe quel répertoire.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Les variables d'environnement sont remplacées si vous définissez des valeurs explicites dans le fichier de configuration Terraform.

Préparer le répertoire

Chaque fichier de configuration Terraform doit avoir son propre répertoire (également appelé module racine).

  1. Dans Cloud Shell, créez un répertoire et un nouveau fichier dans ce répertoire. Le nom du fichier doit comporter l'extension .tf, par exemple main.tf. Dans ce tutoriel, le fichier est appelé main.tf. 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. Si vous suivez un tutoriel, vous pouvez copier l'exemple de code dans chaque section ou étape.

    Copiez l'exemple de code dans le fichier main.tf que vous venez de créer.

    Vous pouvez également copier le code depuis GitHub. Cela est recommandé lorsque l'extrait Terraform fait partie d'une solution de bout en bout.

  3. Examinez et modifiez les exemples de paramètres à appliquer à votre environnement.
  4. Enregistrez les modifications.
  5. Initialisez Terraform. Cette opération n'est à effectuer qu'une seule fois par répertoire. 
    terraform init

    Vous pouvez également utiliser la dernière version du fournisseur Google en incluant l'option -upgrade : 

    terraform init -upgrade

Appliquer les modifications

  1. Examinez la configuration et vérifiez que les ressources que Terraform va créer ou mettre à jour correspondent à vos attentes : 
    terraform plan

    Corrigez les modifications de la configuration si nécessaire.

  2. Appliquez la configuration Terraform en exécutant la commande suivante et en saisissant yes lorsque vous y êtes invité : 
    terraform apply

    Attendez que Terraform affiche le message "Apply completed!" (Application terminée).

  3. Ouvrez votre Google Cloud projet pour afficher les résultats. Dans la console Google Cloud , accédez à vos ressources dans l'interface utilisateur pour vous assurer que Terraform les a créées ou mises à jour.

API

Appelez la méthode datasets.insert avec une ressource d'ensemble de données et un champ externalDatasetReference définis pour votre base de données Spanner.

Notez que les noms des tables des ensembles de données externes ne sont pas sensibles à la casse.

Lorsque vous créez des ensembles de données externes avec une connexion CLOUD_RESOURCE, vous devez disposer de l'autorisation bigquery.connections.delegate (disponible via le rôle Administrateur de connexion BigQuery) sur la connexion utilisée par les ensembles de données externes.

Contrôler l'accès aux tables

Les ensembles de données externes Spanner sont compatibles avec les identifiants des utilisateurs finaux. Cela signifie que l'accès aux tables Spanner à partir d'ensembles de données externes est contrôlé par Spanner. Les utilisateurs ne peuvent interroger ces tables que s'ils ont un accès accordé dans Spanner.

Les ensembles de données externes Spanner sont également compatibles avec la délégation d'accès. La délégation d'accès dissocie l'accès aux tables Spanner des ensembles de données externes et de l'accès direct aux tables Spanner sous-jacentes. Une connexion de ressource Cloud associée à un compte de service permet de se connecter à Spanner. Les utilisateurs peuvent interroger ces tables Spanner à partir d'ensembles de données externes, même s'ils n'ont pas d'accès dans Spanner.

Répertorier les tables dans un ensemble de données externe

Pour répertorier les tables disponibles pour l'interrogation dans votre ensemble de données externe, consultez la section Répertorier les ensembles de données.

Obtenir des informations sur la table

Pour obtenir des informations sur les tables de votre ensemble de données externe, telles que les détails du schéma, consultez la section Obtenir des informations sur la table.

Interroger des données Spanner

L'interrogation de tables dans des ensembles de données externes est la même que l'interrogation de tables dans n'importe quel autre ensemble de données BigQuery. Toutefois, les opérations de modification de données (LMD) ne sont pas acceptées.

Les requêtes adressées aux tables des ensembles de données externes Spanner utilisent Data Boost par défaut, et vous ne pouvez pas modifier ce paramètre. Vous avez donc besoin d'autorisations supplémentaires pour exécuter ces requêtes.

Créer une vue dans un ensemble de données externe

Vous ne pouvez pas créer de vue dans un ensemble de données externe. Toutefois, vous pouvez créer une vue dans un ensemble de données standard basée sur une table d'un ensemble de données externe. Pour en savoir plus, consultez la section Créer des vues.

Supprimer un ensemble de données externe

La suppression d'un ensemble de données externe est identique à la suppression de tout autre ensemble de données BigQuery. La suppression d'ensembles de données externes n'a aucune incidence sur les tables de la base de données Spanner. Pour en savoir plus, consultez la section Supprimer des ensembles de données.

Limites

  • Les limites des requêtes fédérées BigQuery s'appliquent.
  • Seules les tables d'un schéma Spanner par défaut sont accessibles dans BigQuery. Les tables des schémas de noms ne sont pas acceptées.
  • Les clés primaires et étrangères définies dans la base de données Spanner ne sont pas visibles dans BigQuery.
  • Si une table de la base de données Spanner contient une colonne d'un type non compatible avec BigQuery, cette colonne ne sera pas accessible côté BigQuery.
  • Vous ne pouvez pas ajouter, supprimer ni mettre à jour des données ni des métadonnées dans les tables d'un ensemble de données externe Spanner.
  • Vous ne pouvez pas créer de tables, de vues ni de vues matérialisées dans un ensemble de données externe Spanner.
  • Les vues INFORMATION_SCHEMA ne sont pas prises en charge.
  • La mise en cache des métadonnées n'est pas prise en charge.
  • Les paramètres au niveau de l'ensemble de données liés aux valeurs par défaut de création de table n'affectent pas les ensembles de données externes, car vous ne pouvez pas créer de tables manuellement.
  • Les bases de données Spanner qui utilisent le dialecte PostgreSQL ne sont pas compatibles.
  • Les API Write et Read ne sont pas compatibles.
  • La sécurité au niveau des lignes, la sécurité au niveau des colonnes et le masquage des données ne sont pas acceptés.
  • Les vues matérialisées basées sur des tables d'ensembles de données externes Spanner ne sont pas acceptées.
  • L'intégration au catalogue universel Dataplex n'est pas possible. Par exemple, les profils de données et les analyses de la qualité des données ne sont pas acceptés.
  • Les tags au niveau de la table ne sont pas acceptés.
  • La saisie semi-automatique SQL ne fonctionne pas avec les tables externes Spanner lorsque vous écrivez des requêtes.
  • L'option Analyser avec la protection des données sensibles n'est pas disponible pour les ensembles de données externes.
  • Le partage avec BigQuery Sharing (anciennement Analytics Hub) n'est pas disponible pour les ensembles de données externes.
  • Si l'ensemble de données externe Spanner utilise des identifiants d'utilisateur final, vous pouvez créer une vue autorisée qui fait référence à l'ensemble de données externe. Toutefois, lorsque cette vue est interrogée, l'EUC d'une personne qui exécute une requête est envoyée à Spanner.
  • Si l'ensemble de données externe Spanner utilise une connexion à une ressource Cloud pour la délégation d'accès, vous pouvez créer une vue ou une routine autorisée qui fait référence à l'ensemble de données externe.

Étape suivante