标量函数

示例图

以下图表用于下方的示例

要重新创建该图，请在空的 Neo4j 数据库中运行以下查询

CREATE
  (alice:Developer {name:'Alice', age: 38, eyes: 'Brown'}),
  (bob:Administrator {name: 'Bob', age: 25, eyes: 'Blue'}),
  (charlie:Administrator {name: 'Charlie', age: 53, eyes: 'Green'}),
  (daniel:Adminstrator {name: 'Daniel', age: 54, eyes: 'Brown'}),
  (eskil:Designer {name: 'Eskil', age: 41, eyes: 'blue', likedColors: ['Pink', 'Yellow', 'Black']}),
  (alice)-[:KNOWS]->(bob),
  (alice)-[:KNOWS]->(charlie),
  (bob)-[:KNOWS]->(daniel),
  (charlie)-[:KNOWS]->(daniel),
  (bob)-[:MARRIED]->(eskil)

char_length()

详细信息
语法	`char_length(input)`
描述	返回 `STRING`（字符串）中的 Unicode 字符数量。
参数	名称	类型	描述
	`input`	`STRING`	需要计算字符长度的字符串值。
返回	`INTEGER（整数）`

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

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

示例 1. char_length()

查询

RETURN char_length('Alice')

结果
char_length('Alice')
`5`
行：1

返回 STRING 中的 Unicode 字符数。

character_length()

详细信息
语法	`character_length(input)`
描述	返回 `STRING`（字符串）中的 Unicode 字符数量。
参数	名称	类型	描述
	`input`	`STRING`	需要计算字符长度的字符串值。
返回	`INTEGER（整数）`

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

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

示例 2. character_length()

查询

RETURN character_length('Alice')

结果
character_length('Alice')
`5`
行：1

返回 STRING 中的 Unicode 字符数。

coalesce()

详细信息
语法	`coalesce(input)`
描述	返回表达式列表中第一个非空（non-null）的值。
参数	名称	类型	描述
	`input`	`ANY`	如果是第一个非 `null` 的值，它将被返回。
返回	`ANY`

注意事项
如果所有参数均为 `null`，则返回 `null`。

示例 3. coalesce()

查询

MATCH (a)
WHERE a.name = 'Alice'
RETURN coalesce(a.hairColor, a.eyes)

结果
coalesce(a.hairColor, a.eyes)
`"Brown"`
行：1

elementId()

详细信息
语法	`elementId(input)`
描述	返回 `NODE`（节点）或 `RELATIONSHIP`（关系）的元素 ID。
参数	名称	类型	描述
	`input`	`NODE \| RELATIONSHIP`	节点或关系的元素 ID。
返回	`STRING`

在使用 elementId() 时有一些重要事项需要注意：

每个节点和关系都保证有一个元素 ID。此 ID 在单个事务范围内，对于同一 DBMS 中的所有数据库内的所有节点和关系都是唯一的。但是，不保证返回 ID 值的顺序，也不保证 ID STRING 值的长度。在单个事务范围之外，不保证 ID 值与元素之间的映射关系。
当删除节点和关系时，Neo4j 会重用其内部 ID。因此，依赖内部 Neo4j ID 的应用程序非常脆弱且可能不准确。因此，建议使用应用程序生成的 ID。

注意事项
`elementId(null)` 返回 `null`。
在 `NODE`、`RELATIONSHIP` 或 `null` 以外的值上使用 `elementId` 将导致查询失败。

示例 4. 用于节点的 elementId()

查询

MATCH (n:Developer)
RETURN elementId(n)

返回每个 Developer 节点的标识符。

结果
elementId(n)
`"4:d8d172ec-96d8-4364-8f5d-9353d776aeb3:0"`
行：1

示例 5. 用于关系的 elementId()

查询

MATCH (:Developer)-[r]-()
RETURN elementId(r)

返回连接到 Developer 节点的每个关系的标识符。

结果
elementId(r)
`"5:d8d172ec-96d8-4364-8f5d-9353d776aeb3:0"`
`"5:d8d172ec-96d8-4364-8f5d-9353d776aeb3:1"`
行：2

endNode()

详细信息
语法	`endNode(input)`
描述	返回 `RELATIONSHIP` 的结束 `NODE`。
参数	名称	类型	描述
	`input`	`RELATIONSHIP`	一个关系。
返回	`NODE`

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

示例 6. endNode()

查询

MATCH (x:Developer)-[r]-()
RETURN endNode(r)

结果
endNode(r)
`{name: "Bob", age: 25, eyes: "Blue"}`
`{name: "Charlie", age: 53, eyes: "Green"}`
行：2

head()

详细信息
语法	`head(list)`
描述	返回 `LIST<ANY>` 中的第一个元素。
参数	名称	类型	描述
	`list`	`LIST<ANY>`	一个将返回其中第一个元素的列表。
返回	`ANY`

注意事项
`head(null)` 返回 `null`。
`head([])` 返回 `null`。
如果 `list` 中的第一个元素是 `null`，`head(list)` 将返回 `null`。

示例 7. head()

查询

MATCH (a)
WHERE a.name = 'Eskil'
RETURN a.likedColors, head(a.likedColors)

返回列表中的第一个元素。

结果
a.likedColors+	+head(a.likedColors)
`["Pink", "Yellow", "Black"]`	`"Pink"`
行：1

id()
已弃用

建议使用 elementId() 代替。

详细信息
语法	`id(input)`
描述	返回 `NODE` 或 `RELATIONSHIP` 的 ID。
参数	名称	类型	描述
	`input`	`NODE \| RELATIONSHIP`	一个节点或一个关系。
返回	`INTEGER（整数）`

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

在使用 id() 时有一些重要事项需要注意：

id() 函数返回一个节点或关系标识符，该标识符按对象类型和数据库唯一。因此，在同一个数据库中，id() 可能为节点和关系返回相同的值。
Neo4j 实现 ID 的方式是确保数据库中的每个节点和关系都有一个标识符。节点或关系的标识符在单个事务范围内，保证在数据库内所有其他节点和关系的标识符中是唯一的。
当删除节点和关系时，Neo4j 会重用其内部 ID。因此，依赖内部 Neo4j ID 的应用程序非常脆弱且可能不准确。因此，建议使用应用程序生成的 ID。

在复合数据库上，应谨慎使用 id() 函数。建议使用 elementId() 代替。

当在特定数据库的子查询中调用时，节点或关系的结果 ID 值是该数据库本地的。来自不同数据库的节点或关系的本地 ID 可能是相同的。

当从查询的根上下文调用时，结果值是节点或关系的扩展 ID。扩展 ID 可能与相同节点或关系的本地 ID 不同。

示例 8. id()

查询

MATCH (a)
RETURN id(a)

返回每个节点的节点标识符。

结果
id(a)
`0`
`1`
`2`
`3`
`4`
行：5

last()

详细信息
语法	`last(list)`
描述	返回 `LIST<ANY>` 中的最后一个元素。
参数	名称	类型	描述
	`list`	`LIST<ANY>`	一个将返回其中最后一个元素的列表。
返回	`ANY`

注意事项

last(null) 返回 null。

last([]) 返回 null。

如果 list 中的最后一个元素是 null，last(list) 将返回 null。

示例 9. last()

查询

MATCH (a)
WHERE a.name = 'Eskil'
RETURN a.likedColors, last(a.likedColors)

返回列表中的最后一个元素。

结果
a.liked_colors	last(a.liked_colors)
`["Pink", "Yellow", "Black"]`	`"Black"`
行：1

length()

详细信息
语法	`length(input)`
描述	返回 `PATH`（路径）的长度。
参数	名称	类型	描述
	`input`	`PATH`	将对其关系进行计数的路径。
返回	`INTEGER（整数）`

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

要计算 LIST 的长度或 STRING 中 Unicode 字符的数量，请参见 size()

示例 10. length()

查询

MATCH p = (a)-->(b)-->(c)
WHERE a.name = 'Alice'
RETURN length(p)

返回路径 p 的长度。

结果
length(p)
`2`
`2`
`2`
行：3

path_length()
仅限 Cypher 25在 Neo4j 2026.02 中引入

此函数是应用于路径时 length() 函数的别名，它是作为 Cypher GQL 一致性的一部分引入的。除了命名和 GQL 的路径值表达式/连接规则外，该函数符合 GQL 标准。

详细信息
语法	`path_length(input)`
描述	返回 `PATH`（路径）的长度。
参数	名称	类型	描述
	`input`	`PATH`	将对其关系进行计数的路径。
返回	`INTEGER（整数）`

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

要计算 LIST 的长度或 STRING 中 Unicode 字符的数量，请参见 size()

示例 11. path_length()

查询

MATCH p = (a)-->(b)-->(c)
WHERE a.name = 'Alice'
RETURN path_length(p)

返回路径 p 的长度。

结果
path_length(p)
`2`
`2`
`2`
行：3

nullIf()

详细信息
语法	`nullIf(v1, v2)`
描述	如果给定的两个参数相等，则返回 null，否则返回第一个参数的值。
参数	名称	类型	描述
	`v1`	`ANY`	如果第二个值不相等，则返回的第一个值。
	`v2`	`ANY`	用于与第一个值进行比较的第二个值。
返回	`ANY`

此函数与 coalesce() 函数相反，后者在给定值为 null 时返回默认值。

示例 12. nullIf()

查询

RETURN nullIf(4, 4)

由于两个参数相等，返回 null 值。

结果
nullIf(4, 4)
`null`
行：1

示例 13. nullIf()

查询

RETURN nullIf("abc", "def")

由于两个参数不相等，返回第一个参数 "abc"。

结果
nullIf("abc", "def")
`"abc"`
行：1

示例 14. nullIf()

nullIf() 函数可以与 coalesce() 函数结合使用，将一个数据值转换为另一个值。

查询

MATCH (a)
RETURN a.name AS name, coalesce(nullIf(a.eyes, "Brown"), "Hazel") AS eyeColor

结果
名称 (name)	eyeColor
`"Alice"`	`"Hazel"`
`"Bob"`	`"Blue"`
`"Charlie"`	`"Green"`
`"Daniel"`	`"Hazel"`
`"Eskil"`	`"Blue"`
行：5

properties()

详细信息
语法	`properties(input)`
描述	返回一个包含 `NODE`、`RELATIONSHIP` 或 `MAP` 的所有属性的 `MAP`（映射）。
参数	名称	类型	描述
	`input`	`NODE \| RELATIONSHIP \| MAP`	返回其属性的实体。
返回	`MAP`

注意事项
`properties(null)` 返回 `null`。
如果 `input` 已经是一个 `MAP`，则原样返回。

示例 15. properties()

查询

CREATE (p:Person {name: 'Stefan', city: 'Berlin'})
RETURN properties(p)

结果
properties(p)
`{"city": "Berlin", "name": "Stefan"}`
行：1

randomUUID()

详细信息
语法	`randomUUID()`
描述	生成一个随机 UUID。
返回	`STRING`

通用唯一识别码 (UUID)，也称为全局唯一标识符 (GUID)，是一个 128 位的值，具有极强的唯一性保证。

示例 16. randomUUID()

查询

RETURN randomUUID() AS uuid

结果
uuid
`"9f4c297d-309a-4743-a196-4525b96135c1"`
行：1

返回一个随机生成的 UUID。

size()

详细信息
语法	`size(input)`
描述	返回 `LIST<ANY>` 中的项目数、`STRING` 中的 Unicode 字符数或 `VECTOR` 的维度。
参数	名称	类型	描述
	`input`	`STRING \| LIST<ANY> \| VECTOR`	需要计算其长度的值。
返回	`INTEGER（整数）`

要计算 PATH 的长度，请参见 length()。

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

示例 17. size() 应用于列表

查询

RETURN size(['Alice', 'Bob'])

结果
size(['Alice', 'Bob'])
`2`
行：1

返回列表中的元素数量。

示例 18. size() 应用于模式推导

查询

MATCH (a)
WHERE a.name = 'Alice'
RETURN size([p=(a)-->()-->() | p]) AS fof

结果
fof
`3`
行：1

返回匹配模式表达式的路径数量。（路径列表的大小）。

示例 19. size() 应用于字符串

查询

MATCH (a)
WHERE size(a.name) > 6
RETURN size(a.name)

结果
size(a.name)
`7`
行：1

返回 STRING 'Charlie' 中的字符数量。

示例 20. size() 应用于向量

查询

RETURN size(vector([1, 2, 3], 3, INTEGER8)) AS size

结果
size
`3`
行：1

返回向量的维度。

您也可以使用 vector_dimension_count() 函数来返回 VECTOR 值的维度。

startNode()

详细信息
语法	`startNode(input)`
描述	返回 `RELATIONSHIP` 的起始 `NODE`。
参数	名称	类型	描述
	`input`	`RELATIONSHIP`	一个关系。
返回	`NODE`

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

示例 21. startNode()

查询

MATCH (x:Developer)-[r]-()
RETURN startNode(r)

结果
startNode(r)
`{name: "Alice", age: 38, eyes: "Brown"}`
`{name: "Alice", age: 38, eyes: "Brown"}`
行：2

timestamp()

详细信息
语法	`timestamp()`
描述	返回当前时间与 1970 年 1 月 1 日 UTC 午夜之间以毫秒为单位的差值。
返回	`INTEGER（整数）`

datetime.fromEpochMillis() 是 timestamp() 的功能等价物。

注意事项
`timestamp()` 在整个查询期间将返回相同的值，即使是长时间运行的查询也是如此。

示例 22. timestamp()

查询

RETURN timestamp()

返回以毫秒为单位的时间。

结果
timestamp()
`1655201331965`
行：1

toBoolean()

详细信息
语法	`toBoolean(input)`
描述	将 `BOOLEAN`、`STRING` 或 `INTEGER` 值转换为 `BOOLEAN` 值。对于 `INTEGER` 值，0 定义为 false，任何其他 `INTEGER` 定义为 true。
参数	名称	类型	描述
	`input`	`BOOLEAN \| STRING \| INTEGER`	要转换为布尔值的值。
返回	`布尔值 (BOOLEAN)`

注意事项
`toBoolean(null)` 返回 `null`。
如果 `input` 是一个 `BOOLEAN` 值，它将被原样返回。
如果解析失败，将返回 `null`。
如果 `input` 是 `INTEGER` 值 `0`，则返回 `false`。对于任何其他 `INTEGER` 值，返回 `true`。
如果提供不是 `STRING`、`INTEGER` 或 `BOOLEAN` 值的表达式，此函数将返回错误。

示例 23. toBoolean()

查询

RETURN toBoolean('true'), toBoolean('not a boolean'), toBoolean(0)

结果
toBoolean('true')	toBoolean('not a boolean')	toBoolean(0)
`true`	`<null>`	`false`
行：1

toBooleanOrNull()

详细信息
语法	`toBooleanOrNull(input)`
描述	将值转换为 `BOOLEAN` 值，如果无法转换，则返回 null。
参数	名称	类型	描述
	`input`	`ANY`	要转换为布尔值或 null 的值。
返回	`布尔值 (BOOLEAN)`

注意事项
`toBooleanOrNull(null)` 返回 `null`。
如果 `input` 是一个 `BOOLEAN` 值，它将被原样返回。
如果解析失败，将返回 `null`。
如果 `input` 是 `INTEGER` 值 `0`，则返回 `false`。对于任何其他 `INTEGER` 值，返回 `true`。
如果 `input` 不是 `STRING`、`INTEGER` 或 `BOOLEAN` 值，将返回 `null`。

示例 24. toBooleanOrNull()

查询

RETURN toBooleanOrNull('true'), toBooleanOrNull('not a boolean'), toBooleanOrNull(0), toBooleanOrNull(1.5)

结果
toBooleanOrNull('true')	toBooleanOrNull('not a boolean')	toBooleanOrNull(0)	toBooleanOrNull(1.5)
`true`	`<null>`	`false`	`<null>`
行：1

toFloat()

详细信息
语法	`toFloat(input)`
描述	将 `STRING`、`INTEGER` 或 `FLOAT` 值转换为 `FLOAT`（浮点数）值。
参数	名称	类型	描述
	`input`	`STRING \| INTEGER \| FLOAT`	要转换为浮点数的值。
返回	`FLOAT`

注意事项
`toFloat(null)` 返回 `null`。
如果 `input` 是一个 `FLOAT`，它将被原样返回。
如果解析失败，将返回 `null`。
如果提供不是 `INTEGER`、`FLOAT` 或 `STRING` 值的表达式，此函数将返回错误。

示例 25. toFloat()

查询

RETURN toFloat('11.5'), toFloat('not a number')

结果
toFloat('11.5')	toFloat('not a number')
`11.5`	`<null>`
行：1

toFloatOrNull()

详细信息
语法	`toFloatOrNull(input)`
描述	将值转换为 `FLOAT` 值，如果无法转换，则返回 null。
参数	名称	类型	描述
	`input`	`ANY`	要转换为浮点数或 null 的值。
返回	`FLOAT`

注意事项
`toFloatOrNull(null)` 返回 `null`。
如果 `input` 是一个 `FLOAT`，它将被原样返回。
如果解析失败，将返回 `null`。
如果 `input` 不是 `INTEGER`、`FLOAT` 或 `STRING` 值，将返回 `null`。

示例 26. toFloatOrNull()

查询

RETURN toFloatOrNull('11.5'), toFloatOrNull('not a number'), toFloatOrNull(true)

结果
toFloatOrNull('11.5')	toFloatOrNull('not a number')	toFloatOrNull(true)
`11.5`	`<null>`	`<null>`
行：1

toInteger()

详细信息
语法	`toInteger(input)`
描述	将 `BOOLEAN`、`STRING`、`INTEGER` 或 `FLOAT` 值转换为 `INTEGER`（整数）值。对于 `BOOLEAN` 值，true 定义为 1，false 定义为 0。
参数	名称	类型	描述
	`input`	`BOOLEAN \| STRING \| INTEGER \| FLOAT`	要转换为整数的值。
返回	`INTEGER（整数）`

注意事项
`toInteger(null)` 返回 `null`。
如果 `input` 是一个 `INTEGER` 值，它将被原样返回。
如果解析失败，将返回 `null`。
如果 `input` 是布尔值 `false`，将返回 `0`。
如果 `input` 是布尔值 `true`，将返回 `1`。
如果提供不是 `BOOLEAN`、`FLOAT`、`INTEGER` 或 `STRING` 值的表达式，此函数将返回错误。

示例 27. toInteger()

查询

RETURN toInteger('42'), toInteger('not a number'), toInteger(true)

结果
toInteger('42')	toInteger('not a number')	toInteger(true)
`42`	`<null>`	`1`
行：1

toIntegerOrNull()

详细信息
语法	`toIntegerOrNull(input)`
描述	将值转换为 `INTEGER` 值，如果无法转换，则返回 null。
参数	名称	类型	描述
	`input`	`ANY`	要转换为整数或 null 的值。
返回	`INTEGER（整数）`

注意事项
`toIntegerOrNull(null)` 返回 `null`。
如果 `input` 是一个 `INTEGER` 值，它将被原样返回。
如果解析失败，将返回 `null`。
如果 `input` 是 `BOOLEAN` 值 `false`，将返回 `0`。
如果 `input` 是 `BOOLEAN` 值 `true`，将返回 `1`。
如果 `input` 不是 `BOOLEAN`、`FLOAT`、`INTEGER` 或 `STRING` 值，将返回 `null`。

示例 28. toIntegerOrNull()

查询

RETURN toIntegerOrNull('42'), toIntegerOrNull('not a number'), toIntegerOrNull(true), toIntegerOrNull(['A', 'B', 'C'])

结果
toIntegerOrNull('42')	toIntegerOrNull('not a number')	toIntegerOrNull(true)	toIntegerOrNull(['A', 'B', 'C'])
`42`	`<null>`	`1`	`<null>`
行：1

type()

详细信息
语法	`type(input)`
描述	返回 `RELATIONSHIP` 类型的 `STRING` 表示形式。
参数	名称	类型	描述
	`input`	`RELATIONSHIP`	一个关系。
返回	`STRING`

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

示例 29. type()

查询

MATCH (n)-[r]->()
WHERE n.name = 'Alice'
RETURN type(r)

返回 r 的关系类型。

结果
type(r)
`"KNOWS"`
`"KNOWS"`
行：2

valueType()

详细信息
语法	`valueType(input)`
描述	返回给定表达式求值结果的最精确值类型的 `STRING` 表示形式。
参数	名称	类型	描述
	`input`	`ANY`	要返回其类型的值。
返回	`STRING`

输出是确定性的，并使用了类型规范化。

注意事项

Cypher 的未来版本可能包含对当前类型系统的更新。这可能包括引入新类型和现有支持类型的子类型。如果引入了新类型，它将在发布后立即由 valueType() 函数返回。然而，如果引入了先前支持类型的更精确子类型，这将视为破坏性变更。

例如，该函数当前返回 "FLOAT"，但如果添加了更具体的 FLOAT 类型（例如 FLOAT32），这将被视为更具体，并且在 Neo4j 的下一个主要版本之前不会返回。因此，在下一个主要版本之前，任何 FLOAT32 值将继续返回 "FLOAT"。

以下列表包含了 valueType() 函数当前显示的所有受支持类型

预定义类型
- NOTHING
- null
- 布尔值 (BOOLEAN)
- STRING
- INTEGER（整数）
- FLOAT
- DATE
- LOCAL TIME
- ZONED TIME
- LOCAL DATETIME
- ZONED DATETIME
- DURATION（持续时间）
- POINT
- NODE
- RELATIONSHIP
构造类型
- MAP
- LIST<INNER_TYPE>（按内部类型排序）
- PATH
动态联合类型
- INNER_TYPE_1 \| INNER_TYPE_2…（按封闭动态联合类型的特定规则排序）
- ANY

在依赖 valueType() 函数的输出时应考虑这一点。

请参阅类型谓词表达式，以获取测试类型值的替代方法。

示例 30. valueType()

查询

UNWIND ["abc", 1, 2.0, true, [date()]] AS value
RETURN valueType(value) AS result

结果
结果
`"STRING NOT NULL"`
`"INTEGER NOT NULL"`
`"FLOAT NOT NULL"`
`"BOOLEAN NOT NULL"`
`"LIST<DATE NOT NULL> NOT NULL"`
行：5

示例图

char_length()

character_length()

coalesce()

elementId()

endNode()

head()

id()已弃用

last()

length()

path_length()仅限 Cypher 25在 Neo4j 2026.02 中引入

nullIf()

properties()

randomUUID()

size()

startNode()

timestamp()

toBoolean()

toBooleanOrNull()

toFloat()

toFloatOrNull()

toInteger()

toIntegerOrNull()

type()

valueType()

id()
已弃用

path_length()
仅限 Cypher 25在 Neo4j 2026.02 中引入