Criar consultas salvas

Ao escrever SQL no editor de consultas, é possível salvar e compartilhar a 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 Google Cloud projeto têm acesso de proprietário a todas as consultas salvas criadas no projeto. Para substituir esse comportamento, consulte Conceder um papel específico após a criação do recurso.

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)
• Leitor de código (roles/dataform.codeViewer)

Considerações de segurança para consultas salvas

Como os recursos de código no BigQuery são baseados no 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 pelas permissões do Dataform no nível do projeto. Os usuários com a permissão dataform.repositories.list, que está incluída em papéis padrão do BigQuery, como Usuário de jobs do BigQuery, Usuário do BigQuery Studio e Usuário do BigQuery, podem ver todos os recursos de código no painel Explorer do Google Cloud projeto, independentemente de terem criado esses recursos ou de terem sido compartilhados com eles. Para restringir a visibilidade, é possível criar papéis personalizados que excluem a dataform.repositories.list permissão.
• Qualquer secret compartilhado com o agente de serviço do Dataform pode ser acessado 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 Google Cloud projeto 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, essa região se tornará a padrão para todos os recursos de código subsequentes. Os recursos de código atuais não são afetados.

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

1. Acessar a página 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 do 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) usando a chave CMEK padrão para envolvidos no projeto para a API Dataform. Não é possível aplicar chaves CMEK individuais a consultas salvas em Google Cloud console. As novas configurações são aplicadas apenas a consultas salvas recém-criadas.

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

Criar consultas salvas

Para criar uma consulta salva, siga estas etapas:

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

   Acessar o BigQuery

2. Clique em Consulta SQL.

3. No editor de consultas, insira uma consulta SQL válida. 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, é possível usar 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 alterar 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 barra de ferramentas a seguir para conferir os detalhes da consulta ou o histórico de versões, adicionar novos comentários ou responder ou receber um link para um comentário atual:

   

   O recurso da barra de ferramentas Comentários está na visualização. 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 acesso a ele e adicione-o a um papel apropriado do IAM. Em seguida, gere um link para a consulta salva e compartilhe-o com o usuário.

Os usuários com quem você compartilha uma consulta só podem ver 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 Google Cloud console, acesse a 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 Ver 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.

Abrir 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 Google Cloud console, 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 Ver 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 após você parar 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 na visualização.

1. No Google Cloud console, 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 Google Cloud console.

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

1. No Google Cloud console, 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 Ver ações ao lado da pasta em que você quer fazer o 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.

A consulta salva pode ser acessada pelo painel Arquivos ou Explorer.

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á em análise. 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 ativou o BigQuery Studio, as consultas salvas clássicas vão aparecer na pasta Consultas salvas (NUMBER) no 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 Google Cloud console, acesse a página BigQuery.

   Acessar o BigQuery

2. Clique em Consulta SQL.

3. No editor de consultas, insira uma consulta SQL válida. 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. É possível usar o recurso de pesquisa ou filtros para encontrar sua consulta.

4. Clique em Ver ações ao lado da consulta e 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 Google Cloud console, 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 de projetos.

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

A seguir

• Saiba como gerenciar consultas salvas.