Gerenciar consultas salvas

Neste documento, descrevemos como gerenciar consultas salvas e consultas salvas clássicas.

Consultas salvas

Use as seções a seguir para aprender a gerenciar consultas salvas. As consultas salvas são recursos de código do BigQuery Studio com tecnologia do Dataform.

Antes de começar

Para gerenciar consultas salvas do BigQuery Studio e migrar consultas salvas clássicas para o BigQuery Studio, faça o seguinte:

1. Ative o BigQuery Studio no seu projeto.

2. Opcional: para definir permissões do IAM em consultas salvas clássicas públicas ou de projeto migradas durante a migração (pré-lançamento), create ou selecione uma consulta salva do BigQuery Studio e conceda as permissões de Gerenciamento de identidade e acesso (IAM) selecionadas a essa consulta salva.

   1. Durante a migração de consultas salvas clássicas públicas ou de projeto para consultas salvas do BigQuery Studio, selecione uma consulta salva do BigQuery Studio para copiar as permissões concedidas para as consultas salvas migradas.

Importante: em março de 2024, as APIs com suporte aos recursos do BigQuery Studio foram ativadas automaticamente em todos os projetos do BigQuery. Esses novos projetos do BigQuery têm essas APIs ativadas por padrão. Para mais informações, consulte Ativação automática de APIs do BigQuery Studio.

Funções exigidas

Para receber as permissões necessárias para gerenciar consultas salvas, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto em que você quer gerenciar consultas salvas:

• Para gerenciar as consultas salvas do BigQuery Studio no console do Google Cloud:
  • Usuário de jobs do BigQuery (roles/bigquery.jobUser)
  • Usuário de sessão de leitura do BigQuery (roles/bigquery.readSessionUser)
  • Proprietário do código (roles/dataform.codeOwner)
• Para gerenciar consultas salvas do BigQuery Studio usando a API BigQuery: Proprietário do código (roles/dataform.codeOwner)
• Para migrar as consultas salvas clássicas do projeto para o BigQuery Studio, faça o seguinte:
  • Administrador do BigQuery Studio (roles/bigquery.studioAdmin)
  • Administrador de projetos do IAM (roles/resourcemanager.projectIamAdmin)
• Para permitir que usuários autenticados acessem consultas de acesso público: Visualizador de código (roles/dataform.codeViewer)

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esses papéis predefinidos contêm as permissões necessárias para gerenciar consultas salvas. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para gerenciar consultas salvas:

• Para gerenciar as consultas salvas do BigQuery Studio no console do Google Cloud: bigquery.config.get, bigquery.jobs.create, dataform.locations., resourcemanager.projects.get, resourcemanager.projects.list, bigquery.readsessions., dataform.repositories., dataform.workspaces.
• Para gerenciar as consultas salvas do BigQuery Studio usando a API BigQuery: dataform.locations., dataform.repositories., dataform.workspaces.*, resourcemanager.projects.get, resourcemanager.projects.list
• Para migrar as consultas salvas clássicas do projeto para o BigQuery Studio: bigquery.savedqueries.get, bigquery.savedqueries.list, bigquery.savedqueries.update, resourcemanager.projects.setIamPolicy
• Para permitir que usuários autenticados acessem consultas de acesso público: dataform.locations.*, dataform.repositories.computeAccessTokenStatus, dataform.repositories.fetchHistory, dataform.repositories.fetchRemoteBranches, dataform.repositories.get, dataform.repositories.getIamPolicy, dataform.repositories.list, dataform.repositories.queryDirectoryContents, dataform.repositories.readFile, dataform.workspaces.fetchFileDiff, dataform.workspaces.fetchFileGitStatuses, dataform.workspaces.fetchGitAheadBehind. dataform.workspaces.get, dataform.workspaces.getIamPolicy, dataform.workspaces.list, dataform.workspaces.queryDirectoryContents, dataform.workspaces.readFile, dataform.workspaces.searchFiles, resourcemanager.projects.get, resourcemanager.projects.list

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Para mais informações sobre o IAM do BigQuery, consulte Controle de acesso com o IAM.

Conceder acesso a consultas salvas

Para conceder a outros usuários acesso a uma consulta salva, adicione esses usuários a um papel apropriado do IAM.

1. No console do Google Cloud, acesse a página do BigQuery.

   Acessar o BigQuery

2. No painel Explorer, expanda seu projeto e a pasta Consultas e, se necessário, a pasta Consultas compartilhadas. Encontre a consulta salva a que você quer conceder acesso.

3. Clique em Conferir ações ao lado da consulta salva e em Compartilhar > Gerenciar permissões.

4. No painel Gerenciar permissões, clique em Adicionar usuário/grupo.

5. No campo Novos principais, digite um principal..

6. Na lista Papel, selecione um dos seguintes papéis:

   • Proprietário de código: pode executar qualquer ação na consulta salva, incluindo excluí-la ou compartilhá-la.
   • Editor de código: pode editar a consulta.
   • Leitor de código: pode visualizar a consulta.
   Observação: o principal também precisa ter o papel de Usuário do BigQuery (roles/bigquery.user) para executar a consulta salva.

7. Opcional: para ver uma lista completa de papéis e configurações de compartilhamento avançadas, clique em Compartilhamento avançado.

8. Clique em Salvar.

9. Para retornar às informações da consulta salvas, clique em Fechar.

Compartilhar consultas salvas

Para compartilhar uma consulta salva com outros usuários, gere e compartilhe um link para ela. Antes que os usuários possam ver a consulta salva que você compartilha, primeiro é necessário conceder a eles acesso a essa consulta.

Para executar uma consulta compartilhada, os usuários precisam ter acesso aos dados que a consulta acessa. Para mais informações, consulte Como conceder acesso a um conjunto de dados.

Se você planeja compartilhar uma consulta salva, considere incluir um comentário na consulta que descreva a finalidade dela.

1. No console do Google Cloud, acesse a página do BigQuery.

   Acessar o BigQuery

2. No painel Explorer, expanda seu projeto e a pasta Consultas e, se necessário, expanda a pasta Consultas compartilhadas. Encontre a consulta salva que você quer compartilhar.

3. Clique em Ver ações ao lado da consulta e em Compartilhar > Copiar link.

4. Compartilhe o link com outros usuários.

Conceder acesso público a uma consulta salva

É possível conceder acesso público a uma consulta salva do BigQuery Studio concedendo a função de leitor de código (roles/dataform.codeViewer) na consulta salva ao principal allAuthenticatedUsers.

Quando você atribui um papel do IAM ao allAuthenticatedUsers, as contas de serviço e todos os usuários na Internet que se autenticaram com uma Conta do Google recebem esse papel. Isso inclui contas que não estão conectadas a uma conta do Google Workspace ou do Cloud Identity, como contas pessoais do Gmail. Os usuários que não forem autenticados, como os visitantes anônimos, não serão incluídos. Para mais informações, consulte Todos os usuários autenticados.

Por exemplo, quando você concede a função "Leitor de código" a allAuthenticatedUsers na consulta salva sales, todas as contas de serviço e usuários na Internet que se autenticaram com uma Conta do Google têm acesso somente leitura à consulta salva sales.

Cuidado: conceder permissões de administrador, edição ou nível de execução a allAuthenticatedUsers pode permitir que usuários de má-fé acessem seus dados. Conceda apenas as permissões mínimas necessárias.

Para conceder acesso público a uma consulta salva do BigQuery Studio, faça o seguinte:

1. No console do Google Cloud, acesse a página do BigQuery.

   Acessar o BigQuery

2. No painel Explorer, expanda seu projeto e a pasta Consultas e, se necessário, a pasta Consultas compartilhadas. Encontre a consulta salva a que você quer conceder acesso público.

3. Clique em Conferir ações ao lado da consulta salva e em Compartilhar > Gerenciar permissões.

4. No painel Gerenciar permissões, clique em Adicionar usuário/grupo.

5. No campo Novos participantes, insira allAuthenticatedUsers.

6. Na lista Papel, selecione a função Leitor de código.

7. Clique em Salvar.

8. Para retornar às informações da consulta salvas, clique em Fechar.

Impedir o acesso público a consultas salvas

Para garantir que nenhum acesso público seja concedido a nenhuma consulta salva do BigQuery Studio, restrinja o principal allAuthenticatedUsers no seu projeto.

Para restringir allAuthenticatedUsers no seu projeto, você pode definir a política iam.allowedPolicyMemberDomains e remover allAuthenticatedUsers da lista de allowed_values.

Quando você restringe allAuthenticatedUsers na política iam.allowedPolicyMemberDomains, o principal allAuthenticatedUsers não pode ser usado em nenhuma política do IAM no seu projeto, o que impede o acesso público a todos os recursos, incluindo consultas salvas do BigQuery Studio.

Para mais informações sobre a política iam.allowedPolicyMemberDomains e instruções para configurá-la, consulte Como restringir identidades por domínio.

Ver todas as consultas salvas

Para visualizar uma lista de todas as consultas salvas no seu projeto, faça o seguinte:

1. No console do Google Cloud, acesse a página do BigQuery.

   Acessar o BigQuery

2. No painel Explorer, clique em Ver ações ao lado de Consultas e execute uma das seguintes ações: :

• Para abrir a lista na guia atual, clique em Mostrar tudo.
• Para abrir a lista em uma nova guia, clique em Mostrar tudo em > Nova guia.
• Para abrir a lista em uma guia dividida, clique em Mostrar tudo em > Dividir guia.

Ver metadados da consulta salva

Para conferir os metadados das consultas salvas, faça o seguinte:

1. No console do Google Cloud, acesse a página do BigQuery.

   Acessar o BigQuery

2. No painel Explorer, expanda seu projeto e a pasta Consultas e, se necessário, a pasta Consultas compartilhadas. Clique no nome da consulta salva com os metadados que você quer ver.

3. Confira o painel Resumo para ver informações sobre a consulta salva, como a região que ela usa e a data da última modificação.

Trabalhar com versões de consulta salvas

Use as seções a seguir para aprender a visualizar, comparar e restaurar versões de uma consulta salva.

Ver versões da consulta salvas

Para conferir as versões da consulta salvas, faça o seguinte:

1. No console do Google Cloud, acesse a página do BigQuery.

   Acessar o BigQuery

2. No painel Explorer, expanda seu projeto e a pasta Consultas e, se necessário, a pasta Consultas compartilhadas. Clique no nome da consulta salva com a atividade que você quer ver.

3. Clique na guia Atividade para ver uma lista das versões de consulta salvas em ordem decres cente por data.

Comparar versões de consultas salvas

Para comparar as versões de consulta salvas, faça o seguinte:

1. No console do Google Cloud, acesse a página do BigQuery.

   Acessar o BigQuery

2. No painel Explorer, expanda seu projeto e a pasta Consultas e, se necessário, a pasta Consultas compartilhadas. Clique no nome da consulta salva com as informações de versão que você quer comparar.

3. Na guia Atividade, clique em Ver ações ao lado de uma versão de consulta salva e clique em Comparar. O painel de comparação é aberto, comparando a versão da consulta salva selecionada com a versão atual da consulta salva.

4. Opcional: para comparar as versões inline em vez de em painéis separados, clique em Comparar e em Inline.

Restaurar uma versão de consulta salva

Use uma das seguintes opções para restaurar uma versão de consulta salva. Restaurar a partir do painel de comparação permite comparar a versão anterior da consulta salva com a versão atual antes de decidir se quer restaurá-la.

Painel de atividades

1. No painel Explorer, expanda seu projeto e a pasta Consultas e, se necessário, a pasta Consultas compartilhadas. Clique no nome da consulta salva da qual você quer restaurar uma versão anterior.
2. Selecione o painel Atividade.
3. Clique em Ver ações ao lado da versão da consulta salva que você quer restaurar e, em seguida, clique em Restaurar.
4. Clique em Confirmar para confirmar a ação.

Painel de comparação

1. No painel Explorer, expanda seu projeto e a pasta Consultas e, se necessário, a pasta Consultas compartilhadas. Clique no nome da consulta salva da qual você quer restaurar uma versão anterior.
2. Selecione o painel Atividade.
3. Clique em Ver ações ao lado de uma versão de consulta salva e, em seguida, clique em Comparar. O painel de comparação é aberto, comparando a versão da consulta salva selecionada com a versão mais recente da consulta salva.
4. Se quiser restaurar a versão anterior da consulta salva após a comparação, clique em Restaurar.
5. Clique em Confirmar para confirmar a ação.

Fazer o download de consultas salvas

Para fazer o download de uma consulta salva, faça o seguinte:

1. No console do Google Cloud, acesse a página do BigQuery.

   Acessar o BigQuery

2. No painel Explorer, expanda seu projeto e a pasta Consultas e, se necessário, a pasta Consultas compartilhadas. Clique no nome de uma consulta salva para abri-la.

3. Clique em Fazer download.

Excluir consulta salva

Para excluir uma consulta salva, faça o seguinte:

1. No console do Google Cloud, acesse a página do BigQuery.

   Acessar o BigQuery

2. No painel Explorer, expanda seu projeto e a pasta Consultas e, se necessário, a pasta Consultas compartilhadas. Encontre a consulta salva que você quer excluir.

3. Clique em Ver ações ao lado da consulta salva e, em seguida, clique em Excluir.

4. Para confirmar a exclusão, digite delete na caixa de diálogo.

5. Clique em Excluir.

Consultas salvas clássicas

Descontinuadas: as consultas salvas, disponíveis na visualização do BigQuery Studio, vão substituir totalmente as consultas salvas clássicas até março de 2025. Para mais informações, acesse Descontinuação das consultas salvas clássicas. Para saber como migrar para consultas salvas, acesse Migrar consultas salvas clássicas.

Use as seções a seguir para saber como gerenciar consultas salvas clássicas.

Observação: se você não ativou o BigQuery Studio, as consultas salvas clássicas aparecerão na pasta Consultas salvas (NUMBER) do painel Explorer em vez da pasta Consultas (clássicas).

Compartilhar consultas salvas clássicas

É possível compartilhar consultas salvas clássicas que você concedeu ao projeto ou à visibilidade pública. A visibilidade do projeto permite que os participantes com as permissões necessárias visualizem, atualizem ou excluam a consulta. A visibilidade pública permite que qualquer pessoa com o link da consulta veja, mas não atualize nem exclua a consulta.

Para compartilhar uma consulta salva clássica com outros usuários, gere e compartilhe um link para ela.

Para executar uma consulta compartilhada, os usuários precisam ter acesso aos dados que a consulta acessa. Para mais informações, consulte Como conceder acesso a um conjunto de dados.

Se você planeja compartilhar uma consulta salva clássica, considere incluir um comentário na consulta que descreva a finalidade dela.

1. No painel Explorer, expanda seu projeto e a pasta Consultas(clássicas) e, em seguida, encontre a consulta salva clássica que você quer compartilhar.
2. Clique em Ver ações ao lado da consulta e clique em Gerar link.
3. Compartilhe o link com os usuários a quem você quer conceder acesso à consulta.

Salvar uma consulta clássica como consulta salva

1. No console do Google Cloud, acesse a página do BigQuery.

   Ir para o BigQuery

2. No painel Explorer, expanda seu projeto e a pasta (clássica) de consultas e, se necessário, a pasta Consultas de projetos.

3. Clique no nome de uma consulta salva clássica para abri-la.

4. Clique em Salvar consulta (clássico) > Salvar consulta como....

5. Na caixa de diálogo Salvar consulta, digite um nome e escolha o local para a consulta.

6. Clique em Salvar.

Migrar consultas salvas clássicas

Pré-lançamento: esse recurso está em pré-lançamento para projetos com menos de 2.500 consultas salvas clássicas.

Esse produto ou recurso está sujeito aos Termos de ofertas pré-GA na seção Termos gerais de serviço" dos Termos específicos de serviço . Os produtos e recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Para solicitar suporte ou enviar feedback sobre esse recurso, envie um e-mail para [e-mail].

Para migrar consultas salvas clássicas em lote, você precisa ter as permissões necessárias. Essas permissões determinam o tipo de consultas salvas clássicas que você pode migrar.

É possível migrar em lote as seguintes consultas salvas clássicas:

Consultas salvas clássicas pessoais

As consultas salvas clássicas particulares permanecem visíveis apenas para o usuário que as criou. Elas são identificadas pelo ícone . As consultas salvas clássicas pessoais só podem ser migradas pelos proprietários. Administradores e usuários que receberam acesso às consultas salvas migradas do BigQuery Studio podem acessar, modificar ou excluir consultas salvas pessoais.

Consultas salvas clássicas públicas

Pública: as consultas públicas salvas clássicas são visíveis para qualquer pessoa com o link da consulta. Elas são identificadas pelo ícone . As consultas salvas clássicas públicas só podem ser migradas pelos proprietários.

As permissões do IAM em consultas salvas clássicas públicas não são mapeadas para permissões em consultas salvas do BigQuery Studio. Isso significa que as consultas salvas do BigQuery Studio migradas de consultas salvas clássicas públicas não estão disponíveis publicamente por padrão. É necessário definir as permissões do IAM para consultas salvas migradas do BigQuery Studio durante ou após a migração.

Para definir permissões do IAM para as consultas salvas migradas do BigQuery Studio durante a migração, selecione uma consulta salva do BigQuery Studio que tenha as permissões que você quer aplicar às consultas salvas migradas. O BigQuery vai copiar as permissões concedidas na consulta salva do BigQuery Studio selecionada e aplicá-las às consultas salvas migradas. Também é possível adicionar manualmente usuários ou grupos com quem você quer compartilhar as consultas salvas migradas.

Se você não definir as permissões do IAM durante a migração, apenas você terá acesso às consultas salvas migradas do BigQuery Studio.

Consultas salvas clássicas do projeto

As consultas salvas para envolvidos no projeto ficam visíveis para os principais com as permissões necessárias. Elas são identificadas pelo ícone . É possível migrar em lote todas as consultas salvas clássicas do projeto.

As permissões do IAM nas consultas salvas clássicas do projeto não são mapeadas diretamente para as permissões nas consultas salvas do BigQuery Studio. É necessário definir as permissões do IAM para consultas salvas migradas do BigQuery Studio, durante ou após a migração.

Para definir permissões do IAM para as consultas salvas migradas do BigQuery Studio durante a migração, selecione uma consulta salva do BigQuery Studio que tenha as permissões que você quer aplicar às consultas salvas migradas. O BigQuery vai copiar as permissões concedidas na consulta salva do BigQuery Studio selecionada e aplicá-las às consultas salvas migradas. Também é possível adicionar manualmente usuários ou grupos com quem você quer compartilhar as consultas salvas migradas.

Se você não definir permissões do IAM durante a migração, apenas você terá acesso às consultas salvas migradas do BigQuery Studio.

Durante a migração em lote de consultas salvas clássicas, o BigQuery faz o seguinte:

• Salva todas as consultas salvas clássicas migradas como consultas salvas do BigQuery Studio, armazenadas na região selecionada.
• Converte todas as consultas salvas clássicas migradas em consultas salvas clássicas de leitura somente, disponíveis até 2025.

Após a migração, você pode acessar as consultas salvas clássicas pessoais, públicas e de projeto como consultas salvas do BigQuery Studio e como consultas salvas clássicas somente leitura. As consultas salvas clássicas somente leitura vão estar disponíveis até 2025.

Riscos de migração

Depois da migração em lote, não será possível modificar as consultas clássicas salvas migradas. As consultas clássicas salvas pessoais, públicas e do projeto migradas passam a ser somente leitura. As consultas salvas clássicas pessoais, públicas e de projeto, somente leitura, vão estar disponíveis até 2025.

O BigQuery vai adicionar as consultas salvas do BigQuery Studio migradas ao seu projeto do Google Cloud usando a API Dataform. Para reverter essas mudanças, é necessário fazer uma limpeza manual.

Aviso: depois que a migração for iniciada, não será possível interromper ou cancelar o processo.

Migrar consultas salvas clássicas em lote

Para migrar em lote as consultas salvas clássicas do seu projeto para as consultas salvas do BigQuery Studio, faça o seguinte:

1. No console do Google Cloud, acesse a página do BigQuery.

   Ir para o BigQuery

2. No painel Explorer, expanda seu projeto e clique em Ver ações ao lado de Consultas (clássicas) e, em seguida, em Migrar consultas salvas clássicas.

3. No painel Migração de consultas salvas clássicas, na seção Verificar a prontidão para a migração, clique em Próxima para confirmar que você tem as permissões necessárias.

   Suas permissões do IAM determinam qual tipo de consulta salva clássica você pode migrar e quais seções do painel Migração de consultas salvas clássicas estão visíveis para você.

4. Na seção Região, no menu suspenso Região, selecione uma região em que o BigQuery vai armazenar as consultas salvas migradas.

   Recomendamos selecionar sua região padrão para os recursos de código do BigQuery Studio. Para mais informações, consulte Definir a região padrão para recursos de código.

5. Para migrar todas as consultas pessoais clássicas salvas, na seção Migrar consultas pessoais, marque a caixa de seleção Migrar todas as consultas pessoais e clique em Próxima.

6. Para migrar todas as consultas públicas salvas clássicas no seu projeto, na seção Migrar consultas públicas, faça o seguinte:

   1. Marque a caixa de seleção Migrar todas as consultas públicas.
   2. No menu suspenso SQL, selecione uma consulta salva do BigQuery Studio que tenha as políticas do IAM que você quer aplicar às consultas salvas migradas.

   3. Opcional: para adicionar um usuário ou grupo com quem você quer compartilhar as consultas salvas migradas, clique em Adicionar usuário/grupo e Conceder acesso às consultas salvas.

      Para compartilhar as consultas salvas migradas publicamente, defina allAuthenticatedUsers como o participante e conceda a ele o papel de leitor de código. Para mais informações, consulte Conceder acesso público.

   4. Clique em Próxima.

7. Para migrar consultas salvas clássicas para envolvidos no projeto, na seção Migrar consultas do projeto, faça o seguinte:

   1. Marque a caixa de seleção Migrar todas as consultas do projeto.
   2. No menu suspenso SQL, selecione uma consulta salva do BigQuery Studio que tenha as políticas do IAM que você quer aplicar às consultas salvas migradas.
   3. Opcional: para adicionar um usuário ou grupo com quem você quer compartilhar as consultas salvas migradas, clique em Adicionar usuário/grupo e Conceder acesso às consultas salvas.
   4. Clique em Próxima.

8. Para confirmar que você entende os riscos da migração e que quer migrar as consultas clássicas salvas em lote, na seção Confirmar, no campo Confirmar, insira confirm e clique em Próxima.

   Aviso: depois que a migração for iniciada, não será possível interromper ou cancelar o processo.

9. Clique em Enviar.

A migração pode levar mais de 15 minutos, dependendo do número de consultas migradas.

Excluir consultas salvas clássicas

1. No console do Google Cloud, acesse a página do BigQuery.

   Acessar o BigQuery

2. No painel Explorer, expanda seu projeto e a pasta (clássica) de consultas e, se necessário, a pasta Consultas de projetos.

3. Encontre a consulta salva clássica que você quer excluir.

4. Clique em Ver ações ao lado da consulta e, em seguida, clique em Excluir.

5. Para confirmar a exclusão, digite delete na caixa de diálogo.

6. Clique em Excluir.

A seguir

• Para saber mais sobre as consultas salvas do BigQuery Studio, consulte Introdução às consultas salvas.
• Para saber como criar consultas salvas, consulte Criar consultas salvas.