Halaman ini menjelaskan cara mengekspor data dari Spanner ke file CSV atau mengimpor data dari file CSV ke database Spanner.
- Jika Anda ingin mengimpor database Spanner yang sebelumnya telah diekspor ke file Avro di Cloud Storage, lihat Mengimpor file Spanner Avro.
- 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 sekumpulan file CSV.
Sebelum memulai
Untuk mengimpor atau mengekspor database Spanner, Anda harus mengaktifkan Spanner, Cloud Storage, Compute Engine, dan Dataflow API terlebih dahulu:
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 diimpor. Tidak ada kapasitas komputasi tambahan yang diperlukan untuk mengimpor atau mengekspor database, meskipun Anda mungkin perlu menambahkan kapasitas komputasi tambahan agar tugas Anda selesai dalam jangka waktu yang wajar. Lihat Mengoptimalkan tugas untuk mengetahui detail selengkapnya.
- Cloud Storage: Untuk mengimpor, Anda harus memiliki bucket berisi file yang diekspor sebelumnya. Untuk mengekspor, Anda harus membuat bucket untuk file yang diekspor jika belum memilikinya. Anda dapat melakukannya di konsol Google Cloud, baik melalui halaman Cloud Storage maupun saat membuat ekspor melalui halaman Spanner. Anda tidak perlu menetapkan ukuran bucket.
- Dataflow: Tugas impor atau ekspor tunduk pada CPU, penggunaan disk, dan alamat IP kuota Compute Engine 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 menunjukkan jumlah maksimum resource yang Anda izinkan untuk digunakan Dataflow untuk tugas Anda. Nilai awal yang direkomendasikan adalah:
- CPU: 200
- Alamat IP yang sedang digunakan: 200
- Persistent disk standar: 50 TB
Umumnya, Anda tidak perlu melakukan penyesuaian lainnya. Dataflow menyediakan penskalaan otomatis sehingga Anda hanya membayar resource sebenarnya 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.
Persyaratan IAM
Untuk mengimpor atau mengekspor database, Anda juga harus memiliki peran IAM dengan izin yang memadai untuk menggunakan semua layanan yang terlibat dalam tugas impor atau ekspor. Untuk mengetahui informasi tentang cara memberikan peran dan izin, lihat Menerapkan peran IAM.
Untuk mengimpor atau mengekspor database, Anda memerlukan peran berikut:
- Di level project Google Cloud:
- Viewer Spanner (
roles/spanner.viewer
) - Admin Dataflow (
roles/dataflow.admin
) - Storage Admin (
roles/storage.admin
)
- Viewer Spanner (
- Di level instance atau database Spanner, atau di level project Google Cloud:
- Pembaca Database Spanner (
roles/spanner.databaseReader
) - Admin Database Spanner (
roles/spanner.databaseAdmin
)
- Pembaca Database Spanner (
Ekspor 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 Teks Spanner ke Cloud Storage.
Anda juga dapat membaca informasi dalam dokumen ini tentang melihat atau memecahkan masalah tugas, mengoptimalkan tugas yang lambat, dan faktor yang memengaruhi performa tugas.
Mengimpor data dari file CSV ke Spanner
Proses untuk mengimpor data dari file CSV mencakup langkah-langkah berikut:
- Ekspor data Anda ke file CSV dan simpan file tersebut di Cloud Storage. Jangan sertakan baris header.
- Membuat file manifes JSON dan menyimpan file bersama dengan file CSV Anda.
- 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.
- Jalankan tugas impor Anda.
Langkah 1: Ekspor data dari database non-Spanner ke file CSV
Proses impor memasukkan 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 harus 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: Buat file manifes JSON
Anda juga harus membuat file manifes dengan deskripsi file JSON 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 {i>database<i} penerima.
Jika dialeknya dihilangkan, maka default-nya adalah GoogleSQL.
Format file manifes sesuai dengan jenis pesan berikut, yang ditampilkan di sini dalam format protocol buffer:
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 oleh
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: Buat tabel untuk database Spanner Anda
Sebelum menjalankan impor, Anda harus membuat tabel target dalam database Spanner. Jika tabel Spanner target sudah memiliki skema, kolom apa pun yang ditentukan dalam file manifes harus memiliki jenis data yang sama dengan kolom yang sesuai dalam skema tabel target.
Sebaiknya Anda membuat indeks sekunder, kunci asing, dan mengubah aliran data setelah mengimpor data ke Spanner, bukan saat pertama kali membuat tabel. Jika tabel Anda sudah berisi struktur ini, sebaiknya hapus dan buat ulang setelah data diimpor.
Langkah 4: Jalankan tugas impor Dataflow menggunakan gcloud
Untuk memulai tugas impor, ikuti petunjuk penggunaan Google Cloud CLI untuk menjalankan tugas dengan template Cloud Storage Text to 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.
Pilih region untuk tugas impor Anda
Sebaiknya pilih region yang berbeda 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 adalah region, Anda dapat memanfaatkan penggunaan jaringan gratis dengan memilih region yang sama untuk tugas impor, dengan asumsi bahwa region tersebut tersedia.
Jika lokasi bucket Cloud Storage Anda adalah dual-region, 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 ditempatkan bersama tidak tersedia untuk tugas impor Anda, atau jika lokasi bucket Cloud Storage Anda adalah multi-region, biaya transfer data keluar akan berlaku. Lihat harga transfer data Cloud Storage 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 tersebut, termasuk log, di bagian Dataflow pada Konsol Google Cloud.
Melihat detail tugas Dataflow
Untuk melihat detail tugas impor/ekspor yang Anda jalankan dalam seminggu terakhir, termasuk tugas yang sedang berjalan:
- Buka halaman Database overview untuk database tersebut.
- Klik item menu panel kiri Import/Export. Halaman Import/Export database menampilkan daftar tugas terbaru.
Di halaman Import/Export database, klik nama tugas di kolom Dataflow job name:
Konsol Google Cloud menampilkan detail tugas Dataflow.
Untuk melihat tugas yang Anda jalankan lebih dari satu minggu yang lalu:
Buka halaman tugas Dataflow di konsol Google Cloud.
Temukan pekerjaan Anda di daftar, lalu klik namanya.
Konsol Google Cloud menampilkan detail tugas Dataflow.
Melihat log Dataflow untuk tugas Anda
Untuk melihat log tugas Dataflow, buka halaman detail tugas seperti yang dijelaskan di atas, lalu klik Logs di sebelah kanan nama tugas.
Jika tugas gagal, cari error di log. Jika ada error, jumlah error akan ditampilkan di samping Logs:
Untuk melihat error tugas:
Klik jumlah error di sebelah Logs.
Konsol Google Cloud menampilkan log tugas. Anda mungkin perlu men-scroll untuk melihat error.
Temukan entri dengan ikon error .
Klik entri log individual untuk meluaskan kontennya.
Untuk mengetahui informasi selengkapnya tentang memecahkan masalah tugas Dataflow, lihat Memecahkan masalah pipeline Anda.
Memecahkan masalah tugas impor atau ekspor yang gagal
Jika Anda melihat error berikut di 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% latensi Baca/Tulis di tab Monitoring dalam database Spanner Anda di Konsol Google Cloud. Jika instance menampilkan nilai tinggi (beberapa detik), artinya instance kelebihan beban, yang menyebabkan waktu tunggu baca/tulis berakhir dan gagal.
Salah satu penyebab latensi tinggi adalah tugas Dataflow yang berjalan menggunakan terlalu banyak pekerja, sehingga menempatkan terlalu banyak beban pada instance Spanner.
Untuk menentukan batas jumlah pekerja Dataflow:Jika Anda menggunakan konsol Dataflow, parameter Max worker terletak di bagian Parameter opsional di halaman Create job from template.
Jika Anda menggunakan gcloud, 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
Mengoptimalkan tugas impor atau ekspor yang berjalan lambat
Jika telah mengikuti saran di setelan awal, biasanya Anda tidak perlu melakukan penyesuaian lainnya. Jika tugas Anda berjalan lambat, ada beberapa pengoptimalan lain yang dapat Anda coba:
Mengoptimalkan tugas dan lokasi data: Jalankan tugas Dataflow di region yang sama tempat instance Spanner dan bucket Cloud Storage berada.
Pastikan resource Dataflow yang memadai: Jika kuota Compute Engine yang relevan membatasi resource tugas Dataflow Anda, halaman Dataflow tugas di Konsol Google Cloud akan menampilkan ikon peringatan dan pesan log:
Dalam situasi ini, meningkatkan kuota CPU, alamat IP yang sedang digunakan, dan persistent disk standar dapat mempersingkat waktu proses tugas, tetapi Anda mungkin dikenai lebih banyak biaya Compute Engine.
Periksa pemakaian CPU Spanner: Jika pemakaian CPU untuk instance melebihi 65%, Anda dapat meningkatkan kapasitas komputasi dalam instance tersebut. Kapasitas tersebut menambahkan lebih banyak resource Spanner dan tugas akan dipercepat, tetapi biaya Spanner Anda akan lebih besar.
Faktor yang memengaruhi performa tugas impor atau ekspor
Beberapa faktor memengaruhi waktu yang diperlukan untuk menyelesaikan tugas impor atau ekspor.
Ukuran database Spanner: Pemrosesan data yang lebih banyak memerlukan lebih banyak waktu dan resource.
Skema database Spanner, termasuk:
- Jumlah tabel
- Ukuran baris
- Jumlah indeks sekunder
- Jumlah {i>foreign key<i}
- 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 lintas region akan memperlambat tugas.
Jumlah pekerja Dataflow: Pekerja Dataflow yang optimal diperlukan untuk mendapatkan performa yang baik. Dengan menggunakan penskalaan otomatis, Dataflow akan memilih jumlah pekerja untuk tugas, bergantung pada jumlah pekerjaan yang perlu dilakukan. Namun, jumlah pekerja akan dibatasi oleh kuota CPU, alamat IP yang sedang digunakan, dan persistent disk standar. UI Dataflow menampilkan ikon peringatan jika mengalami batas kuota. Dalam situasi ini, progresnya lebih lambat, tetapi tugas seharusnya tetap dapat diselesaikan. Penskalaan otomatis dapat membebani Spanner sehingga menyebabkan error jika ada banyak data yang harus diimpor.
Pemuatan 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 substansial, tugas akan berjalan lebih lambat.
Jumlah kapasitas komputasi Spanner: Jika penggunaan CPU untuk instance lebih dari 65%, tugas akan berjalan lebih lambat.
Menyesuaikan pekerja untuk performa impor yang baik
Saat memulai tugas impor Spanner, pekerja Dataflow harus ditetapkan ke nilai optimal untuk performa yang baik. Terlalu banyak pekerja melebihi beban Spanner dan terlalu sedikit pekerja menyebabkan performa impor yang buruk.
Jumlah maksimum pekerja 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 bebas error.
Untuk mencapai target penggunaan tersebut di sebagian besar skema dan skenario, sebaiknya jumlah maksimum vCPU pekerja antara 4-6x jumlah node Spanner.
Misalnya, untuk instance Spanner yang terdiri dari 10 node, yang menggunakan pekerja n1-standard-2, Anda akan menetapkan maksimal pekerja ke 25, sehingga menghasilkan 50 vCPU.