翻译页面

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

架构

概述

StackQL 是一个统一的 SQL 接口，用于跨多个 Provider 查询和管理云基础设施。下面的容器图展示了 StackQL 系统的主要组件及其交互。

StackQL 支持通过多个入口点执行 SQL 查询：

CLI / Shell：交互式 shell 和命令行界面，用于直接从终端执行 SQL 查询。用户可以运行即席查询、脚本，或使用交互式 shell 进行探索。
PostgreSQL 线协议：支持从 psql、DBeaver 等标准 PostgreSQL 客户端或任何其他兼容 PostgreSQL 的工具进行连接。这样可以与现有的数据库工作流和 BI 工具无缝集成。
MCP 服务器：一个 Model Context Protocol 服务器，用于集成 AI 助手，使大语言模型能够通过自然语言查询和管理基础设施。

SQL 解析器：使用基于 Yacc 的自定义语法，将 SQL 输入解析为抽象语法树（AST）。解析器（实现为 stackql-parser）验证 SQL 语法，并为查询规划做好准备。
查询引擎：负责规划和执行查询的中央编排层。它确定哪些操作可以下推到 API 层，哪些需要在本地进行 SQL 处理。查询引擎负责：
- 查询规划和优化
- API 调用与本地 SQL 执行之间的协调
- 结果聚合和转换

Provider SDK omnisdk 管理与云服务商的所有交互。它在 StackQL v1.0 中取代了 any-sdk。主要职责包括：

Provider 发现：从 StackQL Registry 获取 Provider 规范（StackQL Registry 包含每个受支持云服务商的基于 OpenAPI 的定义），并可选择在使用每个文档之前验证其 ML-DSA-65 签名。
身份验证：处理每个 Provider 的身份验证，支持多种身份验证方式，包括 API 密钥、OAuth 令牌、服务账号凭据等。每个 Provider 定义都指定其身份验证要求；一个会话可以用多个别名绑定同一个 Provider，各自使用独立的凭据（见 Provider 会话）。
图规划：将每条语句规划为一张由 Provider 交换组成的图，这些交换通过数据边和控制边相连。连接、子查询、CTE 和视图都经过同一个规划器，从一个计划扇出的请求在每个 Provider 和每个主机的限制内并发运行。
API 请求构建：将 SQL 查询转换为适用于每个 Provider 的 REST API 调用，处理端点构造、参数映射和请求格式化。
分页：自动处理分页的 API 响应，屏蔽各个 Provider 所用的不同分页方案（基于游标、基于偏移量、基于令牌等）的复杂性。
谓词下推：将映射到请求参数的条件，以及在不需要排序时的 LIMIT，下推到 Provider 请求中，以减少发出的请求数量和传输的数据量。
响应转换：在 API 响应到达时将其转换为行，以便暂存到 SQL 后端或流式传输到客户端。

SQL 连接、暂存和后端执行都保留在 StackQL 中。omnisdk 不包含 SQL 暂存，也从不接收数据库连接；StackQL 向它传递关系句柄，并接收行游标。

SQL 后端对物化后的 API 数据执行关系操作：

SQL 后端处理的操作包括：

StackQL 通过云服务商（AWS、GCP、Azure、Kubernetes、GitHub 以及更多）的 REST API 与其连接。所有通信都通过 HTTPS 进行，Provider SDK 负责处理每个 Provider 的 API 约定的具体细节。

StackQL Registry 托管 Provider 定义，即基于 OpenAPI 的规范，描述可用的资源、方法及其映射。Provider 带有版本，可使用 REGISTRY PULL 命令按需拉取。