CSV 형식으로 데이터 가져오기 및 내보내기

이 페이지에서는 Cloud Spanner에서 CSV 파일로 데이터를 내보내거나 CSV 파일에서 Cloud Spanner 데이터베이스로 데이터를 가져오는 방법을 설명합니다.

이 프로세스는 Dataflow를 사용합니다. Cloud Spanner에서 Cloud Storage 버킷으로 데이터를 내보내거나 JSON 매니페스트 파일과 CSV 파일 집합이 포함된 Cloud Storage 버킷에서 Cloud Spanner로 데이터를 가져올 수 있습니다.

시작하기 전에

Cloud Spanner 데이터베이스를 가져오거나 내보내려면 먼저 Cloud Spanner, Cloud Storage, Compute Engine, Dataflow API를 사용 설정해야 합니다.

API 사용 설정

또한 충분한 할당량과 필수 IAM 권한이 필요합니다.

할당량 요구사항

Google Cloud 서비스별 가져오기 또는 내보내기 작업 할당량 요구사항은 다음과 같습니다.

  • Cloud Spanner: 가져올 데이터 양을 지원할 수 있는 충분한 노드가 있어야 합니다. 데이터베이스를 가져오거나 내보내는 데 노드가 추가로 필요하지는 않지만 적당한 시간 안에 작업을 마치려면 노드를 추가해야 할 수도 있습니다. 자세한 내용은 작업 최적화를 참조하세요.
  • Cloud Storage: 가져오려면 이전에 내보낸 파일이 포함된 버킷이 있어야 합니다. 내보내려면 내보낸 파일을 위한 버킷을 만들어야 합니다(아직 없는 경우). 이 작업은 Cloud Storage 페이지를 통해서 또는 Cloud Spanner 페이지를 통해 내보내기를 만드는 동안 Cloud Console에서 수행할 수 있습니다. 버킷의 크기를 설정할 필요는 없습니다.
  • Dataflow: 가져오기 또는 내보내기 작업에는 다른 Dataflow 작업과 동일한 CPU, 디스크 사용량, IP 주소 Compute Engine 할당량이 적용됩니다.
  • Compute Engine: 가져오기 또는 내보내기 작업을 실행하기 전에 Dataflow가 사용하는 Computer Engine의 초기 할당량을 설정해야 합니다. 이 할당량은 Dataflow가 작업에 사용할 수 있는 최대 리소스 수를 나타냅니다. 권장되는 시작 값은 다음과 같습니다.

    • CPU: 200
    • 사용 중인 IP 주소: 200
    • 표준 영구 디스크: 50TB

    일반적으로 다른 조정은 할 필요가 없습니다. Dataflow는 자동 확장을 제공하므로 가져오기 또는 내보내기 중에 사용된 실제 리소스에 대해서만 비용을 지불하면 됩니다. 작업에 더 많은 리소스가 사용될 수 있으면 Dataflow UI에 경고 아이콘이 표시됩니다. 경고 아이콘이 표시되더라도 작업은 완료됩니다.

IAM 요구사항

데이터베이스를 가져오거나 내보내려면 가져오기 또는 내보내기 작업과 관련된 모든 서비스를 사용할 수 있는 충분한 권한이 있는 IAM 역할도 있어야 합니다. 역할 및 권한 부여에 대해서는 IAM 역할 적용을 참조하세요.

데이터베이스를 가져오거나 내보내려면 다음 역할이 필요합니다.

  • Google Cloud 프로젝트 수준:
    • Cloud Spanner 뷰어
    • Dataflow 관리자
    • 스토리지 관리자
  • Cloud Spanner 데이터베이스 또는 인스턴스 수준 또는 Google Cloud 프로젝트 수준:
    • Cloud Spanner 리더
    • Cloud Spanner 데이터베이스 관리자(가져오기 작업에만 필요)

Cloud Spanner 데이터를 CSV 파일로 내보내기

Cloud Spanner에서 Cloud Storage의 CSV 파일로 데이터를 내보내려면 gcloud 명령줄 도구 사용 안내에 따라 Cloud Spanner to Cloud Storage 텍스트 템플릿을 사용하여 작업을 실행합니다.

작업 보기 또는 문제해결, 느린 작업 최적화, 작업 성능에 영향을 미치는 요소에 대한 이 문서의 정보를 참조할 수도 있습니다.

CSV 파일에서 Cloud Spanner로 데이터 가져오기

CSV 파일에서 데이터를 가져오는 프로세스에는 다음 단계가 포함됩니다.

  • CSV 파일로 데이터를 내보내고 Cloud Storage에 해당 파일을 저장합니다.
  • JSON 매니페스트 파일을 만들어 CSV 파일과 함께 저장합니다.
  • Cloud Spanner 데이터베이스에 빈 대상 테이블을 만들거나 CSV 파일에 있는 열의 데이터 유형이 기존 테이블의 해당 열과 일치하는지 확인합니다.
  • 가져오기 작업을 실행합니다.

Cloud Spanner 데이터베이스 이외의 데이터베이스에서 CSV 파일로 데이터 내보내기

가져오기 프로세스는 Cloud Storage 버킷에 있는 CSV 파일에서 데이터를 가져옵니다. CSV 형식의 데이터는 모든 소스에서 내보낼 수 있습니다.

데이터를 내보낼 때는 다음 사항에 유의하세요.

  • 가져올 텍스트 파일은 CSV 형식이어야 합니다.
  • 데이터는 다음 유형 중 하나와 일치해야 합니다.

    • INT64
    • FLOAT64
    • BOOL
    • STRING
    • DATE
    • TIMESTAMP
  • CSV 파일을 내보낼 때 메타데이터를 포함하거나 메타데이터를 생성할 필요가 없습니다.

  • 파일에서 특정 이름 지정 규칙을 따를 필요는 없습니다.

파일을 직접 Cloud Storage로 내보내지 않는 경우, Cloud Storage 버킷에 CSV 파일을 업로드해야 합니다.

JSON 매니페스트 파일 만들기

또한 가져올 파일에 대한 JSON 설명을 사용하여 매니페스트 파일을 만들고, CSV 파일을 저장한 Cloud Storage 버킷과 동일한 버킷에 이 파일을 넣어야 합니다. 이 매니페스트 파일에는 각 테이블의 이름과 데이터 파일 위치를 나열하는 tables 배열이 포함되어 있습니다.

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

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. Supports the
      // following data types: BOOL, INT64, FLOAT64, STRING, DATE, and TIMESTAMP.
      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;
}

다음 예시는 AlbumsSingers라는 테이블을 가져오기 위한 매니페스트 파일을 보여줍니다. 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"}
      ]
    }
  ]
}

Cloud Spanner 데이터베이스의 테이블 만들기

가져오기를 실행하기 전에 Cloud Spanner 데이터베이스에서 대상 테이블을 만들어야 합니다. 대상 Cloud Spanner 테이블에 이미 스키마가 있는 경우, 매니페스트 파일에서 지정된 모든 열에는 대상 테이블 스키마의 해당 열과 동일한 데이터 유형이 있어야 합니다.

gcloud를 사용하여 Dataflow 가져오기 작업 실행

가져오기 작업을 시작하려면 gcloud 명령줄 사용 안내에 따라 CSV to Cloud Spanner 템플릿을 사용하여 작업을 실행합니다.

가져오기 작업을 시작한 후에는 Cloud Console에서 작업에 대한 세부정보를 확인할 수 있습니다.

가져오기 작업이 완료된 후에 필요한 보조 색인외환 키를 추가합니다.

가져오기 작업의 리전 선택

Cloud Storage 버킷이 리전 구성을 사용하는지 멀티 리전 구성을 사용하는지에 따라 다른 리전을 선택해야 할 수도 있습니다. 네트워크 이그레스 요금을 방지하려면 Cloud Storage 버킷의 위치와 겹치는 리전을 선택하세요.

리전 버킷 위치

Cloud Storage 버킷 위치가 리전이며 해당 리전에서 무료 네트워크 사용량을 활용할 수 있는 경우, 가져오기 작업에 같은 리전을 선택하세요.

같은 리전을 사용할 수 없는 경우, 이그레스 요금이 적용됩니다. Cloud Storage 네트워크 이그레스 가격을 참조하여 네트워크 이그레스 요금이 가장 적은 리전을 선택하세요.

멀티 리전 버킷 위치

Cloud Storage 버킷 위치가 멀티 리전인 경우, 멀티 리전 위치를 구성하는 리전 중 하나를 선택하여 무료 네트워크 사용량을 활용하세요.

겹치는 리전을 사용할 수 없으면 이그레스 요금이 적용됩니다. Cloud Storage 네트워크 이그레스 가격 책정을 참조하여 네트워크 이그레스 요금이 가장 적은 리전을 선택하세요.

Dataflow UI에서 작업 보기 또는 문제해결

가져오기 또는 내보내기 작업을 시작한 후에는 Cloud Console의 Dataflow 섹션에서 로그를 비롯한 작업의 세부정보를 볼 수 있습니다.

Dataflow 작업 세부정보 보기

현재 실행 중인 작업의 세부정보를 보려면 다음을 수행합니다.

  1. 데이터베이스의 데이터베이스 세부정보 페이지로 이동합니다.
  2. 다음과 비슷한 작업 상태 메시지에서 Dataflow에서 작업 세부정보 보기를 클릭합니다.

    진행 중인 작업 상태 메시지

    Cloud Console에 Dataflow 작업의 세부정보가 표시됩니다.

최근에 실행한 작업을 보려면 다음을 수행합니다.

  1. 데이터베이스의 데이터베이스 세부정보 페이지로 이동합니다.
  2. 가져오기/내보내기 탭을 클릭합니다.
  3. 목록에서 작업의 이름을 클릭합니다.

    Cloud Console에 Dataflow 작업의 세부정보가 표시됩니다.

일주일 이상 전에 실행한 작업을 보려면 다음을 수행합니다.

  1. Cloud Console에서 Dataflow 작업 페이지로 이동합니다.

    작업 페이지로 이동

  2. 목록에서 작업을 찾은 다음 작업 이름을 클릭합니다.

    Cloud Console에 Dataflow 작업의 세부정보가 표시됩니다.

작업의 Dataflow 로그 보기

Dataflow 작업의 로그를 보려면 위에서 설명한대로 작업의 세부정보 페이지로 이동한 다음 작업 이름 오른쪽에 있는 로그를 클릭합니다.

작업이 실패한 경우 로그에서 오류를 찾습니다. 오류가 있으면 오류 개수가 로그 옆에 표시됩니다.

로그 버튼 옆의 오류 개수 예시

작업 오류를 보려면 다음을 수행합니다.

  1. 로그 옆에 있는 오류 개수를 클릭합니다.

    Cloud Console에 작업 로그가 표시됩니다. 오류를 보려면 스크롤해야 할 수도 있습니다.

  2. 오류 아이콘(오류 아이콘)이 있는 항목을 찾습니다.

  3. 개별 로그 항목을 클릭하여 내용을 펼칩니다.

Dataflow 작업 문제해결에 대한 자세한 내용은 파이프라인 문제해결을 참조하세요.

실패한 가져오기 또는 내보내기 작업 문제해결

작업 로그에 다음 오류가 표시되는 경우가 있습니다.

com.google.cloud.spanner.SpannerException: NOT_FOUND: Session not found

--or--

com.google.cloud.spanner.SpannerException: DEADLINE_EXCEEDED: Deadline expired before operation could complete.

Cloud Console에 있는 Cloud Spanner 데이터베이스의 모니터링 탭에서 99% 읽기/쓰기 지연 시간을 확인합니다. 높은 값(수 초)이 표시되면 인스턴스가 과부하되어 읽기/쓰기 제한 시간이 초과되고 실패했음을 나타냅니다.

지연 시간이 긴 이유 중 하나는 Dataflow 작업이 너무 많은 작업자를 사용해 실행되어 Cloud Spanner 인스턴스에 너무 많은 부하가 발생하기 때문입니다.

Dataflow 작업자 수를 지정하려면 다음 안내를 따르세요.
  • Dataflow Console을 사용할 경우 최대 작업자 매개변수는 템플릿에서 작업 만들기 페이지의 선택적 매개변수 섹션에 있습니다.

  • gcloud를 사용할 경우 max-workers 인수를 지정합니다. 예를 들면 다음과 같습니다.

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

최대 작업자 수는 데이터 크기에 따라 크게 달라지지만 총 Spanner CPU 사용률은 70~90%여야 합니다. 이렇게 하면 Spanner 효율성과 오류 없는 작업 완료 간의 균형을 잘 잡을 수 있습니다.

대부분의 스키마/시나리오에서 이러한 사용률 목표를 달성하려면 Spanner 노드 수의 4~6배에 해당하는 최대 작업자 vCPU 수를 사용하는 것이 좋습니다.

예를 들어 n1-standard-2 작업자를 사용하는 10노드 스패너 인스턴스의 경우 최대 작업자 수를 25로 설정하여 vCPU 50개를 제공합니다.

느리게 실행되는 가져오기 또는 내보내기 작업 최적화

초기 설정의 제안에 따랐다면 일반적으로 다른 조정이 필요 없습니다. 작업이 느리게 실행되는 경우에는 몇 가지 다른 최적화 방법을 시도할 수 있습니다.

  • 작업 및 데이터 위치 최적화: Cloud Spanner 인스턴스 및 Cloud Storage 버킷이 있는 리전과 동일한 리전에서 Dataflow 작업을 실행합니다.

  • 충분한 Dataflow 리소스 확보: 관련 Compute Engine 할당량에 따라 Dataflow 작업의 리소스가 제한되는 경우에는 Google Cloud Console에서 작업의 Dataflow 페이지에 경고 아이콘(경고 아이콘)과 로그 메시지가 표시됩니다.

    할당량 한도 경고 스크린샷

    이 경우 CPU, 사용 중인 IP 주소, 표준 영구 디스크의 할당량을 늘리면 작업 실행 시간이 단축될 수 있지만 Compute Engine 요금이 늘어날 수 있습니다.

  • Cloud Spanner CPU 사용률 확인: 인스턴스의 CPU 사용률이 65%를 초과하면 해당 인스턴스의 노드 수를 늘려볼 수 있습니다. 노드를 추가하면 Cloud Spanner 리소스가 늘어나고 작업 속도가 빨라지지만 Cloud Spanner 요금이 늘어납니다.

가져오기 또는 내보내기 작업 성능에 영향을 미치는 요인

가져오기 또는 내보내기 작업 완료에 걸리는 시간은 몇 가지 요소의 영향을 받습니다.

  • Cloud Spanner 데이터베이스 크기: 처리하는 데이터가 많을수록 시간과 리소스가 더 많이 소요됩니다.

  • Cloud Spanner 데이터베이스 스키마: 테이블 수, 행 크기, 보조 색인 수, 외래 키 수는 가져오기 또는 내보내기 작업을 실행하는 데 걸리는 시간에 영향을 줍니다.

  • 데이터 위치: 데이터는 Dataflow를 사용하여 Cloud Spanner와 Cloud Storage 간에 전송됩니다. 이 세 가지 구성요소가 같은 리전에 위치하는 것이 이상적입니다. 구성요소가 서로 다른 리전에 있으면 다른 리전으로 데이터를 이동하느라 작업 속도가 느려집니다.

  • Dataflow 작업자 수: Dataflow는 수행해야 할 작업량에 따라 자동 확장을 사용하여 작업의 작업자 수를 선택합니다. 하지만 작업자 수는 CPU, 사용 중인 IP 주소, 표준 영구 디스크의 할당량에 따라 제한을 받습니다. 할당량 한도에 도달하면 Dataflow UI에 경고 아이콘이 표시됩니다. 이러한 경우 진행 속도가 느려지지만 작업은 완료됩니다.

  • Cloud Spanner의 기존 부하: 가져오기 작업을 실행하면 Cloud Spanner 인스턴스에 CPU 부하가 상당히 늘어납니다. 일반적으로 내보내기 작업을 실행하면 Cloud Spanner 인스턴스에 부하가 약간 늘어납니다. 인스턴스에 이미 상당한 기존 부하가 있다면 작업 실행 속도가 더 느려집니다.

  • Cloud Spanner 노드 수: 인스턴스의 CPU 사용률이 65%를 초과하면 작업 실행 속도가 더 느려집니다.