---
title: "定义控制文件 | OceanBase 文档中心"
description: "定义控制文件 通过已定义的控制文件，OBLOADER 可以对被导入的数据进行预处理。 文件模板 控制文件的定义模版如下所示： lang=java ( ${列名} ${字节偏移位置}(可选) "${预处理函数}"(可选) ${映射定义}(可选), ${列名} ${字节偏移位置}(可选) "${预处理函数}"(可选) $…"
---
切换语言

- 中文站 - 简体中文
- International - English
- 日本站 - 日本語

文档反馈![](https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*eAudSaxX8P0AAAAAAAAAAAAADiGDAQ/original) 导数工具V 4.2.1 企业版

# 定义控制文件

更新时间：2025-08-04 14:06:01

通过已定义的控制文件，OBLOADER 可以对被导入的数据进行预处理。

## 文件模板

控制文件的定义模版如下所示：

```javascript
lang=java
(
  ${列名} ${字节偏移位置}(可选) "${预处理函数}"(可选) ${映射定义}(可选),
  ${列名} ${字节偏移位置}(可选) "${预处理函数}"(可选) ${映射定义}(可选),
  ${列名} ${字节偏移位置}(可选) "${预处理函数}"(可选) ${映射定义}(可选),
  ${列名} ${字节偏移位置}(可选) "${预处理函数}"(可选) ${映射定义}(可选)
);

```

现有 Ctrl 文件的设计如下：

```sql
lang=java
server=mysql|oracle (
    c1 "nvl(c1, 'not null')" map(field_position),
    c2 "none" map(field_position)
);

```

#### 注意

- `field_position` 为导入的数据文件中预处理数据的列位置。
 - 控制文件的命名规范为 **<表名>.ctrl**。
 - 对于 `--cut`, `--csv`, `--sql` 格式数据，无需定义字节偏移位置。
 - 预处理函数定义请参考 [预处理函数](https://www.oceanbase.com/docs/enterprise-oceanbase-dumper-loader-cn-10000000002034061)。

## 注意事项

- 如表中定义的列名包含了数据库关键字，需在列名前后添加反引号（`）进行转义。示例如下：

  ```sql
  lang=java
  (
      `WHEN` "lower(`WHEN`)",
      c2 "nanvl(c2,'0')"
  );

  ```

- OBLOADER 3.x 版本不再支持 map 文件，字段映射功能合并到 ctrl 文件中。示例如下：

  ```sql
  lang=java(
      C1 "NONE" map(1),
      C2 "NONE" map(1), // 多列映射
      C3 "CONSTANT('xxx')", // xxx 为指定的常量
      C4 "SEQUENCE(100, 1)" // 100 为初值，1 为步长
  );

  ```

#### 说明

OBLOADER 3.0.0 之前版本仅支持单列映射，不支持生成列。OBLOADER 3.0.0 之后版本的控制文件中可以配置多列映射以及生成列。生成列------数据文件中不存在的列。

## 示例

- 导入 `--pos` 格式的数据。示例如下：

  ```sql
  lang=java
  (
    c1 position(1:5) "trim(c1)",                   -- 截取 c1 列的第 1 到第 5 个字节，并且对得到的结果两侧截断空格
    c2 position(7:25) "replace(trim(c2),'',' ')"   -- 截取 c2 列的第 7 到第 25 个字节，并且对得到的结果两侧截断空格，同时对于空字符用空格替代
  );

  ```

- 导入 `--cut`、`--csv` 和 `--sql` 格式的数据。示例如下：

  ```sql
  lang=java
  (
    c1 "lower(c1)",                                                                           -- c1 列的值中的字母转换为小写
    c2 "ltrim(c2)",                                                                           -- c2 列的值从左开始截断空格
    c3 "rtrim(c3)",                                                                           -- c3 列的值从右开始截断空格
    c4 "substr(c4,0,5)",                                                                      -- c4 列的值第 1 位置截取 5 个字符长度的字符串
    c5 "trim(c5)",                                                                            -- c5 列的值左右两侧截断空格
    c6 "upper(c6)",                                                                           -- c6 列的值中的字母转换为大写
    c7 "nanvl(c7,'0')",                                                                       -- c7 列的值进行数值验证，非数值则返回 0
    c8 "replace(c8,'a','A')",                                                                 -- c8 列的值中的 a 替换为 A
    c9 "nvl(c9,'nill')",                                                                      -- c9 列的值进行判空，若为 null 返回 null 字符串
    c10 "to_timestamp(c10,'yyyyMMddHHmmssSSS')",                                              -- c10 列的值进行格式化，若格式失败则返回 null，否则返u回 yyyy-MM-dd HH:mm:ss.SSS
    c11 "length(c11)",                                                                        -- c11 列的值进行长度计算
    c12 "lpad(c12,5,'x')",                                                                    -- c12 列的值左侧追加 5 个字节长度字符串 'x'
    c13 "rpad(c13,5,'x')",                                                                    -- c13 列的值右侧追加 5 个字节长度字符串 'x'
    c14 "convert(c14,'utf-8','gbk')",                                                         -- c14 列的值从 gbk 转换为 utf-8 字符编码
    c15 "concat(c15, '_suffix')",                                                             -- c15 列的值与常量进行拼接
    c16 "none",                                                                               -- c16 列的值不作任何处理，直接返回对应列的值
    c17 "systimestamp",                                                                       -- c17 列的值不作任何处理，直接返回当前集群的时间戳
    c18 "constant('1')",                                                                      -- c18 列的值不作任何处理，仅返回常量 1
    c19 "tmsfmt(c19,'yyyyMMddHHmmssSSS','20210310000000000','yyyyMMddHHmmssSSS')",            -- c19 列的值进行日期验证，验证失败返回默认值
    c20 "lpadb(c20,5,'x')",                                                                   -- c20 列的值左侧追加 5 个字节长度的(单)字符 'x'
    c21 "rpadb(c21,5,'x')",                                                                   -- c21 列的值右侧追加 5 个字节长度的(单)字符 'x'
    c22 "case when length(trim(c22))<18 then 'Y' else 'N' end",                               -- c22 列的值进行条件真值匹配，若为真返回对应列的值
    c23 "case length(trim(c23)) when '1' then 'one' when '2' then 'two' else 'unknown' end",  -- c23 列的值进行条件等值匹配，若匹配成功返回对应列的值
    C24 "SYSDATE",                                                                            -- c24 列的值为当前日期
    C25 "MASK(C25)",                                                                          -- c25 列的值进行脱敏，只对列名有效，列中的大、小写字母和数字使用默认脱敏字符替代（默认脱敏字符：大写字母 X，小写字母 x，数字 n）
    C26 "MASK_FIRST_N(C26,'A','a','b',3)",                                                    -- c26 列的值指定大、小写字母以及数字的脱敏字符（默认 N 为 0，从第一个字符开始）
    C27 "MASK_LAST_N(C27,'A','a','b',3)",                                                     -- c27 列的值指定大、小写字母以及数字的脱敏字符（默认 N 为 0，从最后一个字符开始）
    C28 "MASK_SHOW_FIRST_N(C28,'A','a','b',3)",                                               -- c28 列的值指定不脱敏字符数（默认 N 为 0，从第一个字符开始）
    C29 "MASK_SHOW_LAST_N(C29,'A','a','b',3)",                                                -- c29 列的值指定不脱敏字符数（默认 N 为 0，从最后一个字符开始）
    C30 "REVERSE(C30)",                                                                       -- c30 列的值将字符顺序颠倒
  )

  ```

  #### 注意

  OBLOADER 3.0.0 之后版本不再支持 `--null-replacer`,`--empty-replacer`, ` --default-date` , `--date-format` 选项。

 上一篇 下一篇 ![有帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*y6ocSqN8cqsAAAAAAAAAAAAAARQnAQ)![无帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*BG9IQJyLHF8AAAAAAAAAAAAAARQnAQ)![反馈](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*eTWdQKCRKHwAAAAAAAAAAAAAARQnAQ)[AI](https://www.oceanbase.com/obi) 咨询热线