2024 年 9 月 26 日: PostgreSQL 17 发布!
支持的版本:当前 (17) / 16 / 15 / 14 / 13 / 12
开发版本:devel
不支持的版本:11 / 10 / 9.6 / 9.5 / 9.4 / 9.3 / 9.2 / 9.1 / 9.0 / 8.4 / 8.3 / 8.2 / 8.1 / 8.0 / 7.4 / 7.3 / 7.2 / 7.1

9.8. 数据类型格式化函数 #

PostgreSQL 格式化函数提供了一套强大的工具,用于将各种数据类型(日期/时间、整数、浮点数、数值)转换为格式化的字符串,以及从格式化的字符串转换为特定数据类型。 表 9.26 列出了它们。这些函数都遵循一个通用的调用约定:第一个参数是要格式化的值,第二个参数是一个模板,定义了输出或输入格式。

表 9.26. 格式化函数

函数

描述

示例

to_char ( timestamp, text ) → text

to_char ( timestamp with time zone, text ) → text

根据给定的格式将时间戳转换为字符串。

to_char(timestamp '2002-04-20 17:31:12.66', 'HH12:MI:SS')05:31:12

to_char ( interval, text ) → text

根据给定的格式将间隔转换为字符串。

to_char(interval '15h 2m 12s', 'HH24:MI:SS')15:02:12

to_char ( numeric_type, text ) → text

根据给定的格式将数字转换为字符串;适用于 integerbigintnumericrealdouble precision

to_char(125, '999')125

to_char(125.8::real, '999D9')125.8

to_char(-125.8, '999D99S')125.80-

to_date ( text, text ) → date

根据给定的格式将字符串转换为日期。

to_date('05 Dec 2000', 'DD Mon YYYY')2000-12-05

to_number ( text, text ) → numeric

根据给定的格式将字符串转换为数值。

to_number('12,454.8-', '99G999D9S')-12454.8

to_timestamp ( text, text ) → timestamp with time zone

根据给定的格式将字符串转换为时间戳。 (另见 表 9.33 中的 to_timestamp(double precision)。)

to_timestamp('05 Dec 2000', 'DD Mon YYYY')2000-12-05 00:00:00-05


提示

to_timestampto_date 用于处理无法通过简单强制转换进行转换的输入格式。 对于大多数标准日期/时间格式,只需将源字符串强制转换为所需数据类型即可,这更容易。 同样,对于标准数字表示,to_number 是不必要的。

to_char 输出模板字符串中,有一些模式会被识别并根据给定的值替换为格式正确的 data。 任何不是模板模式的文本都会被原样复制。 同样,在输入模板字符串(用于其他函数)中,模板模式标识由输入 data 字符串提供的 value。 如果模板字符串中存在不是模板模式的字符,则输入 data 字符串中的对应字符会被简单地跳过(无论它们是否等于模板字符串字符)。

表 9.27 显示了用于格式化日期和时间值的模板模式。

表 9.27. 日期/时间格式化模板模式

模式 描述
HH 一天中的小时(01–12)
HH12 一天中的小时(01–12)
HH24 一天中的小时(00–23)
MI 分钟(00–59)
SS 秒(00–59)
MS 毫秒(000–999)
US 微秒(000000–999999)
FF1 十分之一秒(0–9)
FF2 百分之一秒(00–99)
FF3 毫秒(000–999)
FF4 十分之一毫秒(0000–9999)
FF5 百分之一毫秒(00000–99999)
FF6 微秒(000000–999999)
SSSS, SSSSS 午夜后的秒数(0–86399)
AM, am, PM or pm 午夜/下午指示器(无句点)
A.M., a.m., P.M. or p.m. 午夜/下午指示器(有句点)
Y,YYY 年份(4 位或更多位)带逗号
YYYY 年份(4 位或更多位)
YYY 年份的后 3 位数字
YY 年份的后 2 位数字
Y 年份的后 1 位数字
IYYY ISO 8601 周编号年份(4 位或更多位)
IYY ISO 8601 周编号年份的后 3 位数字
IY ISO 8601 周编号年份的后 2 位数字
I ISO 8601 周编号年份的后 1 位数字
BC, bc, AD or ad 纪元指示器(无句点)
B.C., b.c., A.D. or a.d. 纪元指示器(有句点)
MONTH 完整大写月份名称(用空格填充到 9 个字符)
Month 完整首字母大写月份名称(用空格填充到 9 个字符)
month 完整小写月份名称(用空格填充到 9 个字符)
MON 缩写大写月份名称(英语中为 3 个字符,本地化长度会有所不同)
Mon 缩写首字母大写月份名称(英语中为 3 个字符,本地化长度会有所不同)
mon 缩写小写月份名称(英语中为 3 个字符,本地化长度会有所不同)
MM 月份数字(01–12)
DAY 完整大写星期名称(用空格填充到 9 个字符)
Day 完整首字母大写星期名称(用空格填充到 9 个字符)
day 完整小写星期名称(用空格填充到 9 个字符)
DY 缩写大写星期名称(英语中为 3 个字符,本地化长度会有所不同)
Dy 缩写首字母大写星期名称(英语中为 3 个字符,本地化长度会有所不同)
dy 缩写小写星期名称(英语中为 3 个字符,本地化长度会有所不同)
DDD 一年中的第几天(001–366)
IDDD ISO 8601 周编号年份中的第几天(001–371;一年的第 1 天是第一周的星期一)
DD 一个月中的第几天(01–31)
D 一周中的第几天,星期日(1)到星期六(7
ID ISO 8601 一周中的第几天,星期一(1)到星期日(7
W 一个月中的第几周(1–5)(第一周从一个月的第一天开始)
WW 一年中的第几周(1–53)(第一周从一年的第一天开始)
IW ISO 8601 周编号年份中的第几周(01–53;一年的第一个星期四在第 1 周)
CC 世纪(2 位数字)(21 世纪从 2001-01-01 开始)
J 儒略日(自公元前 4714 年 11 月 24 日当地午夜以来的整数天数;参见 附录 B.7
Q 季度
RM 大写罗马数字中的月份(I–XII;I=一月)
rm 小写罗马数字中的月份(i–xii;i=一月)
TZ 大写时区缩写
tz 小写时区缩写
TZH 时区小时
TZM 时区分钟
OF 相对于 UTC 的时区偏移量(HHHH:MM

修饰符可以应用于任何模板模式以更改其行为。例如,FMMonth 是使用 FM 修饰符的 Month 模式。表 9.28 显示了用于日期/时间格式的修饰符模式。

表 9.28. 用于日期/时间格式的模板模式修饰符

修饰符 描述 示例
FM 前缀 填充模式(抑制前导零和填充空格) FMMonth
TH 后缀 大写序数后缀 DDTH,例如,12TH
th 后缀 小写序数后缀 DDth,例如,12th
FX 前缀 固定格式全局选项(参见使用说明) FX Month DD Day
TM 前缀 翻译模式(使用基于 lc_time 的本地化星期几和月份名称) TMMonth
SP 后缀 拼写模式(未实现) DDSP

日期/时间格式的使用说明

  • FM 会抑制前导零和尾随空格,否则这些零和空格将被添加到模式输出中以使其宽度固定。在 PostgreSQL 中,FM 只修改下一个规范,而在 Oracle 中,FM 会影响所有后续规范,重复的 FM 修饰符会切换填充模式的开启和关闭。

  • TM 会抑制尾随空格,无论是否指定了 FM

  • to_timestampto_date 会忽略输入中的字母大小写;因此,例如 MONMonmon 都接受相同的字符串。使用 TM 修饰符时,大小写折叠将根据函数输入排序规则的规则执行(参见 第 23.2 节)。

  • to_timestampto_date 会跳过输入字符串开头和日期和时间值周围的多个空格,除非使用 FX 选项。例如,to_timestamp(' 2000    JUN', 'YYYY MON')to_timestamp('2000 - JUN', 'YYYY-MON') 可以正常工作,但 to_timestamp('2000    JUN', 'FXYYYY MON') 会返回错误,因为 to_timestamp 只期望一个空格。FX 必须作为模板中的第一个项目指定。

  • to_timestampto_date 的模板字符串中,分隔符(空格或非字母/非数字字符)会匹配输入字符串中的任何单个分隔符或被跳过,除非使用 FX 选项。例如,to_timestamp('2000JUN', 'YYYY///MON')to_timestamp('2000/JUN', 'YYYY MON') 可以正常工作,但 to_timestamp('2000//JUN', 'YYYY/MON') 会返回错误,因为输入字符串中的分隔符数量超过了模板中的分隔符数量。

    如果指定了 FX,则模板字符串中的分隔符会精确匹配输入字符串中的一个字符。但请注意,输入字符串字符不必与模板字符串中的分隔符相同。例如,to_timestamp('2000/JUN', 'FXYYYY MON') 可以正常工作,但 to_timestamp('2000/JUN', 'FXYYYY  MON') 会返回错误,因为模板字符串中的第二个空格会消耗输入字符串中的字母 J

  • TZH 模板模式可以匹配带符号的数字。如果没有 FX 选项,减号可能会出现歧义,并且可能被解释为分隔符。该歧义将按如下方式解决:如果模板字符串中 TZH 之前的分隔符数量少于输入字符串中减号之前的分隔符数量,则减号将被解释为 TZH 的一部分。否则,减号将被视为值之间的分隔符。例如,to_timestamp('2000 -10', 'YYYY TZH')-10TZH 匹配,但 to_timestamp('2000 -10', 'YYYY  TZH')10TZH 匹配。

  • 普通文本允许在 to_char 模板中,并将按字面意义输出。您可以将子字符串放在双引号中以强制将其解释为字面文本,即使它包含模板模式。例如,在 '"Hello Year "YYYY' 中,YYYY 将被年份数据替换,但 Year 中的单个 Y 不会被替换。在 to_dateto_numberto_timestamp 中,字面文本和双引号字符串会导致跳过字符串中包含的字符数量;例如,"XX" 会跳过两个输入字符(无论它们是否为 XX)。

    提示

    PostgreSQL 12 之前,可以使用非字母或非数字字符跳过输入字符串中的任意文本。例如,to_timestamp('2000y6m1d', 'yyyy-MM-DD') 曾经可以正常工作。现在,您只能使用字母字符来实现此目的。例如,to_timestamp('2000y6m1d', 'yyyytMMtDDt')to_timestamp('2000y6m1d', 'yyyy"y"MM"m"DD"d"') 会跳过 ymd

  • 如果要在输出中包含双引号,则必须在它之前添加一个反斜杠,例如 '\"YYYY Month\"'。反斜杠在双引号字符串之外没有其他特殊含义。在双引号字符串中,反斜杠会导致下一个字符按字面意义处理,无论它是什么(但这只有在下一个字符是双引号或另一个反斜杠时才会产生特殊效果)。

  • to_timestampto_date 中,如果年份格式规范少于四位数字,例如 YYY,并且提供的年份少于四位数字,则年份将被调整为最接近 2020 年的年份,例如,95 将变为 1995。

  • to_timestampto_date 中,负年份被视为表示公元前。如果同时写入负年份和明确的 BC 字段,则您将再次获得公元。输入的年份零被视为公元前 1 年。

  • to_timestampto_date 中,YYYY 转换在处理超过 4 位数字的年份时存在限制。您必须在 YYYY 之后使用某些非数字字符或模板,否则年份始终被解释为 4 位数字。例如(年份为 20000):to_date('200001130', 'YYYYMMDD') 将被解释为 4 位数字的年份;请改用年份后面的非数字分隔符,例如 to_date('20000-1130', 'YYYY-MMDD')to_date('20000Nov30', 'YYYYMonDD')

  • to_timestampto_date 中,如果存在 YYYYYYYY,YYY 字段,则 CC(世纪)字段会被接受,但会被忽略。如果 CCYYY 一起使用,则结果将被计算为指定世纪中的该年。如果指定了世纪但没有指定年份,则将假设世纪的第一年。

  • to_timestampto_date 中,星期几名称或数字(DAYD 和相关字段类型)会被接受,但会被忽略,因为它们不参与计算结果。季度 (Q) 字段也是如此。

  • to_timestampto_date 中,ISO 8601 星期编号日期(与格里高利日期不同)可以通过两种方式之一指定

    • 年份、星期编号和星期几:例如,to_date('2006-42-4', 'IYYY-IW-ID') 返回日期 2006-10-19。如果省略星期几,则假定为 1(星期一)。

    • 年份和一年中的天数:例如,to_date('2006-291', 'IYYY-IDDD') 也返回 2006-10-19

    尝试使用 ISO 8601 星期编号字段和格里高利日期字段的混合来输入日期是毫无意义的,并且会导致错误。在 ISO 8601 星期编号年的上下文中,“月份”或“一个月中的天数”的概念没有意义。在格里高利年的上下文中,ISO 星期没有意义。

    注意事项

    虽然 to_date 会拒绝格里高利和 ISO 星期编号日期字段的混合,但 to_char 不会,因为像 YYYY-MM-DD (IYYY-IDDD) 这样的输出格式规范可能很有用。但是,请避免编写类似 IYYY-MM-DD 的内容;这会在年初产生令人惊讶的结果。(参见 第 9.9.1 节 以获取更多信息。)

  • to_timestamp 中,毫秒 (MS) 或微秒 (US) 字段用作小数点后的秒数位。例如,to_timestamp('12.3', 'SS.MS') 不是 3 毫秒,而是 300,因为转换将其视为 12 + 0.3 秒。因此,对于格式 SS.MS,输入值 12.312.3012.300 指定相同的毫秒数。要获得 3 毫秒,必须写入 12.003,转换将其视为 12 + 0.003 = 12.003 秒。

    以下是一个更复杂的示例:to_timestamp('15:12:02.020.001230', 'HH24:MI:SS.MS.US') 是 15 小时、12 分钟和 2 秒 + 20 毫秒 + 1230 微秒 = 2.021230 秒。

  • to_char(..., 'ID') 的星期几编号与 extract(isodow from ...) 函数匹配,但 to_char(..., 'D') 的编号与 extract(dow from ...) 的天数编号不匹配。

  • to_char(interval)HHHH12 格式化为 12 小时时钟上的显示,例如 0 小时和 36 小时都输出为 12,而 HH24 输出完整的小时值,该值在 interval 值中可能会超过 23。

表 9.29 显示了可用于格式化数字值的模板模式。

表 9.29. 用于数字格式的模板模式

模式 描述
9 数字位置(如果无关紧要,可以省略)
0 数字位置(即使无关紧要,也不会省略)
.(句号) 小数点
,(逗号) 组(千位)分隔符
PR 负值在尖括号中
S 符号锚定到数字(使用区域设置)
L 货币符号(使用区域设置)
D 小数点(使用区域设置)
G 组分隔符(使用区域设置)
MI 减号位于指定位置(如果数字 < 0)
PL 加号位于指定位置(如果数字 > 0)
SG 加/减号位于指定位置
RN 罗马数字(输入介于 1 和 3999 之间)
THth 序数后缀
V 移位指定数量的数字(参见说明)
EEEE 科学记数法的指数

数字格式的使用说明

  • 0 指定一个数字位置,该位置将始终被打印,即使它包含前导/尾随零。9 也指定一个数字位置,但如果它是前导零,则它将被空格替换,而如果它是尾随零并且指定了填充模式,则它将被删除。(对于 to_number(),这两个模式字符等效。)

  • 如果格式提供的分数位数少于要格式化的数字,则 to_char() 会将数字四舍五入到指定的位数。

  • 模式字符 SLDG 分别代表当前语言环境定义的符号、货币符号、小数点和千位分隔符(参见 lc_monetarylc_numeric)。模式字符句点和逗号分别代表这些确切的字符,具有小数点和千位分隔符的含义,与语言环境无关。

  • 如果 to_char() 的模式中没有明确规定符号,则会为符号保留一列,并且该符号将锚定到(出现在数字的左侧)。如果 S 出现在一些 9 的左侧,它也将锚定到数字。

  • 使用 SGPLMI 格式化的符号不会锚定到数字;例如,to_char(-12, 'MI9999') 生成 '-  12'to_char(-12, 'S9999') 生成 '  -12'。(Oracle 实现不允许在 9 之前使用 MI,而是要求 9 位于 MI 之前。)

  • TH 不会转换小于零的值,也不会转换分数。

  • PLSGTHPostgreSQL 扩展。

  • to_number 中,如果使用非数据模板模式(如 LTH),则会跳过相应数量的输入字符,无论它们是否与模板模式匹配,除非它们是数据字符(即数字、符号、小数点或逗号)。例如,TH 会跳过两个非数据字符。

  • Vto_char 一起使用时会将输入值乘以 10^n,其中 nV 后面的位数。Vto_number 一起使用时会以类似的方式进行除法。 to_charto_number 不支持将 V 与小数点结合使用(例如,99.9V99 不允许)。

  • EEEE(科学记数法)不能与除数字和小数点模式之外的任何其他格式模式或修饰符结合使用,并且必须位于格式字符串的末尾(例如,9.99EEEE 是一个有效的模式)。

某些修饰符可以应用于任何模板模式以更改其行为。例如,FM99.99 是带有 FM 修饰符的 99.99 模式。表 9.30 显示了用于数字格式化的修饰符模式。

表 9.30. 用于数字格式化的模板模式修饰符

修饰符 描述 示例
FM 前缀 填充模式(抑制尾随零和填充空格) FM99.99
TH 后缀 大写序数后缀 999TH
th 后缀 小写序数后缀 999th

表 9.31 显示了 to_char 函数使用的一些示例。

表 9.31. to_char 示例

表达式 结果
to_char(current_timestamp, 'Day, DD  HH12:MI:SS') 'Tuesday  , 06  05:39:18'
to_char(current_timestamp, 'FMDay, FMDD  HH12:MI:SS') 'Tuesday, 6  05:39:18'
to_char(current_timestamp AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z"') '2022-12-06T05:39:18Z', ISO8601 扩展格式
to_char(-0.1, '99.99') '  -.10'
to_char(-0.1, 'FM9.99') '-.1'
to_char(-0.1, 'FM90.99') '-0.1'
to_char(0.1, '0.9') ' 0.1'
to_char(12, '9990999.9') '    0012.0'
to_char(12, 'FM9990999.9') '0012.'
to_char(485, '999') ' 485'
to_char(-485, '999') '-485'
to_char(485, '9 9 9') ' 4 8 5'
to_char(1485, '9,999') ' 1,485'
to_char(1485, '9G999') ' 1 485'
to_char(148.5, '999.999') ' 148.500'
to_char(148.5, 'FM999.999') '148.5'
to_char(148.5, 'FM999.990') '148.500'
to_char(148.5, '999D999') ' 148,500'
to_char(3148.5, '9G999D999') ' 3 148,500'
to_char(-485, '999S') '485-'
to_char(-485, '999MI') '485-'
to_char(485, '999MI') '485 '
to_char(485, 'FM999MI') '485'
to_char(485, 'PL999') '+485'
to_char(485, 'SG999') '+485'
to_char(-485, 'SG999') '-485'
to_char(-485, '9SG99') '4-85'
to_char(-485, '999PR') '<485>'
to_char(485, 'L999') 'DM 485'
to_char(485, 'RN') '        CDLXXXV'
to_char(485, 'FMRN') 'CDLXXXV'
to_char(5.2, 'FMRN') 'V'
to_char(482, '999th') ' 482nd'
to_char(485, '"Good number:"999') 'Good number: 485'
to_char(485.8, '"Pre:"999" Post:" .999') 'Pre: 485 Post: .800'
to_char(12, '99V999') ' 12000'
to_char(12.4, '99V999') ' 12400'
to_char(12.45, '99V9') ' 125'
to_char(0.0004859, '9.99EEEE') ' 4.86e-04'

提交更正

如果您在文档中发现任何不正确的内容、与您对特定功能的体验不符或需要进一步澄清的内容,请使用 此表单 报告文档问题。