Chat2Query API を使ってみる

TiDB Cloud は、指示を提供することで AI を使用して SQL ステートメントを生成および実行できる RESTful インターフェイスである Chat2Query API を提供します。その後、API はクエリ結果を返します。

Chat2Query API には HTTPS 経由でのみアクセスできるため、ネットワーク上で送信されるすべてのデータは TLS を使用して暗号化されます。

注記：
Chat2Query APIはTiDB サーバーレスクラスタで利用可能です。 TiDB専用クラスターで Chat2Query API を使用するには、 TiDB Cloudのサポートにお問い合わせください。

あなたが始める前に

Chat2Query API を使用する前に、TiDB クラスターを作成し、 SQLクエリを生成するAI有効にしていることを確認してください。 TiDB クラスターがない場合は、 TiDB サーバーレスクラスターを作成するまたはTiDB 専用クラスターの作成の手順に従って作成します。

ステップ 1. Chat2Query API を有効にする

Chat2Query API を有効にするには、次の手順を実行します。

プロジェクトのクラスターページに移動します。
ヒント：
複数のプロジェクトがある場合は、左下隅のをクリックして、別のプロジェクトに切り替えます。
クラスター名をクリックし、左側のナビゲーションウィンドウで[Chat2Query]をクリックします。
Chat2Query の右上隅で[...]をクリックし、 [設定]を選択します。
DataAPIを有効にすると、Chat2Query データアプリが作成されます。
注記：
1 つの TiDB クラスターで DataAPI を有効にすると、同じプロジェクト内のすべての TiDB クラスターで Chat2Query API を使用できるようになります。
メッセージ内の「Data Service」リンクをクリックして、Chat2Query API にアクセスします。
Chat2Query System データアプリとそのChat2Data 終点左側のペインに表示されていることがわかります。

ステップ 2. API キーを作成する

エンドポイントを呼び出す前に、API キーを作成する必要があります。 Chat2Query データアプリの API キーを作成するには、次の手順を実行します。

データサービスの左側のペインで、 Chat2Query システムの名前をクリックして詳細を表示します。
「認証」領域で、 「API キーの作成」をクリックします。
[API キーの作成]ダイアログボックスで、説明を入力し、API キーのロールを選択します。
このロールは、API キーがデータアプリにリンクされたクラスターに対してデータの読み取りまたは書き込みを行えるかどうかを制御するために使用されます。 ReadOnlyまたはReadAndWrite役割を選択できます。
- ReadOnly : API キーはSELECT 、 SHOW 、 USE 、 DESC 、 EXPLAINステートメントなどのデータの読み取りのみを許可します。
- ReadAndWrite : API キーによるデータの読み取りと書き込みを許可します。この API キーを使用して、DML ステートメントや DDL ステートメントなどのすべての SQL ステートメントを実行できます。
「次へ」をクリックします。公開鍵と秘密鍵が表示されます。
秘密キーをコピーして安全な場所に保存したことを確認してください。このページを離れると、完全な秘密キーを再度取得することはできなくなります。
「完了」をクリックします。

ステップ 3. Chat2Data エンドポイントを呼び出す

データサービスページの左側のペインで、 [Chat2Query] > [/chat2data]をクリックしてエンドポイントの詳細を表示します。 Chat2Data のプロパティが表示されます。

エンドポイントパス: (読み取り専用) Chat2Data エンドポイントのパス/chat2data 。
エンドポイント URL : (読み取り専用) Chat2Data エンドポイントの URL。エンドポイントを呼び出すために使用されます。たとえば、 https://<region>.data.tidbcloud.com/api/v1beta/app/chat2query-<ID>/endpoint/chat2data 。
Request Method : (読み取り専用) Chat2Data エンドポイントの HTTP メソッドPOST 。
Timeout(ms) : Chat2Data エンドポイントのタイムアウト (ミリ秒単位)。
Max Rows : Chat2Data エンドポイントが返す最大行数。

TiDB Cloudは、エンドポイントの呼び出しに役立つコードサンプルを生成します。例を取得してコードを実行するには、次の手順を実行します。

現在のChat2Dataページで、 [エンドポイント URL]の右側にある[コード例]をクリックします。 [コード例]ダイアログボックスが表示されます。
ダイアログボックスで、エンドポイントの呼び出しに使用するクラスターとデータベースを選択し、コード例をコピーします。
コード例をアプリケーションに貼り付けて実行します。
- <Public Key>と<Private Key>プレースホルダーを API キーに置き換えます。
- <your instruction>プレースホルダーを、AI に SQL ステートメントを生成して実行させる命令に置き換えます。
- <your table name, optional>プレースホルダーを、クエリするテーブル名に置き換えます。テーブル名を指定しない場合、AI はデータベース内のすべてのテーブルをクエリします。

注記：
各 Chat2Query データアプリには、1 日あたり 100 リクエストのレート制限があります。レート制限を超えると、API は429エラーを返します。さらに割り当てが必要な場合は、サポートチームにリクエストを送信するお問い合わせください。

次のコード例は、 sample_data.github_eventsテーブルから最も人気のある GitHub リポジトリを検索するために使用されます。

curl --digest --user '<Public Key>:<Private Key>' \
  --request POST 'https://<region>.data.tidbcloud.com/api/v1beta/app/chat2query-<ID>/endpoint/chat2data' \
  --header 'content-type: application/json' \
  --data-raw '{
      "cluster_id": "12345678912345678960",
      "database": "sample_data",
      "tables": ["github_events"],
      "instruction": "Find the most popular repo from GitHub events"
      }'

前述の例では、リクエスト本文は次のプロパティを持つ JSON オブジェクトです。

cluster_id :文字列。 TiDB クラスターの一意の識別子。
database :文字列。データベースの名前。
tables :配列。 (オプション) クエリ対象のテーブル名のリスト。
instruction :文字列。必要なクエリを説明する自然言語命令。

応答は次のとおりです。

{
    "type": "chat2data_endpoint",
    "data": {
        "columns": [
            {
                "col": "repo_name",
                "data_type": "VARCHAR",
                "nullable": false
            },
            {
                "col": "count",
                "data_type": "BIGINT",
                "nullable": false
            }
        ],
        "rows": [
            {
                "count": "2390",
                "repo_name": "pytorch/pytorch"
            }
        ],
        "result": {
            "code": 200,
            "message": "Query OK!",
            "start_ms": 1678965476709,
            "end_ms": 1678965476839,
            "latency": "130ms",
            "row_count": 1,
            "row_affect": 0,
            "limit": 50,
            "sql": "SELECT sample_data.github_events.`repo_name`, COUNT(*) AS count FROM sample_data.github_events GROUP BY sample_data.github_events.`repo_name` ORDER BY count DESC LIMIT 1;",
            "ai_latency": "30ms"
        }
    }

API 呼び出しが成功しなかった場合は、 200以外のステータスコードが返されます。以下は500ステータスコードの例です。

{
    "type": "chat2data_endpoint",
    "data": {
        "columns": [],
        "rows": [],
        "result": {
            "code": 500,
            "message": "internal error! defaultPermissionHelper: rpc error: code = DeadlineExceeded desc = context deadline exceeded",
            "start_ms": "",
            "end_ms": "",
            "latency": "",
            "row_count": 0,
            "row_affect": 0,
            "limit": 0
        }
    }
}

Chat2Query API を使ってみる

あなたが始める前に

ステップ 1. Chat2Query API を有効にする

ステップ 2. API キーを作成する

ステップ 3. Chat2Data エンドポイントを呼び出す

もっと詳しく知る

このページは役に立ちましたか？