Cloud Storage Text to Spanner 템플릿

Cloud Storage Text to Spanner 템플릿은 Cloud Storage에서 CSV 텍스트 파일을 읽고 Spanner 데이터베이스로 가져오는 일괄 파이프라인입니다.

파이프라인 요구사항

대상 Spanner 데이터베이스와 테이블이 있어야 합니다.
Cloud Storage 버킷에 대한 읽기 권한과 대상 Spanner 데이터베이스에 대한 쓰기 권한이 있어야 합니다.
CSV 파일이 있는 입력 Cloud Storage 경로가 있어야 합니다.
CSV 파일에 대한 JSON 설명이 있는 가져오기 매니페스트 파일을 만들어야 하며 Cloud Storage에 해당 매니페스트 파일을 저장해야 합니다.
대상 Spanner 데이터베이스에 이미 스키마가 있는 경우 매니페스트 파일에 지정된 열의 데이터 유형이 대상 데이터베이스 스키마의 해당 열과 같아야 합니다.

ASCII 또는 UTF-8로 인코딩된 매니페스트 파일은 다음 형식과 일치해야 합니다.

매니페스트 형식 및 예시

매니페스트 파일의 형식은 프로토콜 버퍼 형식으로 여기 표시된 다음 메시지 유형에 해당합니다.

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

다음 예시는 Albums 및 Singers라는 테이블을 GoogleSQL 언어 데이터베이스로 가져오기 위한 매니페스트 파일을 보여줍니다. Albums 테이블은 작업이 데이터베이스에서 검색하는 열 스키마를 사용하고 Singers 테이블은 매니페스트 파일이 지정하는 스키마를 사용합니다.

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

가져올 텍스트 파일은 ASCII 또는 UTF-8 인코딩의 CSV 형식이어야 합니다. UTF-8 인코딩 파일에는 바이트 순서 표시(BOM)를 사용하지 않는 것이 좋습니다.

데이터는 다음 유형 중 하나와 일치해야 합니다.

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

참고: 가져오기 매니페스트 파일에서 대상 테이블의 열 이름과 데이터 유형을 지정하지 않으면 CSV 파일의 열과 대상 데이터베이스의 열 순서가 같아야 합니다. 다음 쿼리를 실행하여 테이블의 열 순서를 확인할 수 있습니다.

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

템플릿 매개변수

필수 매개변수

instanceId : Spanner 데이터베이스의 인스턴스 ID입니다.
databaseId : Spanner 데이터베이스의 데이터베이스 ID입니다.
importManifest: 매니페스트 파일을 가져올 때 사용할 Cloud Storage의 경로입니다. (예: gs://your-bucket/your-folder/your-manifest.json)

선택적 매개변수

spannerHost: 템플릿에서 호출할 Cloud Spanner 엔드포인트입니다. 테스트에만 사용됩니다. (예: https://batch-spanner.googleapis.com) 기본값은 https://batch-spanner.googleapis.com입니다.
columnDelimiter: 소스 파일이 사용하는 열 구분 기호입니다. 기본값은 ','입니다(예: ,).
fieldQualifier: columnDelimiter를 포함하는 소스 파일에서 모든 값 주변에 표시되어야 하는 문자입니다. 기본값은 "입니다.
trailingDelimiter: 소스 파일의 행에 후행 구분 기호가 있는지 여부를 지정합니다(즉, 마지막 열 값 다음에 각 행의 끝에 columnDelimiter 문자가 있는 경우). 기본값은 true입니다.
escape: 소스 파일이 사용하는 이스케이프 문자입니다. 기본적으로 이 매개변수는 설정되지 않으며 템플릿은 이스케이프 문자를 사용하지 않습니다.
nullString: NULL 값을 나타내는 문자열입니다. 기본적으로 이 매개변수는 설정되지 않으며 템플릿은 null 문자열을 사용하지 않습니다.
dateFormat: 날짜 열을 파싱하는 데 사용되는 형식입니다. 기본적으로 파이프라인은 날짜 열을 2019-01-31 또는 2019-1-1 00:00:00과 같이 yyyy-M-d[' 00:00:00']로 파싱합니다. 날짜 형식이 다른 경우에는 java.time.format.DateTimeFormatter(https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/format/DateTimeFormatter.html) 패턴을 사용하여 형식을 지정합니다.
timestampFormat: 타임스탬프 열을 파싱하는 데 사용되는 형식입니다. 타임스탬프가 긴 정수이면 유닉스 시간으로 파싱됩니다. 그렇지 않으면 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) 형식을 사용하는 문자열로 파싱됩니다. 아니면 "Jan 21 1998 01:02:03.456+08:00" 형식의 타임스탬프에 MMM dd yyyy HH:mm:ss.SSSVV를 사용하여 패턴 문자열을 직접 지정합니다.
spannerProjectId: Spanner 데이터베이스가 포함된 Google Cloud 프로젝트의 ID입니다. 설정하지 않으면 기본 Google Cloud 프로젝트의 프로젝트 ID가 사용됩니다.
spannerPriority: Spanner 호출의 요청 우선순위입니다. 가능한 값은 HIGH, MEDIUM, LOW입니다. 기본값은 MEDIUM입니다.
handleNewLine: true이면 입력 데이터에 줄바꿈 문자가 포함될 수 있습니다. 그렇지 않으면 줄바꿈 문자로 인해 오류가 발생합니다. 기본값은 false입니다. 줄바꿈 처리를 사용 설정하면 성능이 저하될 수 있습니다.
invalidOutputPath: 가져올 수 없는 행을 쓸 때 사용할 Cloud Storage 경로입니다. (예: gs://your-bucket/your-path) 기본값은 빈 값입니다.

맞춤설정된 날짜 또는 타임스탬프 형식을 사용해야 하는 경우 유효한 java.time.format.DateTimeFormatter 패턴인지 확인합니다. 다음 표는 날짜 및 타임스탬프 열에 맞춤설정된 형식의 다른 예시를 보여줍니다.

유형	값 입력	형식	설명
`DATE`	2011-3-31		기본적으로 템플릿은 이 형식을 파싱할 수 있습니다. `dateFormat` 매개변수를 지정할 필요가 없습니다.
`DATE`	2011-3-31 00:00:00		기본적으로 템플릿은 이 형식을 파싱할 수 있습니다. 형식을 지정할 필요가 없습니다. 원한다면 `yyyy-M-d' 00:00:00'`을 사용할 수 있습니다.
`DATE`	01 Apr, 18	dd MMM, yy
`DATE`	Wednesday, April 3, 2019 AD	EEEE, LLLL d, yyyy G
`TIMESTAMP`	2019-01-02T11:22:33Z 2019-01-02T11:22:33.123Z 2019-01-02T11:22:33.12356789Z		기본 형식 `ISO_INSTANT`가 이 유형의 타임스탬프를 파싱할 수 있습니다. `timestampFormat` 매개변수를 제공할 필요가 없습니다.
`TIMESTAMP`	1568402363		기본적으로 템플릿은 이 유형의 타임스탬프를 파싱하여 Unix epoch 시간으로 처리할 수 있습니다.
`TIMESTAMP`	Tue, 3 Jun 2008 11:05:30 GMT	EEE, d MMM yyyy HH:mm:ss VV
`TIMESTAMP`	2018/12/31 110530.123PST	yyyy/MM/dd HHmmss.SSSz
`TIMESTAMP`	2019-01-02T11:22:33Z 또는 2019-01-02T11:22:33.123Z	yyyy-MM-dd'T'HH:mm:ss[.SSS]VV	입력 열이 2019-01-02T11:22:33Z 및 2019-01-02T11:22:33.123Z의 조합인 경우 기본 형식은 이 유형의 타임스탬프를 파싱할 수 있습니다. 직접 형식 매개변수를 제공할 필요가 없습니다. 하지만 `yyyy-MM-dd'T'HH:mm:ss[.SSS]VV`를 사용하면 두 경우 모두 처리할 수 있습니다. 포스트픽스 'Z'는 문자 리터럴이 아닌 시간대 ID로 파싱해야 하므로 `yyyy-MM-dd'T'HH:mm:ss[.SSS]'Z'`를 사용할 수 없습니다. 내부적으로 타임스탬프 열이 `java.time.Instant`로 변환됩니다. 따라서 UTC로 지정하거나 시간대 정보를 연결해야 합니다. 2019-01-02 11:22:33 같은 현지 날짜/시간은 유효한 `java.time.Instant`로 파싱할 수 없습니다.

템플릿 실행

콘솔

Dataflow 템플릿에서 작업 만들기 페이지로 이동합니다.

템플릿에서 작업 만들기로 이동

작업 이름 필드에 고유한 작업 이름을 입력합니다.
(선택사항): 리전 엔드포인트의 드롭다운 메뉴에서 값을 선택합니다. 기본 리전은 us-central1입니다.
Dataflow 작업을 실행할 수 있는 리전 목록은 Dataflow 위치를 참조하세요.
Dataflow 템플릿 드롭다운 메뉴에서 the Text Files on Cloud Storage to Cloud Spanner template을 선택합니다.
제공된 매개변수 필드에 매개변수 값을 입력합니다.
작업 실행을 클릭합니다.

gcloud

셸 또는 터미널에서 템플릿을 실행합니다.

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

다음을 바꿉니다.

JOB_NAME: 선택한 고유한 작업 이름
VERSION: 사용할 템플릿 버전
다음 값을 사용할 수 있습니다.
- latest: 버킷의 날짜가 지정되지 않은 상위 폴더(gs://dataflow-templates-REGION_NAME/latest/)에서 사용할 수 있는 최신 버전의 템플릿을 사용합니다.
- 버전 이름(예: 2023-09-12-00_RC00): 버킷의 날짜가 지정된 해당 상위 폴더(gs://dataflow-templates-REGION_NAME/)에 중첩되어 있는 특정 버전의 템플릿을 사용합니다.
주의: 최신 버전의 템플릿이 브레이킹 체인지로 업데이트될 수 있습니다. 프로덕션 환경에서는 이러한 브레이킹 체인지가 프로덕션 워크플로에 영향을 미치지 않도록 최신 날짜가 지정된 상위 폴더에 보관된 템플릿을 사용해야 합니다.
REGION_NAME: Dataflow 작업을 배포할 리전(예: us-central1)
INSTANCE_ID: Spanner 인스턴스 ID
DATABASE_ID: Spanner 데이터베이스 ID
GCS_PATH_TO_IMPORT_MANIFEST: 가져오기 매니페스트 파일의 Cloud Storage 경로

API

REST API를 사용하여 템플릿을 실행하려면 HTTP POST 요청을 전송합니다. API 및 승인 범위에 대한 자세한 내용은 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"
   }
}

다음을 바꿉니다.

PROJECT_ID: Dataflow 작업을 실행하려는 Google Cloud 프로젝트 ID
JOB_NAME: 선택한 고유한 작업 이름
VERSION: 사용할 템플릿 버전
다음 값을 사용할 수 있습니다.
- latest: 버킷의 날짜가 지정되지 않은 상위 폴더(gs://dataflow-templates-REGION_NAME/latest/)에서 사용할 수 있는 최신 버전의 템플릿을 사용합니다.
- 버전 이름(예: 2023-09-12-00_RC00): 버킷의 날짜가 지정된 해당 상위 폴더(gs://dataflow-templates-REGION_NAME/)에 중첩되어 있는 특정 버전의 템플릿을 사용합니다.
주의: 최신 버전의 템플릿이 브레이킹 체인지로 업데이트될 수 있습니다. 프로덕션 환경에서는 이러한 브레이킹 체인지가 프로덕션 워크플로에 영향을 미치지 않도록 최신 날짜가 지정된 상위 폴더에 보관된 템플릿을 사용해야 합니다.
LOCATION: Dataflow 작업을 배포할 리전(예: us-central1)
INSTANCE_ID: Spanner 인스턴스 ID
DATABASE_ID: Spanner 데이터베이스 ID
GCS_PATH_TO_IMPORT_MANIFEST: 가져오기 매니페스트 파일의 Cloud Storage 경로

템플릿 소스 코드

자바

이 템플릿의 소스 코드는 GitHub의 GoogleCloudPlatform/DataflowTemplates 저장소에 있습니다.

다음 단계

Dataflow 템플릿 알아보기
Google 제공 템플릿 목록 참조