クエリ API エンドポイント

Beta feature. Learn more.

クエリ 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 Endpoint を選択することで設定できます。どの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 （任意）：応答のフォーマット。Query 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"}

クエリ変数を使用したリクエストおよびJSONCompactEachRowフォーマットのバージョン2

クエリ 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));

応答:

OK

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 @-