Importe e exporte dados no formato CSV

Esta página descreve como exportar dados do Spanner para ficheiros CSV ou importar dados de ficheiros CSV para bases de dados com o dialeto GoogleSQL ou com o dialeto PostgreSQL do Spanner.

O processo usa o Dataflow. Pode exportar dados do Spanner para um contentor do Cloud Storage ou importar dados para o Spanner a partir de um contentor do Cloud Storage que contenha um ficheiro de manifesto JSON e um conjunto de ficheiros CSV.

Antes de começar

Para importar ou exportar uma base de dados do Spanner, primeiro, tem de ativar as APIs Spanner, Cloud Storage, Compute Engine e Dataflow:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

Também precisa de quota suficiente e das autorizações de IAM necessárias.

Requisitos de quota

Os requisitos de quota para tarefas de importação ou exportação são os seguintes:

  • Spanner: tem de ter capacidade de computação suficiente para suportar a quantidade de dados que está a importar. Não é necessária capacidade de computação adicional para importar ou exportar uma base de dados, embora possa ter de adicionar mais capacidade de computação para que a tarefa termine num período razoável. Consulte o artigo Otimize tarefas para ver mais detalhes.
  • Cloud Storage: para importar, tem de ter um contentor com os ficheiros exportados anteriormente. Para exportar, tem de criar um contentor para os ficheiros exportados se ainda não tiver um. Pode fazê-lo na Google Cloud consola, através da página do Cloud Storage ou durante a criação da exportação através da página do Spanner. Não precisa de definir um tamanho para o seu contentor.
  • Dataflow: as tarefas de importação ou exportação estão sujeitas às mesmas quotas de CPU, utilização do disco e endereço IP do Compute Engine que outras tarefas do Dataflow.

  • Compute Engine: antes de executar a tarefa de importação ou exportação, tem de configurar quotas iniciais para o Compute Engine, que o Dataflow usa. Estas quotas representam o número máximo de recursos que permite que o Dataflow use para a sua tarefa. Os valores iniciais recomendados são:

    • CPUs: 200
    • Endereços IP em utilização: 200
    • Disco persistente padrão: 50 TB

    Geralmente, não tem de fazer outros ajustes. O Dataflow oferece o dimensionamento automático para que só pague pelos recursos reais usados durante a importação ou a exportação. Se o seu trabalho puder usar mais recursos, a IU do Dataflow apresenta um ícone de aviso. A tarefa deve terminar mesmo que exista um ícone de aviso.

Funções necessárias

Para receber as autorizações de que precisa para exportar uma base de dados, peça ao seu administrador para lhe conceder as seguintes funções do IAM na conta de serviço do trabalhador do Dataflow:

Exporte dados do Spanner para ficheiros CSV

Para exportar dados do Spanner para ficheiros CSV no Cloud Storage, siga as instruções para usar a Google Cloud CLI para executar uma tarefa com o modelo de texto do Spanner para o Cloud Storage.

Também pode consultar as informações nesta página sobre a otimização de tarefas lentas e os fatores que afetam o desempenho das tarefas.

Importe dados de ficheiros CSV para o Spanner

O processo de importação de dados de ficheiros CSV inclui os seguintes passos:

  1. Exporte os seus dados para ficheiros CSV e armazene-os no Cloud Storage. Não inclua uma linha de cabeçalho.
  2. Crie um ficheiro de manifesto JSON e armazene-o juntamente com os ficheiros CSV.
  3. Crie tabelas de destino vazias na sua base de dados do Spanner ou certifique-se de que os tipos de dados das colunas nos seus ficheiros CSV correspondem a quaisquer colunas correspondentes nas suas tabelas existentes.
  4. Execute a tarefa de importação.

Passo 1: exporte dados de uma base de dados não pertencente ao Spanner para ficheiros CSV

O processo de importação transfere dados de ficheiros CSV localizados num contentor do Cloud Storage. Pode exportar dados em formato CSV de qualquer origem.

Tenha em atenção o seguinte quando exportar os seus dados:

  • Os ficheiros de texto a importar têm de estar no formato CSV.

  • Os dados têm de corresponder a um dos seguintes tipos:

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 tem de incluir nem gerar metadados quando exporta os ficheiros CSV.

  • Não tem de seguir nenhuma convenção de nomenclatura específica para os seus ficheiros.

Se não exportar os ficheiros diretamente para o Cloud Storage, tem de carregar os ficheiros CSV para um contentor do Cloud Storage.

Passo 2: crie um ficheiro do manifesto JSON

Também tem de criar um ficheiro de manifesto com uma descrição JSON dos ficheiros a importar e colocá-lo no mesmo contentor do Cloud Storage onde armazenou os ficheiros CSV. Este ficheiro de manifesto contém uma matriz tables que lista o nome e as localizações dos ficheiros de dados para cada tabela. O ficheiro também especifica o dialeto da base de dados de receção. Se o dialeto for omitido, a predefinição é GoogleSQL.

O formato do ficheiro do manifesto corresponde ao seguinte tipo de mensagem, apresentado aqui no formato de protocol buffer: 

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 seguinte mostra um ficheiro de manifesto para importar tabelas denominadas Albums e Singers para uma base de dados de dialeto GoogleSQL. A tabela Albums usa o esquema de colunas que a tarefa obtém da base de dados, e a tabela Singers usa o esquema que o ficheiro de manifesto especifica: 

{
  "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"}
      ]
    }
  ]
}

Passo 3: crie a tabela para a sua base de dados do Spanner

Antes de executar a importação, tem de criar as tabelas de destino na base de dados do Spanner. Se a tabela do Spanner de destino já tiver um esquema, todas as colunas especificadas no ficheiro de manifesto têm de ter os mesmos tipos de dados que as colunas correspondentes no esquema da tabela de destino.

Recomendamos que crie índices secundários, chaves externas e streams de alterações depois de importar os dados para o Spanner e não quando cria inicialmente a tabela. Se a sua tabela já contiver estas estruturas, recomendamos que as elimine e as recrie depois de importar os dados.

Passo 4: execute uma tarefa de importação do Dataflow através do gcloud

Para iniciar a tarefa de importação, siga as instruções para usar a CLI do Google Cloud para executar uma tarefa com o modelo de texto do Cloud Storage para o Spanner.

Depois de iniciar uma tarefa de importação, pode ver detalhes sobre a tarefa na consola. Google Cloud

Após a conclusão da tarefa de importação, adicione os índices secundários, chaves externas e fluxos de alterações necessários.

Escolha uma região para a tarefa de importação

Recomendamos que escolha uma região diferente com base na localização do seu contentor do Cloud Storage. Para evitar custos de transferência de dados de saída, escolha uma região que corresponda à localização do seu contentor do Cloud Storage.

  • Se a localização do seu contentor do Cloud Storage for uma região, pode tirar partido da utilização da rede sem custo financeiro escolhendo a mesma região para a sua tarefa de importação, desde que essa região esteja disponível.

  • Se a localização do seu contentor do Cloud Storage for uma região dupla, pode tirar partido da utilização da rede gratuita escolhendo uma das duas regiões que compõem a região dupla para a sua tarefa de importação, partindo do princípio de que uma das regiões está disponível.

  • Se não estiver disponível uma região de colocação conjunta para a sua tarefa de importação ou se a localização do contentor do Cloud Storage for uma multirregião, aplicam-se custos 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 nos custos de transferência de dados mais baixos.

Veja ou resolva problemas de tarefas na IU do Dataflow

Depois de iniciar uma tarefa de importação ou exportação, pode ver os detalhes da tarefa, incluindo registos, na secção Dataflow da Google Cloud consola.

Veja os detalhes das tarefas do Dataflow

Para ver os detalhes de todas as tarefas de importação ou exportação que executou na última semana, incluindo as tarefas que estão a ser executadas agora:

  1. Navegue para a página Vista geral da base de dados da base de dados.
  2. Clique no item de menu do painel esquerdo Importar/Exportar. A página Importar/Exportar da base de dados apresenta uma lista de tarefas recentes.

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

    Mensagem de estado da tarefa em curso

    A Google Cloud consola apresenta detalhes da tarefa do Dataflow.

Para ver uma tarefa que executou há mais de uma semana:

  1. Aceda à página de tarefas do Dataflow na Google Cloud consola.

    Aceda a Empregos

  2. Encontre o seu trabalho na lista e, de seguida, clique no respetivo nome.

    A Google Cloud consola apresenta detalhes da tarefa do Dataflow.

Veja os registos do Dataflow para a sua tarefa

Para ver os registos de uma tarefa do Dataflow, navegue para a página de detalhes da tarefa e, de seguida, clique em Registos à direita do nome da tarefa.

Se uma tarefa falhar, procure erros nos registos. Se existirem erros, a quantidade de erros é apresentada junto a Registos:

Exemplo de contagem de erros junto ao botão Registos

Para ver erros de tarefas:

  1. Clique na contagem de erros junto a Registos.

    A Google Cloud consola apresenta os registos da tarefa. Pode ter de deslocar a página para ver os erros.

  2. Localize as entradas com o ícone de erro Ícone de erro.

  3. Clique numa entrada de registo individual para expandir o respetivo conteúdo.

Para mais informações sobre a resolução de problemas de tarefas do Dataflow, consulte o artigo Resolva problemas do seu pipeline.

Resolva problemas de tarefas de importação ou exportação com falhas

Se vir os seguintes erros nos registos de tarefas:

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/escrita de 99% no separador Monitorização da sua base de dados do Spanner na Google Cloud consola. Se estiver a apresentar valores elevados (vários segundos), significa que a instância está sobrecarregada, o que faz com que as leituras/escritas excedam o limite de tempo e falhem.

Uma das causas da latência elevada é o facto de a tarefa do Dataflow estar a ser executada com demasiados trabalhadores, o que coloca uma carga excessiva na instância do Spanner.

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

Consola

Se estiver a usar a consola do Dataflow, o parâmetro Max workers está localizado na secção Parâmetros opcionais da página Criar tarefa a partir de um modelo.

Aceda ao Dataflow

gcloud

Execute o comando gcloud dataflow jobs run e especifique o argumento max-workers. Por 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

Resolva problemas de erro de rede

Pode ocorrer o seguinte erro quando exporta as suas bases de dados do Spanner:

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

Este erro ocorre porque o Spanner assume que pretende usar uma rede VPC no modo automático denominada default no mesmo projeto que a tarefa do Dataflow. Se não tiver uma rede VPC predefinida no projeto ou se a sua rede VPC estiver numa rede VPC de modo personalizado, tem de criar uma tarefa do Dataflow e especificar uma rede ou uma sub-rede alternativa.

Otimize tarefas de importação ou exportação de execução lenta

Se seguiu as sugestões nas definições iniciais, geralmente, não tem de fazer outros ajustes. Se o seu trabalho estiver a ser executado lentamente, existem algumas outras otimizações que pode experimentar:

  • Otimize a tarefa e a localização dos dados: execute a tarefa do Dataflow na mesma região onde se encontram a instância do Spanner e o contentor do Cloud Storage.

  • Garanta recursos suficientes do Dataflow: se as quotas relevantes do Compute Engine limitarem os recursos da tarefa do Dataflow, a página do Dataflow na Google Cloud consola apresenta um ícone de aviso Ícone de aviso e mensagens de registo:

    Captura de ecrã do aviso de limite de quota

    Nesta situação, aumentar as quotas para CPUs, endereços IP em utilização e disco persistente padrão pode reduzir o tempo de execução da tarefa, mas pode incorrer em mais encargos do Compute Engine.

  • Verifique a utilização da CPU do Spanner: se verificar que a utilização da CPU da instância é superior a 65%, pode aumentar a capacidade de computação nessa instância. A capacidade adiciona mais recursos do Spanner e o trabalho deve acelerar, mas incorre em mais encargos do Spanner.

Fatores que afetam o desempenho da tarefa de importação ou exportação

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

  • Tamanho da base de dados do Spanner: o processamento de mais dados demora mais tempo e requer mais recursos.

  • Esquema da base 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 externas
    • O número de streams de alterações

  • Localização dos dados: os dados são transferidos entre o Spanner e o Cloud Storage através do Dataflow. Idealmente, todos os três componentes estão localizados na mesma região. Se os componentes não estiverem na mesma região, a movimentação dos dados entre regiões torna a tarefa mais lenta.

  • Número de trabalhadores do Dataflow: os trabalhadores do Dataflow ideais são necessários para um bom desempenho. Ao usar o dimensionamento automático, o Dataflow escolhe o número de trabalhadores para a tarefa, consoante a quantidade de trabalho que tem de ser feito. No entanto, o número de trabalhadores é limitado pelas quotas de CPUs, endereços IP em utilização e disco persistente padrão. A IU do Dataflow apresenta um ícone de aviso se encontrar limites máximos de quota. Nesta situação, o progresso é mais lento, mas a tarefa deve ser concluída na mesma. O dimensionamento automático pode sobrecarregar o Spanner, o que leva a erros quando existe uma grande quantidade de dados a importar.

  • Carga existente no Spanner: uma tarefa de importação adiciona uma carga significativa da CPU a uma instância do Spanner. Normalmente, uma tarefa de exportação adiciona uma carga ligeira a uma instância do Spanner. Se a instância já tiver uma carga existente substancial, a tarefa é executada mais lentamente.

  • Quantidade de capacidade de computação do Spanner: se a utilização da CPU da instância for superior a 65%, a tarefa é executada mais lentamente.

Ajuste os trabalhadores para um bom desempenho da importação

Ao iniciar uma tarefa de importação do Spanner, os trabalhadores do Dataflow têm de ser definidos para um valor ideal para um bom desempenho. Demasiados trabalhadores sobrecarregam o Spanner e muito poucos trabalhadores resultam num desempenho de importação insatisfatório.

O número máximo de trabalhadores depende muito do tamanho dos dados, mas, idealmente, a utilização total da CPU do Spanner deve estar entre 70% e 90%. Isto oferece um bom equilíbrio entre a eficiência do Spanner e a conclusão de tarefas sem erros.

Para alcançar esse objetivo 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 do Spanner de 10 nós, usando trabalhadores n1-standard-2, definiria o número máximo de trabalhadores como 25, o que daria 50 vCPUs.