开发与测试¶

本文档描述了Interactive的源代码组织结构，并提供了如何从源码构建Interactive以及运行测试的指南。

开发环境¶

在从源代码构建Interactive之前，您需要配置一个包含各种依赖项的开发环境。这里我们提供两种选择：在本地机器上安装所有依赖项，或在提供的Docker镜像中进行构建。

在本地安装依赖¶

交互式源代码应兼容并可在大多数现代Linux发行版上安装，包括Debian、RedHat和Ubuntu（已在Ubuntu 22.04上测试），支持x86和ARM平台。如果您在系统编译或安装过程中遇到任何问题，请在Github仓库提交问题。

注意

目前无法在macOS上从源代码编译Interactive，主要原因是某些依赖项（seastar）与macOS不兼容。

要在本地机器上安装所有依赖项，请使用命令行工具脚本gsctl.py运行以下代码。

python3 gsctl.py install-deps dev

在Docker容器中开发¶

我们提供了一个包含所有工具和依赖项的Docker镜像graphscope-dev。

docker run -it registry.cn-hongkong.aliyuncs.com/graphscope/graphscope-dev:latest

或者您可以在开发容器中打开GraphScope的代码库。

理解代码库¶

交互式系统由两部分组成，执行引擎和前端编译器。

交互式查询引擎¶

交互式查询引擎的代码组织在flex文件夹中，结构如下：

codegen: 该仓库构建的二进制文件gen_code_from_plan能够从物理计划生成C++代码。
engines:
- engines/graph_db: 提供GraphDB的接口和实现，用于管理图存储。
- engines/hqps_db: 包含图查询引擎的实现、数据结构以及物理算子。
- engines/http_server: 包含基于Seastar httpd的HTTP服务器，并在hiactor中定义智能体。
interactive: 包含与产品相关的组件。
- interactive/docker: 用于交互式环境的Dockerfile。
- interactive/examples: 图定义示例和原始数据。
- interactive/openapi/openapi_interactive: Interactive服务的RESTful API的OpenAPI规范。
storages:
- storages/metadata: 元数据存储的实现。
- storages/immutable_graph: 不可变图存储的实现。
- storages/rt_mutable_graph: 基于mutable_csr实现的可变图存储。
tests: 包含测试用例和脚本。
third_party: 包含第三方依赖项。
utils: 实用工具类和函数。

依赖关系图¶

交互式遵循GraphScope Flex的积木式构建理念，由多个模块组成。依赖关系图展示了这些模块之间的关联，但为了清晰起见，仅包含了部分第三方依赖项。

Dependency Graph between modules — 模块间的依赖关系图¶

编译器¶

编译器在交互式查询中至关重要，它能将用图查询语言（Cypher/Gremlin）编写的图查询通过GAIA IR转换为物理查询计划。编译器代码位于interactive_engine/compiler目录。有关编译器的更多详细信息，请参阅此文档

构建交互式¶

首先，构建交互式查询引擎。

git clone https://github.com/alibaba/GraphScope # or replace with your own forked repo
cd GraphScope 
git submodule update --init
cd flex
mkdir build && cd build
cmake ..
make -j

然后，构建编译器。

cd interactive_engine
mvn clean package -DskipTests -Pexperimental

CMake选项¶

BUILD_TEST: 表示是否构建测试。
BUILD_DOC: 表示是否构建Flex文档。
BUILD_ODPS_FRAGMENT_LOADER: 支持从ODPS表加载图数据。
USE_PTHASH: 表示在构建顶点映射时是否使用完美哈希。
OPTIMIZE_FOR_HOST: 决定是否针对当前机器的性能优化Flex。请注意，启用此选项可能导致生成的二进制文件无法在其他平台或CPU架构上运行。

测试¶

我们为Interactive创建了大量测试用例，可在GitHub工作流interactive.yaml中查阅。以下是一个用于验证SDK和交互式管理服务准确性的基础测试用例。

首先，需要创建一个目录作为交互式工作区，然后继续创建一个名为modern_graph的新图并将数据导入该图。

# Clone the testing data
export GS_TEST_DIR=/tmp/gstest
git clone -b master --single-branch --depth=1 https://github.com/GraphScope/gstest.git ${GS_TEST_DIR}

export GITHUB_WORKSPACE=/path/to/GraphScope
export FLEX_DATA_DIR=${GITHUB_WORKSPACE}/flex/interactive/examples/modern_graph
export TMP_INTERACTIVE_WORKSPACE=/tmp/interactive_workspace
cd ${GITHUB_WORKSPACE}/flex/build/

# Create interactive workspace
mkdir -p ${TMP_INTERACTIVE_WORKSPACE}
SCHEMA_FILE=${GITHUB_WORKSPACE}/flex/interactive/examples/modern_graph/graph.yaml
BULK_LOAD_FILE=${GITHUB_WORKSPACE}/flex/interactive/examples/modern_graph/bulk_load.yaml

# Create a directory to put modern_graph's schema.yaml and graph data
mkdir -p ${TMP_INTERACTIVE_WORKSPACE}/data/modern_graph/
cp ${SCHEMA_FILE} ${TMP_INTERACTIVE_WORKSPACE}/data/modern_graph/graph.yaml

# Load data to modern_graph
GLOG_v=10 ./bin/bulk_loader -g ${SCHEMA_FILE} -l ${BULK_LOAD_FILE} -d ${TMP_INTERACTIVE_WORKSPACE}/data/modern_graph/indices/

工作空间类似于数据库的数据目录，用于存储元数据和图数据。以下是一个示例。

/tmp/temp_workspace
├── data
│   ├── 1 -> /tmp/temp_workspace/data/modern_graph
│   ├── 2
│   └── modern_graph
└── METADATA
    ├── GRAPH_META
    ├── INDICES_LOCK
    ├── JOB_META
    ├── PLUGIN_META
    ├── PLUGINS_LOCK
    └── RUNNING_GRAPH

随后，执行hqps_admin_test.sh脚本来测试交互式管理服务的功能。

cd ${GITHUB_WORKSPACE}/flex/tests/hqps
# Change the default_graph field to 
bash hqps_admin_test.sh ${TMP_INTERACTIVE_WORKSPACE} ./interactive_config_test.yaml ${GS_TEST_DIR}

interactive_config_test.yaml 文件用于指定交互式服务的配置。

directories:
  workspace: /tmp/interactive_workspace # The workspace to start service on.
log_level: INFO
default_graph: modern_graph # The graph to serve at the beginning
compute_engine:
  type: hiactor
  workers:
    - localhost:10000
  thread_num_per_worker: 1
  store:
    type: cpp-mcsr
  metadata_store:
    type: file 
compiler: # Configurations for the Graph Compiler
  planner: 
    is_on: true
    opt: RBO
    rules:
      - FilterIntoJoinRule
      - FilterMatchRule
      - NotMatchToAntiJoinRule
  meta:
    reader:
      schema:
        uri: http://localhost:7777/v1/service/status
        interval: 1000 # ms
      statistics:
        uri: http://localhost:7777/v1/graph/%s/statistics
        interval: 86400000 # ms
  endpoint:
    default_listen_address: localhost
    bolt_connector:
      disabled: false
      port: 7687
    gremlin_connector:
      disabled: false
      port: 8182
  query_timeout: 40000
  gremlin_script_language_name: antlr_gremlin_calcite
http_service:
  default_listen_address: localhost
  admin_port: 7777
  query_port: 10000

手动启动服务¶

交互式功能的主要入口是 interactive_server。

启用AdminService¶

要在开发环境中启动管理服务，请使用命令行参数 --enable-admin-service true。${ENGINE_CONFIG} 指定交互式查询引擎的配置，详见 engine-configuration。${WORKSPACE} 指向维护交互相关数据的目录。

./bin/interactive_server -c ${ENGINE_CONFIG} -w ${WORKSPACE} --enable-admin-service true

启动编译器服务¶

编译器服务可以作为AdminService的子进程启动。这确保了在AdminService中切换图时，编译器服务也会切换到相应图的模式。这是当前Interactive中的默认行为。

./bin/interactive_server -c ${ENGINE_CONFIG} -w ${WORKSPACE} --enable-admin-service true --start-compiler true

错误代码¶

运行时错误会被分类、分配错误代码，并包含在HTTP响应体中（仅针对非200的HTTP响应）。状态码与HTTP代码的映射关系如下表所示。

代码	HTTP状态码
成功(0)	200
无效参数(2)	400
不支持的操作(11)	400
未找到(4)	404
已存在(5)	409
权限拒绝(8)	403
代码生成错误(100)	500
无效模式(101)	400
非法操作(102)	400
内部错误(103)	500
无效的导入文件(104)	400
IO错误(105)	500
查询失败(106)	500
默认	500