SQL 与直连

第 4 课 · 共 6 课 约 6 分钟

每个组织一个只读数据库：表名是对象类型，列名是属性；一条 SELECT、1 万行、20 秒。

本课目标

读完这一课，你将能够

  • 说出 Semantic 数据库的结构：schema、表名、列名、关系表与接口表
  • 在 SQL 页写一条合规的查询，用上位置参数
  • 说出直连怎么拿，reader 与 public 两个角色各看得见什么

每个组织一个数据库

Semantic 给每个组织一个自己的 Postgres schema，名字是 ont_ 加组织名，例如 AIDC 是 ont_aidc。第一次打开 SQL 页时按需建好；本体的定义变了，下一次查询时自动重建。

里面不复制任何数据：每张表都是一个视图，直接读对象的当前值（数据源的值加上语义层的改动）。已删除的对象、源头已消失的对象不会出现。

OBJECT TYPE

一个对象类型一张表

表名 = 对象类型的 API name，列名 = 属性的 API name，例如 organization、modelUsage。一对多的关系直接用外键 join。

LINK

多对多关系一张表

两端各一列，列名是 <对象类型>_<关系>，值是走这条关系到达的对象的主键：applicationSdks 里的 application_sdks 是 SDK 的主键。

INTERFACE

一个接口一张表

实现它的对象类型合在一起，另有 __objectType 和 __primaryKey 两列。

DERIVED

派生属性不在表里

它们是读的时候沿关系算的；在 SQL 里自己 join，再 count 或 sum。

在 SQL 页写查询

左栏 SQL 打开 SQL Console：左边是表和列，右边是编辑器和结果，Ctrl/⌘ + Enter 执行。两条查 AIDC 自己数据的例子：

-- 每个组织有几位数字员工（派生属性不在表里，自己 join）
SELECT o.name, count(a."agentId") AS agents
FROM organization o
LEFT JOIN agent a ON a."organizationId" = o."organizationId"
GROUP BY o.name
ORDER BY agents DESC
LIMIT 20;

-- 按月汇总模型费用，最近的月份在前
SELECT "month", round(sum("costUsd")::numeric, 2) AS cost_usd, sum(calls) AS calls
FROM "modelUsage"
GROUP BY "month"
ORDER BY "month" DESC;
  • 只收一条 SELECT，可以用 WITH、VALUES、TABLE 开头；不能写入，也不能改定义。
  • 最多返回 10,000 行，超出会提示截断；20 秒没跑完就取消，加条件或 LIMIT。
  • 值用位置参数 $1、$2……和查询分开传（API 是 POST /api/v1/sqlQueries/executeOntology 的 parameters），不要拼进 SQL；不支持 DECLARE 和 SET。
随口一问

帮我查一下模型费用。

好的交代

在 cell-aidc 的 Semantic 里用 SQL 查 "modelUsage"：按月汇总 "costUsd"，只要最近 6 个月，从新到旧，结果给我一张表，不要改任何数据。

直连：psql、BI 工具与 Notebook

本组织的开发者可以在 SQL 页的「连接」里轮换口令，拿到一条只读连接串，用 psql、BI 工具或 Notebook 直连。口令只显示一次；再轮换一次，旧口令立即失效。

aidc semantic database --rotate        # 轮换口令，拿到新的连接串（只显示一次）
psql "<连接串>"
\dv                                      -- 列出视图：对象类型、多对多关系、接口各一张
SELECT count(*) FROM "modelUsage";
readerpublic
看得见本组织看得见的全部表只有公开的表（授予了 Everyone）
给谁用本组织成员、开发者 Key、Agent Key、在 Ontology 上有 Viewer 以上角色的人；直连也是它只看得见 Public 的外部账号
连接数上限105

两个角色都是只读登录，每次查询 20 秒超时：看不到平台自己的表，也看不到别的组织的 schema。SQL 页和 API 按你的身份自动选角色，你不用管。

要点

  • 每个组织一个 schema；表名 = 对象类型的 API name，列名 = 属性的 API name。
  • 多对多关系一张表，列名 <对象类型>_<关系>；接口一张表，带 __objectType。
  • 只收一条 SELECT，最多 10,000 行、20 秒；值用 $1 传。
  • 开发者轮换口令拿只读连接串，用 psql 直连；口令只显示一次。
  • reader 看本组织看得见的全部，public 只看公开的。

练一练

写三条查询

在 SQL 页做。没有自己的数据时，打开 AIDC 的 SQL 页，用公开的产品、方案、SDK、模型、课程练。

数一数每个学习对象有几门课：SELECT track, count(*) FROM course GROUP BY track;

小测

选一个答案，马上看解析。

Q1「模型用量」的 API name 是 modelUsage，在 SQL 里表名怎么写？

Q2下面哪条会被 SQL 页拒绝？

Q3一个别家公司的账号打开 AIDC 的 SQL 页，能查到哪些表？

延伸阅读