在 BigQuery 语义图上编写正确查询ADK bigquery-graph Skill 的 GRAPH_EXPAND 与 AGG() 查询规范【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-pythonBigQuery 语义图Semantic Graph是建立在属性图Property Graph之上、附带预定义业务度量Measure与元数据描述、同义词的分析型图模型。在 ADK 的bigquery-graphSkill 中Agent 面对语义图时必须遵循一套与普通表查询截然不同的 SQL 规范通过GRAPH_EXPAND表值函数访问扁平化视图、用AGG()包裹所有度量列、并优先使用预定义度量而非手写标准 SQL 聚合。本文以 semantic_queries.md 为骨架结合其同目录下的 DDL 参考、特性对等说明与最佳实践文档完整讲解这套查询规则及其背后的底层原理让你或你的 Agent能在 BigQuery 语义图上写出正确、高效且不触发NOT_FOUND/Returning expressions of type MEASURE is not allowed等典型错误的查询。一、语义图是什么不是一张表而是一张图的扁平化视图在开始写 SQL 之前必须先厘清语义图的对象模型。从仓库中 feature_parity.md 的定义可以确认语义图在 BigQuery 中并不是一种独立的资源类型它在物理上就是一张标准的属性图Property Graph只是额外携带了语义元数据。与传统属性图的差异体现在三个层面特性属性图Property Graph语义图Semantic Graph核心要素节点Nodes与边Edges节点Nodes与边Edges属性标准属性即维度 Dimension维度Dimension与度量Measure元数据名称、标签Labels描述、同义词、is_measure标记查询语言GQL图查询语言GQL或通过GRAPH_EXPAND使用 SQL也就是说语义图在 DDL 层面用CREATE PROPERTY GRAPH定义可能还以CREATE TABLE的形式呈现其扁平 schema但这只是 schema 的呈现方式而在查询层面它既可以被原生 GQL 查询也可以通过GRAPH_EXPAND表值函数以一张大表One-Big-Table, OBT的形式被标准 SQL 查询。GRAPH_EXPAND会在查询时把属性图拍平成一个虚拟的扁平关系视图每个属性列都被冠以节点/边别名_属性名的前缀例如Customer_name、Customer_total_orders并对分析型问题与 BI 指标做了专门优化。这正是 semantic_queries.md 开篇所述语义图是图的虚拟扁平视图针对数据分析和问题回答而优化的含义。需要特别留意的是GRAPH_EXPAND对图的拓扑有严格限制详见 feature_parity.md它要求图必须构成一棵有效的树或若干树形层级不支持森林/多根、有向环、自环以及菱形汇聚路径同一祖先节点经多条不同有向路径到达同一后代节点。如果图存在环或汇聚路径正确做法是简化 schema或改用原生 GQL 模式匹配参考 SKILL.md 中的 GQL 指南而不是继续试图用GRAPH_EXPAND强行查询。二、规则一永远通过GRAPH_EXPAND查询绝不把它当普通表semantic_queries.md 的第一条规则是语义图查询的最高优先级红线总是使用GRAPH_EXPAND表值函数TVF来查询语义图其参数是完整的图名字符串格式为project_id.dataset_id.property_graph_id。CRITICAL RULE语义图不是普通表即使它的 schema 可能是用CREATE TABLE呈现的。绝不能把它当作普通表直接查询例如FROM my_project.my_dataset.my_graph。CRITICAL FALLBACK RULE如果某个使用GRAPH_EXPAND的查询失败例如语法错误或系统限制不要退而求其次把它当作标准表查询——这样做会直接触发严重的NOT_FOUND错误。标准查询模板如下SELECT ... FROM GRAPH_EXPAND(project_id.dataset_id.property_graph_id) WHERE ...这条规则源于GRAPH_EXPAND的运行时语义扁平化视图只在 TVF 调用时动态生成图本身并没有一个物化的普通表可供FROM直接引用。因此任何绕过GRAPH_EXPAND的降级尝试都无法命中实际对象最终以NOT_FOUND告终。在编写 Agent 指令时这条禁止回退的约束尤其重要——LLM 在第一次尝试失败后倾向于换一种写法而这里恰恰必须坚持原路修正。三、规则二度量列必须用AGG()包裹语义图区别于普通表的核心标志是 schema 中存在标记为is_measureTRUE的度量列。例如Customer_total_orders INT64 OPTIONS(is_measureTRUE)对这类列semantic_queries.md 规定必须使用AGG()函数查询度量列语法为AGG(measure_column_name)。不要把SUM、AVG等其他聚合函数直接作用于度量列。完整示例含给定 schema 与查询-- 给定 Schema -- CREATE TABLE my_project.my_dataset.my_graph ( -- Customer_name STRING, -- Customer_total_orders INT64 OPTIONS(is_measureTRUE), -- Product_name STRING -- ); -- 查询度量 SELECT Customer_name, AGG(Customer_total_orders) AS total_orders FROM GRAPH_EXPAND(my_project.my_dataset.my_graph) GROUP BY Customer_name;这条规则的底层原因可以从 feature_parity.md 的查询限制一节找到源码级解释度量在 DDL 中通过MEASURE关键字定义后底层会启用**粒度锁定grain-locking**机制目的是在连接JOIN过程中防止重复计数overcounting。这一机制带来的直接后果是不能在标准SELECT列表中直接选择度量列必须用特殊的AGG()函数包裹。否则报错Returning expressions of type MEASURE is not allowed.不能对包含度量的图直接执行SELECT *会隐式尝试选择未包裹AGG()的度量列。解决方法是显式列出非度量列或用SELECT * EXCEPT (measure_col1, ...)排除它们。度量列不能用于查询优化器无法自动去关联de-correlate的复杂相关子查询如EXISTS子句解决方法是改写为显式JOIN或先把聚合放进公共表表达式CTE。度量列不能在原生 GQL 查询如GRAPH_TABLE中被引用或投影——原生 GQL 只严格作用于标准属性图的维度。要查度量必须用标准 SQL GRAPH_EXPANDAGG()。四、规则三优先使用预定义度量而不是手写标准 SQL 聚合第三条规则是查询风格上的强制性偏好必须优先使用 schema 中预定义的度量is_measureTRUE的列而不是手写标准 SQL 聚合如COUNT(DISTINCT ...)、SUM等只要存在可用的相关度量。其语境是语义图把业务逻辑内建在度量中以保证准确性并防止过度计数overcounting而手写标准 SQL 聚合会绕过这套业务逻辑。semantic_queries.md 给出的对比场景用户询问实体总数schema 同时提供了Entity_id列与度量列Entity_count INT64 OPTIONS(is_measureTRUE)错误标准 SQLSELECT COUNT(DISTINCT Entity_id) AS total_entities ...正确度量SELECT AGG(Entity_count) AS total_entities ...这一偏好与规则二同源度量列的AGG()语义由 DDL 中MEASURE(SUM(amount)) AS total_order_amount这类定义决定粒度锁定保证其在任何查询上下文中都返回业务上正确的数值。手写COUNT(DISTINCT ...)等表达式则完全取决于 Agent 对去重口径的自行理解在复杂的多层 JOIN 场景下极易产生重复计数或口径漂移。五、理解度量的定义与维度要求DDL 侧要正确使用度量还需要理解度量在 DDL 侧是如何定义的。参考 ddl_reference.md 的语义扩展一节PROPERTIES ( amount, -- 维度属性声明度量所必需 MEASURE(SUM(amount)) AS total_order_amount -- 聚合该维度属性 )关键语法与约束语法MEASURE(AGG_FUNC(column)) AS measure_name。支持SUM、COUNT、AVG、MIN、MAX、COUNT(DISTINCT ...)等标准聚合函数。必须显式命名度量必须使用别名不允许匿名度量。维度属性强制要求文档中以 IMPORTANT 标注任何在MEASURE聚合表达式中被引用的源列必须同时在同一条PROPERTIES(...)块中被显式声明为普通维度属性。如果聚合了一个未作为维度暴露的列查询将直接失败。上面示例中amount同时出现在维度列表与MEASURE(SUM(amount))中正是这个原因。此外属性还可以通过OPTIONS附带业务元数据提升自然语言接口的可发现性property_name OPTIONS ( [ description description_string ] [, synonyms [synonym_1, synonym_2, ...] ] )description用于描述属性语义synonyms提供一组别名。语义图的完整 DDL 示例含节点级DEFAULT LABEL OPTIONS(...)、列级描述/同义词与预定义度量同样见 ddl_reference.md例如CREATE OR REPLACE PROPERTY GRAPH my-project.my_dataset.ecomm_semantic_graph NODE TABLES ( my-project.my_dataset.users AS User KEY(user_id) DEFAULT LABEL PROPERTIES ( user_id OPTIONS(descriptionUnique system identifier for each user), name, age ), my-project.my_dataset.orders AS Order KEY(order_id) DEFAULT LABEL PROPERTIES ( order_id, order_date, amount, -- 维度属性声明度量所必需 MEASURE(SUM(amount)) AS total_order_amount OPTIONS( descriptionTotal revenue aggregated from user orders, synonyms[revenue, sales_turnover] ), MEASURE(COUNT(*)) AS order_count OPTIONS( descriptionCount of orders placed by customers ) ) ) EDGE TABLES ( my-project.my_dataset.orders AS PLACED KEY(order_id) SOURCE KEY(user_id) REFERENCES User (user_id) DESTINATION KEY(order_id) REFERENCES Order (order_id) DEFAULT LABEL NO PROPERTIES );配合 graph_schema_ddl_advisor.md 描述的 Schema 顾问协议在定义阶段应依次完成识别用户需求属性图 vs 语义图、是否经GRAPH_EXPAND查询→ 构建/修正 DDL 语法 → 应用最佳实践限定属性范围、强制安全别名、检查扁平视图列名冲突→ 集成语义特性度量、描述、同义词→ 校验图拓扑限制是否构成合法树。六、规避GRAPH_EXPAND的坑Schema 侧最佳实践由于GRAPH_EXPAND的扁平化输出是列名拼接的结果查询能否成功与 Schema 建模质量高度相关。best_practices.md 为语义图查询的正确性提供了四条关键前提限定属性范围默认或使用PROPERTIES ALL COLUMNS会把源表所有列都挂到图上导致图查询产生冗余列扫描严重拖慢性能。应使用PROPERTIES (col1, col2, ...)只暴露真正需要的属性。定义主键/外键约束BigQuery 运行时并不强制 PK/FK但会用它们优化执行计划消除不必要的表扫描、剪枝 JOIN 路径。应在源表 DDL 中为节点表定义 PK、为边表定义 FK并在CREATE PROPERTY GRAPH中引用若唯一性或引用完整性被破坏图查询结果可能出错。避免扁平化列名冲突GRAPH_EXPAND用别名_属性名拼接列名若节点N的属性a_b与节点N_a的属性b都生成N_a_b查询会报通用内部错误Error encountered during execution. Retrying may solve the problem.。应精心设计别名与属性名。始终使用安全别名AS alias省略别名时 BigQuery 默认用完整表路径如project.dataset.table作为别名扁平化列名会包含点号与连字符违反标准 SQL 输出 schema 规则SELECT *会报Invalid field name。务必使用纯字母数字的简单别名例如NODE TABLES ( \my-project.my_dataset.user_profiles AS User KEY(id) ... )。若 schema 别名确实需要特殊字符如连字符或空格DDL 与查询两侧都须正确加引号DDL 中用反引号如AS \My-Node查询时必须写 SELECTMy-Node_property FROM GRAPH_EXPAND(...) 漏写反引号会让引擎把连字符当作减法运算符而报语法错误。七、在 ADK 中启用bigquery-graph Skill 与工具链这套语义图查询规范并不是孤立文档而是 ADK 内置 Skill 体系的一部分。SKILL.md 定义了名为bigquery-graph的 Skilllicense: Apache-2.0metadata 标注作者google-adk、版本1.0它面向属性图的 GQL 或 SQL/PGQ 查询路径查找、多跳遍历、拓扑连接、最短路径、节点可达性、边连通性以及语义图查询并强制只使用 BigQuery GoogleSQL GQL 标准实现 ISO GQL 标准严禁生成 Cypher 查询。在 Skill 的 Reference Directory 中semantic_queries.md 被列为语义图查询规范与 Schema 最佳实践、DDL 参考、特性对等说明、DDL 顾问文档共同构成 Agent 生成图查询时的参考知识库——本文所述的GRAPH_EXPANDAGG()规范正是其中的语义图查询子集。从 bigquery_skill.py 的源码可以确认 Skill 的装配方式get_bigquery_skill()通过load_skill_from_dir从skills/bigquery-ai-ml目录加载预打包 Skill遵循 agentskills.io 规范并可与BigQueryToolset、SkillToolset组合挂载到LlmAgent上from google.adk.tools.bigquery import BigQueryToolset from google.adk.tools.bigquery.bigquery_skill import get_bigquery_skill from google.adk.tools.skill_toolset import SkillToolset bq_skill get_bigquery_skill() toolset SkillToolset(skills[bq_skill]) bigquery_toolset BigQueryToolset(...) agent LlmAgent(tools[bigquery_toolset, toolset])注意google.adk.tools.bigquery.bigquery_toolset已在 bigquery_toolset.py 中标记为废弃实际实现迁移到了google.adk.integrations.bigquery.bigquery_toolset。需要说明的是bigquery-graphSkill 目录在源码中目前作为 Agent 指令知识库存在SKILL.md 与其 references 子目录在工具装配层面通过load_skill_from_dir加载使用当其作为参考文档被注入 Agent 上下文后Agent 便会在生成语义图 SQL 时遵循本规范。八、查询前自查清单结合 semantic_queries.md 与同目录参考文档生成或审查语义图查询前建议逐条核对入口查询是否经由FROM GRAPH_EXPAND(project_id.dataset_id.property_graph_id)绝无直接FROM图名的情况。回退若GRAPH_EXPAND失败是否仍坚持修正原查询而不是降级为普通表查询那将导致NOT_FOUND度量列schema 中所有is_measureTRUE的列是否都被AGG()包裹是否避免了SELECT *直接扫出度量列聚合偏好schema 已有对应度量时是否优先AGG(measure)而非手写COUNT(DISTINCT ...)/SUM拓扑前提图是否满足GRAPH_EXPAND的树形结构要求无环、无多根、无汇聚路径、无自环不满足时是否改用原生 GQL见 SKILL.mdSchema 健康度扁平化列名是否无冲突、别名是否为纯字母数字否则查询须加反引号度量引用的列是否同时声明为维度属性遵循这套规范Agent 与开发者就能在 BigQuery 语义图上稳定产出业务口径正确、不触发引擎报错的分析查询——这正是 ADKbigquery-graphSkill 期望 Agent 达到的语义查询能力。【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考