Criar pipelines

Neste documento, descrevemos como criar pipelines no BigQuery. Os pipelines são gerados pelo Dataform.

Antes de começar

Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery, Dataform, and Vertex AI APIs.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery, Dataform, and Vertex AI APIs.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

Requisitos do VPC Service Controls

Se você usa o VPC Service Controls para proteger seus pipelines, saiba que as execuções de pipeline são alimentadas pelo Dataform. Ao configurar o VPC Service Controls para execuções programadas, verifique se os seguintes requisitos são atendidos:

• Você precisa definir o dataform.restrictGitRemotes serviço de política da organização.
• O Dataform e o BigQuery precisam ser restritos pelo mesmo perímetro de serviço do VPC Service Controls.
• Para permitir que os usuários façam a autenticação com as credenciais da Conta do Google ao programar ou acionar manualmente execuções, adicione as identidades de usuário às regras de entrada. Para mais informações, consulte Como atualizar políticas de entrada e saída de um perímetro de serviço e Referência de regras de entrada.

Para etapas de configuração detalhadas e considerações de segurança, consulte Configurar o VPC Service Controls para o Dataform.

Papéis necessários para pipelines

Para receber as permissões necessárias para criar pipelines, peça ao administrador que conceda a você os seguintes papéis do IAM:

• Para criar pipelines: Criador de código (roles/dataform.codeCreator) no projeto
• Para editar e executar pipelines: Editor do Dataform (roles/dataform.editor) no projeto
• Para criar pipelines em pastas de usuários:
  • Criador de código (roles/dataform.codeCreator) no projeto
  • Proprietário do código (roles/dataform.codeOwner) na pasta
  • Editor de código (roles/dataform.codeEditor) na pasta
• Para criar pipelines em pastas de grupo:
  • Colaborador da pasta de equipe (roles/dataform.teamFolderContributor) na pasta de equipe
  • Proprietário da pasta de equipe (roles/dataform.teamFolderOwner) na pasta de equipe
• Para conectar um repositório Git a pastas do Git: Usuário do OAuth do Developer Connect (roles/developerconnect.oauthUser) no projeto

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

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Para mais informações sobre o IAM do Dataform, consulte Controlar o acesso com o IAM.

Para mais informações sobre papéis em pastas, consulte Criar e gerenciar pastas.

Para mais informações sobre papéis em repositórios Git, consulte Gerenciar código com repositórios Git do BigQuery Studio.

Observação: ao criar um pipeline, o BigQuery concede a você a função de administrador do Dataform (roles/dataform.admin) nele. Todos os usuários com o papel de administrador do Dataform concedido no projeto Google Cloud têm acesso de proprietário a todos os pipelines criados no projeto. Para substituir esse comportamento, consulte Conceder um papel específico na criação de recursos.

Papéis necessários para opções de notebook

Para receber as permissões necessárias para selecionar um modelo de ambiente de execução nas opções de notebook, peça ao administrador para conceder a você o papel do IAM de Usuário do ambiente de execução do notebook (roles/aiplatform.notebookRuntimeUser) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Se você não tiver essa função, selecione a especificação padrão de tempo de execução do notebook.

Considerações de segurança para pipelines

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

Criar um pipeline

É possível criar e armazenar pipelines das seguintes maneiras:

• Em pastas: organize pipelines em pastas pessoais ou de equipe no painel Arquivos do BigQuery Studio.
• Nas pastas do Git do BigQuery Studio (pré-lançamento): hospede, controle de versões e gerencie vários pipelines independentes ou de nível raiz em uma pasta com um repositório Git conectado usando o Developer Connect.
• Na barra de guias do editor: crie um pipeline no menu + do editor de consultas.
• Na página "Pipelines e conexões" (pré-lançamento): crie um pipeline usando um fluxo de trabalho simplificado e específico do BigQuery.

Criar um pipeline em uma pasta

É possível criar e organizar pipelines diretamente nas pastas pessoais do usuário ou nas pastas compartilhadas da equipe no BigQuery Studio. Para mais informações sobre pastas, consulte Organizar recursos de código com pastas.

Para criar um pipeline em uma pasta, 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. Faça o seguinte para criar um pipeline:

   • Selecione a pasta do usuário ou da equipe em que você quer colocar o pipeline, clique no botão + (Criar) na barra de ferramentas e selecione Pipeline.
   • Na árvore de arquivos, clique em Ver ações ao lado do nome de uma pasta e selecione Criar > Pipeline.
   • Abra uma pasta para ver o conteúdo dela no painel principal e clique em Criar pipeline.

4. Na caixa de diálogo de criação, insira um nome para o pipeline.

5. Clique em Criar. Uma nova pasta de pipeline aparece na árvore de arquivos com o ícone Pipeline.

6. Clique na pasta do pipeline para abrir o Visualizador de pipeline e configure as definições do pipeline.

Criar um pipeline em um repositório Git

Visualizar

Este produto ou recurso está sujeito aos "Termos das Soluções 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.

Observação: para enviar feedback ou solicitar suporte sobre esse recurso, envie um e-mail para [e-mail].

É possível criar e gerenciar pipelines diretamente em pastas integradas ao Git no BigQuery Studio. Uma pasta Git representa um repositório remoto do GitHub ou GitLab conectado ao BigQuery Studio usando o Developer Connect. É possível hospedar e organizar vários pipelines independentes em um único repositório Git. Os pipelines de repositório Git oferecem suporte a implantações do Dataform para programação, configurações de lançamento e orquestração de vários ambientes.

Para criar um pipeline em uma pasta do Git, siga estas etapas:

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

   Acessar o BigQuery

2. Se você ainda não conectou seu repositório Git, crie e conecte um repositório Git do BigQuery Studio.

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

4. Na árvore de arquivos, localize a pasta do repositório Git conectado ou um diretório aninhado nela.

5. Clique em Ver ações ao lado do nome da pasta e selecione Criar > Pipeline.

6. Na caixa de diálogo, insira o nome do pipeline e clique em Salvar.

   Um novo diretório de pipeline é criado e inicializado com os arquivos padrão:

   • workflow_settings.yaml: configuração do pipeline.
   • definitions/actions.yaml: definições de tarefas vazias.

7. Clique no diretório do pipeline no navegador de arquivos para abrir o Visualizador de pipelines.

Observação: se o repositório Git remoto tiver a configuração do pipeline (workflow_settings.yaml) no diretório raiz, o BigQuery Studio vai reconhecer automaticamente o repositório como um pipeline de nível raiz.A pasta do repositório Git vai mostrar o ícone Pipeline. Ao clicar na pasta do repositório Git, o Visualizador de pipeline é aberto, mostrando o DAG compilado de todo o repositório. Não é necessário criar um diretório de pipeline aninhado.

Criar um pipeline na barra de guias do editor

Para criar um pipeline na barra de guias do editor, siga estas etapas:

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

   Acessar o BigQuery

2. Na barra de guias do painel do editor, clique na seta ao lado do sinal + e clique em Pipeline.

3. Opcional: para renomear o pipeline, clique no nome dele e digite um novo.

4. Clique em Começar e configure as definições de pipeline.

Criar um pipeline na página "Pipelines e conexões"

Você pode usar a página Pipelines e conexões do BigQuery no console Google Cloud para criar um pipeline do Dataform que usa um fluxo de trabalho simplificado e específico do BigQuery. Esse recurso está na visualização.

Para instruções sobre como criar um pipeline na página Pipelines e conexões do BigQuery, consulte Criar um recurso de integração de dados.

Configurar as definições do pipeline

Para configurar as definições do pipeline, abra o pipeline no Visualizador de pipelines, clique na guia Configurações e configure as seguintes seções:

1. Na seção Autenticação, escolha autorizar o pipeline com as credenciais de usuário da sua Conta do Google ou uma conta de serviço.

   • Para usar as credenciais de usuário da sua Conta do Google (Prévia), selecione Executar com minhas credenciais de usuário.

     Opcional: na seção Opções de acesso estendido, selecione os serviços adicionais necessários para seu pipeline:

     • Knowledge Catalog: permite atualizações de metadados do Google Cloud Knowledge Catalog.
     • Google Drive: permite acesso somente leitura aos arquivos do Google Drive.

     • Bigtable: permite acesso somente leitura aos dados do Google Bigtable.

       Observação: não é possível autenticar execuções baseadas em API com credenciais de usuário. Para executar todas as tarefas em um pipeline usando a API Dataform, configure o pipeline para usar uma conta de serviço.

   • Para usar uma conta de serviço, selecione Executar com a conta de serviço selecionada e escolha uma conta de serviço. Se você precisar criar uma conta de serviço, clique em Nova conta de serviço.

2. Na seção Local de processamento, selecione um local para o pipeline.

   • Para ativar a seleção automática de um local, selecione Seleção automática de local. Essa opção seleciona um local com base nos conjuntos de dados referenciados na solicitação. O processo de seleção é o seguinte:

     • Se a consulta fizer referência a conjuntos de dados do mesmo local, o BigQuery usará esse local.
     • Se a consulta fizer referência a conjuntos de dados de dois ou mais locais diferentes, um erro vai ocorrer. Para mais detalhes sobre essa limitação, consulte Replicação de conjuntos de dados entre regiões.
     • Se a consulta não fizer referência a nenhum conjunto de dados, o BigQuery usará a multirregião US por padrão.

   • Para escolher uma região específica, selecione Região e escolha uma opção no menu Região. Como alternativa, use a variável de sistema @@location na consulta. Para mais informações, consulte Especificar locais.

   • Para escolher uma multirregião, selecione Multirregião e escolha uma no menu Multirregião.

   O local de processamento do pipeline não precisa corresponder ao local de armazenamento padrão dos recursos de código.

Opções do SQLX

Para configurar as opções do SQLX para seu pipeline, faça o seguinte na seção Opções do SQLX:

1. No campo Projeto padrão, insira o nome de um projetoGoogle Cloud . Esse valor é usado para defaultProject no arquivo workflow_settings.yaml e para defaultDatabase no arquivo dataform.json. O projeto padrão é usado pelas tarefas do pipeline durante a execução.

   Observação: o nome do projeto não é validado. Portanto, é possível inserir qualquer string não vazia. No entanto, se o projeto não existir, a execução do pipeline vai falhar.

2. Opcional: no campo Conjunto de dados padrão, pesquise e selecione um conjunto de dados existente. A lista de conjuntos de dados disponíveis é filtrada com base no projeto e no local de processamento selecionados. Esse valor é usado para defaultDataset no arquivo workflow_settings.yaml. O conjunto de dados padrão é usado pelas tarefas do pipeline durante a execução.

   Observação: definir o conjunto de dados padrão e mudar a região do pipeline invalida a seleção do conjunto de dados. Mudar o projeto também pode invalidar a seleção de conjuntos de dados. Se um determinado conjunto de dados não existir no projeto selecionado, ele será criado.

Opções de notebooks

Para adicionar um notebook ao pipeline, faça o seguinte na seção Opções de notebook:

1. No campo Modelo de execução, aceite o ambiente de execução padrão do notebook ou pesquise e selecione um ambiente de execução existente.

   • Para conferir as especificações do ambiente de execução padrão, clique na seta ao lado.
   • Para criar um ambiente de execução, consulte Criar um modelo de ambiente de execução.
   Observação: um modelo de ambiente de execução de notebook precisa estar na mesma região do pipeline que o especifica.
   Observação: quando você inclui um notebook em um pipeline do BigQuery, não é possível mudar a rede da instância de ambiente de execução do Gemini Enterprise Agent Platform. O tempo de execução é restrito à rede padrão, e não é possível selecionar outra rede.

2. No campo Bucket do Cloud Storage, clique em Procurar e selecione ou crie um bucket do Cloud Storage para armazenar a saída dos notebooks no pipeline.

3. Siga as etapas em Adicionar um principal a uma política no nível do bucket para adicionar sua conta de serviço personalizada do Dataform como um principal ao bucket do Cloud Storage que você planeja usar para armazenar a saída de execuções de pipeline programadas e conceda o papel de administrador do Storage (roles/storage.admin) a esse principal.

   A conta de serviço personalizada do Dataform selecionada precisa receber o papel do IAM "Administrador de armazenamento" no bucket selecionado.

Adicionar uma tarefa de pipeline

É possível adicionar várias tarefas a um pipeline que executa recursos de código em uma sequência específica.

Os recursos de código compatíveis em pipelines incluem:

• Consultas SQL
• Notebooks
• Preparações de dados
• Tabelas e visualizações (tarefas do SQLX)

Convenções de nomenclatura de tarefas

Ao nomear uma tarefa de pipeline, siga estas convenções de nomenclatura:

• Os nomes de tarefas só podem conter letras (a-z, A-Z), números (0-9), sublinhados (_) e hífens (-).
• Os nomes das tarefas precisam começar com uma letra, um número ou um sublinhado.
• Pontos (.) são proibidos em nomes de tarefas. Ao nomear ou renomear uma tarefa, não inclua extensões de arquivo, como .sql ou .py. Se um nome de tarefa conter um ponto, o botão Executar será desativado.
• Os nomes de tarefas podem conter caracteres com um total de até 1.024 bytes UTF-8.
• Os nomes das tarefas precisam ser exclusivos no contêiner de pipeline.
• Os nomes das tarefas diferenciam maiúsculas de minúsculas.

Adicionar uma tarefa

Para adicionar uma tarefa a um pipeline, siga estas etapas:

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, clique em Pipelines e selecione um pipeline.

4. Para adicionar um recurso de código, selecione uma das seguintes opções:

Consulta SQL

Você pode criar uma nova consulta ou importar uma já existente.

1. Escolha uma destas opções:

   • Clique em Adicionar tarefa e selecione Consulta. Você pode criar uma nova consulta ou importar uma já existente.

   • Ao trabalhar com pipelines em pastas ou pastas do Git, clique com o botão direito do mouse na pasta do pipeline no painel Arquivos e selecione Criar consulta.

   • Ao trabalhar com pipelines em pastas ou pastas do Git, clique no botão Adicionar tarefa no Visualizador de pipeline.

2. Opcional: no painel Detalhes da tarefa de consulta, no menu Executar após, selecione uma tarefa para preceder sua consulta.

Criar uma consulta

1. Clique no menu de seta ao lado de Editar consulta e selecione No contexto ou Em uma nova guia.

2. Pesquise uma consulta.

3. Selecione um nome de consulta e pressione Enter.

4. Clique em Salvar.

5. Opcional: para renomear a consulta, clique no nome dela no painel de pipeline, em Editar consulta, no nome da consulta atual na parte de cima da tela e digite um novo nome.

Importar uma consulta

1. Clique no menu de seta ao lado de Editar consulta e clique em Importar uma cópia.

2. Pesquise uma consulta para importar ou selecione uma no painel de pesquisa. Quando você importa uma consulta, a original permanece inalterada porque o arquivo de origem da consulta é copiado para o pipeline.

3. Clique em Editar para abrir a consulta importada.

4. Clique em Salvar.

Notebook

Você pode criar um notebook ou importar um que já existe. Para mudar as configurações dos modelos de ambiente de execução do notebook, consulte Opções de notebook.

1. Escolha uma destas opções:

   • Clique em Adicionar tarefa e selecione Notebook.

   • Ao trabalhar com pipelines em pastas ou pastas do Git, clique com o botão direito do mouse na pasta do pipeline no painel Arquivos e selecione Criar notebook.

   • Ao trabalhar com pipelines em pastas ou pastas do Git, clique no botão Adicionar tarefa no Visualizador de pipeline.

   1. Opcional: no painel Detalhes da tarefa do notebook, no menu Executar após, selecione uma tarefa para preceder o notebook.

   Criar um notebook

2. Clique no menu de seta ao lado de Editar notebook e selecione No contexto ou Em nova guia.

3. Pesquise um notebook.

4. Selecione um nome de notebook e pressione Enter.

5. Clique em Salvar.

6. Opcional: para renomear o notebook, clique no nome dele no painel de pipeline, clique em Editar notebook, clique no nome atual na parte de cima da tela e digite um novo nome.

Importar um notebook

1. Clique no menu de seta ao lado de Editar notebook e clique em Importar uma cópia.

2. Pesquise um notebook para importar ou selecione um no painel de pesquisa. Quando você importa um notebook, o original permanece inalterado porque o arquivo de origem do notebook é copiado para o pipeline.

3. Para abrir o notebook importado, clique em Editar.

4. Clique em Salvar.

Preparação de dados

Você pode criar uma nova preparação de dados ou importar uma já existente.

1. Escolha uma destas opções:

   • Clique em Adicionar tarefa e selecione Preparação de dados.

   • Ao trabalhar com pipelines em pastas ou pastas do Git, clique com o botão direito do mouse na pasta do pipeline no painel Arquivos e selecione Criar preparação de dados.

   • Ao trabalhar com pipelines em pastas ou pastas do Git, clique no botão Adicionar tarefa no Visualizador de pipeline.

2. Opcional: no painel Detalhes da tarefa de preparação de dados, no menu Executar após, selecione uma tarefa para preceder a preparação de dados.

Criar uma nova preparação de dados

1. Clique no menu de seta ao lado de Editar preparação de dados e selecione No contexto ou Em uma nova guia.

2. Pesquise uma preparação de dados.

3. Selecione um nome de preparação de dados e pressione Enter.

4. Clique em Salvar.

5. Opcional: para renomear a preparação de dados, clique no nome dela no painel de pipeline, clique em Editar preparação de dados, clique no nome na parte de cima da tela e insira um novo nome.

Importar uma preparação de dados atual

1. Clique no menu suspenso de seta ao lado de Editar preparação de dados e clique em Importar uma cópia.

2. Pesquise uma preparação de dados para importar ou selecione uma no painel de pesquisa. Quando você importa uma preparação de dados, o original permanece inalterado porque o arquivo de origem da preparação de dados é copiado para o pipeline.

3. Para abrir a preparação de dados importados, clique em Editar.

4. Clique em Salvar.

Tabela

Visualizar

Este produto ou recurso está sujeito aos "Termos das Soluções 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.

Observação: para enviar feedback ou pedir suporte, entre em contato com [e-mail].

1. Escolha uma destas opções:

• Clique em Adicionar tarefa e selecione Tabela.

• Ao trabalhar com pipelines em pastas ou pastas do Git, clique com o botão direito do mouse na pasta do pipeline no painel Arquivos e selecione Criar tabela.

• Ao trabalhar com pipelines em pastas ou pastas do Git, clique no botão Adicionar tarefa no Visualizador de pipeline.

1. No painel Criar novo, selecione Tabela ou Tabela incremental.

2. Verifique o projeto padrão da tabela ou selecione um novo.

3. Verifique o conjunto de dados padrão da tabela ou selecione um novo.

4. Insira um nome para a tabela.

5. No painel de detalhes da tarefa da tabela, clique em Abrir para abrir a tarefa.

6. Configure a tarefa usando as configurações em Detalhes > Configuração ou no bloco config do editor de código da tabela.

Para mudanças de metadados, use a guia Configuração. Nela, você pode editar um valor específico no bloco config do editor de código, como uma string ou uma matriz, que é formatada como um objeto JavaScript. Usar essa guia ajuda a evitar erros de sintaxe e verificar se as configurações estão corretas.

Opcional: no menu Executar após, selecione uma tarefa para preceder sua tabela.

Também é possível definir os metadados da tarefa do pipeline no bloco config do editor. Para mais informações, consulte Como criar tabelas.

O editor valida seu código e mostra o status da validação.

Observação: quando você usa funções JavaScript como valores no bloco config, não é possível editar as funções JavaScript na guia Configuração.

1. Use a chave metadata para especificar informações do Knowledge Catalog (Visualização). Esse processo de enriquecimento é compatível com as seguintes estruturas de metadados:

• Visão geral: documentação e texto de resumo da entrada.
• Aspectos genéricos: detalhes semânticos, como sistema e tipo de tabela.

O exemplo de configuração a seguir mostra como adicionar uma visão geral e aspectos genéricos de metadados a uma configuração de tabela para o Knowledge Catalog:

       ```javascript
       config {
       type: "table",
       metadata: {
          overview: "This table provides standardized trip data.",
          extraProperties: {
             generic: {
                   system: "BigQuery",
                   type: "fact table"
             }
             }
       }
       }
       ```

1. Em Detalhes > Consultas compiladas, confira o SQL compilado do código SQLX.

2. Clique em Executar para executar o SQL no pipeline.

3. Em Resultados da consulta, inspecione a prévia dos dados.

Ver

Visualizar

Este produto ou recurso está sujeito aos "Termos das Soluções 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.

Observação: para enviar feedback ou pedir suporte, entre em contato com [e-mail].

1. Escolha uma destas opções:

   • Clique em Adicionar tarefa e selecione Visualizar.

   • Ao trabalhar com pipelines em pastas ou pastas do Git, clique com o botão direito do mouse na pasta do pipeline no painel Arquivos e selecione Criar visualização.

   • Ao trabalhar com pipelines em pastas ou pastas do Git, clique no botão Adicionar tarefa no Visualizador de pipeline.

2. No painel Criar novo, selecione Visualização ou Visualização materializada.

3. Verifique o projeto padrão da visualização ou selecione um novo.

4. Verifique o conjunto de dados padrão da visualização ou selecione um novo.

5. Insira um nome para a visualização.

6. No painel "Ver detalhes da tarefa", clique em Abrir para abrir a tarefa.

7. Configure a tarefa usando as configurações em Detalhes > Configuração ou no bloco config do editor de código da visualização.

Para mudanças de metadados, use a guia Configuração. Nela, você pode editar um valor específico no bloco config do editor de código, como uma string ou uma matriz, que é formatada como um objeto JavaScript. Usar essa guia ajuda a evitar erros de sintaxe e verificar se as configurações estão corretas.

Opcional: no menu Executar após, selecione uma tarefa para preceder sua visualização.

Também é possível definir os metadados da tarefa do pipeline no bloco config do editor. Para mais informações, consulte Como criar uma visualização com o Dataform Core.

O editor valida seu código e mostra o status da validação.

Observação: quando você usa funções JavaScript como valores no bloco config, não é possível editar as funções JavaScript na guia Configuração.

1. Use a chave metadata para especificar informações do Knowledge Catalog (Visualização). Esse processo de enriquecimento é compatível com as seguintes estruturas de metadados:

• Visão geral: documentação e texto de resumo da entrada.
• Aspectos genéricos: detalhes semânticos, como sistema e tipo de tabela.

O exemplo de configuração a seguir mostra como adicionar uma visão geral e aspectos genéricos de metadados a uma configuração de tabela para o Knowledge Catalog:

       ```javascript
       config {
       type: "view",
       metadata: {
          overview: "This view provides standardized trip data.",
          extraProperties: {
             generic: {
                   system: "BigQuery",
                   type: "view"
             }
             }
       }
       }
       ```

1. Em Detalhes > Consultas compiladas, confira o SQL compilado do código SQLX.

2. Clique em Executar para executar o SQL no pipeline.

3. Em Resultados da consulta, inspecione a prévia dos dados.

Editar uma tarefa de pipeline

Para editar uma tarefa de pipeline, siga estas etapas:

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, clique em Pipelines e selecione um pipeline.

4. Clique na tarefa selecionada.

5. Para mudar a tarefa anterior, no menu Executar após, selecione uma tarefa que antecede a sua.

6. Para editar o conteúdo da tarefa selecionada, clique em Editar.

7. Na nova guia que será aberta, edite o conteúdo da tarefa e salve as mudanças.

Excluir uma tarefa de pipeline

Para excluir uma tarefa de um pipeline, siga estas etapas:

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, clique em Pipelines e selecione um pipeline.

4. Clique na tarefa selecionada.

5. No painel Detalhes da tarefa, clique em Excluir Excluir.

Compartilhar um pipeline

Importante: se você aumentar a segurança definindo o campo enable_private_workspace (prévia) como true no método da API Dataform projects.locations.updateConfig, somente o criador do pipeline poderá ler e gravar código nele. Para mais informações, consulte Ativar espaços de trabalho particulares.

Observação: é possível compartilhar um pipeline, mas não uma tarefa dentro dele.

Para compartilhar um pipeline, siga estas etapas:

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, clique em Pipelines e selecione um pipeline.

4. Clique em Compartilhar e selecione Gerenciar permissões.

5. Clique em Adicionar usuário/grupo.

6. No campo Novos participantes, insira o nome de pelo menos um usuário ou grupo.

7. Em Atribuir papéis, selecione um papel.

8. Clique em Salvar.

Compartilhar um link para um pipeline

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, clique em Pipelines e selecione um pipeline.

4. Clique em Compartilhar e selecione Compartilhar link. O URL do seu pipeline é copiado para a área de transferência do computador.

Executar um pipeline

Ao executar um pipeline, você pode executar todas as tarefas nele, selecionar manualmente tarefas específicas ou executar tarefas com tags selecionadas.

Executar todas as tarefas em um pipeline

Para executar manualmente a versão atual de um pipeline, selecione uma das seguintes opções:

Console

Para executar todas as tarefas em um pipeline, faça o seguinte:

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, clique em Pipelines e selecione um pipeline.

4. Clique em  Executar > Executar todas as tarefas. Se você selecionou Executar com minhas credenciais de usuário para sua autenticação, autorize sua Conta do Google (Prévia).

5. Opcional: para inspecionar a execução, confira as execuções manuais anteriores.

API

Observação: a API Dataform não é compatível com credenciais de usuário para execuções de pipeline. É preciso selecionar uma conta de serviço na seção Autenticação das configurações do pipeline para usar a API.

Para executar um pipeline manualmente, compile o espaço de trabalho padrão e use o resultado da compilação para criar uma invocação de fluxo de trabalho.

1. Para criar um resultado de compilação para o espaço de trabalho padrão, use o método projects.locations.repositories.compilationResults.create.

   Execute a solicitação de API com as seguintes informações:

   curl -X POST \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
      -d '{
         "workspace": "projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID/workspaces/default"
      }' \
      "https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID/compilationResults"
   

   Substitua:

   • LOCATION: a região Google Cloud do seu repositório, por exemplo, us-central1. Para encontrar o local do repositório no console do Google Cloud , navegue até o painel Explorer, selecione o pipeline, abra a guia Configurações e clique em Abrir pipeline no Dataform. O local está no URL no formato /locations/LOCATION/.
   • PROJECT_ID: o identificador exclusivo do seu projetoGoogle Cloud .
   • REPOSITORY_ID: o identificador exclusivo do seu repositório do Dataform, por exemplo, my-secure-repo. Para encontrar o ID do repositório no console do Google Cloud , acesse o painel Explorer, selecione o pipeline, abra a guia Configurações e confira o campo ID do repositório do Dataform.

2. No corpo da resposta, localize o campo name e copie o valor dele, por exemplo, projects/my-project/locations/us-central1/repositories/my-repo/compilationResults/12345-67890.

3. Acione a execução do pipeline usando o método projects.locations.repositories.workflowInvocations.create.

   Execute a solicitação de API com as seguintes informações:

   curl -X POST \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
      -d '{
         "compilationResult": "COMPILATION_RESULT"
      }' \
      "https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID/workflowInvocations"
   

   Substitua:

   • COMPILATION_RESULT: o nome completo do recurso do resultado da compilação que você copiou na etapa anterior.
   • LOCATION: a região Google Cloud do seu repositório, por exemplo, us-central1.
   • PROJECT_ID: o identificador exclusivo do seu projetoGoogle Cloud .
   • REPOSITORY_ID: o identificador exclusivo do seu repositório do Dataform, por exemplo, my-secure-repo.

Executar tarefas selecionadas em um pipeline

Para executar as tarefas selecionadas em um pipeline, faça o seguinte:

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, clique em Pipelines e selecione um pipeline.

4. Clique em  Executar > Selecionar tarefas para executar.

5. No painel Executar, na seção Autenticação, autorize a execução com as credenciais de usuário da sua Conta do Google ou de uma conta de serviço.

   • Para usar as credenciais de usuário da sua Conta do Google (Prévia), selecione Executar com credenciais de usuário.

     Optional: In the **Extended access options** section, select the
     additional services that your pipeline requires:
     
     - **Knowledge Catalog**: Allows Google Cloud Knowledge Catalog metadata updates.
     - **Google Drive**: Allows read-only access to Google Drive files.
     - **Bigtable**: Allows read-only access to Google
       Bigtable data.
     

   • Para usar uma conta de serviço personalizada, selecione Executar com a conta de serviço selecionada e escolha uma conta de serviço personalizada.

     Observação: para ver as contas de serviço no menu, você precisa ter a permissão iam.serviceAccounts.list no nível do projeto, disponível no papel "Visualizar contas de serviço" (roles/iam.serviceAccountViewer). Se você não tiver essa permissão, selecione a conta de serviço clicando em Inserir manualmente e inserindo o ID da conta.

     Se você precisar criar uma conta de serviço, clique em Nova conta de serviço.

6. Verifique se a opção Seleção de tarefas está marcada.

7. No menu Selecionar tarefas para executar, pesquise tarefas específicas e selecione as que você quer executar.

   A tabela Tarefas lista as tarefas selecionadas. Clique no nome de uma tarefa para abrir diretamente no editor de SQL.

8. Opcional: configure as seguintes opções de execução:

   • Incluir dependências: selecione essa opção para executar as tarefas selecionadas e as dependências delas.
   • Incluir dependentes: selecione essa opção para executar as tarefas selecionadas e seus dependentes transitivos downstream.
   • Executar com atualização completa: selecione essa opção para recriar todas as tabelas do zero.
   • Executar como job interativo com alta prioridade (padrão): selecione essa opção para definir a prioridade do job de consulta do BigQuery. Por padrão, o BigQuery executa consultas como jobs de consulta interativos, que são projetados para começar a ser executados o mais rápido possível. Desmarcar essa opção executa as consultas como jobs de consulta em lote, que têm prioridade mais baixa.

9. Clique em Executar. Se você selecionou Executar com credenciais do usuário como método de autenticação, autorize sua Conta do Google (Prévia).

10. Opcional: para inspecionar a execução, confira as execuções manuais anteriores.

Executar tarefas com tags selecionadas em um pipeline

Para executar tarefas com tags selecionadas em um pipeline, faça o seguinte:

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, clique em Pipelines e selecione um pipeline.

4. Clique em  Executar > Executar por tag e faça uma destas ações:

   • Clique na tag que você quer executar.
   • Clique em  Selecionar tags para executar.

5. No painel Executar, na seção Autenticação, autorize a execução com as credenciais de usuário da sua Conta do Google ou de uma conta de serviço.

   • Para usar as credenciais de usuário da sua Conta do Google (Prévia), selecione Executar com credenciais de usuário.

     Optional: In the **Extended access options** section, select the
     additional services that your pipeline requires:
     
     - **Knowledge Catalog**: Allows Google Cloud Knowledge Catalog metadata updates.
     - **Google Drive**: Allows read-only access to Google Drive files.
     - **Bigtable**: Allows read-only access to Google
       Bigtable data.
     

   • Para usar uma conta de serviço personalizada, selecione Executar com a conta de serviço selecionada e escolha uma conta de serviço personalizada.

     Observação: para ver as contas de serviço no menu, você precisa ter a permissão iam.serviceAccounts.list no nível do projeto, disponível no papel "Visualizar contas de serviço" (roles/iam.serviceAccountViewer). Se você não tiver essa permissão, selecione a conta de serviço clicando em Inserir manualmente e inserindo o ID da conta.

     Se você precisar criar uma conta de serviço, clique em Nova conta de serviço.

6. Verifique se a opção Seleção de tags está marcada.

7. No menu Selecionar tags para executar, pesquise tags específicas e selecione as que você quer executar.

   A tabela Tarefas lista as tarefas selecionadas. Clique no nome de uma tarefa para abrir diretamente no editor de SQL.

8. Opcional: configure as seguintes opções de execução:

   • Incluir dependências: selecione essa opção para executar as tarefas selecionadas e as dependências delas.
   • Incluir dependentes: selecione essa opção para executar as tarefas selecionadas e seus dependentes transitivos downstream.
   • Executar com atualização completa: selecione essa opção para recriar todas as tabelas do zero.
   • Executar como job interativo com alta prioridade (padrão): selecione essa opção para definir a prioridade do job de consulta do BigQuery. Por padrão, o BigQuery executa consultas como jobs de consulta interativos, que são projetados para começar a ser executados o mais rápido possível. Desmarcar essa opção executa as consultas como jobs de consulta em lote, que têm prioridade mais baixa.

9. Clique em Executar. Se você selecionou Executar com credenciais do usuário como método de autenticação, autorize sua Conta do Google (Prévia).

10. Opcional: para inspecionar a execução, confira as execuções manuais anteriores.

Autorizar sua Conta do Google

Visualizar

Este produto ou recurso está sujeito aos "Termos das Soluções 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.

Observação: para solicitar suporte ou enviar feedback sobre esse recurso, entre em contato com [e-mail].

Para autenticar o recurso com suas credenciais de usuário da Conta do Google, conceda permissão manualmente para que os pipelines do BigQuery recebam o token de acesso da sua Conta do Google e acessem os dados de origem em seu nome. É possível conceder aprovação manual com a interface da caixa de diálogo do OAuth. Se você selecionar qualquer uma das Opções de acesso estendido, será necessário conceder acesso a esses serviços, como o Google Drive ou o Knowledge Catalog.

Observação: as políticas de Acesso Baseado no Contexto (CAA), incluindo as baseadas em IP, geolocalização e conformidade do dispositivo, não são compatíveis ao executar ou programar pipelines do BigQuery com credenciais de usuário para uma Conta do Google, porque as solicitações de token têm origem na infraestrutura do Google. As políticas de CAA bloqueiam essas execuções, a menos que o ID do cliente OAuth do Dataform seja exento das políticas.

Você só precisa conceder permissão aos pipelines do BigQuery uma vez.

Para revogar a permissão concedida, siga estas etapas:

1. Acesse a página da sua Conta do Google.
2. Clique em Pipelines do BigQuery.
3. Clique em Remover acesso.

Aviso: a revogação de permissões de acesso impede que execuções de pipeline futuras sejam realizadas pela Conta do Google em todas as regiões.

Se o pipeline tiver um notebook, você também precisará conceder manualmente permissão para que o Colab Enterprise receba o token de acesso da sua Conta do Google e acesse os dados de origem em seu nome. Você só precisa conceder permissão uma vez. É possível revogar essa permissão na página da Conta do Google.

A seguir

• Saiba mais sobre os pipelines do BigQuery.
• Saiba como gerenciar pipelines.
• Saiba como programar pipelines.
• Saiba como gerenciar código com repositórios Git do BigQuery Studio.
• Saiba como organizar recursos de código com pastas.