LogicForm V2 简介

开发状态

LogicForm V2 仍在开发中，暂未上线。本文档用于提前公开接口方向，当前契约仍可能在正式发布前调整，请勿直接用于生产环境。

LogicForm V2 是 Data Agent 的新一代语义查询协议。调用方使用稳定、可读的 JSON 描述“查询什么”，由 SemanticDB 根据 Schema、数据权限和数据源映射执行查询。调用方不需要拼接数据库 SQL，也不需要为不同数据库维护多套业务逻辑。

为什么需要 V2

LogicForm V2 的核心目标是让语义查询更准确、更透明，也更容易扩展。

更统一、严谨的语义

Schema、Property、查询条件、分组和指标都使用统一的公开标识与表达式结构。
preds 与 groupby 共享同一套 PredItem 表达式，不再为相同计算维护多套语法。
多输入计算统一使用 components，Operator 配置统一放在 args。
日期、分页、跨 Schema 查询、对象关系和周期指标都有明确且可校验的契约。
无法解析或无法证明等价的请求会明确失败，不会静默忽略条件或返回语义不完整的数据。

减少内部推断，判断流程可追踪

数据源、物理表、字段映射、聚合方式和关系路径都由显式配置决定。
跨 Schema 指标仍位于同一个 preds 数组，通过 PredItem 的 schema 和 LogicForm 的 propertyResolve 显式声明字段归属与实体粒度对齐。
执行结果提供规范化后的 LogicForm、实际 SQL、参数、数据血缘和动态结果 Schema。
onProgress 可以观察校验、规范化、规划、SQL 生成、执行和结果处理等阶段。
错误包含稳定的错误码和上下文，调用方可以记录、展示或自动处理。

这里的“可追踪”是公开诊断能力，不要求使用者理解内部实现。通常只需保存返回结果中的 normedLogicform、sqls 和 lineage，即可还原一次查询采用的口径和数据来源。

更强的插件化能力

LogicForm V2 的核心能力都可以按明确边界扩展：

数据库 Provider：接入新的数据库协议和 SQL 方言。
Schema Mapping：把同一个逻辑 Schema 映射到不同数据源、明细表或预聚合指标表。
Semantic Type：注册新的业务语义类型、校验规则、查询规范化和结果处理方式。
Operator：注册新的标量、聚合、窗口、逻辑或复合计算。
Plugin：把 Schema 元数据、兼容转换、实体身份规则和 Operator 打包为一个能力。
Query Cache：由调用方注入缓存实现，并按物理数据源的新鲜度策略失效。

所有 Registry 和 Plugin 都由调用方创建并持有，不依赖全局单例。不同租户或应用实例可以使用不同能力集合，彼此不会污染。

主要能力

LogicForm V2 支持：

字段选择、过滤、分组、聚合、排序和分页；
嵌套表达式、条件聚合、窗口函数和多输入算术；
相对时间、时间分桶、周期平移、同比/环比、期初期末和累计；
对象关系路径、多级关系查询和对象结果填充；
子查询、派生查询和跨 Schema 指标；执行器可在内部拆分并合并多个 Provider 查询；
行、列和 Schema 级权限；
多数据库连接、多物理 Mapping、缓存和物理数据血缘；
自定义语义类型、Operator、插件和数据库 Provider。

最小示例

const logicform = {
  version: '2.0',
  schema: 'sales',
  query: {
    日期: { year: 2026, month: 8 },
  },
  groupby: [{ pred: '门店', name: '门店' }],
  preds: [{ operator: '$sum', pred: '销售额', name: '销售额' }],
  sort: { 销售额: -1 },
  limit: 10,
};

这个请求完整表达了查询版本、逻辑数据集、时间范围、分组维度、指标、排序和返回行数。数据库连接、物理表名和物理列名不写入 LogicForm，而由执行参数中的 Schema Mapping 决定。

文档范围

本章节是面向 LogicForm 使用者和扩展开发者的公开接口规范，不介绍内部模块实现。建议按以下顺序阅读：

命名约定

产品名称写作 LogicForm；JSON 字段名仍使用小写 logicform 语境中的既有形式。
Schema 和 Property 使用 id，不使用旧版 _id、_sid 或 sid。
schema.id 是 LogicForm 的逻辑数据集标识。
property.name 是推荐的业务字段引用；property.id 也可作为输入引用，并会被规范化。
Operator 名称以 $ 开头，例如 $sum、$dateBucket。
结果行中的 _id 是执行器生成的行身份，不是 Schema/Property 元数据字段。

#LogicForm V2 简介

#为什么需要 V2

#更统一、严谨的语义

#减少内部推断，判断流程可追踪

#更强的插件化能力

#主要能力

#最小示例

#文档范围

#命名约定