用法

将 JDBC 驱动添加到您的应用程序中，例如作为 Gradle 依赖

示例 1. 在基于 Gradle 的项目中将完整包作为运行时依赖使用

dependencies {
    runtimeOnly(org.neo4j:neo4j-jdbc-full-bundle:6.9.1) (1)
}

1	对于 Maven 项目，坐标相同。

随后您可以像使用其他 JDBC 驱动一样使用 Neo4j JDBC 驱动

如果任何工具要求您提供具体驱动类的名称，则为 org.neo4j.jdbc.Neo4jDriver。

示例 2. 获取连接并执行查询

import java.sql.DriverManager;
import java.sql.SQLException;
import java.util.List;

public final class Quickstart {

    static void queryWithCypher() {
        var query = """
                MATCH (m:Movie)<-[:ACTED_IN]-(p:Person)
                RETURN m.title AS title, collect(p.name) AS actors
                ORDER BY m.title
                """;

        var url = "jdbc:neo4j://:7687/movies";
        var username = "neo4j";
        var password = "verysecret";

        try (var con = DriverManager.getConnection(url, username, password); (1)
                var stmt = con.createStatement();  (2)
                var result = stmt.executeQuery(query)) { (3)

            while (result.next()) { (4)
                var movie = result.getString(1); (5)
                var actors = (List<String>) result.getObject("actors"); (6)
                System.out.printf("%s%n", movie);
                actors.forEach(actor -> System.out.printf("\t * %s%n", actor));
            }
        }
        catch (SQLException ex) {
            throw new RuntimeException(ex);
        }
    }
}

1	实例化 JDBC 连接。无需预先加载任何类，驱动会自动注册
2	创建（可复用的）语句
3	执行查询
4	遍历结果，就像处理其他 JDBC 结果集一样
5	JDBC 的索引从 1 开始
6	JDBC 还允许按列名检索结果列；Neo4j JDBC 驱动也支持复杂对象，例如列表

在上述示例中，我们使用了 Neo4j 的 通用语言，Cypher^®，来查询数据库。Neo4j JDBC 驱动对使用 SQL 也有一定支持。它可以自动完成转换，也可以按需转换。若要翻译单个查询，请调用 java.sql.Connection#nativeSQL(String) 并在查询中使用返回值。若需自动转换，请实例化驱动并将可选的 URL 参数 sql2cypher 设置为 true。下面的示例展示了如何操作

示例 3. 配置 JDBC 驱动以自动将 SQL 转换为 Cypher。

var query = """
        SELECT m.title AS title, collect(p.name) AS actors
        FROM Person as p
        JOIN Movie as m ON (m.id = p.ACTED_IN)
        ORDER BY m.title
        """; (1)

var url = "jdbc:neo4j://:7687/movies?enableSQLTranslation=true";

try (var con = DriverManager.getConnection(url, username, password);
        var stmt = con.createStatement();
        var result = stmt.executeQuery(query)) {

    while (result.next()) {
        var movie = result.getString(1);
        var actors = (List<String>) result.getObject("actors");
        System.out.printf("%s%n", movie);
        actors.forEach(actor -> System.out.printf("\t * %s%n", actor));
    }
}

1	该 SQL 查询将被翻译为前例相同的 Cypher 查询。方法的其余部分与之前完全相同。

欲了解更多信息，请参见 SQL 到 Cypher 的转换。

JDBC 规范不支持命名参数，仅支持基于索引的参数，起始索引为 1。因此，对所有 PreparedStatement 实例，需要如下指定参数

示例 4. 在 PreparedStatement 中使用参数

var cypher = "CREATE (m:Movie {title: $1})";
try (var con = DriverManager.getConnection(url, username, password);
        PreparedStatement stmt = con.prepareStatement(cypher)) {
    stmt.setString(1, "Test");
    stmt.executeUpdate();
}

这与 SQL 到 Cypher 的转换机制无关

示例 5. 在 PreparedStatement 中使用参数（SQL 变体）

var sql = "INSERT INTO Movie (title) VALUES (?)";
try (var con = DriverManager.getConnection(url + "?enableSQLTranslation=true", username, password);
        PreparedStatement stmt = con.prepareStatement(sql)) {
    stmt.setString(1, "Test");
    stmt.executeUpdate();
}

若要使用命名参数，请将 PreparedStatement 强制转型为 Neo4jPreparedStatement。

示例 6. 使用 Neo4jPreparedStatement 的命名参数

var match = "MATCH (n:Movie {title: $title}) RETURN n.title AS title";
try (var con = DriverManager.getConnection(url, username, password);
        Neo4jPreparedStatement stmt = (Neo4jPreparedStatement) con.prepareStatement(match)) {
    stmt.setString("title", "Test");
    try (var resultSet = stmt.executeQuery()) {
        while (resultSet.next()) {
            LOGGER.info(resultSet.getString("title"));
        }
    }
}

通过环境变量获取连接

如果您愿意直接依赖 org.neo4j.jdbc.Neo4jDriver，并希望尽可能简便地获取连接，您可以使用 fromEnv

示例 7. 从环境变量获取连接

// import org.neo4j.jdbc.Neo4jDriver;

try (var con = Neo4jDriver.fromEnv().orElseThrow(); (1)
        var stmt = con.createStatement();
        var result = stmt.executeQuery(query)) {

    // Same loop as earlier
}
catch (SQLException ex) {
    throw new RuntimeException(ex);
}

1	请注意我们直接使用了具体的驱动类，并且这些方法返回的是 Optional：如果未找到所需的连接变量，则无法创建连接。

fromEnv 方法会查找若干特定的系统环境变量，并遵循 12-factor 应用的原则

首先，它在系统环境中查找
其次，它会在当前工作目录中查找名为 .env 的文件。还有重载方法，可让您配置要查找的目录和文件名。

支持的变量有

NEO4J_URI: 要连接的实例的地址或 URI。
NEO4J_USERNAME: （可选）用户名。
NEO4J_PASSWORD: （可选）密码。
NEO4J_SQL_TRANSLATION_ENABLED: （可选）是否启用完整的 SQL 到 Cypher 转换，默认值为 false。

系统环境和 .env 文件中的信息会合并。例如，如果 NEO4J_SQL_TRANSLATION_ENABLED 存在于系统环境中而不在 .env 文件中，它仍会被读取。由于优先级顺序，系统环境中的信息始终优先于 .env 文件。

此功能在 Neo4j AuraDB 中尤其有用。创建新的 AuraDB 实例时，您会下载一个 .env 文件，可直接与 Neo4j JDBC 驱动一起使用

示例 8. 使用来自 AuraDB 的 .env 文件

try (
    var con = Neo4jDriver.fromEnv("Neo4j-cb3d8b2d-Created-2024-02-14.txt")
        .orElseThrow();
    var stmt = con.createStatement();
    var movies = stmt.executeQuery("MATCH (n:Movie) RETURN n.title AS title")
) {
    while (movies.next()) {
        System.out.println(movies.getString("title"));
    }
}