格式化函数

format()
仅限 Cypher 25引入于 Neo4j 2025.09

format() 函数用于创建时间实例和持续时间类型的动态格式化字符串表示形式。

详细信息

语法

format(value[, pattern])

描述

返回 ISO 格式的 STRING 或按提供的模式格式化的 STRING 形式的时间值。

参数

名称

类型

描述

值

DATE（日期） | LOCAL TIME（本地时间） | ZONED TIME（带时区时间） | LOCAL DATETIME（本地日期时间） | ZONED DATETIME（带时区日期时间） | DURATION（持续时间）

需要格式化的时间值。

pattern

STRING

用于格式化时间值的模式。如果未提供模式，则在大多数情况下，该值将根据 ISO 8601 进行格式化。

返回

STRING
注意事项

输出格式可以通过 pattern 参数进行自定义。

pattern 参数遵循 Java DateTimeFormatter 的规范。

如果未指定模式，该函数将返回一个 ISO 格式的字符串，但有部分例外情况（Cypher® 的实现比 ISO 8601 更宽松），例如在使用带有时区的秒时。

大多数字符在重复时会产生不同的输出。

某些字符不能应用于特定类型，例如 u 不能用于构造 LOCAL TIME 的字符串，因为它表示年份，而不属于时间值的一部分。

除 [、]、{、}、# 和 ' 以外的任何非保留字符都会直接输出。为确保未来兼容性，建议将所有想要直接输出的字符用单引号括起来。

实例类型

Cypher 的实例类型包括 DATE、LOCAL TIME、ZONED TIME、LOCAL DATETIME 和 ZONED DATETIME。更多信息，请参阅 值和类型 → 时间瞬间。

使用 字符串模式字符 中的字符来为实例类型创建字符串模式。

示例

示例 1. 实例格式化，美式和欧式日期
查询
WITH datetime('1986-11-18T6:04:45.123456789+01:00[Europe/Berlin]') AS dt
RETURN format(dt, "MM/dd/yyyy") AS US, format(dt, "dd/MM/yyyy") AS EU
结果
美国格式 欧洲格式

"11/18/1986"

"18/11/1986"

行：1
示例 2. 带有星期几、月份、日期、纪元和年份的实例格式化
查询
WITH datetime('1986-11-18T6:04:45.123456789+01:00[Europe/Berlin]') AS dt
RETURN format(dt, "EEEE, MMMM d, G uuuu") AS instanceString
结果
instanceString

"Tuesday, November 18, AD 1986"

行：1

四个 E 和 M（文本表示形式）会输出星期和月份的全称。

示例 3. 带有年内日期和本地化星期几的实例格式化
查询
WITH datetime('1986-11-18T6:04:45.123456789+01:00[Europe/Berlin]') AS dt
RETURN format(dt, "DDD'nd day of the year,' c'rd day of the week'") AS instanceString
结果
instanceString

"322nd day of the year, 3rd day of the week"

行：1
示例 4. 带有 12/24 小时制小时、分钟和时区名称的实例格式化
查询
WITH datetime('1986-11-18T6:04:45.123456789+01:00[Europe/Berlin]') AS dt
RETURN format(dt, "k:mm z") AS CET, format(dt, "K:mm O") AS GMT
结果
中欧时间 (CET) 格林威治标准时间 (GMT)

"6:04 CET"

"6:04 GMT+1"

行：1
示例 5. 带有月份、日期、日内毫秒、分钟和秒的实例格式化
查询
WITH datetime('1986-11-18T6:04:45.123456789+01:00[Europe/Berlin]') AS dt
RETURN format(dt, "LLL d,' minute 'm', second 's', millisecond of the day 'A") AS instanceString
结果
instanceString

"Nov 18, minute 4, second 45, millisecond of the day 21885123"

行：1

三个 L（数字/文本表示形式）会输出简写形式（"Nov"）。

示例 6. 带有补齐和周基年份的实例格式化
查询
WITH datetime('1986-11-18T6:04:45.123456789+01:00[Europe/Berlin]') AS dt
RETURN format(dt, "pppYY") AS instanceString
结果
instanceString

" 86"

行：1

三个 p 字符为两个 Y 字符输出的两位数字形式添加了一个空格字符作为填充。

字符串模式字符

实例类型字符串模式的允许字符
字符 含义 呈现形式 示例

G

纪元

文本 (text)

AD; Anno Domini; A

u

year

year

2004; 04

y

纪元年

year

2004; 04

D

年内日期

数量 (number)

189

M / L

月份

数字/文本

7; 07; Jul; July; J

d

日期

数量 (number)

10

g

修正儒略日

数量 (number)

2451334

Q / q

季度

数字/文本

3; 03; Q3; 3rd quarter

Y

周基年份

year

1996; 96

w

周基年份的周

数量 (number)

27

W

月内的周

数量 (number)

4

E

星期几

文本 (text)

Tue; Tuesday; T

e / c

本地化星期几

数字/文本

2; 02; Tue; Tuesday; T

F

月内对齐周

数量 (number)

3

a

上午/下午

文本 (text)

PM

B

日内时段

文本 (text)

在上午

h

12小时制小时 (1-12)

数量 (number)

12

K

12小时制小时 (0-11)

数量 (number)

0

k

24小时制小时 (1-24)

数量 (number)

24

H

24小时制小时 (0-23)

数量 (number)

0

m

分钟

数量 (number)

30

s

秒

数量 (number)

55

S

秒的分数

分数

978

A

日内毫秒

数量 (number)

1234

n

秒内纳秒

数量 (number)

987654321

N

日内纳秒

数量 (number)

1234000000

V

时区 ID

时区 ID

America/Los_Angeles; Z; -08:30

v

通用时区名称

时区名称

Pacific Time; PT

z

时区名称

时区名称

Pacific Standard Time; PST

O

本地化时区偏移

偏移量 O

GMT+8; GMT+08:00; UTC-08:00

X

时区偏移（'Z' 代表零）

偏移量 X

Z; -08; -0830; -08:30; -083015; -08:30:15

x

时区偏移

偏移量 x

+0000; -08; -0830; -08:30; -083015; -08:30:15

Z

时区偏移

偏移量 Z

+0000; -0800; -08:00

p

后续补齐

补齐修饰符

1

"

文本转义

delimiter

'

单引号

字面值

持续时间类型

使用 字符串模式字符 中的字符来为持续时间类型创建字符串模式。

Cypher 的 DURATION 类型具有组件和组件组。更多信息，请参阅 值和类型 → 持续时间组件。

如果字符串模式包含某个组件组的字符，但不包含表示同一组中更长时间单位的字符，format() 会将较长的时间单位转换为所含字符表示的等效持续时间。例如，如果模式中存在 q（季度）但缺少 y（年），则 1 年会被转换为 4 个季度。这是因为如果没有参考点，就无法确定持续时间的具体细节。

示例

示例 7. 持续时间格式化，年份转换为季度
查询
WITH duration({years: 1, months: 4}) AS d
RETURN format(d, "y 'years' q 'quarters' M 'months'") AS withYears, format(d, "q 'quarters' M 'months'") AS withoutYears
结果
withYears withoutYears

"1 years 1 quarters 1 months"

"5 quarters 1 months"

行：1
示例 8. 持续时间格式化，周转换为天
查询
WITH duration({weeks: 3, days: 4}) AS d
RETURN format(d, "w 'weeks' d 'days'") AS withWeeks, format(d, "d 'days'") AS withoutWeeks
结果
withWeeks withoutWeeks

"3 weeks 4 days"

"25 days"

行：1
示例 9. 持续时间格式化，小时转换为分钟
查询
WITH duration({days: 4, hours: 5, minutes: 6, seconds: 7}) AS d
RETURN format(d, "h 'hours' m 'minutes'") AS withHours, format(d, "m 'minutes'") AS withoutHours
结果
withHours withoutHours

"5 hours 6 minutes"

"306 minutes"

行：1

注意 4 天是如何无法转换为小时或分钟且不影响查询结果的。天与小时和分钟属于不同的组件组，请参阅 持续时间类型字符串模式的允许字符。

字符串模式字符

持续时间类型字符串模式的允许字符
组件组 字符 呈现形式

月份

y / Y/ u

years

q / Q

季度

M / L

月份

天

w / W

周

d / D

天

秒

h / H / k / K

小时

m

分钟

s

秒

n / S

秒的分数

A

milliseconds

N

nanoseconds