标量函数 - Cypher 手册

示例图

以下图用于下面的示例

要重新创建图，请对空的 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)`
描述	返回表达式列表中第一个非空值。
参数	名称	类型	描述
	`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

nullIf()

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

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

示例 11. nullIf()

查询

RETURN nullIf(4, 4)

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

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

示例 12. nullIf()

查询

RETURN nullIf("abc", "def")

返回第一个参数 "abc"，因为两个参数不相等。

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

示例 13. nullIf()

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

查询

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

结果
名称	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`，则原样返回。

示例 14. 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 位值，具有强大的唯一性保证。

示例 15. randomUUID()

查询

RETURN randomUUID() AS uuid

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

返回一个随机生成的 UUID。

size()

详情
语法	`size(input)`
描述	返回 `LIST<ANY>` 中的项目数量或 `STRING` 中 Unicode 字符的数量。
参数	名称	类型	描述
	`input`	`STRING \| LIST<ANY>`	一个将计算其长度的值。
返回	`INTEGER`

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

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

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

查询

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

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

返回列表中元素的数量。

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

查询

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

结果
fof
`3`
行数：1

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

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

查询

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

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

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

startNode()

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

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

示例 19. 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()` 在整个查询期间将返回相同的值，即使是长时间运行的查询也是如此。

示例 20. 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` 值，此函数将返回错误。

示例 21. 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`。

示例 22. 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` 值，此函数将返回错误。

示例 23. 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`。

示例 24. 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` 值，此函数将返回错误。

示例 25. 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`。

示例 26. 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`。

示例 27. 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() 函数就会返回该类型。但是，如果引入了先前支持的类型的更精确子类型，则将被视为一个重大更改。因此，在 Neo4j 5.13 发布后引入的任何新子类型都不会被 valueType() 函数返回，直到 Neo4j 的下一个主要版本。

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

考虑到这一点，以下列表包含 valueType() 函数在 Neo4j 下一个主要版本之前显示的所有支持类型（截至 Neo4j 5.13）

预定义类型
- 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() 函数的输出时，应考虑到这一点。

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

示例 28. 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