使用LOAD DATA/XML命令导入数据

操作场景

您可以使用LOAD DATA FROM OBS或 LOAD XML FROM OBS语句从OBS桶上存储的文件中加载数据。文件会分段下载到本地临时盘上，然后导入到数据库。数据导入完成会删除本地文件。

单机、集群和Serverless类型的实例均支持将OBS的文本文件导入至TaurusDB实例。

LOAD DATA FROM OBS语句可以导入OBS桶中的文本文件或清单文件，您也可以使用SELECT INTO OUTFILE OBS导出数据保存到OBS桶中。

LOAD XML FROM OBS语句可以导入已手动上传到OBS的符合社区语法的XML文件。

版本约束

将OBS的文本文件导入到TaurusDB，需要数据库内核版本大于等于2.0.75.260300。

内核版本的查询方法请参见如何查看云数据库 TaurusDB实例的版本号。

前提条件

开启导入导出功能，需打开参数开关rds_load_from_obs_enable，修改参数值为ON。参数修改请参见修改TaurusDB实例参数。
执行导入的用户必须拥有对应库表的INSERT权限；如果使用REPLACE参数，则还需拥有对应库表的DELETE权限。

您必须先为TaurusDB数据库集群授予OBS的访问权限，然后才能从OBS存储桶中加载数据。

如果用户通过主账号开启加载OBS存储桶，不需要任何额外配置。如果是IAM子用户并且是第一次操作开启加载OBS存储桶，则需要给子用户临时配置创建委托的权限。

加载OBS存储桶时必须拥有如下IAM权限：

表1 IAM权限与委托
IAM策略	IAM权限	委托
基于角色或策略	iam:agencies:listAgencies iam:agencies:createAgency iam:permissions:listRolesForAgencyOnProject iam:permissions:grantRoleToGroupOnProject iam:permissions:grantRoleToAgencyOnProject iam:roles:listRoles iam:roles:createRole 如不满足，请创建自定义策略。	会自动创建委托DbsObsLoadAgency，该委托用户可见，删除委托会导致加载OBS存储桶失败。
基于身份策略	iam:agencies:list 如不满足，请创建自定义身份策略。	需要手动创建DbsObsLoadAgency委托。如果您已创建过委托，可跳过。

约束限制

表2 约束限制
模块	约束限制
LOAD DATA	建议不要同时发起多个LOAD DATA请求。多个LOAD DATA同时进行，数据高并发写入，表锁竞争以及系统IO抢占会影响总体效率，可能会出现SQL事务超时现象，导致LOAD DATA全部失败。 LOAD DATA导入含虚拟列的表时，建议通过修改“sql_mode”参数值为“STRICT_TRANS_TABLES”，开启严格模式，否则虚拟列的数据可能出现精度不准确或溢出等问题。如何修改参数请参见修改TaurusDB实例参数。请勿将XML格式文件通过LOAD DATA方式导入，可能会导致数据错乱。
LOAD XML	不支持LOAD XML语法树之外的其他参数。 LOAD XML 导入含虚拟列的表时，建议sql_mode开启严格模式。否则虚拟列的数据可能出现精度不准确或溢出等问题。不支持LOAD XML导入到基于分区表的视图。仅支持导入XML格式文件。
性能影响	数据导入导出阶段会在一定程度上影响TaurusDB实例性能，请选择在业务低峰时间导入。

手动创建DbsObsLoadAgency委托

登录IAM控制台。
在统一身份认证服务的左侧导航窗格中，选择“委托”页签，在上方输入框中输入“DbsObsLoadAgency”执行搜索。
- 如果无此委托，执行3。
- 如果已有委托，单击操作列的“授权”，执行6。
在创建委托页面，设置委托信息。

图1 创建委托
- 委托名称：DbsObsLoadAgency
- 委托类型：云服务
- 云服务：搜索op_svc_rds，选择数据库服务DBS
- 持续时间：永久
单击“完成”。
在授权的确认弹窗中，单击“立即授权”。
搜索勾选DbsObsLoad权限，单击“下一步”。
选择指定区域项目资源，勾选要授权的Region，单击“确定”。

使用LOAD DATA FROM OBS导入数据

语法介绍
```
LOAD DATA [FROM] OBS [FILE | MANIFEST] 'OBS-URI'
    [REPLACE | IGNORE]
    INTO TABLE tbl_name
    [PARTITION (partition_name,...)]
    [CHARACTER SET charset_name]
    [{FIELDS | COLUMNS}
        [TERMINATED BY 'string']
        [[OPTIONALLY] ENCLOSED BY 'char']
        [ESCAPED BY 'char']
    ]
    [LINES
        [STARTING BY 'string']
        [TERMINATED BY 'string']
    ]
    [IGNORE number {LINES | ROWS}]
    [(col_name_or_user_var,...)]
    [SET col_name = expr,...]
```
LOAD DATA FROM OBS使用以下特定的必需和可选参数，更多详细信息可以参考MySQL官方文档。
- FROM：可选参数。
- OBS：表示从OBS中加载数据。如果使用 [FROM] OBS从OBS桶中加载数据，则无法使用LOCAL INFILE关键字。
- FILE | MANIFEST：可选，默认为FILE。
  - FILE：表示从OBS单个文件中加载数据。
  - MANIFEST：表示从OBS指定清单上的所有文件中加载数据。
    清单文件是JSON格式文件，此文件列出了要加载到数据库的表的文本文件。其格式和内容如下：
```
{
    "entries": [
        {
            "url": "obs://bucket/customermeta",
            "mandatory": true
        },
        {
            "url": "obs://bucket/customerdata",
            "mandatory": true
        }
    ]
}
```
    清单中的每个url必须指定带桶名和文件的完整对象路径的url，格式固定为obs://bucket/object。mandatory表示在找不到文件时是否返回错误信息，默认为true，不建议修改。
  - OBS-URI
    指定要导入的文本或清单文件的URI，格式固定为 obs://bucket/object。您可以在OBS控制台中直接复制您要导入对象的URI，详情请参见下载对象。
    - bucket：指定要导入的文本或清单文件所在OBS桶的名称。
    - object：指定要导入的文本文件、清单文件或XML文件的名称。如果导入MANIFEST 清单文件，对象名对应为 object.manifest。
  - REPLACE | IGNORE：指定行数据在主键/唯一键冲突时的处理策略。参数可选，默认行为同IGNORE。
    - REPLACE：在冲突时用新行替换原有行数据。
    - IGNORE：冲突时新行直接被丢弃。
  - PARTITION：可选参数，用于指定将数据导入到指定分区、子分区。
  - CHARACTER SET：可选参数，用于指定导入文件的字符集。如果不指定，则默认使用系统变量character_set_filesystem指定的字符集。
  - FIELDS 和 COLUMNS：可选参数。指定字段格式。
    - TERMINATED BY：指定字段间的分隔符，默认是 \t。
    - ENCLOSED BY：指定字段值的封装字符，如果使用OPTIONALLY，则只封装字符类型字段；若不指定，则封装所有字段。
    - ESCAPED BY：指定转义字符，默认为反斜杠"\"。
  - LINES：可选参数。指定行格式。
    - STARTING BY：指定每行数据忽略的前缀字符串。
    - TERMINATED BY：指定行终止符，默认为换行符"\n"。
  - IGNORE：可选参数。指定忽略文件开头的指定行数。
  - col_name_or_user_var：可选参数。指定文件中的每一列数据，对应到表中的哪一列，或暂存到哪个变量中。
  - SET：可选参数。指定对导入的列值进行转换、计算。
参考示例
- 导入单个文件。
  从OBS的bucket桶中加载result.txt文本文件到TaurusDB数据库中的表t中。
```
LOAD DATA FROM OBS 'obs://bucket/result.txt' INTO TABLE t;
```
- 导入清单文件。
  将OBS的bucket桶中加载t.manifest清单文件到TaurusDB数据库中的表t中。该语句会将清单文件中的所有数据文件全部导入到表中。
```
LOAD DATA FROM OBS MANIFEST 'obs://bucket/t.manifest' INTO TABLE t;
```
- 指定字符集、列分隔符、行分隔符，导入单个文件。
  该语句每个字段以逗号分隔，每行数据以换行符分隔。
```
LOAD DATA FROM OBS FILE 'obs://bucket/test/tt.csv' INTO TABLE tt CHARACTER SET utf8mb4 FIELDS TERMINATED BY ','  LINES TERMINATED BY '\n';
```
- 指定字符集、列分隔符、转义字符、行分隔符、忽略行数等参数，导入清单文件。
  该语句指定唯一键冲突时，直接替换为新数据。指定文件字符集为 utf8mb4。字段分隔符为逗号。将\保留转义。指定行分隔符为换行符。忽略文件第一行。只导入指定的i1、t2、c3三列数据。
```
LOAD DATA FROM OBS MANIFEST 'obs://bucket/tt.manifest'
REPLACE INTO TABLE tt
CHARACTER SET utf8mb4
FIELDS TERMINATED BY ',' 
OPTIONALLY ENCLOSED BY '""'
ESCAPED BY '\\'
LINES TERMINATED BY '\n'
IGNORE 1 LINES
(i1, t2, c3);
```

使用LOAD XML FROM OBS导入数据

语法介绍
```
LOAD XML FROM OBS 'OBS-URI'
    [REPLACE | IGNORE]
    INTO TABLE tbl_name
    [PARTITION (partition_name,...)]
    [CHARACTER SET charset_name]
    [ROWS IDENTIFIED BY '<element-name>']
    [IGNORE number {LINES | ROWS}]
    [(field_name_or_user_var,...)]
    [SET col_name = expr,...]
```
LOAD XML FROM OBS语句使用以下特定的必需和可选参数。更多详细信息可以参考MySQL官方文档。
- OBS-URI：指定要导入的文本URI，格式固定为 obs://bucket/object。您可以在OBS控制台中直接复制您要导入对象的URI，详情请参见下载对象。
  - bucket：指定要导入的文本所在OBS桶的名称。
  - object：指定要导入的文本文件或XML文件的名称，不支持清单文件。
- REPLACE | IGNORE：指定行数据在主键/唯一键冲突时的处理策略。参数可选，默认行为同IGNORE。
  - REPLACE：在冲突时用新行替换原有行数据。
  - IGNORE：冲突时新行直接被丢弃。
- PARTITION：可选参数。用于指定将数据导入到指定分区、子分区。
- CHARACTER SET：可选参数。用于指定导入文件的字符集。如果不指定，则默认使用系统变量character_set_filesystem指定的字符集。
- ROWS IDENTIFIED BY：可选参数。指定行标识符，标签及其子元素构成一条表记录。
- IGNORE：可选参数。指定忽略文件开头的指定行数。
- field_name_or_user_var：可选参数。指定文件中的每一列数据，对应到表中的哪一列，或暂存到哪个变量中。
- SET：可选参数。指定数据在写入到表之前，对列数据进行转换与赋值。

参考示例

导入XML文件。
将OBS bucket中的test.xml文件加载到TaurusDB数据库的表t中。
```
LOAD XML FROM OBS 'obs://bucket/test.xml' INTO TABLE t;
```

指定字符集、字段分隔符、行分隔符，导入XML文件。

LOAD XML FROM OBS FILE 'obs://bucket/test//tt.csv' INTO TABLE tt CHARACTER SET utf8mb4 FIELDS TERMINATED BY ','  LINES TERMINATED BY '\n';

常见错误信息

导入文本文件时，错误信息中包含的OBS Error错误码具体含义如下：

表3 OBS Error 错误码
错误码	错误信息	处理措施
HttpErrorNotFound	对象不存在	请检查OBS桶中对象是否存在。
InvalidAccessKeyId	AK不合法	SQL执行时间过长，临时AK已过期。建议避免单次导出过大数据量。