Importar arquivos Parquet no armazenamento para o catálogo de tempo de execução do Lakehouse usando o Dataflow

É possível usar um blueprint do criador de jobs do Dataflow para adicionar arquivos Apache Parquet do armazenamento baseado em nuvem (Cloud Storage, Amazon S3 ou Armazenamento de Blobs do Azure) a uma tabela do Apache Iceberg no Lakehouse sem fronteiras.

Esse processo usa a transformação IcebergAddFiles. Se os arquivos Parquet estiverem no Cloud Storage, essa transformação vai registrar os arquivos no Lakehouse sem mover ou reescrever os dados subjacentes. Se os arquivos estiverem em um sistema de armazenamento externo, como o Amazon S3, eles serão copiados para o Cloud Storage para uma consulta mais rápida pelo Lakehouse e depois registrados.

Use os detalhes de conexão a seguir para adicionar arquivos Parquet do armazenamento baseado na nuvem a uma tabela do Apache Iceberg no Lakehouse.

Antes de começar

  1. Ative as APIs Dataflow, BigQuery e Lakehouse.

  2. Para receber as permissões necessárias para criar os recursos, peça ao administrador para conceder a você os papéis necessários do Identity and Access Management (IAM) no projeto.

  3. Crie um catálogo, um namespace e uma tabela do Lakehouse para importar dados.

  4. Crie um bucket de armazenamento baseado na nuvem (Cloud Storage, Amazon S3 ou Azure Blob Storage) e faça upload dos arquivos Parquet para o bucket.

  5. Se o bucket de armazenamento baseado na nuvem que você está usando não for o Cloud Storage do Google, crie um bucket do Cloud Storage para armazenar os registros de erros do job.

Suporte e limitações

A importação de arquivos Parquet no armazenamento baseado em nuvem para o Lakehouse usando o Dataflow tem as seguintes limitações:

  • Os dados de origem precisam estar no formato Apache Parquet e armazenados no Cloud Storage, no Amazon S3 ou no Armazenamento de Blobs do Azure.
  • Esse recurso só é compatível com pipelines em lote.

Importar arquivos Parquet para o Lakehouse

Siga estas etapas para importar arquivos Parquet do armazenamento baseado na nuvem para uma tabela do Iceberg no Lakehouse usando a UI do criador de jobs do Dataflow.

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

    Acessar o Lakehouse

  2. Selecione o catálogo, o namespace e a tabela para importar os dados.

  3. Na página Detalhes da tabela, clique em Importar tabela e selecione De arquivos Apache Parquet (lote).

    A página Criador de jobs do Dataflow é aberta.

  4. Na seção Origens:

    1. Abra a entrada de origem CreateGlobalInput que já foi criada.

    2. Na seção do editor Configuração de origem YAML, insira um ou mais caminhos para os arquivos Parquet na sequência elements.

      Para melhorar a eficiência da importação, especifique vários conjuntos de arquivos (globs) ao registrar um grande número de arquivos. Exemplo:

      reshuffle: true
      elements:
        -   gs://BUCKET_NAME/restaurant-data/2023/*.parquet
        -   gs://BUCKET_NAME/restaurant-data/2024/*.parquet
      
    3. Clique em Concluído.

  5. Na seção Transformações:

    1. Clique na seção de transformação IcebergAddFiles para abri-la.

    2. No campo Tabela do Iceberg, insira o namespace e o nome da tabela. Por exemplo: NAMESPACE .TABLE_NAME .

    3. Opcional: no campo Tamanho do arquivo de manifesto, insira o número de arquivos de dados a serem incluídos em cada arquivo de manifesto. O padrão é 10.000.

    4. Em Propriedades do catálogo, configure os seguintes itens:

      1. warehouse: o local do Cloud Storage do seu catálogo. Por exemplo, gs://CATALOG_PATH.

      2. header.x-goog-user-project: o ID do projeto do Google Cloud : PROJECT_ID.

    5. Opcional: para permitir que o job atualize o esquema da tabela de destino para corresponder aos arquivos Parquet, selecione uma ou mais opções na lista Evolução do esquema. Para mais informações, consulte Configurar a evolução do esquema.

    6. Clique em Concluído.

    7. Se você estiver migrando do Amazon S3 ou do Armazenamento de Blobs do Azure, será necessário fornecer outras configurações para copiar arquivos Parquet para o Cloud Storage. Isso não será necessário se os arquivos já estiverem no Cloud Storage.

      1. Clique na seção de transformação CopyFilesToGCS para abrir.

      2. Defina o valor do parâmetro de configuração gcs_file_path para fornecer o bucket totalmente qualificado do Cloud Storage para onde os arquivos temporários serão copiados. Recomendamos usar o mesmo bucket do Cloud Storage usado pelo data warehouse do Lakehouse.

      3. Clique em Concluído.

      4. Clique na seção Opções do Dataflow para abri-la.

      5. Se os arquivos Parquet estiverem no Amazon S3, clique em adicionar outras opções de pipeline para fornecer opções de pipeline relacionadas ao S3 do Apache Beam. Por exemplo, s3_region_name, s3_access_key_id, s3_secret_access_key e os valores correspondentes.

      6. Se os arquivos Parquet estiverem no Armazenamento de Blobs do Azure, clique em Adicionar outras opções de pipeline para fornecer opções de pipeline do Apache Beam relacionadas ao Azure. Por exemplo, azure_connection_string, blob_service_endpoint, azure_managed_identity_client_id e os valores correspondentes.

  6. Na seção Coletores:

    1. Clique no coletor Write results para abri-lo.

    2. No campo Local do JSON, especifique o local do Cloud Storage e o nome do arquivo para gravar os resultados de erro. Exemplo:

      gs://BUCKET_NAME/errors/errors.json
      
    3. Clique em Concluído.

  7. Na seção Opções do Dataflow, clique em Executar job.

Se você precisar personalizar ainda mais o pipeline do Dataflow usado para registrar arquivos Parquet, use o formulário do criador de jobs ou o editor YAML.

Configurar a evolução do esquema

Por padrão, a transformação IcebergAddFiles não altera o esquema da tabela de destino. Usando um job em lote, é possível ativar a evolução do esquema para inspecionar o rodapé de cada arquivo Parquet e atualizar o esquema da tabela antes de registrar os arquivos. Se a tabela de destino não existir, o job vai criar a tabela com base nos esquemas combinados dos arquivos Parquet.

Para ativar a evolução de esquema na seção de transformação IcebergAddFiles, selecione uma ou mais opções na lista Evolução de esquema:

  • Adicionar colunas: adiciona colunas de um arquivo Parquet que não estão na tabela como colunas opcionais.
  • Tornar as colunas opcionais: muda uma coluna de tabela obrigatória para opcional quando um arquivo omite a coluna ou pode conter valores nulos nela.
  • Ampliar tipos de coluna: amplia o tipo de dados de uma coluna, como de int para long.

Se algum arquivo de dados tiver um esquema incompatível, o pipeline vai falhar sem confirmar as mudanças de esquema ou registrar arquivos. Por exemplo, um esquema será incompatível se exigir uma alteração que você não selecionou ou se entrar em conflito com a tabela ou outro arquivo.

Ao selecionar pelo menos uma opção de Evolução do esquema, também é possível especificar colunas que precisam estar sempre presentes e não nulas, mesmo quando a opção Tornar colunas opcionais está selecionada. Expanda Colunas obrigatórias, clique em Adicionar item e insira um valor no campo Nome da coluna. Para campos aninhados, separe os nomes com pontos, como address.city. Os arquivos que omitem uma coluna obrigatória ou contêm valores nulos nela são enviados para a saída de erro.

Examinar a saída do job

Depois que o job for concluído, verifique se os dados foram registrados na tabela do Iceberg consultando-os no BigQuery.

  1. Na lista de jobs do Dataflow, verifique se o status do job é Concluído.

    Acessar "Jobs"

  2. Se o job falhar ou tiver erros, verifique o arquivo de registro de erros JSON no Cloud Storage para mais detalhes.

    Acessar buckets

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

    Acessar o BigQuery

  4. No editor de consultas, insira uma consulta SQL para inspecionar a tabela. É possível usar a convenção PROJECT_ID.CATALOG.NAMESPACE.TABLE_NAME para consultar.

    SELECT * FROM `PROJECT_ID.CATALOG.NAMESPACE.TABLE_NAME` LIMIT 10
    
  5. Clique em Executar.

  6. Revise os Resultados da consulta para garantir que os dados foram processados corretamente.

A seguir