Creare query salvate

Quando scrivi SQL nell'editor di query, puoi salvare la query e condividerla con altri. Le query salvate sono asset di codice BigQuery Studio basati su Dataform.

Per saperne di più sull'eliminazione delle query salvate e sulla gestione della cronologia delle query salvate, consulta Gestire le query salvate.

Autorizzazioni obbligatorie

Imposta le autorizzazioni appropriate per creare, modificare o visualizzare le query salvate.

Tutti gli utenti con il ruolo Amministratore Dataform (roles/dataform.admin) hanno accesso come proprietari a tutte le query salvate create nel progetto.

Per saperne di più su Identity and Access Management (IAM) di BigQuery, consulta Controllo dell'accesso con IAM.

Autorizzazioni per creare query salvate

Per creare ed eseguire query salvate, devi disporre delle seguenti autorizzazioni IAM:

• dataform.locations.get
• dataform.locations.list
• dataform.repositories.list
• dataform.repositories.create

Puoi ottenere queste autorizzazioni dai seguenti ruoli IAM:

• Utente job BigQuery (roles/bigquery.jobUser)
• BigQuery Read Session User (roles/bigquery.readSessionUser)
• Code Creator (roles/dataform.codeCreator)

Nota: gli utenti a cui è stato assegnato il ruolo Code Creator in un progetto possono elencare i nomi degli asset di codice in quel progetto utilizzando l'API Dataform o l'interfaccia a riga di comando (CLI) Dataform.

Nota: quando crei una query salvata, BigQuery ti concede il ruolo Dataform Admin (roles/dataform.admin) per quella query salvata. Tutti gli utenti con il ruolo Dataform Admin concesso per il progetto Google Cloud hanno accesso di proprietario a tutte le query salvate create nel progetto. Per ignorare questo comportamento, consulta Concedere un ruolo specifico al momento della creazione della risorsa.

Autorizzazioni per modificare le query salvate

Per modificare ed eseguire le query salvate, devi disporre dei seguenti ruoli IAM:

• Utente job BigQuery (roles/bigquery.jobUser)
• BigQuery Read Session User (roles/bigquery.readSessionUser)
• Editor di codice (roles/dataform.codeEditor)

Autorizzazioni per visualizzare le query salvate

Per visualizzare ed eseguire le query salvate, devi disporre dei seguenti ruoli IAM:

• Utente job BigQuery (roles/bigquery.jobUser)
• BigQuery Read Session User (roles/bigquery.readSessionUser)
• Code Viewer (roles/dataform.codeViewer)

Considerazioni sulla sicurezza per le query salvate

Poiché gli asset di codice in BigQuery sono basati su Dataform, devi considerare le seguenti implicazioni per la sicurezza per gli utenti con accesso a questi asset:

• La visibilità degli asset di codice è regolata dalle autorizzazioni Dataform a livello di progetto. Gli utenti con l'autorizzazione dataform.repositories.list, inclusa nei ruoli BigQuery standard come Utente job BigQuery, Utente BigQuery Studio e Utente BigQuery, possono visualizzare tutti gli asset di codice nel riquadro Explorer del progetto Google Cloud , indipendentemente dal fatto che li abbiano creati o che siano stati condivisi con loro. Per limitare la visibilità, puoi creare ruoli personalizzati che escludono l'autorizzazione dataform.repositories.list.
• Qualsiasi secret condiviso con l'agente di servizio Dataform può potenzialmente essere accessibile agli utenti che possono modificare questi asset. Per proteggere le tue credenziali, limita la creazione e la modifica dell'accesso agli utenti attendibili e limita i secret accessibili all'agente di servizio Dataform. Per saperne di più, consulta Accesso ai secret durante l'installazione del pacchetto.

Per saperne di più, consulta Considerazioni sulla sicurezza per le autorizzazioni Dataform.

Impostare la regione predefinita per gli asset di codice

Tutti i nuovi asset di codice nel tuo progetto Google Cloud utilizzano una regione predefinita. Una volta creato l'asset, non puoi modificarne la regione.

Importante :se modifichi la regione durante la creazione di un asset di codice, questa diventa quella predefinita per tutti gli asset di codice successivi. Gli asset di codice esistenti non sono interessati.

Per impostare la regione predefinita per i nuovi asset di codice:

1. Vai alla pagina BigQuery.

   Vai a BigQuery

2. Nel riquadro a sinistra, fai clic su File per aprire il browser dei file:

   

3. Accanto al nome del progetto, fai clic su Azioni del riquadro dei file > Cambia regione di codice.

4. Seleziona la regione del codice che vuoi utilizzare come predefinita.

5. Fai clic su Salva.

Per un elenco delle regioni supportate, vedi Località BigQuery Studio.

Cripta con CMEK

Puoi criptare le query salvate supportate da Dataform con chiavi di crittografia gestite dal cliente (CMEK) utilizzando la chiave CMEK predefinita a livello di progetto per l'API Dataform. Non puoi applicare singole chiavi CMEK alle query salvate nella console Google Cloud . Le nuove impostazioni vengono applicate solo alle query salvate create di recente.

Per ulteriori informazioni e istruzioni sull'impostazione della chiave predefinita, consulta Utilizzare CMEK per proteggere gli asset di codice di BigQuery Studio.

Creare query salvate

Per creare una query salvata:

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

   Vai a BigQuery

2. Fai clic su Query SQL.

3. Nell'editor di query, inserisci una query SQL valida. Ad esempio, puoi eseguire una query su un set di dati pubblico:

   SELECT
     name,
     SUM(number) AS total
   FROM
     `bigquery-public-data.usa_names.usa_1910_2013`
   GROUP BY
     name
   ORDER BY
     total DESC
   LIMIT
     10;

   In alternativa, puoi utilizzare il riquadro Riferimento per creare nuove query.

4. Fai clic su Salva > Salva query o premi Ctrl+S (o Cmd+S su macOS).

5. Nella finestra di dialogo Salva query, digita un nome per la query salvata.

6. (Facoltativo) Per modificare la regione utilizzata da questa query salvata e da tutti gli altri asset di codice in futuro, seleziona una nuova regione nel campo Regione.

7. Fai clic su Salva.

   Viene creata la prima versione della query salvata.

8. (Facoltativo) Dopo aver salvato la query, utilizza la seguente barra degli strumenti per visualizzare i dettagli della query o la cronologia delle versioni, aggiungere nuovi commenti o rispondere a un commento esistente o ottenere un link a un commento esistente:

   

   La funzionalità della barra degli strumenti Commenti è in anteprima. Per fornire un feedback o richiedere assistenza per questa funzionalità, invia un'email all'indirizzo [e-mail].

Condividere query salvate

Per condividere una query salvata con un utente, devi prima concedere a quest'ultimo l'accesso alla query salvata e aggiungerlo a un ruolo IAM appropriato. Poi, genera un link alla query salvata e condividilo con l'utente.

Gli utenti con cui condividi una query vedono solo la versione più recente. Le modifiche salvate automaticamente che non hai salvato esplicitamente non vengono visualizzate nella query condivisa.

Per condividere una query salvata:

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

   Vai a BigQuery

2. Nel riquadro a sinistra, fai clic su File per aprire il browser dei file.

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

3. Nel riquadro File, espandi il progetto e le sottocartelle per trovare la query salvata che vuoi condividere.

4. Fai clic su Visualizza azioni accanto alla query salvata e poi su Condividi > Gestisci autorizzazioni.

5. Nel riquadro Gestisci autorizzazioni, fai clic su Aggiungi utente/gruppo.

6. Nel campo Nuove entità, inserisci un'entità.

7. Nell'elenco Ruolo, seleziona uno dei seguenti ruoli:

   • Proprietario del codice: può eseguire qualsiasi azione sulla query salvata, inclusa l'eliminazione o la condivisione.
   • Editor di codice: può modificare la query.
   • Visualizzatore di codice: può visualizzare la query.
   Nota: il principal deve disporre anche del ruolo Utente BigQuery (roles/bigquery.user) per eseguire la query salvata.

8. (Facoltativo) Per visualizzare un elenco completo di ruoli e impostazioni di condivisione avanzate, fai clic su Condivisione avanzata.

9. Fai clic su Salva.

10. Per tornare ai dettagli della query salvata, fai clic su Chiudi.

11. Per generare un link alla query salvata, fai clic su Visualizza azioni > Condividi > Copia link.

    Il link viene copiato negli appunti.

Aprire una versione di una query salvata come nuova query

Per aprire una versione di una query salvata esistente come nuova query:

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

   Vai a BigQuery

2. Nel riquadro a sinistra, fai clic su File per aprire il browser dei file:

   

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

3. Nel riquadro File, espandi il progetto e le sottocartelle per trovare la query salvata che vuoi aprire.

4. Fai clic sulla query salvata e poi su Cronologia delle versioni.

5. Fai clic su Visualizza azioni accanto a una versione della query salvata e poi su Apri come nuova query.

Aggiornare le query salvate

Le modifiche apportate al testo di una query salvata vengono salvate automaticamente due secondi dopo che hai smesso di digitare e vengono visualizzate nella Cronologia delle versioni come Le tue modifiche. Le modifiche salvate automaticamente non costituiscono una nuova versione della query. Le modifiche salvate automaticamente vengono visualizzate ogni volta che apri la query, ma non sono visibili a nessun altro, a meno che tu non le salvi esplicitamente come nuova versione della query. Le query salvate automaticamente sono in anteprima.

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

   Vai a BigQuery

2. Nel riquadro a sinistra, fai clic su File per aprire il browser dei file:

   

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

3. Nel riquadro File, espandi il progetto e le sottocartelle per trovare la query salvata che vuoi aggiornare.

4. Fai clic sulla query salvata per aprirla.

5. Modifica la query.

6. Per salvare la query modificata, fai clic su Salva query > Salva query o premi Ctrl+S (o Cmd+S su macOS).

   Viene creata una nuova versione della query.

Caricare le query salvate

Puoi caricare una query SQL locale per utilizzarla come query salvata in BigQuery Studio. La query salvata caricata è visibile anche nella pagina BigQuery della console Google Cloud .

Per caricare una query salvata:

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

   Vai a BigQuery

2. Nel riquadro a sinistra, fai clic su File per aprire il browser dei file:

   

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

3. Nel riquadro File, fai clic su Visualizza azioni accanto alla cartella in cui vuoi caricare la query, quindi fai clic su Carica > Query.

4. Nella finestra di dialogo Carica SQL, nel campo SQL, fai clic su Sfoglia e poi seleziona la query che vuoi caricare.

5. (Facoltativo) Nel campo Nome SQL, modifica il nome della query.

6. Nel campo Regione, seleziona la regione in cui vuoi caricare la query salvata.

7. Fai clic su Carica.

Puoi accedere alla query salvata tramite il riquadro File o Esplora.

Risolvere i problemi relativi alle query salvate

Questa sezione descrive come risolvere i problemi comuni relativi alle query salvate.

Impossibile salvare le query

Se non riesci a salvare una query, l'API Dataform potrebbe non essere abilitata per il progetto. L'API Dataform viene abilitata automaticamente per la maggior parte dei progetti, ma non per i progetti che utilizzano il vincolo della policy dell'organizzazione Limitare l'utilizzo del servizio di risorse, come i progetti protetti.

Per risolvere il problema, assicurati che l'API Dataform sia abilitata:

1. Nella console Google Cloud , vai alla pagina API e servizi.
2. Cerca l'API Dataform e assicurati che sia abilitata.
3. Se l'API non è abilitata, fai clic su Abilita.
4. Riprova a utilizzare le query salvate.

Mancata corrispondenza della regione per le query salvate

La modifica della regione predefinita per gli asset di codice influisce solo sugli asset creati dopo la modifica. Gli asset esistenti rimangono nella regione originale.

Per risolvere il problema, assicurati che la regione selezionata per la query salvata corrisponda a una delle regioni supportate. Se necessario, crea una nuova query salvata in una regione supportata o modifica la regione predefinita per gli asset di codice.

Query salvate classiche

Ritirato :le query salvate, disponibili in BigQuery Studio, sostituiranno completamente le query salvate classiche in futuro. La cronologia del ritiro è in fase di revisione. Per saperne di più, consulta Ritiro delle query classiche salvate. Per scoprire come eseguire la migrazione alle query salvate, consulta la sezione Eseguire la migrazione delle query salvate classiche.

Utilizza le seguenti sezioni per scoprire come creare e aggiornare query salvate classiche. Per saperne di più sulla condivisione, la migrazione e l'eliminazione delle query classiche salvate, consulta Query classiche salvate.

Nota: se non hai attivato BigQuery Studio, le query salvate classiche vengono visualizzate nella cartella Query salvate (NUMBER) nel riquadro Explorer anziché nella cartella Query(classiche).

Autorizzazioni richieste per le query classiche salvate

Per creare, visualizzare, aggiornare ed eliminare query salvate classiche sono necessarie le seguenti autorizzazioni IAM:

• Query salvate classiche private:
  • La creazione di query salvate classiche private non richiede autorizzazioni speciali. Puoi salvare una query privata in qualsiasi progetto, ma solo tu puoi visualizzarla, aggiornarla o eliminarla.
• Query salvate classiche a livello di progetto:
  • La creazione di una query salvata classica a livello di progetto richiede le autorizzazioni bigquery.savedqueries.create. Il ruolo predefinito bigquery.admin include le autorizzazioni bigquery.savedqueries.create.
  • La visualizzazione di una query salvata classica a livello di progetto richiede le autorizzazioni bigquery.savedqueries.get e bigquery.savedqueries.list. I ruoli predefiniti bigquery.admin e bigquery.user includono le autorizzazioni bigquery.savedqueries.get e bigquery.savedqueries.list.
  • L'aggiornamento di una query salvata classica a livello di progetto richiede le autorizzazioni bigquery.savedqueries.update. Il ruolo predefinito bigquery.admin include le autorizzazioni bigquery.savedqueries.update.
  • L'eliminazione di una query salvata classica a livello di progetto richiede autorizzazioni bigquery.savedqueries.delete. Il ruolo predefinito bigquery.admin include le autorizzazioni bigquery.savedqueries.delete.
• Query salvate classiche pubbliche:
  • La creazione di query classiche salvate pubbliche non richiede autorizzazioni speciali. Puoi salvare una query salvata classica pubblica in qualsiasi progetto, ma solo tu puoi aggiornarla o eliminarla. Chiunque abbia il link può visualizzare una query salvata pubblica classica.

Per saperne di più sui ruoli IAM in BigQuery, consulta Ruoli e autorizzazioni predefiniti.

Creare query salvate classiche

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

   Vai a BigQuery

2. Fai clic su Query SQL.

3. Nell'editor di query, inserisci una query SQL valida. Ad esempio, puoi eseguire una query su un set di dati pubblico:

   SELECT
     name,
     SUM(number) AS total
   FROM
     `bigquery-public-data.usa_names.usa_1910_2013`
   GROUP BY
     name
   ORDER BY
     total DESC
   LIMIT
     10;

4. Fai clic su Salva query (classica) > Salva query (classica).

5. Nella finestra di dialogo Salva query, inserisci un nome per la query e poi imposta Visibilità su una delle seguenti opzioni:

   • Personale (modificabile solo da te) per una query salvata classica privata.
   • Progetto (modificabile da entità con le autorizzazioni appropriate) per una query salvata classica a livello di progetto.
   • Pubblica per una query salvata classica pubblica.

6. Fai clic su Salva.

Condividere le query salvate classiche

Puoi condividere le query salvate classiche a cui hai assegnato la visibilità a livello di progetto o pubblica. La visibilità a livello di progetto consente alle entità con le autorizzazioni richieste di visualizzare, aggiornare o eliminare la query. La visibilità pubblica consente a chiunque abbia il link della query di visualizzarla, ma non di aggiornarla o eliminarla.

Per condividere una query salvata classica con altri utenti, devi generare e condividere un link alla query salvata classica.

Per eseguire una query condivisa classica, gli utenti devono avere accesso ai dati a cui la query accede. Per saperne di più, vedi Concedere l'accesso a un set di dati.

Se prevedi di condividere una query salvata classica, valuta la possibilità di includere un commento nella query che ne descriva lo scopo.

Per condividere una query salvata classica:

1. Nel riquadro a sinistra, fai clic su Explorer.

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

2. Nel riquadro Explorer, espandi il progetto e fai clic su (Classic) Queries.

3. Individua e fai clic sulla query salvata classica a cui vuoi concedere l'accesso. Puoi utilizzare la funzionalità di ricerca o i filtri per trovare la query.

4. Fai clic su Visualizza azioni accanto alla query, quindi fai clic su Copia link.

5. Condividi il link con gli utenti a cui vuoi concedere l'accesso alla query.

Aggiorna le query salvate classiche

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

   Vai a BigQuery

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

   

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

3. Nel riquadro Explorer, espandi il progetto e la cartella (Classic) Queries e, se necessario, la cartella Project queries.

4. Fai clic sul nome di una query salvata classica per aprirla.

5. Modifica la query.

6. Per salvare la query modificata, fai clic su Salva query (versione classica) > Salva query (versione classica).

Risolvere i problemi relativi alle query salvate classiche

Questa sezione descrive come risolvere i problemi comuni relativi alle query salvate classiche.

Impossibile accedere alle query salvate di un utente disattivato

A differenza delle query salvate di BigQuery Studio, a cui possono accedere gli amministratori del progetto, le query salvate classiche private diventano inaccessibili se l'utente che le ha create ha lasciato un'organizzazione e il suo Account Google è stato disattivato o sospeso. Le query scompaiono dalla console Google Cloud per tutti gli utenti, tranne il proprietario originale.

Per recuperare queste query, un amministratore di Google Workspace o Cloud Identity deve eseguire i seguenti passaggi:

1. Riattiva temporaneamente l'account dell'utente disattivato.
2. Reimposta la password dell'utente.
3. Accedi alla console Google Cloud come utente riattivato.
4. Nell'editor di query, apri ogni query salvata.
5. Fai clic su Salva o Salva query con nome.
6. Modifica la Visibilità da Personale a Progetto.
7. Fai clic su Salva. In questo modo, la query è visibile agli altri utenti dello stesso progetto che dispongono delle autorizzazioni necessarie.
8. Una volta migrate tutte le query, sospendi di nuovo l'account dell'utente.

Per evitare questo problema, salva le query essenziali per l'attività o condivise dal team con visibilità Progetto.

Passaggi successivi

• Scopri come gestire le query salvate.