Chat2Query APIを使い始める

TiDB Cloudは、RESTfulインターフェースであるChat2Query APIを提供しています。このAPIを使用すると、AIが指示を与えるだけでSQL文を生成・実行できます。そして、APIがクエリ結果を返します。

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

注記：

Chat2Query APIはAWSでホストされているTiDB Cloudスタータークラスターでのみ利用可能です。3 TiDB Cloud専用クラスターでChat2Query APIをご利用いただくには、 TiDB Cloudサポートお問い合わせください。

始める前に

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

Chat2Queryデータアプリを作成する

プロジェクトのデータ アプリを作成するには、次の手順を実行します。

1. プロジェクトのデータサービスページで、左ペインで「データアプリを作成」をクリックします。データアプリ作成ダイアログが表示されます。

   ヒント：

   クラスターのSQL エディターページが表示されている場合は、右上隅の... をクリックし、 API 経由で Chat2Query にアクセスして、新しい Chat2Query データ アプリをクリックすることで、データ アプリ作成ダイアログを開くこともできます。

2. ダイアログで、データアプリの名前を定義し、データソースとして必要なクラスターを選択し、データアプリの種類として「Chat2Query データアプリ」を選択します。必要に応じて、アプリの説明を記入することもできます。

3. [作成]をクリックします。

   新しく作成されたChat2Queryデータアプリが左側のペインに表示されます。このデータアプリの下に、Chat2Queryエンドポイントのリストが表示されます。

APIキーを作成する

エンドポイントを呼び出す前に、エンドポイントがTiDB Cloudクラスターのデータにアクセスするために使用する Chat2Query データ アプリの API キーを作成する必要があります。

API キーを作成するには、次の手順を実行します。

1. データサービスの左側のペインで、Chat2Query データ アプリをクリックすると、右側にその詳細が表示されます。

2. 認証領域で、 「API キーの作成」をクリックします。

3. 「API キーの作成」ダイアログで説明を入力し、API キーの次のいずれかのロールを選択します。

   • Chat2Query Admin : API キーがデータ サマリーを管理し、提供された指示に基づいて SQL ステートメントを生成し、任意の SQL ステートメントを実行できるようにします。

   • Chat2Query Data Summary Management Role : API キーによるデータ サマリーの生成と更新のみを許可します。

     ヒント：

     Chat2Query APIの場合、データサマリーとは、AIによるデータベースの分析結果であり、データベースの説明、テーブルの説明、列の説明などが含まれます。データベースのデータサマリーを生成することで、SQL文を生成する際に、指示を与えることでより正確なレスポンスを得ることができます。

   • Chat2Query SQL ReadOnly : API キーは提供された指示に基づいて SQL ステートメントを生成し、 SELECT SQL ステートメントを実行することのみを許可します。

   • Chat2Query SQL ReadWrite : API キーが提供された指示に基づいて SQL ステートメントを生成し、任意の SQL ステートメントを実行することを許可します。

4. デフォルトでは、APIキーに有効期限はありません。キーの有効期限を設定する場合は、 「有効期限Daysをクリックし、時間単位（ Minutes 、またはMonths ）を選択して、希望する数値を入力してください。

5. 「次へ」をクリックします。公開鍵と秘密鍵が表示されます。

   秘密鍵をコピーして安全な場所に保存してください。このページを離れると、完全な秘密鍵を再度取得することはできません。

6. 「完了」をクリックします。

Chat2Queryエンドポイントを呼び出す

注記：

Chat2Queryデータアプリには、1日あたり100リクエストのレート制限があります。レート制限を超えた場合、APIは429エラーを返します。クォータを増やすには、サポートチームまでリクエストを送信するください。

各 Chat2Query データ アプリには、次のエンドポイントがあります。

• Chat2Query v3エンドポイント: /v3/dataSummariesや/v3/chat2dataなど、名前が/v3で始まるエンドポイント(推奨)
• Chat2Query v2エンドポイント: /v2/dataSummariesや/v2/chat2dataなど、名前が/v2で始まるエンドポイント
• Chat2Query v1 エンドポイント: /v1/chat2data (非推奨)

ヒント：

/v1/chat2dataと比較すると、 /v3/chat2dataと/v2/chat2dataでは、まず/v3/dataSummariesまたは/v2/dataSummariesを呼び出してデータベースを分析する必要があります。そのため、 /v3/chat2dataと/v2/chat2dataによって返される結果は、一般的により正確です。

エンドポイントのコード例を取得する

TiDB Cloudは、Chat2Queryエンドポイントを素早く呼び出すためのコードサンプルを提供しています。Chat2Queryエンドポイントのコードサンプルを取得するには、以下の手順を実行してください。

1. データサービスページの左側のペインで、Chat2Query エンドポイントの名前をクリックします。

   エンドポイント URL、コード例、リクエスト メソッドなど、このエンドポイントを呼び出すための情報が右側に表示されます。

2. [コード例を表示]をクリックします。

3. 表示されたダイアログ ボックスで、エンドポイントの呼び出しに使用するクラスター、データベース、および認証方法を選択し、コード例をコピーします。

   注記：

   /v2/jobs/{job_id}などの一部のエンドポイントでは、認証方法を選択するだけで済みます。

4. エンドポイントを呼び出すには、アプリケーションに例を貼り付け、例のパラメータを独自のものに置き換えて (プレースホルダー${PUBLIC_KEY}と${PRIVATE_KEY} API キーに置き換えるなど)、実行します。

Chat2Query v3エンドポイントまたはv2エンドポイントを呼び出す

TiDB Cloudデータ サービスは、次の Chat2Query v3 エンドポイントと v2 エンドポイントを提供します。

/v3/chat2dataと/v2/chat2data呼び出す手順は同じです。以下のセクションでは、 /v3/chat2data例に挙げてその呼び出し方法を説明します。

1. /v3/dataSummariesを呼び出してデータサマリーを生成する

/v3/chat2data呼び出す前に、まず/v3/dataSummaries呼び出して AI にデータベースを分析してデータの概要を生成させます。そうすることで、後で/v3/chat2data SQL 生成でより優れたパフォーマンスを得ることができます。

以下は、 /v3/dataSummariesを呼び出してsp500insightデータベースを分析し、データベースのデータ概要を生成するコード例です。

curl --digest --user ${PUBLIC_KEY}:${PRIVATE_KEY} --request POST 'https://<region>.data.tidbcloud.com/api/v1beta/app/chat2query-<ID>/endpoint/v3/dataSummaries'\
 --header 'content-type: application/json'\
 --data-raw '{
    "cluster_id": "10140100115280519574",
    "database": "sp500insight",
    "description": "Data summary for SP500 Insight",
    "reuse": false
}'

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

• cluster_id :文字列。TiDBクラスタの一意の識別子。
• database :文字列。データベースの名前。
• description :文字列。データ概要の説明。
• reuse :ブール値。既存のデータサマリーを再利用するかどうかを指定しますtrueに設定すると、APIは既存のデータサマリーを再利用します。6 false設定すると、APIは新しいデータサマリーを生成します。

応答の例は次のとおりです。

{
  "code": 200,
  "msg": "",
  "result": {
    "data_summary_id": 304823,
    "job_id": "fb99ef785da640ab87bf69afed60903d"
  }
}

2. /v2/jobs/{job_id}を呼び出して分析ステータスを確認します。

/v3/dataSummaries APIは非同期です。大規模なデータセットを持つデータベースの場合、データベース分析を完了して完全なデータサマリーを返すまでに数分かかる場合があります。

データベースの分析ステータスを確認するには、次のように/v2/jobs/{job_id}エンドポイントを呼び出します。

curl --digest --user ${PUBLIC_KEY}:${PRIVATE_KEY} --request GET 'https://<region>.data.dev.tidbcloud.com/api/v1beta/app/chat2query-<ID>`/endpoint/v2/jobs/{job_id}'\
 --header 'content-type: application/json'

応答の例は次のとおりです。

{
  "code": 200,
  "msg": "",
  "result": {
    "ended_at": 1699518950, // A UNIX timestamp indicating when the job is finished
    "job_id": "fb99ef785da640ab87bf69afed60903d", // ID of current job
    "result": DataSummaryObject, // AI exploration information of the given database
    "status": "done" // Status of the current job
  }
}

"status"が"done"場合、完全なデータサマリーが準備完了しており、 /v3/chat2data呼び出すことでこのデータベースに対してSQL文を生成して実行できます。それ以外の場合は、完了するまで待って、後で分析ステータスを確認する必要があります。

レスポンスのDataSummaryObject 、指定されたデータベースのAI探索情報を表します。3の構造はDataSummaryObjectのとおりです。

{
    "cluster_id": "10140100115280519574", // The cluster ID
    "data_summary_id": 304823, // The data summary ID
    "database": "sp500insight", // The database name
    "default": false, // Whether this data summary is the default one
    "status": "done", // The status of the data summary
    "description": {
        "system": "Data source for financial analysis and decision-making in stock market", // The description of the data summary generated by AI
        "user": "Data summary for SP500 Insight" // The description of the data summary provided by the user
    },
    "keywords": ["User_Stock_Selection", "Index_Composition"], // Keywords of the data summary
    "relationships": {
        "companies": {
            "referencing_table": "...", // The table that references the `companies` table
            "referencing_table_column": "..." // The column that references the `companies` table
            "referenced_table": "...", // The table that the `companies` table references
            "referenced_table_column": "..." // The column that the `companies` table references
        }
    }, // Relationships between tables
    "summary": "Financial data source for stock market analysis", // The summary of the data summary
    "tables": { // Tables in the database
      "companies": {
        "name": "companies" // The table name
        "description": "This table provides comprehensive...", // The description of the table
        "columns": {
          "city": { // Columns in the table
            "name": "city" // The column name
            "description": "The city where the company is headquartered.", // The description of the column
          }
        },
      },
    }
}

3. /v3/chat2dataを呼び出してSQL文を生成し実行する

データベースのデータ概要が準備できたら、クラスター ID、データベース名、質問を指定して/v3/chat2data呼び出して SQL ステートメントを生成および実行できます。

例えば：

curl --digest --user ${PUBLIC_KEY}:${PRIVATE_KEY} --request POST 'https://<region>.data.tidbcloud.com/api/v1beta/app/chat2query-<ID>/endpoint/v3/chat2data'\
 --header 'content-type: application/json'\
 --data-raw '{
    "cluster_id": "10140100115280519574",
    "database": "sp500insight",
    "question": "<Your question to generate data>",
    "sql_generate_mode": "direct"
}'

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

• cluster_id :文字列。TiDBクラスタの一意の識別子。
• database :文字列。データベースの名前。
• data_summary_id :整数。SQL生成に使用されるデータサマリーのID。このプロパティは、 cluster_idとdatabase指定されていない場合にのみ有効になります。8とcluster_id database両方を指定した場合、APIはデータベースのデフォルトのデータサマリーを使用します。
• question :文字列。必要なクエリを説明する自然言語での質問。
• sql_generate_mode :文字列。SQL文を生成するモード。値はdirectまたはauto_breakdownです。 directに設定すると、APIは指定されたquestion SQL文に基づいて直接SQL文を生成します。 auto_breakdownに設定すると、APIはquestion SQL文を複数のタスクに分割し、各タスクごとにSQL文を生成します。

応答の例は次のとおりです。

{
  "code": 200,
  "msg": "",
  "result": {
    "cluster_id": "10140100115280519574",
    "database": "sp500insight",
    "job_id": "20f7577088154d7889964f1a5b12cb26",
    "session_id": 304832
  }
}

次のようにステータス コード400の応答を受信した場合は、データ サマリーが準備されるまでしばらく待つ必要があることを意味します。

{
    "code": 400,
    "msg": "Data summary is not ready, please wait for a while and retry",
    "result": {}
}

/v3/chat2data APIは非同期です。3 /v2/jobs/{job_id}ポイントを呼び出すことでジョブのステータスを確認できます。

curl --digest --user ${PUBLIC_KEY}:${PRIVATE_KEY} --request GET 'https://<region>.data.dev.tidbcloud.com/api/v1beta/app/chat2query-<ID>/endpoint/v2/jobs/{job_id}'\
 --header 'content-type: application/json'

応答の例は次のとおりです。

{
  "code": 200,
  "msg": "",
  "result": {
    "ended_at": 1718785006, // A UNIX timestamp indicating when the job is finished
    "job_id": "20f7577088154d7889964f1a5b12cb26",
    "reason": "", // The reason for the job failure if the job fails
    "result": {
      "assumptions": [],
      "chart_options": { // The generated chart options for the result
        "chart_name": "Table",
        "option": {
          "columns": [
            "total_users"
          ]
        },
        "title": "Total Number of Users in the Database"
      },
      "clarified_task": "Count the total number of users in the database.", // The clarified description of the task
      "data": { // The data returned by the SQL statement
        "columns": [
          {
            "col": "total_users"
          }
        ],
        "rows": [
          [
            "1"
          ]
        ]
      },
      "description": "",
      "sql": "SELECT COUNT(`user_id`) AS total_users FROM `users`;", // The generated SQL statement
      "sql_error": null, // The error message of the SQL statement
      "status": "done", // The status of the job
      "task_id": "0",
      "type": "data_retrieval" // The type of the job
    },
    "status": "done"
  }
}

Chat2Data v1エンドポイントを呼び出す（非推奨）

注記：

Chat2Data v1エンドポイントは非推奨です。代わりにChat2Data v3エンドポイントを呼び出すことをお勧めします。

TiDB Cloudデータ サービスは、次の Chat2Query v1 エンドポイントを提供します。

/v1/chat2dataエンドポイントを直接呼び出して、SQL文を生成・実行できます。3 と比較すると、 /v2/chat2data /v1/chat2dataレスポンスが速くなりますが、パフォーマンスは低くなります。

TiDB Cloudは、エンドポイントの呼び出しを支援するためのコードサンプルを生成します。サンプルコードを入手して実行するには、 エンドポイントのコード例を取得する参照してください。

/v1/chat2data呼び出すときは、次のパラメータを置き換える必要があります。

• プレースホルダー${PUBLIC_KEY}と${PRIVATE_KEY} API キーに置き換えます。
• <your table name, optional>プレースホルダーをクエリ対象のテーブル名に置き換えます。テーブル名を指定しない場合、AI はデータベース内のすべてのテーブルをクエリします。
• <your instruction>プレースホルダーを、AI に SQL ステートメントを生成して実行してほしい命令に置き換えます。

注記：

• Chat2Queryデータアプリには、1日あたり100リクエストのレート制限があります。レート制限を超えた場合、APIは429エラーを返します。クォータを増やすには、サポートチームまでリクエストを送信するください。
• ロールChat2Query Data Summary Management RoleのAPIキーではChat2Data v1エンドポイントを呼び出すことができません。以下のコード例は、テーブルsp500insight.usersに含まれるユーザー数をカウントするために使用されます。

curl --digest --user ${PUBLIC_KEY}:${PRIVATE_KEY} --request POST 'https://<region>.data.dev.tidbcloud.com/api/v1beta/app/chat2query-<ID>/endpoint/chat2data'\
 --header 'content-type: application/json'\
 --data-raw '{
    "cluster_id": "10939961583884005252",
    "database": "sp500insight",
    "tables": ["users"],
    "instruction": "count the users"
}'

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

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

応答は次のとおりです。

{
  "type": "chat2data_endpoint",
  "data": {
    "columns": [
      {
        "col": "COUNT(`user_id`)",
        "data_type": "BIGINT",
        "nullable": false
      }
    ],
    "rows": [
      {
        "COUNT(`user_id`)": "1"
      }
    ],
    "result": {
      "code": 200,
      "message": "Query OK!",
      "start_ms": 1699529488292,
      "end_ms": 1699529491901,
      "latency": "3.609656403s",
      "row_count": 1,
      "row_affect": 0,
      "limit": 1000,
      "sql": "SELECT COUNT(`user_id`) FROM `users`;",
      "ai_latency": "3.054822491s"
    }
  }
}

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

もっと詳しく知る

• APIキーを管理する
• マルチラウンドChat2Queryを開始する
• ナレッジベースを使用する
• データサービスの応答コードとステータスコード