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

查询 API 端点

查询 API 端点 功能使您能够直接从 ClickHouse Cloud 控制台中的任何保存的 SQL 查询创建 API 端点。您可以通过 HTTP 访问 API 端点，以在不需要通过原生驱动程序连接到 ClickHouse Cloud 服务的情况下执行保存的查询。

快速入门指南​

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

创建保存的查询​

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

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

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

测试示例查询

接下来的步骤是保存该查询：

保存示例查询

有关保存查询的更多文档可以在这里找到。

配置查询 API 端点​

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

配置查询端点

选择一个 API 密钥后，查询 API 端点将自动开通。将显示一个示例 curl 命令，以便您可以发送测试请求：

端点 curl 命令

查询 API 参数​

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

测试和监控​

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

端点 curl 测试

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

端点监控

实施细节​

描述​

此路由在指定的查询端点上运行查询。它支持不同的版本、格式和查询变量。响应可以以流的形式传输（仅限 version 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：