作者：隰宗正(霜键)

01 当可观测数据遇上“关系图谱”

1.1 从“孤立的实体”到“连接的网络”

在现代云原生架构的宏大叙事中，我们习惯于将系统中的每个组件——服务、容器、中间件、基础设施，视为独立的“实体”进行监控和管理。我们为它们配置仪表盘，设置告警，追踪它们的性能指标。然而，这种“个体视角”存在一个根本性的盲点：它忽略了系统最本质的特征——连接（Connection）。任何一个实体都不是孤立存在的，它们通过调用、依赖、包含等关系，构成了一张复杂巨大、动态变化的“关系图谱”。

传统的监控和查询工具，无论是基于 SQL 还是 SPL，其核心都是处理二维的、表格化的数据。它们擅长回答关于“个体”的问题（“这个 Pod 的 CPU 使用率是多少？”），但在回答关于“关系”的问题时却显得力不从心。当面对“这个服务的故障会影响哪些下游业务？”或“要访问到核心数据库，需要经过哪些中间服务？”这类问题时，传统工具往往需要复杂的 JOIN 操作、多步查询，甚至需要工程师结合线下架构图进行“人脑拼凑”。这种方式不仅效率低下，而且在关系复杂、层级深的情况下几乎无法完成。我们拥有了所有“点”的数据，却失去了一张看清“线”的地图。

1.2 我们的思路：融合图查询

面对这一挑战，我们的解决思路是：将“图”（Graph）作为可观测数据模型的重要组成。我们认为，系统的真实形态本就是一张图，那么对它的查询和分析，也应该使用最符合其本质的方式——图查询。

为了实现这一点，我们在 UModel 体系的核心构建了 EntityStore。它采用了创新的双存储架构，同时维护了 __entity__日志库（存储实体的详细属性）和 __topo__日志库（存储实体间的拓扑关系）。这相当于我们为整个可观测系统建立了一个实时更新的、可查询的数字孪生图谱。

基于这个图谱，我们提供了从易到难、层层递进的三种图查询能力，以满足不同用户的需求：

graph-match：为最常见的路径查询场景设计，语法直观，让用户能像描述一句话一样（“A 经过 B 调用了 C”）来快速查找特定链路。
graph-call：封装了最高频的图算法（如邻居查找、直接关系查询），通过函数式接口提供，用户只需关心意图（“找 A 的 3 跳邻居”）而无需关心实现细节。
Cypher：引入业界标准的图查询语言，提供最完整、最强大的图查询能力，支持任意复杂的模式匹配、多级跳跃、聚合分析，是处理复杂图问题的终极武器。

这一整套解决方案，旨在将强大的图分析能力，以一种低门槛、工程化的方式，提供给每一位运维和开发工程师。

1.3 核心价值：解锁系统洞察的新维度

引入图查询能力，不仅仅是增加了一种新的查询语法，更是为系统洞察解锁了一个全新的维度。

全局化的故障影响分析（爆炸半径分析）：当故障发生时，可以通过一次查询，快速确定该故障点向下游辐射的所有可能路径和受影响的业务范围，为故障处理的优先级排序和决策提供实时数据支持。
端到端的根因溯源：与影响分析相反，当某个底层服务出现问题时，可以向上游回溯，快速定位是哪个业务或变更触发了异常，实现精准的根因定位。
架构健康度与合规性审计：可以通过图查询来验证线上系统的实际架构是否与设计相符。例如，查询是否存在“跨网络域的非法调用”，或者“某个核心数据服务是否被非授权的应用依赖”，从而实现架构的持续治理。
安全与权限链路分析：在安全审计中，可以追踪从用户到具体资源的完整访问路径，确保每一层权限授予都符合安全规范，防止潜在的数据泄露风险。

总而言之，图查询能力将我们对系统的认知从“点的集合”提升到了“结构化的网络”，使得我们能够基于系统组件之间的真实关系进行提问和分析，从而获得前所未有的深度洞察力。它是一把钥匙，开启了在复杂系统中进行高效故障排查、架构治理和安全审计的大门。

02 图查询相关概念

2.1 相关概念

协作关系：

UModel (知识图谱)
├── EntitySet: apm.service (类型定义)
│   ├── Entity: user-service (实例1)
│   ├── Entity: payment-service (实例2)
│   └── Entity: order-service (实例3)
├── EntitySet: k8s.pod (类型定义)
│   ├── Entity: web-pod-123 (实例1)
│   └── Entity: api-pod-456 (实例2)
└── EntitySetLink: service_runs_on_pod (关系定义)
    ├── Relation: user-service -> web-pod-123
    └── Relation: payment-service -> api-pod-456

EntityStore 借助于 SLS LogStore 资源实现数据写入、消费等功能，在创建 EntityStore 时，会同步创建以下 LogStore 资产：

${workspace}__entity：用于写入实体数据
${workspace}__topo：用于写入关系数据

本文介绍的图查询用法，是针对于写入 ${workspace}__topo的关系数据的查询。支持多跳关系路径分析、实体邻接关系分析、自定义拓扑模式识别等能力。

注意：本文介绍的图查询用法，系可观测 2.0 高阶 PaaS API 的底层查询，适合高度定制化自由查询模式的资深用户。若仅需简单的关联查找、查询信息等能力，推荐使用高阶 PaaS API，接口更友好。

2.2 总览

03 图查询基础概念

在深入使用图查询之前，理解其基础概念至关重要。图查询的核心思想是将数据抽象为图（Graph）结构：实体是节点（Node），关系是边（Edge）。每个节点都有标签（Label）和属性（Properties），标签用于标识节点的类型，属性用于存储节点的详细信息。同样，每条边也有类型（Type）和属性，类型表示关系的类别，属性可以存储关系的额外信息。

3.1 节点和边的描述语法

在图查询中，使用特定的语法来描述节点和边：

节点：使用小括号 ()表示
边：使用中括号 []表示
描述格式：<变量名>:<标签> {属性键值对}

下面是一些基础语法示例：

// 任意节点
()
// 具有特定标签的节点  
(:"apm@apm.service")           // graph-match写法
(:`apm@apm.service`)           // cypher写法
// 具有标签和属性的节点
(:"apm@apm.service" { __entity_type__: 'apm.service' })
// 命名变量的节点
(s:"apm@apm.service" { __entity_id__: '123456' })
// 任意边
[]
// 命名边
[edge]
// 具有类型的边
[e:calls { __type__: "calls" }]

语法差异说明：

graph-match：在 SPL 上下文中，特殊字符需要双引号包裹
Cypher：作为独立语法，标签使用反引号包裹

// gra
// graph-match语法
.topo | graph-match (s:"apm@apm.service" {__entity_id__: '123'})-[e]-(d)
        project s, e, d
// Cypher语法（``apm@apm.service`` 反引号字符串格式，使用两个反引号包裹）
.topo | graph-call cypher(`
    MATCH (s:``apm@apm.service`` {__entity_id__: '35af918180394ff853be6c9b458704ea'})-[e]-(d)
    RETURN s, e, d
`)ph-match语法.topo | graph-match (s:"apm@apm.service" {__entity_id__: '123'})-[e]-(d)        project s, e, d// Cypher语法（``apm@apm.service`` 反引号字符串格式，使用两个反引号包裹）.topo | graph-call cypher(`    MATCH (s:``apm@apm.service`` {__entity_id__: '35af918180394ff853be6c9b458704ea'})-[e]-(d)    RETURN s, e, d`)

3.2 路径语法与方向

图查询路径使用 ASCII 字符描述关系方向：

3.3 返回值结构

在 EntityStore 的体系中，节点的标签格式为 domain@entity_type，例如 apm@apm.service 表示域为 apm、实体类型为 apm.service 的节点。这种标签设计不仅清晰地表示了节点的归属和类型，还支持基于域的快速过滤和查询。节点的属性包括了系统内置的属性（如 __entity_id__、__domain__、__entity_type__）以及用户在写入时自定义的属性（如 servicename、instanceid 等）。边的类型同样可以用字符串表示，比如 calls、runs_on、contains 等，每条边也会携带相应的属性信息。

3.3.1 节点 JSON 格式

{
  "id": "apm@apm.service:347150ad7eaee43d2bd25d113f567569",
  "label": "apm@apm.service", 
  "properties": {
    "__domain__": "apm",
    "__entity_type__": "apm.service",
    "__entity_id__": "347150ad7eaee43d2bd25d113f567569",
    "__label__": "apm@apm.service"
  }
}

3.3.2 边 JSON 格式

{
  "startNodeId": "apm@apm.service:347150ad7eaee43d2bd25d113f567569",
  "endNodeId": "apm@apm.service.host:34f627359470c9d36da593708e9f2db7",
  "type": "contains",
  "properties": {
    "__type__": "contains"
  }
}

图查询的本质是模式匹配：用户描述一个图模式（Pattern），系统在图中查找所有符合该模式的子图。图模式可以用路径表达式来表示，最基础的路径表达式就是 (节点)-[边]->(节点)，这表示从源节点通过一条边到达目标节点。路径表达式可以扩展为更复杂的模式，比如 (A)-[e1]->(B)-[e2]->(C) 表示从 A 经过 B 到达 C 的两跳路径，或者 (A)-[*1..3]->(B) 表示从 A 到 B 的可能的多跳路径。这种表达方式既直观又强大，能够描述从简单的一对一关系到复杂的多层级网络路径。

04 graph-match：直观的路径查询

graph-match 是图查询中最直观、最容易上手的功能。它的设计哲学是让用户能够用接近自然语言的方式描述查询意图，然后系统自动执行查询并返回结果。graph-match 的语法结构相对简单，主要由路径描述和结果投影两部分组成。

graph-match 的核心特点是必须从已知的起始点开始查询。起始点需要同时指定标签和 __entity_id__ 属性，这确保了查询能够快速定位到具体的实体。从技术实现的角度看，这种设计是有意为之：图的遍历通常是一个指数级复杂度的操作，如果允许从任意模式开始查询，可能会导致全图扫描，性能无法保证。而强制指定起始点后，系统可以基于该点进行有向遍历，将搜索空间限制在可控范围内。

路径描述的语法遵循直观的方向性表达。(A)-[e]->(B) 表示从 A 到 B 的有向边，(A)<-[e]-(B) 表示从 B 到 A 的有向边，(A)-[e]-(B) 表示双向边（不限制方向）。用户可以为路径中的每个节点和边命名变量，这些变量可以在后续的 project 语句中使用。路径可以连接多个节点和边，形成多跳路径，比如 (start)-[e1]->(mid)-[e2]->(end)。

project 语句用于指定返回的内容。用户可以直接返回节点或边的 JSON 对象，也可以使用点号语法提取特定的属性，如 "node.__entity_type__"、"edge.__type__ attribution。project 还支持重命名操作，让返回的字段具有更友好的名称。这种灵活的输出方式让 graph-match 既能满足快速探索的需求（返回完整对象），也能满足数据分析的需求（提取特定字段）。

4.1 实际应用案例

4.1.1 全链路路径查询

查找从特定操作开始的完整调用链路：

.topo |
  graph-match (s:"apm@apm.operation" {__entity_id__: '925f76b2a7943e910187fd5961125288'})
              <-[e1]-(v1)-[e2:calls]->(v2)-[e3]->(v3)
  project s, 
          "e1.__type__", 
          "v1.__label__", 
          "e2.__type__", 
          "v2.__label__", 
          "e3.__type__", 
          "v3.__label__", 
          v3

返回结果：

s：起始操作节点
e1.type：第一段关系类型
v1.label：中间节点标签
v2, v3：后续节点信息

4.1.2 邻居节点统计

统计特定服务的邻居分布情况：

.topo |
  graph-match (s:"apm@apm.service" {__entity_id__: '0e73700c768a8e662165a8d4d46cd286'})
              -[e]-(d)   
  project eType="e.__type__", dLabel="d.__label__"
| stats cnt=count(1) by dLabel, eType
| sort cnt desc
| limit 20

4.1.3 条件路径查询

查找满足特定条件的路径终点：

.topo |
  graph-match (s:"apm@apm.service.operation" {__entity_id__: '6f0bb4c892effff81538df574a5cfcd9'})
              <-[e1]-(v1)-[e2:runs_on]->(v2)-[e3]->(v3)
  project s, 
          "e1.__type__", 
          "v1.__label__", 
          "e2.__type__", 
          "v2.__label__", 
          "e3.__type__", 
          destId="v3.__entity_id__", 
          v3 
| where destId='9a3ad23aa0826d643c7b2ab7c6897591'
| project s, v3

4.1.4 Pod 到 Node 的关系链

追踪 Pod 的完整部署链：

.topo |
  graph-match (pod:"k8s@k8s.pod" {__entity_id__: '347150ad7eaee43d2bd25d113f567569'})
              <-[r1:contains]-(node:"k8s@k8s.node")
              <-[r2:contains]-(cluster:"k8s@k8s.cluster")
  project 
    pod,
    node, 
    cluster,
    "r1.__type__",
    "r2.__type__"

4.1.5 graph-match 限制

尽管 graph-match 非常直观易用，但它也有一些限制：

05 graph-call：函数式图操作

graph-call 提供了一套函数式的图查询接口，这些函数封装了常见的图操作模式，让用户能够更高效地执行特定类型的查询。graph-call 的设计理念是提供声明式的函数接口，用户只需指定意图和参数，具体的遍历算法由系统优化执行。

getNeighborNodes 是最常用的 graph-call 函数，它用于获取指定节点的邻居节点。函数的签名是 getNeighborNodes(type, depth, nodeList)，其中 type 参数控制遍历的类型，depth 参数控制遍历的深度，nodeList 参数指定起始节点列表。type 参数的取值包括：sequence（有向序列遍历，保持边的方向性）、sequence_in（只返回指向起始节点的路径）、sequence_out（只返回从起始节点出发的路径）、full（全方向遍历，不考虑边的方向）。这种类型划分让用户能够根据实际需求选择合适的遍历策略。

depth 参数控制遍历的深度，实际使用中建议不要设置过大，一般 3 到 5 层已经足够覆盖大多数场景。过深的遍历不仅会带来性能问题，返回的结果也可能因为关联关系过多而失去实际意义。nodeList 参数接受一个节点描述数组，每个节点描述遵循与 graph-match 相同的语法，需要指定标签和 __entity_id__。getNeighborNodes 会为每个起始节点分别执行遍历，然后合并结果返回。

getNeighborNodes 的返回结果包含四个字段：srcNode（源节点 JSON）、destNode（目标节点 JSON）、relationType（关系类型）、srcPosition（源节点在路径中的位置，-1 表示直接邻居）。srcPosition 字段特别有用，它让用户能够区分直接关系和间接关系，在做统计分析时可以按位置分组，了解不同层级的关系分布。

getDirectRelations 函数用于批量查询节点之间的直接关系。与 getNeighborNodes 不同，getDirectRelations 只返回直接相连的关系，不进行多跳遍历。这个函数特别适合批量检查多个已知节点之间的关系，比如检查一组服务之间是否存在调用关系，或者检查一组资源之间的依赖关系。函数的参数是一个节点列表，返回结果是关系数组，每个关系包含完整的节点和边信息。

5.1 实际应用案例

5.1.1 获取服务的完整邻居关系

-- 获取服务的所有邻居（2跳内）
.topo | graph-call getNeighborNodes(
  'full', 2,
  [(:"apm@apm.service" {__entity_id__: '0e73700c768a8e662165a8d4d46cd286'})]
)
| stats cnt=count(1) by relationType
| sort cnt desc

5.1.2 故障上游影响分析

查找可能影响目标服务的上游服务：

.topo | graph-call getNeighborNodes(
  'sequence_in', 3,
  [(:"apm@apm.service" {__entity_id__: '0e73700c768a8e662165a8d4d46cd286'})]
)
| where relationType in ('calls', 'depends_on')
| extend impact_level = CASE
    WHEN srcPosition = '-1' THEN 'direct'
    WHEN srcPosition = '-2' THEN 'secondary'
    ELSE 'indirect' END
| extend parsed_service_id = json_extract_scalar(srcNode, '$.id')
| project 
    upstream_service = parsed_service_id,
    impact_level,
    relation_type = relationType
| stats cnt=count(1) by impact_level, relation_type

5.1.3 故障下游影响分析

查找受目标服务故障影响的下游服务：

.topo | graph-call getNeighborNodes(
  'sequence_out', 3,
  [(:"apm@apm.service" {__entity_id__: 'failing-service-id'})]
)
| where relationType in ('calls', 'depends_on')
| extend affected_service = json_extract_scalar(destNode, '$.id')
| stats impact_count=count(1) by affected_service
| sort impact_count desc
| limit 20

5.1.4 云资源依赖分析

分析 ECS 实例的网络依赖：

.topo | graph-call getNeighborNodes(
  'sequence_out', 2,
  [(:"acs@acs.ecs.instance" {__entity_id__: 'i-bp1234567890'})]
)
| extend relation_category = CASE
    WHEN relationType in ('belongs_to', 'runs_in') THEN 'infrastructure'
    WHEN relationType in ('depends_on', 'uses') THEN 'dependency'
    WHEN relationType in ('connects_to', 'accesses') THEN 'network'
    ELSE 'other' END
| stats cnt=count(1) by relation_category
| sort cnt desc
| limit 0, 100

5.1.5 批量查询节点间的直接关系

.topo | graph-call getDirectRelations(
  [
    (:"app@app.service" {__entity_id__: '347150ad7eaee43d2bd25d113f567569'}),
    (:"app@app.operation" {__entity_id__: '73ef19770998ff5d4c1bfd042bc00a0f'})
  ]
)

返回的关系示例：

{
  "startNodeId": "app@app.service:347150ad7eaee43d2bd25d113f567569",
  "endNodeId": "app@app.operation:73ef19770998ff5d4c1bfd042bc00a0f", 
  "type": "contains",
  "properties": {"__type__": "contains"}
}

graph-call 的函数式设计带来的优势是查询意图清晰，系统能够针对特定模式进行优化。但这也意味着它只适合预定义的查询模式，对于需要自定义复杂路径模式的场景，还是需要使用 Cypher。在实际使用中，建议优先考虑 graph-call 的预定义函数，只有当预定义函数无法满足需求时，再考虑使用更灵活 Cypher。

06 Cypher：强大的声明式查询语言

Cypher 是图数据库领域的标准查询语言，借鉴了 SQL 的易用性和声明式风格，同时针对图结构进行了专门优化。在 EntityStore 中，Cypher 提供了最强大和灵活的图查询能力，能够处理从简单的单节点查询到复杂的多级跳路径网络的各种场景。

Cypher 的语法遵循三段式结构：MATCH、WHERE、RETURN，这与 SQL 的 SELECT、WHERE、FROM 结构类似，但逻辑更符合图查询的思维模式。MATCH 子句用于描述图模式，WHERE 子句用于添加筛选条件，RETURN 子句用于指定返回的内容。这种结构化的语法让复杂的图查询也变得易于阅读和维护。

MATCH 子句的强大之处在于它支持的图模式描述。用户可以在 MATCH 中指定任意复杂的路径模式，包括多级跳、可选路径、路径变量等。多级跳的语法是 [*min..max]，其中范围是左闭右开的，比如 [*2..3] 表示只查询 2 跳路径。这种语法设计让用户能够灵活地控制遍历深度，在精度和性能之间取得平衡。MATCH 还支持多个路径模式的组合，用户可以同时描述多个路径模式，系统会找到所有满足任一模式的子图。

WHERE 子句支持丰富的筛选条件。用户可以对节点的属性、边的属性进行各种条件判断，包括相等、包含、以某字符串开头或结尾、范围判断等。WHERE 子句还支持逻辑组合（AND、OR、NOT）和复杂的表达式。相比 graph-match，Cypher 的 WHERE 子句更加灵活，不仅可以在查询时进行筛选，还可以对中间节点进行条件限制，这对于复杂路径模式的查询特别有用。

RETURN 子句提供了灵活的输出控制。用户可以返回节点对象、边对象、路径对象，也可以提取特定的属性字段。RETURN 还支持聚合函数（如 count、sum、avg 等）和分组操作，这让 Cypher 不仅能够进行图遍历，还能够进行图分析。结合 SPL 的强大处理能力，Cypher + SPL 的组合能够完成从数据查询到分析计算的全流程。

6.1 基础查询示例

6.1.1 单节点查询

-- 查询特定类型的所有节点
.topo | graph-call cypher(`
    MATCH (n {__entity_type__:"apm.service"})
    WHERE n.__domain__ STARTS WITH 'a' AND n.__entity_type__ = "apm.service"
    RETURN n
`)

相比 graph-match 的优势：

支持 WHERE 子句进行复杂筛选
MATCH 可以只包含节点，无需指定关系
支持更多的属性查询（__entity_type__、__domain__等）

6.1.2 关系查询

-- 查询服务间调用关系
.topo | graph-call cypher(`
    MATCH (src:``apm@apm.service``)-[e:calls]->(dest:``apm@apm.service``)
    WHERE src.cluster = 'production' AND dest.cluster = 'production'
    RETURN src.service, dest.service, e.__type__
`)

6.2 多级跳查询

6.2.1 基础多级跳语法

-- 查找2-3跳的调用链路
.topo | graph-call cypher(`
    MATCH (src {__entity_type__:"acs.service"})-[e:calls*2..4]->(dest)
    WHERE dest.__domain__ = 'acs'
    RETURN src, dest, dest.__entity_type__
`)

重要说明：

多级跳规则是左闭右开：*2..4表示查询 2 跳和 3 跳
*1..3表示 1 跳或 2 跳，不包括 3 跳

6.2.2 连通性分析

-- 查找服务间的可达路径
.topo | graph-call cypher(`
    MATCH (startNode:``apm@apm.service`` {service: 'gateway'})
          -[path:calls*1..4]->
          (endNode:``apm@apm.service`` {service: 'database'})
    RETURN startNode.service, length(path) as hop_count, endNode.service
`)

6.2.3 影响链分析

-- 分析故障传播路径
.topo | graph-call cypher(`
    MATCH (failed:``apm@apm.test_service`` {status: 'error'})
          -[impact:depends_on*1..3]->
          (affected)
    WHERE affected.__entity_type__ = 'apm.service'
    RETURN failed.service, 
           length(impact) as impact_distance,
           affected.service
    ORDER BY impact_distance ASC
`)

6.2.4 节点聚合统计

-- 统计不同域的服务数量
.topo | graph-call cypher(`
    MATCH (src {__entity_type__:"apm.service"})-[e:calls*2..3]->(dest)
    WHERE dest.__domain__ = 'apm'
    RETURN src, count(src) as connection_count
`)

适用场景：

连通分量分析：识别图中的连通子图
中心度计算：找出网络中的关键节点
集群检测：发现紧密连接的节点群组

6.2.5 路径模式查找

-- 查找特定的拓扑模式
.topo | graph-call cypher(`
    MATCH (src:``acs@acs.vpc.vswitch``)-[e1]->(n1)<-[e2]-(n2)-[e3]->(n3)
    WHERE NOT (src = n2 AND e1.__type__ = e2.__type__) 
        AND n1.__entity_type__ <> n3.__entity_type__ 
        AND NOT (src)<-[e1:``calls``]-(n1)
    RETURN src, e1.__type__, n1, e2.__type__, n2, e3.__type__, n3
`)

适用场景：

安全审计：发现异常的网络连接模式
合规检查：验证网络架构的合规性
模式检测：识别特定的系统拓扑结构

Cypher 的一个重要特性是支持基于实体自定义属性的查询。在 graph-match 中，中间节点只能通过标签进行过滤，但在 Cypher 中，用户可以基于实体的任意自定义属性进行查询和筛选。这个特性让 Cypher 能够处理更加细粒度的查询需求，比如查找所有 CPU 使用率大于 80% 的实例，或者查找所有属于某个特定用户的资源。

6.3 自定义属性查询示例

基于实体自定义属性的查询是完整版 Cypher 的核心亮点。在标准查询中，虽然可以通过 Usearch 获取实体的详细信息，但在图遍历过程中使用实体属性进行筛选还是有限制的。完整版 Cypher 实现了真正的属性级查询，用户可以在 MATCH 或 WHERE 子句中直接使用实体的自定义属性，系统会自动从 EntityStore 中获取实体的详细信息，并基于这些信息进行过滤。这种设计让图查询不再只是基于拓扑结构的遍历，还能够基于实体的实际属性进行智能筛选，大大提升了查询的精确度。

多级路径输出是另一个重要特性。在传统的图查询中，多级跳查询通常只返回起点和终点，中间的路径信息可能会丢失。但在故障排查和影响分析场景中，了解完整的路径往往比只知道起点和终点更有价值。完整版 Cypher 支持返回路径对象，路径对象包含了路径中所有节点和边的信息，用户可以通过路径对象了解数据流转的完整链路。这个特性特别适用于分析故障传播路径、追踪数据流、理解系统架构等场景。

6.3.1 基于实体自定义属性查询

-- 使用实体的自定义属性进行查询 (仅为示例，实际属性kv以真实场景为准)
.topo | graph-call cypher(`
    MATCH (n:``acs@acs.alb.listener`` {listener_id: 'lsn-rxp57*****'})-[e]->(d)
    WHERE d.vSwitchId CONTAINS 'vsw-bp1gvyids******' 
        AND d.user_id IN ['1654*******', '2'] 
        AND d.dns_name ENDS WITH '.com'
    RETURN n, e, d
`)

6.3.2 复杂的属性条件查询

-- 复杂的属性条件查询 (仅为示例，实际属性kv以真实场景为准)
.topo | graph-call cypher(`
    MATCH (instance:``acs@acs.ecs.instance``)
    WHERE instance.instance_type STARTS WITH 'ecs.c6'
        AND instance.cpu_cores >= 4
        AND instance.memory_gb >= 8
        AND instance.status = 'Running'
    RETURN 
        instance.instance_id,
        instance.instance_type,
        instance.cpu_cores,
        instance.memory_gb,
        instance.availability_zone
    ORDER BY instance.cpu_cores DESC, instance.memory_gb DESC
`)

6.4 多级路径输出

6.4.1 返回完整路径信息

-- 返回多级跳的完整路径信息
.topo | graph-call cypher(`
    MATCH (n:``acs@acs.alb.listener``)-[e:``calls``*2..3]-()
    RETURN e
`)

路径结果格式：

返回路径中所有边的数组
每个边包含完整的起止节点和属性信息
支持路径长度和路径权重计算

6.5 细粒度链路控制的连通性查找

6.5.1 跨网络层级的连接分析

-- 查找ECS实例到负载均衡器的连接路径
.topo | graph-call cypher(`
    MATCH (start_node:``acs@acs.ecs.instance``)
          -[e*2..3]-
          (mid_node {listener_name: 'entity-test-listener-zuozhi'})
          -[e2*1..2]-
          (end_node:``acs@acs.alb.loadbalancer``)
    WHERE start_node.__entity_id__ <> mid_node.__entity_id__ 
        AND start_node.__entity_type__ <> mid_node.__entity_type__
    RETURN 
        start_node.instance_name, 
        e, 
        mid_node.__entity_type__, 
        e2, 
        end_node.instance_name
`)

6.5.2 服务网格连接分析

-- 分析微服务网格中的流量路径
.topo | graph-call cypher(`
    MATCH (client:``apm@apm.service``)
          -[request:calls]->
          (gateway:``apm@apm.gateway``)
          -[route:routes_to]->
          (service:``apm@apm.service``)
          -[backend:calls]->
          (database:``middleware@database``)
    WHERE client.environment = 'production'
        AND request.protocol = 'HTTP'
        AND route.load_balancer_type = 'round_robin'
    RETURN 
        client.service,
        gateway.gateway_name,
        service.service,
        database.database_name,
        request.request_count,
        backend.connection_pool_size
`)

6.5.3 级联故障分析

-- 分析服务故障的级联影响
.topo | graph-call cypher(`
    MATCH (failed_service:``apm@apm.service`` {service: 'load-generator'})
    MATCH (failed_service)-[cascade_path*1..4]->(affected_service:``apm@apm.service``)
    RETURN 
        failed_service.service as root_cause,
        length(cascade_path) as impact_depth,
        affected_service.service as affected_service,
        cascade_path as dependency_chain
    ORDER BY impact_depth ASC
`)

07 典型应用场景

图查询在实际运维和分析场景中的应用非常广泛，以下列举几个典型的应用模式，帮助用户更好地理解如何将图查询能力应用到实际工作中。

7.1 分析服务调用链

-- 分析特定服务的调用模式
.topo |
  graph-match (s:"apm@apm.service" {__entity_id__: 'abcdefg123123'})
              -[e:calls]-(d:"apm@apm.service")
  project 
    source_service="s.service",
    target_service="d.service", 
    call_type="e.__type__"
| stats call_count=count(1) by source_service, target_service
| sort call_count desc

7.2 权限链追踪

在复杂的系统中，理解用户的权限是如何传递到资源的，对于安全审计和合规检查至关重要：

-- 追踪用户到资源的访问路径
.topo |
  graph-match (user:"identity@user" {__entity_id__: 'user-123'})
              -[auth:authenticated_to]->(app:"apm@apm.service")
              -[access:accesses]->(resource:"acs@acs.rds.instance")
  project 
    user_id="user.user_id",
    app_name="app.service",
    resource_id="resource.instance_id",
    auth_method="auth.auth_method",
    access_level="access.permission_level"

7.3 数据完整性检查

7.3.1 检查数据完整性

.topo | graph-call cypher(`
    MATCH (n)-[e]->(m)
    RETURN 
        count(DISTINCT n) as unique_nodes,
        count(DISTINCT e) as unique_edges,
        count(DISTINCT e.__type__) as edge_types
`)

7.3.2 识别悬挂关系

-- 查找指向不存在实体的关系
.let topoData = .topo | graph-call cypher(`
        MATCH ()-[e]->()
        RETURN e
    `)
    | extend startNodeId = json_extract_scalar(e, '$.startNodeId'), endNodeId = json_extract_scalar(e, '$.endNodeId'), relationType = json_extract_scalar(e, '$.type')
    | project startNodeId, endNodeId, relationType;
--$topoData
.let entityData = .entity with(domain='*', type='*') 
| project __entity_id__, __entity_type__, __domain__
| extend matchedId = concat(__domain__, '@', __entity_type__, ':', __entity_id__)
| join -kind='left' $topoData on matchedId = $topoData.endNodeId
| project matchedId, startNodeId, endNodeId, relationType
| extend status = COALESCE(startNodeId, '悬挂')
| where status = '悬挂';
$entityData

08 数据完整性与查询模式选择

在使用图查询时，数据完整性是一个需要特别关注的问题。EntityStore 的图查询能力依赖于三方面的数据：UModel（数据模型定义）、Entity（实体数据）、Topo（拓扑关系数据）。这三方面的数据完整性直接影响了查询的能力和结果。

8.1 数据缺失场景分析

8.2 pure-topo 模式

需要注意的是，完整版 Cypher 依赖于 UModel、Entity 和 Topo 三方面的数据都要完备。如果 Entity 数据不完整，虽然仍然可以进行拓扑查询，但无法使用自定义属性进行筛选。为了解决这个问题，系统提供了 pure-topo 模式：

-- 标准模式（需要完整数据）
.topo | graph-call cypher(`
    MATCH (n:``acs@acs.alb.listener`` {ListenerId: 'lsn-123'})-[e]->(d)
    WHERE d.vSwitchId CONTAINS 'vsw-456'
    RETURN n, e, d
`)
-- pure-topo模式（仅依赖关系数据）
.topo | graph-call cypher(`
    MATCH (n:``acs@acs.alb.listener``)-[e]->(d)
    RETURN n, e, d
`, 'pure-topo')

pure-topo 模式特点：

优势：不依赖 Entity 数据，查询速度更快
限制：无法使用实体的自定义属性进行筛选
适用：拓扑结构分析、关系验证等场景

8.3 查询模式选择策略

当三方面数据都完整时，用户可以使用完整版 Cypher 的所有功能，包括基于自定义属性的查询、多级路径输出等。当 Entity 数据不完整但 Topo 数据完整时，可以使用 pure-topo 模式进行查询，这种模式下查询速度会更快，但只能基于拓扑结构进行查询，无法使用实体属性进行筛选。当 Topo 数据不完整时，虽然 Entity 数据完整，也无法进行图查询，因为图查询的核心是关系，没有关系数据就无法构成图。

在实际使用中，用户应该根据数据的完整性情况选择合适的查询方式。如果数据完整性足够，优先使用完整版 Cypher，享受属性级查询的便利。如果性能是首要考虑，且只需要拓扑结构信息，可以使用 pure-topo 模式。如果需要进行数据完整性检查，可以先使用简单的查询测试数据的完整性，然后再执行复杂的查询。

09 性能优化与最佳实践

图查询虽然强大，但在大数据量的情况下，性能也可能成为瓶颈。合理的使用方法和优化策略能够显著提升查询性能，确保系统在高负载下也能稳定响应。

9.1 查询结构优化

9.1.1 合理使用索引

-- ❌ 优化前：全表扫描
.topo | graph-call cypher(`
    MATCH (n) WHERE n.service = 'web-app'
    RETURN n
`)
-- ✅ 优化后：使用标签索引
.topo | graph-call cypher(`
    MATCH (n:``apm@apm.service`` {service: 'web-app'})
    RETURN n
`)

9.1.2 早期条件过滤

-- ❌ 优化前：后期过滤
.topo | graph-call cypher(`
    MATCH (start)-[*1..5]->(endNode)
    WHERE start.environment = 'production' AND endNode.status = 'active'
    RETURN start, endNode
`)
-- ✅ 优化后：早期过滤
.topo | graph-call cypher(`
    MATCH (start {environment: 'production'})-[*1..5]->(endNode {status: 'active'})
    RETURN start, endNode
`)

9.2 查询范围控制

查询范围的精确控制是最重要的优化策略：

时间范围优化：合理利用时间字段进行范围限制
限制遍历深度：深度超过 5 层会显著影响性能
精确起始点：使用具体的 entity_id 而非模糊匹配
合理选择遍历类型：根据实际需求选择 sequence 或 full

9.3 结果集控制

9.3.1 分页和限制

-- 使用LIMIT控制结果数量
.topo | graph-call cypher(`
    MATCH (service:``apm@apm.service``)-[calls:calls]->(target)
    WHERE calls.request_count > 1000
    RETURN service.service, target.service, calls.request_count
    ORDER BY calls.request_count DESC
    LIMIT 50
`)

9.3.2 结果采样

-- 对大结果集进行采样
.topo | graph-call cypher(`
    MATCH (n:``apm@apm.service``)
    RETURN n.service
    LIMIT 100
`)
| extend seed = random()
| where seed < 0.1

9.4 多级跳优化

9.4.1 控制跳跃深度

-- 避免过深的遍历
.topo | graph-call cypher(`
    MATCH (start)-[path*1..3]->(endNode)
    WHERE length(path) <= 2
    RETURN path
`)

9.4.2 使用方向性优化

-- 利用关系方向减少搜索空间
.topo | graph-call cypher(`
    MATCH (start)-[calls:calls*1..3]->(endNode)  -- 明确方向
    WHERE start.__entity_type__ = 'apm.service'
    RETURN start, endNode
`)

9.5 最佳实践建议

使用 SPL 过滤：在图查询后及时过滤不需要的结果
分批处理：对于大型图查询，考虑分批处理
结果缓存：对于频繁查询的路径，考虑结果缓存
查询拆分：将复杂查询拆分为多个简单查询，然后使用 SPL 合并

10 常见问题

10.1 边类型恰好与 Cypher 关键字重合

.topo | graph-call cypher(`
    MATCH (s)-[e:``contains``]->(d)
    WHERE s.__domain__ CONTAINS "apm"
    RETURN e
`)

contains 是 cypher 关键字，同时也是边类型，此时作为 Cypher 语法需要在边类型上面加入 back-tick 标识进行包裹，又因为在 SPL 上下文中，所以作为 SPL 语法需要变为双 back-tick 标识进行包裹。

10.2 多级跳语法说明

-- 查找2-3跳的调用链路
.topo | graph-call cypher(`
    MATCH (src {__entity_type__:"acs.service"})-[e:calls*2..4]->(dest)
    WHERE dest.__domain__ = 'acs'
    RETURN src, dest, dest.__entity_type__
`)