Menggunakan AnalyticDB for PostgreSQL Client SDK untuk Menulis Data - AnalyticDB

Topik ini menjelaskan cara menggunakan AnalyticDB for PostgreSQL Client SDK untuk menulis data ke AnalyticDB for PostgreSQL dengan memanggil operasi API.

AnalyticDB for PostgreSQL Client SDK mendukung pengembangan kustom dan integrasi program penulisan data. Program penulisan data yang dikembangkan menggunakan AnalyticDB for PostgreSQL Client SDK menyederhanakan proses penulisan data serta menyediakan mekanisme internal seperti pemrosesan paralel. Kinerja metode ini beberapa kali lebih tinggi dibandingkan pernyataan COPY dan INSERT. Anda tidak perlu khawatir tentang masalah kolam koneksi atau cache.

Catatan

AnalyticDB for PostgreSQL Client SDK dirancang untuk menulis data secara efisien dan tidak membaca atau memproses data mentah.

Repositori Maven

Anda dapat menggunakan Maven untuk mengonfigurasi versi AnalyticDB for PostgreSQL Client SDK. Contoh kode:

<dependency>
  <groupId>com.alibaba.cloud.analyticdb</groupId>
  <artifactId>adb4pgclient</artifactId>
  <version>1.0.4</version>
</dependency>

Catatan

AnalyticDB for PostgreSQL Client SDK bergantung pada paket-paket berikut: druid(1.1.17), postgresql(jdbc 42.2.5), commons-lang3(3.4), slf4j-api(1.7.24), dan slf4j-log4j12(1.7.24).
Jika sistem memberikan peringatan konflik versi dengan AnalyticDB for PostgreSQL Client SDK, verifikasi bahwa Anda menggunakan versi yang benar dari paket-paket tersebut.

Paket JAR AnalyticDB for PostgreSQL Client SDK: adb4pgclient-1.0.4.jar.

Operasi terkait

Tabel 1. Operasi untuk kelas DatabaseConfig
Operasi	Deskripsi
setHost(String adbHost)	Menentukan titik akhir yang digunakan untuk terhubung ke database AnalyticDB for PostgreSQL.
setPort(int port)	Menentukan nomor port yang digunakan untuk terhubung ke database AnalyticDB for PostgreSQL. Nilai default: 5432.
setDatabase(String database)	Menentukan nama database AnalyticDB for PostgreSQL.
setUser(String username)	Menentukan akun database yang digunakan untuk terhubung ke database AnalyticDB for PostgreSQL.
setPassword(String pwd)	Menentukan kata sandi yang digunakan untuk terhubung ke database AnalyticDB for PostgreSQL.
addTable(List<String> table, String schema)	Menentukan tabel tempat Anda ingin menyisipkan data. Anda dapat memanggil operasi ini beberapa kali. Setiap kali Anda memanggil operasi ini, Anda dapat menentukan tabel yang menggunakan skema yang sama. Setelah Anda menggunakan kelas DatabaseConfig untuk membuat objek Adb4pgClient, operasi ini tidak lagi berlaku.
setColumns(List<String> columns, String tableName, String schemaName)	Menentukan kolom yang ingin Anda sisipkan ke dalam tabel. Jika Anda ingin menyisipkan semua kolom ke dalam tabel, atur parameter kolom menjadi `columnList.add("*")`. Anda harus menentukan kolom untuk semua tabel yang terdaftar dalam parameter tabel. Jika tidak, operasi ini gagal dalam pemeriksaan sistem.
setInsertIgnore(boolean insertIgnore)	Menentukan apakah akan mengabaikan baris yang memiliki kunci utama yang bertentangan. Operasi ini berlaku untuk semua tabel yang ditentukan. Nilai default: false. Dalam hal ini, baris yang memiliki kunci utama yang bertentangan akan ditimpa.
setEmptyAsNull(boolean emptyAsNull)	Menentukan apakah akan menetapkan nilai kosong sebagai null. Operasi ini berlaku untuk semua tabel yang ditentukan. Nilai default: false.
setParallelNumber(int parallelNumber)	Menentukan jumlah maksimum thread konkuren yang digunakan untuk menulis data ke database AnalyticDB for PostgreSQL. Operasi ini berlaku untuk semua tabel yang ditentukan. Nilai default: 4. Kami merekomendasikan agar Anda mempertahankan nilai default.
setLogger(Logger logger)	Menentukan logger yang digunakan oleh objek Adb4pgClient. Di AnalyticDB for PostgreSQL, slf4j.Logger digunakan.
setRetryTimes(int retryTimes)	Menentukan jumlah maksimum percobaan ulang untuk melakukan commit data ketika terjadi kesalahan. Nilai default: 3.
setRetryIntervalTime(long retryIntervalTime)	Menentukan interval antara setiap dua percobaan ulang. Unit: milidetik. Nilai default: 1000.
setCommitSize(long commitSize)	Menentukan jumlah data yang secara otomatis di-commit. Unit: byte. Nilai default: 10.000.000. Kami merekomendasikan agar Anda mempertahankan nilai default.

Tabel 2. Operasi untuk kelas Row
Operasi	Deskripsi
setColumn(int index, Object value)	Menentukan nilai kolom dalam baris. Anda dapat memanggil operasi ini beberapa kali berdasarkan urutan kolom dalam baris untuk menentukan beberapa kolom. Operasi ini tidak mendukung penggunaan kembali objek baris. Setiap catatan data harus dikaitkan dengan objek baris tertentu.
setColumnValues(List<Object> values)	Menentukan nilai beberapa kolom dalam baris.
updateColumn(int index, Object value)	Memperbarui nilai kolom dalam baris. Operasi ini memungkinkan Anda menggunakan kembali objek baris dengan memperbarui data.

Tabel 3. Operasi untuk kelas Adb4pgClient
Operasi	Deskripsi
addRow(Row row, String tableName, String schemaName) / addRows(List<Row> rows, String tableName, String schemaName)	Menyisipkan satu atau lebih catatan data berformat baris ke dalam tabel. Catatan data disimpan dalam buffer AnalyticDB for PostgreSQL Client SDK hingga di-commit. Jika jumlah catatan mencapai nilai parameter commitSize, sistem akan melakukan commit otomatis saat Anda memanggil operasi addRow atau addRows. Jika commit otomatis gagal, sistem melaporkan kesalahan yang berisi catatan data yang gagal. Anda harus menangani kesalahan sesuai informasi yang diberikan.
addMap(Map<String, String> dataMap,String tableName, String schemaName) / addMaps(List<Map<String, String>> dataMaps, String tableName, String schemaName)	Menyisipkan satu atau lebih catatan data berformat peta ke dalam tabel. Catatan data disimpan dalam buffer AnalyticDB for PostgreSQL Client SDK. Jika jumlah catatan mencapai nilai parameter commitSize, sistem akan melakukan commit otomatis saat Anda memanggil operasi addMap atau addMaps. Jika commit otomatis gagal, sistem melaporkan kesalahan yang berisi catatan data yang gagal. Anda harus menangani kesalahan sesuai informasi yang diberikan.
commit()	Melakukan commit data yang disimpan dalam buffer AnalyticDB for PostgreSQL Client SDK. Jika commit gagal, sistem akan melaporkan kesalahan dengan pernyataan yang gagal. Anda harus menangani kesalahan tersebut berdasarkan informasi yang diberikan.
TableInfo getTableInfo(String tableName, String schemaName)	Mendapatkan skema tabel.
List<ColumnInfo> getColumnInfo(String tableName, String schemaName)	Mendapatkan kolom tabel. Anda dapat memanggil operasi `columnInfo.isNullable()` untuk memeriksa apakah kelas ColumnInfo dapat bernilai null.
stop()	Melepaskan kolam thread internal dan sumber daya yang digunakan oleh objek Adb4pgClient setelah selesai digunakan. Jika catatan data dalam buffer belum di-commit saat Anda memanggil operasi ini, sistem melaporkan kesalahan. Untuk melepaskan kolam thread internal dan sumber daya secara paksa, panggil operasi `forceStop()`.
forceStop()	Melepaskan secara paksa kolam thread internal dan sumber daya yang digunakan oleh objek Adb4pgClient. Setelah Anda memanggil operasi ini, catatan data yang belum di-commit dalam buffer akan hilang. Kami merekomendasikan agar Anda tidak memanggil operasi ini kecuali diperlukan.
Connection getConnection() throws SQLException	Mengambil koneksi ke database AnalyticDB for PostgreSQL dari kolam koneksi objek Adb4pgClient. Koneksi yang diambil bekerja seperti koneksi Java Database Connectivity (JDBC). Anda dapat menggunakan koneksi ini untuk melakukan operasi penulisan kecuali COPY. Catatan Anda harus melepaskan sumber daya seperti ResultSet, Statement, dan Connection yang digunakan oleh objek Adb4pgClient setelah selesai digunakan.

Tabel 4. Operasi untuk kelas ColumnInfo
Operasi	Deskripsi
boolean isNullable()	Menentukan apakah kelas ColumnInfo dapat bernilai null.

Kode kesalahan	Kode status HTTP	Deskripsi
COMMIT_ERROR_DATA_LIST	101	Kesalahan yang dikembalikan karena beberapa catatan data gagal di-commit. Catatan Anda dapat memanggil operasi `e.getErrData()` untuk mendapatkan daftar catatan data yang gagal (List<String>). Kesalahan ini mungkin dikembalikan untuk operasi `addMap`, addMaps, `addRow`, addRows, dan `commit`. Anda harus menangani kesalahan ini secara terpisah untuk setiap operasi.
COMMIT_ERROR_OTHER	102	Kesalahan yang dikembalikan karena pengecualian selain kegagalan commit terjadi.
ADD_DATA_ERROR	103	Kesalahan yang dikembalikan karena catatan data gagal ditambahkan.
CREATE_CONNECTION_ERROR	104	Kesalahan yang dikembalikan karena koneksi gagal dibuat.
CLOSE_CONNECTION_ERROR	105	Kesalahan yang dikembalikan karena koneksi gagal ditutup.
CONFIG_ERROR	106	Kesalahan yang dikembalikan karena konfigurasi kelas DatabaseConfig gagal.
STOP_ERROR	107	Kesalahan yang dikembalikan karena objek Adb4pgClient gagal dihentikan.
OTHER	999	Kesalahan default yang dikembalikan.

Contoh kode

public class Adb4pgClientUsage {
    public void demo() {
        DatabaseConfig databaseConfig = new DatabaseConfig();
        // Harus menetapkan host atau url database sebenarnya
        databaseConfig.setHost("100.100.100.100");
        // Harus menetapkan port database sebenarnya
        databaseConfig.setPort(8888);
        // Tentukan akun database yang digunakan untuk terhubung ke database AnalyticDB for PostgreSQL Anda.
        databaseConfig.setUser("nama pengguna Anda");
        // Tentukan kata sandi yang digunakan untuk terhubung ke database AnalyticDB for PostgreSQL Anda.
        databaseConfig.setPassword("kata sandi Anda");
      // Tentukan nama database AnalyticDB for PostgreSQL Anda.
        databaseConfig.setDatabase("nama database Anda");
        // Tentukan tabel tempat Anda ingin menyisipkan data.
        List<String> tables = new ArrayList<String>();
        tables.add("nama tabel Anda 1");
        tables.add("nama tabel Anda 2");

        // Anda dapat memanggil operasi addTable untuk menentukan tabel yang menggunakan skema yang sama. Setelah Anda menggunakan kelas DatabaseConfig untuk membuat objek Adb4pgClient, tabel yang ditentukan tidak dapat diubah.
        // Jika Anda menetapkan parameter nama skema tabel menjadi null, skema publik digunakan.
        databaseConfig.addTable(tables, "nama skema tabel");

        // Tentukan kolom yang ingin Anda sisipkan ke dalam tabel.
        List<String> columns = new ArrayList<String>();
        columns.add("kolom1");
        columns.add("kolom2");
        // Jika Anda ingin menyisipkan semua kolom ke dalam tabel, atur parameter kolom menjadi columns.add("*").
        databaseConfig.setColumns(columns, "nama tabel Anda 1", "nama skema tabel");
        databaseConfig.setColumns(Collections.singletonList("*"),"nama tabel Anda 2", "nama skema tabel");


        // Jika nilai kolom kosong, atur null
        databaseConfig.setEmptyAsNull(false);
        // Tentukan apakah mengabaikan baris yang memiliki kunci utama yang bertentangan.
        databaseConfig.setInsertIgnore(true);
        // Jika data gagal di-commit ke AnalyticDB for PostgreSQL, Anda dapat mencoba melakukan commit ulang hingga tiga kali.
        databaseConfig.setRetryTimes(3);
        // Tetapkan interval percobaan ulang 1000 milidetik.
        databaseConfig.setRetryIntervalTime(1000);
        // Inisialisasi objek Adb4pgClient. Setelah Anda menginisialisasi objek Adb4pgClient, Anda tidak dapat mengubah konfigurasi kelas DatabaseConfig.
        Adb4pgClient adbClient = new Adb4pgClient(databaseConfig);

        // Simpan catatan data ke buffer AnalyticDB for PostgreSQL Client SDK dan kemudian lakukan commit catatan sekaligus. Untuk informasi lebih lanjut, lihat bagian "Catatan Penggunaan" dari topik ini.
        for (int i = 0; i < 10; i++) {
            // Tambahkan baris ke buffer. Satu instance untuk satu catatan
            Row row = new Row(columns.size());
            // Tetapkan kolom
            // indeks kolom harus sesuai dengan urutan kolom
            // nilai kolom dapat berupa jenis apa pun, secara internal akan diformat sesuai dengan jenis kolom
            row.setColumn(0, i); // Nilai angka
            row.setColumn(1, "nilai string"); // Nilai string
            // Jika jumlah catatan data dalam buffer mencapai batas atas, sistem secara otomatis melakukan commit catatan ketika Anda memanggil operasi addRow atau addMap.
            // Jika commit otomatis gagal, sistem mengembalikan kesalahan COMMIT_ERROR_DATA_LIST.
            adbClient.addRow(row, "nama tabel Anda 1", "nama skema tabel");
        }

        Row row = new Row();
        row.setColumn(0, 10); // Nilai angka
        row.setColumn(1, "2018-01-01 08:00:00"); // Nilai tanggal/waktu/timestamp
        adbClient.addRow(row, "nama tabel Anda 1", "nama skema tabel");
        // Perbarui kolom. Objek Row dapat digunakan kembali.
        row.updateColumn(0, 11);
        row.updateColumn(1, "2018-01-02 08:00:00");
        adbClient.addRow(row, "nama tabel Anda 1", "nama skema tabel");

        // Tambahkan peta ke buffer
        Map<String, String> rowMap = new HashMap<String, String>();
        rowMap.put("t1", "12");
        rowMap.put("t2", "nilai string");
        // Jika Anda ingin melakukan commit beberapa catatan data, kami merekomendasikan agar Anda menyimpan catatan ke buffer AnalyticDB for PostgreSQL Client SDK dan kemudian melakukan commit catatan sekaligus.
        adbClient.addMap(rowMap, "nama tabel Anda 2", "nama skema tabel");

        // Commit buffer ke ADS
        // Buffer dibersihkan setelah berhasil commit ke ADS
        try {
            adbClient.commit();
        } catch (Exception e) {
            // TODO: Tangani pengecualian di sini
        } finally {
            adbClient.stop();
        }
    }

}

Catatan Penggunaan

AnalyticDB for PostgreSQL Client SDK tidak aman untuk thread. Jika Anda memanggil lebih dari satu thread, pastikan setiap thread memiliki objek Adb4pgClient-nya sendiri.
Penting
Jika beberapa thread berbagi objek Adb4pgClient yang sama, masalah keamanan akan muncul dan kinerja penulisan data menurun.
Sebuah catatan data dianggap telah ditulis ke AnalyticDB for PostgreSQL hanya setelah di-commit.
Jika objek Adb4pgClient mengembalikan kesalahan, Anda harus menangani kesalahan tersebut sesuai informasi yang diberikan. Jika sebuah catatan data tidak dapat di-commit, Anda dapat mencoba melakukan commit ulang atau melewati catatan data yang gagal setelah mencatatnya.
Saat menulis data ke AnalyticDB for PostgreSQL, catatan data mungkin disimpan ke buffer dan di-commit secara batch untuk meningkatkan pemanfaatan CPU. Kami merekomendasikan agar Anda mempertahankan jumlah thread yang sesuai dan memantau status pengumpulan sampah aplikasi Anda.
Kami merekomendasikan agar Anda melakukan commit 10.000 catatan data sekaligus.
Anda harus menyelesaikan konfigurasi kelas DatabaseConfig sebelum membuat objek Adb4pgClient. Setelah objek Adb4pgClient dibuat, Anda tidak dapat mengubah konfigurasi kelas DatabaseConfig.
AnalyticDB for PostgreSQL Client SDK bertujuan untuk mengoptimalkan penulisan data (pernyataan INSERT). Untuk mengoptimalkan eksekusi pernyataan SQL lainnya, panggil operasi getConnection() untuk menetapkan koneksi JDBC.