Como importar dados de bancos de dados que não são do Cloud Spanner

Nesta página, descrevemos como preparar arquivos Avro que você exportou de bancos de dados que não são do Cloud Spanner e, em seguida, importá-los para o Cloud Spanner. Se quiser importar um banco de dados do Cloud Spanner que já foi exportado, consulte Como importar arquivos Avro do Cloud Spanner.

O processo usa o Dataflow. Ele importa dados de um bucket do Cloud Storage que contém um arquivo de manifesto JSON e um conjunto de arquivos Avro.

Antes de começar

Para importar um banco de dados do Cloud Spanner, primeiro você precisa ativar as APIs Cloud Spanner, Cloud Storage, Compute Engine e Dataflow:

Ative as APIs

É preciso também ter cota suficiente e as permissões necessárias do Cloud IAM.

Requisitos de cota

Os requisitos de cota para jobs de importação, do serviço do Google Cloud, são os seguintes:

• Cloud Spanner: é necessário ter nós suficientes para suportar o volume de dados que estão sendo importados. Não é necessário incluir qualquer outro nó para importar um banco de dados. No entanto, talvez seja necessário adicionar nós para que o job seja concluído dentro de um prazo razoável. Consulte Como otimizar jobs para saber mais detalhes.
• Cloud Storage: para importar, é preciso ter um bucket contendo os arquivos exportados anteriormente. Não é necessário definir um tamanho para o bucket.
• Dataflow: os jobs de importação estão sujeitos às mesmas cotas do Compute Engine para endereço IP, uso da CPU e do disco aplicadas a outros jobs do Dataflow.

• Compute Engine: antes de executar um job de importação, é necessário configurar cotas iniciais para o Compute Engine, que serão usadas pelo Dataflow. Essas cotas representam o número máximo de recursos que você permite que o Dataflow use para seu job. Os valores iniciais recomendados são:

  • CPUs: 200
  • Endereços IP em uso: 200
  • Disco permanente padrão: 50 TB

  Geralmente, não é necessário fazer nenhum outro ajuste. O Dataflow fornece escalonamento automático para que você pague apenas pelos recursos efetivamente utilizados durante a importação. Se seu job puder usar mais recursos, a IU do Dataflow exibirá um ícone de aviso. O job será concluído, mesmo que um ícone de aviso seja exibido.

Requisitos do Cloud IAM

Para importar um banco de dados, é preciso também ter papéis do Cloud IAM com permissões suficientes para usar todos os serviços envolvidos em um job de importação. Para informações sobre como conceder papéis e permissões, consulte Como aplicar papéis do IAM.

Para importar um banco de dados, você precisa dos seguintes papéis:

• No nível do projeto do Google Cloud:
  • Visualizador do Cloud Spanner
  • Administrador do Dataflow
  • Administrador do Storage
• No nível do banco de dados ou da instância do Cloud Spanner, ou no nível do projeto do Google Cloud:
  • Leitor do Cloud Spanner
  • Administrador de banco de dados do Cloud Spanner (obrigatório apenas para jobs de importação)

Como exportar dados de um banco de dados que não seja do Cloud Spanner para arquivos Avro

O processo de importação traz dados de arquivos Avro localizados em um bucket do Cloud Storage. É possível exportar dados no formato Avro de qualquer fonte e usar qualquer método disponível para fazer isso.

Tenha isto em mente ao exportar seus dados:

• É possível exportar usando qualquer um dos tipos primitivos do Avro, bem como o tipo complexo de matriz.

• Cada coluna nos seus arquivos Avro precisa usar um dos seguintes tipos de colunas:

  • ARRAY
  • BOOL
  • BYTES
  • DOUBLE
  • FLOAT
  • INT
  • LONG^*
  • STRING^*

  ^*É possível importar um LONG armazenando um carimbo de data/hora ou um STRING armazenando um carimbo de data/hora como um Cloud Spanner TIMESTAMP. Consulte os mapeamentos recomendadosabaixo para detalhes.

• Não é necessário incluir ou gerar metadados ao exportar os arquivos Avro.

• Não é necessário seguir nenhuma convenção de nomenclatura específica para seus arquivos.

Se você não exportar seus arquivos diretamente para o Cloud Storage, precisará fazer o upload dos arquivos Avro para um bucket do Cloud Storage. Para ver instruções detalhadas, consulte Como fazer upload de objetos.

Como criar o esquema para o banco de dados do Cloud Spanner

Antes de executar sua importação, é preciso criar a tabela de destino no Cloud Spanner e definir seu esquema.

É necessário criar um esquema que use o tipo de coluna apropriado para cada coluna nos arquivos Avro.

Mapeamentos recomendados

Tipo de coluna Avro	Tipo de coluna Cloud Spanner
ARRAY	ARRAY
BOOL	BOOL
BYTES	BYTES
DOUBLE	FLOAT64
FLOAT	FLOAT64
INT	INT64
LONG	INT64 TIMESTAMP (quando LONG representa um carimbo de data/hora do número de microssegundos desde 1970-01-01 00:00:00 UTC)
STRING	STRING TIMESTAMP (quando STRING representa um carimbo de data/hora no formato canônico para consultas SQL)

Observação: se uma coluna nos dados do Avro contiver valores NULL, garanta que a coluna correspondente na tabela do Cloud Spanner seja anulável.

É recomendável criar índices secundários e chaves estrangeiras depois de importar seus dados para o Cloud Spanner, em vez de definir inicialmente o esquema para a tabela.

Como criar um arquivo spanner-export.json

Também é possível criar um arquivo chamado spanner-export.json no bucket do Cloud Storage. Este arquivo contém uma matriz de tables que lista o nome e os locais dos arquivos de dados para cada tabela.

Os conteúdos do arquivo têm o seguinte formato:

{
  "tables": [
   {
    "name": "TABLE1",
    "dataFiles": [
      "RELATIVE/PATH/TO/TABLE1_FILE1",
      "RELATIVE/PATH/TO/TABLE1_FILE2"
    ]
   },
   {
    "name": "TABLE2",
    "dataFiles": ["RELATIVE/PATH/TO/TABLE2_FILE1"]
   }
  ]
}

Observação: não há suporte para caracteres curingas. Você precisa escrever todos os nomes de arquivo na íntegra.

Como executar um job de importação do Dataflow usando gcloud

Para iniciar o job de importação, siga as instruções para usar a ferramenta de linha de comando gcloud para executar um job com o Modelo Avro para o Cloud Spanner.

Depois de iniciar um job de importação, é possível ver detalhes sobre ele no Console do Cloud.

Após a conclusão do job de importação, adicione as chaves estrangeiras e os índices secundários necessários.

Observação: para evitar cobranças de saída de rede, escolha uma região que se sobreponha à localização do seu intervalo do Cloud Storage. Consulte abaixo Como escolher uma região para mais informações.

Como escolher uma região para o job de importação

Convém escolher uma região diferente dependendo da configuração que o bucket do Cloud Storage usa: regional ou multirregional. Para evitar cobranças de saída de rede, escolha uma região que se sobreponha ao local do seu intervalo do Cloud Storage.

Locais de intervalos regionais

Se o local do bucket do Cloud Storage for regional, escolha a mesma região para o job de importação, caso esteja disponível, para aproveitar o uso gratuito da rede.

Se a mesma região não estiver disponível, haverá cobranças de saída. Consulte os preços de saída de rede do Cloud Storage para escolher uma região que incorra tarifas de saída de rede mais baixas.

Locais de intervalos multirregionais

Se o local do bucket do Cloud Storage for multirregional, escolha uma das regiões que o compõem para aproveitar o uso gratuito da rede.

Se não houver uma região sobreposta disponível, haverá cobranças de saída. Consulte os preços de saída de rede do Cloud Storage para escolher uma região que incorra tarifas de saída de rede mais baixas.

Como visualizar ou solucionar problemas de jobs na IU do Dataflow

Depois de iniciar um job de importação, é possível ver os detalhes dele, incluindo registros, na seção do Dataflow do Console do Cloud.

Como visualizar detalhes do job do Dataflow

Para ver detalhes de um job que está sendo executado, siga estas etapas:

1. Navegue até a página Detalhes do banco de dados.

2. Clique em Visualizar detalhes do job no Dataflow na mensagem de status do job, que é semelhante a esta:

   

   O Console do Cloud exibe detalhes do job do Dataflow.

Para visualizar um job executado recentemente, siga estas etapas:

1. Navegue até a página Detalhes do banco de dados.
2. Clique na guia Importar/Exportar.

3. Clique no nome do seu job na lista.

   O Console do Cloud exibe detalhes do job do Dataflow.

Para visualizar um job executado há mais de uma semana, siga estas etapas:

1. Acesse a página de jobs do Dataflow no Console do Cloud.

   Acessar a página de jobs (em inglês)

2. Encontre seu job na lista e clique no nome dele.

   O Console do Cloud exibe detalhes do job do Dataflow.

Observação: jobs do mesmo tipo no mesmo banco de dados têm nomes iguais. É possível distinguir os jobs pelos valores nas colunas Horário de início ou Horário de término.

Como visualizar registros do Dataflow para seu job

Para visualizar os registros de um job do Dataflow, navegue até a página de detalhes do job, conforme descrito acima. Em seguida, clique em Registros, à direita do nome do job.

Se um job falhar, procure erros nos registros. Se houver erros, a contagem de erros será exibida ao lado de Registros:

Para ver os erros do job, siga estas etapas:

1. Clique na contagem de erros, ao lado de Registros.

   O Console do Cloud exibe os registros do job. Pode ser necessário rolar para visualizar os erros.

2. Localize entradas com o ícone de erro .

3. Clique em uma entrada de registro individual para expandir seu conteúdo.

Para mais informações sobre como solucionar problemas de jobs do Dataflow, consulte Solução de problemas do pipeline.

Solução de problemas de jobs de importação com falha

Se você vir os seguintes erros nos registros do job:

com.google.cloud.spanner.SpannerException: NOT_FOUND: Session not found

--or--

com.google.cloud.spanner.SpannerException: DEADLINE_EXCEEDED: Deadline expired before operation could complete.

Verifique a latência de gravação de 99% na guia Monitoring do Console do Cloud Spanner. Se estiver exibindo valores altos (vários segundos), significa que a instância está sobrecarregada, fazendo com que as gravações atinjam o tempo limite e falhem.

Uma causa disso é que o job do Dataflow está sendo executado usando muitos workers, colocando muita carga na instância do Cloud Spanner.

Para especificar um limite no número de workers do Dataflow, em vez de usar o recurso de importação no Console do Cloud Spanner, inicie a importação usando o modelo Avro do Cloud Storage para Cloud Spanner do Dataflow e especifique o número máximo dos workers, conforme descrito abaixo:

• Se você estiver usando o console do Dataflow, o parâmetro Workers máximos estará localizado na seção Parâmetros opcionais da página Criar job a partir do modelo.

• Se você estiver usando o gcloud, especifique o argumento max-workers. Exemplo:

    gcloud dataflow jobs run my-import-job \
    --gcs-location='gs://dataflow-templates/latest/GCS_Avro_to_Cloud_Spanner' \
    --region=us-central1 \
    --parameters='instanceId=test-instance,databaseId=example-db,inputDir=gs://my-gcs-bucket' \
    --max-workers=10
  

O número máximo de workers depende muito dos dados importados, mas o ideal é que a utilização total da CPU do Spanner esteja entre 70% e 90%. Isso fornece um bom equilíbrio entre a eficiência do Spanner e a conclusão de jobs sem erros.

Para atingir essa meta de utilização na maioria dos esquemas/cenários, recomendamos um número máximo de vCPUs de trabalho entre 4 e 6 vezes o número de nós do Spanner.

Por exemplo, para uma instância do Spanner de 10 nós, usando workers n1-standard-2, defina o máximo de workers como 25, fornecendo 50 vCPUs.

Como otimizar jobs de importação de execução lenta

Se as sugestões das configurações iniciais forem seguidas, geralmente não será necessário fazer nenhum outro ajuste. Se o job estiver sendo executado lentamente, é possível tentar outras otimizações:

• Otimize o local do job e dos dados: execute o job do Cloud Dataflow na mesma região em que estão localizados o bucket do Cloud Storage e a instância do Cloud Spanner.

• Garanta recursos suficientes do Dataflow: se as cotas relevantes do Compute Engine limitarem os recursos do job do Dataflow, a página do Dataflow no Console do Google Cloud exibirá um ícone de aviso e mensagens de registro:

  

  Nessa situação, é possível reduzir o ambiente de execução do job aumentando as cotas (em inglês) para CPUs, endereços IP em uso e disco permanente padrão. Porém, isso pode resultar em mais cobranças do Compute Engine.

• Verifique a utilização da CPU do Cloud Spanner: é possível aumentar o número de nós de uma instância caso a utilização da CPU para ela seja superior a 65%. Os nós extras adicionam mais recursos do Cloud Spanner e isso pode acelerar o job, mas resultará em cobranças adicionais do Cloud Spanner.

Fatores que afetam o desempenho do job de importação

Vários fatores influenciam o tempo necessário para concluir um job de importação.

• Tamanho do banco de dados do Cloud Spanner: o processamento de mais dados leva mais tempo e exige mais recursos.

• Esquema do banco de dados do Cloud Spanner: o número de tabelas, o tamanho das linhas, o número de índices secundários e o número de chaves estrangeiras influenciam o tempo necessário para executar um job de importação.

• Local dos dados: os dados são transferidos entre o Cloud Spanner e o Cloud Storage usando o Dataflow. O ideal é que os três componentes estejam localizados na mesma região. Se não estiverem, a movimentação dos dados pelas regiões prejudica a velocidade de execução do job.

• Número de workers do Dataflow: usando o escalonamento automático, o Dataflow escolhe o número de workers para o job, dependendo da quantidade de trabalho que precisa ser feita. O número de workers, no entanto, será limitado pelas cotas para CPUs, endereços IP em uso e disco permanente padrão. A IU do Dataflow exibirá um ícone de aviso caso encontre limites de cotas. Nessa situação, o progresso será mais lento, mas ainda assim o job será concluído.

• Carga atual no Cloud Spanner: um job de importação adiciona carga significativa da CPU em uma instância do Cloud Spanner. Se a instância já tiver uma carga atual substancial, a execução do job será mais lenta.

• Número de nós do Cloud Spanner: se a utilização da CPU para a instância for superior a 65%, o job será executado mais lentamente.