字符串函数

字符串函数仅对字符串表达式执行操作，如果用于任何其他类型的值，将返回错误。该规则的一个例外是 toString()，它还接受数字、布尔值和时间值（即 DATE、ZONED TIME、LOCAL TIME、ZONED DATETIME、LOCAL DATETIME 或 DURATION 值）。

以 STRING 作为输入的函数全都基于Unicode 字符进行操作，而不是基于标准的 char[]。例如，对任何Unicode 字符应用 size() 函数都将返回 1，即使该字符无法容纳在一个 char 的 16 位空间中。

当 toString() 应用于时间值时，它会返回一个适合由相应的时间函数进行解析的 STRING 表示。因此，该 STRING 将根据 ISO 8601 格式进行格式化。

另请参阅字符串连接运算符。

btrim()

详细信息
语法	`btrim(input[, trimCharacterString])`
描述	返回移除前导和尾随空白字符后的给定 `STRING`，也可以指定要移除的 `trimCharacterString`。
参数	名称	类型	描述
	`input`	`STRING`	将移除其前导和尾随修剪字符的值。
	`trimCharacterString`	`STRING`	要从给定字符串的开头和结尾移除的字符。
返回	`STRING`

注意事项
`btrim(null)` 返回 `null`。
`btrim(null, null)` 返回 `null`。
`btrim("hello", null)` 返回 `null`。
`btrim(null, ' ')` 返回 `null`。
如果未指定 `trimCharacterString`，则将移除所有前导和尾随的空白字符。

示例 1. btrim()

查询

RETURN btrim('   hello    '), btrim('xxyyhelloxyxy', 'xy')

结果
btrim(' hello')	btrim('xxyyhelloxyxy', 'xy')
`"hello"`	`"hello"`
行：1

left()

详细信息
语法	`left(original, length)`
描述	返回一个包含给定 `STRING` 中最左侧指定数量（`INTEGER`）字符的 `STRING`。
参数	名称	类型	描述
	`original`	`STRING`	要对其最右侧字符进行修剪的字符串值。
	`length`	`INTEGER（整数）`	要返回的最左侧字符的长度。
返回	`STRING`

注意事项
`left(null, length)` 返回 `null`。
`left(null, null)` 返回 `null`。
`left(original, null)` 将引发错误。
如果 `length` 不是正 `INTEGER`，则会引发错误。
如果 `length` 超过 `original` 的长度，则返回 `original`。

示例 2. left()

查询

RETURN left('hello', 3)

结果
left('hello', 3)
`"hel"`
行：1

lower()

详细信息
语法	`lower(input)`
描述	返回转换为小写的给定 `STRING`。
参数	名称	类型	描述
	`input`	`STRING`	要转换为小写的字符串。
返回	`STRING`

此函数是 toLower() 函数的别名，它是作为 Cypher® GQL 一致性的一部分引入的。

注意事项
`lower(null)` 返回 `null`。

示例 3. lower()

查询

RETURN lower('HELLO')

结果
lower('HELLO')
`"hello"`
行：1

ltrim()

详细信息
语法	`ltrim(input[, trimCharacterString])`
描述	返回移除前导空白字符后的给定 `STRING`，也可以指定要移除的 `trimCharacterString`。
参数	名称	类型	描述
	`input`	`STRING`	将移除其前导修剪字符的值。
	`trimCharacterString`	`STRING`	要从给定字符串开头移除的字符。
返回	`STRING`

注意事项
`ltrim(null)` 返回 `null`。
`ltrim(null, null)` 返回 `null`。
`ltrim("hello", null)` 返回 `null`。
`ltrim(null, ' ')` 返回 `null`。
如果未指定 `trimCharacterString`，则将移除所有前导空白字符。

示例 4. ltrim()

查询

RETURN ltrim('   hello'), ltrim('xxyyhelloxyxy', 'xy')

结果
ltrim(' hello')	ltrim('xxyyhelloxyxy', 'xy')
`"hello"`	`"helloxyxy"`
行：1

normalize()

详细信息
语法	`normalize(input[, normalForm])`
描述	规范化 `STRING`，可以选择指定规范化形式。
参数	名称	类型	描述
	`input`	`STRING`	要规范化的值。
	`normalForm`	`[NFC, NFD, NFKC, NFKD]`	指定任何规范形式（NFC、NFD、NFKC 或 NFKD）的关键字。
返回	`STRING`

Unicode 规范化是将同一字符串的不同表示形式转换为标准化形式的过程。有关更多信息，请参阅 Unicode 规范化形式的文档。

normalize() 函数对于将 STRING 值转换为可比较的形式非常有用。比较两个 STRING 值时，比较的是它们的 Unicode 码点。在 Unicode 中，外观相同的字符可能由两个或多个不同的码点表示。例如，字符 < 可以表示为 \uFE64 (﹤) 或 \u003C (<)。对于人眼来说，这些字符看起来是一样的。但是，如果进行比较，Cypher 将返回 false，因为 \uFE64 不等于 \u003C。使用 normalize() 函数，可以将码点 \uFE64 规范化为 \u003C，从而创建一个单一的码点表示，使它们能够成功进行比较。

注意事项
`normalize(null)` 返回 `null`。

示例 5. normalize()

查询

RETURN normalize('\u212B') = '\u00C5' AS result

结果
结果
`true`
行：1

要检查 STRING 是否已规范化，请使用 IS NORMALIZED 运算符。

normalize() 指定规范形式

主要有两种类型的规范化形式

规范等价：NFC（默认）和 NFD 是规范等价的形式。这意味着代表相同抽象字符的码点将被规范化为相同的码点（并具有相同的外观和行为）。NFC 形式将始终给出组合规范形式（如果可能，将组合代码替换为单个表示）。NFD 形式给出分解形式（组合形式的对立面，如果可能，它将组合的码点转换为拆分形式）。
兼容性规范化：NFKC 和 NFKD 是兼容性规范化形式。所有规范等价的序列都是兼容的，但并非所有兼容的序列都是规范的。这意味着以 NFC 或 NFD 规范化的字符也应该在 NFKC 和 NFKD 中进行规范化。其他仅在外观上略有差异的字符应该是兼容等价的。

例如，带有尖音符和钩号符号的希腊字母 Upsilon ϓ 可以由 Unicode 码点表示：\u03D3。

NFC 规范化：\u03D3 带有尖音符和钩号符号的希腊大写字母 Upsilon (ϓ)
NFD 规范化：\u03D2\u0301 带有钩号符号的希腊大写字母 Upsilon + 组合尖音符 (ϓ)
NFKC 规范化：\u038E 带有重音符的希腊大写字母 Upsilon (Ύ)
NFKD 规范化：\u03A5\u0301 希腊大写字母 Upsilon + 组合尖音符 (Ύ)

在兼容性规范化形式（NFKC 和 NFKD）中，字符在视觉上是不同的，因为它不再包含钩号符号。

示例 6. normalize() 指定规范化形式

查询

RETURN normalize('\uFE64', NFKC) = '\u003C' AS result

结果
结果
`true`
行：1

replace()

详细信息
语法	`replace(original, search, replace [, limit])`
描述	返回一个 `STRING`，其中所有出现的指定搜索 `STRING` 已被另一个（指定）替换 `STRING` 替换。
参数	名称	类型	描述
	`original`	`STRING`	要修改的字符串。
	`search`	`STRING`	在原始字符串中要替换的值。
	`replace`	`STRING`	要在原始字符串中插入的值。
	`limit`	`STRING`	在字符串中从左开始替换搜索值的最大次数。引入于 Neo4j 2025.06
返回	`STRING`

注意事项
如果任何参数为 `null`，则返回 `null`。
如果在 `original` 中找不到 `search`，则返回 `original`。
如果未定义 `limit`，则将替换所有搜索到的匹配项。

示例 7. replace()

查询

RETURN replace("hello", "l", "w")

结果
replace("hello", "l", "w")
`"hewwo"`
行：1

带限制的查询

RETURN replace("hello", "l", "w", 1)

结果
replace("hello", "l", "w", 1)
`"hewlo"`
行：1

reverse()

详细信息
语法	`reverse(input)`
描述	返回一个 `STRING` 或 `LIST<ANY>`，其中给定 `STRING` 或 `LIST<ANY>` 中的所有字符或元素顺序已被反转。
参数	名称	类型	描述
	`input`	`STRING \| LIST<ANY>`	要反转的字符串或列表。
返回	`STRING \| LIST<ANY>`

注意事项
`reverse(null)` 返回 `null`。
另请参阅列表函数 → `reverse()`。

示例 8. reverse

查询

RETURN reverse('palindrome')

结果
reverse('palindrome')
`"emordnilap"`
行：1

right()

详细信息
语法	`right(original, length)`
描述	返回一个包含给定 `STRING` 中最右侧指定数量字符的 `STRING`。
参数	名称	类型	描述
	`original`	`STRING`	要对其最左侧字符进行修剪的字符串值。
	`length`	`INTEGER（整数）`	要返回的最右侧字符的长度。
返回	`STRING`

注意事项
`right(null, length)` 返回 `null`。
`right(null, null)` 返回 `null`。
`right(original, null)` 将引发错误。
如果 `length` 不是正 `INTEGER`，则会引发错误。
如果 `length` 超过 `original` 的长度，则返回 `original`。

示例 9. right()

查询

RETURN right('hello', 3)

结果
right('hello', 3)
`"llo"`
行：1

rtrim()

详细信息
语法	`rtrim(input[, trimCharacterString])`
描述	返回移除尾随空白字符后的给定 `STRING`，也可以指定要移除的 `trimCharacterString`。
参数	名称	类型	描述
	`input`	`STRING`	将移除其前导和尾随修剪字符的值。
	`trimCharacterString`	`STRING`	要从给定字符串的开头和结尾移除的字符。
返回	`STRING`

注意事项
`rtrim(null)` 返回 `null`。
`rtrim(null, null)` 返回 `null`。
`rtrim("hello", null)` 返回 `null`。
`rtrim(null, ' ')` 返回 `null`。
如果未指定 `trimCharacterString`，则将移除所有前导空白字符。

示例 10. rtrim()

查询

RETURN rtrim('hello   '), rtrim('xxyyhelloxyxy', 'xy')

结果
rtrim('hello ')	rtrim('xxyyhelloxyxy', 'xy')
`"hello"`	`"xxyyhello"`
行：1

split()

详细信息
语法	`split(original, splitDelimiters)`
描述	返回通过在给定的分隔符匹配处拆分给定 `STRING` 而生成的 `LIST<STRING>`。
参数	名称	类型	描述
	`original`	`STRING`	要拆分的字符串。
	`splitDelimiters`	`STRING \| LIST<STRING>`	用于拆分原始字符串的字符串。
返回	`LIST<STRING>`

注意事项
`split(null, splitDelimiter)` 返回 `null`。
`split(original, null)` 返回 `null`

示例 11. split()

查询

RETURN split('one,two', ',')

结果
split('one,two', ',')
`["one","two"]`
行：1

substring()

详细信息
语法	`substring(original, start, length)`
描述	返回从给定 `STRING` 中提取的特定 `length` 的子字符串，起始位置为 0 基索引。
参数	名称	类型	描述
	`original`	`STRING`	要缩短的字符串。
	`开始`	`INTEGER（整数）`	新字符串的起始位置。
	`length`	`INTEGER（整数）`	新字符串的长度。
返回	`STRING`

注意事项
`start` 使用零基索引。
如果省略 `length`，则函数返回从 `start` 给定位置开始到 `original` 结尾的子字符串。
如果 `original` 为 `null`，则返回 `null`。
如果 `start` 或 `length` 为 `null` 或负整数，则会引发错误。
如果 `start` 为 `0`，则子字符串将从 `original` 的开头开始。
如果 `length` 为 `0`，则返回空 `STRING`。

示例 12. substring()

查询

RETURN substring('hello', 1, 3), substring('hello', 2)

结果
substring('hello', 1, 3)	substring('hello', 2)
`"ell"`	`"llo"`
行：1

toLower()

详细信息
语法	`toLower(input)`
描述	返回转换为小写的给定 `STRING`。
参数	名称	类型	描述
	`input`	`STRING`	要转换为小写的字符串。
返回	`STRING`

注意事项
`toLower(null)` 返回 `null`。

示例 13. toLower()

查询

RETURN toLower('HELLO')

结果
toLower('HELLO')
`"hello"`
行：1

toString()

详细信息
语法	`toString(input)`
描述	将 `INTEGER`、`FLOAT`、`BOOLEAN`、`POINT` 或时间类型（即 `DATE`、`ZONED TIME`、`LOCAL TIME`、`ZONED DATETIME`、`LOCAL DATETIME` 或 `DURATION`）的值转换为 `STRING`。
参数	名称	类型	描述
	`input`	`ANY`	要转换为字符串的值。
返回	`STRING`

注意事项
`toString(null)` 返回 `null`。
如果 `input` 是 `STRING`，则原样返回。
如果提供的表达式不是 `INTEGER`、`FLOAT`、`BOOLEAN`、`STRING`、`POINT`、`DURATION`、`DATE`、`ZONED TIME`、`LOCAL TIME`、`LOCAL DATETIME` 或 `ZONED DATETIME` 值，此函数将返回错误。

示例 14. toString()

查询

RETURN
  toString(11.5),
  toString('already a string'),
  toString(true),
  toString(date({year: 1984, month: 10, day: 11})) AS dateString,
  toString(datetime({year: 1984, month: 10, day: 11, hour: 12, minute: 31, second: 14, millisecond: 341, timezone: 'Europe/Stockholm'})) AS datetimeString,
  toString(duration({minutes: 12, seconds: -60})) AS durationString

结果
toString(11.5)	toString('already a string')	toString(true)	dateString	datetimeString	durationString
`"11.5"`	`"already a string"`	`"true"`	`"1984-10-11"`	`"1984-10-11T12:31:14.341+01:00[Europe/Stockholm]"`	`"PT11M"`
行：1

toStringOrNull()

详细信息
语法	`toStringOrNull(input)`
描述	将 `INTEGER`、`FLOAT`、`BOOLEAN`、`POINT` 或时间类型（例如 `DATE`、`ZONED TIME`、`LOCAL TIME`、`ZONED DATETIME`、`LOCAL DATETIME` 或 `DURATION`）的值转换为 `STRING`，如果无法转换，则返回 null。
参数	名称	类型	描述
	`input`	`ANY`	要转换为字符串或 null 的值。
返回	`STRING`

注意事项
`toStringOrNull(null)` 返回 `null`。
如果 `input` 不是 `INTEGER`、`FLOAT`、`BOOLEAN`、`STRING`、`POINT`、`DURATION`、`DATE`、`ZONED TIME`、`LOCAL TIME`、`LOCAL DATETIME` 或 `ZONED DATETIME` 值，则返回 `null`。

示例 15. toStringOrNull()

查询

RETURN toStringOrNull(11.5),
toStringOrNull('already a string'),
toStringOrNull(true),
toStringOrNull(date({year: 1984, month: 10, day: 11})) AS dateString,
toStringOrNull(datetime({year: 1984, month: 10, day: 11, hour: 12, minute: 31, second: 14, millisecond: 341, timezone: 'Europe/Stockholm'})) AS datetimeString,
toStringOrNull(duration({minutes: 12, seconds: -60})) AS durationString,
toStringOrNull(['A', 'B', 'C']) AS list

结果
toStringOrNull(11.5)	toStringOrNull('already a string')	toStringOrNull(true)	dateString	datetimeString	durationString	list
`"11.5"`	`"already a string"`	`"true"`	`"1984-10-11"`	`"1984-10-11T12:31:14.341+01:00[Europe/Stockholm]"`	`"PT11M"`	`<null>`
行：1

toUpper()

详细信息
语法	`toUpper(input)`
描述	返回转换为大写的给定 `STRING`。
参数	名称	类型	描述
	`input`	`STRING`	要转换为大写的字符串。
返回	`STRING`

注意事项
`toUpper(null)` 返回 `null`。

示例 16. toUpper()

查询

RETURN toUpper('hello')

结果
toUpper('hello')
`"HELLO"`
行：1

trim()

详细信息
语法	`trim(trimSpecification, trimCharacterString, input)`
描述	返回移除前导和/或尾随 `trimCharacterString` 后的给定 `STRING`。
参数	名称	类型	描述
	`trimSpecification`	`[LEADING, TRAILING, BOTH]`	要修剪的字符串部分；LEADING（前导）、TRAILING（尾随）、BOTH（两者）
	`trimCharacterString`	`STRING`	要从给定字符串的开头和/或结尾移除的字符。
	`input`	`STRING`	将移除所有前导和/或尾随修剪字符的值。
返回	`STRING`

注意事项
`trim(null)` 返回 `null`。
`trim(null FROM "hello")` 返回 `null`。
`trim(" " FROM null)` 返回 `null`。
`trim(BOTH null FROM null)` 返回 `null`。
如果未指定 `trimSpecification` 和 `trimCharacterString`，则将移除所有前导和/或尾随的空白字符。

示例 17. trim()

查询

RETURN trim('   hello   '), trim(BOTH 'x' FROM 'xxxhelloxxx')

结果
trim(' hello ')	trim(BOTH 'x' FROM 'xxxhelloxxx')
`"hello"`	`"hello"`
行：1

upper()

详细信息
语法	`upper(input)`
描述	返回转换为大写的给定 `STRING`。
参数	名称	类型	描述
	`input`	`STRING`	要转换为大写的字符串。
返回	`STRING`

此函数是 toUpper() 函数的别名，它是作为 Cypher GQL 一致性的一部分引入的。

注意事项
`upper(null)` 返回 `null`。

示例 18. upper()

查询

RETURN upper('hello')

结果
upper('hello')
`"HELLO"`
行：1