bitflicker64 commented on code in PR #540: URL: https://github.com/apache/hugegraph-doc/pull/540#discussion_r4304830910
########## content/cn/docs/quickstart/toolchain/hugegraph-hubble.md: ########## @@ -50,21 +49,25 @@ docker compose -p "$HUBBLE_DEMO_PROJECT" -f docker-compose.yml ps curl -fsS http://127.0.0.1:8080/versions ``` -服务健康后，打开 <http://127.0.0.1:8088>。全新目录未配置 `HUGEGRAPH_ADMIN_PASSWORD` 时，Server 允许匿名访问， -Hubble 直接进入首页。需要认证时，按 Docker README 配置 `.env` 中的管理员密码与 JWT 密钥，使用 Server 账号登录； -Hubble 没有独立账号库。个人中心与账号管理只在相应认证和权限条件下显示，不要覆盖已有 `.env`。 +服务启动完成后，在浏览器访问 <http://127.0.0.1:8088>。若未在 `.env` 中配置 `HUGEGRAPH_ADMIN_PASSWORD`，Server 默认允许匿名访问， +Hubble 会直接进入首页。若已启用认证，请根据 Docker README 在 `.env` 中配置管理员密码与 JWT 密钥，并使用 Server 账号登录（Hubble 无独立用户库）。 +个人中心与账号管理入口仅在开启认证且具备相应权限时展示。 + +`latest` 镜像便于快速体验最新功能，生产环境建议指定发布版本号或镜像 digest。正式发布包可前往 [下载页](/cn/docs/download/download/) 获取。 + +> [!DETAILS]- 核实部署版本 +> +> 文档截图用于定位界面元素，实际版本以部署镜像的 digest 及构建信息为准。 -`latest` 便于体验当前功能，正式部署应固定镜像版本或 digest。镜像是便捷分发物，正式发布包见 [下载页](/cn/docs/download/download/)。 -算法与账号配图使用 Toolchain `1.8.0` 构建的 Hubble 与 Server `1.7.0`。Hubble 的 `/about` 当前返回静态值 `3.0.0`， -不能据此判断构建版本；此组合只说明这些配图的运行环境，不保证 `latest` 始终对应这些版本。界面入口仍取决于 Server 提供的能力。 -Compose 的 `server-data` 和 `hubble-data` 分别保存图数据与 Hubble 元数据；更多持久化与生产配置见 +Compose 中的 `server-data` 与 `hubble-data` 卷分别持久化保存图数据与 Hubble 元数据；更多生产配置参见 [Server 部署指南](/cn/docs/quickstart/hugegraph/hugegraph-server/)。 ## 首页：找到当前任务的入口 首页按“图概览 → 图导入 → 图查询”组织工作入口，适合第一次使用时了解整体流程。 -左侧导航可随时返回各栏目；顶部的图选择器决定查询、Schema 和异步任务的操作对象，切换页面后也要留意当前图。 -单机模式只有 `DEFAULT` 图空间，不需要额外配置 PD。 +首页按“图概览 → 图导入 → 图查询”组织核心工作流。左侧导航栏可随时切换各功能模块； Review Comment: Minor: The rewrite added a new sentence but kept the old one, so the section now opens with two sentences that both start with `首页按“图概览 → 图导入 → 图查询”组织` (lines 67 and 68). The English guide has one. Please delete line 67 or merge the two. ########## content/en/docs/quickstart/toolchain/hugegraph-hubble.md: ########## @@ -147,16 +140,49 @@ Inspect person properties in table or JSON view. To visualize the people-to-soft g.V().hasLabel('person').outE('created').inV().path() ``` - - Graph results support 2D / 3D. Click a vertex or edge to inspect its ID, label, and properties; double-click a vertex to expand its neighbors. Layout, styling, and filtering help highlight relevant relationships, while export helps share results. -Use **New** to create elements, or edit existing data when authorized. Layout, colors, and display limits only change presentation; -adding/editing elements and Gremlin writes change Server data. +Use **New** to create elements, or edit existing data when authorized. Layout adjustments, styling, and display bounds only affect the local canvas; +adding or editing elements via the UI or executing Gremlin write statements modifies underlying Server graph data. + +Press `Ctrl` / `Command` + `Enter` to execute queries quickly. Immediate execution is ideal for interactive exploration; submit long or resource-intensive +queries as background async tasks. Cypher is available when supported by the backend Server. +The keyboard shortcut acts on whichever input currently has focus: generating a query from +the natural language prompt, or running statements in the code editor. -Use `Ctrl` / `Command` + `Enter` to execute. Immediate mode suits small explorations; submit long queries asynchronously -and avoid returning an entire large graph. Cypher is available only when Server supports it. -Text2GQL is currently a UI preview with no model or query service connected; it cannot generate executable queries. +### Text2GQL natural-language queries {#text2gql} + +Describe your query requirement in the **Natural language** input. Text2GQL combines the current graph schema to generate read-only Gremlin or Cypher +and execute it automatically. Generated statements can be edited freely (read-only safety checks still apply before execution). +In **Async** mode, both generated and handwritten queries can be submitted as background tasks. +Inputs automatically restore the graph's most recent query prompt without running it, and the execution history retains original natural-language questions. + +```gallery + # Query workspace Review Comment: Minor: The three English Text2GQL screenshots show the Chinese UI. `content/en/docs/images/hubble/text2gql.jpg`, `text2gql-settings.jpg` and `text2gql-prompt.jpg` have the same md5 as their `content/cn/...` copies (for example 2982a7f4... for `text2gql.jpg`), while the other English Hubble screenshots such as `overview.jpg` are captured with the English locale. The English text refers to **Natural language**, **System & Operations -> Model settings** and **Apply**, none of which appear in these images. Please recapture the English set with the EN locale. ########## content/en/docs/quickstart/toolchain/visualization/hugegraph-hubble-hstore.md: ########## @@ -6,45 +6,44 @@ weight: 2 search_keywords: [HugeGraph Hubble, HStore, PD, GraphSpace, cluster management] --- -This guide covers the differences between HStore + PD and standalone RocksDB. -For modeling, importing data, and querying, see the [Hubble standalone guide](/docs/quickstart/toolchain/hugegraph-hubble/). -This guide follows Toolchain `master`. +This guide highlights the key differences between HStore + PD distributed deployments and standalone RocksDB. +For general graph modeling, data import, and query workflows, see the [Hubble standalone guide](/docs/quickstart/toolchain/hugegraph-hubble/). +Content aligns with the Toolchain, Server, PD, and Store `master` branches (all currently `1.8.0`). The main repository's [docker/docker-compose-hstore.yml](https://github.com/apache/hugegraph/blob/master/docker/docker-compose-hstore.yml) -already combines PD, Store, Server, and Hubble. Follow the adjacent -[Docker README](https://github.com/apache/hugegraph/blob/master/docker/README.md) to prepare `.env` and generated Hubble local configuration, -then start it from `docker/`; do not maintain another deployment YAML. -The settings below explain connection differences and do not replace the README's PD credential and service-readiness requirements. - -The screenshots use Hubble built from Toolchain `1.8.0` with Server, PD, and Store `1.7.0`. Hubble currently returns the static value `3.0.0` -from `/about`, which does not identify its build version. This pairing describes the screenshot environment; `latest` is mutable. +provides complete orchestration for PD, Store, Server, and Hubble. Follow the adjacent +[Docker README](https://github.com/apache/hugegraph/blob/master/docker/README.md) to prepare `.env` and generate the local Hubble configuration, +then launch services from `docker/` without maintaining separate Compose files. +The guidance below focuses on connectivity and operations; ensure prerequisite credentials and service readiness from the README are met. +Docker `latest` is a moving tag. Screenshots assist in UI navigation; verify deployed versions via image digests and build details. Metrics and permission APIs vary by version. ## Connect to a distributed cluster Hubble still manages graph data through the **Server graph API**. In distributed mode, it discovers Servers through PD and collects cluster information from PD and Store. Hubble does not read or write graph data directly in Store. -For the official Compose deployment, prepare `.env` in the main repository's `docker/` directory following its README, then generate the Hubble configuration: +1. **Generate Hubble configuration.** Prepare `.env` in the main repository's `docker/` directory following the Docker README. -```bash -set -a -. ./.env -set +a -./set-hubble-pd-password.sh hstore -``` + ```bash + set -a + . ./.env + set +a + ./set-hubble-pd-password.sh hstore + ``` -The script reads the loaded `HG_PD_AUTH_SECRET_KEY` and writes the PD operations password to the host file -`docker/conf/hubble/hstore.local.properties`. Edit this generated file to customize connection or operations settings, preserving -`operations.pd.password` so it matches PD's secret. Do not replace it with the tracked `.example` template. Compose mounts it read-only at -`/hubble/conf/hugegraph-hubble.properties` inside the container; do not edit it there. Do not commit the generated file or `.env`. -Running the script again overwrites the generated file, so reapply custom settings afterward. + The script reads `HG_PD_AUTH_SECRET_KEY` from `.env` and writes the generated PD operations password to the host file Review Comment: Minor: "writes the generated PD operations password" reads as if the script creates a new password. `docker/set-hubble-pd-password.sh` takes `secret=${2:-${HG_PD_AUTH_SECRET_KEY:-}}` and writes that value as `operations.pd.password`; it generates the properties file, not the password. Please say it writes the value of `HG_PD_AUTH_SECRET_KEY` as `operations.pd.password` into the generated file. The Chinese step at `content/cn/docs/quickstart/toolchain/visualization/hugegraph-hubble-hstore.md:34` ("将生成的 PD 运维密码写入") needs the same wording change. ########## content/en/docs/quickstart/toolchain/hugegraph-hubble.md: ########## @@ -1,45 +1,43 @@ --- title: "Graph Visualization with Hubble: Standalone Quick Start" -description: "Visualize graph data with Hubble and RocksDB Server: start with Docker, explore schema, import CSV, and run Gremlin queries." +description: "Use Hubble and RocksDB Server to manage schema, import CSV, and query graph data with Gremlin, Cypher, or Text2GQL." linkTitle: "Hubble Basics and Standalone" weight: 1 -search_keywords: [HugeGraph Hubble, graph visualization, Web management interface, RocksDB] +search_keywords: [HugeGraph Hubble, graph visualization, Web management interface, RocksDB, Text2GQL, natural-language queries, Prompt] search_boost: 1.6 --- -Hubble is the HugeGraph Web management and graph visualization interface. Use one workspace to manage schema, import data, run queries, -and switch between graph, table, and JSON results. This guide uses **standalone RocksDB Server + Hubble**, without PD or Store. +Hubble is the HugeGraph Web management and graph visualization interface. Use a single workspace to manage schema, import data, run queries, +and switch smoothly between graph, table, and JSON results. This guide uses **standalone RocksDB Server + Hubble**, without requiring PD or Store. -For HStore, read the shared operations here first, then follow the [distributed supplement](/docs/quickstart/toolchain/visualization/hugegraph-hubble-hstore/). -This guide follows Toolchain `master` (currently `1.8.0`); Docker `latest` is mutable, so check the actual running versions. +For use with an HStore distributed cluster, read the foundational operations here first, then consult the +[distributed supplement](/docs/quickstart/toolchain/visualization/hugegraph-hubble-hstore/). +This guide aligns with the Toolchain and Server `master` branches (both currently `1.8.0`). > [!WARNING] -> Do not expose Hubble or Server directly to the public network. In production, use HTTPS, containers, -> [authentication and authorization](/docs/config/config-authentication/), and an access allowlist. - +> Do not expose unauthenticated Hubble or Server instances directly to the public internet. In production, use HTTPS, container isolation, +> [authentication and authorization](/docs/config/config-authentication/), and network allowlists. ## Start the standalone pair Use the main repository's [docker/docker-compose.yml](https://github.com/apache/hugegraph/blob/master/docker/docker-compose.yml) -instead of writing another Compose file. It already combines RocksDB Server and Hubble, with networking, health checks, and data volumes. -See the adjacent [README](https://github.com/apache/hugegraph/blob/master/docker/README.md) for deployment details. +instead of writing custom Compose files. It already integrates RocksDB Server and Hubble with networking, health checks, and data volumes; +see the adjacent [README](https://github.com/apache/hugegraph/blob/master/docker/README.md) for deployment details. ```bash git clone --branch master --single-branch --depth 1 https://github.com/apache/hugegraph.git cd hugegraph/docker ``` -If you already have the main repository, enter its `docker/` directory. Compose mounts -[`conf/hubble/standalone.properties`](https://github.com/apache/hugegraph/blob/master/docker/conf/hubble/standalone.properties) -from that directory. It sets `pd.enabled=false` and `server.direct_url=http://server:8080`; -both services communicate over one Docker network, without a Server address configured per graph. -Do not download only the YAML and start it from another directory: relative configuration files may be missing. +If you already have the repository locally, navigate directly to its `docker/` directory. Compose automatically mounts +[`conf/hubble/standalone.properties`](https://github.com/apache/hugegraph/blob/master/docker/conf/hubble/standalone.properties), +which pre-configures `pd.enabled=false` and `server.direct_url=http://server:8080`. Because both services communicate over a shared Docker network, +you do not need to configure Server endpoints per graph. Start Compose directly from `docker/` so relative file paths resolve correctly. -Hubble defaults to host loopback port `8088`; Server publishes `8080`. For a trial on your machine only, change Server's -`ports` entry to `127.0.0.1:8080:8080` to avoid exposing the anonymous API to other machines. +Hubble listens on host port `8088` by default; Server publishes `8080`. For a local trial, set Server's Review Comment: Minor: The old text said Hubble is published on host loopback by default, and that is still true: `docker/docker-compose.yml` maps `${HUBBLE_PUBLISH_HOST:-127.0.0.1}:8088:8088` while Server maps `8080:8080` on all interfaces. "Hubble listens on host port `8088` by default" drops that, and the contrast is why the next sentence asks only for Server's `ports` to change. Please keep "loopback" (and mention `HUBBLE_PUBLISH_HOST` if remote access is expected). The Chinese line `content/cn/docs/quickstart/toolchain/hugegraph-hubble.md:36` ("默认监听宿主机 `8088` 端口") lost the same detail. ########## content/en/docs/quickstart/toolchain/hugegraph-hubble.md: ########## @@ -147,16 +140,49 @@ Inspect person properties in table or JSON view. To visualize the people-to-soft g.V().hasLabel('person').outE('created').inV().path() ``` - - Graph results support 2D / 3D. Click a vertex or edge to inspect its ID, label, and properties; double-click a vertex to expand its neighbors. Layout, styling, and filtering help highlight relevant relationships, while export helps share results. -Use **New** to create elements, or edit existing data when authorized. Layout, colors, and display limits only change presentation; -adding/editing elements and Gremlin writes change Server data. +Use **New** to create elements, or edit existing data when authorized. Layout adjustments, styling, and display bounds only affect the local canvas; +adding or editing elements via the UI or executing Gremlin write statements modifies underlying Server graph data. + +Press `Ctrl` / `Command` + `Enter` to execute queries quickly. Immediate execution is ideal for interactive exploration; submit long or resource-intensive +queries as background async tasks. Cypher is available when supported by the backend Server. +The keyboard shortcut acts on whichever input currently has focus: generating a query from +the natural language prompt, or running statements in the code editor. -Use `Ctrl` / `Command` + `Enter` to execute. Immediate mode suits small explorations; submit long queries asynchronously -and avoid returning an entire large graph. Cypher is available only when Server supports it. -Text2GQL is currently a UI preview with no model or query service connected; it cannot generate executable queries. +### Text2GQL natural-language queries {#text2gql} Review Comment: Important: The PR body names apache/hugegraph-toolchain#824 as the companion; the problem is merge order. This section documents the #824 backend (Model settings, built-in and temporary models, Prompt templates, `data/text2gql-master.key`), but #824 is still open. Toolchain master (09f9aa1c) has no `Text2Gql*` class under `hubble-be/src/main/java`, and `hubble-fe/src/modules/analysis/QueryBar/Home/index.js:160` still renders the placeholder with `TODO(text2gql): connect a reviewed backend contract`. Line 15 says the guide aligns with Toolchain `master`, and startup uses `HUGEGRAPH_VERSION=latest`, so a reader who follows it today gets the preview tab and no Model settings page. Please hold this PR until #824 is merged and an image includes it, or add a note that Text2GQL needs a Hubble build with #824. The Chinese section at `content/cn/docs/quickstart/toolchain/hugegraph-hubble.md:144` has the same dependency. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
