Criar consultas salvas

Ao escrever SQL no editor de consultas, você pode salvar e compartilhar sua consulta com outras pessoas. As consultas salvas são recursos de código do BigQuery Studio com tecnologia do Dataform.

Para saber mais sobre como excluir consultas salvas e gerenciar o histórico de consultas salvas, consulte Gerenciar consultas salvas.

Permissões necessárias

Defina as permissões apropriadas para criar, editar ou ver consultas salvas.

Todos os usuários com o papel de administrador do Dataform (roles/dataform.admin) têm acesso de proprietário a todas as consultas salvas criadas no projeto.

Para mais informações sobre o Identity and Access Management (IAM) do BigQuery, consulte Controle de acesso com o IAM.

Permissões para criar consultas salvas

Para criar e executar consultas salvas, você precisa das seguintes permissões do IAM:

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

É possível conseguir essas permissões com os seguintes papéis do IAM:

• Usuário de jobs do BigQuery (roles/bigquery.jobUser)
• Usuário de sessão de leitura do BigQuery (roles/bigquery.readSessionUser)
• Criador de código (roles/dataform.codeCreator)

Observação: os usuários com papel de Criador de código em um projeto podem listar os nomes dos recursos de código nesse projeto usando a API Dataform ou a interface de linha de comando (CLI) do Dataform.

Observação: ao criar uma consulta salva, o BigQuery concede a você o papel de administrador do Dataform (roles/dataform.admin) nessa consulta salva. Todos os usuários com o papel de administrador do Dataform concedido no projeto Google Cloud têm acesso de proprietário a todas as consultas salvas criadas no projeto. Para substituir esse comportamento, consulte Conceder um papel específico na criação de recursos.

Permissões para editar consultas salvas

Para editar e executar consultas salvas, você precisa dos seguintes papéis do IAM:

• Usuário de jobs do BigQuery (roles/bigquery.jobUser)
• Usuário de sessão de leitura do BigQuery (roles/bigquery.readSessionUser)
• Editor de código (roles/dataform.codeEditor)

Permissões para ver consultas salvas

Para visualizar e executar consultas salvas, você precisa dos seguintes papéis do IAM:

• Usuário de jobs do BigQuery (roles/bigquery.jobUser)
• Usuário de sessão de leitura do BigQuery (roles/bigquery.readSessionUser)
• Visualizador de código (roles/dataform.codeViewer)

Considerações de segurança para consultas salvas

Como os recursos de código no BigQuery são desenvolvidos pelo Dataform, considere as seguintes implicações de segurança para usuários com acesso a esses recursos:

• A visibilidade dos recursos de código é regida por permissões do Dataform para envolvidos no projeto. Os usuários com a permissão dataform.repositories.list, que está incluída nas funções padrão do BigQuery, como Usuário de jobs do BigQuery, Usuário do BigQuery Studio e Usuário do BigQuery, podem acessar todos os recursos de código no painel Explorador do projeto Google Cloud , independentemente de terem criado ou recebido esses recursos. Para restringir a visibilidade, crie papéis personalizados que excluam a permissão dataform.repositories.list.
• Qualquer secret compartilhada com o agente de serviço do Dataform pode ser acessada por usuários que podem editar esses recursos. Para proteger suas credenciais, restrinja a criação e o acesso de edição a usuários confiáveis e limite os secrets acessíveis ao agente de serviço do Dataform. Para mais informações, consulte Acesso a secrets durante a instalação do pacote.

Para mais informações, consulte Considerações de segurança para permissões do Dataform.

Definir a região padrão para recursos de código

Todos os novos recursos de código no seu projeto Google Cloud usam uma região padrão. Depois que o recurso é criado, não é possível mudar a região dele.

Importante: se você mudar a região ao criar um recurso de código, ela vai se tornar a padrão para todos os recursos de código subsequentes. Os recursos de código atuais não serão afetados.

Para definir a região padrão para novos recursos de código, faça o seguinte:

1. Acessar a página do BigQuery.

   Acessar o BigQuery

2. No painel à esquerda, clique em Arquivos para abrir o navegador de arquivos:

   

3. Ao lado do nome do projeto, clique em Ver ações do painel de arquivos > Mudar região de código.

4. Selecione a região de código que você quer usar como padrão.

5. Clique em Salvar.

Para conferir uma lista de regiões compatíveis, consulte Locais do BigQuery Studio.

Criptografar com CMEK

É possível criptografar as consultas salvas com suporte do Dataform usando chaves de criptografia gerenciadas pelo cliente (CMEK) com a chave CMEK padrão para envolvidos no projeto para a API Dataform. Não é possível aplicar chaves CMEK individuais a consultas salvas no console Google Cloud . As novas configurações são aplicadas apenas às consultas salvas criadas recentemente.

Para mais informações e instruções sobre como definir a chave padrão, consulte Usar a CMEK para proteger recursos de código do BigQuery Studio.

Criar consultas salvas

Para criar uma consulta salva, siga estas etapas:

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

   Acessar o BigQuery

2. Clique em Consulta SQL.

3. No editor de consultas, insira uma consulta válida do SQL. Por exemplo, consulte um conjunto de dados público:

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

   Como alternativa, use o painel Referência para criar novas consultas.

4. Clique em Salvar > Salvar consulta ou pressione Control+S (ou Command+S no macOS).

5. Na caixa de diálogo Salvar consulta, digite um nome para a consulta salva.

6. Opcional: para mudar a região usada por essa consulta salva e por todos os outros recursos de código no futuro, selecione uma nova região no campo Região.

7. Clique em Salvar.

   A primeira versão da consulta salva é criada.

8. Opcional: depois de salvar a consulta, use a seguinte barra de ferramentas para ver os detalhes dela ou o histórico de versões, adicionar novos comentários, responder ou receber um link para um comentário existente:

   

   O recurso da barra de ferramentas Comentários está em pré-lançamento. Para enviar feedback ou solicitar suporte para esse recurso, envie um e-mail para [e-mail].

Compartilhar consultas salvas

Para compartilhar uma consulta salva com um usuário, primeiro conceda a ele acesso à consulta salva e adicione-o a um papel apropriado do IAM. Em seguida, gere um link para a consulta salva e compartilhe com o usuário.

Os usuários com quem você compartilha uma consulta só veem a versão mais recente dela. As mudanças salvas automaticamente que você não salvou explicitamente não aparecem na consulta compartilhada.

Para compartilhar uma consulta salva, siga estas etapas:

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

   Acessar o BigQuery

2. No painel à esquerda, clique em Arquivos para abrir o navegador de arquivos.

   Se o painel esquerdo não aparecer, clique em Expandir painel esquerdo para abrir.

3. No painel Arquivos, expanda seu projeto e as subpastas para encontrar a consulta salva que você quer compartilhar.

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

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

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

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

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

9. Clique em Salvar.

10. Para retornar aos detalhes da consulta salva, clique em Fechar.

11. Para gerar um link para a consulta salva, clique em Ver ações > Compartilhar > Copiar link.

    O link será copiado para a área de transferência.

Abra uma versão de consulta salva como uma nova consulta

Para abrir qualquer versão de uma consulta salva atual como uma nova consulta, siga estas etapas:

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

   Acessar o BigQuery

2. No painel à esquerda, clique em Arquivos para abrir o navegador de arquivos:

   

   Se o painel esquerdo não aparecer, clique em Expandir painel esquerdo para abrir.

3. No painel Arquivos, expanda seu projeto e as subpastas para encontrar a consulta salva que você quer abrir.

4. Clique na consulta salva e em Histórico de versões.

5. Clique em Conferir ações ao lado de uma versão de consulta salva e, em seguida, clique em Abrir como nova consulta.

Atualizar consultas salvas

As mudanças feitas no texto de uma consulta salva são salvas automaticamente dois segundos depois que você para de digitar e aparecem no Histórico de versões como Suas mudanças. As mudanças salvas automaticamente não são uma nova versão da consulta. As mudanças salvas automaticamente reaparecem sempre que você abre a consulta, mas não ficam visíveis para mais ninguém, a menos que você as salve explicitamente como uma nova versão da consulta. As consultas salvas automaticamente estão em Prévia.

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

   Acessar o BigQuery

2. No painel à esquerda, clique em Arquivos para abrir o navegador de arquivos:

   

   Se o painel esquerdo não aparecer, clique em Expandir painel esquerdo para abrir.

3. No painel Arquivos, expanda seu projeto e as subpastas para encontrar a consulta salva que você quer atualizar.

4. Clique na consulta salva para abri-la.

5. Modifique a consulta.

6. Para salvar a consulta modificada, clique em Salvar consulta > Salvar consulta ou pressione Control+S (ou Command+S no macOS).

   Uma nova versão da consulta é criada.

Fazer upload de consultas salvas

É possível fazer upload de uma consulta SQL local para usá-la como uma consulta salva no BigQuery Studio. A consulta salva enviada também fica visível na página do BigQuery no console do Google Cloud .

Para fazer upload de uma consulta salva, siga estas etapas:

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

   Acessar o BigQuery

2. No painel à esquerda, clique em Arquivos para abrir o navegador de arquivos:

   

   Se o painel esquerdo não aparecer, clique em Expandir painel esquerdo para abrir.

3. No painel Arquivos, clique em Conferir ações ao lado da pasta em que você quer fazer upload da consulta e clique em Fazer upload > Consulta.

4. Na caixa de diálogo Fazer upload de SQL, no campo SQL, clique em Procurar e selecione a consulta que você quer fazer o upload delas.

5. Opcional: no campo Nome do SQL, edite o nome da consulta.

6. No campo Região, selecione onde você quer fazer o upload da consulta salva.

7. Clique em Fazer upload.

Você pode acessar a consulta salva no painel Arquivos ou Explorer.

Resolver problemas com consultas salvas

Nesta seção, descrevemos como resolver problemas comuns com consultas salvas.

Não é possível salvar consultas

Se não for possível salvar uma consulta, talvez a API Dataform não esteja ativada para o projeto. A API Dataform é ativada automaticamente para a maioria dos projetos, mas não para aqueles que usam a restrição da política da organização Restringir o uso do serviço de recursos, como os projetos garantidos.

Para resolver esse problema, verifique se a API Dataform está ativada:

1. No console do Google Cloud , acesse a página APIs e serviços.
2. Procure a API Dataform e verifique se ela está ativada.
3. Se a API não estiver ativada, clique em Ativar.
4. Tente de novo usando consultas salvas.

Incompatibilidade de região para consultas salvas

Mudar a região padrão para recursos de código afeta apenas os recursos criados após a mudança. Os recursos atuais permanecem na região original.

Para resolver esse problema, verifique se a região selecionada para a consulta salva corresponde a uma das regiões com suporte. Se necessário, crie uma consulta salva em uma região compatível ou ajuste a região padrão dos recursos de código.

Consultas salvas clássicas

Descontinuadas: as consultas salvas, disponíveis no BigQuery Studio, vão substituir totalmente as consultas salvas clássicas no futuro. O cronograma de descontinuação está sendo revisado. 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 aprender a criar e atualizar consultas salvas clássicas. Para mais informações sobre como compartilhar, migrar e excluir consultas salvas clássicas, consulte Consultas salvas clássicas.

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

Permissões necessárias para consultas salvas clássicas

As seguintes permissões do IAM são obrigatórias para criar, visualizar, atualizar e excluir consultas salvas clássicas:

• Consultas salvas clássicas particulares:
  • A criação de consultas salvas clássicas particulares não requer permissões especiais. É possível salvar uma consulta particular em qualquer projeto, mas somente você poderá ver, atualizar ou excluir a consulta.
• Consultas salvas clássicas para envolvidos no projeto:
  • Para criar uma consulta salva para envolvidos no projeto, é preciso ter permissões bigquery.savedqueries.create. O papel predefinido bigquery.admin inclui permissões bigquery.savedqueries.create.
  • Para conferir uma consulta salva para envolvidos no projeto, é preciso ter permissões bigquery.savedqueries.get e bigquery.savedqueries.list. Os papéis predefinidos bigquery.admin e bigquery.user incluem as permissões bigquery.savedqueries.get e bigquery.savedqueries.list.
  • Para atualizar uma consulta clássica salva para envolvidos no projeto, é preciso ter permissões bigquery.savedqueries.update. O papel predefinido bigquery.admin inclui permissões bigquery.savedqueries.update.
  • Para excluir uma consulta clássica salva para envolvidos no projeto, é preciso ter permissões bigquery.savedqueries.delete. O papel predefinido bigquery.admin inclui permissões bigquery.savedqueries.delete.
• Consultas salvas clássicas públicas:
  • A criação de consultas salvas clássicas públicas não requer permissões especiais. É possível salvar uma consulta clássica pública em qualquer projeto, mas somente você conseguirá atualizar ou excluir a consulta. Qualquer pessoa com o link pode acessar uma consulta clássica salva pública.

Para mais informações sobre os papéis do IAM no BigQuery, consulte Papéis e permissões predefinidos.

Criar consultas salvas clássicas

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

   Acessar o BigQuery

2. Clique em Consulta SQL.

3. No editor de consultas, insira uma consulta válida do SQL. Por exemplo, consulte um conjunto de dados público:

   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. Clique em Salvar consulta (clássica) > Salvar consulta (clássica).

5. Na caixa de diálogo Salvar consulta, insira um nome para sua consulta e defina a Visibilidade como uma das seguintes opções:

   • Pessoal (editável apenas por você) para uma consulta salva clássica particular.
   • Projeto (editável pelos participantes com as permissões apropriadas) para uma consulta salva clássica para envolvidos no projeto.
   • Público para uma consulta salva clássica pública.

6. Clique em Salvar.

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

Para compartilhar uma consulta salva clássica, siga estas etapas:

1. No painel à esquerda, clique em Explorer.

   Se o painel esquerdo não aparecer, clique em Expandir painel esquerdo para abrir.

2. No painel Explorer, expanda seu projeto e clique em Consultas(clássicas).

3. Encontre e clique na consulta salva clássica a que você quer conceder acesso. Use a pesquisa ou os filtros para encontrar sua consulta.

4. Clique em Ver ações ao lado da consulta e clique em Copiar link.

5. Compartilhe o link com os usuários a quem você quer conceder acesso à consulta.

Atualizar consultas salvas clássicas

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

   Acessar o BigQuery

2. No painel à esquerda, clique em Explorer:

   

   Se o painel esquerdo não aparecer, clique em Expandir painel esquerdo para abrir.

3. No painel Explorer, expanda seu projeto e a pasta Consultas(clássicas) e, se necessário, a pasta Consultas do projeto.

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

5. Modifique a consulta.

6. Para salvar a consulta modificada, clique em Salvar consulta (clássica) > Salvar consulta (clássica).

Resolver problemas com consultas salvas clássicas

Nesta seção, descrevemos como resolver problemas comuns com consultas salvas clássicas.

Não é possível acessar as consultas salvas de um usuário desativado

Ao contrário das consultas salvas do BigQuery Studio, que podem ser acessadas por administradores de projetos, as consultas salvas clássicas particulares ficam inacessíveis se o usuário que as criou sair de uma organização e a Conta do Google dele for desativada ou suspensa. As consultas desaparecem do console do Google Cloud para todos os usuários, exceto o proprietário original.

Para recuperar essas consultas, um administrador do Google Workspace ou do Cloud Identity precisa seguir estas etapas:

1. Reative temporariamente a conta do usuário desativado.
2. Redefina a senha do usuário.
3. Faça login no console Google Cloud como o usuário reativado.
4. No editor de consultas, abra cada consulta salva.
5. Clique em Salvar ou Salvar consulta como.
6. Mude a Visibilidade de Pessoal para Projeto.
7. Clique em Salvar. Isso torna a consulta visível para outros usuários no mesmo projeto que têm as permissões necessárias.
8. Depois que todas as consultas forem migradas, suspenda a conta do usuário novamente.

Para evitar esse problema, salve consultas essenciais para os negócios ou compartilhadas com a equipe com visibilidade Projeto.

A seguir

• Saiba como gerenciar consultas salvas.