JDBC數(shù)據(jù)源
本文介紹云數(shù)據(jù)庫 SelectDB 版與JDBC數(shù)據(jù)源進(jìn)行對接使用的流程,幫助您對兼容JDBC協(xié)議的數(shù)據(jù)源進(jìn)行聯(lián)邦分析。
概述
JDBC Catalog支持通過標(biāo)準(zhǔn)JDBC協(xié)議連接其他數(shù)據(jù)源。連接后,SelectDB會自動同步數(shù)據(jù)源下的Database和Table的元數(shù)據(jù),以便快速訪問這些外部數(shù)據(jù)。
SelectDB支持選擇MySQL、PostgreSQL、Oracle、SQLServer、Clickhouse、Doris、SPA HANA、Trino/Presto、OceanBase作為JDBC數(shù)據(jù)源。
創(chuàng)建語法
CREATE CATALOG <catalog_name>
PROPERTIES ("key"="value", ...)
參數(shù)說明
參數(shù) | 是否必選 | 默認(rèn)值 | 說明 |
user | 是 | 無 | 對應(yīng)數(shù)據(jù)庫的賬號。 |
password | 是 | 無 | 對應(yīng)數(shù)據(jù)庫的密碼。 |
jdbc_url | 是 | 無 | JDBC連接串。 |
driver_url | 是 | 無 | JDBC Driver Jar包名稱。 |
driver_class | 是 | 無 | JDBC Driver Class名稱。 |
lower_case_table_names | 否 | "false" | 是否以小寫的形式同步JDBC外部數(shù)據(jù)源的庫名和表名。 |
only_specified_database | 否 | "false" | 指定是否只同步指定的Database。 |
include_database_list | 否 | "" | 當(dāng) |
exclude_database_list | 否 | "" | 當(dāng) |
驅(qū)動包路徑
創(chuàng)建JDBC Catalog需要指定對應(yīng)數(shù)據(jù)庫的驅(qū)動包路徑。對應(yīng)參數(shù)driver_url
可以通過以下方式指定:
文件名。例如
mysql-connector-java-8.0.25.jar
,SelectDB會自動在本地jdbc_drivers/
目錄下查找相應(yīng)jar包,其中默認(rèn)包含了mysql-connector-java-8.0.25.jar
、postgresql-42.5.1.jar
、mssql-jdbc-11.2.3.jre8.jar
、ojdbc8.jar
這4個常用的Driver包,您可按需使用。HTTP地址。例如
https://doris-community-test-1308700295.cos.ap-hongkong.myqcloud.com/jdbc_driver/mysql-connector-java-8.0.25.jar
,系統(tǒng)會從這個HTTP地址下載Driver文件,僅支持無認(rèn)證的HTTP服務(wù)。
小寫表名同步
當(dāng)lower_case_table_names
設(shè)置為true
時,SelectDB通過維護(hù)小寫名稱到遠(yuǎn)程系統(tǒng)中實(shí)際名稱的映射,能夠查詢非小寫的數(shù)據(jù)庫和表。
SelectDB 2.X版本僅對Oracle數(shù)據(jù)庫有效。在查詢時,會將所有的庫名和表名轉(zhuǎn)換為大寫,再查詢 Oracle。例如
Oracle在TEST空間下有TEST表,SelectDB在創(chuàng)建Catalog時設(shè)置
lower_case_table_names=true
,則SelectDB可以通過SELECT * FROM oracle_catalog.test.test
查詢到TEST表,SelectDB會自動將test.test
格式化成TEST.TEST
下發(fā)到Oracle。需要注意這是個默認(rèn)行為,這意味著此時不能查詢Oracle中小寫的表名。對于其他數(shù)據(jù)庫,仍需要在查詢時指定實(shí)際的庫名和表名。
SelectDB 3.X及之后的版本,對所有的數(shù)據(jù)庫都有效,在查詢時,會將所有的庫名和表名轉(zhuǎn)換為真實(shí)的名稱再去查詢。如果是從老版本升級到3.X,需要
Refresh <catalog_name>
才能生效。但是,如果數(shù)據(jù)庫或者表名只有大小寫不同,例如
SelectDB
和selectdb
,則SelectDB由于歧義而無法查詢它們。當(dāng)FE參數(shù)的
lower_case_table_names
設(shè)置為1或2時,JDBC Catalog的lower_case_table_names
參數(shù)必須設(shè)置為true。如果FE參數(shù)的lower_case_table_names
設(shè)置為0,則 JDBC Catalog的參數(shù)可以為true或false,默認(rèn)為false。這確保了SelectDB在處理內(nèi)部和外部表配置時的一致性和可預(yù)測性。
指定同步數(shù)據(jù)庫
以下參數(shù)和指定同步數(shù)據(jù)庫有關(guān):
only_specified_database
:在通過JDBC連接時可以指定連接到哪個Database或Schema。如:MySQL的jdbc_url
中可以指定Database,PostgreSQL的jdbc_url
中可以指定currentSchema。include_database_list
:僅在only_specified_database=true
時生效,指定需要同步的Database,以英文逗號(,)分隔,Database名稱是大小寫敏感的。exclude_database_list
:僅在only_specified_database=true
時生效,指定不需要同步的多個Database,以英文逗號(,)分隔,Database名稱是大小寫敏感的。
當(dāng)
include_database_list
和exclude_database_list
有重合的Database配置時,會優(yōu)先考慮exclude_database_list
。如果使用該參數(shù)連接Oracle數(shù)據(jù)庫,則必須使用
ojdbc8.jar
以上版本的jar包。
創(chuàng)建示例
MySQL
創(chuàng)建示例
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",
"checksum" = "fdf55dcef04b09f2eaf42b75e61ccc9a"
)
若出現(xiàn)compute driver checksum相關(guān)錯誤,可臨時增加如下property屏蔽checksum檢測機(jī)制:
"checksum" = "fdf55dcef04b09f2eaf42b75e61ccc9a"
。
層級映射
SelectDB | MySQL |
Catalog | MySQL Server |
Database | Database |
Table | Table |
類型映射
MYSQL Type | SelectDB Type | 備注 |
BOOLEAN | TINYINT | 無 |
TINYINT | TINYINT | 無 |
SMALLINT | SMALLINT | 無 |
MEDIUMINT | INT | 無 |
INT | INT | 無 |
BIGINT | BIGINT | 無 |
UNSIGNED TINYINT | SMALLINT | SelectDB沒有UNSIGNED數(shù)據(jù)類型,所以擴(kuò)大一個數(shù)量級。 |
UNSIGNED MEDIUMINT | INT | SelectDB沒有UNSIGNED數(shù)據(jù)類型,所以擴(kuò)大一個數(shù)量級。 |
UNSIGNED INT | BIGINT | SelectDB沒有UNSIGNED數(shù)據(jù)類型,所以擴(kuò)大一個數(shù)量級。 |
UNSIGNED BIGINT | LARGEINT | 無 |
FLOAT | FLOAT | 無 |
DOUBLE | DOUBLE | 無 |
DECIMAL | DECIMAL | 無 |
UNSIGNED DECIMAL(p,s) | DECIMAL(p+1,s) / STRING | 如果 |
DATE | DATE | 無 |
TIMESTAMP | DATETIME | 無 |
DATETIME | DATETIME | 無 |
YEAR | SMALLINT | 無 |
TIME | STRING | 無 |
CHAR | CHAR | 無 |
VARCHAR | VARCHAR | 無 |
JSON | JSON | 無 |
SET | STRING | 無 |
BIT | BOOLEAN/STRING | BIT(1)會映射為BOOLEAN,其他BIT映射為STRING。 |
TINYTEXT、TEXT、MEDIUMTEXT、LONGTEXT | STRING | 無 |
BLOB、MEDIUMBLOB、LONGBLOB、TINYBLOB | STRING | 無 |
TINYSTRING、STRING、MEDIUMSTRING、LONGSTRING | STRING | 無 |
BINARY、VARBINARY | STRING | 無 |
Other | UNSUPPORTED | 無 |
PostgreSQL
創(chuàng)建示例
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",
"checksum" = "20c8228267b6c9ce620fddb39467d3eb"
);
層級映射
映射PostgreSQL時,SelectDB的一個Database對應(yīng)PostgreSQL中指定Catalog下的一個Schema,例如上方示例中jdbc_url
參數(shù)中demo
中的schemas。而SelectDB的Database下的Table則對應(yīng)于PostgreSQL中Schema下的Tables。即映射關(guān)系如下:
SelectDB | PostgreSQL |
Catalog | Database |
Database | Schema |
Table | Table |
SelectDB通過SQL語句SELECT nspname FROM pg_namespace WHERE has_schema_privilege('<UserName>', nspname, 'USAGE');
來獲得PG user能夠訪問的所有Schema并將其映射為SelectDB的Database。
類型映射
POSTGRESQL Type | SelectDB Type | 備注 |
boolean | BOOLEAN | 無 |
smallint/int2 | SMALLINT | 無 |
integer/int4 | INT | 無 |
bigint/int8 | BIGINT | 無 |
decimal/numeric | DECIMAL | 無 |
real/float4 | FLOAT | 無 |
double precision | DOUBLE | 無 |
smallserial | SMALLINT | 無 |
serial | INT | 無 |
bigserial | BIGINT | 無 |
char | CHAR | 無 |
varchar/text | STRING | 無 |
timestamp | DATETIME | 無 |
date | DATE | 無 |
json/jsonb | JSON | 無 |
time | STRING | 無 |
interval | STRING | 無 |
point/line/lseg/box/path/polygon/circle | STRING | 無 |
cidr/inet/macaddr | STRING | 無 |
bit | BOOLEAN/STRING | bit(1)會映射為BOOLEAN,其他bit映射為STRING。 |
uuid | STRING | 無 |
Other | UNSUPPORTED | 無 |
Oracle
創(chuàng)建示例
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",
"checksum" = "621a393d7be9ff0f2fec6fbba2c8f9b6"
);
層級映射
映射Oracle時,SelectDB的一個Database對應(yīng)Oracle中的一個User。而SelectDB的Database中的Table則對應(yīng)于Oracle中該User有權(quán)限訪問的Table。即映射關(guān)系如下:
SelectDB | Oracle |
Catalog | Database |
Database | User |
Table | Table |
當(dāng)前不支持同步Oracle的SYNONYM TABLE。
類型映射
ORACLE Type | SelectDB Type | 備注 |
number(p) / number(p,0) | TINYINT/SMALLINT/INT/BIGINT/LARGEINT | SelectDB會根據(jù)p的大小來選擇對應(yīng)的類型:
|
number(p,s),[ if(s>0 && p>s) ] | DECIMAL(p,s) | 無 |
number(p,s),[ if(s>0 && p < s) ] | DECIMAL(s,s) | 無 |
number(p,s),[ if(s<0) ] | TINYINT/SMALLINT/INT/BIGINT/LARGEINT |
|
number | 無 | SelectDB目前不支持未指定p和s的Oracle類型。 |
decimal | DECIMAL | 無 |
float/real | DOUBLE | 無 |
DATE | DATETIME | 無 |
TIMESTAMP | DATETIME | 無 |
CHAR/NCHAR | STRING | 無 |
VARCHAR2/NVARCHAR2 | STRING | 無 |
LONG/ RAW/ LONG RAW/ INTERVAL | STRING | 無 |
Other | UNSUPPORTED | 無 |
SQLServer
創(chuàng)建示例
若您使用的SelectDB版本高于或等于3.0.8,為了確保您能正常訪問SQLServer的數(shù)據(jù),務(wù)必在jdbc_url連接串中包含encrypt=false
參數(shù)。
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",
"checksum" = "b204274eb02a848ac405961e6f43e7bd"
);
層級映射
映射SQLServer時,SelectDB的Database對應(yīng)SQLServer中指定Database,例如上方示例中jdbc_url
參數(shù)中的SelectDB_test下的一個Schema。而SelectDB中Database下的Table則對應(yīng)SQLServer中Schema下的Tables。即映射關(guān)系如下:
SelectDB | SQLServer |
Catalog | Database |
Database | Schema |
Table | Table |
類型映射
SQLServer Type | SelectDB Type |
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 |
Other | UNSUPPORTED |
Doris
SelectDB JDBC Catalog也支持連接Doris數(shù)據(jù)庫。
創(chuàng)建示例
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",
"checksum" = "fdf55dcef04b09f2eaf42b75e61ccc9a"
)
類型映射
Doris Type | JDBC Catalog SelectDB Type | 備注 |
BOOLEAN | BOOLEAN | 無 |
TINYINT | TINYINT | 無 |
SMALLINT | SMALLINT | 無 |
INT | INT | 無 |
BIGINT | BIGINT | 無 |
LARGEINT | LARGEINT | 無 |
FLOAT | FLOAT | 無 |
DOUBLE | DOUBLE | 無 |
DECIMALV3 | DECIMALV3/STRING | 將根據(jù)DECIMAL字段的(precision, scale)選擇用何種類型。 |
DATE | DATE | 無 |
DATETIME | DATETIME | 無 |
CHAR | CHAR | 無 |
VARCHAR | VARCHAR | 無 |
STRING | STRING | 無 |
TEXT | STRING | 無 |
HLL | HLL | 查詢HLL需要設(shè)置 |
Array | Array | Array內(nèi)部類型適配邏輯參考上述類型,不支持嵌套復(fù)雜類型。 |
BITMAP | BITMAP | 查詢BITMAP需要設(shè)置 |
Other | UNSUPPORTED | 無 |
ClickHouse
創(chuàng)建示例
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",
"checksum" = "9be22a93267dc4b066e0a3aefc2dd024"
);
層級映射
SelectDB | ClickHouse |
Catalog | ClickHouse Server |
Database | Database |
Table | Table |
類型映射
ClickHouse Type | SelectDB Type |
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 |
Other | UNSUPPORTED |
SPA HANA
創(chuàng)建示例
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"
)
層級映射
SelectDB | SAP HANA |
Catalog | Database |
Database | Schema |
Table | Table |
類型映射
SAP HANA Type | SelectDB Type |
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 |
Trino或Presto
創(chuàng)建示例
Trino
CREATE CATALOG jdbc_trino PROPERTIES ( "type"="jdbc", "user"="hadoop", "password"="", "jdbc_url" = "jdbc:trino://localhost:9000/hive", "driver_url" = "trino-jdbc-389.jar", "driver_class" = "io.trino.jdbc.TrinoDriver" );
Presto
CREATE CATALOG jdbc_presto PROPERTIES ( "type"="jdbc", "user"="hadoop", "password"="", "jdbc_url" = "jdbc:presto://localhost:9000/hive", "driver_url" = "presto-jdbc-0.280.jar", "driver_class" = "com.facebook.presto.jdbc.PrestoDriver" );
層級映射
映射Trino或Presto時,SelectDB的Database對應(yīng)Trino或Presto中指定Catalog下的一個Schema。而SelectDB中Database下的Table則對應(yīng)Trino或Presto中Schema下的Tables。即映射關(guān)系如下:
SelectDB | Trino/Presto |
Catalog | Catalog |
Database | Schema |
Table | Table |
類型映射
Trino/Presto Type | SelectDB Type |
boolean | BOOLEAN |
tinyint | TINYINT |
smallint | SMALLINT |
integer | INT |
bigint | BIGINT |
decimal | DECIMAL/DECIMALV3/STRING |
real | FLOAT |
double | DOUBLE |
date | DATE |
timestamp | DATETIME |
varchar | TEXT |
char | CHAR |
array | ARRAY |
others | UNSUPPORTED |
OceanBase
創(chuàng)建示例
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"
)
SelectDB在連接OceanBase時,會自動識別OceanBase處于MySQL或者Oracle模式,層級對應(yīng)和類型映射參見上方的MySQL與Oracle章節(jié)。
數(shù)據(jù)查詢
示例
SELECT * FROM mysql_catalog.mysql_database.mysql_table WHERE k1 > 1000 AND k3 ='term';
由于可能存在使用數(shù)據(jù)庫內(nèi)部的關(guān)鍵字作為字段名,為使得這種狀況下SelectDB仍能正確查詢,在SQL語句中,SelectDB會根據(jù)各個數(shù)據(jù)庫的標(biāo)準(zhǔn)自動在字段名與表名上加上轉(zhuǎn)義符。例如 MYSQL(``)、PostgreSQL("")、SQLServer([])、ORACLE("")等,此時可能會造成字段名的大小寫敏感,您可以通過EXPLAIN SQL命令,查看轉(zhuǎn)義后下發(fā)到各個數(shù)據(jù)庫的查詢語句。
謂詞下推
當(dāng)執(zhí)行類似于WHERE dt = '2022-01-01'
的查詢時,SelectDB能夠?qū)⑦@些過濾條件下推到外部數(shù)據(jù)源,從而直接在數(shù)據(jù)源層面過濾不符合條件的數(shù)據(jù),減少了不必要的數(shù)據(jù)獲取和傳輸。這將大大提高了查詢性能,同時也降低了對外部數(shù)據(jù)源的負(fù)載。
當(dāng)會話變量enable_func_pushdown
設(shè)置為true時,SelectDB會將WHERE
之后的函數(shù)條件也下推到外部數(shù)據(jù)源。該功能目前僅支持MySQL,如遇到MySQL不支持的函數(shù),可以將此參數(shù)設(shè)置為false,目前SelectDB會自動識別部分MySQL不支持的函數(shù)進(jìn)行下推條件過濾,您可以通過EXPLAIN SQL命令查看具體的查詢語句。
目前不支持下推的函數(shù)為:DATE_TRUNC
和MONEY_FORMAT
。
行數(shù)限制
如果在查詢中帶有LIMIT關(guān)鍵字,SelectDB會將其轉(zhuǎn)譯成適合不同數(shù)據(jù)源的語義。
數(shù)據(jù)寫入
在SelectDB中建立JDBC Catalog后,可以通過INSERT INTO
語句直接寫入數(shù)據(jù),也可以將SelectDB執(zhí)行完查詢之后的結(jié)果寫入JDBC Catalog,或者是從一個JDBC Catalog將數(shù)據(jù)導(dǎo)入另一個JDBC Catalog中。
示例
INSERT INTO mysql_catalog.mysql_database.mysql_table VALUES(1, "doris");
INSERT INTO mysql_catalog.mysql_database.mysql_table SELECT * FROM table;
事務(wù)
SelectDB的數(shù)據(jù)是由一組Batch的方式寫入JDBC Catalog。如果中途導(dǎo)入中斷,之前寫入的數(shù)據(jù)可能需要回滾。所以JDBC Catalog支持?jǐn)?shù)據(jù)寫入時的事務(wù),事務(wù)的支持需要通過設(shè)置會話變量enable_odbc_transcation
。
SET enable_odbc_transcation = TRUE;
事務(wù)保證了JDBC外表數(shù)據(jù)寫入的原子性,但一定程度上會降低數(shù)據(jù)寫入的性能,可按需開啟該功能。