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

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

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

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

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

为了支持这种以开发人员为中心的用例，我们去年推出了 ClickPipes——我们的 ClickHouse Cloud 原生摄取平台。ClickPipes 最初支持 Kafka 流摄取，但此后我们实施了对 Redpanda、WarpStream、Azure Event Hub、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 Console 中的现有功能的基础上构建了它

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

换句话说，构建查询 API 端点所需的基础元素已经在生产环境中经过了数月至数年的实战检验。实施主要需要以一种新的方式将这些组件串联在一起，并扩展我们的 SQL 控制台已保存查询 UI，以便为用户提供一种简单无缝的方式来配置和监控其端点。

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

前端开发人员只需要两项关键技能即可构建他们的下一个分析应用程序：在 ClickHouse 中创建查询的能力（如果需要，可以借助我们的副驾驶/Gen AI）以及熟练掌握他们首选的 Web 框架。

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