Skip to main content

交互工具（客户端 | API）

交互工具（客户端 | API）​

ArcGraph 图数据库提供了丰富的交互工具，包括多元化的客户端工具以及功能强大的 RESTful API 接口，以满足不同用户的开发与管理需求，确保用户能够轻松、高效地与 ArcGraph 图数据库进行深度交互。

客户端类型​

  • ArcGraph 图开发平台

    ArcGraph 图开发平台是 Fabarta 公司精心打造的一款图数据库操作工具。它采用直观的可视化图形界面，极大地简化了图模型设计、分析画布以及图数据管理等图数据开发流程。ArcGraph 图开发平台提供了可视化和 Console 两种操作界面，以满足不同用户的工作习惯和需求，为图数据开发带来了极大的便利与灵活性。

  • 客户端 CLI

    ArcGraph 图数据库提供了一款名为 ArcGraph CLI 的客户端 CLI 工具。ArcGraph CLI 是一个功能强大的命令行工具，用户可以通过它连接 ArcGraph 图数据库并执行 Cypher 语句，为开发者提供了便捷的图数据库操作体验。

  • 客户端 SDK

    为了方便开发者在特定编程语言中集成 ArcGraph 图数据库，我们提供了多种语言的客户端 SDK，包括：

    • ArcGraph Java SDK：用于在 Java 应用中访问和操作 ArcGraph 图数据库。
    • ArcGraph Python SDK：适用于 Python 开发者，帮助用户构建基于 ArcGraph 的图数据应用。

客户端下载​

客户端 CLI客户端 SDK
下载地址v2.1.1
v2.1.0		Java
Python
参考文档客户端 CLI 参考文档客户端 SDK 参考文档（Java）
客户端 SDK 参考文档（Python）

版本兼容性​

为确保用户能够正确选择和配置与 ArcGraph 图数据库兼容的客户端工具，以下提供了各客户端工具与 ArcGraph 图数据库不同版本之间的兼容性列表。

ArcGraph 图数据库版本客户端 CLI客户端 SDK（Java）客户端 SDK（Python）
v2.1.3-v2.1.3-
v2.1.2-v2.1.2-
v2.1.1v2.1.1v2.1.1v2.1.1
v2.1.0_hav2.1.0v2.1.0_hav2.1.0
v2.1.0v2.1.0v2.1.0v2.1.0

RESTful API​

自 ArcGraph v2.1.2 版本起，ArcGraph 图数据库提供强大的 RESTful API 支持，允许用户通过 HTTP 请求与数据库进行高效、灵活的交互，实现图数据库的登录、图数据查询功能等操作，详情请参见 RESTful API章节。

客户端 CLI​

ArcGraph CLI（Command Line Interface，命令行界面）是一个命令行工具，用于连接 ArcGraph 图数据库，执行 Cypher 语句。ArcGraph CLI 与 ArcGraph 图数据库的版本兼容性信息以及各版本的下载链接，请参见 交互工具（客户端 | API） 章节。请根据您的 ArcGraph 图数据库版本，选择并下载相应版本的 ArcGraph CLI。以下将以 ArcGraph CLI v2.1.0 版本为例，为您详细介绍其使用方法。

下载二进制程序​

Mac 用户手册​

下载 (适用于 M1/M2/M3 芯片)​
  1. 打开终端。
  2. 使用以下命令下载程序： 
    curl -O http://dl.infra.fabarta.com/arcgraph/cli/mac/v2.1.0/arcgraph_client_m1
安装​

设置下载文件的可执行权限：

chmod +x arcgraph_client_m1
运行​

在终端中，运行以下命令来启动程序：

./arcgraph_client_m1 -u arcgraph -p arcgraph -e localhost:8182

详细说明

  • -u：输入 ArcGraph Server 的用户名。
  • -p：输入 ArcGraph Server 的密码。
  • -e：输入客户端连接的 ArcGraph Server 地址。

Linux 用户手册​

下载​

  1. 打开终端。

  2. 输入以下命令以下载程序：

    wget http://dl.infra.fabarta.com/arcgraph/cli/linux/v2.1.0/arcgraph_client
安装​

为下载的文件设置可执行权限：

chmod +x arcgraph_client
运行​

在终端中，运行以下命令来启动程序：

./arcgraph_client -u arcgraph -p arcgraph -e localhost:8182

详细说明

  • -u：输入 ArcGraph Server 的用户名。
  • -p：输入 ArcGraph Server 的密码。
  • -e：输入客户端连接的 ArcGraph Server 地址。

Windows 用户手册​

下载​

单击 Windows版下载链接 下载安装包到您的计算机。

安装​

在大多数情况下，Windows 不需要特别设置可执行权限。

运行​

在安装包存放路径下打开 Windows 终端(cmd.exe)，并运行以下命令来运行程序：

./arcgraph_client.exe -u arcgraph -p arcgraph -e localhost:8182

详细说明

  • -u：输入 ArcGraph Server 的用户名。
  • -p：输入 ArcGraph Server 的密码。
  • -e：输入客户端连接的 ArcGraph Server 地址。

通用说明​

  • 如果您在安装或运行程序时遇到任何问题，请确保您的操作系统是最新的，并检查您是否有足够的权限来安装和运行软件。
  • 对于详细的使用说明和命令选项，请参阅随软件提供的文档或访问软件的官方网站。

ArcGraph RESTful Service​

ArcGraph RESTful Service 是 ArcGraph 图数据库的 HTTP 服务，支持通过 RESTful API 来操作图数据库。请注意，该功能仅 ArcGraph v2.1.0 和 v2.1.1 版本支持，自 v2.1.2 版本起，该功能已全面升级为独立的 RESTful API 功能，详情请见详情请参见 RESTful API 章节。

下载 ArcGraph RESTful Service​

单击 链接，获取 ArcGraph RESTful Service 程序包。

部署 ArcGraph RESTful Service​

ArcGraph RESTful Service 支持直接下载程序包并使用 Java 进行安装或通过 Docker 部署两种部署方式。

通过 Java 部署​

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

  1. 将 ArcGraph RESTful Service 工具下载至指定的目录下，例如，下载至“demosrv”目录下。
  2. 在“demosrv”目录下创建一个命名为“config.yaml”的配置文件，用于指定 ArcGraph 图数据库的地址。其内容示例如下，请根据实际情况将示例中的 localhost:8182 替换为实际的 ArcGraph 地址，如果需要配置多个地址，则可以用逗号（“,”）进行分隔。
    • 单个地址 
      server: "localhost:8182"
    • 多个地址 
      server: "localhost:8182,localhost2:8182,localhost3:8182"
  3. 在终端中运行如下命令，启动服务。 
    java -jar ./arcgraph-restapi-service-2.1.0_HA-SNAPSHOT.jar

通过 Docker 部署​

  1. 创建一个命名为“config.yaml”的配置文件，用于指定 ArcGraph 图数据库的地址。其内容示例如下，请根据实际情况将示例中的 localhost:8182 替换为实际的 ArcGraph 地址，如果需要配置多个地址，则可以用逗号（“,”）进行分隔。
    • 单个地址 
      server: "localhost:8182"
    • 多个地址 
      server: "localhost:8182,localhost2:8182,localhost3:8182"
  2. 若“config.yaml”所在的位置为“/tmp/config.yaml”，则在终端中运行以下命令启动 Docker 容器。ArcGraph 的 RESTful 服务将在容器的 8080 端口运行，并映射到主机的 9090 端口。 
    docker run --mount type=bind,source=/tmp/config.yaml,target=/config.yaml -p 9090:8080 docker-reg.infra.fabarta.com:5000/fabarta/arcgraph/restfulsrv:v2.1.0_HA

使用 ArcGraph RESTful Service​

请求授权​

在访问服务时，用户的请求需要携带鉴权头部信息，头部信息格式如下：

语法

Authorization: <base64Token>

详细说明
<base64Token>：表示 <arcgraphUsername>:<arcgraphPassword> （即“登录用户名:登录密码”）的 Base64 编码。

示例
用户名密码为“arcgraph/arcgraph”时，HTTP 请求头需要携带鉴权信息如下：

Authorization: YXJjZ3JhcGg6YXJjZ3JhcGg=

访问 RESTful 服务​

  • 示例 1
    操作具体某个图: /db/{db}/tx/commit。
    POST 请求为：

    {
        "statements": [
            {
                "statement": "show current graph"
            }
        ]
    }

    Response 示例为：

    {
        "results": [
            {
                "columns": [
                    "graph_id",
                    "graph_name"
                ],
                "rows": [
                    {
                        "values": [
                            {
                                "type": "INT64",
                                "value": 1079
                            },
                            {
                                "type": "STRING",
                                "value": "g1"
                            }
                        ]
                    }
                ]
            }
        ]
    }

  • 示例 2

    在未使用图的情况下进行操作：/tx/commit。
    POST 请求为：

    {
        "statements": [
            {
                "statement": "show graphs"
            }
        ]
    }

    Response 示例为：

    {
        "results": [
            {
                "columns": [
                    "Graph Name",
                    "Graph Id"
                ],
                "rows": [
                    {
                        "values": [
                            {
                                "type": "STRING",
                                "value": "SYSTEM"
                            },
                            {
                                "type": "INT64",
                                "value": 1
                            }
                        ]
                    },
                    {
                        "values": [
                            {
                                "type": "STRING",
                                "value": "demograph1"
                            },
                            {
                                "type": "INT64",
                                "value": 1077
                            }
                        ]
                    },
                    {
                        "values": [
                            {
                                "type": "STRING",
                                "value": "demograph2"
                            },
                            {
                                "type": "INT64",
                                "value": 1078
                            }
                        ]
                    },
                    {
                        "values": [
                            {
                                "type": "STRING",
                                "value": "g1"
                            },
                            {
                                "type": "INT64",
                                "value": 1079
                            }
                        ]
                    }
                ]
            }
        ]
    }

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 图数据库的版本兼容性信息以及各版本的下载链接，请参见 交互工具（客户端 | API） 章节。请根据您的 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_haAPI 文档

ArcGraph Python SDK​

概念说明​

以下是 ArcGraph Python SDK 中主要类的详细说明，旨在帮助用户更好地理解和使用这些类。

  • Client 类
    创建 Client 对象时，可配置多个参数，包括线程数（max_workers）、用户名（username）、密码（password）、图名称（graph_name，可选）以及高可用模式（ha，可选支持设置为 True 或 False）。当 ha 设置为 True 时，Client 在高可用（HA）环境中将自动寻找并连接到当前集群中的 Leader 服务器节点。

    创建 Client 对象语法如下：

    def __init__(self, url, max_workers=None, username="", password="", graph_name="", ha=None)

    Client 类定义的方法如下：

    • query 方法
      query 方法可以指定想要执行的 Cypher 语句以及超时时间（单位为秒，默认值为 300 秒），该方法返回结果为数组类型，数组中的每个元素为一个 ArcgraphRecord 对象。query 方法适用于同步阻塞且需保证顺序性的场景。

      def query(self, message, timeout=None)

    • submit 方法
      submit 方法将用户的语句提交至线程池执行，多个 submit 提交将无法保证执行的顺序性。该方法适用于并发执行且无需立即返回结果的场景，如需保证顺序，建议使用 query 方法。

      def submit(self, message, timeout=None)

  • ResultSet 类
    ResultSet 类定义的方法如下：

    • get_headers 方法
      get_headers 方法用于返回语句的表头信息，该方法仅在执行 all().result() 后才会返回有效的表头信息。

      def get_headers(self)

    • all 方法
      all 方法用于返回 future 对象，在调用 all() 之后调用 result 即可获得执行结果。

      def all(self)

  • ArcgraphRecord 类
    ArcgraphRecord 类定义的方法如下：

    • get_headers 方法
      get_headers 方法用于返回该记录的表头信息，结果为字符串数组。

      def get_headers(self)

    • get_values 方法
      get_values 方法用于返回该对象所表示的所有列信息。

      def get_values(self)

获取与安装​

SDK 下载​

ArcGraph Python SDK 与 ArcGraph 图数据库的版本兼容性信息以及各版本的下载链接，请参见 交互工具（客户端 | API） 章节。请根据您的操作系统和 ArcGraph 图数据库的具体版本，选择并下载相应版本的 Python SDK .whl 文件。

SDK 安装​

安装 ArcGraph Python SDK 前请确保系统已安装了 Python 3.8 及以上版本，并已获取 ArcGraph Python SDK .whl 文件。

打开命令行工具并进入到包含下载的 .whl 文件的目录下。执行如下命令，安装 ArcGraph Python SDK。

pip3 install <下载的whl文件名>.whl

应用示例​

创建客户端​

def get_client():
    host_url = "localhost:8182"
    user = "arcgraph"
    password = "arcgraph"
    return Client(host_url, max_workers=4, username=user, password=password)

管理图​

管理图，包括创建图、查看图及删除不再需要的图等。

from arcgraph.client import Client

def get_client():
    host_url = "dockersrvip:8182"
    user = "arcgraph"
    password = "arcgraph"
    return Client(host_url, pool_size=4, max_workers=4, username=user, password=password)

def main():
    client = get_client()
    graph_name = "g1"
    stmts = [
        "drop graph if exists {0}".format(graph_name),
        "create graph {0}".format(graph_name),
        "use graph {0}".format(graph_name),
        "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\"}),(:person{id:2,name:\"name2\"})",
        "insert (:person{id:1})-[:knows{weight:100}]->(:person{id:2})"
    ]
    for stmt in stmts:
        client.query(stmt)
        
    records = client.query("desc vertex person")
    headers = records[0].get_headers()
    print(str(headers))
    for record in records:
        values = record.get_values()
        print(str(values))
    client.close()

管理点/边类型​

管理点/边类型，包括创建、查看及删除点/边类型等。

from arcgraph.client import Client

def get_client():
    host_url = "dockersrvip:8182"
    user = "arcgraph"
    password = "arcgraph"
    return Client(host_url, pool_size=4, max_workers=4, username=user, password=password)

def main():
    client = get_client()
    graph_name = "g1"
    stmts = [
        "drop graph if exists {0}".format(graph_name),
        "create graph {0}".format(graph_name),
        "use graph {0}".format(graph_name),
        "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\"}),(:person{id:2,name:\"name2\"})",
        "insert (:person{id:1})-[:knows{weight:100}]->(:person{id:2})"
    ]
    for stmt in stmts:
        client.query(stmt)
        
    records = client.query("desc vertex person")
    headers = records[0].get_headers()
    print(str(headers))
    for record in records:
        values = record.get_values()
        print(str(values))
    client.query("use graph {0}".format(graph_name))
    client.query("drop edge knows")
    client.query("drop vertex person cascade")
    client.query("drop graph if exists {0}".format(graph_name))
    client.close()

if __name__ == "__main__":
    main()

新增点/边数据​

from arcgraph.client import Client

def get_client():
    host_url = "dockersrvip:8182"
    user = "arcgraph"
    password = "arcgraph"
    return Client(host_url, pool_size=4, max_workers=4, username=user, password=password)

def main():
    client = get_client()
    graph_name = "g1"
    stmts = [
        "drop graph if exists {0}".format(graph_name),
        "create graph {0}".format(graph_name),
        "use graph {0}".format(graph_name),
        "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\"}),(:person{id:2,name:\"name2\"})",
        "insert (:person{id:1})-[:knows{weight:100}]->(:person{id:2})"
    ]
    for stmt in stmts:
        client.query(stmt)
    client.close()

if __name__ == "__main__":
    main()

查看点/边数据​

from arcgraph.client import Client

def get_client():
    host_url = "dockersrvip:8182"
    user = "arcgraph"
    password = "arcgraph"
    return Client(host_url, pool_size=4, max_workers=4, username=user, password=password)

def main():
    client = get_client()
    graph_name = "g1"
    stmts = [
        "drop graph if exists {0}".format(graph_name),
        "create graph {0}".format(graph_name),
        "use graph {0}".format(graph_name),
        "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\"}),(:person{id:2,name:\"name2\"})",
        "insert (:person{id:1})-[:knows{weight:100}]->(:person{id:2})"
    ]
    for stmt in stmts:
        client.query(stmt)
        
    records = client.query("match (n:person) return n")
    headers = records[0].get_headers()
    print(str(headers))
    for record in records:
        values = record.get_values()
        print(str(values))

    records = client.query("match (a:person)-[e:knows]->(b:person) return e")
    headers = records[0].get_headers()
    print(str(headers))
    for record in records:
        values = record.get_values()
        print(str(values))
    client.close()

if __name__ == "__main__":
    main()

查看路径数据​

from arcgraph.client import Client

def get_client():
    host_url = "dockersrvip:8182"
    user = "arcgraph"
    password = "arcgraph"
    return Client(host_url, pool_size=4, max_workers=4, username=user, password=password)

def main():
    client = get_client()
    graph_name = "g1"
    stmts = [
        "drop graph if exists {0}".format(graph_name),
        "create graph {0}".format(graph_name),
        "use graph {0}".format(graph_name),
        "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\"}),(:person{id:2,name:\"name2\"})",
        "insert (:person{id:1})-[:knows{weight:100}]->(:person{id:2})"
    ]
    for stmt in stmts:
        client.query(stmt)

    records = client.query("match path=(a:person)-[e:knows]->(b:person) return path")
    headers = records[0].get_headers()
    print(str(headers))
    for record in records:
        values = record.get_values()
        print(str(values))
    client.close()

if __name__ == "__main__":
    main()

查看带属性的路径数据​

from arcgraph.client import Client

def get_client():
    host_url = "dockersrvip:8182"
    user = "arcgraph"
    password = "arcgraph"
    return Client(host_url, pool_size=4, max_workers=4, username=user, password=password)

def main():
    client = get_client()
    graph_name = "g1"
    stmts = [
        "drop graph if exists {0}".format(graph_name),
        "create graph {0}".format(graph_name),
        "use graph {0}".format(graph_name),
        "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\"}),(:person{id:2,name:\"name2\"})",
        "insert (:person{id:1})-[:knows{weight:100}]->(:person{id:2})"
    ]
    for stmt in stmts:
        client.query(stmt)

    client.query('set session computing_enable_property=true')
    records = client.query("match path=(a:person)-[e:knows]->(b:person) return path")
    headers = records[0].get_headers()
    print(str(headers))
    for record in records:
        values = record.get_values()
        print(str(values))
    client.close()

if __name__ == "__main__":
    main()

查看图详情信息​

from arcgraph.client import Client

def get_client():
    host_url = "dockersrvip:8182"
    user = "arcgraph"
    password = "arcgraph"
    return Client(host_url, pool_size=4, max_workers=4, username=user, password=password)

def main():
    client = get_client()
    graph_name = "g1"
    client.query("drop graph if exists {0}".format(graph_name))
    client.query("create graph {0}".format(graph_name))
    records = client.query("desc graph {0} full".format(graph_name))
    headers = records[0].get_headers()
    print(str(headers))
    for record in records:
        values = record.get_values()
        print(str(values))
    client.close()

if __name__ == "__main__":
    main()

查看图中所有点类型​

  • 方法一：

    from arcgraph.client import Client

    def get_client():
        host_url = "dockersrvip:8182"
        user = "arcgraph"
        password = "arcgraph"
        return Client(host_url, pool_size=4, max_workers=4, username=user, password=password)

    def main():
        client = get_client()
        client.set_graph("demo")
        records = client.query("show vertexes")
        headers = records[0].get_headers()
        print(str(headers))
        for record in records:
            values = record.get_values()
            print(str(values))
        client.close()

    if __name__ == "__main__":
        main()

  • 方法二：

    from arcgraph.client import Client

    def get_client():
        host_url = "dockersrvip:8182"
        user = "arcgraph"
        password = "arcgraph"
        return Client(host_url, pool_size=4, max_workers=4, username=user, password=password)

    def main():
        client = get_client()
        client.set_graph("demo")
        records = client.query("show full vertexes")
        headers = records[0].get_headers()
        print(str(headers))
        for record in records:
            values = record.get_values()
            print(str(values))
        client.close()

    if __name__ == "__main__":
        main()

查看图中所有边类型​

  • 方法一：

    from arcgraph.client import Client

    def get_client():
        host_url = "dockersrvip:8182"
        user = "arcgraph"
        password = "arcgraph"
        return Client(host_url, pool_size=4, max_workers=4, username=user, password=password)

    def main():
        client = get_client()
        client.set_graph("demo")
        records = client.query("show edges")
        if len(records) > 0:
            headers = records[0].get_headers()
            print(str(headers))
            for record in records:
                values = record.get_values()
                print(str(values))
        client.close()

    if __name__ == "__main__":
        main()

  • 方法二：

    from arcgraph.client import Client

    def get_client():
        host_url = "dockersrvip:8182"
        user = "arcgraph"
        password = "arcgraph"
        return Client(host_url, pool_size=4, max_workers=4, username=user, password=password)

    def main():
        client = get_client()
        client.set_graph("demo")
        records = client.query("show full edges")
        if len(records) > 0:
            headers = records[0].get_headers()
            print(str(headers))
            for record in records:
                values = record.get_values()
                print(str(values))
        client.close()

    if __name__ == "__main__":
        main()

查看点类型详情​

  • 方法一：

    def main():
        client = get_client()
        client.set_graph("demo")
        records = client.query("desc vertex person")
        headers = records[0].get_headers()
        print(str(headers))
        for record in records:
            values = record.get_values()
            print(str(values))
        client.close()

  • 方法二：

    from arcgraph.client import Client

    def get_client():
        host_url = "dockersrvip:8182"
        user = "arcgraph"
        password = "arcgraph"
        return Client(host_url, pool_size=4, max_workers=4, username=user, password=password)

    def main():
        client = get_client()
        client.set_graph("demo")
        records = client.query("desc vertex person")
        headers = records[0].get_headers()
        print(str(headers))
        for record in records:
            values = record.get_values()
            print(str(values))
        client.close()

    if __name__ == "__main__":
        main()

查看边类型详情​

  • 方法一：

    def main():
        client = get_client()
        client.set_graph("demo")
        records = client.query("desc edge knows")
        headers = records[0].get_headers()
        print(str(headers))
        for record in records:
            values = record.get_values()
            print(str(values))
        client.close()

  • 方法二：

    from arcgraph.client import Client

    def get_client():
        host_url = "dockersrvip:8182"
        user = "arcgraph"
        password = "arcgraph"
        return Client(host_url, pool_size=4, max_workers=4, username=user, password=password)

    def main():
        client = get_client()
        client.set_graph("demo")
        records = client.query("desc edge knows")
        headers = records[0].get_headers()
        print(str(headers))
        for record in records:
            values = record.get_values()
            print(str(values))
        client.close()

    if __name__ == "__main__":
        main()

相关说明​

ArcGraph 图数据库侧值类型说明​

在 ArcGraph Python SDK 中，ArcGraph 图数据库侧值类型通过 ValueType 枚举类进行定义，涵盖了基础数据类型、复杂数据类型以及图特定的数据类型。ArcGraph 图数据库侧的类型在 ArcGraph Python SDK 中定义如下：

class ValueType(StrEnum):
    NONE_TYPE_KEY = 'None'
    ARRAY_STRING_TYPE_KEY = 'ArrayString'
    ARRAY_INT32_TYPE_KEY = 'ArrayInt32'
    ARRAY_INT64_TYPE_KEY = 'ArrayInt64'
    ARRAY_UINT32_TYPE_KEY = 'ArrayUInt32'
    ARRAY_UINT64_TYPE_KEY = 'ArrayUInt64'
    ARRAY_F32_TYPE_KEY = 'ArrayF32'
    BOOLEAN_TYPE_KEY = 'Boolean'
    BYTE_TYPE_KEY = 'Byte'
    INT32_TYPE_KEY = 'Int32'
    INT64_TYPE_KEY = 'Int64'
    TIMESTAMP_TYPE_KEY = 'Timestamp'
    DATE_TYPE_KEY = 'Date'
    TIME_TYPE_KEY = 'Time'
    DATETIME_TYPE_KEY = 'DateTime'
    UINT32_TYPE_KEY = 'UInt32'
    UINT64_TYPE_KEY = 'UInt64'
    FLOAT_TYPE_KEY = 'Float'
    DOUBLE_TYPE_KEY = 'Double'
    VERTEX_KEY_TYPE_KEY = 'VertexKey'
    EDGE_KEY_TYPE_KEY = 'EdgeKey'
    EDGE_TYPE_KEY = 'Edge'
    VERTEX_TYPE_KEY = 'Vertex'
    STRING_TYPE_KEY = 'String'
    PATH_TYPE_KEY = 'Path'
    PATH_WITH_PRO_TYPE_KEY = 'PathWithProperty'
    VECTOR_TYPE_KEY = 'Vector'
    JSON_TYPE_KEY = 'Json'
    BLOB_TYPE_KEY = 'Blob'
    UUID_TYPE_KEY = 'Uuid'
    TEXT_TYPE_KEY = 'Text'
    BIG_DECIMAL_TYPE_KEY = 'BigDecimal'
    SUB_PATH_TYPE_KEY = 'SubPath'
    GRAPH_SCHEMA_TYPE_KEY = 'value_graph_schema'
    VERTEX_SCHEMA_TYPE_KEY = 'value_vertex_schema'
    EDGE_SCHEMA_TYPE_KEY = 'edge_vertex_schema'

ArcGraph Python SDK 侧值类型说明​

Value 是所有值类型的父类，在 ArcGraph Python SDK 中主要用于引用 ArcGraph 图数据库返回的数据。它提供了一系列方法来检查值的类型，方法如下：

  • def value(self)：将 ArcGraph 返回的结果转换为 Python 的内置类型并返回。
  • def type(self)：返回 ArcGraph 图数据库侧的类型，该类型的具体值需参考 ValueType。
  • def has_null_value(self)：判断返回 Value 对象是否为 NullValue。
  • def has_boolean_value(self)：判断返回 Value 对象是否为 BooleanValue。
  • def has_number_value(self)：判断返回 Value 对象是否为 NumberValue。
  • def has_string_value(self)：判断返回 Value 对象是否为StringValue。
  • def has_array_value(self)：判断返回 Value 对象是否为 ArrayValue。
  • def has_vertex_value(self)：判断返回 Value 对象是否为 VertexValue。
  • def has_edge_value(self)：判断返回 Value 对象是否为 EdgeValue。
  • def has_vid_value(self)：判断返回 Value 对象是否为 VidValue。
  • def has_eid_value(self)：判断返回 Value 对象是否为 EidValue。
  • def has_path_value(self)：判断返回 Value 对象是否为 PathValue。
  • def has_subpath_value(self)：判断返回 Value 对象是否为 SubPathValue。
  • def has_path_with_property_value(self)：判断返回 Value 对象是否为 PathWithPropValue。
  • def has_graph_schema_value(self)：判断返回 Value 对象是否为 GraphSchemaValue。
  • def has_vertex_schema_value(self)：判断返回 Value 对象是否为 VertexSchemaValue。
  • def has_edge_schema_value(self)：判断返回 Value 对象是否为 EdgeSchemaValue。

Value 是所有值类型的父类，包含的具体值类型如下：

  • NullValue

    NullValue 表示返回值缺失，ArcGraph 图数据库中的任何缺失值都将被转换为 ArcGraph Python SDK 中的 NullValue。具体方法如下：

    • def __str__(self)：返回 NullValue 的字符串结果，返回值为 None。
    • def value(self)：返回 NullValue 在 Python 运行环境下的值，返回值为 None。
    • def has_null_value(self)：返回 True，表示此对象为 NullValue。

  • BooleanValue

    BooleanValue 表示返回值为布尔值，ArcGraph 图数据库中的布尔类型值将被转换为 ArcGraph Python SDK 中的 BooleanValue。具体方法如下：

    • def __str__(self)：返回 BooleanValue 的字符串结果，返回值为"True"或"False"。
    • def value(self)：返回 BooleanValue 在 Python 运行环境下的值（True或False）。
    • def has_boolean_value(self)：返回 True，表示此对象为 BooleanValue。

  • NumberValue

    NumberValue 表示返回值为数值类型，ArcGraph 图数据库中的 Byte、Int32、Int64、Uint32、Uint64、Float、Double 以及 BigDecimal 类型，均会被转换为 ArcGraph Python SDK 中的 NumberValue。具体方法如下：

    • def __str__(self)：返回 NumberValue 的字符串结果。
    • def value(self)：返回 NumberValue 在 Python 运行环境下的数值类型。
    • def has_number_value(self)：返回 True，表示此对象为 NumberValue。

  • StringValue

    StringValue 表示返回值为字符串类型，ArcGraph 图数据库中的 String、Timestamp、Date、Time、Datetime、Json、Blob、Uuid 以及 Text 类型均会被转换为 ArcGraph Python SDK 中的 StringValue。具体方法如下：

    • def __str__(self)：返回 StringValue 的字符串结果。
    • def value(self)：返回 StringValue 在 Python 运行环境下的字符串类型。
    • def has_string_value(self)：返回 True，表示此对象为 StringValue。

  • ArrayValue

    ArrayValue 表示返回值为数组类型，ArcGraph 图数据库中的 ArrayString、ArrayInt32、ArrayInt64、ArrayUInt32、ArrayUInt64、ArrayF32 以及 Vector 类型均会被转换为 ArcGraph Python SDK 中的 ArrayValue。具体方法如下：

    • def __str__(self)：返回 ArrayValue 的字符串结果。
    • def value(self)：返回 ArrayValue 包含的所有 Value，结果类型为数组，数组中的每个元素为一个 Value 对象。
    • def has_array_value(self)：返回 True，表示此对象为 ArrayValue。

  • VertexValue
    VertexValue 表示图中的点类型，它对应于 ArcGraph 图数据库中的 Vertex Type 类型。

    • def __str__(self)：返回 VertexValue 的字符串结果。
    • def get_vid(self)：返回 VidValue 对象。
    • def get_properties(self)：返回属性数组，数组中的每个元素为一个 Value 对象。
    • def get_property_names(self)：返回属性名称数组，数组中的每个元素为字符串。
    • def get_type_name(self)：返回点类型的名称，例如 person。
    • def has_vertex_value(self)：返回True，表示此对象为 VertexValue。

  • VidValue
    VidValue 表示图中的点（Vertex）ID 类型，它对应于 ArcGraph 图数据库中的点 ID 类型。

    • def __str__(self)：返回 VidValue 的字符串结果。
    • def get_type_id(self)：返回 VidValue 对象的类型 ID 值。
    • def get_type_name(self)：返回 VidValue 对象的类型名称。
    • def value(self)：返回 VidValue 对象的 _oid 值。
    • def has_vid_value(self)：返回 True，表示此对象为 VidValue。

  • EdgeValue
    EdgeValue 表示图中的边类型，它对应于 ArcGraph 图数据库中的 Edge Type 类型。

    • def __str__(self)：返回 EdgeValue 的字符串结果。
    • def get_eid(self)：返回 EidValue 对象。
    • def get_properties(self)：返回属性数组，数组中的每个元素为一个 Value 对象。
    • def get_property_names(self)：返回属性名称数组，数组中的每个元素为字符串。
    • def get_type_name(self)：返回边类型的名称，例如 knows。
    • def has_edge_value(self)：返回 True，表示此对象为 EdgeValue。

  • EidValue
    EidValue 表示图中的边（Edge）ID 类型，它对应于 ArcGraph 图数据库中的边 ID 类型。

    • def __str__(self)：返回 EidValue 的字符串结果。
    • def get_src_vid(self)：返回起点 VidValue 对象。
    • def get_dst_vid(self)：返回终点 VidValue 对象。
    • def value(self)：返回 _oid。
    • def get_type_id(self)：返回类型的 ID。
    • def get_type_name(self)：返回类型的名称。
    • def get_ts(self)：返回 ts(rank)。
    • def has_eid_value(self)：返回 True，表示此对象为 EidValue。

  • PathValue
    PathValue 表示返回值为路径类型，它对应于 ArcGraph 图数据库中的 Path 类型。

    • def __str__(self)：返回 PathValue 的字符串结果。
    • def get_src_vid(self)：返回起点 VidValue。
    • def get_sub_paths(self)：返回 sub_paths，结果为数组，数组中的元素为 SubPathValue。
    • def has_path_value(self)：返回 True，表示此对象为 PathValue。

  • SubPathValue
    SubPathValue 表示返回值为子路径类型，它对应于 ArcGraph 图数据库中的 SubPath 类型。

    • def __str__(self)：返回 SubPathValue 的字符串结果。
    • def get_eid(self)：返回边 ID 值 EidValue。
    • def get_dst_vid(self)：返回目标点 ID 值 VidValue。
    • def has_subpath_value(self)：返回 True，表示此对象为 SubPathValue。

  • PathWithPropValue
    PathWithPropValue 表示返回值为带属性的路径类型，它对应于 ArcGraph 图数据库中的 PathWithProperty 类型。

    • def __str__(self)：返回 PathValue 的字符串结果。
    • def get_path(self)：返回 Path 值 PathValue。
    • def get_properties(self)：返回属性值，属性值为数组，数组中的元素为 Value 对象。
    • def has_path_with_property_value(self)：返回 True，表示此对象为 PathWithPropValue。

RESTful API​

自 ArcGraph v2.1.2 版本起，ArcGraph 图数据库新增了 RESTful API 功能，该功能为用户提供强大的 RESTful 接口支持，使用户可以通过 HTTP 请求与 ArcGraph 图数据库进行交互，极大提升了数据访问和操作的灵活性与效率。本章节将详细介绍 API 的主要接口及其使用方法，帮助用户高效地使用 ArcGraph 图数据库。

API 接口介绍​

登录接口 (POST /login)​

登录接口用于提供用户登录认证服务，支持通过用户名和密码进行登录，并返回访问 ArcGraph 图数据库的认证令牌（Token）用于后续请求的授权。

请求结构​

登录请求结构如下，其中 graph 字段为可选字段。

{
    "username":"arcgraph",
    "password":"arcgraph",
    "graph": "demo"
}
请求样例​

登录请求样例如下：

curl -H "Content-Type: application/json" -X POST -d '{"username": "arcgraph", "password":"arcgraph"}' "http://<ArcGraphServerIP>:<HttpPort>/login"

参数说明

参数说明
<ArcGraphServerIP>ArcGraph 服务器的 IP 地址。
<HttpPort>HTTP 服务的端口号，通常设置为 7001，可根据实际配置调整。
响应结构​

登录响应结构如下：

{"token":"<TokenResult>"}

参数说明

参数说明
<TokenResult>用于后续请求的认证令牌（Token）。有效期为 5 分钟，但每次使用 token 发起有效请求时，Token 的有效期会自动延长。

查询接口​

查询接口用于提供图数据查询功能，用户可以通过此接口执行 Cypher 查询语句，获取 ArcGraph 图数据库中的数据。

请求结构​

查询请求结构示例如下，该请求用于展示图数据库中所有图的名称。其中，statements 字段的值是一个数组且数组中的每个元素都是一个具体的查询语句。

{
    "statements": [
        {
            "statement": "show graphs"
        }
    ]
}
请求样例​

查询请求样例如下：

curl -H "Content-Type: application/json" -H "Authorization:<TokenResult>" -X POST -d '{"statements": [{"statement":"show graphs"}]}' "http://<ArcGraphServerIP>:<HttpPort>/tx/commit"

参数说明

参数说明
<TokenResult>认证令牌（Token），用于请求的授权验证，需从登录认证流程中获取。
<ArcGraphServerIP>ArcGraph 服务器的 IP 地址。
<HttpPort>HTTP 服务的端口号，通常设置为 7001，可根据实际配置调整。
响应结构​

查询响应结构如下：

{
    "results": [
        {
            "header": [
                "col1","col2","col3"
            ],
            "rows": [
                [
                    col1Value1,
                    col2Value1,
                    col3Value1,
                ],
                [
                    col1Value2,
                    col2Value2,
                    col3Value2,
                ]
            ]
        }
    ]
}

详细说明

  • results 字段是一个数组，该数组的每个元素与请求中的 statements 数组元素一一对应。每个查询结果包含 header 和 rows 字段。
  • header 字段是一个数组，表示查询结果的列名信息。
  • rows 字段是一个二维数组，表示查询的结果。它的每个子数组代表一行查询记录，子数组中的元素依次对应 header 中定义的列名所对应的结果值。

结果展示
为了更直观地理解查询结果，可以将上述查询结果以如下表格形式展示：

col1col2col3
col1Value1col2Value1col3Value1
col1Value2col2Value2col3Value2

响应码介绍​

在图数据库的 RESTful API 交互过程中，HTTP 响应码用于指示请求的状态和可能发生的错误。以下是几种常见的 HTTP 响应码及其在 ArcGraph 图数据库中对应的错误含义：

  • 200 OK：请求成功，未遇到任何错误。
  • 400 BadRequest：查询参数不正确（InvalidParameter），当请求中的查询参数存在语法错误或无效时返回该响应码。
  • 401 Unauthorized：鉴权失败（AuthFailed），当用户未提供有效凭证或凭证无效时返回该响应码。
  • 500 Internal Server Error：当服务器内部发生错误，无法完成请求时返回该响应码。

API 应用​

本章节以 Node.js 环境为例介绍 API 的应用方法。通过示例详细介绍在 Node.js 环境中如何使用 HTTP 客户端库（如 Node.js 内置的 http 模块）与 ArcGraph 图数据库进行 RESTful API 交互。操作前，请确保你的环境中已安装了 Node.js 和必要的 HTTP 请求库。

示例
通过以下 Node.js 脚本执行登录操作并获取 SHOW GRAPHS 的查询结果。

let http = require('http');

// Server Settings
const username = "arcgraph";
const password = "arcgraph";
const server_address = "<YourServerIP>";
const port = 7001;

(async () => {
    try {
        let login_resp = await login();
        let token = login_resp.token;
        let statements = [
            {
                statement: "show graphs"
            }
        ];
        let resp = await query(token, statements);
        let results = resp.results;
        // For the first query result
        let result = results[0];
        let header = result.header;
        let rows = result.rows;
        console.log(header);
        console.log(rows);
    } catch (e) {
        console.log('e:', e);
    }
})();

async function login() {
    let login_request = JSON.stringify({
        username,
        password,
    });
    let options = get_login_option(server_address, port);
    return await send_request(options, login_request);
}

async function query(token, statements) {
    let query_request = JSON.stringify({
        statements
    })
    let options = get_query_option(server_address, port, token);
    return await send_request(options, query_request);
}

async function send_request(options, data) {
    let promise = await new Promise((resolve, reject) => {
        let req = http.request(options, function (res) {
            if (res.statusCode != 200) { reject(res.statusMessage); }
            let _data = '';
            res.on('data', chunk =>  _data += chunk);
            res.on('end', () => resolve(JSON.parse(_data)));
            res.on('error', e => reject(e));
        });
        req.write(data);
        req.end();
    })
    .catch(err => {
        throw err
    });
    return promise
}

function get_json_post_options(host, port, headers, path) {
    return {
        host,
        port,
        path,
        method: 'POST',
        headers,
    };
}

function get_login_option(host, port) {
    let headers = {
        'Content-Type': 'application/json'
    };
    return get_json_post_options(host,port, headers, '/login');
}

function get_query_option(host, port, token) {
    let headers = {
        'Content-Type': 'application/json',
        'Authorization': token,
    };
    return get_json_post_options(host,port, headers, '/tx/commit');
}