Introdução às transferências do Amazon S3

O serviço de transferência de dados do BigQuery para Amazon S3 permite programar e gerenciar automaticamente jobs de carga recorrentes do Amazon S3 para o BigQuery.

Formatos de arquivo compatíveis

O serviço de transferência de dados do BigQuery permite o carregamento de dados do Amazon S3 em um dos seguintes formatos:

• Valores separados por vírgula (CSV)
• 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 Amazon S3 é 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.

Pré-requisitos do Amazon S3

Para carregar dados de uma fonte de dados do Amazon S3, é preciso:

• fornecer o URI do Amazon S3 para seus dados de origem;
• ter o código da sua chave de acesso;
• ter sua chave de acesso secreta;
• definir pelo menos a política AmazonS3ReadOnlyAccess gerenciada pela AWS nos dados de origem do Amazon S3.

URIs do Amazon S3

Quando você fornece o URI do Amazon S3, o caminho precisa estar neste formato: s3://bucket/folder1/folder2/.... Apenas o nome de bucket de nível superior é necessário. Os nomes das pastas são opcionais. Se você especificar um URI que inclua apenas o nome do bucket, todos os arquivos no bucket serão transferidos ao BigQuery e carregados nele.

Parametrização do ambiente de execução da transferência do Amazon S3

O URI do Amazon S3 e a tabela de destino podem ser parametrizados. Assim, você carrega dados de buckets do Amazon S3 organizados por data. Não é possível parametrizar a parte do bucket do URI. Os parâmetros usados pelas transferências do Amazon S3 são os mesmos usados pelas transferências do Cloud Storage.

Para mais detalhes, consulte Parâmetros do ambiente de execução em transferências.

Ingestão de dados para transferências do Amazon S3

É 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 de Amazon S3.

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.

Aviso: o serviço de transferência de dados do BigQuery depende da propriedade "horário da última modificação" em cada arquivo de origem para determinar quais arquivos serão transferidos, conforme visto nos exemplos de transferência. A modificação dessas propriedades pode fazer com que a transferência pule determinados arquivos ou carregue o mesmo arquivo várias vezes. Essa propriedade pode ter nomes diferentes em cada sistema de armazenamento aceito pelo serviço de transferência de dados do BigQuery. Por exemplo, os objetos do Cloud Storage chamam essa propriedade de updated.

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.

Suporte a caracteres curinga em URIs do Amazon S3

Quando os dados de origem são separados em vários arquivos que têm o mesmo nome base, é possível usar um caractere curinga no URI ao carregar os dados. O caractere curinga é um asterisco (*) e pode ser usado em qualquer parte do URI do Amazon S3, exceto no nome do bucket.

É possível utilizar mais de um caractere curinga no URI do Amazon S3. No entanto, você garante o melhor desempenho quando esse URI especifica apenas um caractere curinga:

• Há um limite maior no número máximo de arquivos por execução de transferência.

• O caractere curinga abrange os limites do diretório. Por exemplo, o URI do Amazon S3 s3://my-bucket/*.csv corresponderá ao arquivo s3://my-bucket/my-folder/my-subfolder/my-file.csv.

Exemplos de URI do Amazon S3

Exemplo 1

Para carregar um único arquivo do Amazon S3 no BigQuery, especifique o URI do Amazon S3 referente a esse arquivo.

s3://my-bucket/my-folder/my-file.csv

Exemplo 2

Para carregar todos os arquivos de um bucket do Amazon S3 no BigQuery, especifique apenas o nome do bucket com ou sem caracteres curinga.

s3://my-bucket/

ou

s3://my-bucket/*

s3://my-bucket* não é um URI do Amazon S3 válido, já que não é possível usar um caractere curinga no nome do bucket.

Exemplo 3

Para carregar todos os arquivos do Amazon S3 que tenham o mesmo prefixo, especifique esse prefixo seguido por um caractere curinga.

s3://my-bucket/my-folder/*

Ao contrário do carregamento de todos os arquivos de um bucket do Amazon S3 de nível superior, o caractere curinga precisa ser especificado no final do URI do Amazon S3 para que todos os arquivos sejam carregados.

Exemplo 4

Para carregar todos os arquivos do Amazon S3 com um caminho semelhante, especifique o prefixo comum seguido por um caractere curinga.

s3://my-bucket/my-folder/*.csv

Exemplo 5

Como os caracteres curinga abrangem diretórios, todos os arquivos csv em my-folder e nas subpastas de my-folder são carregados no BigQuery.

Se estes arquivos de origem estiverem em uma pasta logs:

s3://my-bucket/logs/logs.csv
s3://my-bucket/logs/system/logs.csv
s3://my-bucket/logs/some-application/system_logs.log
s3://my-bucket/logs/logs_2019_12_12.csv

eles serão identificados pelo seguinte:

s3://my-bucket/logs/*

Exemplo 6

Se você tem estes arquivos de origem, mas quer transferir apenas aqueles com o nome de arquivo logs.csv:

s3://my-bucket/logs.csv
s3://my-bucket/metadata.csv
s3://my-bucket/system/logs.csv
s3://my-bucket/system/users.csv
s3://my-bucket/some-application/logs.csv
s3://my-bucket/some-application/output.csv

os arquivos com logs.csv no nome serão identificados pelo seguinte:

s3://my-bucket/*logs.csv

Exemplo 7

Ao usar vários caracteres curinga, você tem mais controle sobre quais arquivos são transferidos. Para isso, são necessários limites menores. Isso significa que cada caractere curinga corresponderá apenas até o final de um caminho em um subdiretório. Por exemplo, consulte os arquivos de origem a seguir no Amazon S3:

s3://my-bucket/my-folder1/my-file1.csv
s3://my-bucket/my-other-folder2/my-file2.csv
s3://my-bucket/my-folder1/my-subfolder/my-file3.csv
s3://my-bucket/my-other-folder2/my-subfolder/my-file4.csv

Se você quiser apenas transferir my-file1.csv e my-file2.csv, use o seguinte como valor do URI do Amazon S3:

s3://my-bucket/*/*.csv

Como nenhum caractere curinga abrange os diretórios, esse URI limita a transferência apenas aos arquivos CSV que estão em my-folder1 e my-other-folder2. As subpastas não são incluídas na transferência.

Chaves de acesso da AWS

O ID da chave de acesso e a chave de acesso secreta são usadas para acessar os dados do Amazon S3 em seu nome. Como prática recomendada, crie um ID de chave de acesso e uma chave de acesso secreta exclusivos especificamente para as transferências do Amazon S3 para fornecer acesso mínimo ao serviço de transferência de dados do BigQuery. Para conferir informações sobre como gerenciar suas chaves de acesso, consulte a documentação geral de referência da AWS.

Considerações de consistência

Ao transferir dados do Amazon S3, é possível que alguns deles não sejam movidos para o BigQuery, especialmente se os arquivos foram adicionados ao bucket muito recentemente. Leva aproximadamente 10 minutos para que um arquivo fique disponível para o serviço de transferência de dados do BigQuery depois que ele é adicionado ao bucket. Em alguns casos, no entanto, isso pode levar mais de 10 minutos.

Importante: para reduzir a possibilidade de dados ausentes, programe as transferências do Amazon S3 para que ocorram pelo menos 10 minutos depois que os arquivos forem adicionados ao bucket.

Para mais informações sobre o modelo de consistência do Amazon S3, consulte o modelo de consistência de dados do Amazon S3 na documentação do Amazon S3.

Prática recomendada para custos de transferência de dados de saída

As transferências do Amazon S3 podem falhar se a tabela de destino não tiver sido configurada corretamente. Os motivos de uma configuração incorreta incluem:

• A tabela de destino não existe.
• O esquema da tabela não está definido.
• O esquema da tabela não é compatível com os dados que estão sendo transferidos.

Para evitar custos de transferência de dados de saída do Amazon S3, primeiro teste uma transferência com um subconjunto pequeno, mas representativo, dos arquivos. Quando falamos em "pequeno", estamos nos referindo ao tamanho dos dados e à contagem de arquivos.

Preço

Para conferir informações sobre os preços do serviço de transferência de dados do BigQuery, consulte a página Preços.

Os custos podem ser gerados fora do Google usando esse serviço. Consulte a página de preços do Amazon S3 para conferir detalhes.

Cotas e limites

O serviço de transferência de dados do BigQuery usa jobs para carregar dados do Amazon S3 no BigQuery. Todas as Cotas e limites do BigQuery nos jobs de carregamento são aplicadas às transferências recorrentes do Amazon S3. Há estas considerações adicionais:

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 quando o URI do Amazon S3 inclui até um caractere curinga	10.000.000 arquivos
Número máximo de arquivos por execução de transferência quando o URI do Amazon S3 inclui mais de um caractere curinga	10.000 arquivos

A seguir

• Saiba mais sobre como configurar uma transferência do Amazon S3.
• Saiba mais sobre parâmetros de ambiente de execução em transferências do S3.
• Saiba mais sobre o serviço de transferência de dados do BigQuery.