Modelo do Cloud Storage Text para Spanner

O modelo do Cloud Storage Text para Spanner é um pipeline em lote que lê arquivos de texto CSV do Cloud Storage e os importa para um banco de dados do Cloud Spanner.

Requisitos de pipeline

• O banco de dados e a tabela de destino do Spanner precisam existir.
• É necessário ter permissões de leitura para o bucket do Cloud Storage e permissões de gravação para o banco de dados de destino do Spanner.
• O caminho do Cloud Storage que contém os arquivos CSV precisa existir.
• Você precisa criar um arquivo de manifesto de importação com uma descrição em JSON dos arquivos CSV e armazenar esse arquivo de manifesto no Cloud Storage.
• Se o banco de dados de destino do Spanner já tiver um esquema, todas as colunas especificadas no arquivo de manifesto precisam ter os mesmos tipos de dados das colunas correspondentes no esquema do banco de dados de destino.

• O arquivo de manifesto, codificado em ASCII ou UTF-8, precisa ter o formato a seguir:

  Exemplo e formato do manifesto

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

• Os arquivos de texto a serem importados precisam estar no formato CSV, com codificação ASCII ou UTF-8. Recomendamos não usar a marca de ordem de byte (BOM) em arquivos codificados em UTF-8.
• 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

Observação: caso o nome das colunas e os tipos de dados da tabela de destino não sejam especificados no arquivo de manifesto de importação, as colunas dos arquivos CSV precisam estar na mesma ordem que as colunas na base de dados de destino. Para verificar a ordem das colunas na tabela, execute a consulta a seguir:

SELECT * FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_NAME =
      TABLE_NAME ORDER BY ORDINAL_POSITION

Aviso: se o banco de dados de destino do Cloud Spanner não estiver vazio, os novos dados poderão substituir dados atuais.

Parâmetros do modelo

Parâmetros obrigatórios

• instanceId: o ID da instância referente ao banco de dados do Spanner.
• databaseId: o ID do banco de dados referente ao banco de dados do Spanner.
• importManifest: o caminho no Cloud Storage a ser usado na importação de arquivos de manifesto. Por exemplo: gs://your-bucket/your-folder/your-manifest.json.

Parâmetros opcionais

• spannerHost: opcional: o endpoint do Cloud Spanner para chamar no modelo. Usado apenas para testes. Por exemplo: https://batch-spanner.googleapis.com. O padrão é: https://batch-spanner.googleapis.com.
• columnDelimiter: o delimitador de coluna usado pelo arquivo de origem. O valor padrão é ','. (Exemplo: ,).
• fieldQualifier: o caractere que precisa cercar qualquer valor no arquivo de origem que contém o columnDelimiter. O valor padrão é ".
• trailingDelimiter: especifica se as linhas dos arquivos de origem têm delimitadores à direita, ou seja, se o caractere columnDelimiter aparece no final de cada linha, depois do último valor da coluna. O valor padrão é true.
• escape: o caractere de escape usado pelo arquivo de origem. Por padrão, esse parâmetro não está definido e o modelo não usa o caractere de escape.
• nullString: a string que representa um valor NULL. Por padrão, esse parâmetro não está definido e o modelo não usa a string nula.
• dateFormat: o formato usado para analisar as colunas de data. Por padrão, o pipeline tenta analisar as colunas de data como yyyy-M-d[' 00:00:00'], por exemplo, como 2019-01-31 ou 2019-1-1 00:00:00. Se o formato de data for diferente, especifique o formato usando java.time.format.DateTimeFormatter (https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/format/DateTimeFormatter.html).
• timestampFormat: o formato usado para analisar colunas de carimbo de data/hora. Se o carimbo de data/hora for um número inteiro longo, ele será analisado como um horário na época Unix. Caso contrário, ele será analisado como uma string usando o formato java.time.format.DateTimeFormatter.ISO_INSTANT (https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/format/DateTimeFormatter.html#ISO_INSTANT). Para outros casos, especifique sua própria string padrão usando, por exemplo, MMM dd yyyy HH:mm:ss.SSSVV para carimbos de data/hora na forma de "Jan 21 1998 01:02:03.456+08:00".
• spannerProjectId: o ID do projeto do Google Cloud que contém o banco de dados do Spanner. Se não for definido, o ID do projeto padrão do Google Cloud será usado.
• spannerPriority: a prioridade de solicitação das chamadas do Spanner. Os valores permitidos são HIGH (alto), MEDIUM (médio) e LOW (baixo). Por padrão, a frequência selecionada é MEDIUM (média).
• handleNewLine: se definido como true, os dados de entrada poderão conter caracteres de feed de linha. Caso contrário, os caracteres de nova linha causarão um erro. O valor padrão é false. A ativação do processamento de feed de linha pode reduzir o desempenho.
• invalidOutputPath: o caminho do Cloud Storage a ser usado na gravação de linhas que não podem ser importadas. (Exemplo: gs://your-bucket/your-path). O padrão é vazio.

Se você precisar usar formatos personalizados de data ou carimbos de data/hora, confirme se eles são padrões java.time.format.DateTimeFormatter válidos. A tabela a seguir mostra mais exemplos de formatos personalizados de colunas de data e carimbo de data/hora:

Tipo	Valor de entrada	Formato	Remark
DATE	2011-3-31		O modelo pode analisar esse formato por padrão. Não é necessário especificar o parâmetro dateFormat.
DATE	2011-3-31 00:00:00		O modelo pode analisar esse formato por padrão. Não é necessário especificar o formato. Se preferir, use yyyy-M-d' 00:00:00'.
DATE	1º de abril de 2018	dd MMM, aa
DATE	Quarta-feira, 3 de abril de 2019 AD	EEEE, LLLL d, aaaa G
TIMESTAMP	2019-01-02T11:22:33Z 2019-01-02T11:22:33.123Z 2019-01-02T11:22:33.12356789Z		O formato padrão ISO_INSTANT pode analisar esse tipo de carimbo de data/hora. Não é necessário informar o parâmetro timestampFormat.
TIMESTAMP	1568402363		Por padrão, o modelo pode analisar esse tipo de carimbo de data/hora como o horário Unix da era Unix.
TIMESTAMP	Ter, 3 jun 2008 11:05:30 GMT	EEE, d MMM aaaa HH:mm:ss VV
TIMESTAMP	2018/12/31 110530.123PST	aaaa/MM/dd HHmmss.SSSz
TIMESTAMP	2019-01-02T11:22:33Z ou 2019-01-02T11:22:33.123Z	yyyy-MM-dd'T'HH:mm:ss[.SSS]VV	Se a coluna de entrada for uma combinação de 2019-01-02T11:22:33Z e 2019-01-02T11:22:33.123Z, o formato padrão poderá analisar esse tipo de carimbo de data/hora. Não é necessário fornecer seu próprio parâmetro de formato. Use yyyy-MM-dd'T'HH:mm:ss[.SSS]VV para lidar com os dois casos. Observe que não é possível usar yyyy-MM-dd'T'HH:mm:ss[.SSS]'Z', porque o postfix "Z" precisa ser analisado como um ID de fuso horário, não um caractere literal. Internamente, a coluna de carimbo de data/hora é convertida em java.time.Instant. Portanto, ele precisa ser especificado em UTC ou ter informações de fuso horário associadas a ele. A data/hora local, como 2019-01-02 11:22:33, não pode ser analisada como um java.time.Instant válido.

Executar o modelo

Console

1. Acesse a página Criar job usando um modelo do Dataflow.
Acesse Criar job usando um modelo
2. No campo Nome do job, insira um nome exclusivo.
3. Opcional: em Endpoint regional, selecione um valor no menu suspenso. A região padrão é us-central1.

   Para ver uma lista de regiões em que é possível executar um job do Dataflow, consulte Locais do Dataflow.

4. No menu suspenso Modelo do Dataflow, selecione the Text Files on Cloud Storage to Cloud Spanner template.
5. Nos campos de parâmetro fornecidos, insira os valores de parâmetro.
6. Cliquem em Executar job.

gcloud

Observação: para usar a Google Cloud CLI para executar modelos classic você precisa ter a Google Cloud CLI na versão 138.0.0 ou mais recente.

No shell ou no terminal, execute o modelo:

gcloud dataflow jobs run JOB_NAME \
    --gcs-location gs://dataflow-templates-REGION_NAME/VERSION/GCS_Text_to_Cloud_Spanner \
    --region REGION_NAME \
    --parameters \
instanceId=INSTANCE_ID,\
databaseId=DATABASE_ID,\
importManifest=GCS_PATH_TO_IMPORT_MANIFEST

Substitua:

• JOB_NAME: um nome de job de sua escolha
• VERSION: a versão do modelo que você quer usar

  Use estes valores:

  • latest para usar a versão mais recente do modelo, disponível na pasta mãe não datada no bucket: gs://dataflow-templates-REGION_NAME/latest/
  • o nome da versão, como 2023-09-12-00_RC00, para usar uma versão específica do modelo, que pode ser encontrada aninhada na respectiva pasta mãe datada no bucket: gs://dataflow-templates-REGION_NAME/
  Cuidado: é possível que a versão mais recente dos modelos seja atualizada com alterações interruptivas. Os ambientes de produção precisam usar os modelos mantidos na pasta mãe datada mais recente para evitar que essas alterações interruptivas afetem os fluxos de trabalho de produção.
• REGION_NAME: a região em que você quer implantar o job do Dataflow, por exemplo, us-central1
• INSTANCE_ID: o ID da instância do Spanner
• DATABASE_ID: o ID do banco de dados do Spanner
• GCS_PATH_TO_IMPORT_MANIFEST: o caminho do Cloud Storage para o arquivo de manifesto de importação.

API

Para executar o modelo usando a API REST, envie uma solicitação HTTP POST. Para mais informações sobre a API e os respectivos escopos de autorização, consulte projects.templates.launch.

POST https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/LOCATION/templates:launch?gcsPath=gs://dataflow-templates-LOCATION/VERSION/GCS_Text_to_Cloud_Spanner
{
   "jobName": "JOB_NAME",
   "parameters": {
       "instanceId": "INSTANCE_ID",
       "databaseId": "DATABASE_ID",
       "importManifest": "GCS_PATH_TO_IMPORT_MANIFEST"
   },
   "environment": {
       "machineType": "n1-standard-2"
   }
}

Substitua:

• PROJECT_ID: o ID do projeto do Google Cloud em que você quer executar o job do Dataflow
• JOB_NAME: um nome de job de sua escolha
• VERSION: a versão do modelo que você quer usar

  Use estes valores:

  • latest para usar a versão mais recente do modelo, disponível na pasta mãe não datada no bucket: gs://dataflow-templates-REGION_NAME/latest/
  • o nome da versão, como 2023-09-12-00_RC00, para usar uma versão específica do modelo, que pode ser encontrada aninhada na respectiva pasta mãe datada no bucket: gs://dataflow-templates-REGION_NAME/
  Cuidado: é possível que a versão mais recente dos modelos seja atualizada com alterações interruptivas. Os ambientes de produção precisam usar os modelos mantidos na pasta mãe datada mais recente para evitar que essas alterações interruptivas afetem os fluxos de trabalho de produção.
• LOCATION: a região em que você quer implantar o job do Dataflow, por exemplo, us-central1
• INSTANCE_ID: o ID da instância do Spanner
• DATABASE_ID: o ID do banco de dados do Spanner
• GCS_PATH_TO_IMPORT_MANIFEST: o caminho do Cloud Storage para o arquivo de manifesto de importação.

Código-fonte do modelo

Java

O código-fonte do modelo está disponível no GitHub, dentro do repositório GoogleCloudPlatform/DataflowTemplates.

A seguir

• Saiba mais sobre os modelos do Dataflow.
• Confira a lista de modelos fornecidos pelo Google.