跳到主要内容
翻译页面

本页面由 AI 辅助从英文翻译而来。如两者存在差异，以英文版本为准。

什么是 SQL for APIs？

SQL for APIs（面向 API 的 SQL）是一种设计模式，将 API 操作投影到关系语义上：列出和获取操作变为 SELECT，创建操作变为 INSERT，修改操作变为 UPDATE 或 REPLACE，移除操作变为 DELETE。API 的响应对象成为行；其属性成为列。该模式让任何 REST 或 RPC API 都具有数据库般的易用性，而无需 API 提供方做任何更改。

工作原理​

这种映射是机械的，正因如此它才具有通用性：

API 概念关系概念
Provider（AWS、GitHub）schema 命名空间
服务（EC2、repos）子 schema
资源集合表
列出 / 获取操作SELECT 方法
创建操作INSERT 方法
Patch / put 操作UPDATE / REPLACE 方法
删除操作DELETE 方法
其他生命周期操作（启动、停止、重启）EXEC 方法
必需的路径参数或查询参数必需的 WHERE 子句谓词
请求体字段带 data__ 前缀的插入/更新列

在 StackQL 中，这种映射由扩展的 OpenAPI 规范生成，这些规范保存在开放的 StackQL Provider 注册表中。必需的 API 参数可在运行时发现：SHOW METHODS IN aws.ec2.instances 返回每个方法的 SQL 动词及其必需参数，因此人或 AI 智能体无需阅读 Provider 文档即可推导出正确的查询。

示例​

读取是一条 SELECT，其 WHERE 子句携带 API 的必需参数：

SELECT name, language, stargazers_count
FROM github.repos.repos
WHERE org = 'stackql';

创建是一条 INSERT，其列携带请求体（带 data__ 前缀）和路由参数：

INSERT INTO google.storage.buckets(
  project,
  data__name,
  data__location
)
SELECT
  'my-project',
  'my-new-bucket',
  'US';

SHOW INSERT INTO google.storage.buckets 会机械地生成此模板，其中包含所有可写字段。

为什么存在​

SQL 是现存部署最广泛的查询语言，拥有 50 年的工具积累：驱动程序、ORM、BI 平台、notebook，以及日益重要的 LLM 训练数据。每个主流 AI 模型都已经能够读写合格的 SQL。将 API 投影为 SQL，意味着所有这些工具和模型能力可立即适用于任何 API 接口面。另一种做法（每个 Provider、每种语言各一个 SDK）会使集成工作成倍增加，并且不给智能体提供任何可复用的东西。这一论点在为什么 SQL 是云 API 的强大接口中有进一步阐述。