Mengimpor dan mengekspor data dalam format CSV

Halaman ini menjelaskan cara mengekspor data dari Spanner ke file CSV atau mengimpor data dari file CSV ke database dialek GoogleSQL Spanner atau database dialek PostgreSQL.

• Jika Anda ingin mengimpor database Spanner yang sebelumnya diekspor ke file Avro di Cloud Storage, lihat Mengimpor file Avro Spanner.
• Jika Anda ingin mengimpor file Avro dari database non-Spanner, lihat Mengimpor data dari database non-Spanner.

Proses ini menggunakan Dataflow. Anda dapat mengekspor data dari Spanner ke bucket Cloud Storage, atau mengimpor data ke Spanner dari bucket Cloud Storage yang berisi file manifes JSON dan kumpulan file CSV.

Catatan: Untuk menjelajahi Spanner menggunakan instance uji coba gratis selama 90 hari, lihat Membuat instance uji coba gratis Spanner.

Sebelum memulai

Untuk mengimpor atau mengekspor database Spanner, Anda harus mengaktifkan Spanner, Cloud Storage, Compute Engine, dan Dataflow API terlebih dahulu:

Peran yang diperlukan untuk mengaktifkan API

Untuk mengaktifkan API, Anda memerlukan peran IAM Service Usage Admin (roles/serviceusage.serviceUsageAdmin), yang berisi izin serviceusage.services.enable. Pelajari cara memberikan peran.

Aktifkan API

Anda juga memerlukan kuota yang cukup dan izin IAM yang diperlukan.

Persyaratan kuota

Persyaratan kuota untuk tugas impor atau ekspor adalah sebagai berikut:

• Spanner: Anda harus memiliki kapasitas komputasi yang cukup untuk mendukung jumlah data yang Anda impor. Tidak ada kapasitas komputasi tambahan yang diperlukan untuk mengimpor atau mengekspor database, meskipun Anda mungkin perlu menambahkan lebih banyak kapasitas komputasi agar tugas Anda selesai dalam waktu yang wajar. Lihat Mengoptimalkan tugas untuk mengetahui detail selengkapnya.
• Cloud Storage: Untuk mengimpor, Anda harus memiliki bucket yang berisi file yang sebelumnya diekspor. Untuk mengekspor, Anda harus membuat bucket untuk file yang diekspor jika belum memilikinya. Anda dapat melakukannya di Google Cloud konsol, baik melalui halaman Cloud Storage atau saat membuat ekspor melalui halaman Spanner. Anda tidak perlu menetapkan ukuran untuk bucket.
• Dataflow: Tugas impor atau ekspor tunduk pada kuota Compute Engine CPU, penggunaan disk, dan alamat IP yang sama dengan tugas Dataflow lainnya.

• Compute Engine: Sebelum menjalankan tugas impor atau ekspor, Anda harus menyiapkan kuota awal untuk Compute Engine, yang digunakan Dataflow. Kuota ini mewakili jumlah resource maksimum yang Anda izinkan untuk digunakan Dataflow bagi tugas Anda. Nilai awal yang direkomendasikan adalah:

  • CPU: 200
  • Alamat IP yang digunakan: 200
  • Persistent disk standar: 50 TB

  Umumnya, Anda tidak perlu melakukan penyesuaian lainnya. Dataflow menyediakan penskalaan otomatis sehingga Anda hanya membayar resource aktual yang digunakan selama impor atau ekspor. Jika tugas Anda dapat menggunakan lebih banyak resource, UI Dataflow akan menampilkan ikon peringatan. Tugas akan selesai meskipun ada ikon peringatan.

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan untuk mengekspor database, minta administrator untuk memberi Anda peran IAM berikut pada akun layanan worker Dataflow Anda:

• Cloud Spanner Viewer (roles/spanner.viewer)
• Dataflow Worker (roles/dataflow.worker)
• Storage Admin (roles/storage.admin)
• Spanner Database Reader (roles/spanner.databaseReader)
• Database Admin (roles/spanner.databaseAdmin)

Catatan: Peran Spanner Database Admin hanya diperlukan untuk tugas impor.

Mengekspor data Spanner ke file CSV

Untuk mengekspor data dari Spanner ke file CSV di Cloud Storage, ikuti petunjuk penggunaan Google Cloud CLI untuk menjalankan tugas dengan template Spanner ke Cloud Storage Text.

Anda juga dapat melihat informasi di halaman ini tentang mengoptimalkan tugas yang lambat, dan faktor-faktor yang memengaruhi performa tugas.

**Catatan:** Data aliran perubahan dan nilai di kolom yang dihasilkan tersimpan tidak diekspor.

Mengimpor data dari file CSV ke Spanner

Proses untuk mengimpor data dari file CSV mencakup langkah-langkah berikut:

1. Ekspor data Anda ke file CSV dan simpan file tersebut di Cloud Storage. Jangan menyertakan baris header.
2. Buat file manifes JSON dan simpan file tersebut bersama dengan file CSV Anda.
3. Buat tabel target kosong di database Spanner atau pastikan jenis data untuk kolom dalam file CSV Anda cocok dengan kolom yang sesuai dalam tabel yang ada.
4. Jalankan tugas impor Anda.

Catatan: Template Dataflow tidak dapat menangani file CSV dengan header.

Langkah 1: Mengekspor data dari database non-Spanner ke file CSV

Proses impor mengambil data dari file CSV yang berada di bucket Cloud Storage. Anda dapat mengekspor data dalam format CSV dari sumber mana pun.

Perhatikan hal-hal berikut saat mengekspor data Anda:

• File teks yang akan diimpor harus dalam format CSV.

• Data harus cocok dengan salah satu jenis berikut:

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

• Anda tidak perlu menyertakan atau membuat metadata apa pun saat mengekspor file CSV.

• Anda tidak perlu mengikuti konvensi penamaan tertentu untuk file Anda.

Jika tidak mengekspor file langsung ke Cloud Storage, Anda harus mengupload file CSV ke bucket Cloud Storage.

Langkah 2: Membuat file manifes JSON

Anda juga harus membuat file manifes dengan deskripsi JSON file yang akan diimpor dan menempatkannya di bucket Cloud Storage yang sama tempat Anda menyimpan file CSV. File manifes ini berisi array tables yang mencantumkan nama dan lokasi file data untuk setiap tabel. File ini juga menentukan dialek database penerima. Jika dialek dihilangkan, dialek akan ditetapkan secara default ke GoogleSQL.

Catatan: Jika tabel memiliki kolom yang dihasilkan, manifes harus menyertakan daftar eksplisit kolom yang tidak dihasilkan untuk diimpor untuk tabel tersebut. Spanner menggunakan daftar ini untuk memetakan kolom CSV ke kolom tabel yang benar. Nilai kolom yang dihasilkan dihitung secara otomatis selama impor.

Format file manifes sesuai dengan jenis pesan berikut, yang ditampilkan di sini dalam buffering protokol format:

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

Contoh berikut menunjukkan file manifes untuk mengimpor tabel bernama Albums dan Singers ke dalam database dialek GoogleSQL. Tabel Albums menggunakan skema kolom yang diambil tugas dari database, dan tabel Singers menggunakan skema yang ditentukan file manifes:

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

Langkah 3: Membuat tabel untuk database Spanner

Sebelum menjalankan impor, Anda harus membuat tabel target di database Spanner. Jika tabel Spanner target sudah memiliki skema, semua kolom yang ditentukan dalam file manifes harus memiliki jenis data yang sama dengan kolom yang sesuai dalam skema tabel target.

Sebaiknya buat indeks sekunder, kunci asing, dan aliran perubahan setelah Anda mengimpor data ke Spanner, bukan saat Anda membuat tabel untuk pertama kalinya. Jika tabel Anda sudah berisi struktur ini, sebaiknya hapus dan buat ulang setelah Anda mengimpor data.

Langkah 4: Menjalankan tugas impor Dataflow menggunakan gcloud

Untuk memulai tugas impor, ikuti petunjuk penggunaan Google Cloud CLI untuk menjalankan tugas dengan template Cloud Storage Text ke Spanner.

Setelah memulai tugas impor, Anda dapat melihat detail tentang tugas tersebut di konsol Google Cloud .

Setelah tugas impor selesai, tambahkan indeks sekunder, kunci asing, dan aliran perubahan yang diperlukan.

Catatan: Untuk menghindari biaya transfer data keluar, pilih region yang tumpang-tindih dengan lokasi bucket Cloud Storage Anda.

Memilih region untuk tugas impor

Anda mungkin ingin memilih region lain berdasarkan lokasi bucket Cloud Storage. Untuk menghindari biaya transfer data keluar, pilih region yang cocok dengan lokasi bucket Cloud Storage Anda.

• Jika lokasi bucket Cloud Storage Anda adalah region, Anda dapat memanfaatkan penggunaan jaringan gratis dengan memilih region yang sama untuk tugas impor, dengan asumsi region tersebut tersedia.

• Jika lokasi bucket Cloud Storage Anda adalah region ganda, Anda dapat memanfaatkan penggunaan jaringan gratis dengan memilih salah satu dari dua region yang membentuk region ganda untuk tugas impor, dengan asumsi salah satu region tersedia.

• Jika region yang sama tidak tersedia untuk tugas impor, atau jika lokasi bucket Cloud Storage Anda adalah multi-region, biaya transfer data keluar akan berlaku. Lihat Harga transfer data Cloud Storage data transfer untuk memilih region yang dikenai biaya transfer data terendah.

Melihat atau memecahkan masalah tugas di UI Dataflow

Setelah memulai tugas impor atau ekspor, Anda dapat melihat detail tugas, termasuk log, di bagian Dataflow di Google Cloud konsol.

Melihat detail tugas Dataflow

Untuk melihat detail tugas impor atau ekspor yang Anda jalankan dalam seminggu terakhir, termasuk tugas yang sedang berjalan:

1. Buka halaman Database overview untuk database.
2. Klik item menu panel kiri Import/Export. Halaman Import/Export database menampilkan daftar tugas terbaru.

3. Di halaman Import/Export database, klik nama tugas di kolom Dataflow job name:

   

   Konsol menampilkan detail tugas Dataflow . Google Cloud

Untuk melihat tugas yang Anda jalankan lebih dari seminggu yang lalu:

1. Buka halaman tugas Dataflow di Google Cloud konsol.

   Buka Tugas

2. Temukan tugas Anda dalam daftar, lalu klik namanya.

   Konsol menampilkan detail tugas Dataflow . Google Cloud

Catatan: Tugas dengan jenis yang sama untuk database yang sama memiliki nama yang sama. Anda dapat membedakan tugas berdasarkan nilai di kolom Start time atau End time.

Melihat log Dataflow untuk tugas Anda

Untuk melihat log tugas Dataflow, buka halaman detail tugas, lalu klik Logs di sebelah kanan nama tugas.

Jika tugas gagal, cari error dalam log. Jika ada error, jumlah error akan ditampilkan di samping Logs:

Untuk melihat error tugas:

1. Klik jumlah error di samping Logs.

   Konsol menampilkan log tugas. Google Cloud Anda mungkin perlu men-scroll untuk melihat error.

2. Temukan entri dengan ikon error .

3. Klik entri log individual untuk meluaskan kontennya.

Untuk mengetahui informasi selengkapnya tentang cara memecahkan masalah tugas Dataflow, lihat Memecahkan masalah pipeline.

Memecahkan masalah tugas impor atau ekspor yang gagal

Jika Anda melihat error berikut dalam log tugas:

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

--or--

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

Periksa 99% Read/Write latency di tab Monitoring database Spanner Anda di Google Cloud konsol. Jika nilai tersebut tinggi (beberapa detik), maka ini menunjukkan bahwa instance kelebihan beban, menyebabkan baca/tulis mengalami batas waktu dan gagal.

Salah satu penyebab latensi tinggi adalah tugas Dataflow berjalan menggunakan terlalu banyak worker, sehingga memberikan terlalu banyak beban pada instance Spanner.

Untuk menentukan batas jumlah worker Dataflow:

Konsol

Jika Anda menggunakan konsol Dataflow, parameter Max workers terletak di bagian Optional parameters pada halaman Create job from template.

Buka Dataflow

gcloud

Jalankan perintah gcloud dataflow jobs run, dan tentukan argumen max-workers. Contoh:

  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

Memecahkan masalah error jaringan

Error berikut mungkin terjadi saat Anda mengekspor database 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

Error ini terjadi karena Spanner mengasumsikan bahwa Anda ingin menggunakan jaringan VPC mode otomatis bernama default dalam project yang sama dengan tugas Dataflow. Jika Anda tidak memiliki jaringan VPC default dalam project, atau jika jaringan VPC Anda berada dalam jaringan VPC mode kustom, Anda harus membuat tugas Dataflow dan menentukan jaringan atau subnetwork alternatif.

Mengoptimalkan tugas impor atau ekspor yang berjalan lambat

Jika Anda telah mengikuti saran dalam setelan awal, umumnya Anda tidak perlu melakukan penyesuaian lainnya. Jika tugas Anda berjalan lambat, ada beberapa pengoptimalan lain yang dapat Anda coba:

• Mengoptimalkan lokasi tugas dan data: Jalankan tugas Dataflow di region yang sama dengan lokasi instance Spanner dan bucket Cloud Storage Anda.

• Memastikan resource Dataflow yang cukup: Jika kuota Compute Engine yang relevan membatasi resource tugas Dataflow Anda, halaman Dataflow tugas di Google Cloud konsol akan menampilkan ikon peringatan dan pesan log:

  

  Dalam situasi ini, meningkatkan kuota untuk CPU, alamat IP yang digunakan, dan persistent disk standar dapat mempersingkat waktu proses tugas, tetapi Anda mungkin dikenai lebih banyak biaya Compute Engine.

• Memeriksa penggunaan CPU Spanner: Jika Anda melihat bahwa penggunaan CPU untuk instance lebih dari 65%, Anda dapat meningkatkan kapasitas komputasi di instance tersebut. Kapasitas ini akan menambahkan lebih banyak resource Spanner dan tugas akan dipercepat, tetapi Anda akan dikenai lebih banyak biaya Spanner.

Faktor yang memengaruhi performa tugas impor atau ekspor

Beberapa faktor memengaruhi waktu yang diperlukan untuk menyelesaikan tugas impor atau ekspor.

• Ukuran database Spanner: Memproses lebih banyak data memerlukan lebih banyak waktu dan resource.

• Skema database Spanner, termasuk:

  • Jumlah tabel
  • Ukuran baris
  • Jumlah indeks sekunder
  • Jumlah kunci asing
  • Jumlah aliran perubahan

• Lokasi data: Data ditransfer antara Spanner dan Cloud Storage menggunakan Dataflow. Idealnya, ketiga komponen tersebut berada di region yang sama. Jika komponen tidak berada di region yang sama, memindahkan data antar-region akan memperlambat tugas.

• Jumlah worker Dataflow: Worker Dataflow yang optimal diperlukan untuk performa yang baik. Dengan menggunakan penskalaan otomatis, Dataflow memilih jumlah worker untuk tugas, bergantung pada jumlah pekerjaan yang perlu dilakukan. Namun, jumlah worker akan dibatasi oleh kuota untuk CPU, alamat IP yang digunakan, dan persistent disk standar. UI Dataflow menampilkan ikon peringatan jika menemukan batas kuota. Dalam situasi ini, progres lebih lambat, tetapi tugas akan tetap selesai. Penskalaan otomatis dapat membebani Spanner secara berlebihan sehingga menyebabkan error jika ada banyak data yang akan diimpor.

• Beban yang ada di Spanner: Tugas impor menambahkan beban CPU yang signifikan pada instance Spanner. Tugas ekspor biasanya menambahkan beban ringan pada instance Spanner. Jika instance sudah memiliki beban yang cukup besar, tugas akan berjalan lebih lambat.

• Jumlah kapasitas komputasi Spanner: Jika penggunaan CPU untuk instance lebih dari 65%, tugas akan berjalan lebih lambat.

Menyesuaikan worker untuk performa impor yang baik

Saat memulai tugas impor Spanner, worker Dataflow harus ditetapkan ke nilai optimal untuk performa yang baik. Terlalu banyak worker akan membebani Spanner secara berlebihan dan terlalu sedikit worker akan menghasilkan performa impor yang kurang memuaskan.

Jumlah maksimum worker sangat bergantung pada ukuran data, tetapi idealnya, total penggunaan CPU Spanner harus antara 70% hingga 90%. Hal ini memberikan keseimbangan yang baik antara efisiensi Spanner dan penyelesaian tugas tanpa error.

Untuk mencapai target penggunaan tersebut di sebagian besar skema dan skenario, sebaiknya gunakan jumlah maksimum vCPU worker antara 4-6x jumlah node Spanner.

Misalnya, untuk instance Spanner 10 node, menggunakan worker n1-standard-2, Anda akan menetapkan worker maksimum ke 25, sehingga memberikan 50 vCPU.