自动查询端点：从 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 Event Hub、S3/GCS、Kinesis（最近）以及许多其他数据源的支持。换句话说，围绕数据摄取的以开发人员为中心的工具的开发已经全面展开，因此唯一剩下的功能是围绕编程数据使用提供愉快的开发人员体验。

在我们看来，基于查询的 API 端点为编程数据使用（以及可能还有摄取）提供了一个简单而灵活的框架，因为它们解决了两个关键挑战

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

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

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

即使 ClickHouse 支持 Native 和 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

请注意，此查询包含一个参数 (year)。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 端点提取所有数据，而无需担心内存限制。