过滤后的节点相似度

有向

无向

异构节点

异构关系

加权关系

词汇表

有向: 有向特性。该算法在有向图上定义良好。
有向: 有向特性。该算法忽略图的方向。
有向: 有向特性。该算法不在有向图上运行。
无向: 无向特性。该算法在无向图上定义良好。
无向: 无向特性。该算法忽略图的无向性。
异构节点: 异构节点完全支持。该算法能够区分不同类型的节点。
异构节点: 异构节点允许。该算法对所有选定的节点一视同仁，无论其标签如何。
异构关系: 异构关系完全支持。该算法能够区分不同类型的关系。
异构关系: 异构关系允许。该算法对所有选定的关系一视同仁，无论其类型如何。
加权关系: 加权特性。该算法支持将关系属性用作权重，通过relationshipWeightProperty 配置参数指定。
加权关系: 加权特性。该算法将每个关系视为同等重要，忽略任何关系权重的值。

简介

过滤后的节点相似度算法是节点相似度算法的扩展。它增加了对源节点、目标节点或两者进行过滤的支持。

节点过滤

节点过滤器会减少算法产生结果的节点空间。考虑两个相似度结果：A = (alice)-[:SIMILAR_TO]→(bob) 和 B (bob)-[:SIMILAR_TO]→(alice)。如果 (alice) 节点匹配源节点过滤器且 (bob) 节点匹配目标节点过滤器，则会产生结果 A。如果 (alice) 节点不匹配目标节点过滤器，或者 (bob) 节点不匹配源节点过滤器，则不会产生结果 B。

配置节点过滤器

有关节点相似度的标准配置，请参阅节点相似度语法。

源节点过滤器由 sourceNodeFilter 配置参数指定。目标节点过滤器由 targetNodeFilter 配置参数指定。这两个参数都不是强制性的。

节点过滤参数接受以下其中一种：

表 1. `sourceNodeFilter` 和 `targetNodeFilter` 的语法
单个节点 ID	`sourceNodeFilter: 42`
节点 ID 列表	`sourceNodeFilter: [23, 42, 87]`
单个节点	`MATCH (person:Person) WITH person ORDER BY person.age DESC LIMIT 1` … `sourceNodeFilter: n`
节点列表	`MATCH (person:Person) WHERE person.age > 35 collect(person) AS people` … `sourceNodeFilter: people`
单个标签	`sourceNodeFilter: 'Person'`

语法

本节介绍在每种执行模式下执行过滤后的节点相似度算法所使用的语法。我们将描述命名图语法的变体。要了解有关一般语法变体的更多信息，请参阅语法概述。

每种模式下的过滤节点相似度语法

在命名图上以流模式运行过滤后的节点相似度。

CALL gds.nodeSimilarity.filtered.stream(
  graphName: String,
  configuration: Map
) YIELD
  node1: Integer,
  node2: Integer,
  similarity: Float

表 2. 参数
名称	类型	默认值	可选	描述
graphName	字符串	`不适用`	否	存储在目录中的图的名称。
configuration	映射	`{}`	是	算法特定和/或图过滤的配置。

表 3. 配置
名称	类型	默认值	可选	描述
nodeLabels	字符串列表	`['*']`	是	使用给定的节点标签过滤命名图。将包含具有任何给定标签的节点。
relationshipTypes	字符串列表	`['*']`	是	使用给定的关系类型过滤命名图。将包含具有任何给定类型的关系。
concurrency	整数	`4 ^[1]`	是	运行算法时使用的并发线程数。
jobId	字符串	`内部生成`	是	可用于更轻松地跟踪算法进度的 ID。
logProgress	布尔值	`true`	是	如果禁用，将不会记录进度百分比。
similarityCutoff	浮点数	`1e-42`	是	相似度分数出现在结果中的下限。值必须介于 0 和 1 之间。
degreeCutoff	整数	`1`	是	节点度数的包含性下限，用于在比较中考虑节点。此值不能小于 1。
upperDegreeCutoff	整数	`2147483647`	是	节点度数的包含性上限，用于在比较中考虑节点。此值不能小于 1。
topK	整数	`10`	是	每个节点分数的限制。返回 K 个最大结果。此值不能小于 1。
bottomK	整数	`10`	是	每个节点分数的限制。返回 K 个最小结果。此值不能小于 1。
topN	整数	`0`	是	计算分数的全局限制。返回 N 个最大的总结果。此值不能为负数，值为 0 表示没有全局限制。
bottomN	整数	`0`	是	计算分数的全局限制。返回 N 个最小的总结果。此值不能为负数，值为 0 表示没有全局限制。
relationshipWeightProperty	字符串	`null`	是	用作权重的关系属性名称。如果未指定，算法将以无权重方式运行。
similarityMetric	字符串	`JACCARD`	是	用于计算相似度的度量。可以是 `JACCARD`、`OVERLAP` 或 `COSINE`。
useComponents	布尔值或字符串	`false`	是	如果启用，节点相似度将使用组件来提高计算性能，跳过不同组件中节点的比较。设置为 `false`（默认）：算法不使用组件，但计算整个图的相似度。设置为 `true`：算法使用组件，并在计算相似度之前计算这些组件。设置为字符串：使用存储在图中的预计算组件，字符串是表示组件的节点属性的键。
sourceNodeFilter	整数或整数列表或字符串	`不适用`	否	要应用的源节点过滤器。接受单个节点 ID、节点 ID 列表或单个标签。
targetNodeFilter	整数或整数列表或字符串	`不适用`	否	要应用的目标节点过滤器。接受单个节点 ID、节点 ID 列表或单个标签。
1. 在 GDS 会话中，默认值为可用处理器数量。

表 4. 结果
名称	类型	描述
`node1`	整数	第一个节点的节点 ID。
`node2`	整数	第二个节点的节点 ID。
`similarity`	浮点数	两个节点的相似度分数。

在命名图上以统计模式运行节点相似度。

CALL gds.nodeSimilarity.filtered.stats(
  graphName: String,
  configuration: Map
)
YIELD
  preProcessingMillis: Integer,
  computeMillis: Integer,
  postProcessingMillis: Integer,
  nodesCompared: Integer,
  similarityPairs: Integer,
  similarityDistribution: Map,
  configuration: Map

表 5. 参数
名称	类型	默认值	可选	描述
graphName	字符串	`不适用`	否	存储在目录中的图的名称。
configuration	映射	`{}`	是	算法特定和/或图过滤的配置。

表 6. 配置
名称	类型	默认值	可选	描述
nodeLabels	字符串列表	`['*']`	是	使用给定的节点标签过滤命名图。将包含具有任何给定标签的节点。
relationshipTypes	字符串列表	`['*']`	是	使用给定的关系类型过滤命名图。将包含具有任何给定类型的关系。
concurrency	整数	`4 ^[2]`	是	运行算法时使用的并发线程数。
jobId	字符串	`内部生成`	是	可用于更轻松地跟踪算法进度的 ID。
logProgress	布尔值	`true`	是	如果禁用，将不会记录进度百分比。
similarityCutoff	浮点数	`1e-42`	是	相似度分数出现在结果中的下限。值必须介于 0 和 1 之间。
degreeCutoff	整数	`1`	是	节点度数的包含性下限，用于在比较中考虑节点。此值不能小于 1。
upperDegreeCutoff	整数	`2147483647`	是	节点度数的包含性上限，用于在比较中考虑节点。此值不能小于 1。
topK	整数	`10`	是	每个节点分数的限制。返回 K 个最大结果。此值不能小于 1。
bottomK	整数	`10`	是	每个节点分数的限制。返回 K 个最小结果。此值不能小于 1。
topN	整数	`0`	是	计算分数的全局限制。返回 N 个最大的总结果。此值不能为负数，值为 0 表示没有全局限制。
bottomN	整数	`0`	是	计算分数的全局限制。返回 N 个最小的总结果。此值不能为负数，值为 0 表示没有全局限制。
relationshipWeightProperty	字符串	`null`	是	用作权重的关系属性名称。如果未指定，算法将以无权重方式运行。
similarityMetric	字符串	`JACCARD`	是	用于计算相似度的度量。可以是 `JACCARD`、`OVERLAP` 或 `COSINE`。
useComponents	布尔值或字符串	`false`	是	如果启用，节点相似度将使用组件来提高计算性能，跳过不同组件中节点的比较。设置为 `false`（默认）：算法不使用组件，但计算整个图的相似度。设置为 `true`：算法使用组件，并在计算相似度之前计算这些组件。设置为字符串：使用存储在图中的预计算组件，字符串是表示组件的节点属性的键。
sourceNodeFilter	整数或整数列表或字符串	`不适用`	否	要应用的源节点过滤器。接受单个节点 ID、节点 ID 列表或单个标签。
targetNodeFilter	整数或整数列表或字符串	`不适用`	否	要应用的目标节点过滤器。接受单个节点 ID、节点 ID 列表或单个标签。
2. 在 GDS 会话中，默认值为可用处理器数量。

表 7. 结果
名称	类型	描述
preProcessingMillis	整数	预处理数据所用的毫秒数。
computeMillis	整数	运行算法所用的毫秒数。
postProcessingMillis	整数	计算组件数量和分布统计信息所用的毫秒数。
nodesCompared	整数	计算相似度的节点数量。
similarityPairs	整数	结果中相似度的数量。
similarityDistribution	映射	包含计算出的相似度结果的最小值、最大值、平均值以及 p50、p75、p90、p95、p99 和 p999 百分位值的映射。
configuration	映射	运行算法所用的配置。

在命名图上以变异模式运行过滤后的节点相似度。

CALL gds.nodeSimilarity.filtered.mutate(
  graphName: String,
  configuration: Map
)
YIELD
  preProcessingMillis: Integer,
  computeMillis: Integer,
  mutateMillis: Integer,
  postProcessingMillis: Integer,
  relationshipsWritten: Integer,
  nodesCompared: Integer,
  similarityDistribution: Map,
  configuration: Map

表 8. 参数
名称	类型	默认值	可选	描述
graphName	字符串	`不适用`	否	存储在目录中的图的名称。
configuration	映射	`{}`	是	算法特定和/或图过滤的配置。

表 9. 配置
名称	类型	默认值	可选	描述
mutateRelationshipType	字符串	`不适用`	否	用于写入投射图的新关系的关系类型。
mutateProperty	字符串	`不适用`	否	相似度分数写入 GDS 图中的关系属性。
nodeLabels	字符串列表	`['*']`	是	使用给定的节点标签过滤命名图。
relationshipTypes	字符串列表	`['*']`	是	使用给定的关系类型过滤命名图。
concurrency	整数	`4`	是	运行算法时使用的并发线程数。
jobId	字符串	`内部生成`	是	可用于更轻松地跟踪算法进度的 ID。
similarityCutoff	浮点数	`1e-42`	是	相似度分数出现在结果中的下限。值必须介于 0 和 1 之间。
degreeCutoff	整数	`1`	是	节点度数的包含性下限，用于在比较中考虑节点。此值不能小于 1。
upperDegreeCutoff	整数	`2147483647`	是	节点度数的包含性上限，用于在比较中考虑节点。此值不能小于 1。
topK	整数	`10`	是	每个节点分数的限制。返回 K 个最大结果。此值不能小于 1。
bottomK	整数	`10`	是	每个节点分数的限制。返回 K 个最小结果。此值不能小于 1。
topN	整数	`0`	是	计算分数的全局限制。返回 N 个最大的总结果。此值不能为负数，值为 0 表示没有全局限制。
bottomN	整数	`0`	是	计算分数的全局限制。返回 N 个最小的总结果。此值不能为负数，值为 0 表示没有全局限制。
relationshipWeightProperty	字符串	`null`	是	用作权重的关系属性名称。如果未指定，算法将以无权重方式运行。
similarityMetric	字符串	`JACCARD`	是	用于计算相似度的度量。可以是 `JACCARD`、`OVERLAP` 或 `COSINE`。
useComponents	布尔值或字符串	`false`	是	如果启用，节点相似度将使用组件来提高计算性能，跳过不同组件中节点的比较。设置为 `false`（默认）：算法不使用组件，但计算整个图的相似度。设置为 `true`：算法使用组件，并在计算相似度之前计算这些组件。设置为字符串：使用存储在图中的预计算组件，字符串是表示组件的节点属性的键。
sourceNodeFilter	整数或整数列表或字符串	`不适用`	否	要应用的源节点过滤器。接受单个节点 ID、节点 ID 列表或单个标签。
targetNodeFilter	整数或整数列表或字符串	`不适用`	否	要应用的目标节点过滤器。接受单个节点 ID、节点 ID 列表或单个标签。

表 10. 结果
名称	类型	描述
`preProcessingMillis`	整数	预处理数据所用的毫秒数。
`computeMillis`	整数	运行算法所用的毫秒数。
`mutateMillis`	整数	将属性添加到投射图所用的毫秒数。
`postProcessingMillis`	整数	计算百分位数所用的毫秒数。
`nodesCompared`	整数	计算相似度的节点数量。
`relationshipsWritten`	整数	创建的关系数量。
`similarityDistribution`	映射	包含计算出的相似度结果的最小值、最大值、平均值、标准差以及 p1、p5、p10、p25、p75、p90、p95、p99、p100 百分位值的映射。
`configuration`	映射	运行算法所用的配置。

在命名图上以写入模式运行过滤后的节点相似度。

CALL gds.nodeSimilarity.filtered.write(
  graphName: String,
  configuration: Map
)
YIELD
 preProcessingMillis: Integer,
  computeMillis: Integer,
  writeMillis: Integer,
  postProcessingMillis: Integer,
  nodesCompared: Integer,
  relationshipsWritten: Integer,
  similarityDistribution: Map,
  configuration: Map

表 11. 参数
名称	类型	默认值	可选	描述
graphName	字符串	`不适用`	否	存储在目录中的图的名称。
configuration	映射	`{}`	是	算法特定和/或图过滤的配置。

表 12. 配置
名称	类型	默认值	可选	描述
nodeLabels	字符串列表	`['*']`	是	使用给定的节点标签过滤命名图。将包含具有任何给定标签的节点。
relationshipTypes	字符串列表	`['*']`	是	使用给定的关系类型过滤命名图。将包含具有任何给定类型的关系。
concurrency	整数	`4 ^[3]`	是	运行算法时使用的并发线程数。
jobId	字符串	`内部生成`	是	可用于更轻松地跟踪算法进度的 ID。
logProgress	布尔值	`true`	是	如果禁用，将不会记录进度百分比。
writeConcurrency	整数	`“concurrency”的值`	是	用于将结果写入 Neo4j 的并发线程数。
writeRelationshipType	字符串	`不适用`	否	用于在 Neo4j 数据库中持久化计算出的关系的关系类型。
writeProperty	字符串	`不适用`	否	相似度分数写入 Neo4j 数据库中的关系属性。
similarityCutoff	浮点数	`1e-42`	是	相似度分数出现在结果中的下限。值必须介于 0 和 1 之间。
degreeCutoff	整数	`1`	是	节点度数的包含性下限，用于在比较中考虑节点。此值不能小于 1。
upperDegreeCutoff	整数	`2147483647`	是	节点度数的包含性上限，用于在比较中考虑节点。此值不能小于 1。
topK	整数	`10`	是	每个节点分数的限制。返回 K 个最大结果。此值不能小于 1。
bottomK	整数	`10`	是	每个节点分数的限制。返回 K 个最小结果。此值不能小于 1。
topN	整数	`0`	是	计算分数的全局限制。返回 N 个最大的总结果。此值不能为负数，值为 0 表示没有全局限制。
bottomN	整数	`0`	是	计算分数的全局限制。返回 N 个最小的总结果。此值不能为负数，值为 0 表示没有全局限制。
relationshipWeightProperty	字符串	`null`	是	用作权重的关系属性名称。如果未指定，算法将以无权重方式运行。
similarityMetric	字符串	`JACCARD`	是	用于计算相似度的度量。可以是 `JACCARD`、`OVERLAP` 或 `COSINE`。
useComponents	布尔值或字符串	`false`	是	如果启用，节点相似度将使用组件来提高计算性能，跳过不同组件中节点的比较。设置为 `false`（默认）：算法不使用组件，但计算整个图的相似度。设置为 `true`：算法使用组件，并在计算相似度之前计算这些组件。设置为字符串：使用存储在图中的预计算组件，字符串是表示组件的节点属性的键。
sourceNodeFilter	整数或整数列表或字符串	`不适用`	否	要应用的源节点过滤器。接受单个节点 ID、节点 ID 列表或单个标签。
targetNodeFilter	整数或整数列表或字符串	`不适用`	否	要应用的目标节点过滤器。接受单个节点 ID、节点 ID 列表或单个标签。
3. 在 GDS 会话中，默认值为可用处理器数量。

表 13. 结果
名称	类型	描述
preProcessingMillis	整数	预处理数据所用的毫秒数。
computeMillis	整数	运行算法所用的毫秒数。
writeMillis	整数	将结果数据写回 Neo4j 所用的毫秒数。
postProcessingMillis	整数	计算百分位数所用的毫秒数。
nodesCompared	整数	计算相似度的节点数量。
relationshipsWritten	整数	创建的关系数量。
similarityDistribution	映射	包含计算出的相似度结果的最小值、最大值、平均值、标准差以及 p1、p5、p10、p25、p75、p90、p95、p99、p100 百分位值的映射。
configuration	映射	运行算法所用的配置。

示例

以下所有示例都应在一个空数据库中运行。

这些示例通常使用Cypher 投射。原生投射将在未来的版本中弃用。

在本节中，我们将展示在具体图上运行过滤后的节点相似度算法的示例。目的是说明结果的样式，并提供在实际环境中如何使用该算法的指南。我们将在一个由少量节点以特定模式连接的小型知识图上进行此操作。示例图如下所示：

以下 Cypher 语句将在 Neo4j 数据库中创建示例图：

CREATE
  (alice:Person:Singer {name: 'Alice'}),
  (bob:Person:Singer {name: 'Bob'}),
  (carol:Person:Singer {name: 'Carol'}),
  (dave:Person {name: 'Dave'}),
  (eve:Person:Singer {name: 'Eve'}),
  (guitar:Instrument {name: 'Guitar'}),
  (synth:Instrument {name: 'Synthesizer'}),
  (bongos:Instrument {name: 'Bongos'}),
  (trumpet:Instrument {name: 'Trumpet'}),

  (alice)-[:LIKES]->(guitar),
  (alice)-[:LIKES]->(synth),
  (alice)-[:LIKES {strength: 0.5}]->(bongos),
  (bob)-[:LIKES]->(guitar),
  (bob)-[:LIKES]->(synth),
  (carol)-[:LIKES]->(bongos),
  (dave)-[:LIKES]->(guitar),
  (dave)-[:LIKES]->(synth),
  (dave)-[:LIKES]->(bongos);

这个二分图有两个节点集：Person 节点和 Instrument 节点。其中一些 Person 节点也是歌手。这两个节点集通过 LIKES 关系连接。每个关系都从一个 Person 节点开始，并在一个 Instrument 节点结束。

过滤后的节点相似度算法将只计算度数至少为 1 的节点的相似度。因此，Eve 将不包含在结果中，因为她的度数为零。

以下语句将投射图并将其存储在图目录中。

MATCH (source)
OPTIONAL MATCH (source:Person|Singer)-[r:LIKES]->(target:Instrument)
RETURN gds.graph.project(
  'myGraph',
  source,
  target,
  {
    sourceNodeLabels: labels(source),
    targetNodeLabels: labels(target),
    relationshipProperties: r { strength: coalesce(r.strength, 1.0) }
  }
)

在以下示例中，我们将演示在此图上使用过滤后的节点相似度算法。特别是，我们将应用 sourceNodeFilter 和 targetNodeFilter 过滤器，将相似度搜索严格限制为同时具有 Singer 标签的 Person 节点。

内存估算

首先，我们将使用 estimate 过程估算运行算法的成本。这可以在任何执行模式下完成。在本示例中，我们将使用 write 模式。估算算法有助于了解在图上运行算法对内存的影响。当您随后实际在某种执行模式下运行算法时，系统将执行估算。如果估算显示执行超出其内存限制的可能性非常高，则将禁止执行。要了解更多信息，请参阅自动估算和执行阻止。

有关 estimate 的更多详细信息，请参阅内存估算。

以下将估算运行算法的内存需求：

CALL gds.nodeSimilarity.filtered.write.estimate('myGraph', {
    writeRelationshipType: 'SIMILAR',
    writeProperty: 'score',
    sourceNodeFilter:'Singer',
    targetNodeFilter:'Singer'
})
YIELD nodeCount, relationshipCount, bytesMin, bytesMax, requiredMemory

表 14. 结果
nodeCount	relationshipCount	bytesMin	bytesMax	requiredMemory
9	9	2384	2600	"[2384 Bytes ... 2600 Bytes]"

流

在 stream 执行模式下，算法返回每个关系的相似度分数。这使我们能够直接检查结果或在 Cypher 中对其进行后处理，而不会产生任何副作用。

有关 stream 模式的更多详细信息，请参阅流。

以下将运行算法并流式传输结果：

CALL gds.nodeSimilarity.filtered.stream('myGraph', {sourceNodeFilter:'Singer' , targetNodeFilter:'Singer' } )
YIELD node1, node2, similarity
RETURN gds.util.asNode(node1).name AS Person1, gds.util.asNode(node2).name AS Person2, similarity
ORDER BY similarity DESCENDING, Person1, Person2

表 15. 结果
Person1	Person2	similarity
"Alice"	"Bob"	0.6666666666666666
"Bob"	"Alice"	0.6666666666666666
"Alice"	"Carol"	0.3333333333333333
"Carol"	"Alice"	0.3333333333333333

统计

在 stats 执行模式下，算法返回一行，其中包含算法结果的摘要。此执行模式没有副作用。通过检查 computeMillis 返回项来评估算法性能非常有用。在下面的示例中，我们将省略返回时间。该过程的完整签名可以在语法部分找到。

有关 stats 模式的更多详细信息，请参阅统计。

以下将运行节点相似度算法，并使用指定的过滤器返回统计和测量值形式的结果：

CALL gds.nodeSimilarity.filtered.stats('myGraph', {sourceNodeFilter:'Singer' , targetNodeFilter:'Singer' } )
YIELD nodesCompared, similarityPairs

表 16. 结果
nodesCompared	similarityPairs
3	4

变异

mutate 执行模式扩展了 stats 模式，并带有一个重要的副作用：用包含该关系相似度分数的新关系属性更新命名图。新属性的名称使用强制配置参数 mutateProperty 指定。结果是一行摘要，类似于 stats，但包含一些额外的指标。当多个算法结合使用时，mutate 模式特别有用。

有关 mutate 模式的更多详细信息，请参阅变异。

以下将运行算法，并将结果写回内存图：

CALL gds.nodeSimilarity.filtered.mutate('myGraph',{
    mutateRelationshipType: 'SIMILAR',
    mutateProperty: 'score',
    sourceNodeFilter:'Singer',
    targetNodeFilter:'Singer'
})

YIELD nodesCompared, relationshipsWritten

表 17. 结果
nodesCompared	relationshipsWritten
3	4

从结果可以看出，创建的关系数量与流式示例中的行数相同。

变异产生的关系始终是有向的，即使输入图是无向的。如果 a → b 是 a 的 topK，并且 b → a 对称地是 b 的 topK（或者 a → b 和 b → a 都是 topN），则看起来好像产生了无向关系。然而，它们只是独立产生的两个有向关系。

写入

write 执行模式为每对节点创建一个关系，并将它们的相似度分数作为属性写入 Neo4j 数据库。新关系的类型使用强制配置参数 writeRelationshipType 指定。新属性的名称使用强制配置参数 writeProperty 指定。结果是一行摘要，类似于 stats，但包含一些额外的指标。

有关 write 模式的更多详细信息，请参阅写入。

以下将运行算法并写回结果：

CALL gds.nodeSimilarity.filtered.write('myGraph',{
    writeRelationshipType: 'SIMILAR',
    writeProperty: 'score',
    sourceNodeFilter:'Singer',
    targetNodeFilter:'Singer'
})
YIELD nodesCompared, relationshipsWritten

表 18. 结果
nodesCompared	relationshipsWritten
3	4

从结果中可以看出，创建的关系数量等于流式示例中的行数。

写入的关系始终是有向的，即使输入图是无向的。如果 a → b 是 a 的 topK，并且 b → a 对称地是 b 的 topK（或者 a → b 和 b → a 都是 topN），则看起来好像写入了无向关系。然而，它们只是独立写入的两个有向关系。