Modello di testo Cloud Storage a Spanner

Il modello Cloud Storage Text to Spanner è una pipeline batch che legge file di testo CSV da Cloud Storage e li importa in un database Spanner.

Requisiti della pipeline

• Il database e la tabella Spanner di destinazione devono esistere.
• Devi disporre delle autorizzazioni di lettura per il bucket Cloud Storage e di scrittura per il database Spanner di destinazione.
• Il percorso Cloud Storage di input contenente i file CSV deve esistere.
• Devi creare un file manifest di importazione contenente una descrizione JSON dei file CSV e devi archiviarlo in Cloud Storage.
• Se il database Spanner di destinazione ha già uno schema, tutte le colonne specificate nel file manifest devono avere gli stessi tipi di dati delle colonne corrispondenti nello schema del database di destinazione.

• Il file manifest, codificato in ASCII o UTF-8, deve corrispondere al seguente formato:

  Formato e esempio del manifest

  Il formato del file manifest corrisponde al seguente tipo di messaggio, mostrato qui nel formato buffer di protocollo:

  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;
  }

  L'esempio seguente mostra un file manifest per l'importazione di tabelle denominate Albums e Singers in un database con dialetto GoogleSQL. La tabella Albums utilizza lo schema delle colonne recuperato dal job dal database, mentre la tabella Singers utilizza lo schema specificato dal file manifest:

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

• I file di testo da importare devono essere in formato CSV, con codifica ASCII o UTF-8. Ti consigliamo di non utilizzare il byte order mark (BOM) nei file codificati in UTF-8.
• I dati devono corrispondere a uno dei seguenti tipi:

  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

Parametri del modello

Parametri obbligatori

• instanceId: l'ID istanza del database Spanner.
• databaseId: l'ID database del database Spanner.
• importManifest: il percorso in Cloud Storage da utilizzare per importare i file manifest. Ad esempio, gs://your-bucket/your-folder/your-manifest.json.

Parametri facoltativi

• spannerHost: l'endpoint Cloud Spanner da chiamare nel modello. Utilizzato solo per i test. Ad esempio, https://batch-spanner.googleapis.com. Il valore predefinito è https://batch-spanner.googleapis.com.
• columnDelimiter: il delimitatore di colonna utilizzato dal file di origine. Il valore predefinito è ,. Ad esempio: ,.
• fieldQualifier: il carattere che deve racchiudere qualsiasi valore nel file di origine che contiene columnDelimiter. Il valore predefinito sono le virgolette doppie.
• trailingDelimiter: specifica se le righe nei file di origine hanno delimitatori finali, ovvero se il carattere columnDelimiter viene visualizzato alla fine di ogni riga, dopo l'ultimo valore della colonna. Il valore predefinito è true.
• escape: il carattere di escape utilizzato dal file di origine. Per impostazione predefinita, questo parametro non è impostato e il modello non utilizza il carattere di escape.
• nullString: la stringa che rappresenta un valore NULL. Per impostazione predefinita, questo parametro non è impostato e il modello non utilizza la stringa nulla.
• dateFormat: il formato utilizzato per analizzare le colonne di date. Per impostazione predefinita, la pipeline tenta di analizzare le colonne di date come yyyy-M-d[' 00:00:00'], ad esempio come 2019-01-31 o 2019-1-1 00:00:00. Se il formato della data è diverso, specifica il formato utilizzando i pattern java.time.format.DateTimeFormatter (https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/format/DateTimeFormatter.html).
• timestampFormat: il formato utilizzato per analizzare le colonne timestamp. Se il timestamp è un numero intero lungo, viene analizzato come tempo Unix epoch. In caso contrario, viene analizzato come stringa utilizzando il 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). Per altri casi, specifica la tua stringa di pattern, ad esempio utilizzando MMM dd yyyy HH:mm:ss.SSSVV per i timestamp nel formato Jan 21 1998 01:02:03.456+08:00.
• spannerProjectId: l'ID del progetto Google Cloud che contiene il database Spanner. Se non è impostato, viene utilizzato l'ID progetto del progetto Google Cloud predefinito.
• spannerPriority: la priorità della richiesta per le chiamate Spanner. I valori possibili sono HIGH, MEDIUM e LOW. Il valore predefinito è MEDIUM.
• handleNewLine: se true, i dati di input possono contenere caratteri di nuova riga. In caso contrario, i caratteri di nuova riga causano un errore. Il valore predefinito è false. L'attivazione della gestione dei caratteri di nuova riga può ridurre le prestazioni.
• invalidOutputPath: il percorso Cloud Storage da utilizzare per scrivere le righe che non possono essere importate. Ad esempio, gs://your-bucket/your-path. Il valore predefinito è vuoto.

Se devi utilizzare formati di data o timestamp personalizzati, assicurati che siano validi java.time.format.DateTimeFormatter pattern. La seguente tabella mostra altri esempi di formati personalizzati per le colonne di data e timestamp:

Esegui il modello

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

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