Importar e exportar dados no formato CSV

Nesta página, descrevemos como exportar dados do Spanner para arquivos CSV ou importar dados de arquivos CSV para um banco de dados do Spanner.

• Se você quiser importar um banco de dados do Spanner que já foi exportado a arquivos Avro no Cloud Storage, consulte Importar arquivos Avro do Spanner.
• Se quiser importar arquivos Avro de um banco de dados que não seja do Spanner, consulte Importar dados de bancos de dados que não são do Spanner

O processo usa o Dataflow. É possível exportar dados o Spanner para um bucket do Cloud Storage ou importar dados para ele. Spanner de um bucket do Cloud Storage que contém um JSON de manifesto e um conjunto de arquivos CSV.

Observação: para conhecer o Spanner usando uma instância de teste gratuito de 90 dias, consulte Criar uma instância de teste gratuito do Spanner.

Antes de começar

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

Enable the APIs

É preciso também ter cota suficiente e as permissões obrigatórias do IAM.

Requisitos de cota

Os requisitos de cota para jobs de importação ou exportação são os seguintes:

• Spanner: é preciso ter capacidade de computação suficiente para aceitar a quantidade de dados que você está importando. Nenhuma capacidade de computação extra é necessária para importar ou exportar um banco de dados, mas talvez você precise adicionar mais capacidade de computação para que seu job seja concluído em um tempo razoável. Consulte Otimizar tarefas para mais detalhes.
• Cloud Storage: para importar, é preciso ter um bucket contendo os arquivos exportados anteriormente. Para exportar, crie um bucket para os arquivos exportados, se ainda não tiver um. É possível fazer isso no console do Google Cloud, na página do Cloud Storage ou ao criar a exportação na página do Spanner. Não é preciso definir um tamanho para o bucket.
• Dataflow: os jobs de exportação ou importação estão sujeitos ao mesmo uso de CPU, disco e cotas do Compute Engine do endereço IP aplicados a outros jobs do Dataflow.

• Compute Engine: antes de executar o job de importação ou exportação, é preciso configurar as cotas iniciais para o Compute Engine, 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 oferece escalonamento automático para que você pague somente pelos recursos reais usados durante a importação ou exportação. Se o 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.

Funções exigidas

Para receber as permissões necessárias para exportar um banco de dados, peça ao administrador para conceder a você os seguintes papéis do IAM na conta de serviço do worker do Dataflow:

• Leitor do Cloud Spanner (roles/spanner.viewer)
• Worker do Dataflow (roles/dataflow.worker)
• Administrador de armazenamento (roles/storage.admin)
• Leitor de banco de dados do Spanner (roles/spanner.databaseReader)
• Administrador de banco de dados (roles/spanner.databaseAdmin)

Observação: o papel de administrador do banco de dados do Spanner é necessário apenas para jobs de importação.

Exportar dados do Spanner para arquivos CSV

Para exportar dados do Spanner para arquivos CSV no Cloud Storage: siga as instruções para usar a Google Cloud CLI e executar um job com o Modelo Cloud Storage Text para Spanner.

Também é possível consultar as informações neste documento sobre como visualizar ou solucionar problemas de jobs, como otimizar jobs lentos e fatores que afetam o desempenho dos jobs.

Observação :nem os dados do fluxo de alterações nem os os valores nas colunas geradas armazenadas são exportados.

Importar dados de arquivos CSV para o Spanner

O processo para importar dados de arquivos CSV inclui as seguintes etapas:

1. Exporte seus dados para arquivos CSV e armazene-os no Cloud Storage. Não inclua uma linha de cabeçalho.
2. Crie um arquivo de manifesto JSON e armazene o arquivo junto aos arquivos CSV.
3. Crie tabelas de destino vazias no banco de dados do Spanner ou garanta que os tipos de dados das colunas nos arquivos CSV correspondam às respectivas colunas nas tabelas atuais.
4. Execute o job de importação.

Observação: o modelo de fluxo de dados não processa CSVs com cabeçalhos.

Etapa 1: exportar dados de um banco de dados que não seja do Spanner para arquivos CSV

O processo de importação traz dados de arquivos CSV localizados em um bucket do Cloud Storage. É possível exportar dados em formato CSV de qualquer origem.

Tenha isto em mente ao exportar seus dados:

• Os arquivos de texto a serem importados precisam estar no formato CSV.

• Os dados precisam corresponder a um dos tipos a seguir:

GoogleSQL

BOOL
INT64
FLOAT64
NUMERIC
STRING
DATE
TIMESTAMP
BYTES
JSON

PostgreSQL

boolean
bigint
double precision
numeric
character varying, text
date
timestamp with time zone
bytea

• Não é preciso incluir nem gerar metadados ao exportar os arquivos CSV.

• 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, é necessário fazer o upload dos arquivos CSV para um bucket do Cloud Storage.

Etapa 2: criar um arquivo de manifesto JSON

Também é necessário criar um arquivo de manifesto com uma descrição em JSON dos arquivos a serem importados e colocá-lo no mesmo bucket do Cloud Storage em que você armazenou seus arquivos CSV. Neste arquivo de manifesto, há uma matriz tables que lista o nome e os locais do arquivo de dados para cada tabela. O arquivo também especifica o dialeto do banco de dados receptor. Se o dialeto for omitido, o padrão será o GoogleSQL.

Observação: se uma tabela tiver colunas geradas, o manifesto precisará incluir uma lista explícita das colunas não geradas para importar para essa tabela. O Spanner usa essa lista para mapear colunas CSV para as colunas da tabela correta. Os valores de coluna gerados são calculados automaticamente durante a importação.

O formato do arquivo de manifesto corresponde ao tipo de mensagem a seguir, mostrado aqui no formato de buffer de protocolo:

message ImportManifest {
  // The per-table import manifest.
  message TableManifest {
    // Required. The name of the destination table.
    string table_name = 1;
    // Required. The CSV files to import. This value can be either a filepath or a glob pattern.
    repeated string file_patterns = 2;
    // The schema for a table column.
    message Column {
      // Required for each Column that you specify. The name of the column in the
      // destination table.
      string column_name = 1;
      // Required for each Column that you specify. The type of the column.
      string type_name = 2;
    }
    // Optional. The schema for the table columns.
    repeated Column columns = 3;
  }
  // Required. The TableManifest of the tables to be imported.
  repeated TableManifest tables = 1;

  enum ProtoDialect {
    GOOGLE_STANDARD_SQL = 0;
    POSTGRESQL = 1;
  }
  // Optional. The dialect of the receiving database. Defaults to GOOGLE_STANDARD_SQL.
  ProtoDialect dialect = 2;
}

O exemplo a seguir mostra um arquivo de manifesto para importar tabelas chamadas Albums e Singers para um banco de dados do dialeto GoogleSQL. A tabela Albums usa o esquema de colunas que o job recupera do banco de dados. A tabela Singers usa o esquema especificado pelo arquivo de manifesto:

{
  "tables": [
    {
      "table_name": "Albums",
      "file_patterns": [
        "gs://bucket1/Albums_1.csv",
        "gs://bucket1/Albums_2.csv"
      ]
    },
    {
      "table_name": "Singers",
      "file_patterns": [
        "gs://bucket1/Singers*.csv"
      ],
      "columns": [
        {"column_name": "SingerId", "type_name": "INT64"},
        {"column_name": "FirstName", "type_name": "STRING"},
        {"column_name": "LastName", "type_name": "STRING"}
      ]
    }
  ]
}

Etapa 3: criar a tabela para o banco de dados do Spanner

Antes de executar a importação, é necessário criar as tabelas de destino em seu no banco de dados do Spanner. Se a tabela de destino do Spanner já tiver um esquema, todas as colunas especificadas no arquivo de manifesto precisam ter os mesmos dados de linha como as colunas correspondentes no esquema da tabela de destino.

Recomendamos que você crie índices secundários, chaves externas e fluxos de mudança depois de importar seus dados para o Spanner, e não quando criar a tabela. Se sua tabela já contiver esses então recomendamos descartá-las e recriá-las depois durante a importação dos dados.

Etapa 4: executar um job de importação do Dataflow usando a gcloud

Para iniciar o job de importação, siga as instruções de uso da Google Cloud CLI para executar um job com o modelo do Cloud Storage Text para Spanner.

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

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

Observação: para evitar cobranças de transferência de dados de saída, escolha uma região que se sobreponha à sua região do Cloud Storage para o local do bucket.

Escolha uma região para o job de importação

Convém escolher uma região diferente com base no local do seu bucket do Cloud Storage. Para evitar cobranças de transferência de dados de saída, escolha uma região que corresponda à localização do seu bucket do Cloud Storage.

• Se o local do bucket do Cloud Storage for uma região, podem aproveitar o uso gratuito da rede escolhendo o mesma região para o job de importação, supondo que essa região esteja disponível.

• Se o local do bucket do Cloud Storage for birregional, você pode aproveitar o uso gratuito da rede escolhendo uma das duas regiões que compõem a região birregional do job de importação; supondo que uma das regiões esteja disponível.

• Se uma região colocalizada não estiver disponível para o job de importação ou se o local do bucket do Cloud Storage for uma multirregional, serão aplicadas cobranças de transferência de dados de saída. Consulte os preços de transferência de dados do Cloud Storage para escolher uma região que incorra nas tarifas de transferência de dados mais baixas.

Conferir ou resolver problemas de jobs na interface do Dataflow

Depois de iniciar um job de importação ou exportação, é possível visualizar detalhes do job, incluindo: registros, na seção "Dataflow" do console do Google Cloud.

Mais detalhes do job do Dataflow

Para conferir os detalhes de qualquer job de importação ou exportação executado na última semana, incluindo os jobs que estão em execução no momento:

1. Navegue até a página Detalhes do banco de dados.
2. Clique no item de menu do painel esquerdo Importar/Exportar. A página Importar/Exportar do banco de dados exibe uma lista de jobs recentes.

3. Na página Importar/Exportar do banco de dados, clique no nome do job na coluna Nome do job do Dataflow:

   

   O console do Google Cloud exibe detalhes da API Dataflow trabalho.

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 Google Cloud.

   Acessar "Jobs"

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

   O console do Google Cloud exibe detalhes da API Dataflow trabalho.

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.

Visualizar os registros do Dataflow do job

Para conferir os registros de um job do Dataflow, acesse a página de detalhes dele e 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 Google Cloud mostra 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 abrir o conteúdo dela.

Para mais informações sobre como resolver problemas de jobs do Dataflow, consulte Resolver problemas do pipeline.

Resolver problemas de jobs de importação ou exportação

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 leitura/gravação de 99% na guia Monitoramento do banco de dados do Spanner no console do Google Cloud. Se forem mostrados valores altos (vários segundos), ela indica que a instância está sobrecarregada, e faz leituras e gravações tempo limite e falham.

Uma das causas de alta latência é a execução do job do Dataflow usar workers demais e sobrecarregar o Spanner instância.

Para especificar um limite no número de workers do Dataflow:

Console

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 usando um modelo.

Acessar o Dataflow

gcloud

Execute o gcloud dataflow jobs run. e especifique o argumento max-workers. Exemplo:

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

Resolver erros de rede

O erro a seguir pode ocorrer ao exportar seu Spanner bancos de dados:

Workflow failed. Causes: Error: Message: Invalid value for field
'resource.properties.networkInterfaces[0].subnetwork': ''. Network interface
must specify a subnet if the network resource is in custom subnet mode.
HTTP Code: 400

Esse erro ocorre porque o Spanner presume que você pretende usar uma rede VPC de modo automático chamada default no mesmo projeto do job do Dataflow. Se você não tiver uma rede VPC padrão no projeto ou se ela estiver em uma rede VPC no modo personalizado, será necessário criar um job do Dataflow e especificar uma rede ou sub-rede alternativa.

Otimizar jobs de importação ou exportaçã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 Dataflow na mesma região em que a instância do Spanner e do bucket do Cloud Storage estão localizados.

• Garanta recursos suficientes do Dataflow: se o cotas relevantes do Compute Engine limitar os recursos do job do Dataflow, Página do Dataflow no console do Google Cloud exibe um ícone de aviso e registrar mensagens:

  

  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 o uso da CPU do Spanner: caso a CPU uso da instância for superior a 65%, é possível aumentar a capacidade de computação da instância. A capacidade aumenta Os recursos do Spanner e o job devem acelerar, mas você incorre em mais Cobranças do Spanner.

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

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

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

• Esquema de banco de dados do Spanner, incluindo:

  • O número de tabelas
  • O tamanho das linhas
  • O número de índices secundários
  • O número de chaves estrangeiras
  • O número de fluxos de mudança

• Local dos dados: os dados são transferidos entre o 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: o número ideal de workers do Dataflow é necessário para um bom desempenho. Ao usar 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. O escalonamento automático pode sobrecarregar o Spanner, levando a erros quando há uma grande quantidade de dados para importar.

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

• Quantidade da capacidade de computação do Spanner: se a utilização da CPU para a instância for maior que 65%, o job será executado mais lentamente.

Ajustar os workers para ter um bom desempenho de importação

Ao iniciar um job de importação do Spanner, o Dataflow os workers precisam ser definidos com um valor ideal para ter um bom desempenho. Muitos workers sobrecarregam o Spanner, e poucos workers resultam em um desempenho de importação incrível.

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

Para atingir essa meta de utilização na maioria dos esquemas e 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 de 10 nós do Spanner, use n1-standard-2. workers, você definiria o máximo de workers como 25, ou seja, 50 vCPUs.