Criar consultas salvas

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

Consultas salvas

Use as seções a seguir para aprender a criar consultas salvas. 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 Consultas salvas.

Ativar o BigQuery Studio

Siga as instruções em Ativar o BigQuery Studio para gerenciamento de recursos para salvar, compartilhar e gerenciar versões de recursos de código, como consultas salvas.

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.

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

  Observação :os usuários com a permissão dataform.repositories.create podem executar o código usando a conta de serviço padrão do Dataform e todas as permissões concedidas a essa conta. Para mais informações, consulte Considerações de segurança para permissões do Dataform.

É 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. Os não administradores que usam o BigQuery Studio só podem ver os recursos de código que criaram ou que foram compartilhados com eles.

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)

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

Se esta for a primeira vez que você cria um recurso de código, defina a região padrão para os recursos de código. Não é possível alterar a região de um recurso de código depois que ele é criado.

Observação: se você criar uma consulta salva e escolher uma região padrão diferente da que está usando para recursos de código como, por exemplo, escolher us-west1 ao estar usando us-central1, essa consulta e todos os recursos de código que você criar depois usarão essa nova região por padrão. Os recursos de código atuais continuam usando a região atribuída na criação.

Criar consultas salvas

Para criar uma consulta salva, siga estas etapas:

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

   Ir para o BigQuery

2. Clique em Criar uma nova consulta.

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

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 em Região.

7. Clique em Salvar.

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 Explorer e, se necessário, a pasta Explorer. 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 Explorer e, se necessário, expanda a pasta Explorer. 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.

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

   Acessar o BigQuery

2. No painel Explorer, expanda seu projeto e a pasta Explorer e, se necessário, a pasta Explorer. Selecione uma consulta salva.

3. Selecione o painel Atividade.

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

Se você atualizar uma consulta salva, poderá salvar as alterações em uma nova versão da consulta.

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 Explorer e, se necessário, a pasta Explorer. Clique no nome de uma consulta salva para abri-la.

3. Modifique a consulta.

4. Para salvar a consulta modificada, clique em Salvar consulta > Salvar consulta.

   Uma nova versão da consulta é criada, que pode ser vista no painel Atividade.

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

   Acessar o BigQuery

2. No painel Explorer, expanda seu projeto e depois siga um destes procedimentos:

   • Ao lado de Consultas, clique em Ver ações > Fazer upload da consulta SQL.
   • Ao lado do nome do projeto do Google Cloud, clique em Ver ações > Fazer upload para o projeto > consulta SQL.

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

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

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

6. Clique em Fazer upload.

A consulta salva será exibida no painel Explorer.

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 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 aparecerão 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.

Observação: os usuários que recebem a permissão dataform.repository.list para envolvidos no projeto podem ver todas as consultas salvas criadas no projeto.

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.

   Ir para o BigQuery

2. Clique em Criar uma nova consulta.

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

Atualizar 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 Explorer e, se necessário, a pasta Explorer.

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

4. Modifique a consulta.

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

A seguir

• Saiba como gerenciar consultas salvas.