Impor data lokal menggunakan tool impor AnalyticDB for MySQL - AnalyticDB

Tool impor AnalyticDB for MySQL memuat file delimited lokal ke kluster AnalyticDB for MySQL Edisi Data Warehouse melalui Java Database Connectivity (JDBC). Tool ini lebih unggul dibandingkan pernyataan LOAD DATA karena mendukung impor multi-file secara konkuren serta memungkinkan penyesuaian parameter batchSize dan concurrency untuk memaksimalkan throughput penulisan.

Cara kerja

Tool ini terhubung ke instans Server Load Balancer (SLB), yang mendistribusikan lalu lintas ke beberapa front node. Front node mengurai protokol MySQL dan pernyataan SQL, menulis data, serta menjadwalkan kueri. Data kemudian dialirkan dari front node ke storage node untuk persistensi.

Prasyarat

Sebelum memulai, pastikan Anda telah:

Menginstal Java 1.8 atau versi yang lebih baru (jalankan java -version untuk memeriksa)
Memiliki akses jaringan ke titik akhir kluster AnalyticDB for MySQL
Database dan tabel target telah dibuat di dalam Kluster.

Impor data

Langkah	Deskripsi
Langkah 1: Unduh dan ekstrak tool impor	Unduh dan ekstrak paket tool.
Langkah 2: Siapkan file data	Verifikasi format file, urutan kolom, dan pemisah.
Langkah 3: Konfigurasikan skrip impor	Atur parameter koneksi, file, dan performa.
Langkah 4: Jalankan impor	Jalankan skrip dan pantau progres.

Langkah 1: Unduh dan ekstrak tool impor

Buat direktori kerja:
```
mkdir -p /u01/loadata
```
Masuk ke direktori tersebut:
```
# cd /u01/loadata
```

Unduh tool:

wget https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20220811/gpvn/adb-import-tool.tar.gz

Ekstrak paket:
```
tar zxvf adb-import-tool.tar.gz
```

Paket tersebut mengekstrak file-file berikut:

adb-import.sh.template
adb-import.sh.template.md5
adb-import-tool.jar
adb-import-tool.jar.md5

Langkah 2: Siapkan file data

Periksa format file

Catat jalur mutlak file atau folder yang akan diimpor.
Identifikasi pemisah baris dan pemisah kolom. Nilai-nilai ini akan dikonfigurasi sebagai parameter skrip.
Pastikan urutan kolom dalam file sesuai dengan pernyataan CREATE TABLE. Jalankan SHOW CREATE TABLE di database untuk memverifikasi. Contoh tabel dan file data yang sesuai adalah sebagai berikut:
```
CREATE TABLE `product_info` (
  `id` bigint NOT NULL,
  `name` varchar,
  `price` decimal(15, 2) NOT NULL
)
DISTRIBUTED BY HASH(`id`)
INDEX_ALL='Y';
```
```
1|tv|1000.0
2|computer|2000.0
3|cup|15.8
```
File harus berisi minimal dua kolom. Pemisah tambahan pada kolom terakhir diterima — baik 1|abc|3.0 maupun 1|abc|3.0| valid.

Field kosong secara default dianggap sebagai null. Misalnya, 4||5.0 menyisipkan null ke kolom name, bukan string kosong. Kolom auto-increment ditangani secara otomatis — tidak perlu preprocessing.

Pisahkan file besar

Memisahkan file besar menjadi segmen memungkinkan tool impor membacanya secara konkuren. Ukuran segmen 1 hingga 2 GB direkomendasikan.

Untuk file berukuran 128 GB bernama filename.txt, pisahkan menjadi 64 segmen masing-masing 2 GB:

# split -l$((`wc -l < filename.txt`/64 + 1)) filename.txt filename.txt.split -da 2;

Tool akan membaca ke-64 segmen tersebut secara konkuren selama impor.

Langkah 3: Konfigurasikan skrip impor

File adb-import.sh.template merupakan templat yang dapat digunakan ulang. Salin dan ganti namanya untuk setiap tabel — misalnya, adb-import-product_info.sh untuk tabel product_info.

Parameter wajib

Atur parameter berikut untuk setiap pekerjaan impor:

####################################
# Path ke perintah Java.
# Jika Java sudah ada di PATH Anda, biarkan seperti ini.
####################################
java_cmd=java

####################################
# Jalur mutlak ke JAR tool impor.
# Jika skrip dan JAR berada di direktori yang sama, biarkan seperti ini.
####################################
jar_path=adb-import-tool.jar

####################################
# Pengaturan koneksi database.
# Jika encryptPassword=true, berikan password dalam bentuk Base64-encoded.
####################################
host=host
port=3306
user=adbuser
password=pwd
database=dbname
encryptPassword=false

####################################
# Nama tabel.
####################################
tableName=please_set_table_name

####################################
# Jalur ke file atau folder yang akan diimpor.
# Untuk beberapa file, pisahkan jalur dengan koma (,).
####################################
dataPath=please_set_data_file_path_or_dir_path

####################################
# Jumlah file yang diimpor secara konkuren.
# Untuk memanfaatkan performa AnalyticDB for MySQL secara optimal, atur parameter ini
# ke angka dalam rentang 16 hingga 96.
####################################
concurrency=64

####################################
# Jumlah nilai yang ditulis saat operasi impor dilakukan.
# Tentukan parameter ini berdasarkan panjang baris individual.
# Untuk memanfaatkan performa AnalyticDB for MySQL secara optimal, atur parameter ini
# ke angka dalam rentang 1024 hingga 4096.
# Batch yang lebih kecil memudahkan identifikasi baris gagal secara individual.
####################################
batchSize=4096

####################################
# Encoding file. Nilai valid: UTF-8, GBK.
####################################
encoding=UTF-8

####################################
# Pemisah baris.
# Untuk karakter non-printable, gunakan notasi heksadesimal.
# Contoh: \x0d\x06\x08\x0a -> hex0d06080a
####################################
lineSeparator="\\n"

####################################
# Pemisah kolom.
# Untuk karakter non-printable, gunakan notasi heksadesimal.
# Contoh: \x07\x07 -> hex0707
####################################
delimiter="\\|"

Parameter opsional

Sesuaikan parameter berikut untuk skenario tertentu:

####################################
# Ukuran heap JVM. Tingkatkan jika Anda melihat garbage collection (GC) sering terjadi.
####################################
jvmopts="-Xmx12G -Xms12G"

####################################
# Jumlah maksimum file yang dibaca secara konkuren dari sebuah folder.
####################################
maxConcurrentNumOfFilesToImport=64

####################################
# Cara menangani field kosong.
# false (default): field kosong menjadi null.
# true: field kosong menjadi '' (string kosong).
####################################
nullAsQuotes=false

####################################
# Cetak jumlah baris aktual tabel tujuan setelah setiap file.
####################################
printRowCount=false

####################################
# Jumlah maksimum karakter yang ditampilkan untuk pernyataan SQL yang gagal.
####################################
failureSqlPrintLengthLimit=1000

####################################
# Mode dry-run. true=tampilkan hanya pernyataan INSERT, false=eksekusi pernyataan tersebut.
####################################
disableInsertOnlyPrintSql=false

####################################
# Lewati baris header di setiap file.
####################################
skipHeader=false

####################################
# Ukuran buffer pool untuk batch INSERT.
# Memisahkan I/O dan komputasi, meningkatkan throughput klien.
####################################
windowSize=128

####################################
# Escape backslash (\) dan apostrof (') dalam nilai kolom.
# true (default): aman untuk semua data tetapi sedikit lebih lambat.
# false: lebih cepat, tetapi hanya gunakan jika data Anda tidak mengandung kedua karakter tersebut.
####################################
escapeSlashAndSingleQuote=true

####################################
# Abaikan batch yang gagal diimpor alih-alih menghentikan proses.
####################################
ignoreErrors=false

####################################
# Cetak pernyataan SQL yang gagal.
####################################
printErrorSql=true

####################################
# Cetak stack trace saat terjadi error SQL.
####################################
printErrorStackTrace=true

Langkah 4: Jalankan impor

Jalankan skrip impor:

sh adb-import-product_info.sh;

Entri log berikut mengonfirmasi bahwa skrip telah dimulai:

[2021-03-13 17:50:24.730] add consumer consumer-01

Tool ini tidak menampilkan progress bar. Untuk memeriksa jumlah baris yang telah dimuat, kueri tabel tujuan:
```
mysql > select count(*) from dbname.product_info;
```
Setelah impor selesai, tool mencetak ringkasan: jumlah baris yang dibaca per file, durasi pemrosesan tiap file, total waktu yang berlalu, serta status keberhasilan semua file.
- Semua file berhasil: all import finished successfully
- Satu atau lebih file gagal: all import finished with ERROR!

Jika terjadi error selama proses impor data, tool impor segera menghentikan operasi dan menampilkan detail pernyataan SQL yang gagal. Tabel tujuan akan berisi data parsial. Jalankan TRUNCATE TABLE table_name untuk mengosongkan tabel tujuan, lalu ulangi operasi impor. Alternatifnya, Anda dapat menjalankan DROP TABLE table_name untuk menghapus tabel tujuan dan membuat tabel baru sebelum melakukan impor ulang.

FAQ

Bagaimana cara memeriksa apakah bottleneck berada di sisi klien atau server?

Jalankan perintah berikut di mesin klien untuk mengidentifikasi saturasi resource:

Perintah	Apa yang ditampilkan
`top`	Utilisasi CPU
`free`	Penggunaan memori
`vmstat 1 1000`	Beban sistem secara keseluruhan
`dstat -all --disk-util` atau `iostat 1 1000`	Bandwidth baca disk dan utilisasi
`jstat -gc <pid> 1000`	Detail garbage collection Java

Jika jstat menunjukkan GC yang sering terjadi, tingkatkan heap JVM dengan mengatur jvmopts menjadi -Xmx16G -Xms16G.

Bagaimana cara mengimpor beberapa tabel dengan satu skrip?

Jika semua tabel menggunakan pemisah yang sama, parametrisasi tableName dan dataPath:

tableName=$1
dataPath=$2

Kemudian jalankan pemanggilan terpisah untuk setiap tabel:

# sh adb-import.sh table_name001 /path/table_001
# sh adb-import.sh table_name002 /path/table_002
# sh adb-import.sh table_name003 /path/table_003

Bagaimana cara menjalankan impor di latar belakang?

# nohup sh adb-import.sh &

Periksa log:

# tail -f nohup.out

Verifikasi proses sedang berjalan:

# ps -ef|grep import

Bagaimana cara mengabaikan error impor?

Jika terjadi error eksekusi SQL, atur ignoreErrors=true. Tool akan melanjutkan impor dan mencatat file yang terpengaruh, nomor baris awal, serta pernyataan yang gagal. Jika parameter batchSize ditentukan, nomor baris yang bermasalah kurang dari atau sama dengan nomor baris awal ditambah nilai batchSize.

Ketidaksesuaian jumlah kolom tidak dapat diabaikan. Ketika jumlah kolom dalam suatu baris tidak sesuai dengan definisi tabel, tool segera menghentikan pemrosesan file tersebut. Periksa file secara manual sebelum mencoba lagi. Pesan error tampak seperti ini:

[ERROR] 2021-03-22 00:46:40,444 [producer- /test2/data/lineitem.csv.split00.100-41] analyticdb.tool.ImportTool
(ImportTool.java:591) -bad line found and stop import! 16, file = /test2/data/tpch100g/lineitem.csv.split00.100, rowCount = 7, current row = 3|123|179698|145|73200.15|0.06|0.00|R|F|1994-02-02|1994-01-04|1994-02-
23|NONE|AIR|ongside of the furiously brave acco|

Bagaimana cara mempersempit penyebab error impor?

Tiga pendekatan:

Tingkatkan panjang cetak SQL untuk melihat lebih banyak bagian pernyataan yang gagal:
```
printErrorSql=true
failureSqlPrintLengthLimit=1500
```
Kurangi `batchSize` untuk mengidentifikasi baris bermasalah:
```
batchSize=10
```
Isolasi segmen file tertentu jika Anda telah mengidentifikasi file split mana yang berisi error:
```
dataPath=/u01/this/is/the/directory/where/product_info/stores/file007
```

Bagaimana cara menjalankan tool di Windows?

Di Windows, skrip shell tidak tersedia. Panggil JAR secara langsung melalui command-line interface:

usage: java -jar adb-import-tool.jar [-a <arg>] [-b <arg>] [-B <arg>] [-c <arg>]
      [-D <arg>] [-d <arg>] [-E <arg>] [-f <arg>] [-h <arg>] [-I <arg>]
      [-k <arg>] [-l <arg>] [-m <arg>] [-n <arg>] [-N <arg>] [-O <arg>]
      [-o <arg>] [-p <arg>] [-P <arg>] [-Q <arg>] [-s <arg>]  [-S <arg>]
      [-t <arg>] [-T <arg>] [-u <arg>] [-w <arg>][-x <arg>] [-y <arg>] [-z <arg>]

Parameter wajib:

Flag	Deskripsi
`-h, --ip <arg>`	Titik akhir kluster
`-u, --username <arg>`	Akun database
`-p, --password <arg>`	Password akun
`-P, --port <arg>`	Nomor port
`-D, --databaseName <arg>`	Nama database
`-f, --dataFile <arg>`	Jalur mutlak ke file atau folder. Untuk beberapa file, pisahkan jalur dengan koma (,).
`-t, --tableName <arg>`	Nama tabel tujuan

Parameter opsional:

Flag	Default	Deskripsi
`-a, --createEmptyFinishFilePath <arg>`	(kosong)	Membuat file penanda saat impor selesai. Biarkan kosong untuk menonaktifkan.
`-b, --batchSize <arg>`	`1`	Jumlah baris per batch INSERT. Atur antara 1024 dan 4096 untuk throughput terbaik.
`-B, --encryptPassword <arg>`	`false`	Aktifkan enkripsi password Base64.
`-c, --printRowCount <arg>`	`false`	Cetak jumlah baris tabel tujuan setelah setiap file.
`-d, --skipHeader <arg>`	`false`	Lewati baris pertama setiap file.
`-E, --escapeSlashAndSingleQuote <arg>`	`true`	Escape `\` dan `'` dalam nilai kolom. Atur ke `false` jika data Anda tidak mengandung kedua karakter tersebut.
`-I, --ignoreErrors <arg>`	`false`	Lanjutkan impor saat terjadi error SQL.
`-k, --skipLineNum <arg>`	`0`	Jumlah baris yang dilewati di awal setiap file (mirip dengan `IGNORE number LINES`).
`-l, --delimiter <arg>`	`\|`	Pemisah kolom. Untuk karakter non-printable, gunakan notasi heksa (misalnya, `\x07\x07` -> `hex0707`).
`-m, --maxConcurrentNumOfFilesToImport <arg>`	`Integer.MAX_VALUE`	Jumlah maksimum file yang dibaca secara konkuren dari sebuah folder.
`-n, --nullAsQuotes <arg>`	`false`	`false`: field kosong -> null. `true`: field kosong -> `''`.
`-N, --printErrorSql <arg>`	`true`	Cetak pernyataan SQL yang gagal dijalankan.
`-O, --connectionPoolSize <arg>`	`2`	Ukuran kolam koneksi database.
`-o, --encoding <arg>`	`UTF-8`	Encoding file. Nilai valid: `GBK`, `UTF-8`.
`-Q, --disableInsertOnlyPrintSql <arg>`	`false`	`true`: cetak pernyataan INSERT tanpa mengeksekusi. `false`: eksekusi pernyataan tersebut.
`-s, --lineSeparator <arg>`	`\n`	Pemisah baris. Untuk karakter non-printable, gunakan notasi heksa (misalnya, `\x0d\x06\x08\x0a` -> `hex0d06080a`).
`-S, --printErrorStackTrace <arg>`	`false`	Cetak stack trace saat terjadi error SQL.
`-w, --windowSize <arg>`	`128`	Ukuran buffer pool untuk batch INSERT. Memisahkan I/O dari komputasi untuk meningkatkan performa klien.
`-x, --insertWithColumnNames <arg>`	`true`	Tambahkan nama kolom ke pernyataan INSERT (misalnya, `INSERT INTO tb(column1, column2)`).
`-y, --failureSqlPrintLengthLimit <arg>`	`1000`	Jumlah maksimum karakter yang ditampilkan untuk pernyataan SQL yang gagal.
`-z, --connectionUrlParam <arg>`	`?characterEncoding=utf-8`	Parameter koneksi JDBC tambahan. Contoh: `?characterEncoding=utf-8&autoReconnect=true`.

Contoh:

Impor satu file dengan parameter default:

java -Xmx8G -Xms8G -jar adb-import-tool.jar \
  -hyourhost.ads.aliyuncs.com -uadbuser -ppassword -P3306 -Dtest \
  --dataFile /data/lineitem.sample --tableName LINEITEM

Impor semua file dalam folder dengan throughput maksimum:

java -Xmx16G -Xms16G -jar adb-import-tool.jar \
  -hyourhost.ads.aliyuncs.com -uadbuser -ppassword -P3306 -Dtest \
  --dataFile /data/tpch100g --tableName LINEITEM \
  --concurrency 64 --batchSize 2048