数据管道

加工读取数据集，不重复查询源系统。对象同步只写变化。平台按触发条件执行同步和加工。健康检查显示数据更新状态。

源系统的一张表只同步一次，存成数据集。业务数字在加工里算，对象只放业务粒度。应用和智能体读对象，不读源系统。

六段，各在哪里看

这一节让你找到管道的每一段，并知道去哪里看它的状态。

段	做什么	谁定义	在哪里看
数据源	客户原有的系统，只读	客户	—
接入	数据流（发布端推变化）或 TableImport（平台读）	开发者	/semantic/<组织> 的 Data Connection 页
数据集	一次导入或加工的产出，按事务提交	平台	Data Connection 页里的数据集页
加工	从数据集算出新的数据集	开发者，定义是 JSON	aidc semantic transforms show
对象	数据流或数据集映射到 Object Type 的属性	Object Type 定义里的 datasources	/semantic/<组织> 的本体页
使用	应用、智能体、SQL、订阅、自动化	应用与自动化的作者	应用页，自动化的运行记录

读数据的规则

这一节让你按同一个顺序取数据。每一步都读上一步的产出，不回到源系统。

1. 先找已经同步的数据集：aidc semantic datasets --search <表名或中文名>。找不到，由 developer 建 TableImport（数据接入）。不直接查源系统。
2. 业务数字（联表、聚合、口径）写成 加工，产出业务粒度的数据集。不写进导入的 SQL，不写进 Action 或定时脚本，也不在应用里拉明细现算。
3. 对象只建业务粒度：一个真实的实体一个 Object Type，由数据集供数（接到 Object Type）。原始表不一对一建成对象。同一个实体不建第二个 Object Type。
4. 应用和智能体读对象：查询、聚合、SQL。developer 看明细读数据集：aidc semantic connectivity dataset <RID> --rows 20。
5. 人要填的小表（映射、费率、清单）建成对象和 Action。aidc data import 只用于手工整理的小表，每次最多 5,000 行，不导入源系统的数据。
6. 数据流只放要秒级推送的小信号，最多 20,000 行。主数据和历史明细不进数据流。

接入的两条路

数据流由发布端推送变化。Data Connection 由平台按需读数据库。两条路线的选法见 数据接入。

数据集与事务

这一节讲数据集的记账方式。每次 TableImport 执行，都写一个数据集的事务。平台拿新的结果和上一份比较，只把变了的行写成对象。

导入方式	对象怎么变	适合
SNAPSHOT，可带窗口查询	对象就是这次读到的行。窗口外的行，和源里已经没有的行，标「源头已消失」	只要最近一段时间的数据，如订单、工单
APPEND，带增量列	只读上次之后改过的行，只增改	有可靠修改时间的流水表

• 每周对账：APPEND 看不到源头删掉的行。对账仅适用于配置了 initialIncrementalState 的非旧版 agent worker 导入。距上次全量快照满 7 天，且最近 7 天有成功的执行时，平台在夜里安排全量快照。对账遵守 workHours。失败后隔 7 天再试。平台将源头删掉的行标「源头已消失」。
• 上限：每个 TableImport 最多 150,000 行。同一个 TableImport 同时只有一个在途的构建。
• 数据边界：数据集的字节存在组织自己的存储桶里。平台库只存对象的属性值，即同步来的值和动作改过的值。配置、查询和数据集只给本组织的开发者看。

加工

这一节让你从数据集算出新的指标。指标在加工里算，不写在导入的 SQL 里每次整份重算。源数据只读一次。加工从数据集读。

加工是一条 DuckDB 的 SELECT。输入按别名当表用。加工的产出是同名的数据集。

写法	每次构建算什么	适合
非增量（不写 incremental）	整份重算	小表；要看前后行，如排名、前一天的值
append	只算新加的行，追加到产出	逐行的清洗、过滤、补字段
mergeAndReplace	新行涉及的键，在输入里的全部行重算，再按键合并进产出	按键汇总，如按表计和班日统计

{ "apiName": "stock-balance", "displayName": "库存余额",
  "inputs": {
    "moves": { "dataset": "stock-moves", "key": ["material_code"] },
    "materials": { "dataset": "materials" } },
  "sql": "SELECT m.material_code, sum(m.qty) AS on_hand, max(m.moved_at) AS last_move FROM moves m SEMI JOIN materials t ON t.material_code = m.material_code GROUP BY ALL",
  "incremental": { "semanticVersion": 1, "snapshotInputs": ["materials"], "output": "mergeAndReplace", "key": ["material_code"] } }

aidc semantic transforms put --ontology cell-demo --file stock-balance.json --dry-run   # 先预演：输入、环、名字
aidc semantic transforms put --ontology cell-demo --file stock-balance.json
aidc semantic transforms build <transformRid> --wait
aidc semantic transforms show <transformRid>     # 增量还是整份、受影响的键、读写多少行

• snapshotInputs 是输入的设置，不是写法。参考表整份读。它们的变化不触发构建，也不破坏增量。

以下情况需要整份重算：

• 第一次构建。
• semanticVersion 变了。
• 非 snapshot 的输入被整份替换过，或它的视图被整份替换后又追加了数据。

改了口径要回溯历史，就把 semanticVersion 加一。

• 设了 requireIncremental: true 时，输入快照替换引起的整份重算会导致构建失败。这防止大表意外整份重算。
• 输入和定义都没变时，构建直接成功，不执行 SQL。--force 跳过新鲜度判断。增量输入没有新事务时，加工仍不执行 SQL。需要整份重算时，将 semanticVersion 加一。
• 时间：数据集里不带时区的时间，在 SQL 里是北京时间。current_date 和 now() 也是北京时间。用它们的 SQL 每次结果都会变，不适合增量。
• 边界：只执行一条 SELECT，只能读这次的输入。输入不能是加工自己的产出。一个数据集只有一个产出者。

接到 Object Type

数据流或数据集绑定到 Object Type 以后，平台把变了的行写成对象。绑定的规则和命令见 数据接入。这一节讲绑定以后，对象怎么变。

• upsert（缺省）：标准的流。每条记录按主键更新整个对象，后到的为准。这一批里没出现的对象不消失。多行汇成一个对象、保留历史，也用它。
• mirror：流的全量就是全部对象。数据流里没有的行，对象标「源头已消失」。
• 数据集按导入方式决定：SNAPSHOT 相当于 mirror，APPEND 相当于 upsert。
• 定义落了之后，平台先全量同步一次，之后只同步变化。

新鲜度与按需

这一节讲平台什么时候计算。读取请求、自动化、手动执行或定期对账都可以触发 TableImport。

• 读取由 TableImport 或其下游加工供数的 Object Type 时，平台检查上游 TableImport 的新鲜度。导入和连接须处于 active 状态。导入须在工作时段内。近期失败时，平台暂缓重试。数据比 freshness.maxAgeSeconds 旧时，平台触发同步。缺省是 300 秒。平台先返回当前的值，再在后台同步。
• ?fresh=true（Python 客户端 fresh=True）最多等 20 秒。到时还没同步完，就返回现有的数据。

什么在消耗计算	什么时候发生
数据同步	有人读，且数据比 maxAgeSeconds 旧；或自动化的对象集条件引用了它
加工	输入提交了新的事务
应用	有人打开。只算当前页
订阅	页面可见时保持连接。隐藏超过 1 分钟断开，切回来续上
自动化	数据一变（对象集条件），或到点（时间条件）

Data Connection 路线上，常驻的只有 agent proxy 的控制通道。直连的组织没有常驻进程。数据流的发布端装在源系统旁边，常驻运行，每 30 秒发一次心跳。

数据健康

这一节让你知道数据是否在更新。数据集可以挂健康检查。检查失败、升级、恢复时，平台给建检查的人发邮件。

检查	怎么判
buildStatus	最近一次构建成败。对账的那次构建不算。可以设连续失败几次后升级为 CRITICAL
timeSinceLastUpdated	缺省检查最近一个非空已提交事务距今多久
schemaComparison	数据集现在的列，和期望的列比较
primaryKey	指定的列非空，且不重复

timeSinceLastUpdated 设置 ignoreEmptyTransactions: false 时，也计入空事务。

• 平台每 5 分钟评估一次检查。
• 同一状态 6 小时内不重复发邮件。每个组织每天最多 50 封。
• 报告和邮件只有状态和计数，不含数据的值。
• 没人读的时段，数据不更新。timeSinceLastUpdated 的上限要按最长的正常空闲时间来设。例如每天都有人读的数据，设 26 小时。
• 要发现「有人要数据却拿不到」，看 buildStatus。构建失败和排队超时都会报。

aidc semantic connectivity health create --file <检查.json> --intent "订单数据每日更新"

计算账：定时与按需

这一节帮你比较定时刷新与按需计算的成本。对象变化会触发自动化评估。数据多久同步一次由平台决定：有人读、或有自动化盯着时才同步。

每天运行次数 = 定时任务数 × (1440 ÷ 间隔分钟)
每天计算量  ≈ 每天运行次数 × 每次耗时（× 每次读的数据量）

Demo Company（示例）	定时刷新	按需
24 个看板脚本，每 10 分钟一次	24 × 144 = 3,456 次 / 天，每次查 ERP 加生成页面约 20 秒，每天约 19 小时计算	看板打开时现算当前页。新鲜度由平台按表的大小定（5 分钟到 1 小时）。读取过期数据时触发同步。同一 TableImport 合并在途请求
临时隧道的保活任务，每分钟一次	1,440 次 / 天	应用发布在平台上，没有隧道，没有保活
缺料提醒，每 5 分钟查一遍 ERP 比快照	288 次 / 天，大多数次什么都没变	对象变化触发评估。有自动化盯着的数据，平台在工作时段每 30 分钟、其余时间每 2 小时同步一次
数据是不是新的	脚本断了也没人知道	绑定有同步状态，应用有数据新鲜度组件，健康检查失败会告警

定时刷新的任务越积越多，很多看板没人看也每隔几分钟跑一次。按「数据一变、到点、有人看」三种触发重写，大多数可以停掉。大表（2 万行以上）的首次全量放在夜里，写入时盯着错误率。平时只写变化。

把定时看板迁进 Semantic

这一节讲怎么把一个定时看板改成按需的做法。按下面九步做，每一步都可以停下来核对。

1. 清点：每个定时任务的频率、读什么、产出什么、谁在看、每天真正被打开几次。
2. 分类：
   • 数据一变才要做的，做成自动化，条件是对象集的变化。
   • 时间本身是条件的（日报、月底对账），做成自动化，条件是时间。
   • 有人看才需要的，做成应用，打开时现算。
   • 没人用的，直接停。
3. 建模：按业务对象建 Object Type，不镜像原表。
4. 接数据：用 aidc semantic connectivity explore 找表。创建 TableImport，选择 SNAPSHOT 窗口查询或 APPEND 增量列。也可以使用数据流。需要的指标用加工算。在 Object Type 上绑定 datasources。
5. 做应用或自动化：看板做成应用，打开时现算。提醒做成自动化，在 replaces 里写上替掉了哪个定时任务，以及它原来每天跑几次。自动化的详情页会列出这些替代记录。
6. 预演：aidc semantic automations upsert --ontology cell-demo --file <automation.json> --dry-run，看编译出来的对象集和校验结果。
7. 并行一轮：新旧同时运行，对上结果。
8. 暂停旧任务：暂停，不删除。保留两周，留好恢复的办法。关掉隧道和保活任务。
9. 挂健康检查：在关键数据集上加 buildStatus 和 primaryKey。

自动化的写法见 自动化。

命令行

本页讲的主要命令如下。

命令	做什么
aidc semantic datasets	找已经同步的数据集
aidc semantic transforms put	建或替换加工
aidc semantic transforms show	看加工：增量还是整份，受影响的键
aidc semantic connectivity execute	执行一次 TableImport
aidc semantic datasource list	看数据集和数据流的绑定、同步进度

其余命令（imports、build、datasource sync、health create）的参数，见 参考 · 数据接入。

常见错误

现象	原因	怎么办
加工构建失败，产出了受影响的键以外的键	mergeAndReplace 的 key 表达式写错了	检查每个非 snapshot 输入的 key。表达式个数要和产出的键列一样，并按位置对应
加工构建失败，原因是不能增量	设了 requireIncremental，这次要整份重算	要整份重算，就把 semanticVersion 加一。或去掉 requireIncremental
构建直接成功，没有运行	输入和定义都没变	--force 只跳过新鲜度判断。整份重算需将 semanticVersion 加一

上限一览

项	上限或缺省
每个 TableImport	最多 150,000 行。同时只有一个在途的构建
Data Connection 并发	每个 agent 4 个，每个组织直连 4 个，每个组织全量 1 个
新鲜度	平台按表的大小定：5 分钟到 1 小时。fresh=true 最多等 20 秒。freshness 字段照收，但不再生效
自动化盯着的数据	平台在工作时段（北京时间 06:30–23:00）每 30 分钟同步一次，其余时间每 2 小时一次。evaluation 字段照收，但不再生效
加工的输入	1 到 10 个
加工一次构建	读的文件合计最多 384 MB（Parquet 压缩后）。产出最多 500 万行
加工并发	每个组织同时最多 2 个加工在运行
数据集的产出者	只有一个：一个 TableImport 或一个加工
数据流	见 数据接入 · 限制

worker 默认执行预算为 260 秒。SQL 计算在此预算内预留 30 秒收尾。对象索引未完成时，心跳会续跑。

下一步

• 数据接入：两条接入路线：数据流和 Data Connection。
• 对象：从表到对象，Object Type 怎么定义。
• 本体：定义 Object Type、链接和 Action。
• 自动化：数据变化或到点时执行 Action。
• 参考 · 数据接入：全部命令与参数。