Criar notebooks

Observação: os notebooks do BigQuery Studio começarão a ser cobrados com disponibilidade geral após 11 de abril de 2024. Você começará a ver cobranças baseadas em uso para notebooks do BigQuery Studio na sua fatura.

Neste documento, descrevemos como criar notebooks do Colab Enterprise no BigQuery. Os notebooks são recursos de código do BigQuery Studio com tecnologia do Dataform.

Antes de começar

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. Enable the BigQuery API.

   Enable the API

5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

6. Make sure that billing is enabled for your Google Cloud project.

7. Enable the BigQuery API.

   Enable the API

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

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

Todos os usuários com o papel de administrador do Dataform (roles/dataform.admin) têm acesso de proprietário a todos os notebooks criados 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 notebooks

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

• resourcemanager.projects.get
• resourcemanager.projects.list
• bigquery.config.get
• bigquery.jobs.create
• bigquery.readsessions.create
• bigquery.readsessions.getData
• bigquery.readsessions.update
• resourcemanager.projects.get
• resourcemanager.projects.list
• dataform.locations.get
• dataform.locations.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.

• dataform.repositories.list

• dataform.collections.create

• dataform.collections.list

• aiplatform.notebookRuntimeTemplates.apply

• aiplatform.notebookRuntimeTemplates.get

• aiplatform.notebookRuntimeTemplates.list

• aiplatform.notebookRuntimeTemplates.getIamPolicy

• aiplatform.notebookRuntimes.assign

• aiplatform.notebookRuntimes.get

• aiplatform.notebookRuntimes.list

• aiplatform.operations.list

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

• Usuário de sessão de leitura do BigQuery(roles/bigquery.readSessionUser)

• Usuário do BigQuery Studio(roles/bigquery.studioUser)

  O papel do usuário do BigQuery Studio combina os seguintes papéis do IAM:

  • Usuário de jobs do BigQuery(roles/bigquery.jobUser)
  • Usuário do ambiente de execução do notebook (roles/aiplatform.notebookRuntimeUser)

  • 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 notebooks

Para editar e executar notebooks, 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)
• Usuário do ambiente de execução do notebook (roles/aiplatform.notebookRuntimeUser)
• Editor de código (roles/dataform.codeEditor)

Permissões para ver notebooks

Para visualizar e executar notebooks, 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)
• Usuário do ambiente de execução do notebook (roles/aiplatform.notebookRuntimeUser)
• Visualizador de código (roles/dataform.codeViewer)

Criar notebooks

Use as seções a seguir para aprender a criar um notebook.

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 um notebook no editor do BigQuery

Para criar um notebook contendo uma consulta padrão para uma determinada tabela, siga estas etapas:

1. Acessar a página do BigQuery.

   Acessar o BigQuery

2. Na barra de guias do painel do editor, clique na seta suspensa ao lado do sinal + e clique em Criar um notebook em Python.

   O novo notebook é aberto, com células que mostram exemplos de consultas no conjunto de dados público bigquery-public-data.ml_datasets.penguins.

Criar um notebook a partir de uma tabela

Para criar um notebook contendo uma consulta padrão para uma determinada tabela, siga estas etapas:

1. Acessar a página do BigQuery.

   Acessar o BigQuery

2. No painel Explorer, expanda seu projeto e encontre a tabela que você quer consultar.

3. Clique em Ver ações ao lado da tabela, clique em Consultar em > Notebook Python.

   O novo notebook é aberto, com células que mostram exemplos de consultas na tabela selecionada.

Criar um notebook para explorar o conjunto de resultados de uma consulta

Para criar um notebook para explorar o conjunto de resultados de uma consulta, siga estas etapas:

1. Acessar a página do BigQuery.

   Acessar o BigQuery

2. No painel do editor, execute uma consulta que gere um resultado.

3. No painel Resultados da consulta, clique em Explorar dados e em Explorar com notebook Python.

   O novo notebook é aberto, contendo células com o código para retornar o SQL da consulta e os resultados da consulta.

Criar um notebook a partir de um notebook

Para abrir qualquer versão de um notebook atual como um novo notebook, 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 um notebook

3. Selecione o painel Atividade.

4. Clique em Ver ações ao lado de uma versão do notebook e clique em Abrir como um novo notebook Python.

   Uma cópia do notebook é aberta como um novo notebook.

Fazer upload de notebooks

É possível fazer upload de um notebook local para usá-lo no BigQuery Studio. O notebook enviado por upload fica visível na página do BigQuery no console do Google Cloud.

Para fazer upload de um notebook, 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 Notebooks, clique em Ver ações > Fazer upload para Notebooks.
   • Ao lado do nome do projeto do Google Cloud, clique em Ver ações > Fazer upload para o projeto > Notebook Python.

3. Na caixa de diálogo Fazer upload do notebook, no campo notebook, clique em Procurar e selecione o notebook para upload.

4. Opcional: no campo Nome do notebook, edite o nome do notebook.

5. No campo Região, selecione a região em que você quer fazer upload do notebook.

6. Clique em Fazer upload.

Seu notebook será exibido no painel Explorer.

Conectar-se a um ambiente de execução

Use as seções a seguir para saber como conectar um notebook a um ambiente de execução da Vertex AI. Um ambiente de execução é um recurso de computação que executa o código no notebook.

Para mais informações sobre ambientes de execução, consulte Ambientes de execução e modelos de ambiente de execução.

Conectar ao ambiente de execução padrão

O padrão é predefinido e requer configuração mínima.

Para se conectar ao ambiente de execução padrão, 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. Clique no nome de um notebook para abri-lo.

3. No notebook, clique em Conectar ou execute qualquer célula no notebook.

   Se você ainda não tiver um ambiente de execução ativo, poderá levar vários minutos para se conectar ao ambiente de execução padrão.

Conectar-se a um ambiente de execução não padrão

Se você quiser usar um ambiente de execução diferente do padrão, primeiro crie esse ambiente de execução adicional na Vertex AI.

Para se conectar ao ambiente de execução não padrão, 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. Clique no nome de um notebook para abri-lo.

3. No notebook, clique no menu suspenso ao lado de Conectar e, em seguida, clique em Conectar a um ambiente de execução.

4. Clique em Conectar a um ambiente de execução.

5. Em Ambientes de execução, selecione o ambiente a ser usado.

6. Clique em Conectar.

Conexão com um novo ambiente de execução

Para se conectar a um novo ambiente de execução, 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. Clique no nome de um notebook para abri-lo.

3. No notebook, clique no menu suspenso ao lado de Conectar e, em seguida, clique em Conectar a um ambiente de execução.

4. Clique em Criar novo ambiente de execução.

5. Em Modelo de ambiente de execução, selecione o modelo de ambiente de execução da Vertex AI para usar.

6. Em Nome do ambiente de execução, digite um nome para o ambiente de execução.

7. Clique em Conectar.

Conceder acesso a notebooks

Para conceder acesso a um notebook a outros usuários, adicione-os a um papel apropriado do IAM.

Importante: os usuários que têm acesso ao notebook podem ver toda a saída gerada pelo código no notebook, mesmo que ela contenha dados de tabelas às quais eles não têm acesso. Para evitar que a saída salva seja compartilhada, desative o salvamento de saída do notebook.

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 o notebook a que você quer conceder acesso.

3. Clique em Ver ações ao lado do notebook e depois selecione 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 no notebook, inclusive excluí-lo ou compartilhá-lo.
   • Editor de código: pode editar o notebook.
   • Leitor de código: pode visualizar o notebook.
   Observação: o principal também precisa ter os papéis Usuário de ambiente de execução do notebook (roles/aiplatform.notebookRuntimeUser) e Usuário do BigQuery (roles/bigquery.user) para executar o notebook.

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 à página de informações do notebook, clique em Fechar.

Compartilhar notebooks

Para compartilhar um notebook com outros usuários, gere e compartilhe um link para ele. Para que outros usuários vejam o notebook que você compartilha, primeiro é necessário conceder acesso a ele.

Para executar um notebook, os usuários precisam ter acesso aos dados que ele acessa. Para mais informações, consulte Conceder acesso a um conjunto de dados.

Importante: os usuários que têm acesso ao notebook podem ver toda a saída gerada pelo código no notebook, mesmo que ela contenha dados de tabelas às quais eles não têm acesso. Para evitar que a saída salva seja compartilhada, desative o salvamento de saída do notebook.

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. Localize o notebook que você quer compartilhar.

3. Clique em Conferir ações ao lado do notebook e depois em Compartilhar > Copiar link.

4. Compartilhe o link com outros usuários.

Desativar o salvamento de saída do notebook

Para evitar o compartilhamento da saída salva do notebook com outros usuários que tenham acesso ao arquivo do notebook, desative o salvamento de saída do notebook.

Quando você desativa o salvamento de saída em um notebook selecionado, o BigQuery exclui todas as saídas salvas no arquivo do notebook e não salva a saída de execuções subsequentes.

No entanto, os usuários com acesso ao notebook ainda poderão visualizar a saída das seguintes maneiras:

• Execute o notebook para conferir a saída atual. Esta saída não foi salva.
• Conferir uma versão de arquivo do notebook e a saída no histórico de revisões.

Para desativar o salvamento da saída de um notebook selecionado, 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, em seguida, selecione o notebook em que você quer desativar o salvamento da saída.

3. Clique em Alternar visibilidade do cabeçalho > Editar > Configurações do notebook.

4. Na janela Configurações do notebook, selecione Omitir saída da célula de código ao salvar este notebook.

5. Clique em Salvar.

6. Clique em Atualizar.

Resolver conflitos

Se você e outro usuário fizerem alterações conflitantes em um notebook, o serviço vai gerar um erro Automatic saving failed. This file was updated remotely or in another tab. e fornecer um link Show diff. Para resolver o conflito, siga estas etapas:

1. Clique no link Show diff. A caixa de diálogo Revisar alterações remotas é aberta.
2. Opcional: para comparar o código-fonte do notebook, marque a caixa de seleção Origem dos dados brutos.
3. Opcional: para comparar as versões inline em vez de em painéis separados, marque a caixa de seleção Diferenças inline.
4. Revise as alterações e decida quais manter, revisando sua entrada, se necessário.
5. Clique em Salvar alterações.

Renomear notebooks

Para renomear um notebook, 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. Localize o notebook que você quer renomear.

3. Clique em Ver ações ao lado do notebook e clique em Renomear.

4. Digite um nome para o notebook e clique em Renomear.

Solução de problemas

Confira mais informações em Resolver problemas no Colab Enterprise.

A seguir

• Saiba como gerenciar notebooks.