Gunakan perintah Tunnel untuk unggah dan unduh data - MaxCompute

Gunakan perintah Tunnel untuk mengunggah dan mengunduh data antara lingkungan lokal Anda dan MaxCompute. Tunnel mendukung transfer data batch dan inkremental guna mengakomodasi ingesti serta ekstraksi data skala besar.

Subperintah

tunnel <subcommand> [options] [args]

Subperintah	Alias	Deskripsi
`upload`	`u`	Unggah data lokal ke tabel MaxCompute
`download`	`d`	Unduh data dari tabel MaxCompute ke file lokal
`upsert`	`us`	Tulis data menggunakan semantik UPDATE dan INSERT (hanya untuk Transaction Table 2.0)
`resume`	`r`	Lanjutkan sesi upload yang terganggu
`show`	`s`	Tampilkan riwayat dan log transfer
`purge`	`p`	Bersihkan direktori sesi
`help`	`h`	Tampilkan informasi bantuan

Hubungan antarperintah: Gunakan upload, download, atau upsert untuk mentransfer data. Jika upload terganggu, gunakan resume untuk melanjutkan dari titik terakhir. Gunakan show untuk memeriksa riwayat transfer, dan purge untuk membersihkan log sesi lama.

Upload

Mengunggah data lokal ke tabel MaxCompute dalam mode append. Data yang sudah ada di tabel tidak ditimpa—data lama dan baru tetap berada dalam tabel secara bersamaan.

Setiap operasi upload menargetkan satu tabel atau satu partisi. Untuk tabel partisi, tentukan partisi tingkat terendah.

Sintaks

tunnel upload [options] <path> <[project.]table[/partition]>

Contoh:

# Unggah log.txt ke tabel partisi dua level (file berada di direktori bin klien MaxCompute)
tunnel upload log.txt test_project.test_table/p1="b1",p2="b2"

# Unggah dari jalur mutlak (Windows)
tunnel upload D:\test\log.txt test_project.test_table/p1="b1",p2="b2"

# Pindai file sebelum mengunggah untuk memvalidasi terhadap skema tabel
tunnel upload log.txt test_table --scan=true

# Timpa partisi alih-alih menambahkan
tunnel upload -ow true data.txt sale_detail/sale_date=201312,region=hangzhou

Pada macOS, path harus berupa jalur mutlak, seperti /Users/username/MaxCompute/bin/file.txt.

Upload mendukung file TXT secara default. Untuk mengunggah file CSV, atur -cf true dan gunakan klien MaxCompute versi terbaru. Pemisahan file tidak didukung dalam format CSV.

Parameter

Wajib

Parameter	Deskripsi
`path`	Jalur ke file data lokal. File di direktori `bin` klien MaxCompute dapat dirujuk hanya dengan nama filenya; file di direktori lain memerlukan jalur lengkap.
`[project.]table[/partition]`	Tabel tujuan. Sertakan nama proyek jika tabel berada di proyek berbeda. Tentukan partisi tingkat terendah untuk tabel partisi.

Opsi — Format

Opsi	Default	Deskripsi
`-c`, `-charset`	(tidak diatur)	Pengkodean karakter file. Jika tidak diatur, data mentah diunggah tanpa konversi. Pengkodean default adalah UTF-8.
`-cf`, `-csv-format`	`false`	Atur ke `true` untuk mengunggah file CSV. Saat diaktifkan, pemisahan file tidak didukung.
`-fd`, `-field-delimiter`	`,`	Pemisah kolom. Mendukung beberapa karakter dan escape Unicode seperti `\u0001`. Tidak boleh mengandung pemisah baris.
`-rd`, `-record-delimiter`	`\r\n`	Pemisah baris. Mendukung beberapa karakter, escape Unicode, serta urutan escape `\r`, `\n`, `\t`.
`-h`, `-header`	`false`	Atur ke `true` jika file memiliki baris header. Baris header dilewati selama upload.
`-ni`, `-null-indicator`	`""` (string kosong)	String yang merepresentasikan NULL dalam file sumber. Jika tidak diatur, string kosong diperlakukan sebagai NULL.
`-dfp`, `-date-format-pattern`	`yyyy-MM-dd HH:mm:ss`	Pola format DATETIME. Gunakan `yyyy-MM-dd HH:mm:ss.SSS` untuk presisi milidetik. Lihat Edisi tipe data.

Opsi — Penanganan error

Opsi	Default	Deskripsi
`-s`, `-scan`	`true`	Mengontrol pemindaian file sebelum upload. `true`: pindai terlebih dahulu, lalu unggah jika valid. `false`: lewati pemindaian dan unggah langsung. `only`: pindai tanpa mengunggah.
`-ss`, `-strict-schema`	`true`	Atur ke `false` untuk mengizinkan pencocokan skema longgar: kolom tambahan dibuang, dan kolom yang hilang diisi dengan NULL.
`-dbr`, `-discard-bad-records`	`false`	Atur ke `true` untuk melewati catatan buruk (kolom tambahan, kolom hilang, atau ketidaksesuaian tipe) alih-alih gagal. Saat `false`, upload berhenti dan mengembalikan error pada catatan buruk pertama yang terdeteksi. Gunakan bersama `-mbr` untuk mengatur jumlah maksimum catatan buruk yang dilewati.
`-mbr`, `-max-bad-records`	`1000`	Jumlah maksimum catatan buruk yang dilewati. Hanya berlaku saat `-dbr true` diatur. Jika jumlah catatan buruk melebihi batas ini, upload akan berhenti.

Opsi — Performa

Opsi	Default	Deskripsi
`-t`, `-threads`	`1`	Jumlah thread upload konkuren. Tingkatkan nilai ini untuk meningkatkan throughput pada file besar.
`-bs`, `-block-size`	`100` MiB	Ukuran setiap blok yang diunggah. 1 MiB = 1.048.576 byte.
`-cp`, `-compress`	`true`	Kompres data sebelum mengunggah untuk mengurangi penggunaan jaringan.

Opsi — Sesi

Opsi	Default	Deskripsi
`-acp`, `-auto-create-partition`	`false`	Secara otomatis membuat partisi target jika belum ada.
`-ow`, `-overwrite`	`false`	Atur ke `true` untuk menimpa tabel atau partisi target alih-alih menambahkan.
`-sd`, `-session-dir`	Direktori plugin klien	Direktori yang digunakan untuk menyimpan status sesi.
`-te`, `-tunnel_endpoint`	(tidak diatur)	Titik akhir Tunnel. Lihat Endpoints.
`-tz`, `-time-zone`	Zona waktu lokal	Zona waktu untuk data DATETIME. Default adalah zona waktu lokal (misalnya, `Asia/Shanghai`). Lihat Zona waktu.
`-time`	`false`	Lacak dan tampilkan waktu yang berlalu setelah upload selesai.

Contoh: timpa partisi

Buat tabel partisi dan tambahkan partisi awal:

CREATE TABLE IF NOT EXISTS sale_detail(
      shop_name     STRING,
      customer_id   STRING,
      total_price   DOUBLE)
PARTITIONED BY (sale_date STRING, region STRING);

ALTER TABLE sale_detail ADD PARTITION (sale_date='201312', region='hangzhou');

Unggah data awal (data.txt berisi shopx,x_id,100 dan shopy,y_id,200):

tunnel upload d:\data.txt sale_detail/sale_date=201312,region=hangzhou

Hasil kueri:

+------------+-------------+-------------+------------+------------+
| shop_name  | customer_id | total_price | sale_date  | region     |
+------------+-------------+-------------+------------+------------+
| shopx      | x_id        | 100.0       | 201312     | hangzhou   |
| shopy      | y_id        | 200.0       | 201312     | hangzhou   |
+------------+-------------+-------------+------------+------------+

Perbarui data.txt agar berisi shopx,x_id,300 dan shopy,y_id,400, lalu timpa partisi tersebut:

tunnel upload -ow true data.txt sale_detail/sale_date=201312,region=hangzhou

Hasil kueri setelah ditimpa:

+------------+-------------+-------------+------------+------------+
| shop_name  | customer_id | total_price | sale_date  | region     |
+------------+-------------+-------------+------------+------------+
| shopx      | x_id        | 300.0       | 201312     | hangzhou   |
| shopy      | y_id        | 400.0       | 201312     | hangzhou   |
+------------+-------------+-------------+------------+------------+

Download

Mengunduh data dari tabel MaxCompute atau hasil eksekusi instans tertentu ke file lokal.

Setiap operasi download menargetkan satu tabel atau satu partisi. Untuk tabel partisi, tentukan partisi tingkat terendah.

Prasyarat

Sebelum mengunduh, pastikan Anda memiliki izin Download pada tabel target. Jika tidak, hubungi pemilik proyek atau pengguna dengan role Super_Administrator untuk memberikan akses. Lihat Kontrol akses berbasis kebijakan.

Sintaks

# Unduh dari tabel atau partisi
tunnel download [options] <[project.]table[/partition]> <path>

# Unduh hasil eksekusi instans tertentu
tunnel download [options] instance://<[project/]instance_id> <path>

Contoh:

# Unduh tabel partisi dua level ke file lokal
tunnel download test_project.test_table/p1="b1",p2="b2" test_table.txt

# Unduh ke direktori tertentu (Windows)
tunnel download test_project.test_table/p1="b1",p2="b2" D:\test\test_table.txt

# Unduh hasil eksekusi instans tertentu
tunnel download instance://test_project/test_instance log.txt

Download mendukung file TXT secara default. Untuk mengunduh file CSV, atur -cf true dan gunakan klien MaxCompute versi terbaru. Saat -cf true diatur, pemisah tetap berupa koma (,); pengaturan -fd diabaikan.

Parameter

Wajib

Parameter	Deskripsi
`path`	Jalur tempat menyimpan file yang diunduh. File di direktori `bin` klien MaxCompute dapat dirujuk hanya dengan nama filenya; file di direktori lain memerlukan jalur lengkap.
`[project.]table[/partition]`	Tabel sumber. Sertakan nama proyek jika tabel berada di proyek berbeda. Tentukan partisi tingkat terendah untuk tabel partisi.
`[project/]instance_id`	ID instans untuk mengunduh hasil eksekusi instans tersebut.

Opsi — Format

Opsi	Default	Deskripsi
`-c`, `-charset`	(tidak diatur)	Pengkodean karakter file. Jika tidak diatur, data mentah diunduh tanpa konversi.
`-cf`, `-csv-format`	`false`	Atur ke `true` untuk mengunduh sebagai file CSV. Saat diaktifkan, pemisah tetap berupa `,`; pengaturan `-fd` diabaikan.
`-ci`, `-columns-index`	(semua kolom)	Daftar indeks kolom yang dipisahkan koma untuk diunduh (berbasis 0).
`-cn`, `-columns-name`	(semua kolom)	Daftar nama kolom yang dipisahkan koma untuk diunduh.
`-fd`, `-field-delimiter`	`,`	Pemisah kolom. Mendukung beberapa karakter dan escape Unicode seperti `\u0001`. Diabaikan saat `-cf true` diatur.
`-rd`, `-record-delimiter`	`\r\n`	Pemisah baris. Mendukung beberapa karakter, escape Unicode, serta urutan escape `\r`, `\n`, `\t`.
`-h`, `-header`	`false`	Atur ke `true` untuk menyertakan baris header dalam file yang diunduh. Tidak dapat digunakan dengan `-t` lebih besar dari `1`.
`-ni`, `-null-indicator`	`""` (string kosong)	String yang digunakan untuk merepresentasikan nilai NULL dalam file output. Jika tidak diatur, nilai NULL muncul sebagai string kosong.
`-dfp`, `-date-format-pattern`	`yyyy-MM-dd HH:mm:ss`	Pola format DATETIME.
`-e`, `-exponential`	`false`	Atur ke `true` untuk menggunakan notasi eksponensial untuk nilai DOUBLE. Saat `false`, hingga 20 digit dipertahankan.
`-limit`	(tidak diatur)	Jumlah maksimum catatan yang diunduh. Jika tidak diatur, semua catatan diunduh.

Opsi — Performa

Opsi	Default	Deskripsi
`-t`, `-threads`	`1`	Jumlah thread download konkuren. Tidak boleh lebih besar dari `1` saat `-h true` diatur.
`-cp`, `-compress`	`true`	Kompres data selama download untuk mengurangi penggunaan jaringan.

Opsi — Sesi

Opsi	Default	Deskripsi
`-sd`, `-session-dir`	Direktori plugin klien	Direktori yang digunakan untuk menyimpan status sesi.
`-te`, `-tunnel_endpoint`	(tidak diatur)	Titik akhir Tunnel. Lihat Endpoints.
`-tz`, `-time-zone`	Zona waktu lokal	Zona waktu untuk data DATETIME (misalnya, `Asia/Shanghai`). Lihat Zona waktu.
`-time`	`false`	Lacak dan tampilkan waktu yang berlalu setelah download selesai.

Upsert

Menulis data ke tabel Transaction Table 2.0 menggunakan semantik UPDATE dan INSERT: menyisipkan catatan baru jika tidak ada catatan yang cocok, atau memperbarui catatan yang ada jika ditemukan.

Prasyarat

Versi klien MaxCompute (odpscmd) V0.47 atau lebih baru
Tabel target harus merupakan tabel Transaction Table 2.0

Sintaks

tunnel upsert [options] <path> <[project.]table[/partition]>

Contoh:

tunnel upsert log.txt test_project.test_table/p1="b1",p2="b2"

Upsert mendukung file TXT secara default. Untuk upsert dari file CSV, atur -cf true dan gunakan klien MaxCompute versi terbaru.

Parameter

Wajib

Parameter	Deskripsi
`path`	Jalur ke file data lokal. File di direktori `bin` klien MaxCompute dapat dirujuk hanya dengan nama filenya; file di direktori lain memerlukan jalur lengkap. Pada macOS, ini harus berupa jalur mutlak.
`[project.]table[/partition]`	Tabel target. Sertakan nama proyek jika tabel berada di proyek berbeda. Tentukan partisi tingkat terendah untuk tabel partisi.

Opsi — Format

Opsi	Default	Deskripsi
`-c`, `-charset`	(tidak diatur)	Pengkodean karakter file. Jika tidak diatur, data mentah diunggah tanpa konversi.
`-cf`, `-csv-format`	`false`	Atur ke `true` untuk upsert dari file CSV.
`-fd`, `-field-delimiter`	`,`	Pemisah kolom. Mendukung beberapa karakter dan escape Unicode. Tidak boleh mengandung pemisah baris.
`-rd`, `-record-delimiter`	`\n`	Pemisah baris. Default untuk upsert adalah `\n`, yang berbeda dari upload (`\r\n`).
`-h`, `-header`	`false`	Atur ke `true` jika file memiliki baris header. Baris header dilewati.
`-ni`, `-null-indicator`	`""` (string kosong)	String yang merepresentasikan NULL dalam file sumber. Jika tidak diatur, string kosong diperlakukan sebagai NULL.
`-dfp`, `-date-format-pattern`	`yyyy-MM-dd HH:mm:ss`	Pola format DATETIME. Gunakan `yyyy-MM-dd HH:mm:ss.SSS` untuk presisi milidetik. Lihat Edisi tipe data.

Opsi — Penanganan error

Opsi	Default	Deskripsi
`-ss`, `-strict-schema`	`true`	Atur ke `false` untuk membuang kolom tambahan dan mengisi kolom yang hilang dengan NULL.
`-dbr`, `-discard-bad-records`	`false`	Atur ke `true` untuk melewati catatan buruk alih-alih gagal. Gunakan bersama `-mbr` untuk membatasi jumlah catatan yang dilewati.
`-mbr`, `-max-bad-records`	`1000`	Jumlah maksimum catatan buruk yang dilewati. Hanya berlaku saat `-dbr true` diatur. Jika jumlah catatan buruk melebihi batas ini, operasi akan berhenti.

Opsi — Performa

Opsi	Default	Deskripsi
`-bs`, `-block-size`	`100` MiB	Ukuran setiap blok yang diunggah. 1 MiB = 1.048.576 byte.
`-cp`, `-compress`	`true`	Kompres data sebelum mengunggah untuk mengurangi penggunaan jaringan.

Opsi — Sesi

Opsi	Default	Deskripsi
`-acp`, `-auto-create-partition`	`false`	Secara otomatis membuat partisi target jika belum ada.
`-qn`, `-quota_name`	(tidak diatur)	Kuota Tunnel yang digunakan untuk mengakses MaxCompute. Lihat nama kuota di Konsol MaxCompute di bawah Workspace > Quotas. Lihat Kelola kuota di konsol MaxCompute baru.
`-sd`, `-session-dir`	Direktori plugin klien	Direktori yang digunakan untuk menyimpan status sesi.
`-te`, `-tunnel_endpoint`	(tidak diatur)	Titik akhir Tunnel. Lihat Endpoints.
`-tz`, `-time-zone`	Zona waktu lokal	Zona waktu untuk data DATETIME (misalnya, `Asia/Shanghai`). Lihat Zona waktu.
`-time`	`false`	Lacak dan tampilkan waktu yang berlalu setelah operasi selesai.

Resume

Melanjutkan sesi upload yang terganggu. Hanya upload yang dapat dilanjutkan; download tidak dapat dilanjutkan.

Sintaks

tunnel resume [session_id] [-force]

Parameter	Deskripsi
`session_id`	Wajib. ID sesi upload yang gagal. Ambil dari `tunnel show history`.
`-f`, `-force`	Lanjutkan sesi secara paksa tanpa konfirmasi.

Contoh

odps@ project_name>tunnel resume 20150610xxxxxxxxxxx70a002ec60c -force;
start resume
20150610xxxxxxxxxxx70a002ec60c
Upload session: 20150610xxxxxxxxxxx70a002ec60c
Start upload:d:\data.txt
Resume 1 blocks
2015-06-10 16:46:42     upload block: '1'
2015-06-10 16:46:42     upload block complete, blockid=1
upload complete, average speed is 0 KB/s
OK

Show

Menampilkan riwayat dan log transfer.

Sintaks

# Tampilkan riwayat transfer
tunnel show history [-n <number>]

# Tampilkan log transfer terbaru
tunnel show log

-n <number>: Jumlah entri riwayat yang ditampilkan. Secara default, hingga 500 entri disimpan.

Nilai status sesi

Setiap entri riwayat menampilkan ID sesi, status, dan perintah yang dijalankan. Nilai statusnya adalah:

Status	Deskripsi
`success`	Transfer selesai tanpa error.
`bad`	Transfer selesai, tetapi beberapa catatan dilewati (memerlukan `-dbr true`).
`failed`	Transfer gagal dan tidak ada data yang ditulis.

Contoh

Tampilkan semua riwayat yang tersimpan:

tunnel show history

Output:

20230505xxxxxxxxxxxxxx0b0d5b3c  bad     'upload d:\data.txt sale_detail/sale_date=201312,region=hangzhou -dbr true -time true'
20230505xxxxxxxxxxxxxx0ad720a3  failed  'upload d:\data.txt sale_detail/sale_date=201312,region=hangzhou -time true'
20230505xxxxxxxxxxxxxx0ad5ca68  bad     'upload d:\data.txt sale_detail/sale_date=201312,region=hangzhou -dbr true'
......

Tampilkan 5 entri terakhir:

tunnel show history -n 5

Output:

20230505xxxxxxxxxxxxxx0aa48c4b  success 'download sale_detail/sale_date=201312,region=hangzhou result.txt'
20230505xxxxxxxxxxxxxx0aa6165c  success 'download sale_detail/sale_date=201312,region=hangzhou result.txt'
20230505xxxxxxxxxxxxxx0af11472  failed  'upload d:\data.txt sale_detail/sale_date=201312,region=hangzhou -s false'
20230505xxxxxxxxxxxxxx0b464374  success 'upload d:\data.txt sale_detail/sale_date=201312,region=hangzhou -s false'
20230505xxxxxxxxxxxxxx02dbb6bd  failed  'upload d:\data.txt sale_detail/sale_date="201312",region="hangzhou" -s false'

Purge

Menghapus riwayat sesi dari direktori sesi.

Sintaks

tunnel purge [n]

n: Jumlah hari riwayat yang akan dihapus. Default: 3 (menghapus log dari 3 hari terakhir).

Contoh: Hapus log 5 hari terakhir:

tunnel purge 5

Catatan penggunaan

Tipe data yang didukung

Tipe data	Perilaku upload	Perilaku download
STRING	Panjang maks: 8 MB	Panjang maks: 8 MB
BOOLEAN	Menerima `True`, `False`, `0`, atau `1` (tidak peka huruf besar/kecil)	Mengembalikan `True` atau `False`
BIGINT	Rentang: -9.223.372.036.854.775.807 hingga 9.223.372.036.854.775.807	Rentang yang sama
DOUBLE	Angka 16 digit. Dinyatakan dalam notasi ilmiah.	Dinyatakan sebagai angka (hingga 20 digit). Tak hingga positif: `Infinity`. Tak hingga negatif: `-Infinity`. Maks: `1.7976931348623157E308`. Min: `4.9E-324`.
DATETIME	Zona waktu default: GMT+8. Gunakan `-dfp` untuk mengatur format. Lihat Edisi tipe data.	—

Pola format DATETIME yang didukung:

Pola	Contoh
`yyyyMMddHHmmss`	`20140209101000`
`yyyy-MM-dd HH:mm:ss` (default)	`2014-02-09 10:10:00`
`MM/dd/yyyy`	`09/01/2014`

Nilai NULL

Secara default, string kosong diperlakukan sebagai NULL. Untuk menggunakan indikator null kustom:

tunnel upload log.txt test_table -ni "NULL"

Pengkodean file

Pengkodean default adalah UTF-8. Untuk menentukan pengkodean berbeda:

tunnel upload log.txt test_table -c "gbk"

Pemisah

Baik pemisah baris maupun kolom mendukung beberapa karakter. Pemisah kolom tidak boleh mengandung pemisah baris. Urutan escape yang didukung: \r, \n, \t.

tunnel upload log.txt test_table -fd "||" -rd "\r\n"

Subperintah

Upload

Sintaks

Parameter

Wajib

Opsi — Format

Opsi — Penanganan error

Opsi — Performa

Opsi — Sesi

Contoh: timpa partisi

Download

Prasyarat

Sintaks

Parameter

Wajib

Opsi — Format

Opsi — Performa

Opsi — Sesi

Upsert

Prasyarat

Sintaks

Parameter

Wajib

Opsi — Format

Opsi — Penanganan error

Opsi — Performa

Opsi — Sesi

Resume

Sintaks

Contoh

Show

Sintaks

Nilai status sesi

Contoh

Purge

Sintaks

Catatan penggunaan

Tipe data yang didukung

Nilai NULL

Pengkodean file

Pemisah

Langkah selanjutnya