Topik ini menjelaskan cara menggunakan ApsaraDB for SelectDB dengan sumber data Java Database Connectivity (JDBC). Koneksi ini memungkinkan Anda melakukan analisis federasi pada sumber data yang kompatibel dengan JDBC.
Ikhtisar
Catalog JDBC memungkinkan Anda terhubung ke sumber data lain melalui protokol JDBC standar. Setelah koneksi terbentuk, SelectDB secara otomatis menyinkronkan metadata database dan tabel dari sumber data tersebut, sehingga memungkinkan akses cepat ke data eksternal.
SelectDB mendukung sumber data JDBC berikut: MySQL, PostgreSQL, Oracle, SQLServer, ClickHouse, Doris, SAP HANA, Trino/Presto, dan OceanBase.
Prasyarat
Pastikan semua node dalam kluster sumber data dan instans SelectDB dapat saling berkomunikasi melalui jaringan.
Semua node dalam kluster sumber data dan instans SelectDB berada dalam Virtual Private Cloud (VPC) yang sama. Jika tidak, Anda harus menyelesaikan masalah konektivitas jaringan terlebih dahulu. Untuk informasi selengkapnya, lihat Cara menyelesaikan masalah konektivitas jaringan antara instans SelectDB dan sumber data?
Alamat IP semua node dalam kluster sumber data telah ditambahkan ke daftar putih instans SelectDB. Untuk informasi selengkapnya, lihat Konfigurasi daftar putih.
Jika kluster sumber menggunakan daftar putih, tambahkan Blok CIDR instans SelectDB ke daftar putih kluster sumber.
Untuk mendapatkan alamat IP instans SelectDB dalam VPC tempat instans tersebut berada, Anda dapat mengikuti langkah-langkah yang disediakan di Cara melihat alamat IP dalam VPC tempat instans ApsaraDB SelectDB saya berada?
Untuk mendapatkan Alamat IP publik instans SelectDB, Anda dapat menjalankan perintah ping terhadap Titik akhir publik instans SelectDB untuk memperoleh alamat IP-nya.
Anda memiliki pemahaman dasar tentang catalog dan operasinya. Untuk informasi selengkapnya, lihat Data lakehouse.
Sintaksis
CREATE CATALOG <catalog_name>
PROPERTIES ("key"="value", ...)Parameter
Parameter | Wajib | Nilai default | Deskripsi |
user | Ya | Tidak ada | Username untuk akun database. |
password | Ya | Tidak ada | Password untuk akun database. |
jdbc_url | Ya | Tidak ada | String koneksi JDBC. |
driver_url | Ya | Tidak ada | Nama file JAR driver JDBC. |
driver_class | Ya | Tidak ada | Nama kelas driver JDBC. |
lower_case_table_names | Tidak | "false" | Menentukan apakah nama database dan tabel dari sumber data JDBC eksternal akan disinkronkan dalam huruf kecil. |
only_specified_database | Tidak | "false" | Menentukan apakah hanya database tertentu yang akan disinkronkan. |
include_database_list | Tidak | "" | Jika |
exclude_database_list | Tidak | "" | Jika |
Jalur paket driver
Saat membuat catalog JDBC, Anda harus menentukan jalur paket driver untuk database yang sesuai. Parameter driver_url dapat ditentukan dengan salah satu cara berikut:
Nama file. Misalnya,
mysql-connector-java-8.0.25.jar. SelectDB secara otomatis mencari file JAR yang sesuai di direktori lokaljdbc_drivers/. Secara default, direktori ini berisi empat paket driver umum berikut yang siap digunakan:mysql-connector-java-8.0.25.jar,postgresql-42.5.1.jar,mssql-jdbc-11.2.3.jre8.jar, danojdbc8.jar.URL HTTP. Misalnya,
https://doris-community-test-1308700295.cos.ap-hongkong.myqcloud.com/jdbc_driver/mysql-connector-java-8.0.25.jar. SelectDB mengunduh file driver dari URL ini. Hanya layanan HTTP tanpa autentikasi yang didukung.
Sinkronisasi nama tabel huruf kecil
Ketika parameter lower_case_table_names diatur ke true, SelectDB dapat mengkueri database dan tabel dengan nama huruf besar atau campuran dengan mempertahankan pemetaan dari nama huruf kecil ke nama sebenarnya di sistem remote.
SelectDB 2.X hanya mendukung database Oracle dan mengubah semua nama database serta tabel menjadi huruf besar saat mengeksekusi kueri. Misalnya,
Pada SelectDB 2.X, fitur ini hanya berlaku untuk database Oracle. Saat menjalankan kueri, semua nama database dan tabel diubah menjadi huruf besar sebelum dikirim ke Oracle. Sebagai contoh, jika database Oracle memiliki tabel bernama TEST dalam skema TEST dan Anda mengatur
lower_case_table_names=truesaat membuat catalog di SelectDB, Anda dapat mengkueri tabel tersebut dengan perintahSELECT * FROM oracle_catalog.test.test. SelectDB secara otomatis mengubahtest.testmenjadiTEST.TESTsebelum mengirim kueri ke Oracle. Perlu diperhatikan bahwa ini adalah perilaku default, sehingga Anda tidak dapat mengkueri tabel dengan nama huruf kecil di Oracle.Untuk database lain, Anda harus menggunakan nama database dan tabel yang sebenarnya dalam kueri Anda.
Pada SelectDB 3.X dan versi selanjutnya, fitur ini berlaku untuk semua database. Saat menjalankan kueri, semua nama database dan tabel diubah menjadi nama sebenarnya sebelum dieksekusi. Jika Anda melakukan upgrade ke versi 3.X dari versi sebelumnya, jalankan perintah
Refresh <catalog_name>agar perubahan ini berlaku.Namun, jika nama database atau tabel hanya berbeda dalam hal kapitalisasi—misalnya,
SelectDBdanselectdb—SelectDB tidak dapat mengkuerinya karena ambiguitas.Jika parameter
lower_case_table_namespada frontend (FE) diatur ke 1 atau 2, maka parameterlower_case_table_namesuntuk catalog JDBC harus diatur ke true. Jika parameterlower_case_table_namespada FE diatur ke 0, parameter untuk catalog JDBC dapat diatur ke true atau false, dengan nilai default false. Hal ini memastikan konsistensi dan prediktabilitas saat SelectDB menangani konfigurasi tabel internal dan eksternal.
Sinkronkan database tertentu
Parameter berikut terkait dengan sinkronisasi database tertentu:
only_specified_database: Saat terhubung melalui JDBC, Anda dapat menentukan database atau skema mana yang akan dihubungkan. Misalnya, Anda dapat menentukan database dalamjdbc_urluntuk MySQL, atau menentukan `currentSchema` dalamjdbc_urluntuk PostgreSQL.include_database_list: Parameter ini hanya berlaku ketikaonly_specified_database=true. Parameter ini menentukan database yang akan disinkronkan. Pisahkan beberapa nama database dengan koma (,). Nama database bersifat case-sensitive.exclude_database_list: Parameter ini hanya berlaku ketikaonly_specified_database=true. Parameter ini menentukan database yang dikecualikan dari sinkronisasi. Pisahkan beberapa nama database dengan koma (,). Nama database bersifat case-sensitive.
Jika suatu database dikonfigurasi di kedua parameter
include_database_listdanexclude_database_list, makaexclude_database_listmemiliki prioritas lebih tinggi.Jika Anda menggunakan parameter ini untuk terhubung ke database Oracle, pastikan menggunakan paket JAR
ojdbc8.jaratau versi yang lebih baru.
Contoh
MySQL
Contoh
CREATE CATALOG jdbc_mysql PROPERTIES (
"type"="jdbc",
"user"="root",
"password"="123456",
"jdbc_url" = "jdbc:mysql://127.0.0.1:3306/demo",
"driver_url" = "mysql-connector-java-8.0.25.jar",
"driver_class" = "com.mysql.cj.jdbc.Driver"
)Pemetaan level
SelectDB | MySQL |
Catalog | MySQL Server |
Database | Database |
Tabel | Tabel |
Pemetaan tipe
Tipe MYSQL | Tipe SelectDB | Catatan |
BOOLEAN | TINYINT | Tidak ada |
TINYINT | TINYINT | Tidak ada |
SMALLINT | SMALLINT | Tidak ada |
MEDIUMINT | INT | Tidak ada |
INT | INT | Tidak ada |
BIGINT | BIGINT | Tidak ada |
UNSIGNED TINYINT | SMALLINT | SelectDB tidak memiliki tipe data UNSIGNED, sehingga rentang nilainya diperluas ke level berikutnya. |
UNSIGNED MEDIUMINT | INT | SelectDB tidak memiliki tipe data UNSIGNED, sehingga rentang nilainya diperluas ke level berikutnya. |
UNSIGNED INT | BIGINT | SelectDB tidak memiliki tipe data UNSIGNED, sehingga rentang nilainya diperluas ke level berikutnya. |
UNSIGNED BIGINT | LARGEINT | Tidak ada |
FLOAT | FLOAT | Tidak ada |
DOUBLE | DOUBLE | Tidak ada |
DECIMAL | DECIMAL | Tidak ada |
UNSIGNED DECIMAL(p,s) | DECIMAL(p+1,s) / STRING | Jika |
DATE | DATE | Tidak ada |
TIMESTAMP | DATETIME | Tidak ada |
DATETIME | DATETIME | Tidak ada |
YEAR | SMALLINT | Tidak ada |
TIME | STRING | Tidak ada |
CHAR | CHAR | Tidak ada |
VARCHAR | VARCHAR | Tidak ada |
JSON | JSON | Tidak ada |
SET | STRING | Tidak ada |
BIT | BOOLEAN/STRING | BIT(1) dipetakan ke BOOLEAN. Tipe BIT lainnya dipetakan ke STRING. |
TINYTEXT, TEXT, MEDIUMTEXT, LONGTEXT | STRING | Tidak ada |
BLOB, MEDIUMBLOB, LONGBLOB, TINYBLOB | STRING | Tidak ada |
TINYSTRING, STRING, MEDIUMSTRING, LONGSTRING | STRING | Tidak ada |
BINARY, VARBINARY | STRING | Tidak ada |
Lainnya | TIDAK DIDUKUNG | Tidak ada |
PostgreSQL
Contoh
CREATE CATALOG jdbc_postgresql PROPERTIES (
"type"="jdbc",
"user"="root",
"password"="123456",
"jdbc_url" = "jdbc:postgresql://127.0.0.1:5432/demo",
"driver_url" = "postgresql-42.5.1.jar",
"driver_class" = "org.postgresql.Driver"
);Pemetaan level
Saat memetakan PostgreSQL, database SelectDB berkorespondensi dengan skema dalam catalog PostgreSQL yang ditentukan—misalnya, skema dalam database demo dari jdbc_url pada contoh sebelumnya. Tabel dalam database SelectDB berkorespondensi dengan tabel dalam skema PostgreSQL. Pemetaannya sebagai berikut:
SelectDB | PostgreSQL |
Catalog | Database |
Database | Skema |
Tabel | Tabel |
SelectDB menjalankan pernyataan SQL SELECT nspname FROM pg_namespace WHERE has_schema_privilege('<UserName>', nspname, 'USAGE'); untuk mengambil semua skema yang dapat diakses oleh pengguna PostgreSQL dan memetakannya ke database SelectDB.
Pemetaan tipe
Tipe POSTGRESQL | Tipe SelectDB | Catatan |
boolean | BOOLEAN | Tidak ada |
smallint/int2 | SMALLINT | Tidak ada |
integer/int4 | INT | Tidak ada |
bigint/int8 | BIGINT | Tidak ada |
decimal/numeric | DECIMAL | Tidak ada |
real/float4 | FLOAT | Tidak ada |
double precision | DOUBLE | Tidak ada |
smallserial | SMALLINT | Tidak ada |
serial | INT | Tidak ada |
bigserial | BIGINT | Tidak ada |
char | CHAR | Tidak ada |
varchar/text | STRING | Tidak ada |
timestamp | DATETIME | Tidak ada |
date | DATE | Tidak ada |
json/jsonb | JSON | Tidak ada |
time | STRING | Tidak ada |
interval | STRING | Tidak ada |
point/line/lseg/box/path/polygon/circle | STRING | Tidak ada |
cidr/inet/macaddr | STRING | Tidak ada |
bit | BOOLEAN/STRING | bit(1) dipetakan ke BOOLEAN. Tipe bit lainnya dipetakan ke STRING. |
uuid | STRING | Tidak ada |
Lainnya | TIDAK DIDUKUNG | Tidak ada |
Oracle
Contoh
CREATE CATALOG jdbc_oracle PROPERTIES (
"type"="jdbc",
"user"="root",
"password"="123456",
"jdbc_url" = "jdbc:oracle:thin:@127.0.0.1:1521:helowin",
"driver_url" = "ojdbc8.jar",
"driver_class" = "oracle.jdbc.driver.OracleDriver"
);Pemetaan level
Saat memetakan Oracle, database SelectDB berkorespondensi dengan pengguna di Oracle. Tabel dalam database SelectDB berkorespondensi dengan tabel yang memiliki izin akses oleh pengguna tersebut di Oracle. Pemetaannya sebagai berikut:
SelectDB | Oracle |
Catalog | Database |
Database | Pengguna |
Tabel | Tabel |
Sinkronisasi tabel SYNONYM Oracle tidak didukung.
Pemetaan tipe
Tipe ORACLE | Tipe SelectDB | Catatan |
number(p) / number(p,0) | TINYINT/SMALLINT/INT/BIGINT/LARGEINT | SelectDB memilih tipe yang sesuai berdasarkan nilai p:
|
number(p,s),[ if(s>0 && p>s) ] | DECIMAL(p,s) | Tidak ada |
number(p,s),[ if(s>0 && p < s) ] | DECIMAL(s,s) | Tidak ada |
number(p,s),[ if(s<0) ] | TINYINT/SMALLINT/INT/BIGINT/LARGEINT | Jika |
number | Tidak ada | SelectDB saat ini tidak mendukung tipe Oracle di mana p dan s tidak ditentukan. |
decimal | DECIMAL | Tidak ada |
float/real | DOUBLE | Tidak ada |
DATE | DATETIME | Tidak ada |
TIMESTAMP | DATETIME | Tidak ada |
CHAR/NCHAR | STRING | Tidak ada |
VARCHAR2/NVARCHAR2 | STRING | Tidak ada |
LONG/ RAW/ LONG RAW/ INTERVAL | STRING | Tidak ada |
Lainnya | TIDAK DIDUKUNG | Tidak ada |
SQLServer
Contoh
Jika Anda menggunakan SelectDB 3.0.8 atau versi yang lebih baru, sertakan parameter encrypt=false dalam string koneksi jdbc_url untuk memastikan akses ke data di SQL Server.
CREATE CATALOG jdbc_sqlserver PROPERTIES (
"type"="jdbc",
"user"="SA",
"password"="SelectDB123456",
"jdbc_url" = "jdbc:sqlserver://localhost:1433;DataBaseName=SelectDB_test;encrypt=false",
"driver_url" = "mssql-jdbc-11.2.3.jre8.jar",
"driver_class" = "com.microsoft.sqlserver.jdbc.SQLServerDriver"
);Pemetaan level
Saat memetakan SQLServer, database SelectDB berkorespondensi dengan skema dalam database SQLServer yang ditentukan—misalnya, skema dalam database SelectDB_test dari jdbc_url pada contoh sebelumnya. Tabel dalam database SelectDB berkorespondensi dengan tabel dalam skema SQLServer. Pemetaannya sebagai berikut:
SelectDB | SQLServer |
Catalog | Database |
Database | Skema |
Tabel | Tabel |
Pemetaan tipe
Tipe SQLServer | Tipe SelectDB |
bit | BOOLEAN |
tinyint | SMALLINT |
smallint | SMALLINT |
int | INT |
bigint | BIGINT |
real | FLOAT |
float | DOUBLE |
money | DECIMAL(19,4) |
smallmoney | DECIMAL(10,4) |
decimal/numeric | DECIMAL |
date | DATE |
datetime/datetime2/smalldatetime | DATETIMEV2 |
char/varchar/text/nchar/nvarchar/ntext | STRING |
binary/varbinary | STRING |
time/datetimeoffset | STRING |
Lainnya | TIDAK DIDUKUNG |
Doris
Catalog JDBC SelectDB juga mendukung koneksi ke database Doris.
Contoh
CREATE CATALOG jdbc_doris PROPERTIES (
"type"="jdbc",
"user"="root",
"password"="123456",
"jdbc_url" = "jdbc:mysql://127.0.0.1:9030?useSSL=false",
"driver_url" = "mysql-connector-java-8.0.25.jar",
"driver_class" = "com.mysql.cj.jdbc.Driver"
)Pemetaan tipe
Tipe Doris | Tipe Katalog JDBC SelectDB | Catatan |
BOOLEAN | BOOLEAN | Tidak ada |
TINYINT | TINYINT | Tidak ada |
SMALLINT | SMALLINT | Tidak ada |
INT | INT | Tidak ada |
BIGINT | BIGINT | Tidak ada |
LARGEINT | LARGEINT | Tidak ada |
FLOAT | FLOAT | Tidak ada |
DOUBLE | DOUBLE | Tidak ada |
DECIMALV3 | DECIMALV3/STRING | Tipe dipilih berdasarkan presisi dan skala bidang DECIMAL. |
DATE | DATE | Tidak ada |
DATETIME | DATETIME | Tidak ada |
CHAR | CHAR | Tidak ada |
VARCHAR | VARCHAR | Tidak ada |
STRING | STRING | Tidak ada |
TEXT | STRING | Tidak ada |
HLL | HLL | Untuk mengkueri HLL, atur |
Array | Array | Pemetaan tipe internal untuk Array mengikuti logika tipe yang tercantum di atas. Tipe kompleks bersarang tidak didukung. |
BITMAP | BITMAP | Untuk mengkueri BITMAP, atur |
Lainnya | TIDAK DIDUKUNG | Tidak ada |
ClickHouse
Contoh pembuatan
CREATE CATALOG jdbc_clickhouse PROPERTIES (
"type"="jdbc",
"user"="root",
"password"="123456",
"jdbc_url" = "jdbc:clickhouse://127.0.0.1:8123/demo",
"driver_url" = "clickhouse-jdbc-0.4.2-all.jar",
"driver_class" = "com.clickhouse.jdbc.ClickHouseDriver"
);Pemetaan level
SelectDB | ClickHouse |
Catalog | ClickHouse Server |
Database | Database |
Tabel | Tabel |
Pemetaan tipe
Tipe ClickHouse | Tipe SelectDB |
Bool | BOOLEAN |
String | STRING |
Date/Date32 | DATE |
DateTime/DateTime64 | DATETIME |
Float32 | FLOAT |
Float64 | DOUBLE |
Int8 | TINYINT |
Int16/UInt8 | SMALLINT |
Int32/UInt16 | INT |
Int64/Uint32 | BIGINT |
Int128/UInt64 | LARGEINT |
Int256/UInt128/UInt256 | STRING |
DECIMAL | DECIMALV3/STRING |
Enum/IPv4/IPv6/UUID | STRING |
Array | ARRAY |
Lainnya | TIDAK DIDUKUNG |
SAP HANA
Contoh
CREATE CATALOG jdbc_hana PROPERTIES (
"type"="jdbc",
"user"="SYSTEM",
"password"="SAPHANA",
"jdbc_url" = "jdbc:sap://localhost:31515/TEST",
"driver_url" = "ngdbc.jar",
"driver_class" = "com.sap.db.jdbc.Driver"
)Pemetaan level
SelectDB | SAP HANA |
Catalog | Database |
Database | Skema |
Tabel | Tabel |
Pemetaan tipe
Tipe SAP HANA | Tipe SelectDB |
BOOLEAN | BOOLEAN |
TINYINT | TINYINT |
SMALLINT | SMALLINT |
INTEGER | INT |
BIGINT | BIGINT |
SMALLDECIMAL | DECIMALV3 |
DECIMAL | DECIMALV3/STRING |
REAL | FLOAT |
DOUBLE | DOUBLE |
DATE | DATE |
TIME | STRING |
TIMESTAMP | DATETIME |
SECONDDATE | DATETIME |
VARCHAR | STRING |
NVARCHAR | STRING |
ALPHANUM | STRING |
SHORTTEXT | STRING |
CHAR | CHAR |
NCHAR | CHAR |
OceanBase
Contoh
CREATE CATALOG jdbc_oceanbase PROPERTIES (
"type"="jdbc",
"user"="root",
"password"="123456",
"jdbc_url" = "jdbc:oceanbase://127.0.0.1:2881/demo",
"driver_url" = "oceanbase-client-2.4.2.jar",
"driver_class" = "com.oceanbase.jdbc.Driver"
)Saat SelectDB terhubung ke OceanBase, sistem secara otomatis mendeteksi apakah OceanBase beroperasi dalam mode MySQL atau Oracle. Untuk informasi tentang pemetaan level dan pemetaan tipe, lihat bagian MySQL dan Oracle dalam topik ini.
Kueri data
Contoh
SELECT * FROM mysql_catalog.mysql_database.mysql_table WHERE k1 > 1000 AND k3 ='term';Nama bidang mungkin merupakan kata kunci yang dicadangkan oleh database. Untuk memastikan SelectDB tetap dapat mengeksekusi kueri dengan benar dalam kasus ini, SelectDB secara otomatis menambahkan karakter escape ke nama bidang dan tabel dalam pernyataan SQL sesuai dengan standar masing-masing database. Misalnya, backtick (``) digunakan untuk MySQL, tanda kutip ganda ("") untuk PostgreSQL dan Oracle, serta kurung siku ([]) untuk SQLServer. Hal ini dapat menyebabkan nama bidang menjadi case-sensitive. Anda dapat menjalankan perintah SQL EXPLAIN untuk melihat pernyataan kueri yang telah di-escape yang dikirim ke database remote.
Predicate pushdown
Saat menjalankan kueri dengan klausa WHERE, seperti WHERE dt = '2022-01-01', SelectDB dapat mendorong kondisi filter tersebut ke sumber data eksternal. Proses ini menyaring data yang tidak memenuhi syarat di sumbernya, sehingga mengurangi pengambilan dan transfer data jaringan yang tidak perlu. Hal ini secara signifikan meningkatkan performa kueri dan mengurangi beban pada sumber data eksternal.
Jika variabel session enable_func_pushdown diatur ke true, SelectDB juga mendorong fungsi dalam klausa WHERE ke sumber data eksternal. Fitur ini saat ini hanya didukung untuk MySQL. Jika Anda menggunakan fungsi yang tidak didukung oleh MySQL, atur parameter ini ke false. SelectDB secara otomatis mengenali beberapa fungsi yang tidak didukung oleh MySQL dan mengecualikannya dari kondisi pushdown. Anda dapat menjalankan perintah SQL EXPLAIN untuk melihat pernyataan kueri spesifiknya.
Fungsi berikut tidak didukung untuk pushdown: DATE_TRUNC dan MONEY_FORMAT.
Batas jumlah baris
Jika kueri berisi kata kunci LIMIT, SelectDB menerjemahkannya ke semantik yang sesuai untuk berbagai sumber data.
Menulis data
Setelah membuat catalog JDBC di SelectDB, Anda dapat menulis data menggunakan pernyataan INSERT INTO atau INSERT INTO...SELECT. Anda juga dapat menulis hasil kueri dari SelectDB ke catalog JDBC atau mengimpor data dari satu catalog JDBC ke catalog JDBC lainnya.
Pernyataan INSERT INTO tidak efisien untuk menulis data dalam jumlah besar. Sebaiknya gunakan pernyataan INSERT INTO...SELECT sebagai gantinya.
Contoh
INSERT INTO mysql_catalog.mysql_database.mysql_table VALUES(1, "doris");
INSERT INTO mysql_catalog.mysql_database.mysql_table SELECT * FROM table;Transaksi
Data dari SelectDB ditulis ke catalog JDBC secara batch. Jika proses impor terganggu, data yang telah ditulis sebelumnya mungkin perlu di-rollback. Untuk menangani hal ini, Catalog JDBC mendukung transaksi untuk penulisan data. Aktifkan dukungan transaksi dengan mengatur variabel session enable_odbc_transcation.
SET enable_odbc_transcation = TRUE; Transaksi memastikan atomisitas penulisan data ke tabel eksternal JDBC, tetapi mungkin sedikit menurunkan performa penulisan. Aktifkan fitur ini hanya saat diperlukan.