Planejar uma migração com linhagem de migração

Visualizar

Este 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 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 receber suporte ou enviar feedback sobre esse recurso, entre em contato com [e-mail].

É possível usar o serviço de linhagem de migração para visualizar o fluxo de dados e as conexões no banco de dados de origem ao planejar uma migração de data warehouse do BigQuery.

Ao criar uma linhagem de migração, o serviço de linhagem fornece um gráfico que mostra como os dados se movem pelo sistema de origem e como cada tabela ou visualização no sistema de origem está conectada, conforme mostrado no diagrama a seguir:

O serviço de linhagem de migração é compatível com os seguintes dialetos SQL:

• SQL do Amazon Redshift
• SQL do Snowflake
• SQL do Teradata
• GoogleSQL (BigQuery)

Limitações

O serviço de linhagem processa os primeiros 5 GB dos registros mais antigos do seu banco de dados de origem.

Locais suportados

O serviço de linhagem de migração está disponível em locais selecionados. Para mais informações, consulte Locais do serviço de linhagem e tradutor de SQL do BigQuery.

Permissões necessárias

Para receber as permissões necessárias para usar o serviço de linhagem de migração, peça ao administrador para conceder a você o papel do IAM de Editor do MigrationWorkflow (roles/bigquerymigration.editor) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém as permissões necessárias para usar o serviço de linhagem de migração. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para usar o serviço de linhagem de migração:

• bigquerymigration.workflows.create
• bigquerymigration.workflows.get
• bigquerymigration.lineageDbs.query

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

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

Criar uma linhagem de migração

Para criar uma linhagem de migração, primeiro execute a ferramenta dwh-migration-dumper para gerar arquivos de registro SQL de entrada de origem que você envia para o Cloud Storage. Depois de fazer upload dos arquivos de entrada para o Cloud Storage, é possível gerar a linhagem de migração com o console Google Cloud ou a API BigQuery Migration.

Execute a ferramenta dwh-migration-dumper

Selecione uma das seguintes opções:

Amazon Redshift

Para criar e visualizar uma linhagem de migração em um banco de dados do Amazon Redshift, faça o seguinte:

1. Execute a ferramenta dwh-migration-dumper para gerar um dump dos arquivos do sistema de origem.
2. Faça upload dos registros de consulta para o Cloud Storage.

Snowflake

Para criar e visualizar uma linhagem de migração em um banco de dados do Snowflake, faça o seguinte:

1. Execute a ferramenta dwh-migration-dumper para gerar um dump dos arquivos do sistema de origem.
2. Faça upload dos registros de consulta para o Cloud Storage.

Teradata

Para criar e visualizar uma linhagem de migração em um banco de dados do Teradata, faça o seguinte:

1. Execute a ferramenta dwh-migration-dumper para gerar um dump dos arquivos do sistema de origem.
2. Faça upload dos registros de consulta para o Cloud Storage.

BigQuery

Para criar e visualizar uma linhagem de migração em um banco de dados do BigQuery, faça o seguinte:

1. Conceda à conta ou conta de serviço os seguintes papéis:
   • Leitor de metadados do BigQuery (roles/bigquery.metadataViewer)
   • Leitor do Data Catalog (roles/datacatalog.viewer)
2. Instale a ferramenta dwh-migration-dumper.

3. Para gerar metadados e registros de consulta, execute a ferramenta dwh-migration-dumper. Esses metadados e registros de consulta estão contidos em um ou mais arquivos ZIP.

   dwh-migration-dumper --connector bigquery
   
   dwh-migration-dumper --connector bigquery-logs

4. Faça upload dos arquivos ZIP para um bucket do Cloud Storage. Para mais informações sobre como criar buckets e fazer upload de arquivos para o Cloud Storage, consulte Criar um bucket e Fazer upload de objetos de um sistema de arquivos.

Gerar a linhagem de migração

Depois de fazer upload dos arquivos ZIP que contêm os metadados e os registros de consulta para o Cloud Storage, você pode gerar a linhagem de migração. Selecione uma das seguintes opções:

Console

1. Acesse a página Seus serviços de migração.

   Acessar Seus serviços de migração

2. Em Traduzir SQL, clique em Traduzir > Tradução em lote.

3. Em Configuração de tradução, insira o seguinte:

   1. Em Nome de exibição, especifique um nome para o job de linhagem. O nome pode conter letras, números ou sublinhados.
   2. Em Local de processamento, selecione o local em que você quer que o job de linhagem seja executado.
   3. Em Dialeto de origem, selecione o dialeto SQL de origem.
   4. Em Dialeto de destino, selecione GoogleSQL.

4. Clique em Próxima.

5. Em Detalhes do local do arquivo, faça o seguinte:

   1. Em Local do diretório de saída, especifique o caminho para um bucket do Cloud Storage para salvar os arquivos de saída da tradução. É possível digitar o caminho no formato bucket_name/folder_name/ ou clicar em Procurar.
   2. Em Local do diretório de entrada, especifique o caminho da pasta do Cloud Storage que contém os arquivos ZIP de registros enviados por upload anteriormente. É possível digitar o caminho no formato bucket_name/folder_name/ ou clicar em Procurar. Você também pode nomear o subdiretório dos arquivos de saída no campo Nome do subdiretório de saída.
   3. Para adicionar mais arquivos de entrada, clique em Adicionar um local de diretório de entrada.

6. Clique em Próxima.

7. Marque a caixa de seleção Linhagem de logs de consulta.

8. Clique em Criar.

O job de linhagem está em execução. O job pode levar várias horas para ser concluído, dependendo do tamanho da entrada. Depois que o job for concluído, a ferramenta vai fornecer um link para a linhagem de migração gerada.

API

Para criar um job de linhagem, execute o seguinte comando curl:

  curl -d "{
    \"tasks\": {
      \"TASK_NAME\": {
        \"type\": \"Experimental_Lineage\",
        \"translation_details\": {
          \"target_base_uri\": \"BUCKET_PATH\",
          \"source_target_mapping\": {
            \"source_spec\": {
              \"base_uri\": \"BUCKET_PATH\"
            }
          },
          \"target_types\": \"LINEAGE\"
        }
      }
    }
  }
  " \
    -H "Content-Type:application/json" \
    -H "Authorization: Bearer TOKEN" -X POST https://bigquerymigration.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/workflows

Substitua:

• TASK_NAME: um nome para identificar esse job de linhagem.
• BUCKET_PATH: o caminho para o bucket do Cloud Storage que contém seus arquivos ZIP de entrada.
• PROJECT_ID: o ID do projeto do Google Cloud projeto.
• LOCATION: um local de processamento. Esse valor precisa ser eu ou us.

Essa chamada retorna uma mensagem semelhante a esta:

  {
    "name": "projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID",
    "tasks": {
      "task_name": { /*...*/ }
    },
    "state": "RUNNING"
  }

O job de linhagem está em execução. O job pode levar várias horas para ser concluído, dependendo do tamanho da entrada. Para verificar o status do job de linhagem, execute o seguinte comando curl com o ID do fluxo de trabalho:

  curl \
  -H "Content-Type:application/json" \
  -H "Authorization:Bearer " -X GET https://bigquerymigration.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID

Depois que o job for concluído, a ferramenta vai fornecer um link para a visualização da linhagem gerada.

Abrir a linhagem de migração

Depois de gerar uma linhagem de migração, abra-a usando uma das seguintes opções:

Console

1. Acesse a página Seus serviços de migração.

   Acessar Seus serviços de migração

2. Em Traduzir SQL, clique em Ver recentes.

3. Na página Traduções de SQL, clique no nome do job para selecionar o job de linhagem completo. Os jobs de linhagem têm o valor de saída Lineage.

4. Na página Detalhes da tradução, clique em Linhagem de dados.

API

Para abrir uma linhagem de migração concluída, execute o seguinte comando curl com a API BigQuery Migration:

  curl \
  -H "Content-Type:application/json" \
  -H "Authorization:Bearer " -X GET https://bigquerymigration.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID

Substitua:

• PROJECT_ID: o ID do projeto do Google Cloud projeto.
• LOCATION: um local de processamento. Esse valor precisa ser eu ou us.
• WORKFLOW_ID: o ID do fluxo de trabalho da linhagem gerada.

Navegue até o link incluído no campo taskResult.translationTaskResult.consoleUri da mensagem de saída.

Trabalhar com linhagem de migração

As seções a seguir descrevem maneiras de usar a linhagem de migração para trabalhar com seus dados de origem e banco de dados.

Entender os termos de linhagem de migração

Os termos a seguir são usados em uma linhagem de migração:

Termos	Descrição
Scripts	Scripts SQL e outros programas visíveis nos registros do banco de dados ingeridos durante a criação da linhagem. Os scripts são compostos de instruções, que geralmente são instruções SQL únicas.
Nós	Os vértices do gráfico de linhagem. Elas consistem em tabelas e colunas.
Tabelas	Também chamadas de relações, incluindo tabelas comuns, visualizações, arquivos estruturados e outros recursos semelhantes a tabelas.
Colunas	Também chamados de atributos, incluindo colunas de tabela, projeções de visualização, pseudocolunas, campos semelhantes a colunas em arquivos e outros recursos, além de subcolunas, como campos de struct.
Bordas	Conexões entre nós de linhagem que indicam interações devido a um pipeline que executa um script que lê ou grava esses nós. As arestas são anotadas com carimbos de data/hora, predicados e outros metadados de quando foram derivadas. Um nó adjacente a outro com uma aresta é chamado de conexão direta. Um caminho de arestas entre dois nós é chamado de conexão indireta.
Arestas de linhagem	Arestas direcionais que indicam que o nó de origem foi incluído em uma cláusula como FROM, WHERE ou GROUP BY que influenciou os dados do nó de destino.
Usuários e pipelines	Rótulos de metadados fornecidos pelo banco de dados de origem sobre quem e o que executou scripts. Eles não têm um significado inerente para o mecanismo de linhagem, mas são usados para agrupar scripts por origem.

As seções a seguir descrevem as diferentes páginas em uma linhagem de migração.

Revise a página de destino

A página de destino da linhagem de migração mostra o ID do job de linhagem, um campo de pesquisa para localizar objetos de linhagem por nome e uma lista de sugestões destacando alguns objetos de linhagem que podem ser interessantes. A página também inclui as contagens totais de tabelas, pipelines e usuários em toda a linhagem de migração.

Para navegar até uma tabela, visualização ou coluna específica, pesquise o objeto no campo de pesquisa ou clique em um dos objetos sugeridos na página de destino.

Observação: ao analisar a página de destino, verifique se a contagem total de objetos corresponde ao número de objetos no banco de dados de origem. Se o número de tabelas for menor do que o esperado, isso pode indicar que houve um erro na geração da visualização de linhagem. Se for esse o caso, confirme se você usou o arquivo de registro correto e se os registros estão abaixo do limite de 5 GB. Em seguida, gere a linhagem de migração novamente.

Revisar a página do nó

Para analisar os nós na linhagem de migração, clique em uma das seguintes guias.

Guia "Fluxo de dados"

A guia Fluxo de dados mostra uma representação visual de uma parte do gráfico de linhagem. Ela é a página padrão quando você visualiza uma tabela ou coluna pela primeira vez no serviço de linhagem. O gráfico mostra como os dados se movem pelo sistema de origem. Os nós nesse gráfico representam tabelas ou visualizações, enquanto as arestas entre os nós representam o fluxo de dados dos nós à esquerda para os nós à direita.

Cada tabela no gráfico Fluxo de dados mostra o nome não qualificado. Para conferir o nome totalmente qualificado de uma tabela com o prefixo do banco de dados e do esquema, mantenha o ponteiro sobre o nó para mostrar a dica. Cada tabela indica o esquema, conforme mostrado pela barra vertical no nó. Todos os esquemas na linhagem são classificados em ordem alfabética e recebem uma cor. Assim, as tabelas no mesmo esquema têm as mesmas barras coloridas, e as tabelas em esquemas com nomes semelhantes têm barras coloridas semelhantes.

Cada nó mostra um ícone que indica as propriedades dele:

• monitor: uma visualização, não uma tabela.
• cached: uma tabela que é sempre totalmente atualizada (truncada e reescrita). Clique no ícone para ver os scripts adjacentes a essa tabela.
• Em cache: uma tabela que nem sempre é totalmente atualizada (truncada e depois reescrita). Clique no ícone para ver os scripts ao lado da tabela.
• timer: uma tabela de curta duração. Mantenha o ponteiro sobre o ícone para ver a duração da existência da tabela.
• Snowflake: uma tabela que foi gravada pela última vez há mais de sete dias, o que sugere uma tabela com dados estáticos ou gravados com pouca frequência.

Para revisar os objetos no gráfico Fluxo de dados, faça o seguinte:

• Para ver uma lista de colunas da tabela, clique em uma tabela. Essa visualização inclui o nome de cada coluna, bem como o tipo de dados, determinado por um dump de metadados fornecido ou deduzido do SQL visto nos registros de consultas.
• Para ver o gráfico de linhagem no nível da coluna, clique em uma coluna. No gráfico de linhagem no nível da coluna, as arestas representam fluxos de dados que afetam a coluna de destino.

• Para conferir detalhes sobre uma aresta, clique nela no gráfico. Essa visualização inclui links para os scripts SQL que induziram a aresta.

  Uma aresta é gerada de um nó de origem para um nó de destino quando uma instrução SQL faz referência ao nó de origem enquanto a instrução está calculando dados que são inseridos no nó de destino. Normalmente, isso envolve a transferência de dados da origem para o destino, mas a guia Fluxo de dados também mostra uma aresta quando o nó de origem é usado em uma cláusula WHERE ou GROUP BY que afeta o destino. Para filtrar apenas transferências de dados, clique no botão Mostrar arestas não relacionadas a dados na barra de ferramentas.

Observação: para ajudar na navegação em linhagens de migração grandes, é possível refocar o gráfico em um nó clicando no nome totalmente qualificado dele na barra lateral ou na dica de ferramenta do nó.

Guia "Conexões"

A guia Conexões de um nó de linhagem mostra uma lista de nós próximos no gráfico de linhagem. Por padrão, os nós conectados são classificados pela distância do caminho mais curto do nó atual. Os nós que exigem menos arestas para chegar ao nó atual são listados primeiro. É possível mudar a classificação com a opção Ordenar.

Por padrão, a lista de conexões inclui nós upstream (produtor) e downstream (consumidor) do nó atual. É possível mudar esse filtro com o controle Tipo. Na coluna Distância, os nós upstream do nó atual são mostrados com uma seta apontando para cima e a distância do caminho mais curto para trás até esse nó do nó atual. Da mesma forma, os nós downstream do nó atual são mostrados com uma seta apontando para baixo e a distância do caminho mais curto para frente até esse nó do nó atual. Um nó pode ser upstream e downstream do nó atual se fizer parte de um ciclo.

Para fazer o download de um arquivo com todos os nós mostrados, clique em baixar CSV

Guia Usuários

A guia Usuários de um nó mostra os usuários que executaram scripts que leram ou gravaram o nó ou nós upstream ou downstream dele. Por padrão, o usuário que realizou mais ações separadas é listado primeiro. É possível mudar a classificação com a opção Ordenar.

Para fazer o download de um arquivo com todos os usuários mostrados, clique em Fazer o download do CSV.

Guia "Pipelines"

A guia Pipelines de um nó mostra os pipelines que executaram scripts que leram ou gravaram o nó ou nós upstream ou downstream dele. Por padrão, o pipeline que realizou mais ações separadas é listado primeiro. É possível mudar a ordem com a opção Ordenar.

Para fazer o download de um arquivo com todos os pipelines mostrados, clique em Fazer o download do CSV.

Guia "Código"

A guia Código de um nó mostra todos os scripts SQL encontrados nos arquivos de entrada que leram ou gravaram dados nesse nó. As menções ao nó são destacadas no texto SQL. Clique em um script para abrir o texto completo. É possível mudar as configurações de filtro para filtrar a lista de scripts mostrados.

Para baixar um arquivo com todos os scripts mostrados, clique em Fazer o download do CSV.

Revisar a página de borda

Para analisar as arestas dos nós no gráfico de linhagem, clique em uma das seguintes guias.

Guia "Detalhes"

A guia Detalhes de uma aresta mostra predicados e categorias que descrevem as operações realizadas por scripts que induziram a aresta.

Os predicados são representados como códigos de três partes separados por hífens. A primeira parte é r, indicando que a origem da aresta é uma relação, ou a, indicando que a origem é um atributo. A segunda parte é uma das seguintes abreviações que indica como o nó de origem influenciou os dados no nó de destino:

• has: a relação de origem contém o atributo de destino.
• dat: a origem copia ou transfere dados para o destino.
• res: a origem filtra ou restringe a cardinalidade do destino em uma cláusula como WHERE, HAVING ou JOIN ON.
• grp: a origem é usada em uma cláusula GROUP BY que afeta o destino.

A terceira parte também é r ou a, indicando se o destino da aresta é uma relação ou um atributo.

As categorias de borda podem incluir o seguinte:

• dat predicates:
  • AGGREGATE: a origem foi usada em um cálculo agregado que gravou o destino.
  • EXACT_COPY: os dados da origem foram copiados por completo para o destino.
  • FUNCTION: a origem foi usada para calcular o destino.
  • IDENTITY_COPY: o destino não foi calculado. O destino era uma cópia literal da origem, sem transmissões ou conversões.
  • PARTITION_PROMOTION: o destino contém dados da origem como resultado da promoção de uma partição da origem para o destino.
  • WEAK_COPY: os dados da origem foram copiados, pelo menos parcialmente, para o destino.
• res predicates:
  • FILTER: a origem foi usada em uma comparação que gravou o destino.
  • KEY: os dados da origem foram usados como chave em uma comparação de junção que gravou o destino.
• grp predicates:
  • GROUP: os dados da origem foram usados como uma chave em uma cláusula GROUP BY, o que afeta o destino.

Guia "Código"

A guia Código de uma aresta mostra os scripts SQL que a induziram. Os nós de origem e destino da aresta são destacados quando mencionados no texto SQL.

A seguir

• Execute uma avaliação de migração para avaliar a viabilidade e os possíveis benefícios de migrar seu data warehouse para o BigQuery.
• Use o serviço de tradução de SQL, como o tradutor de SQL interativo, a API Translation e o tradutor de SQL em lote para automatizar a conversão das suas consultas SQL em GoogleSQL, incluindo a personalização de SQL aprimorada com o Gemini.