From d4bc2a5ab8b44db99634a872c6e23b6f348e681a Mon Sep 17 00:00:00 2001 From: qiancai Date: Mon, 26 Oct 2026 16:29:52 +0800 Subject: [PATCH 1/5] tidb-cloud: remove retired Chat2Query documentation --- TOC-tidb-cloud-starter.md | 6 +- TOC-tidb-cloud.md | 6 +- develop/serverless-driver-drizzle-example.md | 4 +- develop/serverless-driver-kysely-example.md | 4 +- tidb-cloud/ai-feature-concepts.md | 8 +- tidb-cloud/connect-to-tidb-cluster.md | 6 +- tidb-cloud/data-service-api-key.md | 2 - tidb-cloud/data-service-app-config-files.md | 1 - tidb-cloud/data-service-concepts.md | 6 - tidb-cloud/data-service-get-started.md | 17 +- tidb-cloud/data-service-manage-data-app.md | 4 - tidb-cloud/data-service-manage-endpoint.md | 8 +- tidb-cloud/data-service-oas-with-nextjs.md | 2 +- tidb-cloud/data-service-overview.md | 7 - .../data-service-postman-integration.md | 3 +- .../data-service-response-and-status-code.md | 80 +--- tidb-cloud/explore-data-with-chat2query.md | 189 -------- tidb-cloud/explore-data-with-sql-editor.md | 101 ++++ tidb-cloud/manage-user-access.md | 8 +- tidb-cloud/releases/release-notes-2023.md | 5 +- tidb-cloud/releases/release-notes-2024.md | 4 - tidb-cloud/sql-proxy-account.md | 2 +- tidb-cloud/tidb-cloud-glossary.md | 6 - tidb-cloud/tidb-cloud-import-local-files.md | 2 +- tidb-cloud/tidb-cloud-quickstart.md | 57 +-- tidb-cloud/tidb-cloud-roadmap.md | 6 +- tidb-cloud/use-chat2query-api.md | 447 ------------------ tidb-cloud/use-chat2query-knowledge.md | 218 --------- tidb-cloud/use-chat2query-sessions.md | 101 ---- 29 files changed, 146 insertions(+), 1164 deletions(-) delete mode 100644 tidb-cloud/explore-data-with-chat2query.md create mode 100644 tidb-cloud/explore-data-with-sql-editor.md delete mode 100644 tidb-cloud/use-chat2query-api.md delete mode 100644 tidb-cloud/use-chat2query-knowledge.md delete mode 100644 tidb-cloud/use-chat2query-sessions.md diff --git a/TOC-tidb-cloud-starter.md b/TOC-tidb-cloud-starter.md index c5ebaa552b356..d79ee491eff71 100644 --- a/TOC-tidb-cloud-starter.md +++ b/TOC-tidb-cloud-starter.md @@ -135,15 +135,11 @@ - [Troubleshoot Access Denied Errors during Data Import from Amazon S3](/tidb-cloud/troubleshoot-import-access-denied-error.md) - [Connect AWS DMS to TiDB Cloud](/tidb-cloud/tidb-cloud-connect-aws-dms.md) - Explore Data - - [Chat2Query in SQL Editor](/tidb-cloud/explore-data-with-chat2query.md) ![PREVIEW](/media/tidb-cloud/blank_transparent_placeholder.png) + - [SQL Editor](/tidb-cloud/explore-data-with-sql-editor.md) - [SQL Proxy Account](/tidb-cloud/sql-proxy-account.md) - Data Service ![PREVIEW](/media/tidb-cloud/blank_transparent_placeholder.png) - [Overview](/tidb-cloud/data-service-overview.md) - [Get Started](/tidb-cloud/data-service-get-started.md) - - Chat2Query API - - [Get Started](/tidb-cloud/use-chat2query-api.md) - - [Start Multi-round Chat2Query](/tidb-cloud/use-chat2query-sessions.md) - - [Use Knowledge Bases](/tidb-cloud/use-chat2query-knowledge.md) - [Manage Data App](/tidb-cloud/data-service-manage-data-app.md) - [Manage Endpoint](/tidb-cloud/data-service-manage-endpoint.md) - [API Key](/tidb-cloud/data-service-api-key.md) diff --git a/TOC-tidb-cloud.md b/TOC-tidb-cloud.md index f998b9c9aaddd..41b202b314a85 100644 --- a/TOC-tidb-cloud.md +++ b/TOC-tidb-cloud.md @@ -171,15 +171,11 @@ - [Precheck Errors, Migration Errors, and Alerts for Data Migration](/tidb-cloud/tidb-cloud-dm-precheck-and-troubleshooting.md) - [Connect AWS DMS to TiDB Cloud](/tidb-cloud/tidb-cloud-connect-aws-dms.md) - Explore Data - - [Chat2Query in SQL Editor](/tidb-cloud/explore-data-with-chat2query.md) ![PREVIEW](/media/tidb-cloud/blank_transparent_placeholder.png) + - [SQL Editor](/tidb-cloud/explore-data-with-sql-editor.md) - [SQL Proxy Account](/tidb-cloud/sql-proxy-account.md) - Data Service ![PREVIEW](/media/tidb-cloud/blank_transparent_placeholder.png) - [Overview](/tidb-cloud/data-service-overview.md) - [Get Started](/tidb-cloud/data-service-get-started.md) - - Chat2Query API - - [Get Started](/tidb-cloud/use-chat2query-api.md) - - [Start Multi-round Chat2Query](/tidb-cloud/use-chat2query-sessions.md) - - [Use Knowledge Bases](/tidb-cloud/use-chat2query-knowledge.md) - [Manage Data App](/tidb-cloud/data-service-manage-data-app.md) - [Manage Endpoint](/tidb-cloud/data-service-manage-endpoint.md) - [API Key](/tidb-cloud/data-service-api-key.md) diff --git a/develop/serverless-driver-drizzle-example.md b/develop/serverless-driver-drizzle-example.md index 0d90faf4810ec..e63d67af75e48 100644 --- a/develop/serverless-driver-drizzle-example.md +++ b/develop/serverless-driver-drizzle-example.md @@ -98,7 +98,7 @@ To complete this tutorial, you need the following: 1. Create a table in your {{{ .starter }}} instance. - You can use [SQL Editor in the TiDB Cloud console](https://docs.pingcap.com/tidbcloud/explore-data-with-chat2query) to execute SQL statements. Here is an example: + You can use [SQL Editor in the TiDB Cloud console](https://docs.pingcap.com/tidbcloud/explore-data-with-sql-editor) to execute SQL statements. Here is an example: ```sql CREATE TABLE `test`.`users` ( @@ -208,7 +208,7 @@ To complete this tutorial, you need the following: 1. Create a table in your {{{ .starter }}} instance. - You can use [SQL Editor in the TiDB Cloud console](https://docs.pingcap.com/tidbcloud/explore-data-with-chat2query.md) to execute SQL statements. Here is an example: + You can use [SQL Editor in the TiDB Cloud console](https://docs.pingcap.com/tidbcloud/explore-data-with-sql-editor) to execute SQL statements. Here is an example: ```sql CREATE TABLE `test`.`users` ( diff --git a/develop/serverless-driver-kysely-example.md b/develop/serverless-driver-kysely-example.md index 53136ed31e5dd..1bb773a80b612 100644 --- a/develop/serverless-driver-kysely-example.md +++ b/develop/serverless-driver-kysely-example.md @@ -90,7 +90,7 @@ To complete this tutorial, you need the following: 1. Create a table in your {{{ .starter }}} instance and insert some data. - You can use [SQL Editor in the TiDB Cloud console](https://docs.pingcap.com/tidbcloud/explore-data-with-chat2query) to execute SQL statements. Here is an example: + You can use [SQL Editor in the TiDB Cloud console](https://docs.pingcap.com/tidbcloud/explore-data-with-sql-editor) to execute SQL statements. Here is an example: ```sql CREATE TABLE `test`.`person` ( @@ -202,7 +202,7 @@ mysql://[username]:[password]@[host]/[database] 1. Create a table in your {{{ .starter }}} instance and insert some data. - You can use [SQL Editor in the TiDB Cloud console](https://docs.pingcap.com/tidbcloud/explore-data-with-chat2query) to execute SQL statements. Here is an example: + You can use [SQL Editor in the TiDB Cloud console](https://docs.pingcap.com/tidbcloud/explore-data-with-sql-editor) to execute SQL statements. Here is an example: ```sql CREATE TABLE `test`.`person` ( diff --git a/tidb-cloud/ai-feature-concepts.md b/tidb-cloud/ai-feature-concepts.md index 6ac96102b6286..e6e80a6b365b1 100644 --- a/tidb-cloud/ai-feature-concepts.md +++ b/tidb-cloud/ai-feature-concepts.md @@ -5,16 +5,10 @@ summary: Learn about AI features for TiDB Cloud. # AI Features -The AI features in TiDB Cloud enable you to fully leverage advanced technologies for data exploration, search, and integration. From natural language-driven SQL query generation to high-performance vector search, TiDB combines database capabilities with modern AI features to power innovative applications. With support for popular AI frameworks, embedding models, and seamless integration with ORM libraries, TiDB offers a versatile platform for use cases such as semantic search and AI-powered analytics. +The AI features in TiDB Cloud enable you to fully leverage advanced technologies for data exploration, search, and integration. TiDB combines database capabilities with modern AI features to power innovative applications. With support for popular AI frameworks, embedding models, and seamless integration with ORM libraries, TiDB offers a versatile platform for use cases such as semantic search and AI-powered analytics. This document highlights these AI features and how they enhance the TiDB experience. -## Chat2Query (PREVIEW) - -Chat2Query is an AI-powered feature integrated into SQL Editor that assists users in generating, debugging, or rewriting SQL queries using natural language instructions. For more information, see [Explore your data with AI-assisted SQL Editor](/tidb-cloud/explore-data-with-chat2query.md). - -In addition, TiDB Cloud provides a Chat2Query API for {{{ .starter }}} instances. After it is enabled, TiDB Cloud will automatically create a system Data App called Chat2Query and a Chat2Data endpoint in Data Service. You can call this endpoint to let AI generate and execute SQL statements by providing instructions. For more information, see [Get started with Chat2Query API](/tidb-cloud/use-chat2query-api.md). - ## Vector search (PREVIEW) Vector search is a search method that prioritizes the meaning of your data to deliver relevant results. diff --git a/tidb-cloud/connect-to-tidb-cluster.md b/tidb-cloud/connect-to-tidb-cluster.md index c8fdaa8207a63..fe6675fa38c8e 100644 --- a/tidb-cloud/connect-to-tidb-cluster.md +++ b/tidb-cloud/connect-to-tidb-cluster.md @@ -36,15 +36,15 @@ After your TiDB Cloud Dedicated cluster is created on TiDB Cloud, you can connec If you want lower latency and more security, set up VPC peering and connect via a private endpoint using a VM instance on the corresponding cloud provider in your cloud account. For more information, see [Connect to TiDB Cloud Dedicated via VPC Peering](/tidb-cloud/set-up-vpc-peering-connections.md). -- [Built-in SQL Editor](/tidb-cloud/explore-data-with-chat2query.md) +- [Built-in SQL Editor](/tidb-cloud/explore-data-with-sql-editor.md) > **Note:** > > To use SQL Editor on [TiDB Cloud Dedicated](/tidb-cloud/select-cluster-tier.md#tidb-cloud-dedicated) clusters, contact [TiDB Cloud support](/tidb-cloud/tidb-cloud-support.md). - If your cluster is hosted on AWS and the TiDB version of the cluster is v6.5.0 or later, you can use the AI-assisted SQL Editor in the [TiDB Cloud console](https://tidbcloud.com/) to maximize your data value. + If your cluster is hosted on AWS and the TiDB version of the cluster is v6.5.0 or later, you can use the SQL Editor in the [TiDB Cloud console](https://tidbcloud.com/) to maximize your data value. - In SQL Editor, you can either write SQL queries manually or simply press ⌘ + I on macOS (or Control + I on Windows or Linux) to instruct [Chat2Query (PREVIEW)](/tidb-cloud/tidb-cloud-glossary.md#chat2query) to generate SQL queries automatically. This enables you to run SQL queries against databases without a local SQL client. You can intuitively view the query results in tables or charts and easily check the query logs. + In SQL Editor, you can write and run SQL queries. This enables you to run SQL queries against databases without a local SQL client. You can intuitively view the query results in tables or charts and easily check the query logs. ## What's next diff --git a/tidb-cloud/data-service-api-key.md b/tidb-cloud/data-service-api-key.md index 143d3189a8932..44c1d55170687 100644 --- a/tidb-cloud/data-service-api-key.md +++ b/tidb-cloud/data-service-api-key.md @@ -51,8 +51,6 @@ Request quotas are subject to rate limits as follows: {"type":"","data":{"columns":[],"rows":[],"result":{"latency":"","row_affect":0,"code":49900007,"row_count":0,"end_ms":0,"limit":0,"message":"API key rate limit exceeded. The limit can be increased up to 1000 requests per minute per API key in TiDB Cloud console. For an increase in quota beyond 1000 rpm, please contact us: https://tidb.support.pingcap.com/","start_ms":0}}} ``` -- TiDB Cloud Data Service allows up to 100 requests per day for each Chat2Query Data App. - ## API key expiration By default, API keys never expire. However, for security considerations, you can specify an expiration time for your API key when you [create](#create-an-api-key) or [edit](#edit-an-api-key) the key. diff --git a/tidb-cloud/data-service-app-config-files.md b/tidb-cloud/data-service-app-config-files.md index 87f7a2cba3feb..a3eb53ae423d5 100644 --- a/tidb-cloud/data-service-app-config-files.md +++ b/tidb-cloud/data-service-app-config-files.md @@ -201,7 +201,6 @@ In the SQL file, you can write statements such as table join queries, complex qu ```sql /* Getting Started: Enter "USE {database};" before entering your SQL statements. -Type "--your question" + Enter to try out AI-generated SQL queries in the TiDB Cloud console. Declare a parameter like "Where id = ${arg}". */ USE sample_data; diff --git a/tidb-cloud/data-service-concepts.md b/tidb-cloud/data-service-concepts.md index 79958ea3a3b2c..8646ddd769e1e 100644 --- a/tidb-cloud/data-service-concepts.md +++ b/tidb-cloud/data-service-concepts.md @@ -23,12 +23,6 @@ An endpoint in [Data Service (PREVIEW)](https://tidbcloud.com/project/data-servi For more information, see [Manage an Endpoint](/tidb-cloud/data-service-manage-endpoint.md). -## Chat2Query API - -In TiDB Cloud, Chat2Query API is a RESTful interface that enables you to generate and execute SQL statements using AI by providing instructions. Then, the API returns the query results for you. - -For more information, see [Get Started with Chat2Query API](/tidb-cloud/use-chat2query-api.md). - ## AI integrations Integrating third-party tools with your Data App enhances your applications with advanced natural language processing and artificial intelligence (AI) capabilities provided by third-party tools. This integration enables your applications to perform more complex tasks and deliver intelligent solutions. diff --git a/tidb-cloud/data-service-get-started.md b/tidb-cloud/data-service-get-started.md index 1b2cae8e20c2a..de00221c24df8 100644 --- a/tidb-cloud/data-service-get-started.md +++ b/tidb-cloud/data-service-get-started.md @@ -7,12 +7,6 @@ summary: Learn how to use TiDB Cloud Data Service to access your data with HTTPS Data Service (PREVIEW) enables you to access TiDB Cloud data via an HTTPS request using a custom API endpoint and allows you to seamlessly integrate with any application or service that is compatible with HTTPS. -> **Tip:** -> -> TiDB Cloud provides a Chat2Query API for {{{ .starter }}} instances. After it is enabled, TiDB Cloud will automatically create a system Data App called **Chat2Query** and a Chat2Data endpoint in Data Service. You can call this endpoint to let AI generate and execute SQL statements by providing instructions. -> -> For more information, see [Get started with Chat2Query API](/tidb-cloud/use-chat2query-api.md). - This document introduces how to quickly get started with TiDB Cloud Data Service (PREVIEW) by creating a Data App, developing, testing, deploying, and calling an endpoint. A Data App is a collection of endpoints that you can use to access data for a specific application. ## Before you begin @@ -61,10 +55,6 @@ To get started with Data Service, you can also create your own Data App, and the 3. In the **Create Data App** dialog, enter a name, a description, and select {{{ .starter }}} instances that you want the Data App to access. - > **Note:** - > - > By default, the Data App type is **Standard Data App**. If you want to create a **Chat2Query Data App**, refer to [Get Started with Chat2Query API](/tidb-cloud/use-chat2query-api.md) instead of this document. - 4. (Optional) To automatically deploy endpoints of the Data App to your preferred GitHub repository and branch, enable **Connect to GitHub**, and then do the following: 1. Click **Install on GitHub**, and then follow the on-screen instructions to install **TiDB Cloud Data Service** as an application on your target repository. @@ -116,11 +106,7 @@ You can customize SQL statements for the endpoint in the -
- ```json { "type": "sql_endpoint", @@ -70,51 +67,6 @@ An example response is as follows: } ``` -
- -
- -```json -{ - "type": "chat2data_endpoint", - "data": { - "columns": [ - { - "col": "id", - "data_type": "BIGINT", - "nullable": false - }, - { - "col": "type", - "data_type": "VARCHAR", - "nullable": false - } - ], - "rows": [ - { - "id": "20008295419", - "type": "CreateEvent" - } - ], - "result": { - "code": 200, - "message": "Query OK!", - "start_ms": 1678965476709, - "end_ms": 1678965476839, - "latency": "130ms", - "row_count": 1, - "row_affect": 0, - "limit": 50 - "sql": "select id,type from sample_data.github_events limit 1;", - "ai_latency": "30ms" - } - } -} -``` - -
- - ## Status code ### 200 @@ -279,9 +231,6 @@ This status code indicates that the request exceeds the rate limit of the API ke An example response is as follows: - -
- ```json { "type": "", @@ -302,33 +251,6 @@ An example response is as follows: } ``` -
- -
- -```json -{ - "type": "chat2data_endpoint", - "data": { - "columns": [], - "rows": [], - "result": { - "code": 429, - "message": "The AI request exceeded the limit of 100 times per day. For more quota, please contact us: https://tidb.support.pingcap.com/", - "start_ms": "", - "end_ms": "", - "latency": "", - "row_count": 0, - "row_affect": 0, - "limit": 0 - } - } -} -``` - -
- - ### 500 This status code indicates that the request met an internal error. There might be various causes for this error. diff --git a/tidb-cloud/explore-data-with-chat2query.md b/tidb-cloud/explore-data-with-chat2query.md deleted file mode 100644 index 4677d92fc09aa..0000000000000 --- a/tidb-cloud/explore-data-with-chat2query.md +++ /dev/null @@ -1,189 +0,0 @@ ---- -title: Explore Your Data with AI-Assisted SQL Editor -summary: Learn how to use AI-assisted SQL Editor in the TiDB Cloud console, to maximize your data value. ---- - -# Explore Your Data with AI-Assisted SQL Editor - -You can use the built-in AI-assisted SQL Editor in the [TiDB Cloud console](https://tidbcloud.com/) to maximize your data value. - -In SQL Editor, you can either write SQL queries manually or simply press ⌘ + I on macOS (or Control + I on Windows or Linux) to instruct [Chat2Query (PREVIEW)](/tidb-cloud/tidb-cloud-glossary.md#chat2query) to generate SQL queries automatically. This enables you to run SQL queries against databases without a local SQL client. You can intuitively view the query results in tables or charts and easily check the query logs. - -## Use cases - -The recommended use cases of SQL Editor are as follows: - -- Utilize the AI capabilities of Chat2Query to generate, debug, or rewrite complex SQL queries instantly. -- Quickly test the MySQL compatibility of TiDB. -- Easily explore the SQL features in TiDB using your own datasets. - -## Limitations - -- SQL queries generated by the AI might not be 100% accurate, and you might need to refine them. -- SQL Editor is available only for [{{{ .starter }}}](/tidb-cloud/select-cluster-tier.md#starter) instances hosted on AWS. To use SQL Editor and Chat2Query on [TiDB Cloud Dedicated](/tidb-cloud/select-cluster-tier.md#tidb-cloud-dedicated) clusters, contact [TiDB Cloud support](/tidb-cloud/tidb-cloud-support.md). - -## Access SQL Editor - -1. Go to the [**My TiDB**](https://tidbcloud.com/tidbs) page. - - > **Tip:** - > - > If you are in multiple organizations, use the combo box in the upper-left corner to switch to your target organization first. - -2. Click the name of your {{{ .starter }}} instance or TiDB Cloud Dedicated cluster, and then click **SQL Editor** in the left navigation pane. - - > **Note:** - > - > In the following cases, the **SQL Editor** entry is displayed in gray and not clickable. - > - > - Your TiDB Cloud Dedicated cluster is earlier than v6.5.0. To use SQL Editor, you need to contract [TiDB Cloud support](/tidb-cloud/tidb-cloud-support.md) to upgrade your clusters. - > - Your TiDB Cloud Dedicated cluster is just created and the running environment for SQL Editor is still in preparation. In this case, wait for a few minutes and Chat2Query will be available. - > - Your TiDB Cloud Dedicated cluster is [paused](/tidb-cloud/pause-or-resume-tidb-cluster.md). - -## Enable or disable AI to generate SQL queries - -PingCAP takes the privacy and security of users' data as a top priority. The AI capacity of Chat2Query in SQL Editor only needs to access database schemas to generate SQL queries, not your data itself. For more information, see [Chat2Query Privacy FAQ](https://www.pingcap.com/privacy-policy/privacy-chat2query). - -When you access Chat2Query for the first time, you will be prompted with a dialog about whether to allow PingCAP and Amazon Bedrock to use your code snippets to research and improve the services. - -- To enable the AI to generate SQL queries, select the checkbox and click **Save and Get Started**. -- To disable the AI to generate SQL queries, close this dialog directly. - -After the first-time access, you can still change the AI setting as follows: - -- To enable AI, click **Enable AI power for data exploration** in the upper-right corner of Chat2Query. -- To disable AI, click in the lower-left corner of the [TiDB Cloud console](https://tidbcloud.com/), click **Account Settings**, click the **AI & Privacy** tab, and then disable the **AI-powered Data Exploration** option. - -## Write and run SQL queries - -In SQL Editor, you can write and run SQL queries using your own dataset. - -1. Write SQL queries. - - -
- - For macOS: - - - If AI is enabled, simply press **⌘ + I** followed by your instructions and press **Enter** to let AI generate SQL queries automatically. - - For a SQL query generated by Chat2Query, click **Accept** to accept the query and continue editing. If the query does not meet your requirements, click **Discard** to reject it. Alternatively, click **Regenerate** to request a new query from Chat2Query. - - - If AI is disabled, write SQL queries manually. - -
- -
- - For Windows or Linux: - - - If AI is enabled, simply press **Ctrl + I** followed by your instructions and press **Enter** to let AI generate SQL queries automatically. - - For a SQL query generated by Chat2Query, click **Accept** to accept the query and continue editing. If the query does not meet your requirements, click **Discard** to reject it. Alternatively, click **Regenerate** to request a new query from Chat2Query. - - - If AI is disabled, write SQL queries manually. - -
- - -2. Run SQL queries. - - -
- - For macOS: - - - If you have only one query in the editor, to run it, press **⌘ + Enter** or click **Run**. - - - If you have multiple queries in the editor, to run one or several of them sequentially, select the lines of the target queries with your cursor, and then press **⌘ + Enter** or click **Run**. - - - To run all queries in the editor sequentially, press **⇧ + ⌘ + Enter**, or select the lines of all queries with your cursor and click **Run**. - -
- -
- - For Windows or Linux: - - - If you have only one query in the editor, to run it, press **Ctrl + Enter** or click **Run**. - - - If you have multiple queries in the editor, to run one or several of them sequentially, select the lines of the target queries with your cursor, and then press **Ctrl + Enter** or click **Run**. - - - To run all queries in the editor sequentially, press **Shift + Ctrl + Enter**, or select the lines of all queries with your cursor and click **Run**. - -
- - -After running the queries, you can see the query logs and results immediately at the bottom of the page. - -> **Note:** -> -> The returned result has a size limit of 8 MiB. - -## Rewrite SQL queries using Chat2Query - -In SQL Editor, you can use Chat2Query to rewrite existing SQL queries to optimize performance, fix errors, or meet other specific requirements. - -1. Select the lines of SQL queries you want to rewrite with your cursor. - -2. Invoke Chat2Query for rewriting by using the keyboard shortcut for your operating system: - - - ⌘ + I on macOS - - Control + I on Windows or Linux - - Press **Enter** after providing your instructions to let AI handle the rewrite. - -3. After invoking Chat2Query, you can see the suggested rewrite and the following options: - - - **Accept**: click this to accept the suggested rewrite and continue editing. - - **Discard**: click this if the suggested rewrite does not meet your expectations. - - **Regenerate**: click this to request another rewrite from Chat2Query based on your feedback or additional instructions. - -> **Note:** -> -> Chat2Query uses AI algorithms to suggest optimizations and corrections. It is recommended that you review these suggestions carefully before finalizing the queries. - -## Manage SQL files - -In SQL Editor, you can save your SQL queries in different SQL files and manage SQL files as follows: - -- To add a SQL file, click **+** on the **SQL Files** tab. -- To rename a SQL file, move your cursor on the filename, click **...** next to the filename, and then select **Rename**. -- To delete a SQL file, move your cursor on the filename, click **...** next to the filename, and then select **Delete**. Note that when there is only one SQL file on the **SQL Files** tab, you cannot delete it. - -## Access Chat2Query via API - -In addition to accessing Chat2Query via UI, you can also access Chat2Query via API. To do so, you need to create a Chat2Query Data App first. - -In Chat2Query, you can access or create a Chat2Query Data App as follows: - -1. Click **...** in the upper-right corner, and then click **Access Chat2Query via API**. -2. In the displayed dialog, do one of the following: - - - To create a new Chat2Query Data App, click **New Chat2Query Data App**. - - To access an existing Chat2Query Data App, click the name of target Data App. - -For more information, see [Get started with Chat2Query API](/tidb-cloud/use-chat2query-api.md). - -## Generate an endpoint from a SQL file - -TiDB Cloud provides a [Data Service (PREVIEW)](/tidb-cloud/data-service-overview.md) feature that enables you to access TiDB Cloud data via an HTTPS request using a custom API endpoint. In SQL Editor, you can generate an endpoint of Data Service (PREVIEW) from a SQL file by taking the following steps: - -1. Move your cursor on the filename, click **...** next to the filename, and then select **Generate endpoint**. -2. In the **Generate endpoint** dialog box, select the Data App you want to generate the endpoint for and enter the endpoint name. -3. Click **Generate**. The endpoint is generated and its details page is displayed. - -For more information, see [Manage an endpoint](/tidb-cloud/data-service-manage-endpoint.md). - -## Manage SQL Editor settings - -In SQL Editor, you can change the following settings: - -- The maximum number of rows in query results -- Whether to show system database schemas on the **Schemas** tab - -To change the settings, take the following steps: - -1. In the upper-right corner of **SQL Editor**, click **...** and select **Settings**. -2. Change the settings according to your need. -3. Click **Save**. diff --git a/tidb-cloud/explore-data-with-sql-editor.md b/tidb-cloud/explore-data-with-sql-editor.md new file mode 100644 index 0000000000000..57a18a0887593 --- /dev/null +++ b/tidb-cloud/explore-data-with-sql-editor.md @@ -0,0 +1,101 @@ +--- +title: Explore Your Data with SQL Editor +summary: Learn how to use SQL Editor in the TiDB Cloud console to write and run SQL queries, manage SQL files, and view query results. +aliases: ['/tidbcloud/explore-data-with-chat2query', '/tidbcloud/use-chat2query-api', '/tidbcloud/use-chat2query-knowledge', '/tidbcloud/use-chat2query-sessions'] +--- + +# Explore Your Data with SQL Editor + +You can use the built-in SQL Editor in the [TiDB Cloud console](https://tidbcloud.com/) to maximize your data value. + +In SQL Editor, you can write and run SQL queries against databases without a local SQL client. You can intuitively view the query results in tables or charts and easily check the query logs. + +## Use cases + +The recommended use cases of SQL Editor are as follows: + +- Quickly test the MySQL compatibility of TiDB. +- Easily explore the SQL features in TiDB using your own datasets. + +## Limitations + +- SQL Editor is available only for [{{{ .starter }}}](/tidb-cloud/select-cluster-tier.md#starter) instances hosted on AWS. To use SQL Editor on [TiDB Cloud Dedicated](/tidb-cloud/select-cluster-tier.md#tidb-cloud-dedicated) clusters, contact [TiDB Cloud support](/tidb-cloud/tidb-cloud-support.md). + +## Access SQL Editor + +1. Go to the [**My TiDB**](https://tidbcloud.com/tidbs) page. + + > **Tip:** + > + > If you are in multiple organizations, use the combo box in the upper-left corner to switch to your target organization first. + +2. Click the name of your {{{ .starter }}} instance or TiDB Cloud Dedicated cluster, and then click **SQL Editor** in the left navigation pane. + + > **Note:** + > + > In the following cases, the **SQL Editor** entry is displayed in gray and not clickable. + > + > - Your TiDB Cloud Dedicated cluster is earlier than v6.5.0. To use SQL Editor, you need to contact [TiDB Cloud support](/tidb-cloud/tidb-cloud-support.md) to upgrade your clusters. + > - Your TiDB Cloud Dedicated cluster is just created and the running environment for SQL Editor is still in preparation. In this case, wait for a few minutes and SQL Editor will be available. + > - Your TiDB Cloud Dedicated cluster is [paused](/tidb-cloud/pause-or-resume-tidb-cluster.md). + +## Write and run SQL queries + +In SQL Editor, you can write and run SQL queries using your own dataset. + +1. Write SQL queries. + +2. Run SQL queries. + + +
+ + For macOS: + + - If you have only one query in the editor, to run it, press **⌘ + Enter** or click **Run**. + + - If you have multiple queries in the editor, to run one or several of them sequentially, select the lines of the target queries with your cursor, and then press **⌘ + Enter** or click **Run**. + + - To run all queries in the editor sequentially, press **⇧ + ⌘ + Enter**, or select the lines of all queries with your cursor and click **Run**. + +
+ +
+ + For Windows or Linux: + + - If you have only one query in the editor, to run it, press **Ctrl + Enter** or click **Run**. + + - If you have multiple queries in the editor, to run one or several of them sequentially, select the lines of the target queries with your cursor, and then press **Ctrl + Enter** or click **Run**. + + - To run all queries in the editor sequentially, press **Shift + Ctrl + Enter**, or select the lines of all queries with your cursor and click **Run**. + +
+ + +After running the queries, you can see the query logs and results immediately at the bottom of the page. + +> **Note:** +> +> The returned result has a size limit of 8 MiB. + +## Manage SQL files + +In SQL Editor, you can save your SQL queries in different SQL files and manage SQL files as follows: + +- To add a SQL file, click **+** on the **SQL Files** tab. +- To rename a SQL file, move your cursor on the filename, click **...** next to the filename, and then select **Rename**. +- To delete a SQL file, move your cursor on the filename, click **...** next to the filename, and then select **Delete**. Note that when there is only one SQL file on the **SQL Files** tab, you cannot delete it. + +## Manage SQL Editor settings + +In SQL Editor, you can change the following settings: + +- The maximum number of rows in query results +- Whether to show system database schemas on the **Schemas** tab + +To change the settings, take the following steps: + +1. In the upper-right corner of **SQL Editor**, click **...** and select **Settings**. +2. Change the settings according to your need. +3. Click **Save**. diff --git a/tidb-cloud/manage-user-access.md b/tidb-cloud/manage-user-access.md index 39600992abcc2..df5bf2a6ebf01 100644 --- a/tidb-cloud/manage-user-access.md +++ b/tidb-cloud/manage-user-access.md @@ -141,8 +141,8 @@ At the project level, TiDB Cloud defines four roles, in which `Project Owner` ca | Restore an instance or cluster from a backup as a new resource. | ✅ | ❌ | ❌ | ❌ | | Manage [Data Service](/tidb-cloud/data-service-overview.md) for data read-only operations such as using or creating endpoints to read data. | ✅ | ✅ | ✅ | ❌ | | Manage [Data Service](/tidb-cloud/data-service-overview.md) for data read and write operations. | ✅ | ✅ | ❌ | ❌ | -| View resource data using [SQL Editor](/tidb-cloud/explore-data-with-chat2query.md), if supported by the resource type. | ✅ | ✅ | ✅ | ❌ | -| Modify and delete resource data using [SQL Editor](/tidb-cloud/explore-data-with-chat2query.md), if supported by the resource type. | ✅ | ✅ | ❌ | ❌ | +| View resource data using [SQL Editor](/tidb-cloud/explore-data-with-sql-editor.md), if supported by the resource type. | ✅ | ✅ | ✅ | ❌ | +| Modify and delete resource data using [SQL Editor](/tidb-cloud/explore-data-with-sql-editor.md), if supported by the resource type. | ✅ | ✅ | ❌ | ❌ | | Manage [changefeeds](/tidb-cloud/changefeed-overview.md). | ✅ | ✅ | ✅ | ❌ | | Review and reset resource passwords, if supported by the resource type. | ✅ | ❌ | ❌ | ❌ | | View resource overview, backup records, metrics, events, and [changefeeds](/tidb-cloud/changefeed-overview.md) in the project. | ✅ | ✅ | ✅ | ✅ | @@ -161,8 +161,8 @@ TiDB X instances support instance-level roles so that you can grant access to a | Permission | `Instance Manager` | `TiDB X Instance Data Access Read-Write` | `TiDB X Instance Data Access Read-Only` | `TiDB X Instance Viewer` | |---|---|---|---|---| | Manage instance operations, such as instance creation, modification, and deletion. | ✅ | ❌ | ❌ | ❌ | -| View and modify instance data using [SQL Editor](/tidb-cloud/explore-data-with-chat2query.md). | ✅ | ✅ | ❌ | ❌ | -| View instance data using [SQL Editor](/tidb-cloud/explore-data-with-chat2query.md). | ✅ | ✅ | ✅ | ❌ | +| View and modify instance data using [SQL Editor](/tidb-cloud/explore-data-with-sql-editor.md). | ✅ | ✅ | ❌ | ❌ | +| View instance data using [SQL Editor](/tidb-cloud/explore-data-with-sql-editor.md). | ✅ | ✅ | ✅ | ❌ | | Manage instance-scoped roles. | ✅ | ❌ | ❌ | ❌ | | View backup records of the TiDB X instance. | ✅ | ❌ | ❌ | ✅ | | Restore the TiDB X instance from backups. | ✅ | ❌ | ❌ | ❌ | diff --git a/tidb-cloud/releases/release-notes-2023.md b/tidb-cloud/releases/release-notes-2023.md index 44a12144b68cf..bd9e7a3820a23 100644 --- a/tidb-cloud/releases/release-notes-2023.md +++ b/tidb-cloud/releases/release-notes-2023.md @@ -758,13 +758,12 @@ This page lists the release notes of [TiDB Cloud](https://www.pingcap.com/tidb-c - Integrate TiDB Cloud with data visualization projects by using Data Service as a data source. - Connect to your database from an environment that MySQL interface does not support. - In addition, TiDB Cloud provides the [Chat2Query API](/tidb-cloud/use-chat2query-api.md), a RESTful interface that allows you to generate and execute SQL statements using AI. + In addition, TiDB Cloud provides the Chat2Query API, a RESTful interface that allows you to generate and execute SQL statements using AI. To access Data Service, navigate to the [**Data Service**](https://tidbcloud.com/project/data-service) page in the left navigation pane. For more information, see the following documentation: - [Data Service Overview](/tidb-cloud/data-service-overview.md) - [Get Started with Data Service](/tidb-cloud/data-service-get-started.md) - - [Get Started with Chat2Query API](/tidb-cloud/use-chat2query-api.md) - Support decreasing the size of TiDB, TiKV, and TiFlash nodes to scale in a [Dedicated Tier](/tidb-cloud/select-cluster-tier.md#tidb-cloud-dedicated) cluster that is hosted on AWS and created after December 31, 2022. @@ -948,7 +947,7 @@ This page lists the release notes of [TiDB Cloud](https://www.pingcap.com/tidb-c - To upload a CSV file, now you can simply drag and drop it to the upload area on the **Import** page. - When creating an import task, if your target database or table does not exist, you can enter a name to let TiDB Cloud create it for you automatically. For the target table to be created, you can specify a primary key or select multiple fields to form a composite primary key. - - After the import is completed, you can explore your data with [AI-powered Chat2Query](/tidb-cloud/explore-data-with-chat2query.md) by clicking **Explore your data by Chat2Query** or clicking the target table name in the task list. + - After the import is completed, you can explore your data with AI-powered Chat2Query by clicking **Explore your data by Chat2Query** or clicking the target table name in the task list. For more information, see [Import local files to TiDB Cloud](/tidb-cloud/tidb-cloud-import-local-files.md). diff --git a/tidb-cloud/releases/release-notes-2024.md b/tidb-cloud/releases/release-notes-2024.md index 9944339ea421c..0638af956fbad 100644 --- a/tidb-cloud/releases/release-notes-2024.md +++ b/tidb-cloud/releases/release-notes-2024.md @@ -257,8 +257,6 @@ This page lists the release notes of [TiDB Cloud](https://www.pingcap.com/tidb-c With Chat2Query API v3 endpoints, you can start multi-round Chat2Query by using sessions. - For more information, see [Get started with Chat2Query API](/tidb-cloud/use-chat2query-api.md). - **Console changes** - Rename Chat2Query (beta) to SQL Editor (beta). @@ -268,8 +266,6 @@ This page lists the release notes of [TiDB Cloud](https://www.pingcap.com/tidb-c - **SQL Editor**: the default interface for manually writing and executing SQL queries in the TiDB Cloud console. - **Chat2Query**: the AI-assisted text-to-query feature, which enables you to interact with your databases using natural language to generate, rewrite, and optimize SQL queries. - For more information, see [Explore your data with AI-assisted SQL Editor](/tidb-cloud/explore-data-with-chat2query.md). - ## June 18, 2024 **General changes** diff --git a/tidb-cloud/sql-proxy-account.md b/tidb-cloud/sql-proxy-account.md index 052c80e91a865..7adaa9b952717 100644 --- a/tidb-cloud/sql-proxy-account.md +++ b/tidb-cloud/sql-proxy-account.md @@ -5,7 +5,7 @@ summary: Learn about the SQL proxy account in TiDB Cloud. # SQL Proxy Account -A SQL proxy account is a SQL user account that is automatically created by TiDB Cloud to access the database via [SQL Editor](/tidb-cloud/explore-data-with-chat2query.md) or [Data Service](https://docs.pingcap.com/tidbcloud/api/v1beta1/dataservice) on behalf of a TiDB Cloud user. For example, `testuser@pingcap.com` is a TiDB Cloud user account, while `3jhEcSimm7keKP8.testuser._41mqK6H4` is its corresponding SQL proxy account. +A SQL proxy account is a SQL user account that is automatically created by TiDB Cloud to access the database via [SQL Editor](/tidb-cloud/explore-data-with-sql-editor.md) or [Data Service](https://docs.pingcap.com/tidbcloud/api/v1beta1/dataservice) on behalf of a TiDB Cloud user. For example, `testuser@pingcap.com` is a TiDB Cloud user account, while `3jhEcSimm7keKP8.testuser._41mqK6H4` is its corresponding SQL proxy account. SQL proxy accounts provide a secure, token-based authentication mechanism for accessing the database in TiDB Cloud. By eliminating the need for traditional username and password credentials, SQL proxy accounts enhance security and simplify access management. diff --git a/tidb-cloud/tidb-cloud-glossary.md b/tidb-cloud/tidb-cloud-glossary.md index 318f4f5bbb3d4..6abfaf9b15b10 100644 --- a/tidb-cloud/tidb-cloud-glossary.md +++ b/tidb-cloud/tidb-cloud-glossary.md @@ -23,12 +23,6 @@ ACID refers to the four key properties of a transaction: atomicity, consistency, ## C -### Chat2Query - -Chat2Query is an AI-powered feature integrated into SQL Editor that assists users in generating, debugging, or rewriting SQL queries using natural language instructions. For more information, see [Explore your data with AI-assisted SQL Editor](/tidb-cloud/explore-data-with-chat2query.md). - -In addition, TiDB Cloud provides a Chat2Query API for {{{ .starter }}} instances hosted on AWS. After it is enabled, TiDB Cloud will automatically create a system Data App called **Chat2Query** and a Chat2Data endpoint in Data Service. You can call this endpoint to let AI generate and execute SQL statements by providing instructions. For more information, see [Get started with Chat2Query API](/tidb-cloud/use-chat2query-api.md). - ### Cluster In TiDB Cloud, a cluster is a dedicated cloud deployment that includes explicit infrastructure details such as node topology, instance types, storage configuration, and scaling model. diff --git a/tidb-cloud/tidb-cloud-import-local-files.md b/tidb-cloud/tidb-cloud-import-local-files.md index 705d622515a0c..1ee3c5c12a18f 100644 --- a/tidb-cloud/tidb-cloud-import-local-files.md +++ b/tidb-cloud/tidb-cloud-import-local-files.md @@ -77,7 +77,7 @@ Currently, this method supports importing one CSV file for one task into either You can view the import progress on the **Import Task Detail** page. If there are warnings or failed tasks, you can check to view the details and solve them. -9. After the import task is completed, you can click **Explore your data by SQL Editor** to query your imported data. For more information about how to use SQL Editor, see [Explore your data with AI-assisted SQL Editor](/tidb-cloud/explore-data-with-chat2query.md). +9. After the import task is completed, you can click **Explore your data by SQL Editor** to query your imported data. For more information about how to use SQL Editor, see [Explore your data with SQL Editor](/tidb-cloud/explore-data-with-sql-editor.md). 10. On the **Import** page, you can click **...** > **View** in the **Action** column to check the import task detail. diff --git a/tidb-cloud/tidb-cloud-quickstart.md b/tidb-cloud/tidb-cloud-quickstart.md index 81d3203e5e5dc..aab278024bc7c 100644 --- a/tidb-cloud/tidb-cloud-quickstart.md +++ b/tidb-cloud/tidb-cloud-quickstart.md @@ -26,7 +26,7 @@ Additionally, you can try out TiDB features on [TiDB Playground](https://play.ti 3. For new sign-up users, TiDB Cloud automatically creates a default {{{ .starter }}} instance named `Instance0` for you. - - To instantly try out TiDB Cloud features with this default {{{ .starter }}} instance, proceed to [Step 2: Try AI-assisted SQL Editor](#step-2-try-ai-assisted-sql-editor). + - To instantly try out TiDB Cloud features with this default {{{ .starter }}} instance, proceed to [Step 2: Try SQL Editor](#step-2-try-sql-editor). - To create a new {{{ .starter }}} instance on your own, follow these steps: 1. Click **Create Resource**. @@ -50,25 +50,33 @@ Additionally, you can try out TiDB features on [TiDB Playground](https://play.ti -## Step 2: Try AI-assisted SQL Editor +## Step 2: Try SQL Editor -For {{{ .starter }}} instances hosted on AWS, you can use the built-in AI-assisted SQL Editor in the TiDB Cloud console to maximize your data value. This enables you to run SQL queries against databases without a local SQL client. You can intuitively view the query results in tables or charts and easily check the query logs. +For {{{ .starter }}} instances hosted on AWS, you can use the built-in SQL Editor in the TiDB Cloud console to maximize your data value. This enables you to run SQL queries against databases without a local SQL client. You can intuitively view the query results in tables or charts and easily check the query logs. 1. On the [**My TiDB**](https://tidbcloud.com/tidbs) page, click the name of your {{{ .starter }}} instance to go to its overview page, and then click **SQL Editor** in the left navigation pane. -2. To try the AI capacity of TiDB Cloud, follow the on-screen instructions to allow PingCAP and AWS Bedrock to use your code snippets for research and service improvement, and then click **Save and Get Started**. +2. Write SQL queries in SQL Editor. -3. In SQL Editor, press ⌘ + I on macOS (or Control + I on Windows or Linux) to instruct [Chat2Query (PREVIEW)](/tidb-cloud/tidb-cloud-glossary.md#chat2query) to generate SQL queries automatically. + For example, you can run the following SQL statements to create a table, insert data, and query the data: - For example, to create a new table `test.t` with two columns (column `id` and column `name`), you can type `use test;` to specify the database, press ⌘ + I, type `create a new table t with id and name` as the instruction, and then press **Enter** to let AI generate a SQL statement accordingly. + ```sql + USE test; - For the generated statement, you can accept it by clicking **Accept** and then further edit it if needed, or reject it by clicking **Discard**. + -- create a new table t with id and name + CREATE TABLE `t` (`id` INT, `name` VARCHAR(255)); - > **Note:** - > - > SQL queries generated by AI are not 100% accurate and might still require further tweaking. + -- add 3 rows + INSERT INTO `t` (`id`, `name`) VALUES + (1, 'row1'), + (2, 'row2'), + (3, 'row3'); -4. Run the SQL queries. + -- query all + SELECT `id`, `name` FROM `t`; + ``` + +3. Run the SQL queries.
@@ -98,31 +106,6 @@ For {{{ .starter }}} instances hosted on AWS, you can use the built-in AI-assist After running the queries, you can immediately see the query logs and results at the bottom of the page. -To let AI generate more SQL statements, you can type more instructions as shown in the following example: - -```sql -use test; - --- create a new table t with id and name -CREATE TABLE - `t` (`id` INT, `name` VARCHAR(255)); - --- add 3 rows -INSERT INTO - `t` (`id`, `name`) -VALUES - (1, 'row1'), - (2, 'row2'), - (3, 'row3'); - --- query all -SELECT - `id`, - `name` -FROM - `t`; -``` - ## Step 3: Try guided tour on the console TiDB Cloud offers an interactive tutorial with carefully crafted sample datasets to help you quickly get started with TiDB Cloud. For {{{ .starter }}} instances hosted on AWS, you can try this tutorial to learn how to use TiDB Cloud for high-performance data analytics. @@ -147,7 +130,7 @@ The MySQL CLI client opens and connects to your {{{ .starter }}} instance. ## What's next - To learn how to connect to your {{{ .starter }}} instance using different methods, see [Connect to a {{{ .starter }}} or Essential instance](/tidb-cloud/connect-to-tidb-cluster-serverless.md). -- For more information about how to use SQL Editor and Chat2Query to explore your data, see [Explore your data with AI-assisted SQL Editor](/tidb-cloud/explore-data-with-chat2query.md). +- For more information about how to use SQL Editor to explore your data, see [Explore your data with SQL Editor](/tidb-cloud/explore-data-with-sql-editor.md). - For TiDB SQL usage, see [Explore SQL with TiDB](/basic-sql-operations.md). - For production use with the benefits of cross-zone high availability, horizontal scaling, and [HTAP](https://en.wikipedia.org/wiki/Hybrid_transactional/analytical_processing), see [Create a TiDB Cloud Dedicated cluster](/tidb-cloud/create-tidb-cluster.md). - To manage your instance using the TiDB Cloud CLI, see [TiDB Cloud CLI Reference (PREVIEW)](/tidb-cloud/cli-reference.md). diff --git a/tidb-cloud/tidb-cloud-roadmap.md b/tidb-cloud/tidb-cloud-roadmap.md index 2f7fe4142c689..f4b84b5b2d34a 100644 --- a/tidb-cloud/tidb-cloud-roadmap.md +++ b/tidb-cloud/tidb-cloud-roadmap.md @@ -29,14 +29,10 @@ The TiDB Cloud roadmap brings you what's coming in the near future, so you can s - Developer experience + Developer experience ✅ Load sample datasets manually. Support loading sample datasets into a cluster. You can use this data to quickly get started with testing the features of TiDB Cloud. - - ✅ Add Chat2Query (an AI-powered SQL editor). - In Chat2Query, you can either let AI generate SQL queries automatically or write SQL queries manually, and run SQL queries against databases without a terminal. - ✅ Support Data Service. With Data Service (PREVIEW), you can read or write TiDB Cloud data via an HTTPS request using a custom API endpoint. diff --git a/tidb-cloud/use-chat2query-api.md b/tidb-cloud/use-chat2query-api.md deleted file mode 100644 index 15b946b9ae90e..0000000000000 --- a/tidb-cloud/use-chat2query-api.md +++ /dev/null @@ -1,447 +0,0 @@ ---- -title: Get Started with Chat2Query API -summary: Learn how to use TiDB Cloud Chat2Query API to generate and execute SQL statements using AI by providing instructions. ---- - -# Get Started with Chat2Query API - -TiDB Cloud provides the Chat2Query API, a RESTful interface that enables you to generate and execute SQL statements using AI by providing instructions. Then, the API returns the query results for you. - -Chat2Query API can only be accessed through HTTPS, ensuring that all data transmitted over the network is encrypted using TLS. - -> **Note:** -> -> Chat2Query API is only available for [TiDB Cloud Starter](/tidb-cloud/select-cluster-tier.md#starter) instances hosted on AWS. To use the Chat2Query API on [TiDB Cloud Dedicated](/tidb-cloud/select-cluster-tier.md#tidb-cloud-dedicated) clusters, contact [TiDB Cloud support](/tidb-cloud/tidb-cloud-support.md). - -## Before you begin - -Before calling Chat2Query endpoints, you need to create a Chat2Query Data App and create an API key for the Data App. - -### Create a Chat2Query Data App - -To create a Data App for your project, perform the following steps: - -1. On the [**Data Service**](https://tidbcloud.com/project/data-service) page of your project, click **Create DataApp** in the left pane. The data app creation dialog is displayed. - - > **Tip:** - > - > If you are on the **SQL Editor** page of your {{{ .starter }}} instance, you can also open the data app creation dialog by clicking **...** in the upper-right corner, choosing **Access Chat2Query via API**, and clicking **New Chat2Query Data App**. - -2. In the dialog, define a name for your Data App, choose the desired clusters as the data sources, and select **Chat2Query Data App** as the **Data App** type. Optionally, you can also write a description for the App. - -3. Click **Create**. - - The newly created Chat2Query Data App is displayed in the left pane. Under this Data App, you can find a list of Chat2Query endpoints. - -### Create an API key - -Before calling an endpoint, you need to create an API key for the Chat2Query Data App, which is used by the endpoint to access data in your TiDB Cloud clusters. - -To create an API key, perform the following steps: - -1. In the left pane of [**Data Service**](https://tidbcloud.com/project/data-service), click your Chat2Query Data App to view its details on the right side. -2. In the **Authentication** area, click **Create API Key**. -3. In the **Create API Key** dialog, enter a description, and then select one of the following roles for your API key: - - - `Chat2Query Admin`: allows the API key to manage data summaries, generate SQL statements based on provided instructions, and execute any SQL statements. - - `Chat2Query Data Summary Management Role`: only allows the API key to generate and update data summaries. - - > **Tip:** - > - > For Chat2Query API, a data summary is an analysis result of your database by AI, including your database descriptions, table descriptions, and column descriptions. By generating a data summary of your database, you can get a more accurate response when generating SQL statements by providing instructions. - - - `Chat2Query SQL ReadOnly`: only allows the API key to generate SQL statements based on provided instructions and execute `SELECT` SQL statements. - - `Chat2Query SQL ReadWrite`: allows the API key to generate SQL statements based on provided instructions and execute any SQL statements. - -4. By default, an API key never expires. If you prefer to set an expiration time for the key, click **Expires in**, select a time unit (`Minutes`, `Days`, or `Months`), and then fill in a desired number for the time unit. - -5. Click **Next**. The public key and private key are displayed. - - Make sure that you have copied and saved the private key in a secure location. After leaving this page, you will not be able to get the full private key again. - -6. Click **Done**. - -## Call Chat2Query endpoints - -> **Note:** -> -> Each Chat2Query Data App has a rate limit of 100 requests per day. If you exceed the rate limit, the API returns a `429` error. For more quota, you can [submit a request](https://tidb.support.pingcap.com/) to our support team. - -In each Chat2Query Data App, you can find the following endpoints: - -- Chat2Query v3 endpoints: the endpoints whose names starting with `/v3`, such as `/v3/dataSummaries` and `/v3/chat2data`(recommended) -- Chat2Query v2 endpoints: the endpoints whose names starting with `/v2`, such as `/v2/dataSummaries` and `/v2/chat2data` -- Chat2Query v1 endpoint: `/v1/chat2data`(deprecated) - -> **Tip:** -> -> Compared with `/v1/chat2data`, `/v3/chat2data` and `/v2/chat2data` requires you to analyze your database first by calling `/v3/dataSummaries` or `/v2/dataSummaries`. Consequently, the results returned by `/v3/chat2data` and `/v2/chat2data` are generally more accurate. - -### Get the code example of an endpoint - -TiDB Cloud provides code examples to help you quickly call Chat2Query endpoints. To get the code example of a Chat2Query endpoint, perform the following steps: - -1. In the left pane of the [**Data Service**](https://tidbcloud.com/project/data-service) page, click the name of a Chat2Query endpoint. - - The information for calling this endpoint is displayed on the right side, such as endpoint URL, code example, and request method. - -2. Click **Show Code Example**. - -3. In the displayed dialog box, select the cluster, database, and authentication method that you want to use to call the endpoint, and then copy the code example. - - > **Note:** - > - > For some of the endpoints such as `/v2/jobs/{job_id}`, you only need to select the authentication method. - -4. To call the endpoint, you can paste the example in your application, replace the parameters in the example with your own (such as replacing the `${PUBLIC_KEY}` and `${PRIVATE_KEY}` placeholders with your API key), and then run it. - -### Call Chat2Query v3 endpoints or v2 endpoints - -TiDB Cloud Data Service provides the following Chat2Query v3 endpoints and v2 endpoints: - -| Method | Endpoint | Description | -| ------ | -------- | ----------- | -| POST | `/v3/dataSummaries` | This endpoint generates a data summary for your database schema, table schema, and column schema by using artificial intelligence for analysis. | -| GET | `/v3/dataSummaries` | This endpoint retrieves all data summaries of your database. | -| GET | `/v3/dataSummaries/{data_summary_id}` | This endpoint retrieves a specific data summary. | -| PUT | `/v3/dataSummaries/{data_summary_id}` | This endpoint updates a specific data summary. | -| PUT | `/v3/dataSummaries/{data_summary_id}/tables/{table_name}` | This endpoint updates the description of a specific table in a specific data summary. | -| PUT | `/v3/dataSummaries/{data_summary_id}/tables/{table_name}/columns` | This endpoint updates the description of columns for a specific table in a specific data summary. | -| POST | `/v3/knowledgeBases` | This endpoint creates a new knowledge base. For more information about the usage of knowledge base related endpoints, see [Use knowledge bases](/tidb-cloud/use-chat2query-knowledge.md). | -| GET | `/v3/knowledgeBases` | This endpoint retrieves all knowledge bases. | -| GET | `/v3/knowledgeBases/{knowledge_base_id}` | This endpoint retrieves a specific knowledge base. | -| PUT | `/v3/knowledgeBases/{knowledge_base_id}` | This endpoint updates a specific knowledge base. | -| POST | `/v3/knowledgeBases/{knowledge_base_id}/data` | This endpoint adds data to a specific knowledge base. | -| GET | `/v3/knowledgeBases/{knowledge_base_id}/data` | This endpoint retrieves data from a specific knowledge base. | -| PUT | `/v3/knowledgeBases/{knowledge_base_id}/data/{knowledge_data_id}` | This endpoint updates specific data in a knowledge base. | -| DEL | `/v3/knowledgeBases/{knowledge_base_id}/data/{knowledge_data_id}` | This endpoint deletes specific data from a knowledge base. | -| POST | `/v3/sessions` | This endpoint creates a new session. For more information about the usage of session-related endpoints, see [Start multi-round Chat2Query](/tidb-cloud/use-chat2query-sessions.md). | -| GET | `/v3/sessions` | This endpoint retrieves a list of all sessions. | -| GET | `/v3/sessions/{session_id}` | This endpoint retrieves the details of a specific session. | -| PUT | `/v3/sessions/{session_id}` | This endpoint updates a specific session. | -| PUT | `/v3/sessions/{session_id}/reset` | This endpoint resets a specific session. | -| POST | `/v3/sessions/{session_id}/chat2data` | This endpoint generates and executes SQL statements within a specific session using artificial intelligence. For more information, see [Start multi-round Chat2Query by using sessions](/tidb-cloud/use-chat2query-sessions.md). | -| POST | `/v3/chat2data` | This endpoint enables you to generate and execute SQL statements using artificial intelligence by providing the data summary ID and instructions. | -| POST | `/v3/refineSql` | This endpoint refines existing SQL queries using artificial intelligence. | -| POST | `/v3/suggestQuestions` | This endpoint suggests questions based on the provided data summary. | -| POST | `/v2/dataSummaries` | This endpoint generates a data summary for your database schema, table schema, and column schema using artificial intelligence. | -| GET | `/v2/dataSummaries` | This endpoint retrieves all data summaries. | -| POST | `/v2/chat2data` | This endpoint enables you to generate and execute SQL statements using artificial intelligence by providing the data summary ID and instructions. | -| GET | `/v2/jobs/{job_id}` | This endpoint enables you to query the status of a specific data summary generation job. | - -The steps to call `/v3/chat2data` and `/v2/chat2data` are the same. The following sections take `/v3/chat2data` as an example to show how to call it. - -#### 1. Generate a data summary by calling `/v3/dataSummaries` - -Before calling `/v3/chat2data`, let AI analyze the database and generate a data summary first by calling `/v3/dataSummaries`, so `/v3/chat2data` can get a better performance in SQL generation later. - -The following is a code example of calling `/v3/dataSummaries` to analyze the `sp500insight` database and generate a data summary for the database: - -```bash -curl --digest --user ${PUBLIC_KEY}:${PRIVATE_KEY} --request POST 'https://.data.tidbcloud.com/api/v1beta/app/chat2query-/endpoint/v3/dataSummaries'\ - --header 'content-type: application/json'\ - --data-raw '{ - "cluster_id": "10140100115280519574", - "database": "sp500insight", - "description": "Data summary for SP500 Insight", - "reuse": false -}' -``` - -In the preceding example, the request body is a JSON object with the following properties: - -- `cluster_id`: _string_. A unique identifier of the {{{ .starter }}} instance. -- `database`: _string_. The name of the database. -- `description`: _string_. A description of the data summary. -- `reuse`: _boolean_. Specifies whether to reuse an existing data summary. If you set it to `true`, the API will reuse an existing data summary. If you set it to `false`, the API will generate a new data summary. - -An example response is as follows: - -```js -{ - "code": 200, - "msg": "", - "result": { - "data_summary_id": 304823, - "job_id": "fb99ef785da640ab87bf69afed60903d" - } -} -``` - -#### 2. Check the analysis status by calling `/v2/jobs/{job_id}` - -The `/v3/dataSummaries` API is asynchronous. For a database with a large dataset, it might take a few minutes to complete the database analysis and return the full data summary. - -To check the analysis status of your database, you can call the `/v2/jobs/{job_id}` endpoint as follows: - -```bash -curl --digest --user ${PUBLIC_KEY}:${PRIVATE_KEY} --request GET 'https://.data.dev.tidbcloud.com/api/v1beta/app/chat2query-`/endpoint/v2/jobs/{job_id}'\ - --header 'content-type: application/json' -``` - -An example response is as follows: - -```js -{ - "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 - } -} -``` - -If `"status"` is `"done"`, the full data summary is ready and you can now generate and execute SQL statements for this database by calling `/v3/chat2data`. Otherwise, you need to wait and check the analysis status later until it is done. - -In the response, `DataSummaryObject` represents AI exploration information of the given database. The structure of `DataSummaryObject` is as follows: - -```js -{ - "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. Generate and execute SQL statements by calling `/v3/chat2data` - -When the data summary of a database is ready, you can call `/v3/chat2data` to generate and execute SQL statements by providing the cluster ID, database name, and your question. - -For example: - -```bash -curl --digest --user ${PUBLIC_KEY}:${PRIVATE_KEY} --request POST 'https://.data.tidbcloud.com/api/v1beta/app/chat2query-/endpoint/v3/chat2data'\ - --header 'content-type: application/json'\ - --data-raw '{ - "cluster_id": "10140100115280519574", - "database": "sp500insight", - "question": "", - "sql_generate_mode": "direct" -}' -``` - -The request body is a JSON object with the following properties: - -- `cluster_id`: _string_. A unique identifier of the {{{ .starter }}} instance. -- `database`: _string_. The name of the database. -- `data_summary_id`: _integer_. The ID of the data summary used to generate SQL. This property only takes effect if `cluster_id` and `database` are not provided. If you specify both `cluster_id` and `database`, the API uses the default data summary of the database. -- `question`: _string_. A question in natural language describing the query you want. -- `sql_generate_mode`: _string_. The mode to generate SQL statements. The value can be `direct` or `auto_breakdown`. If you set it to `direct`, the API will generate SQL statements directly based on the `question` you provided. If you set it to `auto_breakdown`, the API will break down the `question` into multiple tasks and generate SQL statements for each task. - -An example response is as follows: - -```js -{ - "code": 200, - "msg": "", - "result": { - "cluster_id": "10140100115280519574", - "database": "sp500insight", - "job_id": "20f7577088154d7889964f1a5b12cb26", - "session_id": 304832 - } -} -``` - -If you receive a response with the status code `400` as follows, it means that you need to wait a moment for the data summary to be ready. - -```js -{ - "code": 400, - "msg": "Data summary is not ready, please wait for a while and retry", - "result": {} -} -``` - -The `/v3/chat2data` API is asynchronous. You can check the job status by calling the `/v2/jobs/{job_id}` endpoint: - -```bash -curl --digest --user ${PUBLIC_KEY}:${PRIVATE_KEY} --request GET 'https://.data.dev.tidbcloud.com/api/v1beta/app/chat2query-/endpoint/v2/jobs/{job_id}'\ - --header 'content-type: application/json' -``` - -An example response is as follows: - -```js -{ - "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" - } -} -``` - -### Call the Chat2Data v1 endpoint (deprecated) - -> **Note:** -> -> The Chat2Data v1 endpoint is deprecated. It is recommended that you call Chat2Data v3 endpoints instead. - -TiDB Cloud Data Service provides the following Chat2Query v1 endpoint: - -| Method | Endpoint| Description | -| ---- | ---- |---- | -| POST | `/v1/chat2data` | This endpoint allows you to generate and execute SQL statements using artificial intelligence by providing the target database name and instructions. | - -You can call the `/v1/chat2data` endpoint directly to generate and execute SQL statements. Compared with `/v2/chat2data`, `/v1/chat2data` provides a faster response but lower performance. - -TiDB Cloud generates code examples to help you call an endpoint. To get the examples and run the code, see [Get the code example of an endpoint](#get-the-code-example-of-an-endpoint). - -When calling `/v1/chat2data`, you need to replace the following parameters: - -- Replace the `${PUBLIC_KEY}` and `${PRIVATE_KEY}` placeholders with your API key. -- Replace the `` placeholder with the table name you want to query. If you do not specify a table name, AI will query all tables in the database. -- Replace the `` placeholder with the instruction you want AI to generate and execute SQL statements. - -> **Note:** -> -> - Each Chat2Query Data App has a rate limit of 100 requests per day. If you exceed the rate limit, the API returns a `429` error. For more quota, you can [submit a request](https://tidb.support.pingcap.com/) to our support team. -> - An API Key with the role `Chat2Query Data Summary Management Role` cannot call the Chat2Data v1 endpoint. -The following code example is used to count how many users are in the `sp500insight.users` table: - -```bash -curl --digest --user ${PUBLIC_KEY}:${PRIVATE_KEY} --request POST 'https://.data.dev.tidbcloud.com/api/v1beta/app/chat2query-/endpoint/chat2data'\ - --header 'content-type: application/json'\ - --data-raw '{ - "cluster_id": "10939961583884005252", - "database": "sp500insight", - "tables": ["users"], - "instruction": "count the users" -}' -``` - -In the preceding example, the request body is a JSON object with the following properties: - -- `cluster_id`: _string_. A unique identifier of the {{{ .starter }}} instance. -- `database`: _string_. The name of the database. -- `tables`: _array_. (optional) A list of table names to be queried. -- `instruction`: _string_. An instruction in natural language describing the query you want. - -The response is as follows: - -```json -{ - "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" - } - } -} -``` - -If your API call is not successful, you will receive a status code other than `200`. The following is an example of the `500` status code: - -```json -{ - "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 - } - } -} -``` - -## Learn more - -- [Manage an API key](/tidb-cloud/data-service-api-key.md) -- [Start Multi-round Chat2Query](/tidb-cloud/use-chat2query-sessions.md) -- [Use Knowledge Bases](/tidb-cloud/use-chat2query-knowledge.md) -- [Response and Status Codes of Data Service](/tidb-cloud/data-service-response-and-status-code.md) diff --git a/tidb-cloud/use-chat2query-knowledge.md b/tidb-cloud/use-chat2query-knowledge.md deleted file mode 100644 index 1e8760a1d39b1..0000000000000 --- a/tidb-cloud/use-chat2query-knowledge.md +++ /dev/null @@ -1,218 +0,0 @@ ---- -title: Use Knowledge Bases -summary: Learn how to improve your Chat2Query results by using Chat2Query knowledge base APIs. ---- - -# Use Knowledge Bases - -A knowledge base is a collection of structured data that can be used to enhance the SQL generation capabilities of Chat2Query. - -Starting from v3, the Chat2Query API enables you to add or modify knowledge bases by calling knowledge base related endpoints of your Chat2Query Data App. - -> **Note:** -> -> Knowledge base related endpoints are only available for [{{{ .starter }}}](/tidb-cloud/select-cluster-tier.md#starter) instances hosted on AWS. To use knowledge base related endpoints on [TiDB Cloud Dedicated](/tidb-cloud/select-cluster-tier.md#tidb-cloud-dedicated) clusters, contact [TiDB Cloud support](/tidb-cloud/tidb-cloud-support.md). - -## Before you begin - -Before creating a knowledge base for your database, make sure that you have the following: - -- A [Chat2Query Data App](/tidb-cloud/use-chat2query-api.md#create-a-chat2query-data-app) -- An [API key for the Chat2Query Data App](/tidb-cloud/use-chat2query-api.md#create-an-api-key) - -## Step 1. Create a knowledge base for the linked database - -> **Note:** -> -> The knowledge used by Chat2Query is **structured according to the database dimension**. You can connect multiple Chat2Query Data Apps to the same database, but each Chat2Query Data App can only use knowledge from a specific database it is linked to. - -In your Chat2Query Data App, you can create a knowledge base for a specific database by calling the `/v3/knowledgeBases` endpoint. After creation, you will get a `knowledge_base_id` for future knowledge management. - -The following is a general code example for calling this endpoint. - -> **Tip:** -> -> To get a specific code example for your endpoint, click the endpoint name in the left pane of your Data App, and then click **Show Code Example**. For more information, see [Get the example code of an endpoint](/tidb-cloud/use-chat2query-api.md#get-the-code-example-of-an-endpoint). - -```bash -curl --digest --user ${PUBLIC_KEY}:${PRIVATE_KEY} --request POST 'https://.data.tidbcloud.com/api/v1beta/app/chat2query-/endpoint/v3/knowledgeBases'\ - --header 'content-type: application/json'\ - --data-raw '{ - "cluster_id": "", - "database": "", - "description": "" -}' -``` - -An example response is as follows: - -```json -{ - "code":200, - "msg":"", - "result": - { - "default":true, - "description":"", - "knowledge_base_id":2 - } -} -``` - -After getting the response, record the `knowledge_base_id` value in your response for later use. - -## Step 2. Choose a knowledge type - -The knowledge base of each database can contain multiple types of knowledge. Before adding knowledge to your knowledge base, you need to choose a knowledge type that best suits your use case. - -Currently, Chat2Query knowledge bases support the following knowledge types. Each type is specifically designed for different scenarios and has a unique knowledge structure. - -- [Few-shot example](#few-shot-example) -- [Term-sheet explanation](#term-sheet-explanation) -- [Instruction](#instruction) - -### Few-shot example - -Few-shot example refers to the Q&A learning samples provided to Chat2Query, which include sample questions and their corresponding answers. These examples help Chat2Query handle new tasks more effectively. - -> **Note:** -> -> Make sure the accuracy of newly added examples, because the quality of examples affects how well Chat2Query learns. Poor examples, such as mismatched questions and answers, can degrade the performance of Chat2Query on new tasks. - -#### Knowledge structure - -Each example consists of a sample question and its corresponding answer. - -For example: - -```json -{ - "question": "How many records are in the 'test' table?", - "answer": "SELECT COUNT(*) FROM `test`;" -} -``` - -#### Use cases - -Few-Shot examples can significantly improve the performance of Chat2Query in various scenarios, including but not limited to the following: - -1. **When dealing with rare or complex questions**: if Chat2Query encounters infrequent or complex questions, adding few-shot examples can enhance its understanding and improve the accuracy of the results. - -2. **When struggling with a certain type of question**: if Chat2Query frequently makes mistakes or has difficulty with specific questions, adding few-shot examples can help improve its performance on these questions. - -### Term-sheet explanation - -Term-sheet explanation refers to a comprehensive explanation of a specific term or a group of similar terms, helping Chat2Query understand the meaning and usage of these terms. - -> **Note:** -> -> Make sure the accuracy of newly added term explanations, because the quality of explanations affects how well Chat2Query learns. Incorrect interpretations do not improve Chat2Query results but also potentially lead to adverse effects. - -#### Knowledge structure - -Each explanation includes either a single term or a list of similar terms and their detailed descriptions. - -For example: - -```json -{ - "term": ["OSS"], - "description": "OSS Insight is a powerful tool that provides online data analysis for users based on nearly 6 billion rows of GitHub event data." -} -``` - -#### Use cases - -Term-sheet explanation is primarily used to improve Chat2Query's comprehension of user queries, especially in these situations: - -- **Dealing with industry-specific terminology or acronyms**: when your query contains industry-specific terminology or acronyms that might not be universally recognized, using a term-sheet explanation can help Chat2Query understand the meaning and usage of these terms. -- **Dealing with ambiguities in user queries**: when your query contains ambiguous concepts that is confusing, using a term-sheet explanation can help Chat2Query clarify these ambiguities. -- **Dealing with terms with various meanings**: when your query contains terms that carry different meanings in various contexts, using a term-sheet explanation can assist Chat2Query in discerning the correct interpretation. - -### Instruction - -Instruction is a piece of textual command. It is used to guide or control the behavior of Chat2Query, specifically instructing it on how to generate SQL according to specific requirements or conditions. - -> **Note:** -> -> - The instruction has a length limit of 512 characters. -> - Make sure to provide as clear and specific instructions as possible to ensure that Chat2Query can understand and execute the instructions effectively. - -#### Knowledge structure - -Instruction only includes a piece of textual command. - -For example: - -```json -{ - "instruction": "If the task requires calculating the sequential growth rate, use the LAG function with the OVER clause in SQL" -} -``` - -#### Use cases - -Instruction can be used in many scenarios to guide Chat2Query to output according to your requirements, including but not limited to the following: - -- **Limiting query scope**: if you want the SQL to consider only certain tables or columns, use an instruction to specify this. -- **Guiding SQL structure**: if you have specific requirements for the SQL structure, use an instruction to guide Chat2Query. - -## Step 3. Add knowledge to the newly created knowledge base - -To add new knowledge, you can call the `/v3/knowledgeBases/{knowledge_base_id}/data` endpoint. - -### Add a few-shot example type of knowledge - -For example, if you want Chat2Query to generate SQL statements of the count of rows in a table in a specific structure, you can add a few-shot example type of knowledge by calling `/v3/knowledgeBases/{knowledge_base_id}/data` as follows: - -```bash -curl --digest --user ${PUBLIC_KEY}:${PRIVATE_KEY} --request POST 'https://.data.tidbcloud.com/api/v1beta/app/chat2query-/endpoint/v3/knowledgeBases//data'\ - --header 'content-type: application/json'\ - --data-raw '{ - "type": "few-shot", - "meta_data": {}, - "raw_data": { - "question": "How many records are in the 'test' table?", - "answer": "SELECT COUNT(*) FROM `test`;" - } -}' -``` - -In the preceding example code, `"type": "few-shot"` represents the few-shot example knowledge type. - -### Add a term-sheet explanation type of knowledge - -For example, if you want Chat2Query to comprehend the meaning of the term `OSS` using your provided explanation, you can add a term-sheet explanation type of knowledge by calling `/v3/knowledgeBases/{knowledge_base_id}/data` as follows: - -```bash -curl --digest --user ${PUBLIC_KEY}:${PRIVATE_KEY} --request POST 'https://.data.tidbcloud.com/api/v1beta/app/chat2query-/endpoint/v3/knowledgeBases//data'\ - --header 'content-type: application/json'\ - --data-raw '{ - "type": "term-sheet", - "meta_data": {}, - "raw_data": { - "term": ["OSS"], - "description": "OSS Insight is a powerful tool that provides online data analysis for users based on nearly 6 billion rows of GitHub event data." - } -}' -``` - -In the preceding example code, `"type": "term-sheet"` represents the term-sheet explanation knowledge type. - -### Add an instruction type of knowledge - -For example, if you want Chat2Query to consistently use the `LAG` function with the `OVER` clause in SQL queries when dealing with questions about sequential growth rate calculation, you can add an instruction type of knowledge by calling `/v3/knowledgeBases/{knowledge_base_id}/data` as follows: - -```bash -curl --digest --user ${PUBLIC_KEY}:${PRIVATE_KEY} --request POST 'https://.data.tidbcloud.com/api/v1beta/app/chat2query-/endpoint/v3/knowledgeBases//data'\ - --header 'content-type: application/json'\ - --data-raw '{ - "type": "instruction", - "meta_data": {}, - "raw_data": { - "instruction": "If the task requires calculating the sequential growth rate, use the LAG function with the OVER clause in SQL" - } -}' -``` - -In the preceding example code, `"type": "instruction"` represents the instruction knowledge type. \ No newline at end of file diff --git a/tidb-cloud/use-chat2query-sessions.md b/tidb-cloud/use-chat2query-sessions.md deleted file mode 100644 index 6660cde4e4426..0000000000000 --- a/tidb-cloud/use-chat2query-sessions.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: Start Multi-round Chat2Query -summary: Learn how to start multi-round chat by using Chat2Query session-related APIs. ---- - -# Start Multi-round Chat2Query - -Starting from v3, the Chat2Query API enables you to start multi-round chats by calling session related endpoints. You can use the `session_id` returned by the `/v3/chat2data` endpoint to continue your conversation in the next round. - -## Before you begin - -Before starting multi-round Chat2Query, make sure that you have the following: - -- A [Chat2Query Data App](/tidb-cloud/use-chat2query-api.md#create-a-chat2query-data-app). -- An [API key for the Chat2Query Data App](/tidb-cloud/use-chat2query-api.md#create-an-api-key). -- A [data summary for your target database](/tidb-cloud/use-chat2query-api.md#1-generate-a-data-summary-by-calling-v3datasummaries). - -## Step 1. Start a session - -To start a session, you can call the `/v3/sessions` endpoint of your Chat2Query Data App. - -The following is a general code example for calling this endpoint. - -> **Tip:** -> -> To get a specific code example for your endpoint, click the endpoint name in the left pane of your Data App, and then click **Show Code Example**. For more information, see [Get the example code of an endpoint](/tidb-cloud/use-chat2query-api.md#get-the-code-example-of-an-endpoint). - -```bash -curl --digest --user ${PUBLIC_KEY}:${PRIVATE_KEY} --request POST 'https://.data.tidbcloud.com/api/v1beta/app/chat2query-/endpoint/v3/sessions'\ - --header 'content-type: application/json'\ - --data-raw '{ - "cluster_id": "10140100115280519574", - "database": "sp500insight", - "name": "" -}' -``` - -In the preceding code, the request body is a JSON object with the following properties: - -- `cluster_id`: _string_. A unique identifier of the {{{ .starter }}} instance. -- `database`: _string_. The name of the database. -- `name`: _string_. The name of the session. - -An example response is as follows: - -```json -{ - "code": 200, - "msg": "", - "result": { - "messages": [], - "meta": { - "created_at": 1718948875, // A UNIX timestamp indicating when the session is created - "creator": "", // The creator of the session - "name": "", // The name of the session - "org_id": "1", // The organization ID - "updated_at": 1718948875 // A UNIX timestamp indicating when the session is updated - }, - "session_id": 305685 // The session ID - } -} -``` - -## Step 2. Call Chat2Data endpoints with the session - -After starting a session, you can call `/v3/sessions/{session_id}/chat2data` to continue your conversation in the next round. - -The following is a general code example: - -```bash -curl --digest --user ${PUBLIC_KEY}:${PRIVATE_KEY} --request POST 'https://eu-central-1.data.tidbcloud.com/api/v1beta/app/chat2query-YqAvnlRj/endpoint/v3/sessions/{session_id}/chat2data'\ - --header 'content-type: application/json'\ - --data-raw '{ - "question": "", - "feedback_answer_id": "", - "feedback_task_id": "", - "sql_generate_mode": "direct" -}' -``` - -In the preceding code, the request body is a JSON object with the following properties: - -- `question`: _string_. A question in natural language describing the query you want. -- `feedback_answer_id`: _string_. The feedback answer ID. This field is optional and is only used for feedback. -- `feedback_task_id`: _string_. The feedback task ID. This field is optional and is only used for feedback. -- `sql_generate_mode`: _string_. The mode to generate SQL statements. The value can be `direct` or `auto_breakdown`. If you set it to `direct`, the API will generate SQL statements directly based on the `question` you provided. If you set it to `auto_breakdown`, the API will break down the `question` into multiple tasks and generate SQL statements for each task. - -An example response is as follows: - -```json -{ - "code": 200, - "msg": "", - "result": { - "job_id": "d96b6fd23c5f445787eb5fd067c14c0b", - "session_id": 305685 - } -} -``` - -The response is similar to the response of the `/v3/chat2data` endpoint. You can check the job status by calling the `/v2/jobs/{job_id}` endpoint. For more information, see [Check the analysis status by calling `/v2/jobs/{job_id}`](/tidb-cloud/use-chat2query-api.md#2-check-the-analysis-status-by-calling-v2jobsjob_id). \ No newline at end of file From b1ed07ed33014b7c4627de016709a03ef89f0ef8 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Tue, 27 Oct 2026 18:01:24 +0800 Subject: [PATCH 2/5] Update TOC-tidb-cloud-starter.md --- TOC-tidb-cloud-starter.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/TOC-tidb-cloud-starter.md b/TOC-tidb-cloud-starter.md index d79ee491eff71..c3546a3373145 100644 --- a/TOC-tidb-cloud-starter.md +++ b/TOC-tidb-cloud-starter.md @@ -135,7 +135,7 @@ - [Troubleshoot Access Denied Errors during Data Import from Amazon S3](/tidb-cloud/troubleshoot-import-access-denied-error.md) - [Connect AWS DMS to TiDB Cloud](/tidb-cloud/tidb-cloud-connect-aws-dms.md) - Explore Data - - [SQL Editor](/tidb-cloud/explore-data-with-sql-editor.md) + - [SQL Editor](/tidb-cloud/explore-data-with-sql-editor.md) ![PREVIEW](/media/tidb-cloud/blank_transparent_placeholder.png) - [SQL Proxy Account](/tidb-cloud/sql-proxy-account.md) - Data Service ![PREVIEW](/media/tidb-cloud/blank_transparent_placeholder.png) - [Overview](/tidb-cloud/data-service-overview.md) From 7c19fcabe7236614c79a3643f8158c2ff26b3636 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Tue, 27 Oct 2026 18:05:12 +0800 Subject: [PATCH 3/5] Update SQL Editor title to include '(Preview)' Updated the title to indicate that SQL Editor is in preview and clarified its availability for starter instances. --- tidb-cloud/explore-data-with-sql-editor.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/tidb-cloud/explore-data-with-sql-editor.md b/tidb-cloud/explore-data-with-sql-editor.md index 57a18a0887593..eebbe0b0298f8 100644 --- a/tidb-cloud/explore-data-with-sql-editor.md +++ b/tidb-cloud/explore-data-with-sql-editor.md @@ -1,10 +1,10 @@ --- -title: Explore Your Data with SQL Editor +title: Explore Your Data with SQL Editor (Preview) summary: Learn how to use SQL Editor in the TiDB Cloud console to write and run SQL queries, manage SQL files, and view query results. aliases: ['/tidbcloud/explore-data-with-chat2query', '/tidbcloud/use-chat2query-api', '/tidbcloud/use-chat2query-knowledge', '/tidbcloud/use-chat2query-sessions'] --- -# Explore Your Data with SQL Editor +# Explore Your Data with SQL Editor (Preview) You can use the built-in SQL Editor in the [TiDB Cloud console](https://tidbcloud.com/) to maximize your data value. @@ -19,7 +19,7 @@ The recommended use cases of SQL Editor are as follows: ## Limitations -- SQL Editor is available only for [{{{ .starter }}}](/tidb-cloud/select-cluster-tier.md#starter) instances hosted on AWS. To use SQL Editor on [TiDB Cloud Dedicated](/tidb-cloud/select-cluster-tier.md#tidb-cloud-dedicated) clusters, contact [TiDB Cloud support](/tidb-cloud/tidb-cloud-support.md). +- SQL Editor is in public preview for [{{{ .starter }}}](/tidb-cloud/select-cluster-tier.md#starter) instances hosted on AWS. To use SQL Editor on [TiDB Cloud Dedicated](/tidb-cloud/select-cluster-tier.md#tidb-cloud-dedicated) clusters, contact [TiDB Cloud support](/tidb-cloud/tidb-cloud-support.md). ## Access SQL Editor From 6df6c5ec968a723cff3b40cf81fb3a46c27e8ecd Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Tue, 27 Oct 2026 18:05:28 +0800 Subject: [PATCH 4/5] Update TOC-tidb-cloud.md --- TOC-tidb-cloud.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/TOC-tidb-cloud.md b/TOC-tidb-cloud.md index 41b202b314a85..9a975d549c6a0 100644 --- a/TOC-tidb-cloud.md +++ b/TOC-tidb-cloud.md @@ -171,7 +171,7 @@ - [Precheck Errors, Migration Errors, and Alerts for Data Migration](/tidb-cloud/tidb-cloud-dm-precheck-and-troubleshooting.md) - [Connect AWS DMS to TiDB Cloud](/tidb-cloud/tidb-cloud-connect-aws-dms.md) - Explore Data - - [SQL Editor](/tidb-cloud/explore-data-with-sql-editor.md) + - [SQL Editor](/tidb-cloud/explore-data-with-sql-editor.md) ![PREVIEW](/media/tidb-cloud/blank_transparent_placeholder.png) - [SQL Proxy Account](/tidb-cloud/sql-proxy-account.md) - Data Service ![PREVIEW](/media/tidb-cloud/blank_transparent_placeholder.png) - [Overview](/tidb-cloud/data-service-overview.md) From c30835915f0aa0fc1bc24df36089ae577cbb1a16 Mon Sep 17 00:00:00 2001 From: qiancai Date: Tue, 27 Oct 2026 18:24:54 +0800 Subject: [PATCH 5/5] Update tidb-cloud-release-notes.md --- tidb-cloud/releases/tidb-cloud-release-notes.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/tidb-cloud/releases/tidb-cloud-release-notes.md b/tidb-cloud/releases/tidb-cloud-release-notes.md index 77477be50b4f3..b216609f8acb4 100644 --- a/tidb-cloud/releases/tidb-cloud-release-notes.md +++ b/tidb-cloud/releases/tidb-cloud-release-notes.md @@ -12,6 +12,12 @@ This page lists the release notes of [TiDB Cloud](https://www.pingcap.com/tidb-c **General changes** +- **TiDB Cloud Starter** + + - Chat2Query is no longer supported in [SQL Editor](https://docs.pingcap.com/tidbcloud/explore-data-with-sql-editor/?plan=starter&compatibility=mysql) and [Data Service](https://docs.pingcap.com/tidbcloud/data-service-overview/?plan=starter&compatibility=mysql). + + Starting from October 20, 2026, TiDB Cloud no longer supports Chat2Query in SQL Editor and Data Service. This change only affects Chat2Query and the Chat2Query API. All other features in SQL Editor and Data Service remain available. + - **TiDB Cloud Essential and Premium** - TiDB Cloud Essential and Premium support [New Relic](https://newrelic.com/) metrics integration (public preview).