クエリAPIエンドポイント 機能を使用すると、ClickHouse Cloudコンソールの任意の保存されたSQLクエリから直接APIエンドポイントを作成できます。ネイティブドライバーを介してClickHouse Cloudサービスに接続することなく、HTTP経由でAPIエンドポイントにアクセスして保存されたクエリを実行できます。
クイックスタートガイド
先に進む前に、APIキーと管理コンソールロールを持っていることを確認してください。このガイドに従って、APIキーを作成できます。
保存されたクエリの作成
保存されたクエリがある場合は、このステップをスキップできます。
新しいクエリタブを開きます。デモ目的で、約45億件のレコードを含むyoutubeデータセットを使用します。例として、ユーザーが入力したyearパラメータごとに、平均視聴回数が最も多い上位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キーがエンドポイントにアクセスできるか指定するよう求められます：
APIキーを選択すると、クエリAPIエンドポイントが自動的にプロビジョニングされます。テストリクエストを送信するためのcurlコマンドの例が表示されます：
クエリAPIパラメータ
クエリ内のクエリパラメータは、{parameter_name: type}という構文で指定できます。これらのパラメータは自動的に検出され、例のリクエストペイロードには、これらのパラメータを渡すためのqueryVariablesオブジェクトが含まれます。
テストと監視
クエリAPIエンドポイントが作成されると、それが機能するかどうかをcurlまたは他のHTTPクライアントを使用してテストできます：
最初のリクエストを送信した後、すぐに【共有】ボタンの右側に新しいボタンが表示されるはずです。それをクリックすると、クエリに関する監視データを含むフライアウトが開きます：
実装の詳細
このルートは指定されたクエリエンドポイントでクエリを実行します。さまざまなバージョン、形式、クエリ変数をサポートしています。レスポンスはストリーミングされる（バージョン2のみ）か、単一のペイロードとして返されます。
- 必要: はい
- 方法: OpenAPIキー/シークレットによる基本認証
- 権限: クエリエンドポイントに必要な適切な権限。
URLパラメータ
queryEndpointId（必須）: 実行するクエリエンドポイントのユニークな識別子。
クエリパラメータ
なし
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:
SELECT database, name AS num_tables FROM system.tables LIMIT 3;
バージョン1
cURL:
curl -X POST 'https://console-api.clickhouse.cloud/.api/query-endpoints/<endpoint id>/run' \
--user '<openApiKeyId:openApiKeySecret>' \
-H 'Content-Type: application/json' \
-d '{ "format": "JSONEachRow" }'
JavaScript:
fetch(
"https://console-api.clickhouse.cloud/.api/query-endpoints/<endpoint id>/run",
{
method: "POST",
headers: {
Authorization: "Basic <base64_encoded_credentials>",
"Content-Type": "application/json",
},
body: JSON.stringify({
format: "JSONEachRow",
}),
}
)
.then((response) => response.json())
.then((data) => console.log(data))
.catch((error) => console.error("Error:", error));
レスポンス:
{
"data": {
"columns": [
{
"name": "database",
"type": "String"
},
{
"name": "num_tables",
"type": "String"
}
],
"rows": [
["INFORMATION_SCHEMA", "COLUMNS"],
["INFORMATION_SCHEMA", "KEY_COLUMN_USAGE"],
["INFORMATION_SCHEMA", "REFERENTIAL_CONSTRAINTS"]
]
}
}
バージョン2
cURL:
curl -X POST 'https://console-api.clickhouse.cloud/.api/query-endpoints/<endpoint id>/run?format=JSONEachRow' \
--user '<openApiKeyId:openApiKeySecret>' \
-H 'Content-Type: application/json' \
-H 'x-clickhouse-endpoint-version: 2'
JavaScript:
fetch(
"https://console-api.clickhouse.cloud/.api/query-endpoints/<endpoint id>/run?format=JSONEachRow",
{
method: "POST",
headers: {
Authorization: "Basic <base64_encoded_credentials>",
"Content-Type": "application/json",
"x-clickhouse-endpoint-version": "2",
},
}
)
.then((response) => response.json())
.then((data) => console.log(data))
.catch((error) => console.error("Error:", error));
レスポンス:
{"database":"INFORMATION_SCHEMA","num_tables":"COLUMNS"}
{"database":"INFORMATION_SCHEMA","num_tables":"KEY_COLUMN_USAGE"}
{"database":"INFORMATION_SCHEMA","num_tables":"REFERENTIAL_CONSTRAINTS"}
クエリAPIエンドポイントSQL:
SELECT name, database FROM system.tables WHERE match(name, {tableNameRegex: String}) AND database = {database: String};
cURL:
curl -X POST 'https://console-api.clickhouse.cloud/.api/query-endpoints/<endpoint id>/run?format=JSONCompactEachRow' \
--user '<openApiKeyId:openApiKeySecret>' \
-H 'Content-Type: application/json' \
-H 'x-clickhouse-endpoint-version: 2' \
-d '{ "queryVariables": { "tableNameRegex": "query.*", "database": "system" } }'
JavaScript:
fetch(
"https://console-api.clickhouse.cloud/.api/query-endpoints/<endpoint id>/run?format=JSONCompactEachRow",
{
method: "POST",
headers: {
Authorization: "Basic <base64_encoded_credentials>",
"Content-Type": "application/json",
"x-clickhouse-endpoint-version": "2",
},
body: JSON.stringify({
queryVariables: {
tableNameRegex: "query.*",
database: "system",
},
}),
}
)
.then((response) => response.json())
.then((data) => console.log(data))
.catch((error) => console.error("Error:", error));
レスポンス:
["query_cache", "system"]
["query_log", "system"]
["query_views_log", "system"]
テーブルにデータを挿入するクエリ変数内の配列を持つリクエスト
テーブルSQL:
CREATE TABLE default.t_arr
(
`arr` Array(Array(Array(UInt32)))
)
ENGINE = MergeTree
ORDER BY tuple()
クエリAPIエンドポイントSQL:
INSERT INTO default.t_arr VALUES ({arr: Array(Array(Array(UInt32)))});
cURL:
curl -X POST 'https://console-api.clickhouse.cloud/.api/query-endpoints/<endpoint id>/run' \
--user '<openApiKeyId:openApiKeySecret>' \
-H 'Content-Type: application/json' \
-H 'x-clickhouse-endpoint-version: 2' \
-d '{
"queryVariables": {
"arr": [[[12, 13, 0, 1], [12]]]
}
}'
JavaScript:
fetch(
"https://console-api.clickhouse.cloud/.api/query-endpoints/<endpoint id>/run",
{
method: "POST",
headers: {
Authorization: "Basic <base64_encoded_credentials>",
"Content-Type": "application/json",
"x-clickhouse-endpoint-version": "2",
},
body: JSON.stringify({
queryVariables: {
arr: [[[12, 13, 0, 1], [12]]],
},
}),
}
)
.then((response) => response.json())
.then((data) => console.log(data))
.catch((error) => console.error("Error:", error));
レスポンス:
max_threadsを8に設定したClickHouse設定でのリクエスト
クエリAPIエンドポイントSQL:
SELECT * FROM system.tables;
cURL:
curl -X POST 'https://console-api.clickhouse.cloud/.api/query-endpoints/<endpoint id>/run?max_threads=8,' \
--user '<openApiKeyId:openApiKeySecret>' \
-H 'Content-Type: application/json' \
-H 'x-clickhouse-endpoint-version: 2' \
JavaScript:
fetch(
"https://console-api.clickhouse.cloud/.api/query-endpoints/<endpoint id>/run?max_threads=8",
{
method: "POST",
headers: {
Authorization: "Basic <base64_encoded_credentials>",
"Content-Type": "application/json",
"x-clickhouse-endpoint-version": "2",
},
}
)
.then((response) => response.json())
.then((data) => console.log(data))
.catch((error) => console.error("Error:", error));
ストリームとしてレスポンスをリクエストして解析する
クエリAPIエンドポイントSQL:
SELECT name, database FROM system.tables;
Typescript:
async function fetchAndLogChunks(
url: string,
openApiKeyId: string,
openApiKeySecret: string
) {
const auth = Buffer.from(`${openApiKeyId}:${openApiKeySecret}`).toString(
"base64"
);
const headers = {
Authorization: `Basic ${auth}`,
"x-clickhouse-endpoint-version": "2",
};
const response = await fetch(url, {
headers,
method: "POST",
body: JSON.stringify({ format: "JSONEachRow" }),
});
if (!response.ok) {
console.error(`HTTP error! Status: ${response.status}`);
return;
}
const reader = response.body as unknown as Readable;
reader.on("data", (chunk) => {
console.log(chunk.toString());
});
reader.on("end", () => {
console.log("Stream ended.");
});
reader.on("error", (err) => {
console.error("Stream error:", err);
});
}
const endpointUrl =
"https://console-api.clickhouse.cloud/.api/query-endpoints/<endpoint id>/run?format=JSONEachRow";
const openApiKeyId = "<myOpenApiKeyId>";
const openApiKeySecret = "<myOpenApiKeySecret>";
// Usage example
fetchAndLogChunks(endpointUrl, openApiKeyId, openApiKeySecret).catch((err) =>
console.error(err)
);
出力
> npx tsx index.ts
> {"name":"COLUMNS","database":"INFORMATION_SCHEMA"}
> {"name":"KEY_COLUMN_USAGE","database":"INFORMATION_SCHEMA"}
...
> Stream ended.
ファイルからテーブルにストリームを挿入する
ファイル ./samples/my_first_table_2024-07-11.csv に以下の内容を作成します：
"user_id","json","name"
"1","{""name"":""John"",""age"":30}","John"
"2","{""name"":""Jane"",""age"":25}","Jane"
テーブル作成SQL:
create table default.my_first_table
(
user_id String,
json String,
name String,
) ENGINE = MergeTree()
ORDER BY user_id;
クエリAPIエンドポイントSQL:
INSERT INTO default.my_first_table
cURL:
cat ./samples/my_first_table_2024-07-11.csv | curl --user '<openApiKeyId:openApiKeySecret>' \
-X POST \
-H 'Content-Type: application/octet-stream' \
-H 'x-clickhouse-endpoint-version: 2' \
"https://console-api.clickhouse.cloud/.api/query-endpoints/<endpoint id>/run?format=CSV" \
--data-binary @-