添加Oracle数据源

前提条件

• 数据源与HetuEngine集群节点网络互通。
• 集群已启用Kerberos认证（安全模式）创建HetuEngine管理员用户，集群未启用Kerberos认证（普通模式）创建HetuEngine业务用户，并为其赋予HDFS管理员权限，即创建用户时需同时加入“hadoop”和“hadoopmanager”用户组，创建用户可参考创建HetuEngine权限角色。
• 已创建HetuEngine计算实例，可参考创建HetuEngine计算实例。
• 已获取Oracle数据库所在的IP地址，端口号，数据库实例名称或是数据库pdb名称，用户名及密码。

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/hadoopclient”。

准备Oracle驱动

2. 从Oracle官网获取Oracle驱动文件，格式为“ojdbcxxx.jar”，例如“ojdbc8.jar”。

   此处上传的驱动文件名有校验规则：Oracle数据源的驱动文件校验前缀“ojdbc”以及结尾的“jar”，中间的版本号不做校验，可以是任意字符，但是整体长度不能超过80个字符，且文件大小不超过100MB。

3. 上传Oracle驱动文件至HetuEngine所在集群。
   可通过如下两种方式：

   • 通过Manager界面上传至HDFS：
     1. 使用HetuEngine管理员用户登录FusionInsight Manager，选择“集群 > 服务 > HDFS”，进入HDFS服务页面。
     2. 在“概览”页签下的“基本信息”区域，单击“NameNode Web UI”后的链接，进入NameNode Web UI界面。
     3. 选择“Utilities > Browse the file system”，单击，创建“/user/hetuserver/fiber/extra_file/driver/oracle”目录。
     4. 进入“/user/hetuserver/fiber/extra_file/driver/oracle”目录，单击上传2获取的Oracle驱动文件。
     5. 单击驱动文件所在行的“Permission”列的值，勾选“User”列的“Read”和“Write”，“Group”列的“Read”和“Other”列的“Read”，单击“Set”。
   • 通过使用HDFS命令直接上传：
     1. 登录HDFS服务客户端所在节点，切换到客户端安装目录，如“/opt/hadoopclient”。

        cd /opt/hadoopclient

     2. 执行以下命令配置环境变量。

        source bigdata_env

     3. 如果集群为安全模式，执行以下命令进行用户认证。普通模式集群无需执行用户认证。

        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管理员用户登录FusionInsight Manager，选择“集群 > 服务 > HetuEngine”，进入HetuEngine服务页面。
5. 在“概览”页签下的“基本信息”区域，单击“HSConsole Web UI”后的链接，进入HSConsole界面。
6. 选择“数据源”，单击“添加数据源”。在“添加数据源”页面填写参数。
   1. 配置“基本配置”，填写数据源名称，选择数据源类型“JDBC > Oracle”。
   2. 配置“Oracle配置”，参数配置请参考表1 Oracle配置。

      表1 Oracle配置

      参数	描述	取值样例
      驱动名称	选择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数据源自定义配置参数。

      表2 Oracle数据源自定义配置参数

      参数	描述	取值样例
      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. 登录集群客户端所在节点，执行以下命令，切换到客户端安装目录并认证用户。

   cd /opt/hadoopclient

   source bigdata_env

   kinit HetuEngine组件操作用户 （普通模式集群跳过）

8. 执行以下命令，登录数据源的catalog。

   hetu-cli --catalog 数据源名称 --schema 数据库名

   例如执行以下命令：

   hetu-cli --catalog oracle_1 --schema oralce

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列中，则会保留后缀的空格。

功能增强

SELECT * FROM TABLE(
  oracle.system.query(
    query => 'SELECT * FROM tpch.nation'));