| 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 的引擎无关通道。完整差异矩阵见 图引擎能力矩阵。
引擎取得途径：用户告知 / 控制台「知识图谱 → 空间配置」 / 智能工作台右栏图谱空间条目的引擎标签。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 模板）。
本 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 configure set --auto-plugin-install true
aliyun plugin update
aliyun plugin install --names aliyun-cli-dataphin-public
aliyun version
aliyun dataphin-public exec-kg-cypher --help
aliyun dataphin-public get-kg-neighbor --help
详见 CLI 安装指南。
3. Environment Variables
凭证与环境变量由父 skill alibabacloud-dataphin-skills 统一声明并预检（父 §3 + §4 Authentication + §8 Step 0，先于路由到本 skill 执行）；本 skill 不重复声明。
4. Authentication
Pre-check: Credentials Required
aliyun configure list
aliyun version
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），请：
- 确认 RAM 用户已附加上述策略
- 确认策略中 Resource 范围覆盖目标租户
- 确认当前用户在知识图谱空间中具有数据查询权限
- 联系租户管理员授权
详见 RAM 策略参考。
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 参数参考。
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（语义搜索） |
| 看某实体的关系网络 | 步骤 2（邻居遍历） | 步骤 2（邻居遍历） |
在 Lindorm 空间上被要求“用 Cypher 查”时，直说不支持并给出替代方案，不要先发一次 Cypher “试试看”。
步骤 1：Cypher 图查询（仅 Neo4j 引擎空间）
Cypher 是图数据库查询语言，支持节点/关系模式匹配、属性过滤、路径查询等。
❌ Lindorm 空间不要执行本步骤：exec-kg-cypher 在 Lindorm 上固定返回 DPN.Commons.InternalError（实测，trace f3781307 连碰 3 次）。该错误不是环境故障：改写语句、降低 Limit、换标签均无效；把 Gremlin 语句（如 g.V().hasLabel('Company')）塞进 Query 字段也同样报错。Lindorm 请转步骤 2/3。
🚨 节点必须带类型标签，禁止裸 MATCH (n)：无标签查询（如 MATCH (n) RETURN labels(n), count(*)）会扫描底层图引擎 Space 全库——实测扫到 100+ 种标签、百万级节点，是性能灾难。测试/POC 环境若多个知识图谱空间共享同一 Space，还会扫到其他空间数据（实际客户部署要求一个 Space 仅绑定一个知识图谱空间，按规范部署时无跨空间数据问题）。带标签（如 MATCH (n:COMPANY)）时按类型精确命中。所有节点模式（含多跳路径两端）都必须显式指定本空间 Schema 中定义的实体类型标签。
aliyun dataphin-public exec-kg-cypher \
--op-tenant-id "{OpTenantId}" \
--workspace-id "{WorkspaceId}" \
--exec-command '{
"Query": "MATCH (n:COMPANY) RETURN n.name, n.industry LIMIT 10",
"Limit": 100
}' \
--profile {profile} --endpoint {endpoint} \
--user-agent "AlibabaCloud-Agent-Skills/query-kg/{SESSION_ID}"
--exec-command 是 JSON 对象：Query（Cypher 语句，必填）、Limit（返回上限，默认 100）、Params（参数化查询 [{DataType, Key, Value}]，可选）。
独立部署环境需加 --endpoint dataphin-openapi.<env>.aliyun.com（不带 https:// 前缀）。
响应处理：
Data.NodeList[]：匹配到的节点列表（含 DataId、EntityType、Properties[]）Data.EdgeList[]：匹配到的边列表（含 RelationId、RelationType、SourceEntityId、TargetEntityId）Data.RowList[].Columns[].Code/Value：RETURN 子句返回的标量值（与 Cypher RETURN 列对应）Data.ExecuteCypher：实际执行的 Cypher 语句
⚠️ 实测注意（RETURN n 与 DataId）：RETURN n（返回整节点）时，部分空间/版本下 DataId 可能为 null、Properties 为空——此时无法直接拿到供步骤 2 使用的 DataId。稳妥做法：在 Cypher 中 RETURN 能定位实体的具体属性（如 RETURN n.name），或改用 list-kg-entity（manage-kg-knowledge Skill）按属性过滤查回 EntityId；也需确认该实体类型已发布到图引擎（未发布类型对 get-kg-neighbor 会报 DPN.Planning.KgEntityNotExists）。标量统计（如 count(n)）走 RowList，不受影响。
Cypher 常用查询模式
# 1. 查询所有某类型实体
MATCH (c:COMPANY) RETURN c.name, c.industry LIMIT 20
# 2. 查询两个实体间的关系路径
MATCH (a:MovieActor)-[r:ACTED_IN]->(f:Film)
WHERE a.name = '张三'
RETURN a.name, f.title, r.role
# 3. 多跳路径查询（两端节点必须带标签，禁止裸 (a)/(b)）
MATCH path = (a:COMPANY)-[*1..3]->(b:COMPANY)
WHERE a.name = '起点节点'
RETURN path LIMIT 5
# 4. 聚合统计
MATCH (n:COMPANY)-[r:INVEST]->(m:COMPANY)
RETURN n.name, count(r) AS invest_count
ORDER BY invest_count DESC LIMIT 10
# 5. 属性过滤
MATCH (n:Film) WHERE n.year > 2020 RETURN n.title, n.year
限制：exec-kg-cypher 仅支持查询数据，不支持 CREATE、MERGE、DELETE、SET 等写入/修改语句。注意上方所有示例的节点模式均带类型标签——这是硬性要求，不是风格偏好。
步骤 2：邻居节点遍历
从指定实体出发，遍历其邻居节点，用于发现关联关系、构建局部子图。
aliyun dataphin-public get-kg-neighbor \
--op-tenant-id "{OpTenantId}" \
--workspace-id "{WorkspaceId}" \
--entity-data-id "{DataId}" \
--entity-type "{EntityType}" \
--neighbors-query '{"Depth": 1, "DirectionType": "Both"}' \
--profile {profile} --endpoint {endpoint} \
--user-agent "AlibabaCloud-Agent-Skills/query-kg/{SESSION_ID}"
重要：
--entity-data-id 与 --entity-type 均为必填- DataId 来源：exec-kg-cypher 返回的
NodeList[].DataId，或 list-kg-entity 返回的 EntityList[].EntityId
- 遍历控制参数收在
--neighbors-query JSON 对象内，方向字段名是 DirectionType（不是 Direction）
响应处理：
Data.NodeList[]：邻居节点列表（含 EntityId、EntityType、PropertyList[].Code/Value/DataType）Data.EdgeList[]：连接关系列表（含 RelationId、RelationType、SourceEntityId、TargetEntityId、PropertyList[]）
进阶遍历参数
aliyun dataphin-public get-kg-neighbor \
--op-tenant-id "{OpTenantId}" \
--workspace-id "{WorkspaceId}" \
--entity-data-id "{DataId}" \
--entity-type "{EntityType}" \
--neighbors-query '{"Depth": 2, "DirectionType": "Out", "RelationTypes": ["ACTED_IN", "INVEST"]}' \
--profile {profile} --endpoint {endpoint} \
--user-agent "AlibabaCloud-Agent-Skills/query-kg/{SESSION_ID}"
--neighbors-query 结构：
| 字段 | 类型 | 可选值 | 说明 |
|---|
| DirectionType | String | In / Out / Both | 遍历方向，默认 Both |
| Depth | Integer | 1~N | 扩展深度，默认 1 |
| RelationTypes | Array<String> | 关系类型编码数组 | 仅遍历指定关系类型（可选） |
步骤 3：关键词 + 语义混合搜索（引擎无关，V6.2.3+）
SearchKgBySemantic 同时执行关键词匹配与语义向量检索，经 RRF 算法融合排序返回；当语义搜索条件不满足（如无向量模型/无 SemanticEnabled 属性）时自动降级为仅关键词搜索。Neo4j 与 Lindorm 均支持，是 Lindorm 空间“找实体”的首选通道。
仅支持实体搜索，不支持关系搜索（产品侧确认）：无关系类型过滤参数，出参 MatchType 恒为 Entity。要看关系请拿到实体 ID 后转步骤 2 邻居遍历。
命令可用性：该 API 为 V6.2.3 新增，当前 CLI 插件（0.7.x）尚未注册 search-kg-by-semantic 命令（aliyun dataphin-public --help 实测 18 个 KG 命令中无此项）。路径：① 先 aliyun plugin update 后重试；② 插件仍无则走 Python Tea SDK 泛化调用（Action=SearchKgBySemantic，formData POST，参考 Python SDK 模板）；③ 在 Dataphin 智能工作台内直接用 run_kg_query(action=SearchKgBySemantic)（已封装签名，不依赖插件）。
🚨 body 字段名是 SearchCommand（实测）：接口设计文档上写的 SearchKgBySemanticCommand 服务端不认，传它会报 Dataphin.OpenAPI.BadRequest: Missing required argument: SearchCommand（工作台 trace fdbd9ed2 首次真机调用实测）。与 exec-kg-cypher 的 ExecCommand、create-kg-entity 的 CreateCommand 同款命名风格。
插件已注册时的 CLI 形式（参数名按 body 字段 kebab 化推断，插件尚未注册该命令，未实测）：
aliyun dataphin-public search-kg-by-semantic \
--op-tenant-id "{OpTenantId}" \
--workspace-id "{WorkspaceId}" \
--search-command '{
"QueryText": "做新能源汽车的公司",
"EntityTypeCodes": ["COMPANY"],
"TopK": 20,
"MinSimilarity": 0.6
}' \
--profile {profile} --endpoint {endpoint} \
--user-agent "AlibabaCloud-Agent-Skills/query-kg/{SESSION_ID}"
SearchCommand 字段：
| 字段 | 类型 | 必填 | 说明 |
|---|
| QueryText | String | 是 | 自然语言查询文本，0~500 字符 |
| EntityTypeCodes | Array<String> | 否 | 实体类型编码过滤；不传则搜所有实体类型 |
| PropertyCode | String | 否 | 指定某个属性编码做语义搜索；不传则搜所有 SemanticEnabled = true 的属性 |
| TopK | Integer | 否 | 返回上限，默认 20，范围 1~100 |
| MinSimilarity | Float | 否 | 最低相似度阈值 0.0~1.0，默认 0.0（不过滤），仅语义搜索路径生效 |
响应处理（SearchKgBySemanticResult）：
TotalCount：命中总数SearchResults[]：按相似度得分降序，每项含：
MatchType：匹配类型（当前恒为 Entity）MatchSource：keyword（仅关键词命中）/ semantic（仅语义命中）/ both（两路均命中）ItemId / ItemTypeCode：实体 ID 与实体类型编码（ItemId 可直接当作步骤 2 的 --entity-data-id）MatchedPropertyCode / MatchedPropertyValue：命中的属性编码与实际值SimilarityScore：余弦相似度得分 0.0~1.0
MatchSource=keyword 占比异常高时，通常意味着该空间没配向量模型或目标属性未开 SemanticEnabled（已降级为关键词搜索），向用户说明而不是反复调 MinSimilarity。
语义未生效的正解在 Schema 属性层，不是 Cypher：开启语义检索 = 在 Schema 的实体/关系属性上置 isSemanticEnabled: true 并导入发布（见 manage-kg-schema §开启语义检索），平台自动建向量索引；不要用 exec-kg-cypher 手建向量索引（只读通道，CREATE 会被拒）。另注意 Neo4j 版本门槛：平台发布时自动执行的 CREATE VECTOR INDEX 需 Neo4j 5.11+，低版本实例向量索引创建必失败（trace 72c13131 实测，报 Invalid input 'VECTOR'），此时语义搜索永远降级为关键词——属引擎版本限制，引导升级而非重试。
步骤 4：组合查询模式
典型的知识图谱探索流程：先定位目标实体 → 再邻居遍历展开子图。定位手段按引擎选：Neo4j 可用 Cypher；Lindorm 用语义搜索或 list-kg-entity。
模式 A（Neo4j）：Cypher 定位 → 邻居展开
aliyun dataphin-public exec-kg-cypher \
--op-tenant-id "{OpTenantId}" --workspace-id "{WorkspaceId}" \
--exec-command '{"Query": "MATCH (n:Drug {drug_code: '\''D002'\''}) RETURN n LIMIT 1", "Limit": 1}' \
--profile {profile} --endpoint {endpoint} \
--user-agent "AlibabaCloud-Agent-Skills/query-kg/{SESSION_ID}"
aliyun dataphin-public get-kg-neighbor \
--op-tenant-id "{OpTenantId}" --workspace-id "{WorkspaceId}" \
--entity-data-id "0a259156-d9f9-4bc1-be44-9b942a0b0e1a" \
--entity-type "Drug" \
--neighbors-query '{"Depth": 2, "DirectionType": "Both"}' \
--profile {profile} --endpoint {endpoint} \
--user-agent "AlibabaCloud-Agent-Skills/query-kg/{SESSION_ID}"
可用全局参数 --cli-query <jmespath> 直接过滤输出，如 --cli-query 'Data.NodeList[0].DataId'。
模式 B（Lindorm，也适用于 Neo4j）：语义搜索 / 实体列表定位 → 邻居展开
aliyun dataphin-public list-kg-entity \
--op-tenant-id "{OpTenantId}" --workspace-id "{WorkspaceId}" \
--entity-type "COMPANY" \
--list-query '{"Keyword": "阿里", "FilterList": [{"PropertyCode": "industry", "Op": "eq", "Value": "互联网"}], "PageNum": 1, "PageSize": 20}' \
--profile {profile} --endpoint {endpoint} \
--user-agent "AlibabaCloud-Agent-Skills/query-kg/{SESSION_ID}" \
--cli-query 'PageResult.EntityList[0].EntityId'
aliyun dataphin-public get-kg-neighbor \
--op-tenant-id "{OpTenantId}" --workspace-id "{WorkspaceId}" \
--entity-data-id "{EntityId}" \
--entity-type "COMPANY" \
--neighbors-query '{"Depth": 2, "DirectionType": "Both"}' \
--profile {profile} --endpoint {endpoint} \
--user-agent "AlibabaCloud-Agent-Skills/query-kg/{SESSION_ID}"
list-kg-entity 的实体类型走扁平参数 --entity-type（实测把 EntityType 写进 --list-query 会报 unknown field: EntityType）；分页/过滤才在 --list-query 里。
兜底：旧版本独立部署（SDK 泛化调用）
独立部署低于 KG OpenAPI 发布版本（< v6.1.1）未发布 KG OpenAPI 时，使用封装脚本 scripts/query-kg.py（Python Tea SDK call_api()）：
pip install alibabacloud-tea-openapi alibabacloud-tea-util
python3 scripts/query-kg.py cypher --query "MATCH (n:COMPANY) RETURN n.name LIMIT 10" [--limit 100] [--ignore-ssl]
python3 scripts/query-kg.py neighbor --entity-data-id "<DataId>" --entity-type "<EntityType>" [--direction Both] [--depth 1] [--ignore-ssl]
脚本已固化 ExecCommand 参数名、EntityDataId/EntityType 必填、POST 方法等实测暗坑；独立部署自签证书加 --ignore-ssl。SDK 调用细节见 Python SDK 模板。
9. Success Verification
- 引擎判定正确：所选命令与空间引擎匹配（Lindorm 空间未发起任何
exec-kg-cypher 调用）
- Cypher 查询（Neo4j）：
exec-kg-cypher 返回非空 Data.RowList（标量查询）或 Data.NodeList（节点查询）
- 邻居遍历：
get-kg-neighbor 返回 Data.NodeList 和 Data.EdgeList，且与预期关联关系一致
- 语义搜索：
SearchKgBySemanticResult.TotalCount > 0 且 SearchResults[].SimilarityScore 降序；MatchSource 含 semantic/both 说明语义路径生效（全为 keyword 则已降级）
- 无错误：响应中
Code 为 OK、Success 为 true，无 Dataphin.KG.* 错误码
10. Cleanup
本 Skill 为纯只读查询，不创建任何资源，无需清理。
11. Command Tables
| CLI 命令 | 用途 | 适用引擎 | 关键参数 |
|---|
exec-kg-cypher | 执行 Cypher 查询（只读） | 仅 Neo4j | --exec-command（JSON：Query/Limit/Params） |
get-kg-neighbor | 获取邻居节点 | Neo4j + Lindorm | --entity-data-id + --entity-type（均必填）、--neighbors-query（JSON：Depth/DirectionType/RelationTypes） |
search-kg-by-semantic | 关键词+语义混合搜索（仅实体，V6.2.3+） | Neo4j + Lindorm | --search-command（JSON：QueryText/EntityTypeCodes/PropertyCode/TopK/MinSimilarity；body 字段名实测为 SearchCommand） |
exec-kg-gremlin | Gremlin 查询 | — | API 尚未上线，命令不存在，不要尝试 |
exec-kg-cypher / get-kg-neighbor 已注册到 CLI 插件（>= 0.7.1，--help 实测 Online version v6.1.1）；search-kg-by-semantic 为 V6.2.3 新增，插件 0.7.x 尚未注册（先 aliyun plugin update，仍无则走 SDK 泛化调用或工作台 run_kg_query）。公共参数 --op-tenant-id / --workspace-id 必填。旧版本独立部署（< v6.1.1）用 scripts/query-kg.py SDK 兜底。
详见 相关命令索引。
12. Best Practices
- 先确认图引擎，再选命令（最重要）：Neo4j 支持 Cypher；Lindorm 不支持 Cypher，
exec-kg-cypher 固定报 DPN.Commons.InternalError。引擎不明时直接问用户（OpenAPI 无查空间引擎的接口），不要默认 Neo4j。完整矩阵见 图引擎能力矩阵
- Lindorm 上的 InternalError 不要重试（实测）：改写语句、降
Limit、换标签都无效；也不要把 Gremlin 语句塞进 --exec-command 的 Query（trace f3781307 这两个反模式各浪费一轮）
- 不要尝试
exec-kg-gremlin：ExecKgGremlin API 尚未上线，CLI 插件（实测 18 个 KG 命令）无此命令；也不要用 aliyun dataphin-public --version 探版本（非法用法，报 parse failed --version must be assigned with value）
- Lindorm 空间的图查询组合：
search-kg-by-semantic（自然语言找实体）+ list-kg-entity（类型/属性过滤）+ get-kg-neighbor（展子图）；确需多跳图计算则引导用户到控制台图谱视图
- 语义搜索仅实体 + body 字段名是
SearchCommand（实测）：SearchKgBySemantic 不支持关系搜索（无关系类型过滤参数，MatchType 恒为 Entity）；要看关系先拿 ItemId 再 get-kg-neighbor。接口文档写的 SearchKgBySemanticCommand 服务端不认，传它报 Dataphin.OpenAPI.BadRequest: Missing required argument: SearchCommand。MinSimilarity 只影响语义路径，全部命中都是 MatchSource=keyword 时说明已降级（缺向量模型/属性未开 SemanticEnabled），别反复调阈值
- CLI 原生优先：KG API 已注册到 CLI 插件（>= 0.7.1），直接使用
aliyun dataphin-public exec-kg-cypher / get-kg-neighbor，无需 SDK；search-kg-by-semantic（V6.2.3 新增）插件未注册时才退 SDK/工作台工具
- 插件版本前置检查：命令报 unknown command 时先
aliyun plugin update（KG 命令自 0.7.x 注册）
--exec-command 字段名（实测）：参数名是 --exec-command（不是 --execute-command），JSON 内查询字段是 Query（不是 Code）；写错报 Error: --exec-command is required- DirectionType 字段名：
--neighbors-query 中方向字段是 DirectionType（不是 Direction），取值 / /
