Esegui query federate con Data Boost

Questa pagina spiega come utilizzare Spanner Data Boost quando esegui query federate da BigQuery a un database Spanner. Con Data Boost, le query federate vengono eseguite con un impatto minimo sui workload esistenti nell'istanza Spanner di cui è stato eseguito il provisioning. Le query di Data Boost da BigQuery a un database Spanner possono unire i dati di BigQuery ai dati di Spanner.

Puoi eseguire query federate da BigQuery a Spanner utilizzando Data Boost con uno dei seguenti metodi:

• Esegui una query Data Boost federata, che utilizza la funzione di query federata EXTERNAL_QUERY.
• Utilizza Data Boost con set di dati esterni.

La federazione di Spanner consente a BigQuery di eseguire query sui dati archiviati in Spanner in tempo reale, senza copiare o spostare i dati. Per scoprire di più sulle query federate di Spanner, consulta Query federate di Spanner. Per scoprire di più su Data Boost, consulta la panoramica di Data Boost.

Prima di iniziare

Prima di poter eseguire query federate con Data Boost, devi completare le seguenti attività:

• Crea un'istanza e un database Spanner.

• Abilita l'API BigQuery Connection.

• Concedi le autorizzazioni IAM richieste.

Crea un'istanza e un database Spanner

Se non hai un'istanza e un database Spanner, segui i passaggi descritti in Crea ed esegui query su un database utilizzando la console Google Cloud per crearli.

Abilita l'API BigQuery Connection

L'API BigQuery Connection consente di gestire le connessioni BigQuery a origini dati esterne, ad esempio un database Spanner.

• Abilita l'API BigQuery Connection, se non è già abilitata.

  Ruoli richiesti per abilitare le API

  Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

  Abilitare l'API

Per saperne di più, consulta l'API BigQuery Connection nella documentazione di BigQuery.

Concedi le autorizzazioni IAM per Data Boost alle entità

A un'entità devono essere concesse le seguenti autorizzazioni per eseguire query federate con Data Boost:

• spanner.instances.get: consente di ottenere la configurazione di un'istanza.
• spanner.databases.useDataBoost: consente di utilizzare le risorse di computing di Spanner Data Boost per elaborare le query partizionate.

Per saperne di più sulle autorizzazioni di Spanner, consulta Autorizzazioni di Identity and Access Management (IAM).

Per concedere queste autorizzazioni richieste, ti consigliamo di utilizzare il ruolo IAM Cloud Spanner Database Reader With DataBoost (roles/spanner.databaseReaderWithDataBoost). Puoi aggiungere questo ruolo a qualsiasi entità che deve eseguire query federate con Data Boost. Per scoprire di più sui ruoli predefiniti in Spanner, consulta Ruoli predefiniti. Per scoprire come creare un ruolo IAM personalizzato, consulta Crea un ruolo personalizzato.

Esegui una query Data Boost federata

Per eseguire una query Data Boost da BigQuery a un'origine esterna, devi disporre di una connessione BigQuery all'origine esterna e dell'ID della connessione. Quando esegui una query Spanner federata con Data Boost, l'origine esterna è un database Spanner. Dopo aver creato l'ID connessione, BigQuery lo utilizza per eseguire una query Data Boost su un database Spanner.

Utilizza una delle seguenti opzioni per creare un ID connessione BigQuery, quindi utilizza l'ID connessione per eseguire una query Data Boost da BigQuery:

1. Inizia in Spanner: crea l'ID connessione esterna BigQuery nella console Spanner. Dopo aver creato l'ID connessione nella console Spanner, viene eseguito il reindirizzamento alla console BigQuery per eseguire una query federata di Data Boost su un database Spanner.

2. Inizia in BigQuery: crea l'ID connessione esterna di Data Boost nella console BigQuery o utilizzando lo strumento a riga di comando bq. Dopo aver creato l'ID connessione, rimani nella console BigQuery per eseguire una query federata di Data Boost su un database Spanner.

Inizia in Spanner per eseguire una query Data Boost

Per eseguire una query federata di Data Boost a partire da Spanner Studio, segui questi passaggi:

1. Vai alla pagina Istanze di Spanner nella consoleGoogle Cloud .

   Vai alla pagina Istanze

   La console mostra un elenco delle tue istanze Spanner.

2. Seleziona un'istanza Spanner, quindi un database.

3. Nella pagina Panoramica del database, nel menu di navigazione, fai clic su Spanner Studio.

4. Fai clic su Visualizza in BigQuery.

5. Nella finestra di dialogo Visualizza in BigQuery, inserisci un ID connessione.

   L'ID connessione viene utilizzato per creare una nuova connessione esterna BigQuery al tuo database Spanner. Fai riferimento alla connessione esterna utilizzando il seguente pattern:

   PROJECT-ID.LOCATION.CONNECTION-ID
   

   Se l'ID esiste già, si verifica un errore.

6. Compila il resto della finestra di dialogo e procedi nel seguente modo:

   • Seleziona Leggi i dati in parallelo.
   • Seleziona Utilizza Spanner Data Boost.

7. Fai clic su Visualizza in BigQuery.

   BigQuery Studio si apre con la seguente query:

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

   Puoi sostituirlo con la tua query federata. Ad esempio, potresti eseguire una query simile a quella riportata di seguito. Questo esempio esegue una query federata da una tabella denominata orders in un database Spanner e unisce i risultati a una tabella BigQuery denominata 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;

Inizia in BigQuery per eseguire una query Data Boost

Per creare una connessione dati esterna da BigQuery a un database Spanner e utilizzarla per eseguire una query Data Boost federata da BigQuery, seleziona una delle seguenti opzioni:

Console

1. Vai a Crea connessioni Spanner nella documentazione di BigQuery e segui le istruzioni nella scheda Console.

2. Nel riquadro Origine dati esterna, segui questi passaggi:

   • Seleziona Leggi i dati in parallelo.
   • Seleziona Utilizza Spanner Data Boost.

bq

1. Vai a Crea connessioni Spanner nella documentazione di BigQuery e segui le istruzioni nella scheda bq*.

2. Imposta le seguenti proprietà di connessione su true:

   • useParallelism
   • useDataBoost

L'esempio seguente utilizza il comando bq mk per creare una nuova connessione denominata my_connection con le due proprietà richieste per 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

Utilizza Data Boost con set di dati esterni

Per eseguire una query Data Boost da BigQuery a Spanner come origine esterna, puoi creare un set di dati esterno (noto anche come set di dati federato) in BigQuery collegato a un database GoogleSQL o PostgreSQL esistente in Spanner.

Utilizza una connessione CLOUD_RESOURCE

Per impostazione predefinita, i set di dati esterni di Spanner utilizzano le credenziali dell'utente finale (EUC), che richiedono agli utenti di avere accesso diretto ai propri database Spanner. Gli utenti possono eseguire query su questi set di dati se dispongono dell'accesso concesso in Spanner.

Facoltativamente, i set di dati esterni di Spanner possono utilizzare una connessione CLOUD_RESOURCE per interagire con il tuo database Spanner, in modo da fornire a un utente l'accesso ai dati di Spanner tramite BigQuery, senza concedergli l'accesso diretto al database Spanner. Poiché il account di servizio della connessione CLOUD_RESOURCE gestisce il recupero dei dati da Spanner, devi solo concedere agli utenti l'accesso al set di dati esterno Spanner. Questa delega di accesso separa l'accesso alle tabelle Spanner dai set di dati esterni e l'accesso diretto alle tabelle Spanner sottostanti. Per connettersi a Spanner viene utilizzata una connessione alle risorse Cloud associata a un account di servizio. Gli utenti possono eseguire query su queste tabelle Spanner da set di dati esterni anche se non dispongono dell'accesso concesso in Spanner.

Prima di creare set di dati esterni Spanner con una connessione CLOUD_RESOURCE, segui questi passaggi:

Crea una connessione

Puoi creare o utilizzare una connessione CLOUD_RESOURCE esistente per connetterti a Spanner. Assicurati di creare la connessione nella stessa località in cui prevedi di creare il set di dati esterno Spanner.

Seleziona una delle seguenti opzioni:

Console

1. Vai alla pagina BigQuery.

   Vai a BigQuery

2. Nel riquadro a sinistra, fai clic su Explorer:

   

   Se non vedi il riquadro a sinistra, fai clic su Espandi riquadro sinistro per aprirlo.

3. Nel riquadro Explorer, espandi il nome del progetto, quindi fai clic su Connessioni.

4. Nella pagina Connessioni, fai clic su Crea connessione.

5. In Tipo di connessione, scegli Modelli remoti di Vertex AI, funzioni remote, BigLake e Spanner (risorsa Cloud).

6. Nel campo ID connessione, inserisci un nome per la connessione.

7. In Tipo di località, seleziona una località per la connessione. La connessione deve essere collocata insieme alle altre risorse, ad esempio i set di dati.

8. Fai clic su Crea connessione.

9. Fai clic su Vai alla connessione.

10. Nel riquadro Informazioni sulla connessione, copia l'ID account di servizio da utilizzare in un passaggio successivo.

SQL

Utilizza l'istruzione CREATE CONNECTION:

1. Nella console Google Cloud , vai alla pagina BigQuery.

   Vai a BigQuery

2. Nell'editor di query, inserisci la seguente istruzione:

   CREATE CONNECTION [IF NOT EXISTS] `CONNECTION_NAME`
   OPTIONS (
     connection_type = "CLOUD_RESOURCE",
     friendly_name = "FRIENDLY_NAME",
     description = "DESCRIPTION"
     );

   Sostituisci quanto segue:

   • CONNECTION_NAME: il nome della connessione nel formato PROJECT_ID.LOCATION.CONNECTION_ID, LOCATION.CONNECTION_ID o CONNECTION_ID. Se il progetto o la località vengono omessi, vengono dedotti dal progetto e dalla località in cui viene eseguita l'istruzione.
   • FRIENDLY_NAME (facoltativo): un nome descrittivo per la connessione.
   • DESCRIPTION (facoltativo): una descrizione della connessione.

3. Fai clic su Esegui.

Per saperne di più su come eseguire le query, consulta Esegui una query interattiva.

bq

1. In un ambiente a riga di comando, crea una connessione:

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

   Il parametro --project_id sostituisce il progetto predefinito.

   Sostituisci quanto segue:

   • REGION: la tua regione di connessione
   • PROJECT_ID: il tuo ID progetto Google Cloud
   • CONNECTION_ID: un ID per la tua connessione

   Quando crei una risorsa di connessione, BigQuery crea un account di servizio di sistema univoco e lo associa alla connessione.

   Risoluzione dei problemi: se ricevi il seguente errore di connessione, aggiorna Google Cloud SDK:

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

2. Recupera e copia l'ID del account di servizio da utilizzare in un passaggio successivo:

   bq show --connection PROJECT_ID.REGION.CONNECTION_ID

   L'output è simile al seguente:

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

Python

Per scoprire come installare e utilizzare la libreria client per Spanner, consulta Librerie client di Spanner.

Per eseguire l'autenticazione in Spanner, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.

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

Per scoprire come installare e utilizzare la libreria client per Spanner, consulta Librerie client di Spanner.

Per eseguire l'autenticazione in Spanner, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.

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}`);
    }
  }
}

Java

Per scoprire come installare e utilizzare la libreria client per Spanner, consulta Librerie client di Spanner.

Per eseguire l'autenticazione in Spanner, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.

import com.google.api.gax.rpc.AlreadyExistsException;
import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.connection.v1.CloudResourceProperties;
import com.google.cloud.bigquery.connection.v1.Connection;
import com.google.cloud.bigquery.connection.v1.CreateConnectionRequest;
import com.google.cloud.bigquery.connection.v1.LocationName;
import com.google.cloud.bigqueryconnection.v1.ConnectionServiceClient;
import java.io.IOException;

public class CreateConnection {

  /**
   * Creates a BigQuery connection to a Cloud Resource. A Cloud Resource connection provisions a
   * service account that can be granted access to other Google Cloud resources for federated
   * queries.
   *
   * @param projectId The Google Cloud project ID (for example, "example-project-id").
   * @param location The geographic location of the connection (for example, "us-central1").
   * @param connectionId The ID of the connection to create (for example, "example-connection-id").
   */
  public static void createConnection(String projectId, String location, String connectionId) {
    LocationName parent = LocationName.of(projectId, location);

    // CloudResourceProperties provisions a managed Google Cloud service account on creation.
    CloudResourceProperties cloudResourceProperties = CloudResourceProperties.newBuilder().build();
    Connection connection =
        Connection.newBuilder()
            .setFriendlyName("Example Connection")
            .setDescription("Cloud Resource connection for federated queries.")
            .setCloudResource(cloudResourceProperties)
            .build();

    CreateConnectionRequest request =
        CreateConnectionRequest.newBuilder()
            .setParent(parent.toString())
            .setConnectionId(connectionId)
            .setConnection(connection)
            .build();

    try (ConnectionServiceClient client = ConnectionServiceClient.create()) {
      Connection response = client.createConnection(request);

      System.out.printf("Successfully created connection: %s%n", response.getName());
      System.out.printf("Friendly name: %s%n", response.getFriendlyName());
      System.out.printf(
          "Service Account: %s%n", response.getCloudResource().getServiceAccountId());
    } catch (AlreadyExistsException err) {
      System.err.printf(
          "error: connection '%s' already exists in location '%s' for project '%s': %s%n",
          connectionId, location, projectId, err.getMessage());
    } catch (ApiException | IOException err) {
      System.err.printf(
          "error: failed to create connection '%s' in location '%s' for project '%s': %s%n",
          connectionId, location, projectId, err.getMessage());
    }
  }

Terraform

Utilizza la risorsa google_bigquery_connection.

Nota: per creare oggetti BigQuery utilizzando Terraform, devi attivare l'API Cloud Resource Manager.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

L'esempio seguente crea una connessione alle risorse Cloud denominata my_cloud_resource_connection nella regione 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 {}
}

Per applicare la configurazione Terraform in un progetto Google Cloud , completa i passaggi descritti nelle sezioni seguenti.

Prepara Cloud Shell

1. Avvia Cloud Shell.

2. Imposta il progetto Google Cloud predefinito in cui vuoi applicare le configurazioni Terraform.

   Devi eseguire questo comando una sola volta per progetto e puoi eseguirlo in qualsiasi directory.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   Le variabili di ambiente vengono sostituite se imposti valori espliciti nel file di configurazione Terraform.

Prepara la directory

Ogni file di configurazione Terraform deve avere la propria directory (chiamata anche modulo principale).

1. In Cloud Shell, crea una directory e un nuovo file al suo interno. Il nome file deve avere l'estensione .tf, ad esempio main.tf. In questo tutorial, il file è denominato main.tf.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. Se stai seguendo un tutorial, puoi copiare il codice campione in ogni sezione o passaggio.

   Copia il codice campione nel file main.tf appena creato.

   Facoltativamente, copia il codice da GitHub. Questa opzione è consigliata quando lo snippet Terraform fa parte di una soluzione end-to-end.

3. Esamina e modifica i parametri di esempio da applicare al tuo ambiente.
4. Salva le modifiche.
5. Inizializza Terraform. Devi eseguire questa operazione una sola volta per directory.

   terraform init

   Facoltativamente, per utilizzare l'ultima versione del provider Google, includi l'opzione -upgrade:

   terraform init -upgrade

Applica le modifiche

1. Esamina la configurazione e verifica che le risorse che Terraform creerà o aggiornerà corrispondano alle tue aspettative:

   terraform plan

   Apporta le correzioni necessarie alla configurazione.

2. Applica la configurazione Terraform eseguendo il comando seguente e inserendo yes al prompt:

   terraform apply

   Attendi che Terraform visualizzi il messaggio "Apply complete!".

3. Apri il tuo progetto Google Cloud per visualizzare i risultati. Nella console Google Cloud , vai alle risorse nell'interfaccia utente per assicurarti che Terraform le abbia create o aggiornate.

Nota: gli esempi di Terraform in genere presuppongono che le API richieste siano abilitate nel tuo progetto Google Cloud .

Dopo aver creato la connessione, aprila e, nel riquadro Informazioni sulla connessione, copia l'ID del account di servizio. Questo ID è necessario per configurare le autorizzazioni per la connessione. Quando crei una risorsa di connessione, BigQuery crea un account di servizio di sistema univoco e lo associa alla connessione.

Configura l'accesso

Devi concedere al account di servizio associato alla nuova connessione l'accesso in lettura alla tua istanza o al tuo database Spanner. Ti consigliamo di utilizzare il ruolo IAM predefinito Cloud Spanner Database Reader with Data Boost (roles/spanner.databaseReaderWithDataBoost).

Segui questi passaggi per concedere l'accesso ai ruoli a livello di database per il account di servizio che hai copiato in precedenza dalla connessione:

1. Vai alla pagina Istanze di Spanner.

   Vai alla pagina delle istanze

2. Fai clic sul nome dell'istanza che contiene il database per andare alla pagina Dettagli istanza.

3. Nella scheda Panoramica, seleziona la casella di controllo del tuo database.
   Viene visualizzato il riquadro Informazioni.

4. Fai clic su Aggiungi entità.

5. Nel riquadro Aggiungi entità, in Nuove entità, inserisci l'ID account di servizio che hai copiato in precedenza.

6. Nel campo Seleziona un ruolo, seleziona Cloud Spanner Database Reader with DataBoost role.

7. Fai clic su Salva.

Crea un set di dati esterno

Per creare un set di dati esterno:

Console

1. Apri la pagina BigQuery nella console Google Cloud .

   Vai alla pagina BigQuery

2. Nel riquadro a sinistra, fai clic su Spazio di esplorazione:

   

   Se non vedi il riquadro a sinistra, fai clic su Espandi riquadro sinistro per aprirlo.

3. Nel riquadro Explorer, seleziona il progetto in cui vuoi creare il set di dati.

4. Fai clic su Visualizza azioni, quindi su Crea set di dati.

5. Nella pagina Crea set di dati, segui questi passaggi:

   • In ID set di dati, inserisci un nome univoco per il set di dati.
   • In Tipo di località, scegli una località per il set di dati, ad esempio us-central1 o la multi-regione us. Dopo aver creato un set di dati, la località non può essere modificata.

   • Per Set di dati esterno, segui questi passaggi:

     • Seleziona la casella accanto a Link a un set di dati esterno.
     • In Tipo di set di dati esterno, seleziona Spanner.
     • In Origine esterna, inserisci l'identificatore completo del tuo database Spanner nel seguente formato: projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE. Ad esempio projects/my_project/instances/my_instance/databases/my_database.
     • Facoltativamente, in Ruolo database, inserisci il nome di un ruolo database di Spanner. Per saperne di più, consulta i ruoli del database utilizzati per la creazione di connessioni Spanner
     • Facoltativamente, seleziona la casella accanto a Utilizza una connessione alle risorse Cloud per creare il set di dati esterno con una connessione.

   • Lascia invariate le altre impostazioni predefinite.

6. Fai clic su Crea set di dati.

SQL

Utilizza l'istruzione DDL (Data Definition Language) CREATE EXTERNAL SCHEMA.

1. Nella console Google Cloud , vai alla pagina BigQuery.

   Vai a BigQuery

2. Nell'editor di query, inserisci la seguente istruzione:

   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');

   Sostituisci quanto segue:

   • DATASET_NAME: il nome del nuovo set di dati in BigQuery.
   • SPANNER_EXTERNAL_SOURCE: il nome completo del database Spanner, con un prefisso che identifica l'origine, nel seguente formato: google-cloudspanner://[DATABASE_ROLE@]/projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE. Ad esempio: google-cloudspanner://admin@/projects/my_project/instances/my_instance/databases/my_database o google-cloudspanner:/projects/my_project/instances/my_instance/databases/my_database.
   • LOCATION: la località del nuovo set di dati in BigQuery, ad esempio us-central1. Dopo aver creato un set di dati, non puoi modificarne la località.
   • (Facoltativo) CONNECTION_NAME: il nome della connessione alle risorse Cloud.

3. Fai clic su Esegui.

Per saperne di più su come eseguire le query, consulta Esegui una query interattiva.

bq

In un ambiente a riga di comando, crea un set di dati esterno utilizzando il comando bq mk:

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

In alternativa, crea con una connessione:

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

Sostituisci quanto segue:

• LOCATION: la località del nuovo set di dati in BigQuery, ad esempio us-central1. Dopo aver creato un set di dati, non puoi modificarne la località. Puoi impostare un valore predefinito per la località utilizzando il file .bigqueryrc.
• SPANNER_EXTERNAL_SOURCE: il nome completo del database Spanner, con un prefisso che identifica l'origine, nel seguente formato: google-cloudspanner://[DATABASE_ROLE@]/projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE. Ad esempio: google-cloudspanner://admin@/projects/my_project/instances/my_instance/databases/my_database o google-cloudspanner:/projects/my_project/instances/my_instance/databases/my_database.
• DATASET_NAME: il nome del nuovo set di dati in BigQuery. Per creare un set di dati in un progetto diverso da quello predefinito, aggiungi l'ID progetto al nome del set di dati nel seguente formato: PROJECT_ID:DATASET_NAME.
• (Facoltativo) CONNECTION_NAME: il nome della connessione alle risorse Cloud.

Terraform

Utilizza la risorsa google_bigquery_dataset.

Nota: per creare oggetti BigQuery utilizzando Terraform, devi attivare l'API Cloud Resource Manager.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

L'esempio seguente crea un set di dati esterno 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 = ""
  }
}

Per applicare la configurazione Terraform in un progetto Google Cloud , completa i passaggi descritti nelle sezioni seguenti.

Prepara Cloud Shell

1. Avvia Cloud Shell.

2. Imposta il progetto Google Cloud predefinito in cui vuoi applicare le configurazioni Terraform.

   Devi eseguire questo comando una sola volta per progetto e puoi eseguirlo in qualsiasi directory.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   Le variabili di ambiente vengono sostituite se imposti valori espliciti nel file di configurazione Terraform.

Prepara la directory

Ogni file di configurazione Terraform deve avere la propria directory (chiamata anche modulo principale).

1. In Cloud Shell, crea una directory e un nuovo file al suo interno. Il nome file deve avere l'estensione .tf, ad esempio main.tf. In questo tutorial, il file è denominato main.tf.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. Se stai seguendo un tutorial, puoi copiare il codice campione in ogni sezione o passaggio.

   Copia il codice campione nel file main.tf appena creato.

   Facoltativamente, copia il codice da GitHub. Questa opzione è consigliata quando lo snippet Terraform fa parte di una soluzione end-to-end.

3. Esamina e modifica i parametri di esempio da applicare al tuo ambiente.
4. Salva le modifiche.
5. Inizializza Terraform. Devi eseguire questa operazione una sola volta per directory.

   terraform init

   Facoltativamente, per utilizzare l'ultima versione del provider Google, includi l'opzione -upgrade:

   terraform init -upgrade

Applica le modifiche

1. Esamina la configurazione e verifica che le risorse che Terraform creerà o aggiornerà corrispondano alle tue aspettative:

   terraform plan

   Apporta le correzioni necessarie alla configurazione.

2. Applica la configurazione Terraform eseguendo il comando seguente e inserendo yes al prompt:

   terraform apply

   Attendi che Terraform visualizzi il messaggio "Apply complete!".

3. Apri il tuo progetto Google Cloud per visualizzare i risultati. Nella console Google Cloud , vai alle risorse nell'interfaccia utente per assicurarti che Terraform le abbia create o aggiornate.

Nota: gli esempi di Terraform in genere presuppongono che le API richieste siano abilitate nel tuo progetto Google Cloud .

API

Chiama il metodo datasets.insert con una risorsa del set di dati definita e il campo externalDatasetReference per il tuo database Spanner.

Tieni presente che i nomi delle tabelle nei set di dati esterni non fanno distinzione tra maiuscole e minuscole.

Quando crei i set di dati esterni con una connessione CLOUD_RESOURCE, devi disporre dell'autorizzazione bigquery.connections.delegate (disponibile nel ruolo Amministratore connessione BigQuery) sulla connessione utilizzata dai set di dati esterni.

Crea una vista materializzata non incrementale basata su tabelle di un set di dati esterno

Prima di procedere, devi creare il set di dati esterno Spanner sottostante utilizzando una connessione CLOUD_RESOURCE.

Puoi creare viste materializzate non incrementali che fanno riferimento alle tabelle dei set di dati esterni di Spanner utilizzando l'opzione allow_non_incremental_definition. L'esempio seguente utilizza una tabella di set di dati esterni Spanner di base:

/*
  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;

Solo le viste materializzate non incrementali di BigQuery possono avere tabelle di set di dati esterni di Spanner come tabelle di base. Se l'ultimo aggiornamento di una vista materializzata non incrementale è avvenuto al di fuori dell'intervallo max_staleness, la query legge le tabelle del set di dati esterno Spanner di base. Scopri di più sulle viste materializzate non incrementali di BigQuery.

Passaggi successivi

• Scopri di più su Data Boost nella panoramica di Data Boost
• Utilizza Data Boost nelle tue applicazioni
• Monitora l'utilizzo di Data Boost
• Monitora e gestisci l'utilizzo della quota di Data Boost
• Scopri di più sul set di dati esterno Spanner.
• Scopri di più sulla creazione di viste materializzate su set di dati esterni di Spanner.