通过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]
访问数据源表的JDBC URL格式：jdbc:dataphin://host:port/ds_code?tenant_id=TenantID[?ssl=true][currentschema=schema] [&prepareThreshold=0][&user=UserName][&password=PassWord][&delegationuid=UserID][&acounttype=AccountType][&paramName=paramValue][&connect_timeout=connectTimeout][&engine=engine_type]

重要

参数名称区分大小写。
方括号仅为示意，执行命令时需要删除此符号。

参数	是否必填	说明	示例值
host	是	Dataphin OpenAPI的域名。可以在个人中心 > AccessKey管理中的OpenAPI调用地址获取Dataphin的域名。如下图所示：	dataphin-openapi.****.aliyun.com
port	否	端口根据Dataphin OpenAPI是否开启HTTPS决定，如果开启HTTPS端口为`443`，未开启为`80`。默认为80。	80
project_name	否	Dataphin的项目名。 Dataphin将使用该项目的计算资源用于SQL的执行。仅支持Dev、Prod、Basic项目，且用户需为项目的以下成员角色或具有调用JDBC Driver权限的自定义角色： Dev/Basic：开发者、项目管理员、分析师。 Prod：分析师、运维。自定义项目角色。具体操作，请参见新建自定义项目角色。说明仅访问项目内的表时，需配置该参数。 project_name和ds_code必须选择其中一个填写。若已填写本参数，则无需填写ds_code。	Exprojectname
ds_code	否	数据源编码。说明仅访问数据源表时，需配置该参数。 project_name和ds_code必须选择其中一个填写。若已填写本参数，则无需填写project_name。	ds_excode
tenant_id	是	查询的租户ID。	111***111
ssl	否	是否使用HTTPS。 True：使用HTTPS域名。 False：使用HTTP域名。默认为False。	False
currentschema	是	数据源的schema。支持切换schema。若数据源为MySQL等同于无schema的数据源时，仅包含default schema，currentschema传入schema时，则忽略该参数。若数据源为Oracle，可指定schema。	information_schema
user	是	用户的AccessKey ID或者平台的AccessKey ID。使用代理模式时，请使用平台的AccessKey ID。平台AccessKey ID可联系Dataphin运维团队获取。用户的AccessKey ID可在个人中心 > AccessKey管理中获取。	kIB**********PT0
log_level	否	日志记录级别。取值为： DEBUG INFO WARNING ERROR	DEBUG
password	是	访问用户的AccessKey Secret。平台AccessKey可联系Dataphin运维团队获取用户的AccessKey ID可进入个人中心 > AccessKey管理中获取。	Cy**************r2T
delegation_uid	否	被代理访问的Dataphin用户。设置该参数后，使用代理模式的认证方式。当使用平台AccessKey时，可代理其他的个人用户建立连接，访问Dataphin。该参数为被代理的Dataphin用户。	999***999
account_type	否	当使用代理模式认证时，需要指定代理用户的账号类型。 account_name：Dataphin的用户名。 USER_ID：Dataphin内部的唯一ID。默认为USER_ID。说明仅当设置了delegation_uid时，需要配置此参数。若存在相同的用户，则认证不通过。	USER_ID
connect_timeout	否	获取连接时最长的超时时间，单位为秒。大于0：超时时间，最小值为10s。小于等于0：一直等待。	10
engine	否	session中或连接串中指定项目的project_name的离线引擎。若为Hadoop计算源，则默认为hive，但可通过该参数设置为Impala或Spark引擎。设置引擎类型需要在计算源提前进行配置。若指定的引擎为该项目不支持的类型，则忽略该设置，但会给出告警。取值为： MaxCompute Hologres Hive Impala Inceptor ArgoDB Spark 说明访问数据源时忽略该参数。	MaxCompute

认证模式

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

简单模式

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

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

代理模式

重要

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

代理模式通常用于系统与Dataphin之间的集成。这种方式避免了需要对不同的用户分发或配置AccessKey，在JDBC连接串（JDBC URL）中指定代理的用户即可保证对操作按照指定的用户进行鉴权。平台级别的AccessKey具有很高的权限，可代理所有的用户。如下图所示，客户端配置了平台AccessKey，用户userA通过客户端访问时，需要指定delegation_uid=userA指定此次访问为代理userA的访问，需要用userA的功能权限及数据权限进行权限校验。

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：默认为default。
- 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...,MAC:00----*-25`。

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