自动查询端点：从 SQL 查询创建 API

构建交互式数据驱动应用程序不仅需要快速数据库、结构良好的数据和优化的查询。您的前端和微服务还需要一种简单的方法来使用这些查询返回的数据，最好通过结构良好的 API。

今天，我们很高兴宣布新的自动查询端点功能，它使得这一切成为可能。只需点击几下，您就可以直接从 ClickHouse Cloud 控制台中的任何已保存 SQL 查询创建 API 端点。

在 ClickHouse，我们认为真正的“托管”数据库即服务产品不应仅仅抽象掉基础设施的复杂性，还应为每天使用数据的开发人员和分析师提供一流的体验。我们最近彻底改进了 ClickHouse Cloud 控制台体验以支持这一点，从而大幅缩短了 ClickHouse Cloud 服务与我们的控制平面 UI 之间的距离。这种新的 UI 应该使许多分析师用户进行临时数据导入、查询和可视化变得相对简单和轻松。

但是，虽然我们的 SQL 控制台 UI 已成为许多分析师日常工作流中不可或缺的一部分，但它仍然缺乏一些关键功能，无法为开发人员提供真正出色的体验。开发人员通常更关心数据的编程摄取和使用。因此，对于开发人员而言，Cloud 控制台 UI 主要用作数据的真实来源（例如数据是否存在于表中、存储了多少数据量、查询是否已正确优化等）以及用于创建、修改和监控摄取/使用服务的集中位置。

为了支持这种以开发人员为中心的用例，我们去年推出了 ClickPipes——我们的 ClickHouse Cloud 原生摄取平台。ClickPipes 最初支持 Kafka 流摄取，但我们此后已实施了对 Redpanda、WarpStream、Azure 事件中心、S3/GCS、Kinesis（最近）以及许多其他数据源的支持，这些支持将在短期内实现。换句话说，围绕数据摄取的以开发人员为中心的工具开发工作已经顺利进行，因此，唯一剩下的功能部分是围绕编程数据使用提供愉快的开发人员体验。

在我们看来，基于查询的 API 端点代表了一种简单灵活的编程数据使用（以及潜在的摄取）框架，因为它们解决了两个主要挑战

ClickHouse 为大多数主要编程语言维护客户端，大多数客户端设置起来都比较简单。但是，对开发人员可能立即有用的更深层功能（连接池、保持活动配置、压缩、流式传输、参数化等）可能需要一些时间来弄清楚。

或者，使用（例如）Javascript 中的 fetch() API 来访问 ClickHouse 的 HTTP 接口也很容易，但这会带来与语言客户端中相同的初始挑战——复杂性只是从客户端配置转移到 HTTP 标头配置。

基于查询的 API 端点解决方案可以抽象掉大部分这种复杂性。

即使 ClickHouse 为本地和 HTTP 接口都支持几种身份验证方法，但在实践中，基本身份验证（令人担忧的是）仍然被广泛使用。根据我们的经验，许多组织选择基本身份验证，因为它代表了在设置大多数语言客户端/普通 HTTP 请求时阻力最小的路径。虽然数据库级 RBAC 可以缓解围绕基本身份验证的一些风险，但定义正确的用户/角色授权通常很困难——尤其是对于 ClickHouse 的新用户而言

我们基于查询的 API 端点解决方案通过利用我们现有的 Cloud API 密钥/秘密身份验证模式来回避这一挑战。由于每个 API 端点实际上代表一个单一查询，因此访问范围仅限于该特定查询。

首先，我们需要一个 Cloud API 密钥。可以在组织级设置的“API 密钥”页面中创建和管理 API 密钥

现在我们有了密钥，就可以转到 SQL 控制台并创建一个新查询。在本演示中，我们将使用“youtube”数据集，该数据集包含大约 45 亿条记录。作为示例查询，我们将返回在用户输入的年份中按每视频平均观看次数排名前 10 的上传者

with sum(view_count) as view_sum,
    round(view_sum / num_uploads, 2) as per_upload
select
    uploader,
    count() as num_uploads,
    formatReadableQuantity(view_sum) as total_views,
    formatReadableQuantity(per_upload) as views_per_video
from
    youtube
where
    toYear(upload_date) = {year: UInt16}
group by uploader
order by per_upload desc
limit 10

请注意，此查询包含一个参数（年份）。SQL 控制台查询编辑器会自动检测 ClickHouse 查询参数表达式，并为每个参数提供输入。让我们快速运行此查询，以确保它有效

下一步，我们将保存此查询

保存查询后，我们可以通过点击“共享”按钮并选择“API 端点”来为其创建 API 端点。系统将提示您指定哪些 API 密钥可以访问该端点

选择 API 密钥后，我们就可以开始了！示例“curl”命令演示了如何构建对该端点的请求

现在，我们可以尝试 curl 该端点

现在我们已验证该端点有效，让我们回到 SQL 控制台。“共享”按钮右侧应该立即出现一个新按钮。点击该按钮将打开一个包含有关查询的监控数据的弹出窗口

为了尽快发布此功能的初始版本，我们在 Cloud 控制台中的现有功能的基础上进行了构建

• 已保存的查询
• 查询参数化
• 使用证书的无密码 DB 身份验证
• 服务器端查询执行
• 现有 Cloud API 密钥作为端点身份验证方法

换句话说，构建查询 API 端点所需的基石元素已经在生产环境中经过了数月至数年的考验。实施主要需要以一种新方式将这些组件串联起来，并扩展我们的 SQL 控制台已保存查询 UI，以便用户能够轻松流畅地配置和监控其端点。

虽然 OpenAPI 密钥可用，但它们仍处于 Beta 阶段，主要是因为当前的功能无法为网页内用户界面中的直接端点调用提供最佳解决方案。为了提升用户体验，我们计划通过 JWT（您自己的 JWT）引入身份验证/授权。这将使这些 API 端点成为任何开发人员构建分析应用程序后端的基石。

前端开发人员只需要掌握两项关键技能就可以构建他们下一个分析应用程序：能够创建 ClickHouse 查询（如有需要，可借助我们的副驾驶/生成式 AI）以及精通他们首选的 Web 框架。

我们还计划添加对流式 API 的支持，让您可以通过 API 端点提取所有数据，而无需内存限制。