标量函数 - Cypher 手册 - Neo4j 图数据库

示例图

以下图用于下面的示例

要重新创建该图，请对空的 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`。
`elementId` 对除 `NODE`、`RELATIONSHIP` 或 `null` 之外的值调用将导致查询失败。

示例 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"]`	`"黑色"`
行：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

结果
姓名	眼睛颜色
`"爱丽丝"`	`"榛色"`
`"鲍勃"`	`"蓝色"`
`"查理"`	`"绿色"`
`"丹尼尔"`	`"榛色"`
`"埃斯基尔"`	`"蓝色"`
行数: 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": "柏林", "name": "斯特凡"}`
行：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().epochMillis。

注意事项
即使对于长时间运行的查询，`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 5.13 版本中支持的所有类型（直到 Neo4j 的下一个主要版本发布）。

预定义类型
- 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