# 添加Oracle数据源 #### 操作场景 HetuEngine支持配置Oracle数据源实现对Oracle数据源的接入与查询功能。本章节指导用户在集群的HSConsole界面添加Oracle类型的JDBC数据源。 #### 前提条件 - 数据源与HetuEngine集群节点网络互通。 - 集群已启用Kerberos认证（安全模式）创建HetuEngine管理员用户，集群未启用Kerberos认证（普通模式）创建HetuEngine业务用户，并为其赋予HDFS管理员权限，即创建用户时需同时加入"hadoop"和"hadoopmanager"用户组，创建用户可参考[创建HetuEngine权限角色](https://support.huaweicloud.com/cmpntguide-lts-mrs/mrs_01_1714.html)。 - 已创建HetuEngine计算实例，可参考[创建HetuEngine计算实例](https://support.huaweicloud.com/cmpntguide-lts-mrs/mrs_01_1731.html)。 - 已获取Oracle数据库所在的IP地址，端口号，数据库实例名称或是数据库pdb名称，用户名及密码。 #### 约束与限制 本章节适用于MRS 3.5.0及之后的版本。 #### HetuEngine对接Oracle数据源约束 - 目前Oracle数据源默认为只读模式，支持Oracle12及以后版本。 - HetuEngine支持的Oracle数据源的Schema和Table名称不区分大小写。 - 不支持如下语法：CREATE SCHEMA、ALTER SCHEMA、DROP SCHEMA、INSERT INTO ... SELECT、INSERT OVERWRITE、UPDATE、ANALYZE、VIEW相关。 - 当使用CLOB、NCLOB、BLOB或RAW(n)这些Oracle数据库类型的列，或者使用映射到这些Oracle数据库类型的Trino数据类型的列，不支持下推。 例如：由于name在HetuEngine中是VARCHAR类型的列，映射到Oracle中是NCLOB，因此如下两个查询的谓词均不会下推。 ``` SELECT * FROM nation WHERE name>'abcd'; SELECT * FROM nation WHERE name='abcd'; ``` - 如果指定了WHERE子句，则仅当WHERE中的谓词能够完全下推至Oracle的情况下才能执行DELETE。 #### 配置Oracle数据源步骤 **安装集群客户端** 1. 安装包含HetuEngine服务的集群客户端，例如安装目录为"/opt/client"。 下载并安装集群客户端的具体操作，请参考[安装MRS集群客户端](https://support.huaweicloud.com/usermanual-mrs/mrs_01_0089.html)。 **准备Oracle驱动** 2. 从Oracle官网获取Oracle驱动文件，格式为"ojdbc*xxx* .jar"，例如"ojdbc8.jar"。 此处上传的驱动文件名有校验规则：Oracle数据源的驱动文件校验前缀"ojdbc"以及结尾的"jar"，中间的版本号不做校验，可以是任意字符，但是整体长度不能超过80个字符，且文件大小不超过100MB。 3. 上传Oracle驱动文件至HetuEngine所在集群。 可通过如下两种方式： - 通过Manager界面上传至HDFS： 1. 使用HetuEngine管理员用户登录Manager界面，选择"集群 \> 服务 \> HDFS"，进入HDFS服务页面。 2. 在"概览"页签下的"基本信息"区域，单击"NameNode Web UI"后的链接，进入NameNode Web UI界面。 3. 选择"Utilities \> Browse the file system"，单击![](https://support.huaweicloud.com/cmpntguide-lts-mrs/zh-cn_image_0000002060714388.png)，创建"/user/hetuserver/fiber/extra_file/driver/oracle"目录。 4. 进入"/user/hetuserver/fiber/extra_file/driver/oracle"目录，单击![](https://support.huaweicloud.com/cmpntguide-lts-mrs/zh-cn_image_0000002096912949.png)上传[2]获取的Oracle驱动文件。 5. 单击驱动文件所在行的"Permission"列的值，勾选"User"列的"Read"和"Write"，"Group"列的"Read"和"Other"列的"Read"，单击"Set"。 - 通过使用HDFS命令直接上传： 1. 登录HDFS服务客户端所在节点，切换到客户端安装目录，如"/opt/client"。 ``` cd /opt/hadoopclient ``` 2. 执行以下命令配置环境变量。 ``` source bigdata_env ``` 3. 如果集群已启用Kerberos认证（安全模式），执行以下命令进行用户认证。集群未启用Kerberos认证（普通模式）无需执行用户认证。 ``` kinit HetuEngine管理员用户 ``` 根据回显提示输入密码。 4. 执行如下命令创建目录"/user/hetuserver/fiber/extra_file/driver/oracle"，并上传[2]获取的Oracle驱动，然后修改对应的权限。 ``` hdfs dfs -mkdir -p /user/hetuserver/fiber/extra_file/driver/oracle hdfs dfs -put ./Oracle驱动文件 /user/hetuserver/fiber/extra_file/driver/oracle hdfs dfs -chmod -R 644 /user/hetuserver/fiber/extra_file/driver/oracle ``` **配置Oracle数据源** 4. 使用HetuEngine管理员用户登录Manager界面，选择"集群 \> 服务 \> HetuEngine"，进入HetuEngine服务页面。 5. 在"概览"页签下的"基本信息"区域，单击"HSConsole Web UI"后的链接，进入HSConsole界面。 6. 选择"数据源"，单击"添加数据源"。在"添加数据源"页面填写参数。 1. 配置"基本配置"，填写数据源名称，"数据源类型"选择"JDBC \> Oracle"。 2. 配置"Oracle配置"，参数配置请参考[表1 Oracle配置]。 表1Oracle配置 | 参数 | 描述 | 取值样例 | |:---|:---|:---| | 驱动名称 | 选择[2]中已提前上传的待使用的Oracle驱动，格式为*ojdbcxxx*.jar。 | ojdbc8.jar | | JDBC URL | 连接Oracle的JDBC URL地址。端口号默认为1521。 可选择如下格式： - jdbc:oracle:thin*@Oracle数据库所在的IP地址* :*端口号* /*Oracle*数据库pdb名称 - jdbc:oracle:thin*@Oracle数据库所在的IP地址* :*端口号* :*Oracle* *数据库实例名称*。 | - jdbc:oracle:thin:@192.168.1.1:1521/orclpdb - jdbc:oracle:thin:@192.168.1.1:1521:orcl | | 用户名 | 连接Oracle数据源的Oracle用户名。 | - | | 密码 | 连接Oracle数据源的Oracle用户密码。 | - | 3. （可选）自定义配置。 单击"增加"可以增加自定义配置参数。配置Oracle数据源自定义参数，参考[表2 Oracle数据源自定义配置参数]。 表2Oracle数据源自定义配置参数 | 参数 | 描述 | 取值样例 | |:---|:---|:---| | case-insensitive-name-matching | HetuEngine支持的Oracle数据源的Schema和Table名称大小写格式敏感。 - false（默认值）：仅支持查询全小写的Schema和Table。 - true： - 忽略大小写后无同名的Schema和Table：支持查询该Schema和Table。 - 忽略大小写后存在同名的Schema和Table：不支持查询该Schema和Table。 | false | | case-insensitive-name-matching.cache-ttl | Oracle数据源的大小写敏感的Schema和Table名称缓存超时时长，默认值：1m（1分钟）。 | 1m | | dynamic-filtering.enabled | 是否将动态过滤器下推到JDBC查询中。 - true（默认值）：开启下推。 - false：关闭下推。 | true | | dynamic-filtering.wait-timeout | 在启动JDBC查询之前，HetuEngine将等待从连接的构建端收集动态过滤器的最大持续时间。使用较大的超时可能会导致更详细的动态过滤器。但是也会增加某些查询的延迟，默认值：20s。 | 20s | | unsupported-type-handling | 当连接器不支持此数据类型时，是否将其转换为VARCHAR，从而避免失败。 - CONVERT_TO_VARCHAR：将不支持的类型转为VARCHAR类型，并且只支持对它们的读操作。除了数据类型映射表格中有的类型，其余类型均不支持。 - IGNORE（默认值）：不支持的类型将不在查询结果中显示。 | IGNORE | | join-pushdown.enabled | 是否启用Join下推，启用连接下推可能会对某些查询语句产生负面影响。 - true：开启Join下推。 - false（默认值）：关闭Join下推。 | false | | join-pushdown.strategy | 用于评估Join操作是否被下推的策略。 - AUTOMATIC（默认值）：启用基于成本的连接下推。 - EAGER：尽可能下推Join。即使表统计信息不可用，EAGER也可以下推Join，这可能会导致查询性能下降，因此仅建议将EAGER用于测试和故障排除场景。 | AUTOMATIC | | oracle.number.default-scale | Oracle Number（不带精度和小数位数）数据类型映射的HetuEngine Decimal类型的小数位数。默认未设置，如果不设置会视为该列不受支持。 | 5 | | oracle.remarks-reporting.enabled | 是否公开元数据注释： - true：公开元数据注释。 - false（默认值）：不通过REMARKS列公开元数据注释。 | false | | oracle.synonyms.enabled | 是否启用同义词功能，HetuEngine基于性能原因默认禁用了对Oracle SYNONYM的支持： - true：开启同义词功能。 - false（默认值）：禁用同义词功能。 | false | | oracle.source-encoding | 配置远端数据来源环境的字符集编码，防止数据出现乱码： - ZHS16GBK或GBK - AL32UTF8或UTF-8（默认值） | UTF-8 | 单击"删除"可以删除已增加的自定义配置参数。 4. 单击"确定"。 7. 登录集群客户端所在节点，执行以下命令，切换到客户端安装目录，例如安装目录为"/opt/client"，具体以实际替换。 ``` cd /opt/client ``` 执行以下命令配置环境变量。 ``` source bigdata_env ``` 执行以下命令，进行用户认证。（集群未启用Kerberos认证（普通模式）时跳过此步骤） ``` kinit HetuEngine组件操作用户 ``` 8. 执行以下命令，登录数据源的catalog。 ``` hetu-cli --catalog 数据源名称 --schema 数据库名 ``` 例如执行以下命令： ``` hetu-cli --catalog oracle_1 --schema oracle ``` 9. 执行以下命令，可正常查看数据库表信息或不报错即表示连接成功。 ``` show tables; ``` #### Oracle与HetuEngine数据类型映射 数据映射约束： - HetuEngine不支持直接读取Oracle侧没有设置精度和规模的Number类型数据，需要在数据源配置中添加自定义参数"oracle.number.default-scale=s"来将其映射至decimal(38, s)类型。 - HetuEngine不支持读取Number(p, s)数据类型中"p-s\>38"的列。 - Oracle侧的Date类型只存储到秒，所以映射到HetuEngine的数据类型为timestamp(0)。 - HetuEngine查询的时间戳类型数据，如果秒的小数精度大于3，会直接截断为3位小数，而不是四舍五入。 - 由于JDBC驱动程序中对于时间和日期支持的格式不同，插入或查询早于"1582-10-15"的日期时间时可能会出错。 - HetuEngine中VARCHAR(n)会被映射到Oracle中的VARCHAR2(n CHAR)， 如果n大于4000，则会被映射到NCLOB中；CHAR(n)会被映射到CHAR(n CHAR)，如果n大于2000，也会被映射到NCLOB中。 - HetuEngine不能将CHAR和VARCHAR数据类型写入到长度不合适的列中。 - 使用CREATE TABLE AS从一个CHAR值创建NCLOB列会将初始值中的后缀空格去掉；但是如果将一个CHAR值插入到已存在的NCLOB列中，则会保留后缀的空格。 表3Oracle数据类型到HetuEngine数据类型映射 | Oracle类型 | HetuEngine类型 | |:---|:---| | NUMBER(p, s) | DECIMAL(p, s) | | NUMBER(p) | DECIMAL(p, 0) | | FLOAT\[(p)\] | DOUBLE | | BINARY_FLOAT | REAL | | BINARY_DOUBLE | DOUBLE | | VARCHAR2(n CHAR) | VARCHAR(n) | | VARCHAR2(n BYTE) | VARCHAR(n) | | NVARCHAR2(n) | VARCHAR(n) | | CHAR(n) | CHAR(n) | | NCHAR(n) | CHAR(n) | | CLOB | VARCHAR | | NCLOB | VARCHAR | | RAW(n) | VARBINARY | | BLOB | VARBINARY | | DATE | TIMESTAMP(0) | | TIMESTAMP(p) | TIMESTAMP(3) | | TIMESTAMP(p) WITH TIME ZONE | TIMESTAMP(3) WITH TIME ZONE | 表4HetuEngine数据类型到Oracle数据类型映射 | HetuEngine类型 | Oracle类型 | |:---|:---| | TINYINT | NUMBER(3) | | SMALLINT | NUMBER(5) | | INTEGER | NUMBER(10) | | BIGINT | NUMBER(19) | | DECIMAL(p, s) | NUMBER(p, s) | | REAL | BINARY_FLOAT | | DOUBLE | BINARY_DOUBLE | | VARCHAR | NCLOB | | VARCHAR(n) | VARCHAR2(n CHAR) or NCLOB | | CHAR(n) | CHAR(n CHAR) or NCLOB | | VARBINARY | BLOB | | DATE | DATE | | TIMESTAMP | TIMESTAMP(3) | | TIMESTAMP WITH TIME ZONE | TIMESTAMP(3) WITH TIME ZONE | #### 功能增强 连接器中提供query功能支持直接查询底层数据库，仅支持Oracle原生的语法，因为完整的语句会被下推并且在Oracle中执行。可以用于访问HetuEngine中不可用的Oracle功能，或是当某些语句在Oracle侧执行的更快时使用。 ``` SELECT * FROM TABLE( oracle.system.query( query => 'SELECT * FROM tpch.nation')); ```