Mengimpor dan mengekspor data

Dokumen ini menjelaskan cara memigrasikan, mencadangkan, dan mentransfer data di Spanner Omni menggunakan format Avro dan CSV. Gunakan Spanner Omni CLI untuk memindahkan konten database antara Spanner Omni dan solusi penyimpanan seperti Cloud Storage, Amazon Simple Storage Service (Amazon S3), penyimpanan lokal yang kompatibel dengan S3, atau sistem file lokal (NFS). Alur data impor dan ekspor di Spanner Omni tidak mendukung model, grup lokalitas, atau penempatan.

Operasi impor dan ekspor berjalan di server Spanner Omni dan berbagi resource sistem yang tersedia. Pengimporan memerlukan banyak resource dan dapat menyebabkan penggunaan RAM, CPU, dan disk yang tinggi, yang dapat memengaruhi workload aktif. Meskipun tugas ini biasanya berjalan dengan prioritas yang lebih rendah daripada traffic reguler, Anda harus memantau deployment untuk mengetahui potensi dampak performa.

Perbandingan format file

Tabel berikut membandingkan kemampuan format file Avro dan CSV untuk mengimpor dan mengekspor data Spanner.

Kemampuan	Avro	CSV
Mengimpor atau mengekspor seluruh database	Ya	Tidak
Mengimpor tabel yang diekspor sebelumnya	Ya	Ya
Mengekspor pada stempel waktu sebelumnya	Ya	Ya
Mengimpor atau mengekspor menggunakan Spanner	Ya	Ya
Mengimpor data dari database lain	Tidak	Ya

Format Avro dan CSV mengekspor semua tabel dalam database. Format Avro juga mengekspor skema sehingga Anda dapat mengimpornya lagi. Format CSV tidak mengekspor skema.

Sebelum memulai

Sebelum memulai operasi impor atau ekspor, verifikasi izin Anda dan konfigurasi akses ke lokasi penyimpanan data Anda.

Izin

Pastikan Anda memiliki izin berikut sebelum memulai:

spanner.databases.import
spanner.databases.export

Untuk mengetahui informasi selengkapnya tentang Identity and Access Management (IAM) di Spanner Omni, lihat Ringkasan IAM. Untuk mempelajari cara memperbarui peran pengguna, lihat Memperbarui pengguna.

Sumber dan tujuan data

Anda dapat menyimpan data di bucket Amazon Simple Storage Service (Amazon S3), bucket Cloud Storage, penyimpanan lokal yang kompatibel dengan Amazon S3 (seperti MinIO), atau sistem file lokal (NFS). Jika Anda menggunakan sistem file lokal, pastikan data tersedia di jalur yang sama di semua server dalam deployment.

Anda dapat memberikan akses ke datastore dengan dua cara:

Menambahkan penyimpanan eksternal ke deployment: Ini adalah metode yang lebih disarankan jika Anda berencana menggunakan kembali bucket.
Buat kredensial sekali pakai: Pastikan kredensial ini bertahan lebih lama daripada durasi operasi impor atau ekspor (misalnya, 48 jam).

Kredensial harus memberikan izin untuk mencantumkan dan membaca objek di bucket untuk impor. Untuk ekspor ke Amazon S3, Anda memerlukan izin Amazon S3 tambahan berikut:

s3:PutObject
s3:AbortMultipartUpload
s3:ListBucketMultipartUploads

Untuk mengetahui informasi selengkapnya, lihat Izin IAM.

Mengimpor file Avro Spanner

Untuk mengimpor data yang sebelumnya telah Anda ekspor dari database Spanner lain (Spanner atau Spanner Omni) dalam format Avro, ikuti langkah-langkah berikut.

Prasyarat impor Avro

Sebelum memulai impor Avro, pastikan lingkungan Anda memenuhi persyaratan berikut:

Anda telah membuat database tujuan.
Objek skema yang Anda impor belum ada di database. Proses impor Avro membuat tabel ini sebelum mengimpor data.

Petunjuk impor Avro

Identifikasi jalur ke folder yang berisi data yang diekspor. Folder berisi hal-hal berikut:

File spanner-export.json
File ENTITY_NAME-manifest.json untuk setiap entitas yang diekspor (seperti tabel, urutan, atau skema).
Semua file Avro yang tercantum dalam file manifes.

Jika sudah menambahkan datastore sebagai penyimpanan eksternal, Anda tidak perlu menyertakan kredensial dalam jalur. Anda dapat memberikan jalur secara langsung. Jika Anda menggunakan kredensial sekali pakai, gunakan format URL berikut:

Cloud Storage: gs://BUCKET_NAME/BASE_FOLDER[?accesskey=ACCESS_KEY&secret=SECRET_KEY]. Gunakan kredensial HMAC. Untuk mengetahui informasi selengkapnya, lihat kunci HMAC.
Amazon S3: s3://S3_BUCKET/BASE_FOLDER[?accesskey=ACCESS_KEY&secret=SECRET_KEY[&sessiontoken=SESSION_TOKEN]]
Folder file lokal*: file:///PATH_TO_DIR

Untuk memulai impor, jalankan perintah berikut:

spanner databases import DATABASE_ID --url="URL" --format=avro [--avro-skip-wait-for-index-creation]

Catatan tambahan

Pertimbangkan informasi berikut saat Anda mengimpor file Avro:

Catatan tentang mengimpor kolom yang dibuat dan aliran perubahan dalam dokumentasi Spanner.
Catatan tentang mengimpor urutan dalam dokumentasi Spanner.
Catatan tentang mengimpor tabel sisipan dan kunci asing dalam dokumentasi Spanner.
Untuk melewati impor entitas tertentu, hapus entitas tersebut dari file spanner-export.json.
Pembuatan indeks dapat memerlukan waktu yang cukup lama untuk set data besar. Untuk melewati penantian pembuatan indeks, gunakan tanda --avro-skip-wait-for-index-creation opsional.

Jika operasi impor berhasil dimulai, ID operasi yang berjalan lama akan ditampilkan. Gunakan ID ini untuk melacak status operasi.

Mengimpor file CSV

Untuk mengimpor data teks yang telah Anda ekspor dari database lain, ikuti langkah-langkah berikut.

Prasyarat impor CSV

Sebelum memulai impor CSV, pastikan Anda melakukan hal berikut:

Pastikan tabel Anda menggunakan salah satu jenis data yang didukung berikut: BOOL, INT64, FLOAT64, NUMERIC, STRING, DATE, TIMESTAMP, BYTES, dan JSON.
Buat database tujuan.
Buat semua tabel tempat Anda ingin mengimpor data. Proses impor CSV tidak membuat tabel.
Pastikan file CSV tidak berisi baris header.

Petunjuk impor CSV

Untuk mengimpor file CSV, buat file manifes yang menjelaskan data yang akan diimpor. File manifes menggunakan struktur berikut, yang ditentukan di sini dalam format protobuf:

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

Berikut adalah contoh 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"}
      ]
    }
  ]
}

URL dalam perintah impor file CSV berikut tidak berisi baris header harus mengarah ke folder yang berisi file manifes dalam format JSON, seperti yang dijelaskan dalam contoh manifes. File ini dapat berada di Cloud Storage, Amazon S3, atau folder file lokal, menggunakan format URL yang sama untuk kredensial seperti yang dijelaskan dalam petunjuk impor Avro. Untuk memulai impor, jalankan perintah berikut:

spanner databases import DATABASE_ID --url="URL" --format=csv

Opsi impor CSV

Gunakan flag berikut untuk menyesuaikan cara Spanner Omni menangani file teks:

--csv-date-format: Mengganti format untuk kolom tanggal. Defaultnya adalah %Y-%m-%d. Contoh: %d/%m/%Y.
--csv-timestamp-format: Mengganti format untuk kolom stempel waktu. Gunakan ini hanya jika Spanner Omni tidak mendukung format dalam CSV. Contoh: %d/%m/%Y %H:%M:%S%Ez.
--csv-delimiter: Menggantikan karakter pembatas. Defaultnya adalah koma.
--csv-quote-char: Mengganti karakter kutipan. Defaultnya adalah tanda petik ganda.
--csv-escape-char: Mengganti karakter escape. Defaultnya adalah tanda petik ganda.
--csv-null-string: Mengganti string yang merepresentasikan nilai NULL. Defaultnya adalah \N.
--csv-has-trailing-delimiters: Menentukan apakah file CSV memiliki pembatas di akhir. Defaultnya adalah false.

Mengekspor ke file Avro

Untuk mengekspor data ke file Avro, ikuti petunjuk format URL di petunjuk impor Avro.

Server apa pun dalam deployment dapat menulis data ke datastore yang disediakan. Jika Anda menggunakan folder file lokal sebagai tujuan, pastikan semua server memiliki akses ke jalur yang sama dan dapat menulis ke jalur tersebut secara paralel.

Sistem akan mengekspor semua tabel dan entity dalam database. Pastikan Anda memberikan jalur folder baru yang kosong untuk data yang diekspor.

Untuk memulai ekspor, jalankan perintah berikut:

spanner databases export DATABASE_ID --url="URL" --format=avro

Ekspor CSV hanya mendukung tabel dan tidak mengekspor skema database.

Mengekspor ke file CSV

Ekspor CSV tidak mengekspor skema database dan hanya mendukung tabel. Untuk mengekspor data ke file CSV, jalankan perintah berikut:

spanner databases export DATABASE_ID --url="URL" --format=csv

Pemecahan masalah

Jika impor gagal, update skema dan data yang diimpor tidak akan otomatis dikembalikan. Bersihkan database secara manual sebelum Anda mencoba lagi operasi.

Kecepatan operasi impor bergantung pada beberapa faktor, termasuk jumlah file dalam folder, sumber daya komputasi yang tersedia dalam deployment, dan kecepatan disk. Jika resource yang tersedia mencukupi, sistem akan mengimpor file secara paralel.

Mengimpor dan mengekspor data Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.