SQL 与数据库

Ontology SQL 让你用一条 SELECT 查对象。表名是 Object Type 的 API name，列名是属性的 API name。SQL 只读。写入只能走 Action。

Ontology SQL 有两种方言。Postgres 方言是命令行和 SDK 的缺省。标准方言是 Spark SQL，结果是 Apache Arrow。见选方言。

快速上手

用 SDK 查询时，参数用 $1、$2 等占位符，按位置传入。

import { semantic } from "/developer/sdk/v1/aidc.js";

const r = await semantic.sql(
  "SELECT name, seats FROM customer WHERE stage = $1 AND seats > $2 ORDER BY seats DESC",
  { parameters: ["付费", 30] },
);
console.log(r.rows);

命令行的写法相同。--param 按顺序对应 $1、$2。

$ aidc semantic sql 'SELECT name, seats FROM customer WHERE stage = $1 AND seats > $2 ORDER BY seats DESC' --param 付费 --param 30
name	seats
Demo Customer A	48
Demo Customer B	36
（2 行 · 12 ms · 角色 reader）
$ 

最后一行是行数、耗时和角色。耗时因环境而异。

选方言

两种方言查的是同一份数据。下表列出它们的区别。

• 写报表、接 BI 工具、用直连：用 Postgres 方言。它和数据库直连用同一套视图。
• 要 Arrow 结果、按 RID 引用表、用命名参数或 DECLARE：用标准方言。见标准方言：Spark SQL 与 Arrow。

写查询

本节是 Postgres 方言的写法。一条查询的写法有以下规则。

• 只能写一条 SELECT。查询可以用 WITH、VALUES 或 TABLE 开头。服务端去掉末尾的分号。
• 不能写入，不能改定义。DECLARE 和 SET 不支持。
• 参数用 $1、$2 等占位符。JavaScript 用 parameters 数组。命令行重复使用 --param。Python 用参数列表。最多 100 个参数。
• 表名是 Object Type 的 API name，列名是属性的 API name。名字里有大写字母的，要加双引号，例如 "modelUsage" 和 "Billable"。
• 派生属性不在 SQL 里。要用派生结果，用 JOIN 或子查询自己算。
• 一对多链接用外键列 JOIN。例如 agent."customerId" 指向 customer."customerId"。
• 多对多链接有自己的视图，视图名是链接的 API name。两端的列名是 <对象类型>_<链接名>，例如 application_agents。
• 接口有自己的视图，合并了所有实现它的 Object Type。视图多两列：__objectType 标明这一行来自哪个 Object Type，__primaryKey 是主键。
• SQL 只查 main 上的定义，不支持分支。

标准方言：Spark SQL 与 Arrow

标准方言是 Spark SQL 的一个子集。一次请求执行一条只读的 SELECT。SELECT 前面可以有一条 DECLARE。

const { arrow, truncated } = await semantic.sqlOntology(
  "SELECT name, seats FROM customer WHERE seats > ? ORDER BY seats DESC",
  { parameters: [10] },
);
// import { tableFromIPC } from "apache-arrow"; const table = tableFromIPC(arrow);

const r = await semantic.sql(
  "SELECT c.name, count(a.agentId) AS agents FROM customer c LEFT JOIN agent a ON a.customerId = c.customerId GROUP BY c.name",
  { dialect: "spark" },
);   // JSON 结果，每行是一个对象

aidc semantic sql 'SELECT name, seats FROM customer WHERE seats > ?' --dialect spark --param 10
aidc semantic sql 'SELECT name FROM customer WHERE stage = :stage' --dialect spark --named stage=付费 --json
aidc semantic sql 'DECLARE @n INT = 5; SELECT name FROM customer LIMIT @n' --dialect spark
aidc semantic sql 'SELECT * FROM customer' --dialect spark --arrow customers.arrow

表名与列名

• 表名写反引号括起来的 RID。Object Type 是 `ri.ontology.main.object-type.<uuid>`，多对多链接是 `ri.ontology.main.relation.<uuid>`，接口是 `ri.ontology.main.interface.<uuid>`。
• 用 GET /api/v2/ontologies/{命名空间}/objectTypes 查 RID。
• API name 也能当表名，例如 FROM customer 或 FROM `Customer`。名字不分大小写。
• 列名是属性的 API name。多对多链接两端的列名是 <对象类型>_<链接名>。接口的表另有 __objectType 和 __primaryKey 两列。
• tableProviders 把一个表名绑到一个对象集。

参数与变量

• 位置参数写 ?，请求体用 unnamedParameterValues。命名参数写 :name，请求体用 namedParameterMapping。两种不能混用。
• 参数值带类型，例如 { "type": "string", "value": "付费" }。类型有 string、integer、long、double、boolean、date、timestamp、null 和 list。
• SDK 按 JavaScript 的值推断类型。也可以直接写 { type, value }。
• 命令行的 --param 和 --named 按值的写法推断类型。007、1.50 这类值按字符串传。
• 变量写 DECLARE @minSeats INT = 10;。对象集变量写 DECLARE @c `ri.ontology.main.object-type.…`;。

支持的语法与函数

• 语法：WITH、UNION、INTERSECT、EXCEPT、各种 JOIN、子查询、EXISTS、IN、LIKE、BETWEEN、CASE、CAST，以及带 PARTITION BY 和 ORDER BY 的窗口函数。
• 不支持：IF（用 CASE WHEN）、RLIKE、INTERVAL、||（用 concat）、%（用 mod）、窗口的 frame 子句。

权限与结果

• 平台按调用的人判定权限。看不见的 Object Type 等于不存在，返回 OntologyObjectTypeNotFound。
• 看不见的对象不在结果里。看不见的属性是 NULL。Markings 和对象、属性的安全策略照常生效。
• 查询在本组织的只读角色、只读事务里执行。
• 结果是 Apache Arrow IPC stream（application/octet-stream）。带 Accept: application/json 时，返回 { columns, rows, rowCount, truncated, rowLimit, elapsedMs }。
• 结果被截断时，响应头 X-AIDC-Truncated 是 true。

例子

本节的例子用 Postgres 方言。按月汇总费用。Billable 视图合并了模型用量和云费用两类对象。

SELECT month, sum("costUsd") AS usd
FROM "Billable"
GROUP BY month
ORDER BY month

只要模型用量，把视图换成 "modelUsage"。

连接两个 Object Type。下面统计每家公司的智能体数。查询存进 agents.sql 后，用 --file 运行。

SELECT c."name", count(a."agentId") AS agents
FROM customer c
LEFT JOIN agent a ON a."customerId" = c."customerId"
GROUP BY c."name"
ORDER BY agents DESC, c."name"

$ aidc semantic sql --file agents.sql
name	agents
Demo Customer A	4
Demo Customer B	4
Demo Customer D	3
Demo Customer C	2
Demo Customer E	2
Demo Customer F	0
（6 行 · 15 ms · 角色 reader）
$ 

Python 客户端的写法如下。sql 的第二个参数是参数列表。

from aidc_semantic import sql

rows = sql("SELECT name, seats FROM customer WHERE stage = $1 AND seats > $2 ORDER BY seats DESC", ["付费", 30])

命令行选项

aidc semantic sql 的选项如下。

上限

下表列出查询的上限。

角色与权限

本节是 Postgres 方言和数据库直连的权限。标准方言按调用的人逐个判定，见权限与结果。

Postgres 方言有两个只读角色。reader 能看到本组织看得见的全部 Object Type。public 只能看到授予了所有人（Everyone）的 Object Type。

挂了 Marking 的 Object Type 不进 Postgres 方言的视图。见 访问与安全。

数据库：视图与直连

每个组织有一个 Postgres schema。默认前缀是 ont。schema 名由前缀、_ 和名字部分组成。名字部分按下面的步骤得出：

1. 去掉 cell-。
2. 把连续的非小写字母和数字的字符换成 _。
3. 去掉首尾的 _。
4. 取前 40 个字符。

例如 cell-demo 对应 ont_demo。第一次查询时建好。定义变了，下一次查询时自动重建。

• 符合条件的 Object Type 有一个视图，视图名是 Object Type 的 API name。下列类型不建视图：
  • 部门级类型。
  • 受 Markings 或安全策略保护的类型。
  • 名称超过 63 字节的类型。
  • 没有存储属性的类型。
• 符合条件的多对多链接有一个视图。两端的 Object Type 都有视图，且链接名不超过 63 字节。
• 符合条件的接口有一个视图，合并了实现它的 Object Type。接口要有属性，名称不超过 63 字节，并且至少有一个实现它的 Object Type 有视图。
• 视图直接读当前值，即数据源的值加上语义层的改动。视图不复制数据。被删除的对象，和源头已消失的对象，都不出现。
• 派生属性不进视图。
• 属性类型对应的 SQL 类型如下表。

$ aidc semantic database
schema ont_demo · 我用 reader 角色 · active · 视图建于 2026-10-08 09:12
  表  customer                     11 列  客户公司
  表  agent                        9 列  智能体
  …
直连：ont_demo_reader@<主机>:5432/<库>（口令用 aidc semantic database --rotate 拿）
$ 

… 表示省略的视图。表 对应 Object Type，链接 对应多对多链接，接口 对应接口。

开发者可以拿到直连口令。轮换口令会返回一次新的连接串。旧口令立即失效。

$ aidc semantic database --rotate
只读直连（口令只显示这一次，再轮换即失效）：
  psql "…"
  schema ont_demo · user ont_demo_reader
$ 

• 直连只给本组织的开发者。把连接串交给 psql、BI 工具或笔记本即可。
• 直连只能看到本组织看得见的视图。事务默认只读。单条查询超过 20 秒，服务端取消超时查询。
• 口令由服务端派生，不存进数据库。数据库里只存校验值。再轮换一次，旧口令立即失效。
• 连接要求 TLS（sslmode=require），只有 localhost 例外。
• aidc semantic database --sync 按当前定义重建视图。定义变了，查询时也会自动重建。

SQL Console 网页

网页地址是 /semantic/<组织>/sql。在这里运行 SQL，查看结果。开发者在「连接」里轮换直连口令。

错误

下表列出 SQL 的常见错误码。

标准方言的错误体是 { errorCode, errorName, errorInstanceId, parameters }。

命令行

本页相关的命令如下。全部参数见 参考 · Semantic 本体与数据。

API

下表列出 SQL 与数据库的接口。前缀里的 {命名空间} 是组织的命名空间，例如 cell-demo。

两个接口的请求体字段相同：query、parameters、rowLimit、dryRun 和 ontologyIdentifier。标准方言另有 tableProviders。Postgres 方言的响应带 Link: rel="successor-version" 头，指向标准方言的接口。

下一步

• 读写对象：对象集、Action 与订阅。
• 定义本体：视图由 Object Type、链接和接口生成。
• 访问与安全：谁能查询，Marking 怎样限制行和列。
• 数据管道：加工结果怎样变成数据集和对象。