通过JDBC连接Dataphin_智能数据建设与治理 Dataphin(Dataphin)-阿里云帮助中心

本文为您介绍如何使用JDBC Driver连接Dataphin。

前提条件

Dataphin JDBC使用Dataphin的OpenAPI实现SQL查询能力，在使用Dataphin JDBC前需要开通Dataphin OpenAPI功能。

功能概述

双认证模式：Dataphin JDBC支持使用Dataphin AccessKey认证，也可以使用阿里云平台AccessKey并设置代理用户的方式进行认证和鉴权。更多信息，请参见认证模式。
执行结果统一：因使用Dataphin JDBC执行SQL等同于在Dataphin中执行SQL，所以其SQL执行结果与在Dataphin中的界面执行结果一致。同时Dataphin中相关的功能配置，同样也会影响到Dataphin JDBC的执行结果。例如，权限、脱敏规则、安全设置、代码规范等。

使用限制

Dataphin JDBC的SQL执行会通过Dataphin进行SQL翻译、脱敏等预处理，且结果数据通过Dataphin进行传输和转发，都会造成性能的损耗，因此相对于直接对计算引擎进行查询的耗时更长。
Dataphin JDBC执行SQL会通过Dataphin OpenAPI提交到Dataphin进行处理，并最终提交到底层计算引擎取执行。因此在使用Dataphin JDBC前请合理评估调用量，并及时评估是否需要对Dataphin集群和计算引擎进行扩容。
说明
若无法合理评估确认，您可以向Dataphin运维团队提交Dataphin集群的容量评估申请（不包含计算引擎的容量评估）。
Dataphin暂不支持流量控制、并发控制，请谨慎评估影响。

JDBC 驱动

驱动的JAR包您可以联系Dataphin运维人员获取。

连接参数

JDBC URL的格式：jdbc:dataphin://host:port/project_name?[tenant_id=TenantID][&ssl=true][&log_level=Log_Level][&user=UserName][&password=PassWord][&delegation_uid=DelegationUid][&account_type=AccountType][&connect_timeout=ConnectTimeout][&engine=engine_type]

重要

参数名大小写敏感。

参数	取值	说明
host	Dataphin的访问URL。	Dataphin的域名。
port	默认为80。	同Dataphin OpenAPI的服务端口。
project_name	Dataphin的项目名。	Dataphin将使用该项目的计算资源用于SQL的执行。仅支持Dev、Prod、Basic项目，且用户需为项目的以下成员角色： Dev/Basic：开发者、项目管理员、分析师。 Prod：分析师、运维。
tenant_id	租户ID。	必填项。需要指定查询的租户ID。
ssl	是否使用HTTPS	为True时使用HTTPS域名，为False时使用HTTP域名。默认False。
user	访问用户的AccessKey ID。	Dataphin平台的AccessKey ID，或Dataphin个人用户的AccessKey ID。平台AccessKey可联系Dataphin运维团队获取，您的AccessKey ID可进入个人中心-AccessKey管理获取。
log_level	日志记录级别	可选值为：DEBUG、INFO、WARNING、ERROR。
password	访问用户的AccessKey Secret。	AccessKey ID对应的AccessKey Secret。平台AccessKey可联系Dataphin运维团队获取，您的AccessKey ID可进入个人中心-AccessKey管理获取。
delegation_uid	被代理访问Dataphin的用户。	当使用平台AccessKey，可代理其他的个人用户建立连接，访问Dataphin。该参数为被代理的Dataphin用户。
account_type	可选。Delegation_Uid的账号类型： account_name：Dataphin的用户名。 USER_ID：Dataphin内部的唯一ID。 SOURCE_USER_ID：对接来源系统的用户ID。	可选参数。默认为USER_ID，若存在相同的用户，则认证不通过。
connect_timeout	数值： >0时，为超时时间，最小值为10s。为0或者负数时：则一直等待。	可选设置，获取连接时最长的超时时间，单位为秒。
engine	session中或连接串中指定的项目的project_name的离线引擎，若为Hadoop计算源，则默认为hive。	取值范围：[MaxCompute\|Hologres\|Hive\|Impala\|Inceptor\|ArgoDB]。若给出的值为不支持类型，则忽略该设置，但给出告警。

认证模式

Dataphin支持以下两种认证模式，您可以选择其一进行认证。

简单模式

用户名配置为用户的AccessKey ID，密码设置为用户的AccessKey Secret，当前的访问即被识别为该用户。查看AccessKey，请参见Dataphin OpenAPI AccessKey管理。

通过JDBC Driver访问Dataphin，Dataphin对AccessKey进行认证和对该AccessKey的用户进行访问资源或SQL的鉴权后，Dataphin即识别该用户进行SQL的执行。

代理模式

前提条件：若需使用代理模式，需要提前联系Dataphin运维团队开通和配置该功能。

配置平台的AccessKey，通过JDBC Driver访问Dataphin，Dataphin认证平台AccessKey后，对代理用户访问的资源或SQL进行鉴权，通过后，代理该用户进行SQL任务的执行。

Dataphin Driver详细说明

com.aliyun.dataphin.jdbc.DataphinDriver

接口	功能说明	接口定义
connect	获取数据库连接。	`Connection connect (String url, Properties info) throws SQLException;`
acceptsURL	检查是否支持URL。	`boolean acceptsURL(String url) throws SQLException;`

com.aliyun.dataphin.jdbc.DataphinConnection

接口

说明

接口定义

createStatement

创建Statement对象

Statement createStatement
(int resultSetType, 
int resultSetConcurrency)
throws SQLException;

prepareStatement

创建PrepareStatement对象

PreparedStatement prepareStatement(String sql, int resultSetType,int resultSetConcurrency)throws SQLExcept;
PreparedStatement prepareStatement(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability);

com.aliyun.dataphin.jdbc.DataphinStatement

接口	说明	接口定义
executeQuery	执行SQL，返回ResultSet。	`ResultSet executeQuery (String sql) throws SQLException;`
setFetchSize	根据设置的行数分批获取结果数据。若未设置或设置为0，则默认为1000。	`void setFetchSize(int rows) throws SQLException`
cancel	取消Statement的执行。	`void cancel() throws SQLException;`

com.aliyun.dataphin.jdbc.DataphinPrepareStatement

接口	说明	接口定义
executeQuery	执行SQL，返回ResultSet。	`ResultSet executeQuery (String sql) throws SQLException;`

com.aliyun.dataphin.jdbc.DataphinResultSetMetaData

接口	说明	接口定义
getColumnCount	获取结果Schema的列数目。	`int getColumnCount() throws SQLException;`
getColumnName	获取结果Schema的列名称。	`int getColumnCount() throws SQLException;`

com.aliyun.dataphin.jdbc.ResultSet

接口	说明	接口定义
next	逐条获取SQL执行结果数据。	`boolean next() throws SQLException;`

com.aliyun.dataphin.jdbc.DatabaseMetaData

接口

说明

接口定义

getTables

获取表信息。

参数说明：

catalog：项目名称或者板块名称。
schemaPattern：不支持。
tableNamePattern：表名称，支持模糊匹配，不支持正则表达式。
types：不支持。

返回结果：

返回结果为ResultSet。

可以通过next逐条获取SQL执行结果数据，每条数据为单个表的元数据（仅支持获取表名）。

获取表名：

resultSet.getString("table_name")

getTables(String catalog, String schemaPattern, String tableNamePattern, String[] types) throws SQLException

getColumns

获取表的字段信息。

参数说明：

catalog：项目名称或者板块名称。
schemaPattern：不支持。
tableNamePattern：表名称，表的全名，不支持模糊匹配，不支持正则表达式。
columnNamePattern：不支持。

返回结果：

返回结果为ResultSet。

可以通过next逐条获取SQL执行结果数据，每条数据为表的一个字段的元数据（仅支持列名、数据类型）。

获取列名：

resultSet.getString("column_name");

获取列的数据类型：

resultSet.getString("data_type");

ResultSet getColumns(String catalog, String schemaPattern, String tableNamePattern, String columnNamePattern)

示例

可通过Dataphin JDBC Driver获取Catalog信息。

1. 获取表列表

获取项目下的物理表及物理视图列表。

语法

SHOW TABLES
    [FROM db_name]
    [LIKE 'pattern']

参数说明

参数	说明
db_name	Dataphin项目名：展示该项目下的物理表。开发项目及数据板块需要显式的增加_Dev。 db_name不传入时，默认展示URL中设置的project_name下的表。

返回结果

Name	Type	Comment
dim_user	LOGICAL TABLE	用户表
ods_user	PHYSICAL TABLE	用户来源表
ods_user_logical_view	LOGICAL_VIEW	逻辑视图
ods_user_physical_view2	PHYSICAL_VIEW	物理视图

2. 获取表的结构信息

获取物理表及物理视图的字段详情。

语法

{DESCRIBE | DESC} table_name;

说明

仅支持物理表及物理视图。

参数说明

参数	说明
table_name	物理表及物理视图的名称。

返回结果

Name	Type	Comment
ID	BigInt	用户ID
Name	String	用户名称
DS	String	分区时间

服务器端连接控制

最大连接数：默认为100。
连接超时：默认为288000s（2小时）。服务连接到数据库但对其不做任何操作时，等待一定时间之后，连接自动断开。通过该连接进行操作时，服务会报错或者关闭异常，对应的是Connection URL的Connection_Idle_Timeout。

Dataphin JDBC任务提交到MaxCompute执行实例的信息

提交Dataphin JDBC任务到MaxCompute的执行实例时，系统将一同提交Dataphin的相关信息。详情如下：

参数字段	描述
logical_project	JDBC任务执行所在的Dataphin的项目名称。
EXT_JDBC_TASKRUN_ID	JDBC任务的任务ID。
EXT_DPN_TENANT_ID	JDBC任务执行所在的Dataphin租户的ID。
EXT_PLATFORM_ID	提交到MaxCompute的上层平台ID，默认为"Dataphin"。
biz_id	JDBC任务执行人的Dataphin成员ID。
odps.idata.userenv	用户环境信息。包括JavaSDK版本、Java版本、IP以及设备MAC信息。例如： `JavaSDK Revision:fcedc4d,Version:0.37.6,JavaVersion:1.8.0_152,IP:11.31.152.36,MAC:00-16-3E-14-68-25`。

对于提交的信息，您可以用于分析在MaxCompute的账单及查看作业的耗时情况等场景。具体操作，请参见统计MaxCompute TOPN费用账号及耗时作业。