---
title: "定义控制文件 - 导数工具 V4.3.5 | OceanBase 文档中心"
description: "定义控制文件 OBDUMPER 可通过预定义的控制文件对导出的数据进行预处理。 文件模板 控制文件的定义模版如下： lang=java ( ${列名} ${字节偏移位置}(可选) "${预处理函数}", ${列名} ${字节偏移位置}(可选) "${预处理函数}", ${列名} ${字节偏移位置}(可选) "${预处…"
---
切换语言

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

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

# 定义控制文件

更新时间：2026-04-02 14:15:52

[编辑](https://github.com/oceanbase/obdumper-loader-doc/edit/V4.3.5/zh-CN/600.OBDUMPER/300.obdumper-data-processing/100.obdumper-define-control-files.md)  

OBDUMPER 可通过预定义的控制文件对导出的数据进行预处理。

## 文件模板

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

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

```

- 列名：数据库表结构中的字段名称。OBDUMPER 不区分列名大小写。如果需要区分大小写，请将列名放入中括号（[ ]）或者反引号（``）内。例如：`[c1]` 表示 c1 列，`[C1]` 表示 C1 列。
 - 字节偏移位置：仅 `--pos` 格式数据支持定义字节偏移位置。

  相对偏移：`position(length)`，`length` 表示字段的长度（字节）。您可以使用关键字 POSITION 的相对偏移声明方式指定列长以从数据库表中导出某一段字节。示例：

  ```shell
  id position(2),
  gender position(7)

  ```

  其中 `id position(2)` 表示导出第 1 到第 2 个字节，`gender position(2)` 表示导出第 3 到第 9 个字节。
 - 预处理函数：在控制文件中为指定的列配置[预处理函数](https://www.oceanbase.com/docs/common-oceanbase-dumper-loader-1000000004997319)，以对导出的数据进行预处理。

  #### 注意

  控制文件的命名规范为 **<表名>.ctrl**。

## 注意事项

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

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

  ```
 - 控制文件不能和 `--exclude-column-names` 一起生效，控制文件包含 `--exclude-column-names` 的功能。
 - 控制文件中需要列出数据库目标表结构中的字段名称，否则无法与数据文件字段值对应。

## 示例

导出 `--cut` 格式的数据。示例如下：

```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 返回 nill 字符串
  c10 "to_timestamp(c10,'yyyyMMddHHmmssSSS')",                                                    -- c10 列的值进行格式化，若格式失败则返回 null，否则返回 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 "sequence(100,1)"                                                                           -- c25 列的值对指定的列生成递增的序列值（100 代表初始值，1 代表递增值）
  c26 "reverse(c26)",                                                                             -- c26 列的值进行顺序颠倒
  c27 "mask("c27",'A','a','b')",                                                                 -- c27 列的大写字母转换为字母 A，小写字母转换为 a，数字转换为 b
  c28 "mask_first_n(c28,'A','a','b',5)",                                                        -- c28 列的前 5 个字符中的大写字母转换为字母 A，小写字母转化为 a，数字转换为 b
  c29 "mask_last_n(c29,'A','a','b',5)",                                                         -- c29 列的后 5 个字符中的大写字母转换为字母 A，小写字母转化为 a，数字转换为 b
  c30 "mask_show_first_n(c30,'A','a','b',5)",                                                   -- c30 列除前 5 个字符之外的所有字符中的大写字母转换为字母 A，小写字母转化为 a，数字转换为 b
  c31 "mask_show_last_n(c31,'A','a','b',5)"                                                     -- c31 列除后 5 个字符之外的所有字符中的大写字母转换为字母 A，小写字母转化为 a，数字转换为 b
);

```

#### 说明

详情请参见 **预处理函数** 中的函数列表。

  上一篇 下一篇 ![有帮助](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) 咨询热线