ArcGraph Java SDK

概念说明

基本概念

Driver
Driver 类实例负责保存图数据库引擎的地址以及登录信息。创建 Driver 类实例的方法示例如下：
```
Driver driver = GraphDatabase.driver(serverAddress, AuthTokens.basic(userName, password));
```

Session
Session 的类实例对应图数据库引擎端的一个会话，创建 Session 类实例的方法示例如下：

# 创建一个不登录任何图的会话
Session session = driver.session();
# 创建一个登录“Demo”图的会话，如果该图不存在，则创建会话失败
Session session = driver.session("Demo");

Result
在 Session 实例上执行 Cypher 语句后，执行的结果将以 Result 实例的形式返回，示例如下：
```
Result result = session.run("match (n:person) return n order by n.id asc");
```
GraphRecord

图的查询结果可以表示为一个表，该表的每一行记录被表示为一个 GraphRecord。可以从 Result 中获取 GraphRecord ，示例如下：
```
List<GraphRecord> records = result.list();
```
Value
图查询的每一行结果表示为一个 GraphRecord，对于每一行查询结果中的某一列，其结果被表示为 Value，示例如下：
```
for (GraphRecord record : records) {
    // ....
    List<Value> values = record.values();
    // ....
}
```
根据 Value 所包含的具体类型，可以将 Value 的实例转换为更具体的类型，从而更深入地获取所需的信息。示例如下：
```
if (value.hasEdgeSchema()) {
    EdgeSchemaValue edgeSchemaValue = value.asEdgeSchema();
    //...
}
```

值结构概念

在 ArcGraph Java SDK 中，查询操作的输出结果存储在 Result 对象中，以便于用户高效、便捷地访问和处理查询结果。以下是对 Result 对象及其相关组件的详细说明，旨在帮助用户更好地理解其结构和使用方式。

Result 对象

在 ArcGraph Java SDK 中执行查询后返回的结果存储在 Result 对象中，每个 Result 对象对应表示一个结果集合，具体包含的内容示例如下。它内部主要包含列名称（Header）和所有行内容（Rows）两部分信息。这种结构类似于 {header:[...], rows:[...]}。
```
+--------+-------+-------+
| col1   | col2  | col3  |
+========+=======+=======+
| val11  | val12 | val13 |
+--------+-------+-------+
| val21  | val22 | val23 |
+--------+-------+-------+
|...                     |
+--------+-------+-------+
```
- Header：一个包含所有列名称的列表，用于标识每列数据的含义。
- Rows：一个包含多个 GraphRecord 对象的列表，每个 GraphRecord 代表结果集中的一行数据。
GraphRecord 对象

GraphRecord 对象用于表示结果集中的一行数据，它不仅包含了该行的实际值，还携带有列信息，以便于用户能够识别每个值的含义，其内部结构类似于 {header:[...], values:[...]}。GraphRecord 表示的一行数据可能存在多个列，其中每一列的值被抽象定义为 Value 对象。

GraphRecord 对象具体内容示例如下：
```
+--------+-------+-------+
| col1   | col2  | col3  |
+========+=======+=======+
| val11  | val12 | val13 |
+--------+-------+-------+
```
Value 对象

Value 对象用于表示 GraphRecord 中每个列的值。它可以表示基本类型（类似于 StringValue、DoubleValue），也可以表示复合类型（类似于 VertexValue、EdgeValue）。

Value 对象的典型用法如下，通过将 Value 类实例转换为特定的子类型，进而利用这些子类型提供的方法获取更多信息。
```
Value value = ...
if (value.hasVertexValue()) {
    VertexValue vertexValue = value.asVertexValue();
    // 调用VertexValue的更多方法来解析value的实际信息
}
```

环境准备

请确保已安装并运行 Java，Java 版本要求为 Java 8 及以上版本。

SDK 下载

ArcGraph Java SDK 与 ArcGraph 图数据库的版本兼容性信息以及各版本的下载链接，请参见客户端章节。请根据您的 ArcGraph 图数据库版本，选择并下载相应版本的 ArcGraph Java SDK。以下将以 ArcGraph Java SDK v2.1.0_ha 版本为例，为您详细介绍其使用方法。

请单击链接获取不含依赖的 ArcGraph Java SDK，若需包含依赖的版本请联系我们获取。在使用该库时需要将库文件下载到本地后引入工程，以 Maven 工程为例，若用户将该 Jar 文件放在工程的 libs 目录下，那么在 pom.xml 中需要添加依赖项，示例如下：

<dependency>
    <groupId>io.grpc</groupId>
    <artifactId>grpc-netty</artifactId>
    <version>1.58.0</version>
</dependency>
<dependency>
    <groupId>io.grpc</groupId>
    <artifactId>grpc-protobuf</artifactId>
    <version>1.58.0</version>
</dependency>
<dependency>
    <groupId>io.grpc</groupId>
    <artifactId>grpc-stub</artifactId>
    <version>1.58.0</version>
</dependency>
<dependency>
    <groupId>org.msgpack</groupId>
    <artifactId>msgpack-core</artifactId>
    <version>0.9.5</version>
</dependency>
<dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-lang3</artifactId>
    <version>3.13.0</version>
</dependency>
<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>fastjson</artifactId>
    <version>2.0.43</version>
</dependency>
<dependency>
    <groupId>com.fabarta.driver</groupId>
    <artifactId>arcgraph-java-driver</artifactId>
    <version>2.1.0_HA-SNAPSHOT</version>
    <scope>system</scope>
    <systemPath>${project.basedir}/libs/arcgraph-java-driver_slim.jar</systemPath>
</dependency>

样例工程

请单击链接获取 ArcGraph Java SDK 样例工程。

样例代码

ArcGraph Java SDK 样例代码如下所示：

示例 1
创建链接：

public class App 
{
    public static void main( String[] args ) {
        String serverAddress = "localhost:8182";
        String userName = "arcgraph";
        String password = "arcgraph";
        try (Driver driver = GraphDatabase.driver(serverAddress, AuthTokens.basic(userName, password))) {
            driver.verifyConnectivity();
        }
    }
}

示例 2
使用会话：

public class App
{
    public static void main( String[] args ) throws Exception {
        String serverAddress = "localhost:8182";
        String userName = "arcgraph";
        String password = "arcgraph";
        try (Driver driver = GraphDatabase.driver(serverAddress, AuthTokens.basic(userName, password))) {
            try (Session session = driver.session()) {
                String[] stmts = new String[] {
                    "DROP GRAPH IF EXISTS demograph",
                    "CREATE GRAPH IF NOT EXISTS demograph",
                    "use demograph",
                    "create vertex person(primary key id int(64), name string)",
                    "create edge knows(weight int(64), from person to person)",
                    "insert (:person{id:1, name: \"name1\"})",
                    "insert (:person{id:2, name: \"name2\"})",
                    "insert (:person{id:1})-[:knows{weight:100}]->(:person{id:2})",
                };
                for (String stmt : stmts) {
                    session.run(stmt);
                }
                Result result = session.run("match (n:person) return n.name as name");
                for (GraphRecord record : result.list()) {
                    String nameValue = record.get("name").asString();
                    System.out.println("nameValue => " + nameValue);
                }
                Result result2 = session.run("match (n:person) return n");
                for (GraphRecord record : result2.list()) {
                    VertexValue vertexValue = record.get("n").asVertex();
                    String nameValue = vertexValue.get("name").asString();
                    System.out.println("nameValue => " + nameValue);
                }

                Result result3 = session.run("match (:person)-[e:knows]->(:person) return e");
                for (GraphRecord record : result3.list()) {
                    EdgeValue edgeValue = record.get("e").asEdge();
                    long weight = edgeValue.get("weight").asInteger64();
                    System.out.println("weight => " + weight);
                }
            }
        }
    }
}

SDK API 调用

准备数据

在利用 ArcGraph Java SDK 执行 API 调用之前，请确保已在 ArcGraph 图数据库中定义了相应的图模式（Schema）并插入了必要的图数据。以下步骤展示了如何定义点类型、边类型以及插入点边数据的示例，这些数据将作为后续 API 调用操作的基础数据。

创建数据示例

#创建点类型
CREATE VERTEX person(PRIMARY KEY id INT(64), name STRING, address STRING);

#创建边类型
CREATE EDGE knows(weight INT(64), FROM person TO person);

#插入点边数据
INSERT (:person {id:1, name:"name1", address:"address 1"}), (:person {id:2, name:"name2", address:"address 2"});
INSERT (a:person {id:1})-[:knows {weight:101}]->(b:person {id:2});

Cypher 查询示例

点类型 person 查询示例

MATCH (n:person) RETURN n.id AS id, n.name AS name, n.address AS address ORDER BY n.id ASC;

返回结果示例：

+----+-------+-----------+
| id | name  | address   |
+====+=======+===========+
| 1  | name1 | address 1 |
+----+-------+-----------+
| 2  | name2 | address 2 |
+----+-------+-----------+

边类型 knows 查询示例

MATCH (a:person)-[e:knows]->(b:person) RETURN a.id AS fromPerson, b.id AS toPerson, e.weight AS weight;

返回结果示例：

+------------+----------+--------+
| fromPerson | toPerson | weight |
+============+==========+========+
| 1          | 2        | 101    |
+------------+----------+--------+

API 调用

ArcGraph Java SDK 将提供一套丰富的 API 来执行上述 Cypher 查询以及更复杂的图数据操作。以下章节将详细介绍 Result 类和 GraphRecord 类的使用方法。

Result 类的使用

Result 类用于表示用户执行 Cypher 语句后返回的结果集。以下将详细介绍 Result 类包含的主要方法及其使用场景示例。

List<String> keys()

List<String> keys() 方法用于返回结果集的表头（列名）列表。

Result result = session.run("match (n:person) return n.id as id, n.name as name, n.address as address");
for (String key : result.keys()) {
    System.out.println(key);
}
// 代码输出:
// id
// name
// address

Result result = session.run("match (n:person) return n");
for (String key : result.keys()) {
    System.out.println(key);
}
// 代码输出:
// n

boolean hasNext() 与 GraphRecord next()

boolean hasNext() 与 GraphRecord next() 这两个方法组合使用，允许开发者遍历结果集中的所有记录。boolean hasNext() 方法用于判断结果集是否还有下一条记录，而 GraphRecord next() 方法用于返回结果集的下一条记录。
```
Result result = session.run("match (n:person) return n");
while (result.hasNext()) {
    GraphRecord record = result.next();
    // 使用record...
}
```

GraphRecord single()

GraphRecord single() 方法用于返回结果集中的第一条记录。

Result result = session.run("match (n:person) return n");
GraphRecord record = result.single();
while (result.hasNext()) {
    GraphRecord record = result.next();
    // 使用record...
}

Stream<GraphRecord> stream()

Stream<GraphRecord> stream() 方法将以流结构返回结果集。

Result result = session.run("match (n:person) return n");
Stream<Value> values = result.stream().map(item -> item.values().get(0));
values.forEach(System.out::println);

List<GraphRecord> list()

List<GraphRecord> list() 方法将结果集中的所有记录收集到一个列表中，便于后续进行遍历或其他集合操作。

Result result = session.run("match (n:person) return n");
List<GraphRecord> graphRecordList = result.list();
for (GraphRecord record : graphRecordList) {
    System.out.println(record);
}

GraphRecord 的使用

GraphRecord 是 ArcGraph 图数据库查询结果中的基本数据单元，代表了一行查询结果。以下将详细介绍 GraphRecord 类包含的主要方法及其使用场景示例。

List<String> keys()

当结果记录为点边等复合类型时，List<String> keys() 方法用于返回属性列表。

Result result = session.run("match (n:person) return n order by n.id asc");
// 以上查询返回结果如下：
//    >> match (n:person) return n order by n.id asc;
//    start executing statement: match (n:person) return n order by n.id asc;
//    +-----------------------------------------------------------------------------------------------------+
//    | n                                                                                                   |
//    +=====================================================================================================+
//    | vid: [_oid: 36345892629905408, label: person], properties: [36345892629905408, 1, name1, address 1] |
//    +-----------------------------------------------------------------------------------------------------+
//    | vid: [_oid: 36345892629905409, label: person], properties: [36345892629905409, 2, name2, address 2] |
//    +-----------------------------------------------------------------------------------------------------+
GraphRecord record = result.single();
// record在此表示一行记录，包括header信息[n]
List<String> headers = record.keys();
// headers在此的结果为：[n]
List<Value> values = record.values();
// values在此表示一行的值类型，由于headers为[n]，也就是只有一列数据
Value value = values.get(0);
// value在此表示record的第一列数据，
// 又前文可知，该value表示的是一个Vertex记录，所以可以将其转换为Value类的子类型VertexValue
if (value.hasVertex()) {
    VertexValue vertexValue = value.asVertex();
    // VertexValue属于复合类型，可以获取该复合类型的属性列表，方法如下
    for (String propName : vertexValue.keys()) {
        System.out.println(propName);
    }
    // Person类型有内置属性_oid，以及用户定义的属性id, name, address，所以上面的代码输出为：
    // _oid
    // id
    // name
    // address
}

List<Value> values()

List<Value> values() 方法用于返回 GraphRecord 中所有列的值。
Value get(int index)
Value get(int index) 方法用于获取 GraphRecord 中指定索引位置（从 0 开始）的值。
Value get(String name)
Value get(String name) 方法用于获取 GraphRecord 中列名为 name 的值。

int index(String key)
int index(String key) 方法用于返回 GraphRecord 中列名为 key 的索引位置的信息。

Result result = session.run("match (n:person) return n.id as id, n.name as name, n.address as address order by n.id asc");
// 以上查询返回结果如下：
//    >> match (n:person) return n.id as id, n.name as name, n.address as address order by n.id asc;
//    start executing statement: match (n:person) return n.id as id, n.name as name, n.address as address order by n.id asc;
//    +----+-------+-----------+
//    | id | name  | address   |
//    +====+=======+===========+
//    | 1  | name1 | address 1 |
//    +----+-------+-----------+
//    | 2  | name2 | address 2 |
//    +----+-------+-----------+
GraphRecord record = result.single();
// 假设要获取name列的索引，则可以调用如下:
int nameIdx = record.index("name");
// 假设要获取name列的值，则可以调用如下:
Value nameValue = record.get(nameIdx);
// 已知name是String类型，所以可以获取其值如下:
if (nameValue.hasString()) {
    String nameStr = nameValue.asString();
    System.out.println(nameStr);
}
// 也可以直接通过列名称来获取值，方法如下：
Value nameValue2 = record.get("name");
if (nameValue2.hasString()) {
    String nameStr = nameValue2.asString();
    System.out.println(nameStr);
}

API 文档

我们提供了 ArcGraph Java SDK 各版本的 API 指导文档，旨在帮助用户快速掌握 ArcGraph Java SDK API 调用的方法。

版本	API 文档
2.1.0_ha	API 文档

概念说明​

基本概念​

值结构概念​

环境准备​

SDK 下载​

样例工程​

样例代码​

SDK API 调用​

准备数据​

API 调用​

Result 类的使用​

GraphRecord 的使用​

API 文档​