全部产品
Search

搜索本产品

    云原生大数据计算服务 MaxCompute：TO_CHAR

    文档中心

    云原生大数据计算服务 MaxCompute：TO_CHAR

    更新时间：Dec 15, 2025

    TO_CHAR函数用于将不同类型数据转换为STRING类型。分为字符串类型和日期类型两种。字符串类型指的是将BOOLEAN、BIGINT、DECIMAL或DOUBLE类型值转换为对应的STRING类型。日期类型指的是将日期按照指定格式转换为字符串。

    BOOLEAN/BIGINT/DECIMAL/DOUBLE类型转换

    使用TO_CHAR函数将BOOLEAN、BIGINT、DECIMAL或DOUBLE类型值转换为对应的STRING类型。

    命令格式

    STRING TO_CHAR(BOOLEAN|BIGINT|DOUBLE|DECIMAL <value>)

-- 标准示例。
-- 返回123。
SELECT TO_CHAR(123);

    参数说明

    value：必填。BOOLEAN、BIGINT、DECIMAL或DOUBLE类型。

    返回值说明

    返回STRING类型。返回规则如下：

    • value非BOOLEAN、BIGINT、DECIMAL或DOUBLE类型时，返回报错。

    • value值为NULL时，返回NULL。

    使用示例

    基本示例

    • 示例1：将如下值转换为STRING类型。

      -- 返回123。
SELECT TO_CHAR(123);

    • 示例2：输入参数为NULL，返回值为NULL。

      -- 返回NULL。
SELECT TO_CHAR(NULL);

    日期类型转换

    使用TO_CHAR函数将时间日期数据按照指定格式及时区格式化为STRING字符串。

    命令格式

    当使用时间日期类型数据作为输入参数时，TO_CHAR函数支持以下两种签名格式，请根据不同使用需求选择不同的函数签名。

    • 签名1：将DATE或DATETIME类型日期值按照指定格式转换为STRING字符串。

      STRING TO_CHAR(DATE|DATETIME <date>, STRING <format>)

-- 标准示例。
-- 返回2025-03-05。
SELECT TO_CHAR(DATETIME '2025-03-05 14:30:00', 'yyyy-mm-dd');

    • 签名2：将TIMESTAMP或TIMESTAMP_NTZ类型时间按照指定时区及指定格式，转换为STRING字符串。

      STRING TO_CHAR(TIMESTAMP|TIMESTAMP_NTZ <date>, STRING <format>[, STRING <time_zone>])

-- 标准示例。
-- 返回2025-07-20 07:30:00。
SELECT TO_CHAR(TIMESTAMP '2025-07-20 07:30:00', '%Y-%m-%d %H:%M:%S');

    参数说明

    • date：必填。待格式化的日期值。支持DATE、DATETIME、TIMESTAMP或TIMESTAMP_NTZ类型。

      在MaxCompute1.0数据类型版本下，如果参数为STRING类型，格式符合DATETIME类型的格式，即yyyy-mm-dd hh:mi:ss，例如2025-07-21 00:00:00，则会隐式转换为DATETIME类型后参与运算。

    • format：必填。用于指定输出的字符串格式。STRING类型。format目前支持的日期和时间部分的格式元素如下：

      日期部分格式元素

      • %Y/yyyy/YYYY：以十进制数表示的年份和世纪。

      • %y：以十进制数（00~99）表示的年份（不带世纪）。

      • %m/mm/MM：以十进制数表示的月份（01~12）。

      • %B：完整的月份名称（英文），例如January。

      • %b/%h：月份名称（英文）的缩写，例如Jan。

      • %d/dd/DD：以十进制数表示的月份日期 (01~31)。

      • %e：以十进制数字（1~31）表示的月份中的第几天，例如2（其中dd将得到02）。

      • %F：相当于%Y-%m-%d（yyyy-mm-dd）。

      • %j：以十进制数表示的一年中的第几天（001~366），例如360。

      • %u：一周中的第几天（Monday=1），以十进制数（1~7）表示。

      • %A：完整的星期名称（英文），例如Wednesday。

      • %a：星期名称（英文）的缩写，例如Wed。

      时间部分格式元素

      • %p：AM/PM，即上午/下午。

      • %H/hh/HH：以十进制数（00~23）表示的小时（24 小时制）。

      • %I：以十进制数字（01~12）表示的小时（12小时制）。

      • %l：以十进制数字（1~12）表示的小时（12小时制）；无十位数时，个位数前面有空格。

      • %M/mi/MI：以十进制数（00~59）表示的分钟。

      • %S/ss/SS：以十进制数（00~60）表示的秒。

      • %X：相当于HH:MM:SS格式的时间。

      • %T：相当于%H:%M:%S（hh-mi-ss）。

      • ff3：毫秒，为三位十进制数（000~999），用于表示秒的小数部分。

      • %E<number>S：秒，小数精度为<number>位，例如用%E3S匹配00.123。

      • %E*S：有完整6位小数精度的秒，例如00.123456。

      • %Ez：表示数字时区（+HH:MM或-HH:MM）。

    • time_zone：可选。STRING类型。用于指定时区，详情请参见时区列表。

      若未指定时区：

      • 当date为TIMESTAMP类型时，默认为当前Session/Project时区。

      • 当date为TIMESTAMP_NTZ类型时，默认为UTC时区。

    返回值说明

    返回STRING类型。返回规则如下：

    • date非DATE、DATETIME、TIMESTAMP或TIMESTAMP_NTZ类型时，返回报错。

    • date值为NULL时，返回报错。

    • format值为NULL时，返回NULL。

    使用示例

    基本示例

    • 示例1：入参为DATE或DATETIME类型。

      -- 返回今天是2023-12-25。
SELECT TO_CHAR(DATE "2023-12-25", "今天是yyyy-mm-dd");

-- 返回今天是20231225。
SELECT TO_CHAR(DATE "2023-12-25", "今天是%Y%m%d");

-- 返回今天是231225Monday。
SELECT TO_CHAR(DATE "2023-12-25", "今天是%y%m%d%A");

-- 返回今天是 12月25日。
SELECT TO_CHAR(DATE "2023-12-25", "今天是 MM月DD日");

-- 返回阿里金融2010-12*03。
SELECT TO_CHAR(DATETIME '2010-12-03 00:00:00','阿里金融yyyy-mm*dd');

-- 返回时间是15:30:00。
SELECT TO_CHAR(DATETIME '2025-07-18 15:30:00','时间是%X');

-- 返回现在是 3:30:00 PM。
SELECT TO_CHAR(DATETIME '2025-07-18 15:30:00','现在是%l:%M:%S %p');

-- 返回小时部分是03。
SELECT TO_CHAR(DATETIME '2025-07-18 15:30:00','小时部分是%I');

-- 返回25年的第189天，July(Jul|Jul)月，08(8)日,Tuesday(Tue)，15:30:00 PM。
SELECT TO_CHAR(DATETIME '2025-07-08 15:30:00','%y年的第%j天，%B(%b|%h)月，dd(%e)日,%A(%a)，%T %p');

-- 返回日期为2025-07-08是一周的第2天。
SELECT TO_CHAR(DATETIME '2025-07-08 15:30:00','日期为%F是一周的第%u天');

-- 返回NULL。
SELECT TO_CHAR(DATE "2023-12-25", NULL);

    • 示例2：入参为STRING类型。

      对于MaxCompute 1.0数据类型版本，若date参数为STRING类型，且格式符合DATETIME类型的格式yyyy-mm-dd hh:mi:ss，则会隐式转换为DATETIME类型后参与运算。

      -- 设置数据类型版本为1.0。
SET odps.sql.type.system.odps2=false;
SET odps.sql.hive.compatible=false;

-- 输入参数为STRING类型，且符合DATETIME类型格式。
-- 返回20250718。
SELECT TO_CHAR('2025-07-18 00:00:00', 'yyyymmdd');

    • 示例3：入参为TIMESTAMP类型。

      当参数是TIMESTAMP类型时，支持指定时区。若未指定时区，则默认为当前Session/Project时区。

      -- 当前Project时区为Asia/Shanghai。
SET odps.sql.timezone=Asia/Shanghai;

-- 返回2025-07-20 07:30:00.123456。
SELECT TO_CHAR(TIMESTAMP "2025-07-20 07:30:00.123456", "%Y-%m-%d %H:%M:%E*S");

-- 返回2025-07-20 07:30:00+08:00。
SELECT TO_CHAR(TIMESTAMP "2025-07-20 07:30:00", "%Y-%m-%d %H:%M:%S%Ez");

-- 返回2025-07-20 07:30:00。
SELECT TO_CHAR(TIMESTAMP "2025-07-20 07:30:00", "%Y-%m-%d %H:%M:%S", "Asia/Shanghai");
 
-- 返回20250720 06:30:00。
SELECT TO_CHAR(TIMESTAMP "2025-07-20 07:30:00", "yyyymmdd hh:mi:ss", "Asia/Bangkok");

-- 返回2025-07-20 09:30:00.123。
SELECT TO_CHAR(TIMESTAMP "2025-07-20 07:30:00.123456789", "%Y-%m-%d %H:%M:%S.ff3", "Australia/Sydney");

-- 返回2025-07-19 23:30:00。
SELECT TO_CHAR(TIMESTAMP "2025-07-20 07:30:00.123456", "%Y-%m-%d %H:%M:%S", "Etc/GMT");

-- 返回2025-07-19 23:30:00Saturday。
SELECT TO_CHAR(TIMESTAMP "2025-07-20 07:30:00.123456", "%Y-%m-%d %H:%M:%S%A", "Etc/GMT");

-- 返回NULL。
SELECT TO_CHAR(TIMESTAMP "2025-07-20 07:30:00.123456", NULL, "Etc/GMT");

    • 示例4：入参为TIMESTAMP_NTZ类型。

      当参数是TIMESTAMP_NTZ类型时，支持指定时区。若未指定时区，TIMESTAMP_NTZ类型数据本身不包含时区信息，代表基于统一UTC时间基准。

      -- 返回日期时间是2025-07-20 07:30:00.123456。
SELECT TO_CHAR(TIMESTAMP_NTZ "2025-07-20 07:30:00.123456" ,"日期时间是%Y-%m-%d %H:%M:%E6S");

-- 返回2025-07-20 07:30:00。
SELECT TO_CHAR(TIMESTAMP_NTZ "2025-07-20 07:30:00", "%Y-%m-%d %H:%M:%S"，"Etc/GMT");

-- 返回2025-07-20 Sunday 15:30:00。
SELECT TO_CHAR(TIMESTAMP_NTZ "2025-07-20 07:30:00", "yyyy-mm-dd %A hh:mi:ss", "Asia/Shanghai");
-
-- 返回2025-07-20 14:30:00毫秒部分为123。
SELECT TO_CHAR(TIMESTAMP_NTZ "2025-07-20 07:30:00.123456789", "yyyy-mm-dd hh:mi:ss毫秒部分为ff3", "Asia/Bangkok");

-- 返回NULL。
SELECT TO_CHAR(TIMESTAMP_NTZ "2025-07-20 07:30:00",  NULL);

    相关函数

    TO_CHAR函数属于日期函数或字符串函数。

    • 更多日期计算、日期转换的相关函数请参见日期函数。

    • 更多查找字符串、转换字符串格式的相关函数请参见字符串函数。