From f97a0fcb10c480cd668e5e6eef9cc9559325a5d1 Mon Sep 17 00:00:00 2001 From: orion Date: Sun, 15 Nov 2026 04:54:46 +0000 Subject: [PATCH 1/5] docs(api): clarify quotas, loading ownership and deletion --- content/cn/docs/clients/restful-api/auth.md | 14 ++++- content/cn/docs/clients/restful-api/graphs.md | 7 ++- .../cn/docs/clients/restful-api/graphspace.md | 50 +++++++++++----- .../cn/docs/clients/restful-api/traverser.md | 3 +- content/en/docs/clients/restful-api/auth.md | 13 ++++- content/en/docs/clients/restful-api/graphs.md | 10 ++-- .../en/docs/clients/restful-api/graphspace.md | 58 ++++++++++++++----- .../en/docs/clients/restful-api/traverser.md | 3 +- 8 files changed, 116 insertions(+), 42 deletions(-) diff --git a/content/cn/docs/clients/restful-api/auth.md b/content/cn/docs/clients/restful-api/auth.md index 9595371678..fac4196e66 100644 --- a/content/cn/docs/clients/restful-api/auth.md +++ b/content/cn/docs/clients/restful-api/auth.md @@ -17,9 +17,17 @@ description: "Authentication(认证鉴权)REST 接口:管理用户、角色 > 开启权限及相关配置请先参考 [权限配置](/cn/docs/config/config-authentication/) 文档 ##### 用户认证与权限控制概述: -HugeGraph 支持多用户认证、以及细粒度的权限访问控制,采用基于“用户 - 用户组 - 操作 - 资源”的 4 层设计,灵活控制用户角色与权限。 资源描述了图数据库中的数据,比如符合某一类条件的顶点,每一个资源包括 type、label、properties 三个要素,共有 18 种 type、 -任意 label、任意 properties 的组合形成的资源,一个资源的内部条件是且关系,多个资源之间的条件是或关系。用户可以属于一个或多个用户组,每个用户组可以拥有对任意个资源的操作权限,操作类型包括:读、写、删除、执行等种类。HugeGraph 支持动态创建用户、用户组、资源, -支持动态分配或取消权限。初始化数据库时超级管理员用户被创建,后续可通过超级管理员创建各类角色用户,新创建的用户如果被分配足够权限后,可以由其创建或管理更多的用户。 + +HugeGraph 通过四类要素控制访问权限: + +- **用户**:可以属于一个或多个用户组。 +- **用户组**:获得对资源的操作权限。 +- **操作**:包括读、写、删除和执行。 +- **资源**:由 `type`、`label` 和 `properties` 组合定义,例如标签为 `person` 且 `city` 为 `Beijing` 的顶点。 + +同一资源内部的条件取**且(AND)**关系,不同备选资源之间取**或(OR)**关系。 +下文接口支持动态创建用户、用户组和资源,以及分配、撤销权限。鉴权初始化后由超级管理员管理账号与权限; +委派账号必须具备相应管理权限,才能创建或管理其他用户。 ##### 举例说明: user(name=boss) -belong-> group(name=all) -access(read)-> target(graph=graph1, resource={label: person, diff --git a/content/cn/docs/clients/restful-api/graphs.md b/content/cn/docs/clients/restful-api/graphs.md index 01bdbb1d08..987a583dfa 100644 --- a/content/cn/docs/clients/restful-api/graphs.md +++ b/content/cn/docs/clients/restful-api/graphs.md @@ -798,8 +798,8 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph_read_mode #### 6.3.5 LOADING owner 管理 {#loading-ownership} -自 HugeGraph 1.8.0 起提供 owner 协议 1 接口(需配合返回 `protocol: 1` 的新版 Server 与对应 Loader;当前 `master` 分支暂未包含该协议); -Loader 需使用配套的 1.8.0 及以上版本客户端。旧版本发行包、早期 1.8 构建以及当前 `master` 分支均不包含该协议;仅支持 `LOADING` 枚举不能说明支持这些接口。 +当前 1.8.0 `master` 已提供 LOADING owner 协议 1 接口。先探测 `GET .../mode/owners` 并确认返回 `protocol: 1`; +Loader 还需使用配套的 1.8.0 及以上版本客户端。Server 1.7.0 及更早版本,以及部分早期 1.8 开发构建不包含该协议;仅支持 `LOADING` 枚举不能说明支持这些接口。 启用鉴权时,两个接口沿用模式设置接口的权限要求,即图空间管理权限(`space`)或该图所有者权限,并校验 STATUS 写权限。 Server 将句柄绑定到实际鉴权用户;token 本身不赋予权限。申请、释放和重试必须保持相同身份。 @@ -838,7 +838,8 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/mode/owners 释放时将 `action` 设置为 `release`,句柄保持不变;响应中包含 `state: "released"` 和当前实际模式。未申请前直接调用释放会被记录,并导致后续使用该句柄的申请直接返回 `released`。 重试保留同一句柄;Server 校验其鉴权身份、instance 和 epoch。已释放句柄不能再次申请。 -当异常中断(如 `kill -9`)导致句柄残留时,管理员可发起强制恢复请求: +当异常中断(如 `kill -9`)导致句柄残留时,先停止并排空所有相关导入和图写入, +再由管理员读取当前句柄状态并发起强制恢复请求: ```text PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/mode/owners diff --git a/content/cn/docs/clients/restful-api/graphspace.md b/content/cn/docs/clients/restful-api/graphspace.md index 9f59b18047..dd8a499862 100644 --- a/content/cn/docs/clients/restful-api/graphspace.md +++ b/content/cn/docs/clients/restful-api/graphspace.md @@ -20,7 +20,13 @@ description: "Graphspace(图空间)REST 接口:多租户与资源隔离的 > [!WARNING] > **限制图空间列表和详情接口的访问** > -> `GET /graphspaces` 和 `GET /graphspaces/{graphspace}` 均未声明 `@RolesAllowed`;Server 未启用鉴权时这两个接口可匿名调用,启用鉴权后也没有方法级管理员角色限制。详情响应包含 `dp_username` 和 `dp_password`。生产环境必须将 `white_ip.status` 设为 `enable` 并通过 [IP 白名单 API](/cn/docs/clients/restful-api/other/) 启用、维护名单。网关必须按调用者身份或角色,仅允许管理员和可信运维调用方访问这两条路径;只限制来源 IP 范围仍会让同一网段的普通已认证业务账号读取 DP 凭据。Server 网络策略必须仅允许可信网关的出口地址访问 API 端口,阻断客户端绕过网关的直连路径。网关须记录这两条路径的调用身份、来源和结果;Server `audit-*.log` 用于鉴权授权记录,不能替代这两条路径的网关访问审计。业务账号须按最小权限授权。 +> `GET /graphspaces` 和 `GET /graphspaces/{graphspace}` 均未声明 `@RolesAllowed`;Server 未启用鉴权时可匿名调用,启用鉴权后也没有方法级管理员角色限制。 +> 详情响应包含 `dp_username` 和 `dp_password`。 +> +> 生产环境设置 `white_ip.status=enable`,并通过 [IP 白名单 API](/cn/docs/clients/restful-api/other/) 维护名单。网关还须按调用者身份或角色, +> 仅允许管理员和可信运维调用方访问这两条路径。只限制来源 IP 仍会让同一网段的普通已认证账号读取 DP 凭据;Server API 端口应仅允许可信网关出口访问,阻断客户端直连。 +> +> 在网关记录调用身份、来源和结果。Server `audit-*.log` 记录鉴权授权,不能替代这两条路径的网关访问审计;业务账号按最小权限授权。 #### 2.0.1 创建一个图空间 @@ -32,29 +38,33 @@ POST http://localhost:8080/graphspaces ##### Request Body -注意:目前 cpu,内存,以及 k8s 相关功能暂未开放 +`server.use_k8s=true` 时,CPU 与内存限额用于配置 Kubernetes 命名空间配额;其他部署不会据此限制 JVM 或容器资源。 +修改这些字段不会自动调整现有 Pod 的资源。 | 名称 | 是否必填 | 类型 | 默认值 | 取值范围 | 说明 | |------------------------------|----------|---------|-----------|-----------------------------------------------------------------|------------------------------------------------------------------------------------------------------| | name | 是 | String | | 小写字母、数字和下划线组成,首字符必须是小写字母,长度不超过 48 | 图空间的名字 | | nickname | 否 | String | name 的值 | 在所有图空间中必须唯一 | 图空间的显示名 | | description | 否 | String | | | 图空间的描述信息 | -| cpu_limit | 是 | Int | | > 0 | CPU 核数 | -| memory_limit | 是 | Int | | > 0 | 内存大小,单位 GB | -| storage_limit | 是 | Int | | > 0 | 图空间的数据占据的磁盘空间上限,单位 GB | -| compute_cpu_limit | 否 | Int | 0 | >= 0 | 针对图计算的额外资源配置,单位 cores。当该字段不配置或者配置为 0 时,会由 cpu_limit 字段的值进行覆盖 | -| compute_memory_limit | 否 | Int | 0 | >= 0 | 针对图计算的额外内存配置,单位 GB。当该字段不配置或者配置为 0 时,会由 memory_limit 字段的值进行覆盖 | +| cpu_limit | 否 | Int | 128 | > 0 | CPU 核数 | +| memory_limit | 否 | Int | 128 | > 0 | 内存大小,单位 GB | +| storage_limit | 否 | Int | 10240 | > 0 | 图空间的数据占据的磁盘空间上限,单位 GB | +| compute_cpu_limit | 否 | Int | 0 | >= 0 | 计算配额;省略或为 `0` 时持续继承 `cpu_limit` | +| compute_memory_limit | 否 | Int | 0 | >= 0 | 计算配额;省略或为 `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 | 否 | Int | 0 | | 图空间的角色数目的上限 | +| max_graph_number | 否 | Int | 100 | > 0 | 图空间的图数目的上限 | +| max_role_number | 否 | Int | 100 | | 图空间的角色数目的上限 | | auth | 否 | Boolean | false | true, false | 图空间是否支持权限认证 | | configs | 否 | Map | | | 其他配置信息 | {.td-table--wide} +以上是当前 Server REST 创建接口的默认值;已有图空间保留原配额,Hubble 等客户端也可以显式提交其他值。 +省略的计算配额保存为 `0`,持续继承对应的 CPU 或内存配额。 + ```json { "name": "gs1", @@ -200,11 +210,15 @@ GET http://localhost:8080/graphspaces/gs1 > `max_role_number`、`cpu_limit`、`memory_limit`、`storage_limit`)。更新前建议先通过 `GET /graphspaces/{name}` 读取当前配置,并保留未修改字段的原值。 > - **计算资源配额继承**:当 `compute_cpu_limit: 0` 或 `compute_memory_limit: 0`(或创建时缺省)时,表示持续继承主图空间的 `cpu_limit` 和 `memory_limit`。 > 数值 0 代表继承,既非无限制也非分配 0 资源。 +> 更新时省略计算配额字段会保留原设置,显式传入 0 才恢复继承;响应保留这个原始 0 标记。 > - **配额超限约束**:图数量达到 `max_graph_number` 时,新建图请求将被拒绝并返回 `reach graph limit`;存储占用超过 `storage_limit` 时,PD 会将该图空间内的图标记为 > `ReadOnly`(只读),待后续巡检检测到占用降至配额以下后自动恢复 `ReadWrite`。 > - **高精度存储指标**:响应体在保留以 GB 为单位的整数 `storage_used` 字段外,新增了 `storage_used_kb` 字段以支持 1GB 以下的高精度用量展示,`storage_percent` > 比率直接基于该 KB 精度值计算得出。 +客户端必须保留“省略字段”与“显式传入 0”的区别。旧客户端可能把未设置的计算配额序列化为 0,意外恢复继承。 +使用这类客户端时,先读取图空间,再显式传入需要保留的原计算配额。 + ##### Params **路径参数说明:** @@ -224,15 +238,15 @@ GET http://localhost:8080/graphspaces/gs1 | cpu_limit | 是 | Int | | > 0 | OLTP HugeGraphServer 的 CPU 核数 | | memory_limit | 是 | Int | | > 0 | OLTP HugeGraphServer 的内存大小,单位 GB | | storage_limit | 是 | Int | | > 0 | 图空间的数据占据的磁盘空间上限,单位 GB | -| compute_cpu_limit | 否 | Int | 0 | >= 0 | 针对图计算的额外资源配置,单位 cores。当该字段不配置或者配置为 0 时,会由 cpu_limit 字段的值进行覆盖 | -| compute_memory_limit | 否 | Int | 0 | >= 0 | 针对图计算的额外内存配置,单位 GB。当该字段不配置或者配置为 0 时,会由 memory_limit 字段的值进行覆盖 | +| compute_cpu_limit | 否 | Int | 保留原值 | >= 0 | 省略时保留当前设置;`0` 恢复继承 `cpu_limit` | +| compute_memory_limit | 否 | Int | 保留原值 | >= 0 | 省略时保留当前设置;`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 | 否 | Int | | | 图空间的角色数目的上限 | +| max_role_number | 是 | Int | | | 图空间的角色数目的上限 | {.td-table--wide} ##### Method & Url @@ -321,7 +335,17 @@ DELETE http://localhost:8080/graphspaces/gs1 204 ``` -> 注意:删除图空间,会导致图空间的全部资源被释放。 +> [!WARNING] +> 升级到支持图空间统计清理的 Server 前,先升级**全部 PD 节点**。旧 PD 会返回 `UNIMPLEMENTED`,但此时 Server 已清理图、 +> 图空间权限、Schema 模板和服务,只保留图空间配置与列表项并报告删除失败。该操作不是事务,失败响应不会恢复已经清理的资源。 + +删除期间停止在该空间新建图。成功删除还会移除该空间的 PD 配额与用量记录,但不会清理旧版本删除操作留下的历史孤儿记录。 +PD 清理失败时,应修正原因再重试,不能假设失败后的图空间仍保留原有图。 + +若 PD 报告仍有图元数据,通过 PD 已鉴权的 `GET /v1/partitionsAndStats` 核查完整图标识,包含数据 `/g` 与 Schema `/m` 记录, +即使记录下已无分区也会列出;仅查询 `GET /v1/graphs` 不足以完成排查。确认所有权和需要保留的数据后,通过正常 Server 图接口处理 +确认废弃的图。若 Server 已缺少该图配置,使用原图空间、图名和后端重建配置,再正常删除图并重试删除图空间。 +其他 Server 管理的图应通过其所有者处理;不要直接删除 PD 记录,也不要擅自重建其他 Server 管理的图。 #### 2.0.6 列出系统所有图空间及其详情 diff --git a/content/cn/docs/clients/restful-api/traverser.md b/content/cn/docs/clients/restful-api/traverser.md index 3b6078791c..9025a5e6c9 100644 --- a/content/cn/docs/clients/restful-api/traverser.md +++ b/content/cn/docs/clients/restful-api/traverser.md @@ -2076,7 +2076,8 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/{graph}/traversers/crosspoi - max_degree:查询过程中,单个顶点遍历的最大邻接边数目,默认为 10000;当前也兼容参数名 `degree`。 - skip_degree:用于设置查询过程中舍弃超级顶点的最小边数,即当某个顶点的邻接边数目大于 skip_degree 时,完全舍弃该顶点。选填项,如果开启时,需满足 `skip_degree >= max_degree` 约束,默认为 0 (不启用),表示不跳过任何点 (注意:开启此配置后,遍历时会尝试访问一个顶点的 skip_degree 条边,而不仅仅是 max_degree 条边,这样有额外的遍历开销,对查询性能影响可能有较大影响,请确认理解后再开启) - capacity:遍历过程中最大的访问的顶点数目,选填项,默认为 10000000 -- limit:返回的路径的最大数目,选填项,默认为 10 +- limit:返回的不同交点的最大数目,选填,默认 `10`;`-1` 表示不限制交点数。 + `with_path=true` 时,多条路径可能到达同一个交点,因此返回的路径数可以超过该限制。 - with_path:true 表示返回交点所在的路径,false 表示不返回交点所在的路径,选填项,默认为 false - with_vertex,选填项,默认为 false: - true 表示返回结果包含完整的顶点信息(路径中的全部顶点) diff --git a/content/en/docs/clients/restful-api/auth.md b/content/en/docs/clients/restful-api/auth.md index a02fd34fea..4512c2ffe1 100644 --- a/content/en/docs/clients/restful-api/auth.md +++ b/content/en/docs/clients/restful-api/auth.md @@ -17,7 +17,18 @@ description: "Authentication REST API: Manage users, roles, permissions, and acc > To enable authentication and related configurations, please refer to the [Authentication Configuration](/docs/config/config-authentication/) documentation. ##### Overview of User Authentication and Access Control: -HugeGraph supports multi-user authentication and fine-grained access control. It adopts a 4-tier design based on "User-User Group-Operation-Resource" to flexibly control user roles and permissions. Resources describe data in the graph database, such as vertices that meet certain conditions. Each resource consists of three elements: type, label, and properties. There are a total of 18 types and combinations of any label and properties to form resources. The internal condition of a resource is an "AND" relationship, while the condition between multiple resources is an "OR" relationship. Users can belong to one or more user groups, and each user group can have permissions for any number of resources. The types of operations include read, write, delete, execute, etc. HugeGraph supports dynamically creating users, user groups, and resources, and supports dynamically assigning or revoking permissions. During the initialization of the database, a super administrator user is created, and subsequently, various role users can be created by the super administrator. If a newly created user is assigned sufficient permissions, they can create or manage more users. + +HugeGraph controls access through four elements: + +- **Users** belong to one or more groups. +- **Groups** receive permissions on resources. +- **Operations** include read, write, delete and execute. +- **Resources** combine `type`, `label` and `properties`, such as vertices with label `person` whose `city` is `Beijing`. + +Conditions within one resource are combined with **AND**; alternative resources are combined with **OR**. +The APIs below create users, groups and resources, and grant or revoke permissions dynamically. +After authentication is initialized, the super administrator manages accounts and permissions; delegated accounts need the corresponding +management permissions to create or manage other users. ##### Example: user(name=boss) -belong-> group(name=all) -access(read)-> target(graph=graph1, resource={label: person, city: Beijing}) diff --git a/content/en/docs/clients/restful-api/graphs.md b/content/en/docs/clients/restful-api/graphs.md index c3023dfb09..623980b884 100644 --- a/content/en/docs/clients/restful-api/graphs.md +++ b/content/en/docs/clients/restful-api/graphs.md @@ -812,10 +812,9 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph_read_mode #### 6.3.5 LOADING ownership {#loading-ownership} -Starting with HugeGraph 1.8.0, the Server provides the protocol 1 endpoints for LOADING ownership -(requires a Server whose `GET .../mode/owners` returns `protocol: 1` and a matching Loader; current `master` does not include it yet); -Loader integration requires a matching 1.8.0 or newer client. -Released packages, earlier 1.8 builds, and current `master` builds lack this protocol. Support for the `LOADING` enum alone does not imply support for it. +Current 1.8.0 `master` provides the protocol 1 endpoints for LOADING ownership. Probe `GET .../mode/owners` and require `protocol: 1`; +Loader integration also needs a matching 1.8.0 or newer client. Server 1.7.0 and earlier lack this protocol, as do some earlier 1.8 development builds. +Support for the `LOADING` enum alone does not imply support for these endpoints. With authentication enabled, both endpoints use the mode setter's permissions: graph-space management (`space`) or graph ownership, with STATUS write authorization. Server binds the handle to the authenticated principal; a token grants no permission. Keep the same identity for acquire, release and retries. @@ -857,7 +856,8 @@ Release with `action: "release"` and the same handle; its response has `state: " recorded and causes a subsequent acquire with that handle to return `released`. Keep one handle for retries; Server checks its principal, instance and epoch. A released handle cannot acquire again. -To clear orphaned handles after an abnormal exit (e.g. `kill -9`), an administrator can execute an explicit recovery request: +To clear orphaned handles after an abnormal exit (e.g. `kill -9`), first stop and drain all related imports and graph writes. +An administrator can then read the current handle state and execute an explicit recovery request: ```text PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/mode/owners diff --git a/content/en/docs/clients/restful-api/graphspace.md b/content/en/docs/clients/restful-api/graphspace.md index 4b62c7460f..2b68b17806 100644 --- a/content/en/docs/clients/restful-api/graphspace.md +++ b/content/en/docs/clients/restful-api/graphspace.md @@ -20,7 +20,15 @@ HugeGraph implements multi-tenancy through graph spaces, which isolate compute/s > [!WARNING] > **Restrict graph-space listing and detail endpoints** > -> `GET /graphspaces` and `GET /graphspaces/{graphspace}` have no `@RolesAllowed` annotation. They are anonymous when Server authentication is disabled and lack method-level administrator checks when it is enabled. Detail responses contain `dp_username` and `dp_password`. In production, set `white_ip.status=enable` and maintain the [IP allowlist](/docs/clients/restful-api/other/). A gateway must restrict both paths by caller identity or role to administrators and trusted operators; restricting only source IPs still lets ordinary authenticated accounts on that network read DP credentials. Server network policy must allow only trusted gateway egress addresses to the API port, blocking direct client bypass. Record caller identity, source, and outcome at the gateway. Server `audit-*.log` files record authentication and authorization but do not replace gateway access auditing for these paths. Grant business accounts minimum permissions. +> `GET /graphspaces` and `GET /graphspaces/{graphspace}` have no `@RolesAllowed` annotation. They are anonymous when Server authentication is disabled +> and lack method-level administrator checks when it is enabled. Detail responses contain `dp_username` and `dp_password`. +> +> In production, set `white_ip.status=enable` and maintain the [IP allowlist](/docs/clients/restful-api/other/). Restrict both paths at the gateway by +> caller identity or role to administrators and trusted operators. An IP restriction alone still permits ordinary authenticated accounts on that +> network to read DP credentials. Allow only trusted gateway egress addresses to reach Server's API port, blocking direct client bypass. +> +> Record caller identity, source and outcome at the gateway. Server `audit-*.log` files record authentication and authorization, but do not replace +> gateway access auditing for these paths. Grant business accounts minimum permissions. #### 2.0.1 Create a graphspace @@ -32,29 +40,33 @@ POST http://localhost:8080/graphspaces ##### Request Body -Note: CPU/memory and Kubernetes-related capabilities are not publicly available yet. +CPU and memory limits configure namespace quotas when `server.use_k8s=true`; in other deployments they do not impose JVM or container limits. +Changing these fields does not resize existing Pods. | Name | Required | Type | Default | Range/Note | Description | |------------------------------|----------|---------|---------|--------------------------------------------------------------------------------|-----------------------------------------------------------------------------------| | name | Yes | String | | Lowercase letters, digits, underscore; must start with a letter; max length 48 | Graphspace name | | nickname | No | String | name | Must be unique among graphspaces | Display name of the graphspace | | description | No | String | | | Description | -| cpu_limit | Yes | Int | | > 0 | CPU cores for the graphspace | -| memory_limit | Yes | Int | | > 0 (GB) | Memory quota in GB | -| storage_limit | Yes | Int | | > 0 | Maximum disk usage, in GB | -| compute_cpu_limit | No | Int | 0 | >= 0 | Extra HugeGraph-Computer CPU cores; falls back to `cpu_limit` if unset or 0 | -| compute_memory_limit | No | Int | 0 | >= 0 | Extra HugeGraph-Computer memory in GB; falls back to `memory_limit` if unset or 0 | +| cpu_limit | No | Int | 128 | > 0 | CPU cores for the graphspace | +| memory_limit | No | Int | 128 | > 0 (GB) | Memory quota in GB | +| storage_limit | No | Int | 10240 | > 0 | Maximum disk usage, in GB | +| compute_cpu_limit | No | Int | 0 | >= 0 | Compute quota; omitted or `0` continuously inherits `cpu_limit` | +| compute_memory_limit | No | Int | 0 | >= 0 | Compute quota; omitted or `0` continuously inherits `memory_limit` | | oltp_namespace | No | String | "" | | Kubernetes namespace for OLTP HugeGraph-Server | | olap_namespace | No | String | "" | Resources are merged when identical to `oltp_namespace` | Kubernetes namespace for OLAP / HugeGraph-Computer | | storage_namespace | No | String | "" | | Kubernetes namespace for HugeGraph-Store | | operator_image_path | No | String | "" | | HugeGraph-Computer operator image registry | | internal_algorithm_image_url | No | String | "" | | HugeGraph-Computer algorithm image registry | -| max_graph_number | Yes | Int | | > 0 | Maximum number of graphs that can be created inside the graphspace | -| max_role_number | No | Int | 0 | | Maximum number of roles that can be created inside the graphspace | +| max_graph_number | No | Int | 100 | > 0 | Maximum number of graphs that can be created inside the graphspace | +| max_role_number | No | Int | 100 | | Maximum number of roles that can be created inside the graphspace | | auth | No | Boolean | false | true / false | Whether to enable authentication for the graphspace | | configs | No | Map | | | Additional configuration | {.td-table--wide} +These are current Server REST creation defaults. Existing spaces keep their configured limits; clients such as Hubble can submit different values. +Omitted compute limits are stored as `0`, continuously inheriting the corresponding CPU or memory quota. + ```json { "name": "gs1", @@ -201,12 +213,16 @@ GET http://localhost:8080/graphspaces/gs1 > graphspace settings with `GET /graphspaces/{name}` first and preserve fields that are not being changed. > - **Compute Limit Inheritance**: Setting `compute_cpu_limit: 0` or `compute_memory_limit: 0` (or omitting them on creation) means continuously > inheriting `cpu_limit` and `memory_limit`. Zero represents inheritance, not unlimited or zero allocation. +> On update, omitting a compute field preserves its current setting; explicit zero restores inheritance. Responses retain that zero marker. > - **Quota Enforcement**: Exceeding `max_graph_number` causes subsequent graph creations to fail with `reach graph limit`. Exceeding > `storage_limit` triggers PD storage enforcement, automatically marking all graphs in the space as `ReadOnly` until usage drops below the > quota on the next patrol cycle. > - **High-Precision Storage Metric**: In addition to the integer GB `storage_used` field, responses provide `storage_used_kb` for precise sub-GB > tracking. `storage_percent` is calculated from this exact KB value. +Use a client that preserves omitted compute fields. Older clients can serialize an unset field as zero, unintentionally restoring inheritance. +With those clients, read the current space and explicitly send its existing compute limits when preserving independent values. + ##### Params **Path parameter** @@ -226,11 +242,11 @@ GET http://localhost:8080/graphspaces/gs1 | cpu_limit | Yes | Int | > 0 | CPU cores for OLTP HugeGraph-Server | | memory_limit | Yes | Int | > 0 (GB) | Memory quota (GB) for OLTP HugeGraph-Server | | storage_limit | Yes | Int | > 0 | Maximum disk usage, in GB | -| compute_cpu_limit | No | Int | >= 0 | Extra HugeGraph-Computer CPU cores; falls back to `cpu_limit` if unset or 0 | -| compute_memory_limit | No | Int | >= 0 | Extra HugeGraph-Computer memory in GB; falls back to `memory_limit` if unset or 0 | -| oltp_namespace | Yes | String | | Kubernetes namespace for OLTP HugeGraph-Server | -| olap_namespace | Yes | String | Resources are merged when identical to `oltp_namespace` | Kubernetes namespace for OLAP | -| storage_namespace | Yes | String | | Kubernetes namespace for HugeGraph-Store | +| compute_cpu_limit | No | Int | >= 0 | Omitted: preserve current setting; `0`: inherit `cpu_limit` | +| compute_memory_limit | No | Int | >= 0 | Omitted: preserve current setting; `0`: inherit `memory_limit` | +| oltp_namespace | No | String | | Kubernetes namespace for OLTP HugeGraph-Server | +| olap_namespace | No | String | Resources are merged when identical to `oltp_namespace` | Kubernetes namespace for OLAP | +| storage_namespace | No | String | | Kubernetes namespace for HugeGraph-Store | | operator_image_path | No | String | | HugeGraph-Computer operator image registry | | internal_algorithm_image_url | No | String | | HugeGraph-Computer algorithm image registry | | max_graph_number | Yes | Int | > 0 | Maximum number of graphs | @@ -323,7 +339,19 @@ DELETE http://localhost:8080/graphspaces/gs1 204 ``` -> Warning: deleting a graphspace releases all resources that belong to it. +> [!WARNING] +> Upgrade **every PD node before Server** when adopting graph-space statistics cleanup. An older PD returns `UNIMPLEMENTED` after Server has already +> cleared graphs, authorization, Schema templates and services. The remaining space configuration and list entry are retained, and deletion fails. +> This operation is not transactional; a failed request does not restore cleared resources. + +Stop graph creation in the space before deleting it. Successful deletion also removes its exact PD quota/usage record, but does not purge orphans +left by older deletions. After a PD cleanup failure, correct the cause and retry; do not assume the space still contains its previous graphs. + +If PD reports remaining graph metadata, inspect authenticated `GET /v1/partitionsAndStats` on PD. Its full graph identifiers include both data `/g` +and Schema `/m` records, even with no partitions; `GET /v1/graphs` alone is not a complete inventory. Confirm ownership and retained data before +using the normal Server graph APIs to remove a confirmed obsolete graph. If its Server configuration is missing, recreate it with the original +space, graph name and backend, then drop it normally and retry space deletion. A graph belonging to another Server must be handled by that owner; +do not delete PD records blindly or recreate another Server's graph. #### 2.0.6 List all graphspaces with their details diff --git a/content/en/docs/clients/restful-api/traverser.md b/content/en/docs/clients/restful-api/traverser.md index 1c0214cd61..879993a275 100644 --- a/content/en/docs/clients/restful-api/traverser.md +++ b/content/en/docs/clients/restful-api/traverser.md @@ -2081,7 +2081,8 @@ Finds the intersection of destination vertices that satisfy the specified condit - skip_degree: Sets the minimum number of edges to discard super vertices during the query process. If the number of adjacent edges for a vertex is greater than skip_degree, the vertex is completely discarded. Optional. If enabled, it must satisfy the constraint `skip_degree >= max_degree`. Default is 0 (not enabled), which means no vertices are skipped. Note: When this configuration is enabled, the traversal process will attempt to visit skip_degree edges of a vertex, not just max_degree edges. This incurs additional traversal overhead and may significantly impact query performance. Please make sure you understand it before enabling. - capacity: Maximum number of vertices to be visited during the traversal process. Optional. Default is 10000000. -- limit: Maximum number of paths to be returned. Optional. Default is 10. +- limit: Maximum number of distinct crosspoints to return. Optional, default `10`; `-1` means no limit. + With `with_path=true`, several paths may end at the same crosspoint, so the number of returned paths can exceed this limit. - with_path: When set to true, returns the paths where the intersection points are located. When set to false, does not return the paths. Optional. Default is false. - with_vertex: Optional. Default is false. - When set to true, the result includes complete vertex information (all vertices in the paths): From d856b9be1b11d6d796e5eea092b029b05c2149f5 Mon Sep 17 00:00:00 2001 From: orion Date: Sun, 15 Nov 2026 05:07:34 +0000 Subject: [PATCH 2/5] docs: preserve links and split remaining long passages --- content/cn/docs/clients/restful-api/graphs.md | 4 ++++ content/en/docs/clients/restful-api/graphs.md | 2 ++ 2 files changed, 6 insertions(+) diff --git a/content/cn/docs/clients/restful-api/graphs.md b/content/cn/docs/clients/restful-api/graphs.md index 987a583dfa..669ab5e2d0 100644 --- a/content/cn/docs/clients/restful-api/graphs.md +++ b/content/cn/docs/clients/restful-api/graphs.md @@ -80,6 +80,8 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph } ``` + + #### 6.1.3 清空某个图的全部数据,包括 schema、vertex、edge 和 index 等 ##### Params @@ -834,7 +836,9 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/mode/owners ``` 只有响应中包含 `state: "active"` 时才表示申请成功;此时返回 `200` 并回显 `protocol`、`instance`、`epoch`、`token` 以及 `mode: "LOADING"`。 + 若返回 `200` 但 `state: "released"`,说明该句柄已失效或已被提前取消,此时并未获得 owner 保护;必须先停止并排空该次导入尝试,然后再通过 GET 获取新的 `instance` 和 `epoch` 并使用新 token 重新发起尝试。 + 释放时将 `action` 设置为 `release`,句柄保持不变;响应中包含 `state: "released"` 和当前实际模式。未申请前直接调用释放会被记录,并导致后续使用该句柄的申请直接返回 `released`。 重试保留同一句柄;Server 校验其鉴权身份、instance 和 epoch。已释放句柄不能再次申请。 diff --git a/content/en/docs/clients/restful-api/graphs.md b/content/en/docs/clients/restful-api/graphs.md index 623980b884..2e0eb1a0a0 100644 --- a/content/en/docs/clients/restful-api/graphs.md +++ b/content/en/docs/clients/restful-api/graphs.md @@ -80,6 +80,8 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph } ``` + + #### 6.1.3 Clear all data of a graph, include: schema, vertex, edge and index ##### Params From 7ac623438dd5a8868db1aac32372efa6a21a754e Mon Sep 17 00:00:00 2001 From: dark Date: Wed, 18 Nov 2026 01:10:30 +0800 Subject: [PATCH 3/5] docs(api): specify Server 1.8.0+ release for LOADING protocol 1 endpoints --- content/cn/docs/clients/restful-api/graphs.md | 2 +- content/en/docs/clients/restful-api/graphs.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/content/cn/docs/clients/restful-api/graphs.md b/content/cn/docs/clients/restful-api/graphs.md index 669ab5e2d0..2a9506a041 100644 --- a/content/cn/docs/clients/restful-api/graphs.md +++ b/content/cn/docs/clients/restful-api/graphs.md @@ -800,7 +800,7 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph_read_mode #### 6.3.5 LOADING owner 管理 {#loading-ownership} -当前 1.8.0 `master` 已提供 LOADING owner 协议 1 接口。先探测 `GET .../mode/owners` 并确认返回 `protocol: 1`; +HugeGraph Server 1.8.0 及更高版本已提供 LOADING owner 协议 1 接口。先探测 `GET .../mode/owners` 并确认返回 `protocol: 1`; Loader 还需使用配套的 1.8.0 及以上版本客户端。Server 1.7.0 及更早版本,以及部分早期 1.8 开发构建不包含该协议;仅支持 `LOADING` 枚举不能说明支持这些接口。 启用鉴权时,两个接口沿用模式设置接口的权限要求,即图空间管理权限(`space`)或该图所有者权限,并校验 STATUS 写权限。 Server 将句柄绑定到实际鉴权用户;token 本身不赋予权限。申请、释放和重试必须保持相同身份。 diff --git a/content/en/docs/clients/restful-api/graphs.md b/content/en/docs/clients/restful-api/graphs.md index 2e0eb1a0a0..2615154d50 100644 --- a/content/en/docs/clients/restful-api/graphs.md +++ b/content/en/docs/clients/restful-api/graphs.md @@ -814,7 +814,7 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph_read_mode #### 6.3.5 LOADING ownership {#loading-ownership} -Current 1.8.0 `master` provides the protocol 1 endpoints for LOADING ownership. Probe `GET .../mode/owners` and require `protocol: 1`; +HugeGraph Server 1.8.0 and later provide the protocol 1 endpoints for LOADING ownership. Probe `GET .../mode/owners` and require `protocol: 1`; Loader integration also needs a matching 1.8.0 or newer client. Server 1.7.0 and earlier lack this protocol, as do some earlier 1.8 development builds. Support for the `LOADING` enum alone does not imply support for these endpoints. With authentication enabled, both endpoints use the mode setter's permissions: graph-space management (`space`) or graph ownership, with STATUS write From ea2d41bb08d4d12d5a2f4622ada8c265435be2ea Mon Sep 17 00:00:00 2001 From: dark Date: Thu, 19 Nov 2026 19:54:12 +0800 Subject: [PATCH 4/5] docs(api): rephrase graphspace creation default description timelessly --- content/cn/docs/clients/restful-api/graphspace.md | 2 +- content/en/docs/clients/restful-api/graphspace.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/content/cn/docs/clients/restful-api/graphspace.md b/content/cn/docs/clients/restful-api/graphspace.md index dd8a499862..ab58cc4abb 100644 --- a/content/cn/docs/clients/restful-api/graphspace.md +++ b/content/cn/docs/clients/restful-api/graphspace.md @@ -62,7 +62,7 @@ POST http://localhost:8080/graphspaces | configs | 否 | Map | | | 其他配置信息 | {.td-table--wide} -以上是当前 Server REST 创建接口的默认值;已有图空间保留原配额,Hubble 等客户端也可以显式提交其他值。 +创建请求省略字段时,Server 采用上述默认值;图空间保留创建时保存的配额,Hubble 等客户端也可以显式提交其他值。 省略的计算配额保存为 `0`,持续继承对应的 CPU 或内存配额。 ```json diff --git a/content/en/docs/clients/restful-api/graphspace.md b/content/en/docs/clients/restful-api/graphspace.md index 2b68b17806..ee7b9bfcd5 100644 --- a/content/en/docs/clients/restful-api/graphspace.md +++ b/content/en/docs/clients/restful-api/graphspace.md @@ -64,7 +64,7 @@ Changing these fields does not resize existing Pods. | configs | No | Map | | | Additional configuration | {.td-table--wide} -These are current Server REST creation defaults. Existing spaces keep their configured limits; clients such as Hubble can submit different values. +Server applies these defaults only when a create request omits the field; a space keeps the limits stored at creation, and clients such as Hubble can submit other values. Omitted compute limits are stored as `0`, continuously inheriting the corresponding CPU or memory quota. ```json From 69d239a6d60d7296f4373e0db0d35e953c81586e Mon Sep 17 00:00:00 2001 From: dark Date: Sat, 21 Nov 2026 21:35:00 +0800 Subject: [PATCH 5/5] docs(api): qualify Server 1.8.0 create defaults and 1.7.0 update inheritance differences --- content/cn/docs/clients/restful-api/graphspace.md | 4 ++-- content/en/docs/clients/restful-api/graphspace.md | 6 ++++-- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/content/cn/docs/clients/restful-api/graphspace.md b/content/cn/docs/clients/restful-api/graphspace.md index ab58cc4abb..0c017ea1be 100644 --- a/content/cn/docs/clients/restful-api/graphspace.md +++ b/content/cn/docs/clients/restful-api/graphspace.md @@ -62,7 +62,7 @@ POST http://localhost:8080/graphspaces | configs | 否 | Map | | | 其他配置信息 | {.td-table--wide} -创建请求省略字段时,Server 采用上述默认值;图空间保留创建时保存的配额,Hubble 等客户端也可以显式提交其他值。 +以上创建默认值自 Server 1.8.0 起生效。在 Server 1.7.0 中,`cpu_limit`、`memory_limit`、`storage_limit` 与 `max_graph_number` 均为必填项(必须 > 0),省略会导致字段取值为 0 并被校验拒绝。已有图空间保留原配额,Hubble 等客户端也可以显式提交其他值。 省略的计算配额保存为 `0`,持续继承对应的 CPU 或内存配额。 ```json @@ -210,7 +210,7 @@ GET http://localhost:8080/graphspaces/gs1 > `max_role_number`、`cpu_limit`、`memory_limit`、`storage_limit`)。更新前建议先通过 `GET /graphspaces/{name}` 读取当前配置,并保留未修改字段的原值。 > - **计算资源配额继承**:当 `compute_cpu_limit: 0` 或 `compute_memory_limit: 0`(或创建时缺省)时,表示持续继承主图空间的 `cpu_limit` 和 `memory_limit`。 > 数值 0 代表继承,既非无限制也非分配 0 资源。 -> 更新时省略计算配额字段会保留原设置,显式传入 0 才恢复继承;响应保留这个原始 0 标记。 +> 在 Server 1.8.0+ 中,更新时省略计算配额字段会保留原设置,显式传入 0 恢复继承;而在 Server 1.7.0 中,更新处理会忽略 0,保留之前的配额而不会恢复继承。响应保留这个原始 0 标记。 > - **配额超限约束**:图数量达到 `max_graph_number` 时,新建图请求将被拒绝并返回 `reach graph limit`;存储占用超过 `storage_limit` 时,PD 会将该图空间内的图标记为 > `ReadOnly`(只读),待后续巡检检测到占用降至配额以下后自动恢复 `ReadWrite`。 > - **高精度存储指标**:响应体在保留以 GB 为单位的整数 `storage_used` 字段外,新增了 `storage_used_kb` 字段以支持 1GB 以下的高精度用量展示,`storage_percent` diff --git a/content/en/docs/clients/restful-api/graphspace.md b/content/en/docs/clients/restful-api/graphspace.md index ee7b9bfcd5..35605a2b8c 100644 --- a/content/en/docs/clients/restful-api/graphspace.md +++ b/content/en/docs/clients/restful-api/graphspace.md @@ -64,7 +64,7 @@ Changing these fields does not resize existing Pods. | configs | No | Map | | | Additional configuration | {.td-table--wide} -Server applies these defaults only when a create request omits the field; a space keeps the limits stored at creation, and clients such as Hubble can submit other values. +Server 1.8.0 applies these defaults when a create request omits the fields. On Server 1.7.0, `cpu_limit`, `memory_limit`, `storage_limit` and `max_graph_number` are required positive values; omitting them leaves them at zero and causes the request to be rejected. Existing spaces keep their configured limits, and clients such as Hubble can submit other values. Omitted compute limits are stored as `0`, continuously inheriting the corresponding CPU or memory quota. ```json @@ -213,7 +213,9 @@ GET http://localhost:8080/graphspaces/gs1 > graphspace settings with `GET /graphspaces/{name}` first and preserve fields that are not being changed. > - **Compute Limit Inheritance**: Setting `compute_cpu_limit: 0` or `compute_memory_limit: 0` (or omitting them on creation) means continuously > inheriting `cpu_limit` and `memory_limit`. Zero represents inheritance, not unlimited or zero allocation. -> On update, omitting a compute field preserves its current setting; explicit zero restores inheritance. Responses retain that zero marker. +> In Server 1.8.0+, omitting a compute field on update preserves its current setting, while an explicit zero restores inheritance. +> In Server 1.7.0, zero is ignored on update, leaving previous configured limits unchanged instead of restoring inheritance. +> Responses retain that zero marker. > - **Quota Enforcement**: Exceeding `max_graph_number` causes subsequent graph creations to fail with `reach graph limit`. Exceeding > `storage_limit` triggers PD storage enforcement, automatically marking all graphs in the space as `ReadOnly` until usage drops below the > quota on the next patrol cycle.