Exécuter des requêtes fédérées avec Data Boost

Cette page explique comment utiliser Spanner Data Boost lorsque vous exécutez des requêtes fédérées de BigQuery vers une base de données Spanner. Avec Data Boost, les requêtes fédérées s'exécutent avec un impact minimal sur les charges de travail existantes sur l'instance Spanner provisionnée. Les requêtes Data Boost de BigQuery vers une base de données Spanner peuvent joindre des données BigQuery à des données Spanner.

Vous pouvez exécuter des requêtes fédérées depuis BigQuery vers Spanner à l'aide de Data Boost, en utilisant l'une des méthodes suivantes :

• Exécutez une requête Data Boost fédérée, qui utilise la fonction de requête fédérée EXTERNAL_QUERY.
• Utilisez Data Boost avec des ensembles de données externes.

La fédération Spanner permet à BigQuery d'interroger les données résidant dans Spanner en temps réel, sans avoir à les copier ni à les déplacer. Pour en savoir plus sur les requêtes fédérées Spanner, consultez Requêtes fédérées Spanner. Pour en savoir plus sur Data Boost, consultez la présentation de Data Boost.

Avant de commencer

Avant de pouvoir exécuter des requêtes fédérées avec Data Boost, vous devez effectuer les tâches suivantes :

• Créez une instance et une base de données Spanner.

• Activez l'API BigQuery Connection.

• Accordez les autorisations IAM requises.

Créer une instance et une base de données Spanner

Si vous ne disposez pas d'instance ni de base de données Spanner, suivez les étapes de la section Créer et interroger une base de données à l'aide de la console pour les créer. Google Cloud

Activer l'API BigQuery Connection

L'API BigQuery Connection vous permet de gérer les connexions BigQuery à des sources de données externes, comme une base de données Spanner.

• Enable the BigQuery connection API.

  Roles required to enable APIs

  To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

  Enable the API

Pour en savoir plus, consultez la documentation BigQuery sur l'API de connexion BigQuery.

Accorder des autorisations IAM pour Data Boost aux comptes principaux

Un compte principal doit disposer des autorisations suivantes pour exécuter des requêtes fédérées avec Data Boost :

• spanner.instances.get : vous permet d'obtenir la configuration d'une instance.
• spanner.databases.useDataBoost : vous permet d'utiliser les ressources de calcul Spanner Data Boost pour traiter les requêtes partitionnées.

Pour en savoir plus sur les autorisations Spanner, consultez la section Autorisations Identity and Access Management (IAM).

Pour accorder ces autorisations requises, nous vous recommandons d'utiliser le rôle IAM Cloud Spanner Database Reader With DataBoost (roles/spanner.databaseReaderWithDataBoost). Vous pouvez ajouter ce rôle à n'importe quel compte principal qui doit exécuter des requêtes fédérées avec Data Boost. Pour en savoir plus sur les rôles prédéfinis dans Spanner, consultez Rôles prédéfinis. Pour savoir comment créer un rôle IAM personnalisé, consultez Créer un rôle personnalisé.

Exécuter une requête Data Boost fédérée

Pour exécuter une requête Data Boost depuis BigQuery vers une source externe, vous avez besoin d'une connexion BigQuery à la source externe et de l'ID de la connexion. Lorsque vous exécutez une requête Spanner fédérée avec Data Boost, la source externe est une base de données Spanner. Une fois que vous avez créé votre ID de connexion, BigQuery l'utilise pour exécuter une requête Data Boost d'une base de données Spanner.

Utilisez l'une des options suivantes pour créer un ID de connexion BigQuery, puis utilisez cet ID pour exécuter une requête Data Boost depuis BigQuery :

1. Commencez dans Spanner : créez l'ID de connexion externe BigQuery dans la console Spanner. Une fois votre ID de connexion créé dans la console Spanner, vous êtes redirigé vers la console BigQuery pour exécuter une requête Data Boost fédérée sur une base de données Spanner.

2. Commencez dans BigQuery : créez l'ID de connexion externe Data Boost dans la console BigQuery ou à l'aide de l'outil de ligne de commande bq. Une fois l'ID de connexion créé, vous restez dans la console BigQuery pour exécuter une requête Data Boost fédérée sur une base de données Spanner.

Commencer dans Spanner pour exécuter une requête Data Boost

Pour exécuter une requête Data Boost fédérée à partir de Spanner Studio, procédez comme suit :

1. Accédez à la page Instances de Spanner dans la consoleGoogle Cloud .

   Accéder à la page Instances

   La console affiche la liste de vos instances Spanner.

2. Sélectionnez une instance Spanner, puis une base de données.

3. Sur la page Présentation de la base de données, dans le menu de navigation, cliquez sur Spanner Studio.

4. Cliquez sur Afficher dans BigQuery.

5. Dans la boîte de dialogue Afficher dans BigQuery, saisissez un ID de connexion.

   L'ID de connexion permet de créer une connexion externe BigQuery à votre base de données Spanner. Vous référencez votre connexion externe à l'aide du modèle suivant :

   PROJECT-ID.LOCATION.CONNECTION-ID
   

   Une erreur se produit si l'ID existe déjà.

6. Remplissez le reste de la boîte de dialogue, puis procédez comme suit :

   • Sélectionnez Lire des données en parallèle.
   • Sélectionnez Utiliser Spanner Data Boost.

7. Cliquez sur Afficher dans BigQuery.

   BigQuery Studio s'ouvre avec la requête suivante :

   SELECT * FROM EXTERNAL_QUERY("PROJECT-ID.LOCATION.CONNECTION-ID", "SELECT * FROM INFORMATION_SCHEMA.TABLES;");
   

   Vous pouvez le remplacer par votre requête fédérée. Par exemple, vous pouvez effectuer une requête semblable à l'exemple suivant. Cet exemple envoie une requête fédérée à partir d'une table nommée orders dans une base de données Spanner et joint les résultats à une table BigQuery nommée mydataset.customers.

   SELECT c.customer_id, c.name, rq.first_order_date
   FROM mydataset.customers AS c
   LEFT OUTER JOIN EXTERNAL_QUERY(
     'my-project.us.example-db',
     '''SELECT customer_id, MIN(order_date) AS first_order_date
     FROM orders
     GROUP BY customer_id''') AS rq
     ON rq.customer_id = c.customer_id
   GROUP BY c.customer_id, c.name, rq.first_order_date;

Exécuter une requête Data Boost dans BigQuery

Pour créer une connexion de données externes de BigQuery à une base de données Spanner et utiliser cette connexion pour exécuter une requête Data Boost fédérée depuis BigQuery, sélectionnez l'une des options suivantes :

Console

1. Accédez à Créer des connexions Spanner dans la documentation BigQuery et suivez les instructions de l'onglet Console.

2. Dans le volet Source de données externes, procédez comme suit :

   • Sélectionnez Lire des données en parallèle.
   • Sélectionnez Utiliser Spanner Data Boost.

bq

1. Accédez à Créer des connexions Spanner dans la documentation BigQuery et suivez les instructions de l'onglet bq*.

2. Définissez les propriétés de connexion suivantes sur true :

   • useParallelism
   • useDataBoost

L'exemple suivant utilise la commande bq mk pour créer une connexion nommée my_connection avec les deux propriétés requises pour Data Boost :

bq mk --connection --connection_type='CLOUD_SPANNER' --location='us' \
--properties='{"database":"projects/my-project/instances/my-instance/databases/my-database", "useParallelism":true, "useDataBoost": true}' my_connection

Utiliser Data Boost avec des ensembles de données externes

Pour exécuter une requête Data Boost de BigQuery vers Spanner en tant que source externe, vous pouvez 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 GoogleSQL ou PostgreSQL existante dans Spanner.

Utiliser une connexion CLOUD_RESOURCE

Par défaut, les ensembles de données externes Spanner utilisent les identifiants de l'utilisateur final (EUC), ce qui nécessite que les utilisateurs aient un accès direct à leurs bases de données Spanner. Les utilisateurs peuvent interroger ces ensembles de données s'ils ont reçu l'accès dans Spanner.

Si vous le souhaitez, les ensembles de données externes Spanner peuvent utiliser une connexion CLOUD_RESOURCE pour interagir avec votre base de données Spanner. Vous pouvez ainsi fournir à un utilisateur un accès aux données Spanner via BigQuery, sans lui donner un accès direct à la base de données Spanner. Comme 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. Cette 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'y ont pas accès dans 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. Veillez à créer la connexion dans le même emplacement que celui où vous prévoyez de créer votre ensemble de données externe Spanner.

Sélectionnez l'une des options suivantes :

Console

1. Accédez à la page BigQuery.

   Accéder à BigQuery

2. Dans le panneau de gauche, cliquez sur Explorer :

   

   Si le panneau de gauche n'apparaît pas, cliquez sur Développer le panneau de gauche pour l'ouvrir.

3. Dans le volet Explorateur, développez le nom de votre projet, puis cliquez sur Connexions.

4. Sur la page Connexions, cliquez sur Créer une connexion.

5. Pour Type de connexion, sélectionnez Modèles distants Vertex AI, fonctions à distance, BigLake et Spanner (ressource Cloud).

6. Dans le champ ID de connexion, saisissez un nom pour votre connexion.

7. Pour Type d'emplacement, sélectionnez un emplacement pour votre connexion. La connexion doit être colocalisée avec vos autres ressources, telles que les ensembles de données.

8. Cliquez sur Créer une connexion.

9. Cliquez sur Accéder à la connexion.

10. Dans le volet Informations de connexion, copiez l'ID du compte de service à utiliser à l'étape suivante.

bq

1. Dans un environnement de ligne de commande, créez une connexion :

   bq mk --connection --location=REGION --project_id=PROJECT_ID \
       --connection_type=CLOUD_RESOURCE CONNECTION_ID

   Le paramètre --project_id remplace le projet par défaut.

   Remplacez les éléments suivants :

   • REGION : votre région de connexion
   • PROJECT_ID : ID de votre projet Google Cloud
   • CONNECTION_ID : ID de votre connexion

   Lorsque vous créez une ressource de connexion, BigQuery crée un compte de service système unique et l'associe à la connexion.

   Dépannage : Si vous obtenez l'erreur de connexion suivante, mettez à jour le Google Cloud SDK :

   Flags parsing error: flag --connection_type=CLOUD_RESOURCE: value should be one of...
   

2. Récupérez et copiez l'ID du compte de service pour l'utiliser lors d'une prochaine étape :

   bq show --connection PROJECT_ID.REGION.CONNECTION_ID

   Le résultat ressemble à ce qui suit :

   name                          properties
   1234.REGION.CONNECTION_ID     {"serviceAccountId": "[e-mail]"}
   

Python

Pour savoir comment installer et utiliser la bibliothèque cliente pour Spanner, consultez la page Bibliothèques clientes Spanner.

Pour vous authentifier auprès de Spanner, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

import google.api_core.exceptions
from google.cloud import bigquery_connection_v1

client = bigquery_connection_v1.ConnectionServiceClient()


def create_connection(
    project_id: str,
    location: str,
    connection_id: str,
):
    """Creates a BigQuery connection to a Cloud Resource.

    Cloud Resource connection creates a service account which can then be
    granted access to other Google Cloud resources for federated queries.

    Args:
        project_id: The Google Cloud project ID.
        location: The location of the connection (for example, "us-central1").
        connection_id: The ID of the connection to create.
    """

    parent = client.common_location_path(project_id, location)

    connection = bigquery_connection_v1.Connection(
        friendly_name="Example Connection",
        description="A sample connection for a Cloud Resource.",
        cloud_resource=bigquery_connection_v1.CloudResourceProperties(),
    )

    try:
        created_connection = client.create_connection(
            parent=parent, connection_id=connection_id, connection=connection
        )
        print(f"Successfully created connection: {created_connection.name}")
        print(f"Friendly name: {created_connection.friendly_name}")
        print(
            f"Service Account: {created_connection.cloud_resource.service_account_id}"
        )

    except google.api_core.exceptions.AlreadyExists:
        print(f"Connection with ID '{connection_id}' already exists.")
        print("Please use a different connection ID.")
    except Exception as e:
        print(f"An unexpected error occurred while creating the connection: {e}")

Node.js

Pour savoir comment installer et utiliser la bibliothèque cliente pour Spanner, consultez la page Bibliothèques clientes Spanner.

Pour vous authentifier auprès de Spanner, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

const {ConnectionServiceClient} =
  require('@google-cloud/bigquery-connection').v1;
const {status} = require('@grpc/grpc-js');

const client = new ConnectionServiceClient();

/**
 * Creates a new BigQuery connection to a Cloud Resource.
 *
 * A Cloud Resource connection creates a service account that can be granted access
 * to other Google Cloud resources.
 *
 * @param {string} projectId The Google Cloud project ID. for example, 'example-project-id'
 * @param {string} location The location of the project to create the connection in. for example, 'us-central1'
 * @param {string} connectionId The ID of the connection to create. for example, 'example-connection-id'
 */
async function createConnection(projectId, location, connectionId) {
  const parent = client.locationPath(projectId, location);

  const connection = {
    friendlyName: 'Example Connection',
    description: 'A sample connection for a Cloud Resource',
    // The service account for this cloudResource will be created by the API.
    // Its ID will be available in the response.
    cloudResource: {},
  };

  const request = {
    parent,
    connectionId,
    connection,
  };

  try {
    const [response] = await client.createConnection(request);

    console.log(`Successfully created connection: ${response.name}`);
    console.log(`Friendly name: ${response.friendlyName}`);

    console.log(`Service Account: ${response.cloudResource.serviceAccountId}`);
  } catch (err) {
    if (err.code === status.ALREADY_EXISTS) {
      console.log(`Connection '${connectionId}' already exists.`);
    } else {
      console.error(`Error creating connection: ${err.message}`);
    }
  }
}

Terraform

Utilisez la ressource google_bigquery_connection.

Remarque : Pour créer des objets BigQuery à l'aide de Terraform, vous devez activer l'API Cloud Resource Manager.

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 une connexion de ressources cloud nommée my_cloud_resource_connection dans la région US :

# This queries the provider for project information.
data "google_project" "default" {}

# This creates a cloud resource connection in the US region named my_cloud_resource_connection.
# Note: The cloud resource nested object has only one output field - serviceAccountId.
resource "google_bigquery_connection" "default" {
  connection_id = "my_cloud_resource_connection"
  project       = data.google_project.default.project_id
  location      = "US"
  cloud_resource {}
}

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 projet Google Cloud 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.

Remarque : Les exemples Terraform partent généralement du principe que les API requises sont activées dans votre projet Google Cloud .

Une fois la connexion créée, ouvrez-la, puis copiez l'ID du compte de service dans le volet Informations de connexion. Vous en aurez besoin pour configurer les autorisations de 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 au compte de service associé à 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 Data Boost (roles/spanner.databaseReaderWithDataBoost).

Suivez ces étapes pour accorder l'accès aux 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 :

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 :

Console

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

   Accéder à la page "BigQuery"

2. Dans le panneau de gauche, cliquez sur Explorer :

   

   Si le volet de gauche n'apparaît pas, cliquez sur Développer le volet de gauche pour l'ouvrir.

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

4. Cliquez sur Afficher les actions, puis sur Créer un ensemble de données.

5. 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 le champ Type d'emplacement, choisissez un emplacement pour l'ensemble de données, par exemple us-central1 ou la région multirégionale us. 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 le champ Rôle de base de données. Pour en savoir plus, consultez la section sur 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.

6. 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. 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.
   • 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 à une ressource 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 par défaut pour l'emplacement à l'aide du fichier .bigqueryrc.
• SPANNER_EXTERNAL_SOURCE : nom complet et qualifié 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 à une ressource Cloud.

Terraform

Utilisez la ressource google_bigquery_dataset.

Remarque : Pour créer des objets BigQuery à l'aide de Terraform, vous devez activer l'API Cloud Resource Manager.

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 projet Google Cloud 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.

Remarque : Les exemples Terraform partent généralement du principe que les API requises sont activées dans votre projet Google Cloud .

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 dans les ensembles de données externes ne sont pas sensibles à la casse.

Lorsque vous créez les 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.

Créer une vue matérialisée non incrémentielle basée sur des tables provenant d'un ensemble de données externe

Preview

Cette fonctionnalité est soumise(s) aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les fonctionnalités de pré-DG sont disponibles "en l'état" et peuvent avoir une prise en charge limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Avant de continuer, vous devez créer l'ensemble de données externe Spanner sous-jacent à l'aide d'une connexion CLOUD_RESOURCE.

Vous pouvez créer des vues matérialisées non incrémentielles qui font référence à des tables d'ensembles de données externes Spanner à l'aide de l'option allow_non_incremental_definition. L'exemple suivant utilise une table de base d'ensemble de données externes Spanner :

/*
  You must create the spanner_external_dataset with a CLOUD_RESOURCE connection.
*/
CREATE MATERIALIZED VIEW sample_dataset.sample_spanner_mv
  OPTIONS (
      enable_refresh = true, refresh_interval_minutes = 60,
      max_staleness = INTERVAL "24" HOUR,
        allow_non_incremental_definition = true)
AS
  SELECT COUNT(*) cnt FROM spanner_external_dataset.spanner_table;

Seules les vues matérialisées non incrémentielles BigQuery peuvent avoir des tables de l'ensemble de données externes Spanner comme tables de base. Si la dernière actualisation d'une vue matérialisée non incrémentielle s'est produite en dehors de l'intervalle max_staleness, la requête lit les tables de l'ensemble de données externe Spanner de base. En savoir plus sur les vues matérialisées non incrémentielles de BigQuery

Étapes suivantes

• En savoir plus sur Data Boost dans la présentation de Data Boost
• Utiliser Data Boost dans vos applications
• Surveiller l'utilisation de Data Boost
• Surveiller et gérer l'utilisation du quota Data Boost
• En savoir plus sur les ensembles de données externes Spanner
• Découvrez comment créer des vues matérialisées sur des ensembles de données externes Spanner.