Como copiar conjuntos de dados

Copie um conjunto de dados em uma região ou de uma região para outra sem extrair, mover e recarregar dados no BigQuery. Além disso, copie o conjunto de dados uma vez ou por meio de uma programação recorrente personalizada.

Antes de começar

Antes de criar uma cópia do conjunto de dados, siga estas recomendações:

A cópia do conjunto de dados usa os recursos do serviço de transferência de dados do BigQuery. No projeto do Google Cloud para o conjunto de dados de destino, verifique se você concluiu todas as ações necessárias para ativar o serviço de transferência de dados do BigQuery.
Crie um conjunto de dados do BigQuery como o conjunto de destino, na mesma região ou em uma região diferente do seu conjunto de origem. Ao criar um conjunto de dados, você especifica um local para armazenar os dados do BigQuery. No momento, nem todas as regiões são compatíveis com a cópia do conjunto de dados. Consulte Regiões compatíveis. O nome do conjunto precisa ser exclusivo por projeto.
Localize o ID do conjunto de dados de origem que você quer copiar e o ID do projeto de origem.
Se você pretende configurar notificações de execução de transferência para o Pub/Sub, é preciso ter permissões pubsub.topics.setIamPolicy. As permissões do Pub/Sub não serão necessárias caso você configure notificações por e-mail. Para mais informações, consulte Notificações de execução do serviço de transferência de dados do BigQuery.
Se você pretende substituir a tabela de destino ao copiar usando o sinalizador overwrite_destination_table ambas as tabelas precisam ter o mesmo esquema de particionamento.

Permissões necessárias

Antes de criar uma cópia do conjunto de dados, verifique se a pessoa responsável por criá-la tem as seguintes permissões no BigQuery:

As permissões bigquery.transfers.update e bigquery.jobs.create no projeto para criar a transferência da cópia.
A permissão bigquery.datasets.get no conjunto de dados de origem.
As permissões bigquery.datasets.get, bigquery.datasets.update e bigquery.tables.create no conjunto de dados de destino.

O papel predefinido do IAM bigquery.admin para envolvidos no projeto inclui todas as permissões necessárias para uma cópia do conjunto de dados. Para mais informações sobre os papéis do IAM no BigQuery, consulte Papéis e permissões predefinidos ou a Referência de permissões do IAM.

Como configurar uma cópia do conjunto de dados

Saiba como criar uma cópia do conjunto de dados:

Console

Opção 1: use o ícone Copiar conjunto de dados.

Acesse a página do BigQuery no Console do Cloud.

Acesse a página do BigQuery
Selecione o nome do conjunto de dados de origem que você quer copiar.
Clique no ícone Copiar conjunto de dados.
Na caixa de diálogo Copiar conjunto de dados, selecione o ID do projeto e o ID do conjunto de dados de destino. O projeto e o conjunto de dados podem estar em regiões diferentes, mas nem todas são compatíveis com a cópia entre regiões.
Os nomes dos conjuntos de dados em um projeto precisam ser exclusivos.
Como opção, marque a caixa Substituir tabela de destino se quiser atualizar (substituir) todos os dados no conjunto de dados de destino. As tabelas e o esquema serão substituídos.
Exclua o conjunto de dados antigo para evitar mais custos com armazenamento.

Opção 2: use o botão Transferências.

Acesse a página do BigQuery no Console do Cloud.

Acessar a página do BigQuery
Clique em Transferências.
Clique em + CRIAR UMA TRANSFERÊNCIA.
Na página Criar transferência, siga estas instruções:
- Na seção Tipo de origem, em Origem, escolha Cópia do conjunto de dados.
- No campo Nome de exibição da seção Transferir nome da configuração, insira um nome para a transferência, como My Transfer. O nome da transferência pode ser qualquer valor que permita identificá-la facilmente, caso precise modificá-la mais tarde.
- Na seção Opções de programação, para Programação, deixe o valor padrão (Começar agora) ou clique em Começar no horário definido.
  - Para Repetições, escolha uma opção para a frequência de execução da transferência. As opções são estas:
    - Diário (padrão)
    - Semanalmente
    - Mensal
    - Personalizado
    - Sob demanda
    Se você escolher uma opção diferente de "Diário", outras opções estarão disponíveis. Por exemplo, se você escolher "Semanal", aparecerá uma opção para selecionar o dia da semana. Se você escolher Custom, especifique um horário em estilo cron, por exemplo, every 12 hours. O período mais curto permitido é de 12 horas.
  - Em Data e hora de início, insira a data e a hora para iniciar a transferência. Se você escolher Iniciar agora, não poderá modificar esse campo.
- Em Conjunto de dados de destino, escolha o conjunto que você criou para armazenar seus dados, em uma região diferente.
- Em Conjunto de dados de origem, insira o nome do conjunto de dados que você quer copiar.
- Em Projeto de origem, insira o ID do projeto em que o conjunto de dados de origem está.
- (Opcional) Marque a caixa Substituir tabela de destino se quiser atualizar (substituir) todos os dados no conjunto de dados de destino. As tabelas e o esquema serão substituídos.
- Opcional: na seção Opções de notificação:
  - Clique no botão para ativar as notificações por e-mail. Quando você ativa essa opção, o administrador de transferência recebe uma notificação por e-mail quando uma execução de transferência falha.
  - Em Selecionar um tópico do Pub/Sub, escolha o nome do seu tópico ou clique em Criar um tópico. Essa opção configura notificações de execução do Pub/Sub para sua transferência.
Clique em Salvar.
Exclua o conjunto de dados antigo para evitar mais custos com armazenamento.

bq

Digite o comando bq mk e forneça a sinalização de criação da transferência --transfer_config. As sinalizações abaixo também são obrigatórias:

--project_id
--data_source
--target_dataset
--display_name

--params

bq mk --transfer_config --project_id=PROJECT_ID --data_source=DATA_SOURCE --target_dataset=DATASET --display_name=NAME --params='PARAMETERS'

Substitua:

PROJECT_ID: é seu ID do projeto no Google Cloud. Se --project_id não for especificado, o projeto padrão será usado.
DATA_SOURCE: é a fonte de dados: cross_region_copy.
DATASET: o conjunto de dados de destino do BigQuery para a configuração de transferência.
NAME: o nome de exibição do job de cópia ou da configuração de transferência. O nome da transferência pode ser qualquer valor facilmente identificável, caso precise modificá-la mais tarde.
PARAMETERS contém os parâmetros da configuração da transferência criada no formato JSON. Por exemplo, --params='{"param":"param_value"}'. Para a cópia do conjunto de dados, é preciso fornecer os parâmetros source_dataset_id, source_project_id e, opcionalmente, overwrite_destination_table.

Veja abaixo os parâmetros de uma configuração de cópia do conjunto de dados:

source_dataset_id: o ID do conjunto de dados de origem que você quer copiar
source_project_id: o ID do projeto que contém o conjunto de dados de origem
(Opcional) overwrite_destination_table: inclua esse parâmetro se você quiser truncar as tabelas de uma cópia anterior e atualizar todos os dados.

Por exemplo, o comando a seguir cria uma configuração de cópia de conjunto de dados chamada My Transfer com um conjunto de dados de destino mydataset e um projeto com ID myproject.

bq mk --transfer_config --project_id=myproject --data_source=cross_region_copy --target_dataset=mydataset --display_name='My Dataset Copy' --params='{"source_dataset_id":"123_demo_eu","source_project_id":"mysourceproject","overwrite_destination_table":"true"}'

Para mais informações sobre o comando bq mk, consulte Referência da ferramenta de linha de comando.

API

Use o método projects.locations.transferConfigs.create e forneça uma instância do recurso TransferConfig.

Java

Antes de testar essa amostra, siga as instruções de configuração para Java no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Java.

Ver no GitHub Feedback

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.CreateTransferConfigRequest;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.ProjectName;
import com.google.cloud.bigquery.datatransfer.v1.TransferConfig;
import com.google.protobuf.Struct;
import com.google.protobuf.Value;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;

// Sample to copy dataset from another gcp project
public class CopyDataset {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    final String destinationProjectId = "MY_DESTINATION_PROJECT_ID";
    final String destinationDatasetId = "MY_DESTINATION_DATASET_ID";
    final String sourceProjectId = "MY_SOURCE_PROJECT_ID";
    final String sourceDatasetId = "MY_SOURCE_DATASET_ID";
    Map<String, Value> params = new HashMap<>();
    params.put("source_project_id", Value.newBuilder().setStringValue(sourceProjectId).build());
    params.put("source_dataset_id", Value.newBuilder().setStringValue(sourceDatasetId).build());
    TransferConfig transferConfig =
        TransferConfig.newBuilder()
            .setDestinationDatasetId(destinationDatasetId)
            .setDisplayName("Your Dataset Copy Name")
            .setDataSourceId("cross_region_copy")
            .setParams(Struct.newBuilder().putAllFields(params).build())
            .setSchedule("every 24 hours")
            .build();
    copyDataset(destinationProjectId, transferConfig);
  }

  public static void copyDataset(String projectId, TransferConfig transferConfig)
      throws IOException {
    try (DataTransferServiceClient dataTransferServiceClient = DataTransferServiceClient.create()) {
      ProjectName parent = ProjectName.of(projectId);
      CreateTransferConfigRequest request =
          CreateTransferConfigRequest.newBuilder()
              .setParent(parent.toString())
              .setTransferConfig(transferConfig)
              .build();
      TransferConfig config = dataTransferServiceClient.createTransferConfig(request);
      System.out.println("Copy dataset created successfully :" + config.getName());
    } catch (ApiException ex) {
      System.out.print("Copy dataset was not created." + ex.toString());
    }
  }
}

Python

Antes de testar essa amostra, siga as instruções de configuração para Python no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Python.

Instale o cliente Python para a API Data Transfer do BigQuery com pip install google-cloud-bigquery-datatransfer. Em seguida, crie uma configuração de transferência para copiar o conjunto de dados.

Ver no GitHub Feedback

from google.cloud import bigquery_datatransfer

transfer_client = bigquery_datatransfer.DataTransferServiceClient()

destination_project_id = "my-destination-project"
destination_dataset_id = "my_destination_dataset"
source_project_id = "my-source-project"
source_dataset_id = "my_source_dataset"
transfer_config = bigquery_datatransfer.TransferConfig(
    destination_dataset_id=destination_dataset_id,
    display_name="Your Dataset Copy Name",
    data_source_id="cross_region_copy",
    params={
        "source_project_id": source_project_id,
        "source_dataset_id": source_dataset_id,
    },
    schedule="every 24 hours",
)
transfer_config = transfer_client.create_transfer_config(
    parent=transfer_client.common_project_path(destination_project_id),
    transfer_config=transfer_config,
)
print(f"Created transfer config: {transfer_config.name}")

Como visualizar e atualizar jobs de cópia do conjunto de dados

Para ver o progresso e visualizar os detalhes de uma cópia do conjunto de dados, acesse Transferências.

Console

Visão dos detalhes da transferência no console

As execuções de atualização de cópia do conjunto de dados estão programadas para ocorrer de acordo com a frequência especificada, que é configurável. O padrão é a cada 24 horas. Clique no menu Mais e em Atualizar agora se quiser solicitar uma nova execução imediata.

Botão "Atualizar cópia do conjunto de dados".

Preços

Não há cobrança pela cópia do conjunto de dados durante o período da versão Beta.

Com disponibilidade geral, os dados copiados entre as regiões são cobrados com as mesmas taxas dos preços da saída de rede do Compute Engine entre regiões.

O BigQuery envia dados compactados para cópia entre regiões. Portanto, os gigabytes faturados podem ser inferiores ao tamanho do seu conjunto de dados.

Cotas e limitações

Veja abaixo os limites aplicados à cópia de conjuntos de dados no BigQuery. Os limites se aplicam aos jobs de cópia criados usando a ferramenta de linha de comando bq ou o Console do Cloud e para copiar os jobs enviados programaticamente usando o tipo de cópia do método da API jobs.insert.

Todas as cobranças de uso padrão do BigQuery para armazenamento e consulta se aplicam aos dados copiados. Para mais informações, consulte Preços.

As cópias do conjunto de dados do BigQuery estão sujeitas às seguintes limitações.

Cotas

Na região

A cota da cópia de conjuntos de dados na mesma região é igual para todos os jobs de cópia do BigQuery.

Veja a seguir os limites aplicados à cópia de tabelas no BigQuery. Os limites se aplicam a jobs criados automaticamente ao copiar dados usando a ferramenta de linha de comando bq ou o Console do Cloud. Eles também se aplicam aos jobs de cópia enviados de maneira programática usando o método de API jobs.insert do tipo cópia.

Jobs de cópia por tabela de destino/dia: 1.000 (incluindo falhas)
Jobs de cópia por projeto/dia: 100.000 (incluindo falhas)

Entre regiões

Jobs de cópia por tabela de destino/dia: 100 (inclusive falhas)
Jobs de cópia por projeto/dia: 2.000 (inclusive falhas)

Limitações gerais

É preciso criar o conjunto de dados de destino antes de criar uma configuração de transferência para a cópia do conjunto de dados.
Em cada configuração de cópia do conjunto de dados, é possível ter uma cópia ativa por vez. Execuções de transferência adicionais são enfileiradas.

Limitações do tipo de dados

Não é possível copiar visualizações.
Não é possível copiar tabelas externas.
Não é possível copiar armazenamento em um buffer de streaming.
A possibilidade de copiar tabelas criptografadas com chaves gerenciadas pelo cliente varia se você estiver copiando na mesma região ou entre regiões.

Na região

A cópia de tabelas criptografadas, incluindo aquelas com chaves gerenciadas pelo cliente (CMEK, na sigla em inglês), é compatível com cópias de conjuntos de dados na mesma região.

Entre regiões

A cópia de tabelas com a criptografia padrão entre regiões é compatível. No momento, não é possível copiar tabelas criptografadas com chaves gerenciadas pelo cliente (CMEK, na sigla em inglês) entre regiões. As tabelas criptografadas pelo CMEK são ignoradas ao copiar tabelas para o conjunto de dados de destino.

Limitações do conjunto de dados de origem

O tamanho máximo do conjunto de dados de origem é de 20.000 tabelas. A quantidade de tabelas que podem ser copiadas para cada execução varia quando você copia na mesma região ou entre regiões.

Na região

O conjunto de dados de origem pode conter no máximo 20.000 tabelas.
É possível copiar no máximo 20.000 tabelas para cada execução no conjunto de dados de destino.

Entre regiões

O tamanho do conjunto de dados de origem pode ter no máximo 20.000 tabelas.
No máximo 1.000 tabelas podem ser copiadas por execução no conjunto de dados de destino.

Exemplo

Se você configurar uma cópia entre regiões de um conjunto de dados com 8.000 tabelas, o serviço de transferência de dados do BigQuery criará automaticamente oito execuções em sequência. A primeira execução copia 1.000 tabelas e, em seguida, 24 horas depois, outra execução copia 1.000 tabelas, até que todas as tabelas no conjunto de dados estejam copiadas, até o máximo de 20.000 tabelas por conjunto de dados.

Limitações do conjunto de dados de destino

Entre regiões

Não é possível usar conjuntos de dados com chaves gerenciadas pelo cliente (CMEK, na sigla em inglês) como destino ao copiar entre regiões. No entanto, uma tabela com CMEK é permitida como um destino ao copiar dentro das regiões.

Limitações da tabela

No momento, a cópia de tabelas particionadas é aceita. No entanto, não é possível anexar dados a uma tabela particionada.
Se uma tabela existir no conjunto de dados de origem e de destino e não tiver sido alterada desde a última cópia bem-sucedida, ela será ignorada. Isso ocorrerá mesmo se a caixa Substituir tabela de destino estiver marcada.
Ao truncar tabelas, a cópia do conjunto de dados não detecta nenhuma alteração feita no conjunto de destino antes de iniciar a cópia. Todos os dados no conjunto de dados de destino serão atualizados (substituídos). As tabelas e o esquema serão substituídos.
- Se você pretende substituir a tabela de destino ao copiar usando o sinalizador overwrite_destination_table ambas as tabelas precisam ter o mesmo esquema de particionamento.

Regiões compatíveis

Há dois tipos de locais:

Uma região é um lugar geográfico específico, como Londres.
Um local multirregional é uma área geográfica grande, como Estados Unidos, que contém dois ou mais lugares geográficos.

Os conjuntos de dados podem ser copiados de uma região para outra, de uma para várias, de várias para uma ou de várias para várias.

No momento, nem todas as regiões são compatíveis com a cópia de conjuntos de dados. É possível criar cópias nas regiões em que o serviço de transferência de dados do BigQuery atualmente é compatível, como mostrado abaixo.

Locais regionais

	Descrição da região	Nome da região
América
	Iowa	`us-central1`
	Las Vegas	`us-west4`
	Los Angeles	`us-west2`
	Montreal	`northamerica-northeast1`
	Virgínia do Norte	`us-east4`
	Oregon	`us-west1`
	Salt Lake City	`us-west3`
	São Paulo	`southamerica-east1`
	Carolina do Sul	`us-east1`
Europa
	Bélgica	`europe-west1`
	Finlândia	`europe-north1`
	Frankfurt	`europe-west3`
	Londres	`europe-west2`
	Países Baixos	`europe-west4`
	Varsóvia	`europe-central2`
	Zurique	`europe-west6`
Ásia-Pacífico
	Hong Kong	`asia-east2`
	Jacarta	`asia-southeast2`
	Mumbai	`asia-south1`
	Osaka	`asia-northeast2`
	Seul	`asia-northeast3`
	Singapura	`asia-southeast1`
	Sydney	`australia-southeast1`
	Taiwan	`asia-east1`
	Tóquio	`asia-northeast1`

Locais multirregionais

Descrição multirregional	Nome multirregional
Data centers dentro de estados membro da União Europeia¹	`EU`
Data centers nos Estados Unidos	`US`

¹ Os dados localizados na multirregião EU não são armazenados nos data centers europe-west2 (Londres) ou europe-west6 (Zurique).

A seguir

Para informações sobre o uso de transferências, incluindo ver detalhes sobre a configuração, listar configurações e visualizar o histórico de execução, consulte Como trabalhar com transferências.