跳转到主要内容

Graphspace API

Graphspace（图空间）REST 接口：多租户与资源隔离的创建、查看、更新与删除，以及使用前置条件与限制。

2.0 Graphspace

在 HugeGraph 中，多租户是通过图空间（graph space）来实现的，资源的分配和隔离可以通过图空间进行。

重要前置条件：

  1. 目前图空间功能只支持在 hstore 模式下使用。
  2. 如果非 hstore 模式，则只能使用默认的图空间 DEFAULT，且不支持创建、删除和更新图空间的操作。
  3. 注意在 rest-server.properties 中，设置 usePD=true，并且 hugegraph.properties 中，设置 backend=hstore
  4. 生产环境必须启用 Server 认证与授权，并将新建图空间的 auth 设为 true。生产管理员密码必须替换公开默认值 pa（由 auth.admin_pa 配置）。
  5. 本页所有接口都只在 PD 模式下可用，单机模式下会返回 400 和 GraphSpace management is not supported in standalone mode 错误信息。
警告

限制图空间列表和详情接口的访问

GET /graphspaces 和 GET /graphspaces/{graphspace} 均未声明 @RolesAllowed；Server 未启用鉴权时这两个接口可匿名调用，启用鉴权后也没有方法级管理员角色限制。详情响应包含 dp_username 和 dp_password。生产环境必须将 white_ip.status 设为 enable 并通过 IP 白名单 API 启用、维护名单。网关必须按调用者身份或角色，仅允许管理员和可信运维调用方访问这两条路径；只限制来源 IP 范围仍会让同一网段的普通已认证业务账号读取 DP 凭据。Server 网络策略必须仅允许可信网关的出口地址访问 API 端口，阻断客户端绕过网关的直连路径。网关须记录这两条路径的调用身份、来源和结果；Server audit-*.log 用于鉴权授权记录，不能替代这两条路径的网关访问审计。业务账号须按最小权限授权。

2.0.1 创建一个图空间

Method & Url
1POST http://localhost:8080/graphspaces
Request Body

注意：目前 cpu，内存，以及 k8s 相关功能暂未开放

名称是否必填类型默认值取值范围说明
name是String小写字母、数字和下划线组成，首字符必须是小写字母，长度不超过 48图空间的名字
nickname否Stringname 的值在所有图空间中必须唯一图空间的显示名
description否String图空间的描述信息
cpu_limit是Int> 0CPU 核数
memory_limit是Int> 0内存大小，单位 GB
storage_limit是Int> 0图空间的数据占据的磁盘空间上限，单位 GB
compute_cpu_limit否Int0>= 0针对图计算的额外资源配置，单位 cores。当该字段不配置或者配置为 0 时，会由 cpu_limit 字段的值进行覆盖
compute_memory_limit否Int0>= 0针对图计算的额外内存配置，单位 GB。当该字段不配置或者配置为 0 时，会由 memory_limit 字段的值进行覆盖
oltp_namespace否String""OLTP 的 k8s 命名空间
olap_namespace否String""OLAP 的 k8s 命名空间。当 olap_namespace 和 oltp_namespace 的值相同时，其配置的资源限额会进行合并
storage_namespace否String""存储的 k8s 命名空间
operator_image_path否String""图计算 operator 的镜像地址：在创建图空间时，允许指定对应的图计算镜像并交由 K8S 进行统一管理
internal_algorithm_image_url否String""图计算的算法镜像地址：在创建图空间时，允许指定图计算的算法镜像并交由 K8S 进行统一管理
max_graph_number是Int> 0图空间的图数目的上限
max_role_number否Int0图空间的角色数目的上限
auth否Booleanfalsetrue, false图空间是否支持权限认证
configs否Map其他配置信息
 1{
 2  "name": "gs1",
 3  "description": "1st graph space",
 4  "max_graph_number": 100,
 5  "cpu_limit": 1000,
 6  "memory_limit": 8192,
 7  "storage_limit": 1000000,
 8  "max_role_number": 10,
 9  "auth": true,
10  "configs": {}
11}
Response Status
1201
Response Body
 1{
 2  "name": "gs1",
 3  "nickname": "gs1",
 4  "description": "1st graph space",
 5  "cpu_limit": 1000,
 6  "memory_limit": 8192,
 7  "storage_limit": 1000000,
 8  "compute_cpu_limit": 0,
 9  "compute_memory_limit": 0,
10  "oltp_namespace": "hugegraph-server",
11  "olap_namespace": "hugegraph-server",
12  "storage_namespace": "hugegraph-server",
13  "operator_image_path": "127.0.0.1/hugegraph-registry/hugegraph-computer-operator:3.1.1",
14  "internal_algorithm_image_url": "127.0.0.1/hugegraph-registry/hugegraph-computer-algorithm:3.1.1",
15  "max_graph_number": 100,
16  "max_role_number": 10,
17  "cpu_used": 0,
18  "memory_used": 0,
19  "storage_used": 0,
20  "storage_percent": 0.0,
21  "graph_number_used": 0,
22  "role_number_used": 0,
23  "auth": true,
24  "creator": "admin",
25  "create_time": "2024-05-01 12:00:00",
26  "update_time": "2024-05-01 12:00:00"
27}

2.0.2 列出系统所有图空间

Method & Url
1GET http://localhost:8080/graphspaces
Response Status
1200
Response Body
1{
2  "graphSpaces": [
3    "gs1",
4    "DEFAULT"
5  ]
6}

2.0.3 查看某个图空间

Params

路径参数说明：

  • graphspace: 图空间名称
Method & Url
1GET http://localhost:8080/graphspaces/gs1
Response Status
1200
Response Body
 1{
 2  "name": "gs1",
 3  "nickname": "gs1",
 4  "description": "1st graph space",
 5  "cpu_limit": 1000,
 6  "memory_limit": 8192,
 7  "storage_limit": 1000000,
 8  "oltp_namespace": "hugegraph-server",
 9  "olap_namespace": "hugegraph-server",
10  "storage_namespace": "hugegraph-server",
11  "operator_image_path": "127.0.0.1/hugegraph-registry/hugegraph-computer-operator:3.1.1",
12  "internal_algorithm_image_url": "127.0.0.1/hugegraph-registry/hugegraph-computer-algorithm:3.1.1",
13  "compute_cpu_limit": 0,
14  "compute_memory_limit": 0,
15  "max_graph_number": 100,
16  "max_role_number": 10,
17  "cpu_used": 0,
18  "memory_used": 0,
19  "storage_used": 0,
20  "storage_percent": 0.0,
21  "graph_number_used": 0,
22  "role_number_used": 0,
23  "auth": true,
24  "creator": "admin",
25  "create_time": "2024-05-01 12:00:00",
26  "update_time": "2024-05-01 12:00:00",
27  "dp_username": "gs1_dp",
28  "dp_password": "a1b2c3d4e5f60718"
29}

上述 dp_username 和 dp_password 是文档示例值。实际详情响应会返回对应图空间的 DP 凭据，应按敏感凭据保护。

2.0.4 更新某个图空间

注意：auth 鉴权配置，在创建图空间的过程一旦确定下来，不允许更新

Params

路径参数说明：

  • graphspace: 图空间名称

请求体说明：

  • action: 标记本次操作为 Update 动作，取值固定为 “update”
  • update: 即将更新的值，下述参数都应置于 update 中
名称是否必填类型默认值取值范围说明
name是String必须与路径中的图空间名一致图空间名称
nickname否String在所有图空间中必须唯一图空间的显示名
description否String图空间的描述信息
cpu_limit是Int> 0OLTP HugeGraphServer 的 CPU 核数
memory_limit是Int> 0OLTP HugeGraphServer 的内存大小，单位 GB
storage_limit是Int> 0图空间的数据占据的磁盘空间上限，单位 GB
compute_cpu_limit否Int0>= 0针对图计算的额外资源配置，单位 cores。当该字段不配置或者配置为 0 时，会由 cpu_limit 字段的值进行覆盖
compute_memory_limit否Int0>= 0针对图计算的额外内存配置，单位 GB。当该字段不配置或者配置为 0 时，会由 memory_limit 字段的值进行覆盖
oltp_namespace否StringOLTP 的 k8s 命名空间
olap_namespace否StringOLAP 的 k8s 命名空间。当 olap_namespace 和 oltp_namespace 的值相同时，其配置的资源限额会进行合并
storage_namespace否String存储的 k8s 命名空间
operator_image_path否String图计算 operator 的镜像地址：在更新图空间时，允许指定对应的图计算镜像并交由 K8S 进行统一管理
internal_algorithm_image_url否String图计算的算法镜像地址：在更新图空间时，允许指定图计算的算法镜像并交由 K8S 进行统一管理
max_graph_number是Int> 0图空间的图数目的上限
max_role_number否Int图空间的角色数目的上限
Method & Url
1PUT http://localhost:8080/graphspaces/gs1
Request Body
 1{
 2  "action": "update",
 3  "update": {
 4    "name": "gs1",
 5    "description": "1st graph space",
 6    "cpu_limit": 2000,
 7    "memory_limit": 40960,
 8    "storage_limit": 2048,
 9    "oltp_namespace": "hugegraph-server",
10    "olap_namespace": "hugegraph-server",
11    "operator_image_path": "127.0.0.1/hugegraph-registry/hugegraph-computer-operator:3.1.1",
12    "internal_algorithm_image_url": "127.0.0.1/hugegraph-registry/hugegraph-computer-algorithm:3.1.1",
13    "max_graph_number": 1000,
14    "max_role_number": 100
15  }
16}
Response Status
1200
Response Body
 1{
 2  "name": "gs1",
 3  "nickname": "gs1",
 4  "description": "1st graph space",
 5  "cpu_limit": 2000,
 6  "memory_limit": 40960,
 7  "storage_limit": 2048,
 8  "oltp_namespace": "hugegraph-server",
 9  "olap_namespace": "hugegraph-server",
10  "storage_namespace": "hugegraph-server",
11  "operator_image_path": "127.0.0.1/hugegraph-registry/hugegraph-computer-operator:3.1.1",
12  "internal_algorithm_image_url": "127.0.0.1/hugegraph-registry/hugegraph-computer-algorithm:3.1.1",
13  "compute_cpu_limit": 0,
14  "compute_memory_limit": 0,
15  "max_graph_number": 1000,
16  "max_role_number": 100,
17  "cpu_used": 0,
18  "memory_used": 0,
19  "storage_used": 0,
20  "storage_percent": 0.0,
21  "graph_number_used": 0,
22  "role_number_used": 0,
23  "auth": true,
24  "creator": "admin",
25  "create_time": "2024-05-01 12:00:00",
26  "update_time": "2024-05-01 12:30:00"
27}

2.0.5 删除某个图空间

Params

路径参数说明：

  • graphspace: 图空间名称
Method & Url
1DELETE http://localhost:8080/graphspaces/gs1
Response Status
1204

注意：删除图空间，会导致图空间的全部资源被释放。

2.0.6 列出系统所有图空间及其详情

Params

请求参数说明：

  • prefix: 只返回名称或显示名以该前缀开头的图空间
Method & Url
1GET http://localhost:8080/graphspaces/profile
Response Status
1200
Response Body

每条记录包含与 GET /graphspaces/{graphspace} 相同的字段，并额外带上 authed、default、create_time 和 update_time。authed 表示当前用户是否可以进入该图空间：当图空间开启了鉴权，而当前用户既不是管理员、也不是该空间的管理员或成员时为 false。default 目前恒为 false，默认图空间功能尚未实现。

 1[
 2  {
 3    "name": "gs1",
 4    "nickname": "gs1",
 5    "description": "1st graph space",
 6    "cpu_limit": 1000,
 7    "memory_limit": 8192,
 8    "storage_limit": 1000000,
 9    "compute_cpu_limit": 0,
10    "compute_memory_limit": 0,
11    "oltp_namespace": "hugegraph-server",
12    "olap_namespace": "hugegraph-server",
13    "storage_namespace": "hugegraph-server",
14    "max_graph_number": 100,
15    "max_role_number": 10,
16    "cpu_used": 0,
17    "memory_used": 0,
18    "storage_used": 0,
19    "storage_percent": 0.0,
20    "graph_number_used": 0,
21    "role_number_used": 0,
22    "auth": true,
23    "creator": "admin",
24    "authed": true,
25    "default": false,
26    "create_time": "2024-05-01 12:00:00",
27    "update_time": "2024-05-01 12:30:00"
28  }
29]

默认角色

每个图空间内置四种默认角色，可以一次性把一整组权限赋给某个用户或角色：

  • space：图空间管理员，只有管理员可以授予
  • space_member：图空间成员
  • analyst：图空间分析师
  • observer：只读角色，传入 graph 时可以收窄到单个图

user 既可以是用户名，也可以是角色名。当前用户是否具备某个默认角色也可以通过 GET /graphspaces/{graphspace}/auth/managers/default 查询，参见 Authentication API。

2.0.7 授予默认角色

Params

路径参数说明：

  • graphspace: 图空间名称

请求体说明：

  • user: 用户名或角色名，必填
  • role: 取值为 space、space_member、analyst、observer 之一，必填
  • graph: 图名称，选填，只在 role=observer 时生效
Method & Url
1POST http://localhost:8080/graphspaces/gs1/role
Request Body
1{
2  "user": "boss",
3  "role": "analyst"
4}
Response Status
1201
Response Body

只有在单个图上授予角色时才会回显 graph。

1{
2  "user": "boss",
3  "role": "analyst",
4  "graphSpace": "gs1"
5}

2.0.8 查询默认角色

Params

路径参数说明：

  • graphspace: 图空间名称

请求参数说明：

  • user: 用户名或角色名，必填
  • role: 默认角色名称，必填
  • graph: 图名称，选填，只在 role=observer 时生效
Method & Url
1GET http://localhost:8080/graphspaces/gs1/role?user=boss&role=analyst
Response Status
1200
Response Body
1{
2  "check": true
3}

2.0.9 回收默认角色

Params

路径参数说明：

  • graphspace: 图空间名称

请求参数说明：

  • user: 用户名或角色名，必填
  • role: 默认角色名称，必填
  • graph: 图名称，选填，只在 role=observer 时生效
Method & Url
1DELETE http://localhost:8080/graphspaces/gs1/role?user=boss&role=analyst
Response Status
1204

Schema 模板

Schema 模板把一段 Gremlin schema 脚本以名称保存下来，创建图时通过 schema 字段引用它来初始化图，参见 Graphs API。模板可以由它的创建者、图空间管理员或系统管理员修改和删除。

2.0.10 创建 schema 模板

Params

路径参数说明：

  • graphspace: 图空间名称

请求体说明：

  • name: 模板名称，必填
  • schema: Gremlin schema 脚本，必填
Method & Url
1POST http://localhost:8080/graphspaces/gs1/schematemplates
Request Body
1{
2  "name": "template1",
3  "schema": "schema.propertyKey('name').asText().ifNotExist().create();"
4}
Response Status
1201
Response Body
1{
2  "name": "template1",
3  "schema": "schema.propertyKey('name').asText().ifNotExist().create();",
4  "creator": "admin",
5  "create": "2024-05-01 12:00:00.000",
6  "create_time": "2024-05-01 12:00:00.000",
7  "update": "2024-05-01 12:00:00.000",
8  "update_time": "2024-05-01 12:00:00.000"
9}

2.0.11 列出图空间的全部 schema 模板

Method & Url
1GET http://localhost:8080/graphspaces/gs1/schematemplates
Response Status
1200
Response Body
1{
2  "schema_templates": [
3    "template1"
4  ]
5}

2.0.12 查看某个 schema 模板

Method & Url
1GET http://localhost:8080/graphspaces/gs1/schematemplates/template1
Response Status
1200

2.0.13 修改某个 schema 模板

只能修改 schema，模板名称不可修改。

Method & Url
1PUT http://localhost:8080/graphspaces/gs1/schematemplates/template1
Request Body
1{
2  "schema": "schema.propertyKey('age').asInt().ifNotExist().create();"
3}
Response Status
1200

2.0.14 删除某个 schema 模板

Method & Url
1DELETE http://localhost:8080/graphspaces/gs1/schematemplates/template1
Response Status
1204
最后修改 2026-10-12 · feat: upgrade OINK to 1.2.0 and improve docs UX (#514) (6181c8705)