性能建议

始终指定目标数据库

在所有查询中指定目标数据库，可以通过 ExecuteQuery() 中的 ExecuteQueryWithDatabase() 配置回调，或者在 创建新会话时使用 DatabaseName 配置参数来实现。如果不提供数据库，驱动程序必须向服务器发送额外的请求以确定默认数据库。对于单次查询，这种开销很小，但在数百次查询中会变得非常显著。

最佳实践

result, err := neo4j.ExecuteQuery(ctx, driver, "<QUERY>", nil,
    neo4j.EagerResultTransformer,
    neo4j.ExecuteQueryWithDatabase("<database-name>"))
session := driver.NewSession(ctx, neo4j.SessionConfig{
    DatabaseName: "<database-name>",
})

不良实践

result, err := neo4j.ExecuteQuery(ctx, driver, "<QUERY>", nil,
    neo4j.EagerResultTransformer)
session := driver.NewSession(ctx, neo4j.SessionConfig{})

了解事务的成本

当通过 .ExecuteQuery() 或 .ExecuteRead/Write() 提交查询时，驱动程序会将它们包装在 事务 中。这种行为确保了无论事务执行期间发生什么（停电、软件崩溃等），数据库始终处于一致的状态。作为进一步的健壮性层，驱动程序还会以指数退避策略重试失败的事务。

围绕查询创建安全的执行上下文会产生一定的开销，虽然很小，但随着事务数量的增加会累积。当每个查询都作为单独的事务发送时，如果一个事务失败并需要回滚，所有其他事务都不会受到影响。就故障而言，这是最安全的执行模式，但由于事务开销随查询数量线性增加，这也是最慢的模式。

每个查询作为一个单独的事务（低吞吐量）
for i := 0; i < 10000; i++ {
    neo4j.ExecuteQuery(ctx, driver, "<QUERY>", nil,
    neo4j.EagerResultTransformer,
    neo4j.ExecuteQueryWithDatabase("<database-name>"))
    // or session.executeRead/Write() calls
}

一种性能更高的做法是将所有查询组合到一个事务中。这样，整个事务与其他事务隔离，但事务中的单个查询并不相互隔离，其中一个查询失败会导致所有查询回滚。

将查询组合为一个事务（高吞吐量）
session := driver.NewSession(ctx, neo4j.SessionConfig{DatabaseName: "<database-name>"})
defer session.Close(ctx)
res, err := session.ExecuteRead(ctx, func(tx neo4j.ManagedTransaction) (any, error) {
    for i := 0; i < 10000; i++ {
        tx.Run(ctx, "<QUERY>", nil)
    }
    return nil, nil
})

一种更快的方法是跳过 .ExecuteRead/Write()，直接在会话上调用 .Run()。查询将作为自动提交事务运行，它们仍然与其他并发查询隔离，但如果其中任何一个失败，则不会重试。通过这种方法，您是用一定的健壮性换取了更高的吞吐量，因为查询会以服务器所能处理的最快速度发送过去。客户端规模的一个上限由连接池大小决定：每次调用 .Run() 都会借用一个连接，因此并行工作的数量受限于可用连接的数量。

查询作为自动提交事务（最高吞吐量）
session := driver.NewSession(ctx, neo4j.SessionConfig{DatabaseName: "<database-name>"})
defer session.Close(ctx)
for i := 0; i < 10000; i++ {
    session.Run(ctx, "<QUERY>", nil)
}

不要一次性获取大量结果集

当提交可能导致大量记录的查询时，请勿一次性全部检索。Neo4j 服务器可以分批检索记录，并在它们可用时将其流式传输给驱动程序。对结果进行惰性加载（Lazy-loading）可以分散网络流量和内存使用。

为方便起见，.ExecuteQuery() 总是会一次性检索所有结果记录（这就是 EagerResult 中 Eager 的含义）。要对结果进行惰性加载，必须使用 .ExecuteRead/Write()（或其他手动处理的 事务 形式），并且不要在结果上调用 .Collect(ctx)；请改为对其进行迭代。

示例 1. 预加载与延迟加载的比较
预加载 (Eager loading) 延迟加载 (Lazy loading)

  • 服务器必须从存储中读取所有 250 条记录，然后才能将第一条发送给驱动程序（即客户端接收第一条记录所需的时间更长）。

  • 在任何记录可供应用程序使用之前，驱动程序必须接收全部 250 条记录。

  • 客户端必须在内存中保留所有 250 条记录。

  • 服务器读取第一条记录并将其发送给驱动程序。

  • 一旦传输了第一条记录，应用程序就可以处理记录。

  • 剩余记录的等待时间和资源消耗推迟到应用程序请求更多记录时。

  • 服务器的获取时间可以用于客户端处理。

  • 资源消耗受驱动程序获取大小 (fetch size) 的限制。
预加载与延迟加载的时间和内存比较
package main

import (
    "context"
    "time"
    "fmt"
    "github.com/neo4j/neo4j-go-driver/v6/neo4j"
)

// Returns 250 records, each with properties
// - `output` (an expensive computation, to slow down retrieval)
// - `dummyData` (a list of 10000 ints, about 8 KB).
var slowQuery = `
UNWIND range(1, 250) AS s
RETURN reduce(s=s, x in range(1,1000000) | s + sin(toFloat(x))+cos(toFloat(x))) AS output,
range(1, 10000) AS dummyData
`
// Delay for each processed record
var sleepTime = "0.5s"

func main() {
    ctx := context.Background()
    dbUri := "<database-uri>"
    dbUser := "<username>"
    dbPassword := "<password>"
    driver, err := neo4j.NewDriver(
        dbUri,
        neo4j.BasicAuth(dbUser, dbPassword, ""))
    if err != nil {
        panic(err)
    }
    defer driver.Close(ctx)

    err = driver.VerifyConnectivity(ctx)
    if err != nil {
        panic(err)
    }

    log("LAZY LOADING (executeRead)")
    lazyLoading(ctx, driver)

    log("EAGER LOADING (executeQuery)")
    eagerLoading(ctx, driver)
}

func lazyLoading(ctx context.Context, driver neo4j.Driver) {
    defer timer("lazyLoading")()

    sleepTimeParsed, err := time.ParseDuration(sleepTime)
    if err != nil {
        panic(err)
    }

    session := driver.NewSession(ctx, neo4j.SessionConfig{DatabaseName: "<database-name>"})
    defer session.Close(ctx)
    session.ExecuteRead(ctx,
        func(tx neo4j.ManagedTransaction) (any, error) {
            log("Submit query")
            result, err := tx.Run(ctx, slowQuery, nil)
            if err != nil {
                return nil, err
            }
            for result.Next(ctx) != false {
                record := result.Record()
                output, _ := record.Get("output")
                log(fmt.Sprintf("Processing record %v", output))
                time.Sleep(sleepTimeParsed)  // proxy for some expensive operation
            }
            return nil, nil
        })
}

func eagerLoading(ctx context.Context, driver neo4j.Driver) {
    defer timer("eagerLoading")()

    log("Submit query")
    result, err := neo4j.ExecuteQuery(ctx, driver,
        slowQuery,
        nil,
        neo4j.EagerResultTransformer,
        neo4j.ExecuteQueryWithDatabase("<database-name>"))
    if err != nil {
        panic(err)
    }

    sleepTimeParsed, err := time.ParseDuration(sleepTime)
    if err != nil {
        panic(err)
    }

    // Loop through results and do something with them
    for _, record := range result.Records {
        output, _ := record.Get("output")
        log(fmt.Sprintf("Processing record %v", output))
        time.Sleep(sleepTimeParsed)  // proxy for some expensive operation
    }
}

func log(msg string) {
    fmt.Println("[", time.Now().Unix(), "] ", msg)
}

func timer(name string) func() {
    start := time.Now()
    return func() {
        fmt.Printf("-- %s took %v --\n\n", name, time.Since(start))
    }
}
输出
[ 1718802595 ]  LAZY LOADING (executeRead)
[ 1718802595 ]  Submit query
[ 1718802595 ]  Processing record 0.5309371354666308  (1)
[ 1718802595 ]  Processing record 1.5309371354662915
[ 1718802596 ]  Processing record 2.5309371354663197
...
[ 1718802720 ]  Processing record 249.53093713547042
-- lazyLoading took 2m5.467064085s --

[ 1718802720 ]  EAGER LOADING (executeQuery)
[ 1718802720 ]  Submit query
[ 1718802744 ]  Processing record 0.5309371354666308  (2)
[ 1718802744 ]  Processing record 1.5309371354662915
[ 1718802745 ]  Processing record 2.5309371354663197
...
[ 1718802869 ]  Processing record 249.53093713547042
-- eagerLoading took 2m29.113482541s --  (3)
1 使用延迟加载，第一条记录可以更快地获取。
2 使用预加载，第一条记录在结果被消费时（即服务器检索完所有 250 条记录后）才可用。
3 使用预加载（eager loading）的总运行时间更长，因为客户端需要等到接收到最后一条记录，而使用惰性加载时，客户端可以在服务器获取后续记录的同时处理当前记录。通过惰性加载，客户端还可以在满足某些条件后停止请求记录（通过在 Result 对象上调用 .consume()），从而节省时间和资源。

驱动程序的 获取大小（fetch size） 会影响惰性加载的行为。它指示服务器流式传输等于获取大小数量的记录，然后等待客户端跟上，再获取并发送更多记录。

获取大小通常允许限制客户端端的内存消耗，特别是对于记录大小差异较小的结果。如果某条记录非常大，驱动程序仍然需要为整个对象分配空间，因此即使获取大小很小，内存使用量也可能很大。

另一方面，获取大小并不总是能限制服务器端的内存消耗：这取决于具体的查询。例如，带有 ORDER BY 的查询需要在记录流式传输给客户端之前，将整个结果集加载到内存中进行排序。

获取大小越小，客户端和服务器之间需要交换的消息就越多。特别是在服务器延迟较高的情况下，较小的获取大小可能会降低性能。

将读取查询路由到集群读取器

在集群中，将读取查询路由到任何读取器节点。您可以执行以下操作：

最佳实践

result, err := neo4j.ExecuteQuery(ctx, driver,
    "MATCH (p:Person) RETURN p", nil, neo4j.EagerResultTransformer,
    neo4j.ExecuteQueryWithDatabase("<database-name>"),
    neo4j.ExecuteQueryWithReadersRouting())
session := driver.NewSession(ctx, neo4j.SessionConfig{DatabaseName: "<database-name>"})
defer session.Close(ctx)
result, err := session.ExecuteRead(ctx,
    func(tx neo4j.ManagedTransaction) (any, error) {
        return tx.Run(ctx, "MATCH (p:Person) RETURN p", nil)
    })

不良实践

result, err := neo4j.ExecuteQuery(ctx, driver,
    "MATCH (p:Person) RETURN p", nil, neo4j.EagerResultTransformer,
    neo4j.ExecuteQueryWithDatabase("<database-name>"))
    // defaults to routing = writers
session := driver.NewSession(ctx, neo4j.SessionConfig{DatabaseName: "<database-name>"})
defer session.Close(ctx)
result, err := session.ExecuteWrite(ctx,  // don't ask to write on a read-only operation
    func(tx neo4j.ManagedTransaction) (any, error) {
        return tx.Run(ctx, "MATCH (p:Person) RETURN p", nil)
    })

创建索引

为经常进行过滤的属性创建索引。例如，如果您经常通过 name 属性查找 Person 节点，那么在 Person.name 上创建索引将非常有益。您可以使用 CREATE INDEX Cypher 子句为节点和关系创建索引。

// Create an index on Person.name
neo4j.ExecuteQuery(ctx, driver,
    "CREATE INDEX personName FOR (n:Person) ON (n.name)",
    nil, neo4j.EagerResultTransformer,
    neo4j.ExecuteQueryWithDatabase("<database-name>"))

有关更多信息，请参阅 搜索性能索引。

分析查询 (Profile queries)

分析您的查询 以定位可以改进性能的查询。您可以通过在查询前加上 PROFILE 来对其进行分析。服务器输出可通过 ResultSummary 对象上的 .Profile() 方法获取。

result, _ := neo4j.ExecuteQuery(ctx, driver,
    "PROFILE MATCH (p {name: $name}) RETURN p",
    map[string]any{
        "name": "Alice",
    },
    neo4j.EagerResultTransformer,
    neo4j.ExecuteQueryWithDatabase("<database-name>"))
fmt.Println(result.Summary.Profile().Arguments()["string-representation"])
/*
Planner COST
Runtime PIPELINED
Runtime version 5.0
Batch size 128

+-----------------+----------------+----------------+------+---------+----------------+------------------------+-----------+---------------------+
| Operator        | Details        | Estimated Rows | Rows | DB Hits | Memory (Bytes) | Page Cache Hits/Misses | Time (ms) | Pipeline            |
+-----------------+----------------+----------------+------+---------+----------------+------------------------+-----------+---------------------+
| +ProduceResults | p              |              1 |    1 |       3 |                |                        |           |                     |
| |               +----------------+----------------+------+---------+----------------+                        |           |                     |
| +Filter         | p.name = $name |              1 |    1 |       4 |                |                        |           |                     |
| |               +----------------+----------------+------+---------+----------------+                        |           |                     |
| +AllNodesScan   | p              |             10 |    4 |       5 |            120 |                 9160/0 |   108.923 | Fused in Pipeline 0 |
+-----------------+----------------+----------------+------+---------+----------------+------------------------+-----------+---------------------+

Total database accesses: 12, total allocated memory: 184
*/

如果某些查询太慢，以至于无法在合理的时间内运行，您可以在它们前面加上 EXPLAIN 而不是 PROFILE。这将返回服务器运行该查询所使用的计划，但不会执行它。服务器输出可通过 ResultSummary 对象上的 .Plan() 方法获取。

result, _ := neo4j.ExecuteQuery(ctx, driver,
    "EXPLAIN MATCH (p {name: $name}) RETURN p",
    map[string]any{
        "name": "Alice",
    },
    neo4j.EagerResultTransformer,
    neo4j.ExecuteQueryWithDatabase("<database-name>"))
fmt.Println(result.Summary.Plan().Arguments()["string-representation"])
/*
Planner COST
Runtime PIPELINED
Runtime version 5.0
Batch size 128

+-----------------+----------------+----------------+---------------------+
| Operator        | Details        | Estimated Rows | Pipeline            |
+-----------------+----------------+----------------+---------------------+
| +ProduceResults | p              |              1 |                     |
| |               +----------------+----------------+                     |
| +Filter         | p.name = $name |              1 |                     |
| |               +----------------+----------------+                     |
| +AllNodesScan   | p              |             10 | Fused in Pipeline 0 |
+-----------------+----------------+----------------+---------------------+

Total database accesses: ?
*/

指定节点标签

指定节点标签（node labels）。这使得查询规划器可以更高效地工作，并利用可用的索引。要了解如何组合标签，请参阅 Cypher → 标签表达式。

最佳实践

result, err := neo4j.ExecuteQuery(ctx, driver,
    "MATCH (p:Person|Animal {name: $name}) RETURN p",
    map[string]any{
        "name": "Alice",
    }, neo4j.EagerResultTransformer,
    neo4j.ExecuteQueryWithDatabase("<database-name>"))
session := driver.NewSession(ctx, neo4j.SessionConfig{DatabaseName: "<database-name>"})
defer session.Close(ctx)
result, err := session.Run(ctx,
    "MATCH (p:Person|Animal {name: $name}) RETURN p",
    map[string]any{
        "name": "Alice",
    })

不良实践

result, err := neo4j.ExecuteQuery(ctx, driver,
    "MATCH (p {name: $name}) RETURN p",
    map[string]any{
        "name": "Alice",
    }, neo4j.EagerResultTransformer,
    neo4j.ExecuteQueryWithDatabase("<database-name>"))
session := driver.NewSession(ctx, neo4j.SessionConfig{DatabaseName: "<database-name>"})
defer session.Close(ctx)
result, err := session.Run(ctx,
    "MATCH (p {name: $name}) RETURN p",
    map[string]any{
        "name": "Alice",
    })

批量创建数据

使用 WITH 和 UNWIND Cypher 子句，在创建大量记录时对查询进行批处理。

最佳实践

numbers := make([]int, 10000)
for i := range numbers { numbers[i] = i }
neo4j.ExecuteQuery(ctx, driver, `
    UNWIND $numbers AS node
    MERGE (:Number {value: node.value})
    `, map[string]any{
        "numbers": numbers,
    }, neo4j.EagerResultTransformer,
    neo4j.ExecuteQueryWithDatabase("<database-name>"))

不良实践

for i := 0; i < 10000; i++ {
    neo4j.ExecuteQuery(ctx, driver,
        "MERGE (:Number {value: $value})",
        map[string]any{
            "value": i,
        }, neo4j.EagerResultTransformer,
        neo4j.ExecuteQueryWithDatabase("<database-name>"))
}
将大量数据首次导入新数据库的最有效方式是使用 neo4j-admin database import 命令。

使用查询参数

始终使用 查询参数，而不是将值硬编码或连接到查询字符串中。除了防止 Cypher 注入外，这还能充分利用数据库查询缓存。

最佳实践

result, err := neo4j.ExecuteQuery(ctx, driver,
    "MATCH (p:Person {name: $name}) RETURN p",
    map[string]any{
        "name": "Alice",
    }, neo4j.EagerResultTransformer,
    neo4j.ExecuteQueryWithDatabase("<database-name>"))
session := driver.NewSession(ctx, neo4j.SessionConfig{DatabaseName: "<database-name>"})
defer session.Close(ctx)
session.Run(ctx, "MATCH (p:Person {name: $name}) RETURN p", map[string]any{
    "name": "Alice",
})

不良实践

result, err := neo4j.ExecuteQuery(ctx, driver,
    "MATCH (p:Person {name: 'Alice'}) RETURN p",
    // or "MATCH (p:Person {name: '" + name + "'}) RETURN p"
    nil, neo4j.EagerResultTransformer,
    neo4j.ExecuteQueryWithDatabase("<database-name>"))
session := driver.NewSession(ctx, neo4j.SessionConfig{DatabaseName: "<database-name>"})
defer session.Close(ctx)
session.Run(ctx, "MATCH (p:Person {name: $name}) RETURN p", nil)
           // or "MATCH (p:Person {name: '" + name + "'}) RETURN p"

并发

使用 并发模式。如果您在应用程序中并行化复杂且耗时的查询，这对性能的影响可能会更大，但如果您运行许多简单查询，影响则不会那么明显。

仅在需要时使用 MERGE 进行创建

Cypher 子句 MERGE 非常适合创建数据，因为它可以在存在给定模式的精确克隆时避免重复数据。然而，它要求数据库运行两个查询：首先需要 MATCH 该模式，然后（如果需要）才能 CREATE 它。

如果您已经知道插入的数据是新的，请避免使用 MERGE，直接使用 CREATE——这实际上将数据库查询的数量减半了。

过滤通知

过滤服务器应引发的通知的类别和/或严重级别。

术语表

LTS (长期支持版)

长期支持 (Long Term Support) 版本是保证在若干年内得到支持的版本。Neo4j 4.4 和 5.26 是 LTS 版本。

Aura

Aura 是 Neo4j 的全托管云服务。它提供免费和付费计划。

Cypher

Cypher 是 Neo4j 的图查询语言，允许您从数据库中检索数据。它就像 SQL，但专用于图数据库。

APOC

Awesome Procedures On Cypher (APOC) 是一个包含（许多）函数的库，这些函数在 Cypher 本身中难以轻松实现。

Bolt

Bolt 是用于 Neo4j 实例和驱动程序之间交互的协议。默认监听 7687 端口。

ACID

原子性 (Atomicity)、一致性 (Consistency)、隔离性 (Isolation)、持久性 (Durability) (ACID) 是保证数据库事务可靠处理的属性。符合 ACID 的 DBMS 确保即使发生故障，数据库中的数据也能保持准确和一致。

最终一致性

如果一个数据库能保证所有集群成员在某个时间点都存储了数据的最新版本，则该数据库具有最终一致性。

因果一致性

如果读写查询被集群中的每个成员以相同的顺序看到，则数据库具有因果一致性。这比最终一致性更强。

NULL

空标记不是一种类型，而是缺失值的占位符。更多信息，请参阅 Cypher → 使用 null。

事务

事务是一个工作单元，要么被提交，要么在失败时被回滚。例如银行转账：它涉及多个步骤，但它们必须全部成功或全部撤销，以避免钱从一个账户扣除却未存入另一个账户的情况。

背压

背压是对数据流的抵抗力。它确保客户端不会被过快发送的数据压垮，从而超出其处理能力。

书签

书签是代表数据库某种状态的标记。通过将一个或多个书签与查询一起传递，服务器将确保在所表示的状态建立之前，该查询不会被执行。

事务函数

事务函数是由 ExecuteRead 或 ExecuteWrite 调用执行的回调。如果发生服务器故障，驱动程序会自动重新执行该回调。

驱动程序 (Driver)

Driver 对象包含与 Neo4j 数据库建立连接所需的详细信息。