メインコンテンツまでスキップ
メインコンテンツまでスキップ

クエリ API エンドポイント

クエリ API エンドポイント 機能は、ClickHouse Cloud コンソール内の保存された SQL クエリから直接 API エンドポイントを作成することを可能にします。ネイティブドライバを介して ClickHouse Cloud サービスに接続することなく、HTTP 経由で API エンドポイントにアクセスして、保存されたクエリを実行できるようになります。

クイックスタートガイド​

続行する前に、API キーと管理コンソールの役割を持っていることを確認してください。このガイドに従って API キーを作成できます。

保存されたクエリの作成​

保存されたクエリがある場合は、この手順をスキップできます。

新しいクエリタブを開いてください。デモのために、約 45 億件のレコードを含む youtube データセット を使用します。例のクエリとして、ユーザー入力パラメータ year による平均動画閲覧数で上位 10 のアップローダーを返します:

このクエリには、パラメータ (year) が含まれていることに注意してください。SQL コンソールクエリエディタは ClickHouse のクエリパラメータ式を自動的に検出し、各パラメータの入力を提供します。このクエリが正常に動作するか確認するために、すぐに実行してみましょう:

例のクエリをテスト

次のステップでは、クエリを保存します:

例のクエリを保存

保存されたクエリに関する詳細なドキュメントは こちら で見つかります。

クエリ API エンドポイントの設定​

クエリ API エンドポイントは、クエリビューから 共有 ボタンをクリックし、API エンドポイント を選択することで設定できます。どの API キーがエンドポイントにアクセスできるか指定するよう求められます:

クエリエンドポイントの設定

API キーを選択すると、クエリ API エンドポイントが自動的にプロビジョニングされます。テストリクエストを送信できるように例の curl コマンドが表示されます:

エンドポイント curl コマンド

クエリ API パラメータ​

クエリ内のクエリパラメータは、{parameter_name: type} の構文で指定できます。これらのパラメータは自動的に検出され、例のリクエストペイロードにはこれらのパラメータを渡すための queryVariables オブジェクトが含まれます。

テストとモニタリング​

クエリ API エンドポイントが作成されると、curl または他の HTTP クライアントを使用して動作確認を行えます:

エンドポイント curl テスト

最初のリクエストを送信した後、共有 ボタンのすぐ右側に新しいボタンが表示されます。これをクリックすると、クエリに関するモニタリングデータを含むフライアウトが開きます:

エンドポイントモニタリング

実装詳細​

説明​

このルートは、指定されたクエリエンドポイントでクエリを実行します。異なるバージョン、フォーマット、およびクエリ変数をサポートします。レスポンスはストリーム (バージョン 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:

レスポンス:

クエリ変数を使用したリクエストおよび JSONCompactEachRow 形式のバージョン 2​

クエリ 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: