OceanBase logo

OceanBase

A unified distributed database ready for your transactional, analytical, and AI workloads.

DEPLOY YOUR WAY

OceanBase Cloud

The best way to deploy and scale OceanBase

OceanBase Enterprise

Run and manage OceanBase on your infra

TRY OPEN SOURCE

OceanBase Community Edition

The free, open-source distributed database

OceanBase seekdb

Open source AI native search database

Customer Stories

Real-world success stories from enterprises across diverse industries.

View All
BY USE CASES

Mission-Critical Transactions

Global & Multicloud Application

Elastic Scaling for Peak Traffic

Real-time Analytics

Active Geo-redundancy

Database Consolidation

Resources

Comprehensive knowledge hub for OceanBase.

Blog

Live Demos

Training & Certification

Documentation

Official technical guides, tutorials, API references, and manuals for all OceanBase products.

View All
PRODUCTS

OceanBase Cloud

OceanBase Database

Tools

Connectors and Middleware

QUICK START

OceanBase Cloud

OceanBase Database

BEST PRACTICES

Practical guides for utilizing OceanBase more effectively and conveniently

Company

Learn more about OceanBase – our company, partnerships, and trust and security initiatives.

About OceanBase

Partner

Trust Center

Contact Us

International - English
中国站 - 简体中文
日本 - 日本語
Sign In
Start on Cloud

A unified distributed database ready for your transactional, analytical, and AI workloads.

DEPLOY YOUR WAY

OceanBase Cloud

The best way to deploy and scale OceanBase

OceanBase Enterprise

Run and manage OceanBase on your infra

TRY OPEN SOURCE

OceanBase Community Edition

The free, open-source distributed database

OceanBase seekdb

Open source AI native search database

Customer Stories

Real-world success stories from enterprises across diverse industries.

View All
BY USE CASES

Mission-Critical Transactions

Global & Multicloud Application

Elastic Scaling for Peak Traffic

Real-time Analytics

Active Geo-redundancy

Database Consolidation

Comprehensive knowledge hub for OceanBase.

Blog

Live Demos

Training & Certification

Documentation

Official technical guides, tutorials, API references, and manuals for all OceanBase products.

View All
PRODUCTS
OceanBase CloudOceanBase Database
ToolsConnectors and Middleware
QUICK START
OceanBase CloudOceanBase Database
BEST PRACTICES

Practical guides for utilizing OceanBase more effectively and conveniently

Learn more about OceanBase – our company, partnerships, and trust and security initiatives.

About OceanBase

Partner

Trust Center

Contact Us

Start on Cloud
编组
All Products
    • Databases
    • iconOceanBase Database
    • iconOceanBase Cloud
    • iconOceanBase Tugraph
    • iconInteractive Tutorials
    • iconOceanBase Best Practices
    • Tools
    • iconOceanBase Cloud Platform
    • iconOceanBase Migration Service
    • iconOceanBase Developer Center
    • iconOceanBase Migration Assessment
    • iconOceanBase Admin Tool
    • iconOceanBase Loader and Dumper
    • iconOceanBase Deployer
    • iconKubernetes operator for OceanBase
    • iconOceanBase Diagnostic Tool
    • iconOceanBase Binlog Service
    • Connectors and Middleware
    • iconOceanBase Database Proxy
    • iconEmbedded SQL in C for OceanBase
    • iconOceanBase Call Interface
    • iconOceanBase Connector/C
    • iconOceanBase Connector/J
    • iconOceanBase Connector/ODBC
    • iconOceanBase Connector/NET
icon

OceanBase Loader and Dumper

V4.3.4.1

  • Document Overview
  • Introduction
  • Technical Mechanism
  • Preparations
    • Prepare the environment
    • Prepare data
    • Download OBLOADER & OBDUMPER
    • Startup parameters
  • User Guide (OBLOADER)
    • Quick start
    • Command-line options
    • Direct load
    • Data processing
      • Define a control file
      • Preprocessing functions
      • Case expressions
    • Use cases of command-line options
    • Performance tuning
    • Error handling
    • FAQ
  • User Guide (OBDUMPER)
    • Quick start
    • Command-line options
    • Data processing
      • Define a control file
      • Preprocessing functions
      • Case expressions
    • Performance tuning
    • FAQ
  • Security Features
  • Connection configuration
  • Self-service Troubleshooting
  • Release Note
    • Release Note
      • 4.x
        • OBLOADER & OBDUMPER V4.3.4.1
        • OBLOADER & OBDUMPER V4.3.4
        • OBLOADER & OBDUMPER V4.3.3.1
        • OBLOADER & OBDUMPER V4.3.3
        • OBLOADER & OBDUMPER V4.3.2.1
        • OBLOADER & OBDUMPER V4.3.2
        • OBLOADER & OBDUMPER V4.3.1.1
        • OBLOADER & OBDUMPER V4.3.1
        • OBLOADER & OBDUMPER V4.3.0
        • OBLOADER & OBDUMPER V4.2.8.2
        • OBLOADER & OBDUMPER V4.2.8.1
        • OBLOADER & OBDUMPER V4.2.8
        • OBLOADER & OBDUMPER V4.2.7
        • OBLOADER & OBDUMPER V4.2.6
        • OBLOADER & OBDUMPER V4.2.5
        • OBLOADER & OBDUMPER V4.2.4
        • OBLOADER & OBDUMPER V4.2.1
        • OBLOADER & OBDUMPER V4.1.0
        • OBLOADER & OBDUMPER V4.0.0
      • 3.x
        • OBLOADER \& OBDUMPER V3.1.0
        • OBLOADER \& OBDUMPER V3.0.0
    • Versioning rules

Download PDF

Document Overview Introduction Technical Mechanism Prepare the environment Prepare data Download OBLOADER & OBDUMPER Startup parameters Quick start Command-line options Direct load Define a control file Preprocessing functions Case expressions Use cases of command-line options Performance tuning Error handling FAQ Quick start Command-line options Define a control file Preprocessing functions Case expressions Performance tuning FAQ Security Features Connection configuration Self-service Troubleshooting Versioning rules
OceanBase logo

The Unified Distributed Database for the AI Era.

Follow Us
Products
OceanBase CloudOceanBase EnterpriseOceanBase Community EditionOceanBase seekdb
Resources
DocsBlogLive DemosTraining & Certification
Company
About OceanBaseTrust CenterLegalPartnerContact Us
Follow Us

© OceanBase 2026. All rights reserved

Cloud Service AgreementPrivacy PolicySecurity
Contact Us
Document Feedback
  1. Documentation Center
  2. OceanBase Loader and Dumper
  3. V4.3.4.1
iconOceanBase Loader and Dumper
V 4.3.4.1
  • V 4.3.5
  • V 4.3.4.1
  • V 4.3.4
  • V 4.3.3.1
  • V 4.3.3
  • V 4.3.2.1
  • V 4.3.2
  • V 4.3.1
  • V 4.2.8
  • V 4.2.7
  • V 4.2.6
  • V 4.2.5 and earlier

Define a control file

Last Updated:2026-04-07 08:50:21  Updated
share
What is on this page
File template
Considerations
Examples

folded

share

OBDUMPER can preprocess the exported data by using a predefined control file.

File template

The template for defining a control file is as follows:

lang=java
(
  ${Column name} ${Byte offset} (optional) "${Preprocessing function}",
  ${Column name} ${Byte offset} (optional) "${Preprocessing function}",
  ${Column name} ${Byte offset} (optional) "${Preprocessing function}"
);
  • Column name: the name of a field in the database table structure. OBDUMPER is not case-sensitive to column names. If you want to specify column names in a case-sensitive manner, enclose the column names in either square brackets [ ] or backticks ``. For example, [c1] indicates the c1 column, and [C1] indicates the C1 column.

  • Byte offset: This option is supported only for data in the --pos format.

    Relative offset: position(length), where length indicates the length of the field in bytes. You can use the relative offset declaration method of the POSITION keyword to specify the column length and export a specific segment of bytes from the database table. Example:

    id position(2),
    gender position(7)
    

    Here, id position(2) indicates that bytes 1 to 2 are exported, and gender position(2) indicates that bytes 3 to 9 are exported.

  • Preprocessing function: Configure a preprocessing function in the control file for a specified column to preprocess the exported data.

    Notice

    The naming convention for a control file is <table name>.ctrl.

Considerations

  • If a column name in the table contains a database keyword, you must enclose the column name in backticks (`). Example:

    lang=java
    (
        `WHEN` "lower(`WHEN`)",
        c2 "nanvl(c2,'0')"
    );
    
  • A control file cannot take effect together with the --exclude-column-names option. The functionality of the --exclude-column-names option is already included in the control file.

  • The control file must list the field names in the target database table. Otherwise, the field values in the data file cannot be correctly corresponded.

Examples

Here is an example of exporting data in the CUT format Here is an example:

lang=java
(
  c1 "lower(c1)",                                                                                 -- Convert the characters in the c1 column to lowercase.
  c2 "ltrim(c2)",                                                                                 -- Truncate leading spaces from the values in the c2 column.
  c3 "rtrim(c3)",                                                                                 -- Truncate trailing spaces from the values in the c3 column.
  c4 "substr(c4,0,5)",                                                                            -- Extract a string of 5 characters from the first position in the values of the c4 column.
  c5 "trim(c5)",                                                                                  -- Truncate leading and trailing spaces from the values in the c5 column.
  c6 "upper(c6)",                                                                                 -- Convert the characters in the c6 column to uppercase.
  c7 "nanvl(c7,'0')",                                                                             -- Verify if the values in the c7 column are numeric. If not, return 0.
  c8 "replace(c8,'a','A')",                                                                       -- Replace 'a' with 'A' in the values of the c8 column.
  c9 "nvl(c9,'nill')",                                                                            -- Check if the values in the c9 column are null. If so, return the string 'nill'.
  c10 "to_timestamp(c10,'yyyyMMddHHmmssSSS')",                                                    -- Format the values in the c10 column. If the formatting fails, return null. Otherwise, return a timestamp in the format of yyyy-MM-dd HH:mm:ss.SSS.
  c11 "length(c11)",                                                                              -- Calculate the length of the values in the c11 column.
  c12 "lpad(c12,5,'x')",                                                                          -- Add a 5-character string 'x' to the left of the values in column c12
  c13 "rpad(c13,5,'x')",                                                                 -- Add a 5-character string 'x' to the right of the values in column c13
  c14 "convert(c14,'utf-8','gbk')",                                                               -- Convert the character encoding of the values in the c14 column from gbk to utf-8.
  c15 "concat(c15, '_suffix')",                                                                   -- Concatenate the values in the c15 column with the constant '_suffix'.
  c16 "none",                                                                                     -- Return the values in the c16 column without any processing.
  c17 "systimestamp",                                                                             -- Return the current timestamp of the cluster for the values in the c17 column.
  c18 "constant('1')",                                                                            -- Return the constant value 1 for the values in the c18 column.
  c19 "tmsfmt(c19,'yyyyMMddHHmmssSSS','20210310000000000','yyyyMMddHHmmssSSS')",                  -- Verify the date in the values of the c19 column. If the verification fails, return the default value.
  c20 "lpadb(c20,5,'x')",                                                                      -- Add five single-byte 'x' characters to the left side of the values in the c20 column.
  c21 "rpadb(c21,5,'x')",                                                                 -- Add five single-byte 'x' characters to the right side of the values in the c21 column.
  c22 "case when length(trim(c22))<18 then 'Y' else 'N' end",                                     -- Check if the length of the values in the c22 column (after trimming) is less than 18. If so, return 'Y'; otherwise, return 'N'.
  c23 "case length(trim(c23)) when '1' then 'one' when '2' then 'two' else 'unknown' end",        -- Check if the values in the c23 column (after trimming) are equal to '1' or '2'. If so, return the corresponding value; otherwise, return 'unknown'.
  c24 "sysdate",                                                                                  -- Return the current date for the values in the c24 column.
  c25 "sequence(100,1)"                                                                           -- Generate an incremental sequence value for the c25 column. The initial value is 100 and the increment is 1.
  c26 "reverse(c26)",                                                                             -- Reverse the values in the c26 column.
  c27 "mask("c27",'A','a','b')",                                                                 -- Convert uppercase letters in the c27 column to 'A', lowercase letters to 'a', and digits to 'b'.
  c28 "mask_first_n(c28,'A','a','b',5)",                                                        -- Convert the first 5 characters of the c28 column: uppercase letters to 'A', lowercase letters to 'a', and digits to 'b'.
  c29 "mask_last_n(c29,'A','a','b',5)",                                                         -- Convert the last 5 characters of the c29 column: uppercase letters to 'A', lowercase letters to 'a', and digits to 'b'.
  c30 "mask_show_first_n(c30,'A','a','b',5)",                                                   -- Convert all characters except the first 5 of the c30 column: uppercase letters to 'A', lowercase letters to 'a', and digits to 'b'.
  c31 "mask_show_last_n(c31,'A','a','b',5)"                                                     -- Convert all characters except the last 5 of the c31 column: uppercase letters to 'A', lowercase letters to 'a', and digits to 'b'.
);

Note

For more information, see the list of preprocessing functions.

Previous topic

Command-line options
Last

Next topic

Preprocessing functions
Next
What is on this page
File template
Considerations
Examples