Creare query salvate

Questo documento descrive come creare query salvate e query salvate classiche.

Query salvate

Utilizza le sezioni seguenti per scoprire come creare query salvate. Le query salvate sono asset di codice di BigQuery Studio basati su Dataform.

Per ulteriori informazioni sull'eliminazione delle query salvate e sulla gestione della relativa cronologia, consulta Query salvate.

Abilita BigQuery Studio

Segui le istruzioni riportate in Attivare BigQuery Studio per la gestione degli asset per salvare, condividere e gestire le versioni degli asset di codice, come le query salvate.

Importante: a marzo 2024, le API che supportano le funzionalità di BigQuery Studio sono state abilitate automaticamente per tutti i progetti BigQuery esistenti. Nei nuovi progetti BigQuery, queste API sono abilitate per impostazione predefinita. Per saperne di più, consulta Attivazione automatica delle API BigQuery Studio.

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 proprietario a tutte le query salvate create nel progetto.

Per saperne di più su BigQuery Identity and Access Management (IAM), 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

  Nota: gli utenti che hanno l'autorizzazione dataform.repositories.create possono eseguire il codice utilizzando l'account di servizio Dataform predefinito e tutte le autorizzazioni concesse a quell'account di servizio. Per maggiori informazioni, consulta Considerazioni sulla sicurezza per le autorizzazioni Dataform.

Puoi ottenere queste autorizzazioni dai seguenti ruoli IAM:

• Utente job BigQuery (roles/bigquery.jobUser)
• Utente sessione di lettura BigQuery (roles/bigquery.readSessionUser)

• Creatore di codice (roles/dataform.codeCreator)

  Nota: gli utenti a cui è stato assegnato il ruolo Creatore di codice in un progetto possono elencare i nomi degli asset di codice nel progetto utilizzando l'API Dataform o l'interfaccia a riga di comando (CLI) Dataform. I non amministratori che utilizzano BigQuery Studio possono vedere solo gli asset di codice che hanno creato o che sono stati condivisi con loro.

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)
• Utente sessione di lettura BigQuery (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)
• Utente sessione di lettura BigQuery (roles/bigquery.readSessionUser)
• Visualizzatore di codice (roles/dataform.codeViewer)

Impostare la regione predefinita per gli asset di codice

Se è la prima volta che crei un asset di codice, imposta la regione predefinita per gli asset di codice. Non puoi modificare la regione di un asset di codice dopo averlo creato.

Nota: se crei una query salvata e scegli una regione predefinita diversa da quella utilizzata per gli asset di codice, ad esempio scegliendo us-west1 quando usi us-central1, la query e tutti gli asset di codice creati in seguito utilizzeranno quella nuova regione per impostazione predefinita. Gli asset di codice esistenti continuano a utilizzare la regione assegnata loro al momento della creazione.

Creare query salvate

Per creare una query salvata:

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

   Vai a BigQuery

2. Fai clic su Crea una nuova query.

3. Nell'editor query, inserisci una query SQL valida. Ad esempio, puoi eseguire 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 > Salva query.

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

7. Fai clic su Salva.

Concedere l'accesso alle query salvate

Per concedere ad altri utenti l'accesso a una query salvata, aggiungili a un ruolo IAM appropriato.

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

   Vai a BigQuery

2. Nel riquadro Explorer, espandi il progetto, la cartella Query e, se necessario, la cartella Query condivise. Trova la query salvata a cui vuoi concedere l'accesso.

3. Fai clic su Visualizza azioni accanto alla query salvata, quindi fai clic su Condividi > Gestisci autorizzazioni.

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

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

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

   • Proprietario di 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: l'entità deve anche avere il ruolo Utente BigQuery (roles/bigquery.user) per eseguire la query salvata.

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

8. Fai clic su Salva.

9. Per tornare alle informazioni sulla query salvata, fai clic su Chiudi.

Condividere le query salvate

Puoi condividere una query salvata con altri utenti generando e condividendo un link alla query salvata. Prima che gli utenti possano visualizzare la query salvata che condividi, devi concedere loro l'accesso alla query salvata.

Per eseguire una query condivisa, gli utenti devono avere accesso ai dati a cui accede la query. Per maggiori informazioni, consulta Concedere l'accesso a un set di dati.

Se prevedi di condividere una query salvata, valuta la possibilità di includere nella query un commento per descriverne lo scopo.

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

   Vai a BigQuery

2. Nel riquadro Explorer, espandi il progetto e la cartella Query e, se necessario, espandi la cartella Query condivise. Trova la query salvata che vuoi condividere.

3. Fai clic su Visualizza azioni accanto alla query e poi su Condividi > Copia link.

4. Condividi il link con altri utenti.

Aprire una versione della query salvata come nuova query

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

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

   Vai a BigQuery

2. Nel riquadro Explorer, espandi il progetto, la cartella Query e, se necessario, la cartella Query condivise. Seleziona una query salvata.

3. Seleziona il riquadro Attività.

4. Fai clic su Visualizza azioni accanto a una versione della query salvata, quindi fai clic su Apri come nuova query.

Aggiorna le query salvate

Se aggiorni una query salvata, puoi salvare le modifiche in una nuova versione della query.

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

   Vai a BigQuery

2. Nel riquadro Explorer, espandi il progetto, la cartella Query e, se necessario, la cartella Query condivise. Fai clic sul nome di una query salvata per aprirla.

3. Modifica la query.

4. Per salvare la query modificata, fai clic su Salva query > Salva query.

   Viene creata una nuova versione della query, che puoi visualizzare nel riquadro Attività.

Carica le query salvate

Puoi caricare una query SQL locale per utilizzarla come query salvata in BigQuery Studio. La query salvata caricata è quindi 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 Explorer, espandi il progetto ed esegui una delle seguenti operazioni:

   • Accanto a Query, fai clic su Visualizza azioni > Carica query SQL.
   • Accanto al nome del progetto Google Cloud, fai clic su Visualizza azioni > Carica nel progetto > Query SQL.

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

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

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

6. Fai clic su Carica.

La query salvata viene visualizzata nel riquadro Explorer.

Query tradizionali salvate

Ritirati: le query salvate, disponibili nell'anteprima di BigQuery Studio, sostituiranno completamente le query salvate nella versione classica entro marzo 2025. Per saperne di più, consulta Ritiro delle query salvate della versione classica. Per scoprire come eseguire la migrazione alle query salvate, consulta Eseguire la migrazione delle query salvate della versione classica.

Utilizza le sezioni seguenti per scoprire come creare e aggiornare le query salvate classiche. Per ulteriori informazioni su condivisione, migrazione ed eliminazione delle query salvate classiche, consulta Versione classica delle query salvate.

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

Autorizzazioni richieste per le query salvate nella versione classica

Per creare, visualizzare, aggiornare ed eliminare le 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 di bigquery.admin include le autorizzazioni bigquery.savedqueries.create.
  • Per visualizzare una query salvata classica a livello di progetto, sono necessarie 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 di bigquery.admin include le autorizzazioni bigquery.savedqueries.update.
  • L'eliminazione di una query salvata classica a livello di progetto richiede le autorizzazioni bigquery.savedqueries.delete. Il ruolo predefinito di bigquery.admin include le autorizzazioni bigquery.savedqueries.delete.
• Query salvate classiche pubbliche:
  • La creazione di query salvate pubbliche classiche non richiede autorizzazioni speciali. Puoi salvare una query salvata pubblica classica in qualsiasi progetto, ma solo tu puoi aggiornarla o eliminarla. Chiunque abbia il link può visualizzare una query salvata classica pubblica.

Nota: gli utenti a cui è stata concessa l'autorizzazione dataform.repository.list a livello di progetto possono visualizzare tutte le query salvate create nel progetto.

Per ulteriori informazioni sui ruoli IAM in BigQuery, consulta Autorizzazioni e ruoli predefiniti.

Creare query salvate nella versione classica

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

   Vai a BigQuery

2. Fai clic su Crea una nuova query.

3. Nell'editor query, inserisci una query SQL valida. Ad esempio, puoi eseguire 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 (versione classica) > Salva query (versione classica).

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

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

6. Fai clic su Salva.

Condividere le query salvate nella versione classica

Puoi condividere le query salvate classiche per cui hai ottenuto la visibilità pubblica o del progetto. La visibilità del 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, generi e condividi un link alla query salvata classica.

Per eseguire una query condivisa classica, gli utenti devono avere accesso ai dati a cui accede la query. Per maggiori informazioni, consulta Concedere l'accesso a un set di dati.

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

1. Nel riquadro Explorer, espandi il progetto e la cartella Query(classica), quindi trova la query classica salvata che vuoi condividere.
2. Fai clic su Visualizza azioni accanto alla query e poi su Ottieni link.
3. Condividi il link con gli utenti a cui vuoi concedere l'accesso alla query.

Aggiornare le query salvate nella versione classica

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

   Vai a BigQuery

2. Nel riquadro Explorer, espandi il progetto, la cartella Query(classica) e, se necessario, la cartella Query del progetto.

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

4. Modifica la query.

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

Passaggi successivi

• Scopri come gestire le query salvate.