/query-kg

name: query-kg
description: |
  知识图谱图数据查询。通过 CLI 原生命令完成：Cypher 图查询（仅 Neo4j 引擎）、邻居节点遍历与关键词/语义混合搜索（引擎无关）。纯查询 Skill，不含任何写操作。查询前必须先确认图谱空间绑定的图引擎（Neo4j / Lindorm）——Lindorm 不支持 Cypher。
  触发场景：知识图谱查询 / Cypher 查询 / 邻居遍历 / 图查询 / 关系路径查询 / 语义搜索 / 知识图谱探索。

知识图谱图数据查询（query-kg）

1. Scenario Description

数据分析师或数据工程师通过阿里云 CLI 对知识图谱进行只读查询，包括 Cypher 图查询语言、邻居节点遍历与关键词/语义混合搜索，用于数据探索、关系路径分析和图谱可视化数据获取。

> **🚨 第一步先确认图引擎（硬前置）**：知识图谱空间创建时绑定一个图引擎，**引擎直接决定可用的查询通道**： > > | 引擎 | Cypher（`exec-kg-cypher`） | 邻居遍历（`get-kg-neighbor`） | 语义搜索（`search-kg-by-semantic`） | > |---|---|---|---| > | **Neo4j** | ✅ 支持 | ✅ | ✅（V6.2.3+） | > | **Lindorm 图引擎**（V6.2.3 新增） | ❌ **不支持**，调用固定报 `DPN.Commons.InternalError`（实测） | ✅ 实测通过 | ✅ 实测通过（V6.2.3+） | > > Lindorm 的查询语言是 Gremlin，但 **`ExecKgGremlin` OpenAPI 尚未上线**（CLI 插件实测无 `exec-kg-gremlin` 命令）。在 Lindorm 空间上做图查询，请直接走步骤 2/3/4 的引擎无关通道。完整差异矩阵见 [图引擎能力矩阵](../graph-engine-capabilities.md)。 > > 引擎取得途径：用户告知 / 控制台「知识图谱 → 空间配置」 / 智能工作台右栏图谱空间条目的引擎标签。**OpenAPI 无查空间详情/引擎的接口，不确定时直接问用户，不要默认当作 Neo4j。**

**业务流程：**

确认图引擎 → （Neo4j）Cypher 查询探索 / （Lindorm）实体列表 + 语义搜索定位 → 邻居节点遍历 → 结果分析

**资源拓扑：**

知识图谱空间（Workspace）
└── 图引擎（Neo4j 或 Lindorm，创建时绑定）
    ├── Cypher 查询（只读，**仅 Neo4j**）
    │   ├── MATCH / WHERE / RETURN
    │   ├── 节点属性过滤
    │   └── 路径查询与聚合
    ├── 邻居节点遍历（引擎无关）
    │   ├── 方向控制（DirectionType: In/Out/Both）
    │   ├── 深度控制（Depth）
    │   └── 关系类型过滤（RelationTypes）
    └── 关键词+语义混合搜索（引擎无关，V6.2.3+，**仅实体**）
        ├── QueryText 自然语言查询
        ├── EntityTypeCodes / PropertyCode 过滤
        └── TopK / MinSimilarity 阈值控制

**前置条件：**

• 知识图谱空间已存在且 Schema 已发布到图引擎（`manage-kg-schema` Skill 产出）
• 知识数据已写入（`manage-kg-knowledge` Skill 产出）
• OpTenantId（租户 ID）、WorkspaceId（空间 ID）**与该空间的图引擎**已知

> **CLI 原生支持**：KG OpenAPI 已正式发布（CLI `--help` 实测显示 Online version: **v6.1.1**，以 `aliyun dataphin-public exec-kg-cypher --help` 实际输出为准），并注册到 `aliyun-cli-dataphin-public` 插件（**>= 0.7.1**）。本 Skill 全部使用 CLI 原生命令 `exec-kg-cypher` / `get-kg-neighbor`，无需 Python SDK。 > > **旧环境兜底**：独立部署低于 KG OpenAPI 发布版本（< v6.1.1）的环境未发布 KG OpenAPI，CLI 命令会报 API 不存在——此时可退回 Python Tea SDK `call_api()` 泛化调用，本 Skill 保留封装脚本 `scripts/query-kg.py`（见 [Python SDK 模板](./references/python-sdk-template.md)）。

> **本 Skill 纯只读**：不涉及任何写操作（无 HITL 确认），查询结果不影响图谱数据。

2. Installation

**Pre-check: Aliyun CLI >= 3.4.8 required** > 运行 `aliyun version` 确认版本 >= 3.4.8。未安装或版本过低，请从 https://aliyuncli.alicdn.com 安装/升级（各操作系统一键脚本见 ./references/cli-installation-guide.md）。

**Pre-check: Aliyun CLI plugin update required** > [MUST] 运行 `aliyun configure set --auto-plugin-install true` 开启插件自动安装。 > [MUST] 运行 `aliyun plugin update` 确保已装插件保持最新（KG 命令要求插件 **>= 0.7.1**）。

# 安装 aliyun CLI（>= 3.4.8）：https://github.com/aliyun/aliyun-cli
# 各操作系统一键安装脚本见 ./references/cli-installation-guide.md

# 开启插件自动安装并更新已装插件
aliyun configure set --auto-plugin-install true
aliyun plugin update

# 安装 dataphin-public 插件（>= 0.7.1，KG 命令自 0.7.x 起注册）
aliyun plugin install --names aliyun-cli-dataphin-public

# 验证：KG 查询命令已注册
aliyun version            # 需 >= 3.4.8
aliyun dataphin-public exec-kg-cypher --help
aliyun dataphin-public get-kg-neighbor --help

详见 [CLI 安装指南](./references/cli-installation-guide.md)。

3. Environment Variables

> 凭证与环境变量由父 skill `alibabacloud-dataphin-skills` 统一声明并预检（父 §3 + §4 Authentication + §8 Step 0，先于路由到本 skill 执行）；本 skill 不重复声明。

4. Authentication

Pre-check: Credentials Required

# 检查凭证配置
aliyun configure list

# 检查 CLI 版本
aliyun version
# 要求 >= 3.4.8

# 检查 KG 命令已注册（插件 >= 0.7.1）
aliyun dataphin-public exec-kg-cypher --help

**凭证不可打印**：任何时候不得将 AccessKey ID/Secret 输出到终端或日志。

5. RAM Policy

本 Skill 仅涉及只读 API，最小 RAM 权限：

{
  "Effect": "Allow",
  "Action": [
    "dataphin:ExecKgCypher",
    "dataphin:GetKgNeighbor",
    "dataphin:SearchKgBySemantic"
  ],
  "Resource": "*"
}

Permission Failure Handling

若遇到权限错误（HTTP 403 或 ErrorCode 含 `Forbidden`/`NoPermission`/`Dataphin.KG.NoPermission`），请： 1. 确认 RAM 用户已附加上述策略 2. 确认策略中 Resource 范围覆盖目标租户 3. 确认当前用户在知识图谱空间中具有数据查询权限 4. 联系租户管理员授权

详见 [RAM 策略参考](../../ram-policies.md)。

6. Parameter Confirmation

> **IMPORTANT: Parameter Confirmation** > 执行前必须确认以下业务参数：

| 参数 | CLI 标志 | 含义 | 获取方式 | 必填 | |------|---------|------|---------|------| | **图引擎** | （不是 CLI 参数） | 空间绑定的引擎：`Neo4j` / `Lindorm` | **向用户确认**（或看工作台右栏引擎标签 / 控制台空间配置） | **是（选命令前置）** | | OpTenantId | `--op-tenant-id` | 租户 ID | profile 或询问用户 | 是 | | WorkspaceId | `--workspace-id` | 知识图谱空间 ID | **必须向用户索取**（见下方说明） | 是 | | ExecCommand | `--exec-command` | Cypher 查询指令 JSON（`{Query, Limit, Params}`） | 用户编写 | exec-kg-cypher（仅 Neo4j） | | EntityDataId | `--entity-data-id` | 起始实体 DataId | `list-kg-entity` 的 `EntityList[].EntityId`（Neo4j 也可用 Cypher 的 `NodeList[].DataId`） | get-kg-neighbor | | EntityType | `--entity-type` | 起始实体类型 | `export-kg-schema` 或上游查询结果 | get-kg-neighbor | | NeighborsQuery | `--neighbors-query` | 遍历指令 JSON（`{Depth, DirectionType, RelationTypes}`） | 用户指定 | get-kg-neighbor（可选） | | SearchCommand | （见步骤 3） | 搜索指令（`{QueryText, EntityTypeCodes, PropertyCode, TopK, MinSimilarity}`），**字段名是 `SearchCommand` 不是 `SearchKgBySemanticCommand`** | 用户描述转写 | search-kg-by-semantic |

> **图引擎未确认前不要发图查询**：Lindorm 空间上发 Cypher 必报 `DPN.Commons.InternalError`，白费一次调用且易误判为环境故障。

> **WorkspaceId 无自助发现途径**：KG OpenAPI **不提供列出 KG 空间的接口**（全部 18 个 KG 命令中无任何 list-workspace 类命令），WorkspaceId 必须向用户索取（32 位小写 hex 字符串，可在控制台知识图谱空间列表页查到）。不要尝试猜命令或翻 help 探索。

详细 API 入参/出参见 [KG Query API 参数参考](./references/kg-query-api-params.md)。

7. Observability

本子 Skill 的 session-id **继承自父 Skill `alibabacloud-dataphin-skills`**，不重新生成。

所有 CLI 命令携带：

--user-agent AlibabaCloud-Agent-Skills/query-kg/{SESSION_ID}

其中 `{SESSION_ID}` 为父 Skill 生成的 32 字符小写十六进制字符串。

8. Core Workflow

步骤 0：确认图引擎（选命令的分水岭）

开始任何图查询前先确认引擎，再按下表选路径：

| 需求 | Neo4j 空间 | Lindorm 空间 | |---|---|---| | 自由图查询 / 多跳路径 / 聚合统计 | 步骤 1（Cypher） | ❌ 无通道——先向用户说明，再用步骤 2/3 组合逼近；确需复杂图计算则引导到控制台图谱视图 | | 按类型/属性找实体 | `list-kg-entity`（manage-kg-knowledge） | `list-kg-entity` | | 自然语言/近似词找实体 | 步骤 3（语义搜索） | 步骤 3（语义