数据类型及其到 Cypher 类型的映射
本节中的表格显示了 Cypher 数据类型和 Java 类型之间的映射关系。
无论类型如何,查询结果中的所有值都嵌入在 Value
对象中。要提取它们并将其转换为相应的 Java 类型,请使用 .as<type>()
(例如 .asString()
、asInt()
等)。例如,如果来自数据库的 name
属性是字符串,则 record.get("name").asString()
将返回该属性值作为 String
对象。
另一方面,在提交查询参数时,您无需使用驱动程序类型。驱动程序将自动序列化作为参数传递的本机 Java 类型对象。
有关驱动程序将数据序列化到的值类型的完整列表,请参阅 API 文档。
时间类型
驱动程序提供了一组符合 ISO-8601 和 Cypher 的时间数据类型。亚秒级值测量到纳秒精度。
驱动程序的类型依赖于 Java 的 time
类型。所有时间类型,除了 DurationValue
,实际上都是底层 java.time
对象。这意味着:
-
如果您想使用时间类型查询数据库,请实例化一个
java.time
对象并将其用作查询参数(即,您无需关心驱动程序的类型)。 -
如果您从数据库检索一个时间对象(包括通过 Cypher 时间函数之一),您将获得下表中显示的相应驱动程序类型。驱动程序实现了将驱动程序时间类型转换为 Java 类型的方法(例如
.asZonedDateTime()
、.asOffsetTime()
等)。
Cypher 类型 | 驱动程序类型 |
---|---|
|
|
|
|
|
|
|
|
|
|
|
package demo;
import java.util.Map;
import java.time.ZonedDateTime;
import java.time.ZoneId;
import org.neo4j.driver.AuthTokens;
import org.neo4j.driver.Driver;
import org.neo4j.driver.GraphDatabase;
import org.neo4j.driver.QueryConfig;
public class App {
public static void main(String... args) {
final String dbUri = "{neo4j-database-uri}";
final String dbUser = "{neo4j-username}";
final String dbPassword = "{neo4j-password}";
try (var driver = GraphDatabase.driver(dbUri, AuthTokens.basic(dbUser, dbPassword))) {
driver.verifyConnectivity();
// Define a date, with timezone, and use it to set a relationship property
var friendsSince = ZonedDateTime.of(2016, 12, 16, 13, 59, 59, 9999999, ZoneId.of("Europe/Stockholm"));
var result = driver.executableQuery("""
MERGE (a:Person {name: $name})
MERGE (b:Person {name: $friend})
MERGE (a)-[friendship:KNOWS {since: $friendsSince}]->(b)
RETURN friendship.since AS date
""")
.withParameters(Map.of("name", "Alice", "friend", "Bob", "friendsSince", friendsSince))
.withConfig(QueryConfig.builder().withDatabase("neo4j").build())
.execute();
var date = result.records().get(0).get("date");
System.out.println(date.getClass().getName()); // org.neo4j.driver.internal.value.DateTimeValue
System.out.println(date); // 2016-12-16T13:59:59.009999999+01:00[Europe/Stockholm]
var nativeDate = date.asZonedDateTime();
System.out.println(nativeDate.getClass().getName()); // java.time.ZonedDateTime
}
}
}
DurationValue
表示两个时间点之间的差值(以月、天、秒、纳秒表示)。
// import org.neo4j.driver.Values;
var duration = Values.isoDuration(1, 2, 3, 4); // months, days, seconds, nanoseconds
System.out.println(duration); // P1M2DT3.000000004S
有关完整文档,请参阅 API 文档 → DurationValue。
空间类型
Cypher 支持空间值(点),Neo4j 可以将这些点值作为节点和关系的属性存储。
属性 SRID
(空间参考标识符的缩写)是一个数字,用于标识空间类型应在其中解释的坐标系统。您可以将其视为每个空间类型的唯一标识符。
Cypher 类型 | 驱动程序类型 | SRID |
---|---|---|
|
|
7203 |
|
|
4326 |
|
|
9157 |
|
|
4979 |
您可以通过 Values.point(srid, x, y[, z])
创建点值(第三个坐标是可选的)。从数据库查询返回的点是 PointValue
类型,可以通过 .asPoint()
方法转换为 Point
对象。
Point
值package demo;
import java.util.Map;
import org.neo4j.driver.AuthTokens;
import org.neo4j.driver.Driver;
import org.neo4j.driver.GraphDatabase;
import org.neo4j.driver.QueryConfig;
import org.neo4j.driver.Values;
public class App {
public static void main(String... args) {
final String dbUri = "{neo4j-database-uri}";
final String dbUser = "{neo4j-username}";
final String dbPassword = "{neo4j-password}";
try (var driver = GraphDatabase.driver(dbUri, AuthTokens.basic(dbUser, dbPassword))) {
driver.verifyConnectivity();
var result = driver.executableQuery("RETURN point({x: 2.3, y: 4.5, z: 2}) AS point")
.withConfig(QueryConfig.builder().withDatabase("neo4j").build())
.execute();
var point = result.records().get(0).get("point");
System.out.println(point); // Point{srid=9157, x=2.3, y=4.5, z=2.0}
System.out.println(point.asPoint().x()); // 2.3
}
}
}
Point
值并将其用作属性值package demo;
import java.util.Map;
import org.neo4j.driver.AuthTokens;
import org.neo4j.driver.Driver;
import org.neo4j.driver.GraphDatabase;
import org.neo4j.driver.QueryConfig;
import org.neo4j.driver.Values;
public class App {
public static void main(String... args) {
final String dbUri = "{neo4j-database-uri}";
final String dbUser = "{neo4j-username}";
final String dbPassword = "{neo4j-password}";
try (var driver = GraphDatabase.driver(dbUri, AuthTokens.basic(dbUser, dbPassword))) {
driver.verifyConnectivity();
var location = Values.point(4326, 67.28775180193841, 17.734163823312397); // 4326 = 2D geodetic point
var result = driver.executableQuery("CREATE (p:PlaceOfInterest {location: $location}) RETURN p")
.withParameters(Map.of("location", location))
.withConfig(QueryConfig.builder().withDatabase("neo4j").build())
.execute();
var place = result.records().get(0).get("p").get("location");
System.out.println(place); // Point{srid=4326, x=67.28775180193841, y=17.734163823312397}
System.out.println(place.asPoint().y()); // 17.734163823312397
}
}
}
图类型
图类型仅作为结果传递,不能用作参数.
Cypher 类型 | 驱动程序类型 |
---|---|
|
|
|
|
|
NodeValue
表示图中的一个节点。
方法 | 返回 |
---|---|
|
节点标签,作为列表。 |
|
节点属性,作为映射。 |
|
给定属性的值。 |
|
节点的字符串标识符。应谨慎使用此标识符,因为在单个事务范围之外,无法保证 ID 值和元素之间的映射。换句话说,在不同事务中使用 |
package demo;
import java.util.Map;
import org.neo4j.driver.AuthTokens;
import org.neo4j.driver.Driver;
import org.neo4j.driver.GraphDatabase;
import org.neo4j.driver.QueryConfig;
public class App {
public static void main(String... args) {
final String dbUri = "{neo4j-database-uri}";
final String dbUser = "{neo4j-username}";
final String dbPassword = "{neo4j-password}";
try (var driver = GraphDatabase.driver(dbUri, AuthTokens.basic(dbUser, dbPassword))) {
driver.verifyConnectivity();
// Get a node from the database
var result = driver.executableQuery("MERGE (p:Person:Actor {name: $name, age: 59}) RETURN p")
.withParameters(Map.of("name", "Alice"))
.withConfig(QueryConfig.builder().withDatabase("neo4j").build())
.execute();
// Extract node from result
var nodeVal = result.records().get(0).get("p");
var node = nodeVal.asNode(); // .asNode() -> type org.neo4j.driver.types.Node
System.out.printf("Labels: %s %n", node.labels());
System.out.printf("Properties: %s %n", node.asMap());
System.out.printf("Name property: %s %n", node.get("name"));
System.out.printf("Element ID: %s %n", node.elementId());
/*
Labels: [Person, Actor]
Properties: {name=Alice, age=59}
Name property: "Alice"
Element ID: 4:549a0567-2015-4bb6-a40c-8536bf7227b0:5
*/
}
}
}
有关完整文档,请参阅 API 文档 → NodeValue。
RelationshipValue
表示图中的一个关系。
方法 | 返回 |
---|---|
|
关系类型。 |
|
关系属性,作为映射。 |
|
给定属性的值。 |
|
起始节点的 |
|
结束节点的 |
|
关系的字符串标识符。应谨慎使用此标识符,因为在单个事务范围之外,无法保证 ID 值和元素之间的映射。换句话说,在不同事务中使用 |
package demo;
import java.util.Map;
import org.neo4j.driver.AuthTokens;
import org.neo4j.driver.Driver;
import org.neo4j.driver.GraphDatabase;
import org.neo4j.driver.QueryConfig;
public class App {
public static void main(String... args) {
final String dbUri = "{neo4j-database-uri}";
final String dbUser = "{neo4j-username}";
final String dbPassword = "{neo4j-password}";
try (var driver = GraphDatabase.driver(dbUri, AuthTokens.basic(dbUser, dbPassword))) {
driver.verifyConnectivity();
// Get a relationship from the database
var result = driver.executableQuery("""
MERGE (p:Person {name: $name})
MERGE (p)-[r:KNOWS {status: $status, since: date()}]->(friend:Person {name: $friendName})
RETURN r AS friendship
""")
.withParameters(Map.of("name", "Alice", "status", "BFF", "friendName", "Bob"))
.withConfig(QueryConfig.builder().withDatabase("neo4j").build())
.execute();
// Extract relationship from result
var relationshipVal = result.records().get(0).get("friendship");
var relationship = relationshipVal.asRelationship(); // .asRelationship() -> type org.neo4j.driver.types.Relationship
System.out.printf("Type: %s %n", relationship.type());
System.out.printf("Properties: %s %n", relationship.asMap());
System.out.printf("Status property: %s %n", relationship.get("status"));
System.out.printf("Start node: %s %n", relationship.startNodeElementId());
System.out.printf("End node: %s %n", relationship.endNodeElementId());
System.out.printf("Element ID: %s %n", relationship.elementId());
/*
Type: KNOWS
Properties: {since=2024-01-12, status=BFF}
Status property: "BFF"
Start node: 4:549a0567-2015-4bb6-a40c-8536bf7227b0:0
End node: 4:549a0567-2015-4bb6-a40c-8536bf7227b0:6
Element ID: 5:549a0567-2015-4bb6-a40c-8536bf7227b0:1
*/
}
}
}
有关完整文档,请参阅 API 文档 → RelationshipValue。
PathValue
表示图中的一个路径。
驱动程序将路径分解为(可迭代的)段,每个段由一个起始节点、一个关系和一个结束节点组成。可以通过 .start()
、.relationship()
和 .end()
方法按顺序检索段实体。
package demo;
import java.util.Map;
import org.neo4j.driver.AuthTokens;
import org.neo4j.driver.Driver;
import org.neo4j.driver.GraphDatabase;
import org.neo4j.driver.types.Path;
import org.neo4j.driver.QueryConfig;
public class App {
public static void main(String... args) {
final String dbUri = "{neo4j-database-uri}";
final String dbUser = "{neo4j-username}";
final String dbPassword = "{neo4j-password}";
try (var driver = GraphDatabase.driver(dbUri, AuthTokens.basic(dbUser, dbPassword))) {
driver.verifyConnectivity();
// Create some :Person nodes linked by :KNOWS relationships
addFriend(driver, "Alice", "BFF", "Bob");
addFriend(driver, "Bob", "Fiends", "Sofia");
addFriend(driver, "Sofia", "Acquaintances", "Sofia");
// Follow :KNOWS relationships outgoing from Alice three times, return as path
var result = driver.executableQuery("""
MATCH path=(:Person {name: $name})-[:KNOWS*3]->(:Person)
RETURN path AS friendshipChain
""")
.withParameters(Map.of("name", "Alice"))
.withConfig(QueryConfig.builder().withDatabase("neo4j").build())
.execute();
// Extract path from result
var pathVal = result.records().get(0).get("friendshipChain");
var path = pathVal.asPath(); // .asPath() -> type org.neo4j.driver.types.Path
System.out.println("-- Path breakdown --");
for (Path.Segment segment : path) {
System.out.printf(
"%s is friends with %s (%s).%n",
segment.start().get("name").asString(),
segment.end().get("name").asString(),
segment.relationship().get("status").asString());
}
/*
-- Path breakdown --
Alice is friends with Bob (BFF).
Bob is friends with Sofia (Fiends).
Sofia is friends with Sofia (Acquaintances).
*/
}
}
public static void addFriend(Driver driver, String name, String status, String friendName) {
driver.executableQuery("""
MERGE (p:Person {name: $name})
MERGE (p)-[r:KNOWS {status: $status, since: date()}]->(friend:Person {name: $friendName})
""")
.withParameters(Map.of("name", name, "status", status, "friendName", friendName))
.withConfig(QueryConfig.builder().withDatabase("neo4j").build())
.execute();
}
}
有关完整文档,请参阅 API 文档 → PathValue。
异常
驱动程序可能引发多种不同的异常,请参阅 API 文档 → 异常。有关服务器可能返回的错误列表,请参阅 状态码。
一些服务器错误被标记为可以安全重试,无需更改原始请求。此类错误的例子包括死锁、内存问题或连接问题。驱动程序实现 RetryableException
的异常意味着,导致该异常的操作如果再次尝试可能会成功。这在 显式事务 中运行查询时特别有用,可以判断失败的查询是否值得重新运行。
术语表
- LTS
-
长期支持版本是保证支持多年的版本。Neo4j 4.4 是 LTS 版本,Neo4j 5 也将有一个 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
对象包含与 Neo4j 数据库建立连接所需的详细信息。