跳到主要内容
跳到主要内容

查询 API 端点

查询 API 端点 功能允许您直接从 ClickHouse Cloud 控制台中的任何保存的 SQL 查询创建 API 端点。您可以通过 HTTP 访问 API 端点，以执行您的保存查询，而无需通过本地驱动程序连接到您的 ClickHouse Cloud 服务。

快速入门指南​

在继续之前，请确保您拥有 API 密钥和管理员控制台角色。您可以按照本指南 创建 API 密钥。

创建保存的查询​

如果您已经有了保存的查询，可以跳过此步骤。

打开一个新的查询选项卡。为了演示目的，我们将使用 youtube 数据集，该数据集包含大约 45 亿条记录。作为示例查询，我们将根据用户输入的 year 参数返回按每个视频的平均观看次数排名前 10 的上传者：

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

接下来，我们将保存查询：

有关保存查询的更多文档，请参见 这里。

配置查询 API 端点​

可以通过点击 分享 按钮并选择 API 端点 从查询视图直接配置查询 API 端点。系统会提示您指定可以访问该端点的 API 密钥：

选择 API 密钥后，查询 API 端点将自动配置。示例 curl 命令将显示，您可以用它发送测试请求：

查询 API 参数​

查询中的查询参数可以使用语法 {parameter_name: type} 指定。这些参数将被自动检测，示例请求有效负载将包含一个 queryVariables 对象，通过该对象您可以传递这些参数。

测试和监控​

创建查询 API 端点后，您可以使用 curl 或任何其他 HTTP 客户端测试其是否正常工作：

在您发送第一个请求后，分享 按钮右侧应立即出现一个新按钮。单击它将打开一个弹出窗口，包含有关查询的监控数据：

实现详情​

描述​

此路由在指定的查询端点上运行查询。它支持不同的版本、格式和查询变量。响应可以是流式的（仅限版本 2）或作为单个有效负载返回。

身份验证​

  • 必需：是
  • 方法：通过 OpenAPI 密钥/密钥的基本身份验证
  • 权限：对查询端点的适当权限。

URL 参数​

  • queryEndpointId（必需）：要运行的查询端点的唯一标识符。

查询参数​

V1​

无

V2​

  • format（可选）：响应的格式。支持 ClickHouse 支持的所有格式。
  • param_:name 查询变量，用于查询中。 name 应与查询中的变量名称匹配。这应该仅在请求主体是数据流时使用。
  • :clickhouse_setting 任何支持的 ClickHouse 设置 可以作为查询参数传递。

头部​

  • x-clickhouse-endpoint-version（可选）：查询端点的版本。支持的版本为 1 和 2。如果未提供，默认版本为该端点最后保存的版本。
  • x-clickhouse-endpoint-upgrade（可选）：设置此头部以升级端点版本。此操作与 x-clickhouse-endpoint-version 头部配合使用。

请求主体​

  • queryVariables（可选）：包含用于查询的变量的对象。
  • format（可选）：响应的格式。如果查询 API 端点为版本 2，任何 ClickHouse 支持的格式都是可能的。v1 的支持格式为：
    • TabSeparated
    • TabSeparatedWithNames
    • TabSeparatedWithNamesAndTypes
    • JSON
    • JSONEachRow
    • CSV
    • CSVWithNames
    • CSVWithNamesAndTypes

响应​

  • 200 OK：查询成功执行。
  • 400 Bad Request：请求格式错误。
  • 401 Unauthorized：请求未进行身份验证或权限不足。
  • 404 Not Found：未找到指定的查询端点。

错误处理​

  • 确保请求包含有效的身份验证凭据。
  • 验证 queryEndpointId 和 queryVariables 确保它们是正确的。
  • 优雅地处理任何服务器错误，返回适当的错误消息。

升级端点版本​

要将端点版本从 v1 升级到 v2，请在请求中包含 x-clickhouse-endpoint-upgrade 头部并将其设置为 1。这将触发升级过程，并允许您使用 v2 中可用的功能和改进。

示例​

基本请求​

查询 API 端点 SQL：

版本 1​

cURL：

JavaScript：

响应：

版本 2​

cURL：

JavaScript：

响应：

请求中带有查询变量和版本 2 的 JSONCompactEachRow 格式​

查询 API 端点 SQL：

cURL：

JavaScript：

响应：

请求中带有数组的查询变量，该变量向表中插入数据​

表 SQL：

查询 API 端点 SQL：

cURL：

JavaScript：

响应：

请求时将 ClickHouse 设置 max_threads 设置为 8​

查询 API 端点 SQL：

cURL：

JavaScript：

请求并将响应解析为流​

查询 API 端点 SQL：

Typescript：

输出

从文件向表中插入流​

创建一个文件 ./samples/my_first_table_2024-07-11.csv，内容如下：

创建表 SQL：

查询 API 端点 SQL：

cURL：