Introdução às transferências do Cloud Storage

Com o serviço de transferência de dados do BigQuery para o Cloud Storage, é possível programar carregamentos de dados recorrentes de buckets do Cloud Storage para o BigQuery. O caminho para os dados armazenados no Cloud Storage e a tabela de destino pode ser parametrizado, o que permite carregar dados de buckets do Cloud Storage organizados por data.

Formatos de arquivo compatíveis

Atualmente, o serviço de transferência de dados do BigQuery aceita o carregamento de dados do Cloud Storage em um dos formatos a seguir:

  • Valores separados por vírgula (CSV, na sigla em inglês)
  • JSON (delimitado por nova linha)
  • Avro
  • Parquet
  • ORC

Tipos de compactação compatíveis

O serviço de transferência de dados do BigQuery para Cloud Storage é compatível com o carregamento de dados compactados. Os tipos de compactação aceitos por esse serviço são os mesmos compatíveis com os jobs de carregamento do BigQuery. Para mais informações, consulte Como carregar dados compactados e descompactados.

Ingestão de dados para transferências do Cloud Storage

É possível especificar como os dados são carregados no BigQuery selecionando uma Preferência de gravação na configuração da transferência ao configurar uma transferência do Cloud Storage.

Há dois tipos de preferências de gravação disponíveis, transferências incrementais e transferências truncadas.

Transferências incrementais

Uma configuração de transferência com uma preferência de gravação APPEND ou WRITE_APPEND, também chamada de transferência incremental, anexa novos dados incrementalmente desde a etapa anterior da transferência para uma tabela de destino do BigQuery. Quando uma configuração de transferência é executada com uma preferência de gravação APPEND, o serviço de transferência de dados do BigQuery filtra os arquivos que foram modificados desde a execução da transferência anterior. Para determinar quando um arquivo é modificado, o serviço de transferência de dados do BigQuery procura uma propriedade de "horário da última modificação" nos metadados do arquivo. Por exemplo, o serviço de transferência de dados do BigQuery analisa a propriedade de carimbo de data/hora updated em um arquivo do Cloud Storage. Se o serviço de transferência de dados do BigQuery encontrar arquivos com um "horário da última modificação" que tenham ocorrido após o carimbo de data/hora da última transferência bem-sucedida, o serviço transferirá esses arquivos em uma transferência incremental.

Para demonstrar como as transferências incrementais funcionam, considere o exemplo de transferência do Cloud Storage a seguir. Um usuário cria um arquivo chamado file_1 em um bucket do Cloud Storage no momento 2023-07-01T00:00Z. O carimbo de data/hora updated para file_1 é o horário em que o arquivo foi criado. Em seguida, o usuário cria uma transferência incremental no bucket do Cloud Storage, programada para ser executada uma vez por dia às 3h, a partir de 01-07-2023.

  • Em 2023-07-01T03:00Z, a primeira execução de transferência é iniciada. Como esta é a primeira execução de transferência dessa configuração, o serviço de transferência de dados do BigQuery tenta carregar todos os arquivos que correspondem ao URI de origem na tabela de destino do BigQuery. A execução da transferência é bem-sucedida e o serviço de transferência de dados do BigQuery carrega file_1 na tabela de destino do BigQuery.
  • A próxima execução de transferência, em 2023-07-02T03:00Z, não detecta arquivos em que a propriedade de carimbo de data/hora updated é maior que a última execução de transferência bem-sucedida (2023-07-01T03:00Z). A execução da transferência é bem-sucedida sem carregar nenhum dado adicional na tabela de destino do BigQuery.

O exemplo anterior mostra como o serviço de transferência de dados do BigQuery analisa a propriedade de carimbo de data/hora updated do arquivo de origem para determinar se alguma alteração foi feita nos arquivos de origem e transferi-las, caso alguma tenha sido detectada.

Seguindo o mesmo exemplo, suponha que o usuário crie outro arquivo no bucket do Cloud Storage no momento 2023-07-03T00:00Z, chamado file_2. O carimbo de data/hora updated para file_2 é o horário em que o arquivo foi criado.

  • A próxima execução de transferência, em 2023-07-03T03:00Z, detecta que file_2 tem um carimbo de data/hora updated maior que a última execução de transferência bem-sucedida (2023-07-01T03:00Z). Suponha que, quando a execução da transferência for iniciada, ela falhe devido a um erro temporário. Neste cenário, file_2 não é carregado na tabela de destino do BigQuery. O último carimbo de data/hora de execução de transferência permanece em 2023-07-01T03:00Z.
  • A próxima execução de transferência, em 2023-07-04T03:00Z, detecta que file_2 tem um carimbo de data/hora updated maior que a última execução de transferência bem-sucedida (2023-07-01T03:00Z). Desta vez, a execução da transferência é concluída sem problemas. Portanto, ela carrega file_2 na tabela de destino do BigQuery.
  • A próxima execução de transferência, em 2023-07-05T03:00Z, não detecta arquivos em que o carimbo de data/hora updated é maior que a última execução de transferência bem-sucedida (2023-07-04T03:00Z). A execução da transferência é bem-sucedida sem carregar nenhum dado adicional na tabela de destino do BigQuery.

O exemplo anterior mostra que, quando uma transferência falha, nenhum arquivo é transferido para a tabela de destino do BigQuery. Todas as alterações de arquivo são transferidas na próxima execução de transferência bem-sucedida. As transferências bem-sucedidas subsequentes após uma transferência com falha não geram dados duplicados. No caso de uma transferência com falha, você também pode optar por acionar manualmente uma transferência fora do horário programado regularmente.

Transferências truncadas

Uma configuração de transferência com uma preferência de gravação MIRROR ou WRITE_TRUNCATE, também chamada de transferência truncada, substitui os dados na tabela de destino do BigQuery durante cada execução de transferência com dados de todos os arquivos correspondentes ao URI de origem. MIRROR substitui uma nova cópia dos dados na tabela de destino. Se a tabela de destino estiver usando um decorador de partição, a execução da transferência substituirá apenas os dados na partição especificada. Uma tabela de destino com um decorador de partição tem o formato my_table${run_date}, por exemplo, my_table$20230809.

A repetição das mesmas transferências incrementais ou truncadas em um dia não gera dados duplicados. No entanto, se você executar várias configurações de transferência diferentes que afetam a mesma tabela de destino do BigQuery, isso poderá fazer com que o serviço de transferência de dados do BigQuery duplique dados.

Caminho do recurso do Cloud Storage

Para carregar dados de uma fonte do Cloud Storage, forneça o caminho deles.

O caminho do recurso do Cloud Storage contém o nome do bucket e o objeto (nome do arquivo). Por exemplo, se o bucket do Cloud Storage se chamar mybucket e o arquivo de dados for denominado myfile.csv, o caminho de recurso será gs://mybucket/myfile.csv.

O BigQuery não oferece suporte a caminhos de recursos do Cloud Storage que incluam várias barras consecutivas após a barra dupla inicial. Os nomes de objeto do Cloud Storage podem conter vários caracteres de barra ("/") consecutivos. No entanto, o BigQuery os converte em uma única barra. Por exemplo, o caminho de recurso a seguir, ainda que válido no Cloud Storage, não funciona no BigQuery: gs://bucket/my//object//name.

Para recuperar o caminho do recurso do Cloud Storage:

  1. Abra o Console do Cloud Storage.

    Console do Cloud Storage

  2. Procure a localização do objeto (arquivo) que contém os dados de origem.

  3. Clique no nome do objeto.

    A página Detalhes do objeto é aberta.

  4. Copie o valor fornecido no campo gsutil URI, que começa com gs://.

Suporte a caracteres curinga para caminhos de recursos do Cloud Storage

Quando os dados do Cloud Storage são separados em vários arquivos que têm o mesmo nome base, é possível usar um caractere curinga no caminho do recurso ao carregar os dados.

Para adicionar um caractere curinga ao caminho do recurso do Cloud Storage, anexe um asterisco (*) ao nome base. Por exemplo, se você tiver dois arquivos chamados fed-sample000001.csv e fed-sample000002.csv, o caminho do recurso seria gs://mybucket/fed-sample*: Esse caractere curinga pode ser usado no console do Google Cloud ou na Google Cloud CLI.

É possível usar vários caracteres curinga nos objetos (nomes de arquivos) dentro de buckets. Esses caracteres aparecem em qualquer lugar no nome do objeto.

Os caracteres curinga não expandem um diretório em gs://bucket/. Por exemplo, gs://bucket/dir/* encontra arquivos no diretório dir, mas não no subdiretório gs://bucket/dir/subdir/.

Também não há correspondência em prefixos sem caracteres curinga. Por exemplo, gs://bucket/dir não corresponde em gs://bucket/dir/file.csv ou gs://bucket/file.csv

No entanto, é possível usar vários caracteres curinga em nomes de arquivo dentro de buckets. Por exemplo, gs://bucket/dir/*/*.csv corresponde a gs://bucket/dir/subdir/file.csv.

Para exemplos de suporte a caracteres curinga em combinação com nomes de tabelas parametrizados, consulte Como usar parâmetros de ambiente de execução em transferências.

Considerações sobre o local

O bucket do Cloud Storage precisa estar em uma região ou multirregião compatível com a região ou multirregião do conjunto de dados de destino no BigQuery.

  • Se o conjunto de dados do BigQuery estiver em uma multirregião, o bucket do Cloud Storage que contém os dados a serem transferidos precisará estar na mesma multirregião ou em um local dentro da multirregião. Por exemplo, se o conjunto de dados do BigQuery estiver na multirregião "EU", o bucket do Cloud Storage poderá estar localizado na região "Bélgica-west1" da Bélgica, que está na UE.
  • Se o conjunto de dados estiver em uma região, o bucket do Cloud Storage precisará estar na mesma região. Por exemplo, se o conjunto de dados estiver na região "asia-northeast1" de Tóquio, o bucket do Cloud Storage não poderá estar na multirregião "ASIA".

Para informações detalhadas sobre transferências e regiões, consulte Locais e transferências de conjuntos de dados.

Para mais informações sobre locais do Cloud Storage, consulte Locais de intervalos na respectiva documentação.

Preços

Cotas e limites

O serviço de transferência de dados do BigQuery usa jobs para carregar dados do Cloud Storage no BigQuery.

Todas as Cotas e limites do BigQuery em jobs de carregamento são aplicados aos jobs de carregamento recorrentes do Cloud Storage, com as considerações adicionais a seguir:

Valor Limite
Tamanho máximo por execução de transferência do job de carregamento 15 TB
Número máximo de arquivos por execução de transferência 10.000 arquivos

A seguir