# 添加GAUSSDB数据源
#### 操作场景
本章节指导用户在HSConsole界面添加GaussDB类型的JDBC数据源，以实现对GaussDB数据源的查询与分析。
#### 添加GAUSSDB数据源前提条件
- 数据源所在集群与HetuEngine集群节点网络互通。
- 在HetuEngine所在集群的所有节点的"/etc/hosts"文件中，添加待对接数据源所在集群的主机名称和对应的IP映射（数据源集群新扩容主机后，需要同步添加至HetuEngine所在集群的所有节点，集群外客户端需与HetuEngine集群保持一致），及其"/etc/hosts"文件中的"10.10.10.10 hadoop.*系统域名*"（如"10.10.10.10 hadoop.hadoop.com"），否则HetuEngine无法根据主机名称连接到非本集群节点。
- 已创建HetuEngine计算实例，可参考[创建HetuEngine计算实例](https://support.huaweicloud.com/cmpntguide-lts-mrs/mrs_01_1731.html)。
 
#### 添加GAUSSDB数据源操作步骤
1. 使用HetuEngine管理员用户登录FusionInsight Manager界面。 
   登录集群Manager具体操作，请参考[访问MRS集群Manager](https://support.huaweicloud.com/usermanual-mrs/mrs_01_0128.html)。
   
   
2. 选择"集群 \> 服务 \> HetuEngine"，进入HetuEngine服务页面。
3. 在"概览"页签下的"基本信息"区域，单击"HSConsole WebUI"后的链接，进入HSConsole界面。
4. 选择"数据源"，单击"添加数据源"。在"添加数据源"页面填写参数。 
   1. 配置"基本配置"，填写数据源名称，"数据源类型"选择"JDBC \> GAUSSDB-A"，"驱动"默认为"gaussdba"。
   
   2. 配置"GAUSSDB-A配置"，参数配置请参考[表1]。
       表1GAUSSDB-A配置 
      | 参数       | 描述                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | 取值样例                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
      |:---|:---|:---|
      | JDBC URL | 连接GaussDB数据源的JDBC URL地址。格式为： jdbc:postgresql://*GaussDB数据源Coordinator的业务IP* :*端口* /*数据库名称*。 - GaussDB数据源Coordinator的业务IP：使用omm用户在GaussDB数据源的节点上执行**source ${BIGDATA_HOME}/mppdb/.mppdbgs_profile命令** 和**gs_om -t status --detail**命令，会列出所有Coordinator，取对应Coordinator的IP的业务IP。  - 端口：登录GaussDB数据源的Manager页面，在MPPDB的配置页面搜索"mppdb.coo.cooPortBase"参数，该参数值即为MPPDB的coordinator进程端口。   若GaussDB数据源开启SSL，URL地址需添加如下SSL相关参数：ssl=true\&sslfactory=org.postgresql.ssl.NonValidatingFactory。 | - GaussDB数据源未开启SSL： jdbc:postgresql://10.0.136.1:25308/postgres   - GaussDB数据源开启SSL： jdbc:postgresql://10.0.136.1:25308/postgres?ssl=true\&sslfactory=org.postgresql.ssl.NonValidatingFactory    |
      | 用户名      | GaussDB数据源连接用户名。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | 根据连接数据源的用户名修改。                                                                                                                                                                                                                                                                                                                                                                                                                                         |
      | 密码       | GaussDB数据源连接密码。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | 根据连接数据源的用户名密码修改。                                                                                                                                                                                                                                                                                                                                                                                                                                       |
         
      
   
   3. （可选）配置"GaussDB用户信息配置"，参考[表2]。
      "GaussDB用户信息配置"与"HetuEngine-GaussDB用户映射配置"要搭配使用，HetuEngine在对接GaussDB数据源时，通过用户映射，使得HetuEngine的用户具备与GaussDB数据源被映射的用户访问GaussDB数据源时同样的权限。可以多个HetuEngine用户对应一个GaussDB用户。
      在GaussDB数据源中，创建的用户名要符合标识符的命名规范，且最大长度不超过63个字符。当用户名中包含大写字母时数据库将自动转换为小写字母，如果需要创建包含大写字母的用户名则需要使用双引号括起来。因此，配置"Data Source User"时，必须使用GaussDB数据库转换后的用户名。
      例如：
      - 在GaussDB数据源创建的用户名为Gaussuser1，则Data Source User应为gaussuser1。
      
      - 在GaussDB数据源创建的用户名为"Gaussuser1"，则Data Source User应为Gaussuser1。
      
      
       表2GaussDB用户信息配置 
      | 名称               | 描述                                                                                                                       |
      |:---|:---|
      | Data Source User | 数据源用户名称。 如果配置了数据源用户为gaussuser1，那么必须有映射到gaussuser1的HetuEngine用户。例如创建hetuuser1映射到gaussuser1。 |
      | Password         | 对应数据源的用户认证密码。                                                                                                            |
         
      
   
   4. （可选）配置"HetuEngine-GaussDB用户映射配置"，参考[表4 HetuEngine-GaussDB用户映射配置]。
      以HetuEngine User和Data Source User键值对的形式配置多个HetuEngine的用户对应[4.c]多个用户的其中一个。当使用不同的HetuEngine用户访问GaussDB时，可使用对应的GaussDB的用户和密码。
       表3HetuEngine-GaussDB用户映射配置 
      | 名称               | 描述                                                                 |
      |:---|:---|
      | HetuEngine User  | HetuEngine用户名。                                                     |
      | Data Source User | 数据源用户，如gaussuser1（[表2]中配置的数据源用户）。 |
         
      
   
   5. （可选）修改自定义配置。
      - 单击"增加"可以增加自定义配置参数。配置GaussDB数据源自定义参数，参考[表4]。
         表4GaussDB数据源自定义配置参数 
        | 名称                             | 描述                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | 取值样例               |
        |:---|:---|:---|
        | use-connection-pool            | 是否使用JDBC连接池。 - true：使用JDBC连接池。  - false：不使用JDBC连接池。                                                                                                                                                                                                                                                                                                | true               |
        | jdbc.connection.pool.maxTotal  | JDBC连接池中最大连接数。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | 8                  |
        | jdbc.connection.pool.maxIdle   | JDBC连接池中最大空闲连接数。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | 8                  |
        | jdbc.connection.pool.minIdle   | JDBC连接池中最小空闲连接数。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | 0                  |
        | join-pushdown.enabled          | 是否允许将Join下推到数据源执行。 - true：允许将Join下推到数据源执行  - false：Join不会被下推到数据源执行，因此会消耗更多的网络和计算资源                                                                                                                                                                                                                                                           | true               |
        | join-pushdown.strategy         | Join下推功能开启后配置此参数。 - AUTOMATIC：基于代价估算（cost-based）的Join下推  - EAGER：尽可能地Join下推。                                                                                                                                                                                                                                                                      | AUTOMATIC          |
        | source-encoding                | GaussDB数据源编码方式。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | UTF-8              |
        | multiple-cnn-enabled           | 是否使用GaussDB多CN配置。如果使用，首先确保已关闭JDBC连接池功能，其次JDBC URL格式为：jdbc:postgresql://host:port/database,jdbc:postgresql://host:port/database,jdbc:postgresql://host:port/database。                                                                                                                                                                                                                                                                                                                                                                     | false              |
        | parallel-read-enabled          | 是否使用并行数据读取功能。 启用并行数据读取功能将基于节点分布和"max-splits"参数值来确定实际的split数。 并行读取将与数据源创建多个连接，被依赖的数据源应当具备支持负载的能力。                                                                                                                                                                                                                                                                                                                                                                             | false              |
        | split-type                     | 并行数据读取类型。 - NODE：基于GaussDB数据源DN节点划分并行度。  - PARTITION：基于表分区划分并行度。  - INDEX：基于表索引划分并行度。                                                                                                                                                                                                 | NODE               |
        | max-splits                     | 最大并行度。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | 5                  |
        | unsupported-type-handling      | 当连接器不支持此数据类型时，可以转换为VARCHAR，从而避免失败。 - CONVERT_TO_VARCHAR：不支持的类型将转为VARCHAR类型，并且只支持对它们的读操作。不支持的类型包括：BIT VARYING、CIDR、MACADDR、INET、OID、REGTYPE、REGCONFIG、POINT。  - IGNORE（默认值）：不支持的类型将不在查询结果中显示。                                                                                                                                                      | CONVERT_TO_VARCHAR |
        | decimal-mapping                | 默认情况下HetuEngine会跳过未指定精度或超过最大精度38位的Decimal/Number/Numeric数据类型，通过设置"decimal-mapping=allow_overflow"，将其映射为Decimal(38，*x*)数据类型，x值为decimal-default-scale的值。                                                                                                                                                                                                                                                                                                                                                                                   | allow_overflow     |
        | decimal-default-scale          | Decimal/Number/Numeric映射数据类型Decimal(38，*x*)小数位精度值。 默认值：0 取值范围：0\~38                                                                                                                                                                                                                                                                                                                                                                                                         | 0                  |
        | case-insensitive-name-matching | HetuEngine支持的GAUSSDB数据源的Schema和Table名称大小写格式敏感。 - false：仅支持查询全小写的Schema或Table。默认值为false。  - true： - 忽略大小写后无同名的Schema或Table：支持查询该Schema或Table。  - 忽略大小写后存在同名的Schema或Table：不支持查询该Schema或Table。     | false              |
           
        
      
      - 单击"删除"可以删除已增加的自定义配置参数。
       
   
   6. 单击"确定"。
   
   
   
   
5. 登录集群客户端所在节点，执行以下命令，切换到客户端安装目录，例如安装目录为"/opt/client"，具体以实际替换。 
   ```
   cd /opt/client
   ```
   执行以下命令配置环境变量。
   ```
   source bigdata_env
   ```
   执行以下命令进行用户认证。（集群未启用Kerberos认证（普通模式）时跳过此步骤）
   ```
   kinit HetuEngine组件操作用户
   ```
   
   
6. 执行以下命令，登录数据源的catalog。 
   ```
   hetu-cli --catalog 数据源名称 --schema 数据库名
   ```
   例如执行以下命令：
   ```
   hetu-cli --catalog gaussdb_1 --schema admin
   ```
   
   
7. 执行以下命令，可正常查看数据库表信息或不报错即表示连接成功。 
   ```
   show tables;
   ```
   
   
 
#### GAUSSDB数据类型映射
| GAUSSDB数据类型（data type）   | HetuEngine数据类型（data type） |
|:---|:---|
| BOOLEAN                  | BOOLEAN                   |
| TINYINT                  | TINYINT                   |
| SMALLINT                 | SMALLINT                  |
| INTEGER                  | INTEGER                   |
| BINARY_INTEGER           | INTEGER                   |
| BIGINT                   | BIGINT                    |
| SMALLSERIAL              | SMALLINT                  |
| SERIAL                   | INTEGER                   |
| BIGSERIAL                | BIGINT                    |
| FLOAT4 (REAL)            | REAL                      |
| FLOAT8(DOUBLE PRECISION) | DOUBLE PRECISION          |
| DECIMAL\[p (,s)\]        | DECIMAL\[p (,s)\]         |
| NUMERIC\[p (,s)\]        | DECIMAL\[p (,s)\]         |
| CHAR(n)                  | CHAR(n)                   |
| CHARACTER(n)             | CHAR(n)                   |
| NCHAR(n)                 | CHAR(n)                   |
| VARCHAR(n)               | VARCHAR(n)                |
| CHARACTER VARYING(55)    | VARCHAR(n)                |
| VARCHAR2(n)              | VARCHAR(n)                |
| NVARCHAR2(n)             | VARCHAR                   |
| TEXT(CLOB)               | VARCHAR                   |
| DATE                     | TIMESTAMP                 |
| TIMESTAMP                | TIMESTAMP                 |
| UUID                     | UUID                      |
| JSON                     | JSON                      |
   
#### 添加GAUSSDB数据源约束
- 不支持如下语法：GRANT、REVOKE、SHOW GRANTS、SHOW ROLES、SHOW ROLE GRANTS。
- UPDATE和DELETE语法不支持筛选条件子句中包含跨catalog的条件，例如：UPDATE mppdb.table SET column1=value WHERE column2 IN (SELECT column2 from hive.table)。
- UPDATE语法不支持更新DATE/TIMESTAMP/VARBINARY字段。
- 不支持查询WHERE语句条件为REAL，例如SELECT \* FROM mppdb.table WHERE column1 = REAL '1.1'。
- DELETE语法不支持筛选条件子句中包含子查询，例如：DELETE FROM mppdb.table WHERE column IN (SELECT column FROM mppdb.table1)。
- HetuEngine支持GaussDB数据源Decimal/Number/Numeric类型数据的最大精度不超过38位。
- 当谓词的前后两端任意一端包含子查询时，该谓词不会下推，如示例语句count(\*) 后面存在子查询，则不下推，但子查询中的min函数可以下推。
  ```
  select count(*) from item where i_current_price = (select min(i_current_price) from item);
  ```