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

クエリ API エンドポイント

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

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

続行する前に、API キーと Admin Console Role を持っていることを確認してください。このガイドに従って API キーを作成する ことができます。

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

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

新しいクエリ タブを開きます。デモンストレーション用に、約 45 億件のレコードを含む youtube データセット を使用します。例として、ユーザーが入力した year パラメータに基づいて、平均ビュー数による上位 10 人のアップローダーを返します:

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

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

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

クエリ API エンドポイントの構成​

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

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

クエリ API パラメータ​

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

テストと監視​

クエリ API エンドポイントが作成されると、 curl またはその他の HTTP クライアントを使用して正常に機能するかをテストできます:

最初のリクエストを送信すると、Share ボタンのすぐ右に新しいボタンが表示されます。それをクリックすると、クエリに関する監視データを含むフライアウトが開きます:

実装の詳細​

説明​

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