From 90a7e2fa511e2420be04bab16c178856b68f31aa Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Tue, 27 Oct 2026 18:34:20 +0800 Subject: [PATCH 1/3] This is an automated cherry-pick of #24549 Signed-off-by: ti-chi-bot --- TOC-tidb-cloud-starter.md | 8 +- TOC-tidb-cloud.md | 8 +- develop/serverless-driver-drizzle-example.md | 4 +- develop/serverless-driver-kysely-example.md | 4 +- tidb-cloud/ai-feature-concepts.md | 6 +- tidb-cloud/connect-to-tidb-cluster.md | 8 +- 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 | 15 +- 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-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 - .../releases/tidb-cloud-release-notes.md | 710 ++++++++++++++++++ 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 | 37 +- 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, 879 insertions(+), 934 deletions(-) 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 26cd2fc4852f9..d9c9d3adf3aa1 100644 --- a/TOC-tidb-cloud-starter.md +++ b/TOC-tidb-cloud-starter.md @@ -135,15 +135,15 @@ - [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 +<<<<<<< HEAD - [Chat2Query in SQL Editor](/tidb-cloud/explore-data-with-chat2query.md) ![BETA](/media/tidb-cloud/blank_transparent_placeholder.png) +======= + - [SQL Editor](/tidb-cloud/explore-data-with-sql-editor.md) ![PREVIEW](/media/tidb-cloud/blank_transparent_placeholder.png) +>>>>>>> d96fa6c87c (tidb-cloud: remove Chat2Query documentation (#24549)) - [SQL Proxy Account](/tidb-cloud/sql-proxy-account.md) - Data Service ![BETA](/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 3937d1618705a..486b5680ce489 100644 --- a/TOC-tidb-cloud.md +++ b/TOC-tidb-cloud.md @@ -166,15 +166,15 @@ - [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 +<<<<<<< HEAD - [Chat2Query in SQL Editor](/tidb-cloud/explore-data-with-chat2query.md) ![BETA](/media/tidb-cloud/blank_transparent_placeholder.png) +======= + - [SQL Editor](/tidb-cloud/explore-data-with-sql-editor.md) ![PREVIEW](/media/tidb-cloud/blank_transparent_placeholder.png) +>>>>>>> d96fa6c87c (tidb-cloud: remove Chat2Query documentation (#24549)) - [SQL Proxy Account](/tidb-cloud/sql-proxy-account.md) - Data Service ![BETA](/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 a9a2f62c5e548..b3b0fcd6371f4 100644 --- a/tidb-cloud/ai-feature-concepts.md +++ b/tidb-cloud/ai-feature-concepts.md @@ -5,10 +5,11 @@ 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. +<<<<<<< HEAD ## Chat2Query (Beta) 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). @@ -16,6 +17,9 @@ Chat2Query is an AI-powered feature integrated into SQL Editor that assists user 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 (Beta) +======= +## Vector search (PREVIEW) +>>>>>>> d96fa6c87c (tidb-cloud: remove Chat2Query documentation (#24549)) 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 cfaccb722bf3c..9cf732227be34 100644 --- a/tidb-cloud/connect-to-tidb-cluster.md +++ b/tidb-cloud/connect-to-tidb-cluster.md @@ -36,15 +36,19 @@ 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. +<<<<<<< HEAD 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 (beta)](/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. +>>>>>>> d96fa6c87c (tidb-cloud: remove Chat2Query documentation (#24549)) ## What's next diff --git a/tidb-cloud/data-service-api-key.md b/tidb-cloud/data-service-api-key.md index d2b62dfeb873a..436996e93fd10 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 42c735f43b0f5..8385d6e5fb8aa 100644 --- a/tidb-cloud/data-service-concepts.md +++ b/tidb-cloud/data-service-concepts.md @@ -23,12 +23,6 @@ An endpoint in [Data Service (beta)](https://tidbcloud.com/project/data-service) 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 7f6bf139a2d1c..93850d077e92b 100644 --- a/tidb-cloud/data-service-get-started.md +++ b/tidb-cloud/data-service-get-started.md @@ -7,6 +7,7 @@ summary: Learn how to use TiDB Cloud Data Service to access your data with HTTPS Data Service (beta) 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. +<<<<<<< HEAD > **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. @@ -14,6 +15,9 @@ Data Service (beta) enables you to access TiDB Cloud data via an HTTPS request u > 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 (beta) 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. +======= +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. +>>>>>>> d96fa6c87c (tidb-cloud: remove Chat2Query documentation (#24549)) ## Before you begin @@ -61,10 +65,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 +116,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-sql-editor.md b/tidb-cloud/explore-data-with-sql-editor.md new file mode 100644 index 0000000000000..eebbe0b0298f8 --- /dev/null +++ b/tidb-cloud/explore-data-with-sql-editor.md @@ -0,0 +1,101 @@ +--- +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 (Preview) + +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 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 + +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 165ef498bf28d..1cc6c65023fab 100644 --- a/tidb-cloud/manage-user-access.md +++ b/tidb-cloud/manage-user-access.md @@ -137,8 +137,8 @@ At the project level, TiDB Cloud defines four roles, in which `Project Owner` ca | Manage resource data such as data import, data backup and restore, and data migration. | ✅ | ✅ | ❌ | ❌ | | 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. | ✅ | ✅ | ✅ | ✅ | @@ -157,8 +157,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 5d5fce67213c8..fa0d5193c2639 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/releases/tidb-cloud-release-notes.md b/tidb-cloud/releases/tidb-cloud-release-notes.md index 46d5d9b7ad193..f753343c1d7b2 100644 --- a/tidb-cloud/releases/tidb-cloud-release-notes.md +++ b/tidb-cloud/releases/tidb-cloud-release-notes.md @@ -8,6 +8,716 @@ aliases: ['/tidbcloud/supported-tidb-versions','/tidbcloud/release-notes'] This page lists the release notes of [TiDB Cloud](https://www.pingcap.com/tidb-cloud/) in 2026. +<<<<<<< HEAD +======= +## October 20, 2026 + +**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). + + You can send key performance metrics from your TiDB Cloud Essential or Premium instances to New Relic and monitor them on your existing New Relic dashboards. + + For more information, see the following documentation: + + - [Integrate TiDB Cloud Essential with New Relic (PREVIEW)](https://docs.pingcap.com/tidbcloud/monitor-new-relic-integration-for-tidb-x/?plan=essential) + - [Integrate TiDB Cloud Premium with New Relic (PREVIEW)](https://docs.pingcap.com/tidbcloud/monitor-new-relic-integration-for-tidb-x/?plan=premium) + +- **TiDB Cloud Dedicated** + + - Newly created TiDB Cloud Dedicated clusters now have public endpoints disabled by default. Existing clusters retain their current public endpoint settings. + + Before connecting to a newly created cluster over the public internet, enable **Public Endpoint** under **Settings > Networking** in the [TiDB Cloud console](https://tidbcloud.com/), and then add your client IP address to the IP access list. + + For more information, see [Connect to TiDB Cloud Dedicated via Public Connection](https://docs.pingcap.com/tidbcloud/connect-via-standard-connection/). + +- **TiDB Cloud BYOC** + + - TiDB Cloud BYOC supports vCPU limit alerts to help you better monitor resource usage and control cloud costs. + + TiDB Cloud BYOC now notifies you when provisioned vCPU usage approaches the configured regional limit or when a scale-up operation is blocked because the limit has been reached. + + These alerts provide clear guidance on available scaling capacity and recommended actions. + + For more information, see [TiDB Cloud Built-in Alerting](https://docs.pingcap.com/tidbcloud/monitor-built-in-alerting/?plan=byoc). + +## October 15, 2026 + +**General changes** + +- **TiDB Cloud Starter** + + - PostgreSQL-compatible TiDB Cloud Starter is now in public preview on AWS. + + When creating a TiDB Cloud Starter instance, you can now choose between MySQL and PostgreSQL compatibility based on your application needs and technology stack. + + PostgreSQL-compatible TiDB Cloud Starter instances support core instance management operations, including connection, monitoring, backup, and restore. It also supports pgvector-compatible vector search and selected PostgreSQL extensions, enabling you to build a wide range of applications using familiar PostgreSQL ecosystem tools and capabilities. + + Currently, the public preview of PostgreSQL-compatible TiDB Cloud Starter is intended for development and evaluation and is not recommended for production workloads. + + To get started, see [PostgreSQL-compatible TiDB Cloud Starter documentation](https://docs.pingcap.com/tidbcloud/starter/?plan=starter&compatibility=postgresql). + +- **TiDB Cloud BYOC** + + - TiDB Cloud BYOC is now in public preview on AWS. + + Powered by the TiDB X kernel, [TiDB Cloud BYOC](https://docs.pingcap.com/tidbcloud/architecture-concepts/?plan=byoc#tidb-cloud-byoc) is specifically designed for mission-critical and AI workloads that require a scalable, reliable database platform while keeping the data plane within your own cloud environment. + + TiDB Cloud BYOC combines the flexibility of customer-managed infrastructure with the operational simplicity of a managed TiDB Cloud service. + + With the data plane running directly in your AWS account and VPC, your organization retains greater control over the cloud environment, ensuring strict data isolation and seamless security integration. At the same time, PingCAP manages the control plane. This allows you to benefit from TiDB's distributed SQL capabilities, scalability, and compatibility, without the full operational burden of managing the platform yourself. + + Because TiDB Cloud BYOC is deployed in your AWS account, onboarding requires coordination with the TiDB Cloud team. To start BYOC onboarding, [contact Sales](https://www.pingcap.com/contact-us/). + + For more information, see [TiDB Cloud BYOC documentation](https://docs.pingcap.com/tidbcloud/byoc/?plan=byoc). + +- **TiDB Cloud Filesystem** + + - TiDB Cloud Filesystem is now in public preview. + + TiDB Cloud Filesystem is a distributed file system designed specifically for AI coding agents. Built on the same TiDB Cloud Starter infrastructure that already powers millions of AI agents in production, it provides Git-aware, persistent workspaces across sandbox lifecycles, with always-on availability and seamless scalability. + + To get started, see [TiDB Cloud Filesystem documentation](https://docs.pingcap.com/tidbcloud-filesystem/). + +## October 13, 2026 + +**General changes** + +- **TiDB Cloud Essential** + + - TiDB Cloud Essential now lets you create an instance or update its capacity without setting Max RCU. This feature is available for TiDB Cloud Essential instances running TiDB version `CLOUD.202603.x` or later. + + - **Elastic Mode** is the default mode when you create a new TiDB Cloud Essential instance. In this mode, TiDB Cloud automatically allocates backend resources based on your workload. For workloads that consistently require more than 100,000 RCUs, consider upgrading to TiDB Cloud Premium to avoid potential performance bottlenecks. + - If you need to set a maximum capacity limit, you can switch to **Limited Mode**. + + Existing TiDB Cloud Essential instances with a configured Max RCU continue to run without any configuration changes. You can keep the current value or clear it to switch to **Elastic Mode**. + + For more information, see [Create a TiDB Cloud Essential instance](https://docs.pingcap.com/tidbcloud/create-tidb-cluster-serverless/?plan=essential). + + - TiDB Cloud Essential now supports manual backups. These manual backups are retained until you explicitly delete them. + + This feature is available for TiDB Cloud Essential instances running TiDB version `CLOUD.202603.x` or later. + + To create a manual backup, see [Manual backups](https://docs.pingcap.com/tidbcloud/backup-and-restore-serverless/?plan=essential#manual-backups). + +- **TiDB Cloud Premium** + + - TiDB Cloud Premium now lets you create an instance or update its capacity without setting Max RCU. + + - **Elastic Mode** is the default mode when you create a new TiDB Cloud Premium instance: TiDB Cloud automatically allocates backend resources based on your workload. In Elastic Mode, you can set Baseline RCU to specify the minimum provisioned capacity and minimum billable capacity. RCU consumption alerts are supported, and you can set a custom threshold to monitor usage as capacity scales. + - If you need to set a maximum capacity limit, you can still use **Limited Mode**. + + Existing TiDB Cloud Premium instances with a configured Max RCU continue to run without any configuration changes. You can keep the current value or clear it to switch to **Elastic Mode**. + + For more information, see [Create a TiDB Cloud Premium instance](https://docs.pingcap.com/tidbcloud/create-tidb-instance-premium/?plan=premium). + +## September 29, 2026 + +**General changes** + +- **TiDB Cloud Premium** + + - TiDB Cloud Premium adds query latency count threshold alerts. + + TiDB Cloud Premium now provides three built-in alert rules that notify you when more than 20 SQL statements exceed a latency threshold of 256 ms, 512 ms, or 4096 ms within one minute. These alerts help you detect periods with unusually high numbers of slow SQL statements. + + For more information, see [TiDB Cloud Built-in Alerting](https://docs.pingcap.com/tidbcloud/built-in-monitoring-premium/?plan=premium). + +- **TiDB Cloud Dedicated** + + - TiDB Cloud Dedicated supports cross-region AWS PrivateLink connections. + + With this feature, you can create an AWS interface endpoint in one region and privately connect it to a TiDB Cloud Dedicated cluster in another region. Cross-region connections use the same connection string. + + Currently, this feature is available upon request. A cross-region PrivateLink service fee applies per added region, and removing a region does not affect existing connections. To request this feature, contact [TiDB Cloud Support](/tidb-cloud/tidb-cloud-support.md). + + For more information, see [Connect to a TiDB Cloud Dedicated Cluster via AWS PrivateLink](https://docs.pingcap.com/tidbcloud/set-up-private-endpoint-connections/). + +## September 22, 2026 + +**General changes** + +- **TiDB Cloud Dedicated** + + - [TiDB Cloud Dedicated](/tidb-cloud/select-cluster-tier.md#tidb-cloud-dedicated) now supports inbound IPv6 connectivity over AWS PrivateLink, so you can connect to your cluster over either IPv4 or IPv6. + + Currently, this feature is available upon request. To access IPv6 connectivity, contact [TiDB Cloud Support](/tidb-cloud/tidb-cloud-support.md) to request it, and then create a dual-stack AWS interface endpoint. + + For more information, see [Use IPv6 connectivity over a private endpoint](https://docs.pingcap.com/tidbcloud/set-up-private-endpoint-connections#use-ipv6-connectivity-over-a-private-endpoint). + +## September 15, 2026 + +**General changes** + +* **TiDB Cloud CLI** + + [TiDB Cloud CLI (`ti`)](https://github.com/tidbcloud/ti-cli) is now available in public preview for managing [TiDB Cloud Starter](/tidb-cloud/select-cluster-tier.md#starter) instances and file systems in TiDB Cloud Filesystem. TiDB Cloud Filesystem is a serverless distributed file system designed for AI agents and automation workloads. + + You can use `ti` directly or let your scripts, CI jobs, and AI agents run it to automate TiDB Cloud workflows. With `ti`, you can create and manage TiDB Cloud Starter instances, execute SQL statements, and create and access persistent file system workspaces through file commands or supported mounts. JSON output by default, JMESPath output queries, and support for `--wait` and `--dry-run` on applicable commands simplify automation. + + For more information, see [Get Started with TiDB Cloud CLI](/ai/ti/ti-quick-start.md) and [TiDB Cloud CLI (`ti`) Overview](/ai/ti/ti-overview.md). + +## September 8, 2026 + +**Console changes** + +- **TiDB Cloud Essential** + + - [TiDB Cloud Essential](/tidb-cloud/select-cluster-tier.md#essential) instances that include the enhancements announced on [June 30, 2026](#june-30-2026) now display `CLOUD.202603.x` as their TiDB version on the instance overview page in the TiDB Cloud console. + + For more information about these enhancements, see the [June 30, 2026 release notes](#june-30-2026). + +**API changes** + +- **TiDB Cloud Premium** + + - Introduce the changefeed API endpoints for [TiDB Cloud Premium](/tidb-cloud/select-cluster-tier.md#premium), providing programmatic management of change data capture (CDC) changefeeds. + + You can use these endpoints to create, list, get, delete, pause, resume, and scale changefeeds for real-time data replication to downstream systems, including Apache Kafka, MySQL, Amazon S3, and Alibaba Cloud OSS. + + For more information, see [Changefeed API v1beta2 Reference](https://docs.pingcap.com/tidbcloud/api/v1beta2/premium/#tag/Changefeed). + +## September 1, 2026 + +**General changes** + +- **TiDB Cloud Essential** + + - TiDB Cloud Essential now lets you temporarily authorize TiDB Cloud Support to access Plan Replayer files for SQL performance troubleshooting. + + You can choose the access duration, extend it if needed, or revoke access at any time. Access is automatically revoked when the authorization expires. + + Plan Replayer files contain SQL text, table schemas, and optimizer statistics, but no actual table row data. + + For more information, see [Use Plan Replayer to Troubleshoot SQL Performance](https://docs.pingcap.com/tidbcloud/plan-replayer/?plan=essential). + +- **TiDB Cloud Premium** + + - The **Events** page is now available for TiDB Cloud Premium instances. + + You can view historical events that record changes to your Premium instance on this page, along with information such as the event type, status, message, trigger time, and trigger user. Event data is retained for 7 days. + + For more information, see [Events](https://docs.pingcap.com/tidbcloud/tidb-cloud-events/?plan=premium). + + - TiDB Cloud Premium now lets you configure filter rules for database audit logging. + + You can filter audit events by SQL user, event class, table, and execution status to control which database activities are logged, helping you focus on relevant events for security auditing and compliance. + + For more information, see [Specify audit filter rules](https://docs.pingcap.com/tidbcloud/tidb-cloud-auditing-premium/?plan=premium#specify-audit-filter-rules). + + - TiDB Cloud Premium now lets you temporarily authorize TiDB Cloud Support to access Plan Replayer files for SQL performance troubleshooting. + + You can choose the access duration, extend it if needed, or revoke access at any time. Access is automatically revoked when the authorization expires. + + Plan Replayer files contain SQL text, table schemas, and optimizer statistics, but no actual table row data. + + For more information, see [Use Plan Replayer to Troubleshoot SQL Performance](https://docs.pingcap.com/tidbcloud/plan-replayer/?plan=premium). + +**Billing adjustments** + +- **TiDB Cloud Essential** + + - Starting September 1, 2026, billing for backup usage and network egress on [TiDB Cloud Essential](/tidb-cloud/select-cluster-tier.md#essential) instances is gradually taking effect. + + Network egress is billed as a separate line item rather than being included in RCU charges. + + For more information, see [TiDB Cloud Essential Pricing Details](https://www.pingcap.com/tidb-cloud-essential-pricing-details/). + +## August 28, 2026 + +**General changes** + +- **TiDB Cloud Dedicated** + + - Upgrade the default TiDB version of new [TiDB Cloud Dedicated](/tidb-cloud/select-cluster-tier.md#tidb-cloud-dedicated) clusters from [v8.5.7](https://docs.pingcap.com/tidb/stable/release-8.5.7/) to [v8.5.8](https://docs.pingcap.com/tidb/stable/release-8.5.8/). + +## August 25, 2026 + +**General changes** + +- **TiDB Cloud Premium** + + - TiDB Cloud Premium now supports streaming changefeed data directly to Amazon S3 and Alibaba Cloud Object Storage Service (OSS). + + This feature enables you to archive change data to cloud storage for downstream analytics and long-term retention, while reducing costs by eliminating the need for intermediate message queues. + + For more information, see [Sink to Cloud Storage](https://docs.pingcap.com/tidbcloud/changefeed-sink-to-cloud-storage/?plan=premium). + +## August 18, 2026 + +**General changes** + +- **TiDB Cloud Premium** + + - Introduce **Statement Insight** (PREVIEW) for TiDB Cloud Premium instances. + + This feature provides an actionable view into SQL resource consumption in your TiDB Cloud Premium instances. + + Now you can analyze RU consumption, latency, and execution counts of SQL statements in multiple dimensions, such as DB User, SQL type, DB, table, or SQL digest. In addition, you can see top contributors at a glance, making it easier to identify the sources of high resource consumption or slowdowns. + + Currently, this feature is in public preview and available only for a limited number of TiDB Cloud Premium instances created on or after August 19. + + For more information, see [Statement Insight (PREVIEW)](https://docs.pingcap.com/tidbcloud/statement-insight/?plan=premium). + +- **TiDB Cloud Lake** + + - [TiDB Cloud Lake](https://docs.pingcap.com/tidbcloudlake/) is now available on Alibaba Cloud in Japan (Tokyo) (`ap-northeast-1`). + + For more supported regions, see [Platforms & Regions](https://docs.pingcap.com/tidbcloudlake/platforms-regions/). + + - Expand Python extensibility and analytics engineering workflows for TiDB Cloud Lake with the new external Python UDF SDK and dbt adapter. + + - With the new external Python UDF SDK, you can implement custom scalar and table functions in Python, deploy them on a UDF server, register the endpoint in TiDB Cloud Lake, and call the functions directly from SQL. The SDK supports common and complex data types, NULL handling, I/O parallelism, and per-function concurrency controls. + - With the new dbt adapter, you can connect dbt to TiDB Cloud Lake to build, test, and document data transformation workflows. The adapter supports table, view, and incremental materializations, as well as seeds, sources, custom data tests, documentation generation, snapshots, and connection retries. + + For more information, see the following documentation: + + - [External Function](https://docs.pingcap.com/tidbcloudlake/external-function/) + - [Choose a User-Defined Function Type](https://docs.pingcap.com/tidbcloudlake/choose-a-udf-type/) + - [Load Data with dbt](https://docs.pingcap.com/tidbcloudlake/load-with-dbt/) + +## August 11, 2026 + +**General changes** + +- **TiDB Cloud Essential, Premium, and Dedicated** + + - Support subscribing to alert notifications from TiDB Cloud via [Lark](https://www.larksuite.com/). + + If the [support plan](/tidb-cloud/connected-care-overview.md#connected-care) of your organization is **Enterprise** or **Premium**, you can now receive alert notifications via Lark. + + For more information, see the following documentation: + + - TiDB Cloud Essential: [Subscribe via Lark](https://docs.pingcap.com/tidbcloud/monitor-alert-lark/?plan=essential) + - TiDB Cloud Premium: [Subscribe via Lark](https://docs.pingcap.com/tidbcloud/monitor-alert-lark/?plan=premium) + - TiDB Cloud Dedicated: [Subscribe via Lark](https://docs.pingcap.com/tidbcloud/monitor-alert-lark/) + +- **TiDB Cloud Lake** + + - Expand AI, Python, and BI integrations for [TiDB Cloud Lake](https://docs.pingcap.com/tidbcloudlake/) with the new MCP server and SQLAlchemy dialect. + + - With the new MCP server, you can now connect MCP-compatible AI tools to explore database objects, inspect table schemas, and run SQL using natural-language instructions. Built-in session sandbox protection is enabled by default, keeping production objects read-only while restricting writes to session-specific sandbox objects. + - With the new SQLAlchemy dialect, you can connect Python applications and SQLAlchemy-compatible tools to TiDB Cloud Lake through the dialect. You can use tools such as Jupyter Notebook for querying and visualizing data, and Apache Superset for building charts and dashboards. + + For more information, see the following documentation: + + - [TiDB Cloud Lake MCP Server](https://docs.pingcap.com/tidbcloudlake/mcp-server) + - [Connect AI Tools to TiDB Cloud Lake Using MCP](https://docs.pingcap.com/tidbcloudlake/mcp-client-integration) + - [Connect to TiDB Cloud Lake with Jupyter Notebook](https://docs.pingcap.com/tidbcloudlake/jupyter-notebook) + - [Connect to TiDB Cloud Lake with Apache Superset](https://docs.pingcap.com/tidbcloudlake/superset) + +**Console changes** + +- Improve the networking experience across TiDB Cloud plans with the following updates in the [TiDB Cloud console](https://tidbcloud.com/): + + - The **Networking** page now uses more consistent naming for endpoint configurations across TiDB Cloud plans. + - For endpoint types with no configured endpoints, the **Networking** page now displays only the corresponding action button instead of an empty table. + - For TiDB Cloud Starter and Essential instances, you can now click **Connect** in the upper-right corner of the **Networking** page to connect to your instance after configuring network access. + - For TiDB Cloud Essential, Premium, and Dedicated, managing allowed IP addresses for public endpoints is now more intuitive. You can click **Add IP Address** to add an IP address, or click **...** for an existing IP address to edit or delete it. + +## August 5, 2026 + +**General changes** + +- **TiDB Cloud Premium** + + - Introduce **Custom Retention Mode** for automatic backups on TiDB Cloud Premium instances. + + TiDB Cloud Premium now offers two automatic backup modes: + + - **Custom Retention Mode:** lets you specify the retention period from 3 to 33 days and choose when daily snapshots are created. + - **Standard Bundle Mode:** preserves the previous default automatic backup settings for PITR, hourly snapshots, and daily snapshots. + + For more information, see [Automatic backup modes](/tidb-cloud/premium/backup-and-restore-premium.md#automatic-backup-modes). + +## August 4, 2026 + +**General changes** + +- **TiDB Cloud Essential** + + - Support subscribing to alert notifications from TiDB Cloud Essential via generic webhooks. + + If the [support plan](/tidb-cloud/connected-care-overview.md#connected-care) of your organization is **Enterprise** or **Premium**, you can now receive alert notifications via a generic webhook. For services that require custom payload formats, such as Telegram or Microsoft Teams, use a lightweight relay to transform and forward the notifications. + + For more information, see [Subscribe via Webhook](https://docs.pingcap.com/tidbcloud/monitor-alert-webhook/?plan=essential). + +- **TiDB Cloud Premium** + + - Support [Amazon MSK Provisioned](https://docs.aws.amazon.com/msk/latest/developerguide/msk-provisioned.html) clusters as changefeed sinks for TiDB Cloud Premium instances. + + For TiDB Cloud Premium instances hosted on AWS, you can now stream row change events to Amazon MSK Provisioned clusters over AWS PrivateLink. + + For more information, see [Set Up Private Endpoint for Changefeeds](/tidb-cloud/premium/set-up-sink-private-endpoint-premium.md) and [Set Up an Amazon MSK Provisioned Cluster via AWS PrivateLink](/tidb-cloud/setup-aws-msk-provisioned-private-link-service.md). + + - Support subscribing to alert notifications from TiDB Cloud Premium via generic webhooks. + + If the [support plan](/tidb-cloud/connected-care-overview.md#connected-care) of your organization is **Enterprise** or **Premium**, you can now receive alert notifications via a generic webhook. For services that require custom payload formats, such as Telegram or Microsoft Teams, use a lightweight relay to transform and forward the notifications. + + For more information, see [Subscribe via Webhook](https://docs.pingcap.com/tidbcloud/monitor-alert-webhook/?plan=premium). + +- **TiDB Cloud Dedicated** + + - Update pause requirements for TiDB Cloud Dedicated clusters. + + Before [pausing a TiDB Cloud Dedicated cluster](/tidb-cloud/pause-or-resume-tidb-cluster.md), you must turn off [Point-in-Time Restore (PITR)](/tidb-cloud/backup-and-restore.md#turn-on-point-in-time-restore) and ensure that no Data Migration (DM) job is running. If either condition is not met, TiDB Cloud rejects the pause request and displays an error message. + + - Support subscribing to alert notifications from TiDB Cloud Dedicated via generic webhooks. + + If the [support plan](/tidb-cloud/connected-care-overview.md#connected-care) of your organization is **Enterprise** or **Premium**, you can now receive alert notifications via a generic webhook. For services that require custom payload formats, such as Telegram or Microsoft Teams, use a lightweight relay to transform and forward the notifications. + + For more information, see [Subscribe via Webhook](https://docs.pingcap.com/tidbcloud/monitor-alert-webhook/). + +## July 28, 2026 + +**General changes** + +- **TiDB Cloud Dedicated** + + - Database audit logging is now available in public preview for [TiDB Cloud Dedicated](/tidb-cloud/select-cluster-tier.md#tidb-cloud-dedicated) clusters running TiDB v7.5.6 or later, or v8.5.2 or later. + + This feature records user access activities, including executed SQL statements, supports writing audit logs to Amazon S3, Google Cloud Storage (GCS), or Azure Blob Storage, and lets you configure filter rules to control which events are captured for specific SQL users. + + For more information, see [TiDB Cloud Dedicated Database Audit Logging (Preview)](/tidb-cloud/tidb-cloud-auditing.md). + +## July 21, 2026 + +**General changes** + +- **TiDB Cloud Essential** + + - [Top RU](/tidb-cloud/top-ru.md) (public preview) for [TiDB Cloud Essential](/tidb-cloud/select-cluster-tier.md#essential) now supports the following additional region: + + - Alibaba Cloud: `Jakarta (ap-southeast-5)` + + This feature displays minute-level top RU-consuming SQLs, helping you quickly identify the most resource-intensive queries to reduce costs. + +## July 14, 2026 + +**General changes** + +- **TiDB Cloud Dedicated** + + - Enhance cross-region restore for [TiDB Cloud Dedicated](/tidb-cloud/select-cluster-tier.md#tidb-cloud-dedicated). + + When the target restore region has no pre-allocated CIDR block, you can now create a CIDR block directly on the **Restore** page, eliminating the need to manually create a cluster in that region before starting the restore. + +## July 9, 2026 + +**General changes** + +- **TiDB Cloud Dedicated** + + - Upgrade the default TiDB version of new [TiDB Cloud Dedicated](/tidb-cloud/select-cluster-tier.md#tidb-cloud-dedicated) clusters from [v8.5.6](https://docs.pingcap.com/tidb/stable/release-8.5.6/) to [v8.5.7](https://docs.pingcap.com/tidb/stable/release-8.5.7/). + +## July 7, 2026 + +**General changes** + +- **TiDB Cloud Essential** + + - Support the Datadog integration (public preview). + + You can now configure TiDB Cloud to send key metrics from your [TiDB Cloud Essential](/tidb-cloud/select-cluster-tier.md#essential) instances to [Datadog](https://www.datadoghq.com/) for centralized monitoring and alerting. + + For more information, see [Integrate TiDB Cloud with Datadog](https://docs.pingcap.com/tidbcloud/monitor-datadog-integration-for-tidb-x/?plan=essential). + +- **TiDB Cloud Premium** + + - Support the Datadog integration (public preview). + + You can now configure TiDB Cloud to send key metrics from your [TiDB Cloud Premium](/tidb-cloud/select-cluster-tier.md#premium) instances to [Datadog](https://www.datadoghq.com/) for centralized monitoring and alerting. + + For more information, see [Integrate TiDB Cloud with Datadog](https://docs.pingcap.com/tidbcloud/monitor-datadog-integration-for-tidb-x/?plan=premium). + +**Console changes** + +- Standardize the label used in the [TiDB Cloud console](https://tidbcloud.com/) for public preview features as `PREVIEW`, replacing the previous mixed use of `BETA` and `PREVIEW`. + +**API changes** + +- **TiDB Cloud Dedicated** + + - Introduce the changefeed API endpoints for [TiDB Cloud Dedicated](/tidb-cloud/select-cluster-tier.md#tidb-cloud-dedicated), providing programmatic management of change data capture (CDC) changefeeds. + + You can use these endpoints to create, list, get, delete, pause, resume, and scale changefeeds for real-time data replication to downstream systems, including Apache Kafka, MySQL, Amazon S3, Google Cloud Storage (GCS), and Azure Blob Storage. + + For more information, see [Changefeed API v1beta1 Reference](https://docs.pingcap.com/tidbcloud/api/v1beta1/dedicated/#tag/Changefeed). + +## June 30, 2026 + +**General changes** + +- **TiDB Cloud Essential** + + - Enhance the stability, security, and operational experience of [TiDB Cloud Essential](/tidb-cloud/select-cluster-tier.md#essential). The following enhancements and changes are rolling out gradually to newly created TiDB Cloud Essential instances. + + - **Improve the connection experience**: support standalone endpoints for newly created TiDB Cloud Essential instances, so you no longer need to include the mandatory [account prefix](/tidb-cloud/select-cluster-tier.md#user-name-prefix) when connecting to these instances. + - **Support changing the root password**: you can change the root password directly from the TiDB Cloud console. + - **Enhance the data import experience**: after entering the source destination fields on the import data page, you can click **Test Bucket Access** to verify access to the specified object storage bucket before importing data. In addition, the import page now displays the size of files to be imported to improve visibility and management of import operations. + - **Update the availability of the Branch feature**: starting from **July 14, 2026**, newly created TiDB Cloud Essential instances no longer support the [Branch](/tidb-cloud/branch-overview.md) feature. Existing TiDB Cloud Essential instances created before this date are not affected. The Branch feature remains available in [TiDB Cloud Starter](/tidb-cloud/select-cluster-tier.md#starter). + - **Update import and export capabilities**: to enhance security, importing data from local files and exporting data to local files are no longer supported. + - **Update DB audit log storage requirements**: for security and compliance reasons, you must specify an external storage location for audit log retention. + - [Changefeed](/tidb-cloud/essential-changefeed-overview.md) will be available as a billable feature starting from **July 1, 2026**. + + These features are rolling out in phases. Contact [support@pingcap.com](mailto:support@pingcap.com) for early access. + + - [Top RU](/tidb-cloud/top-ru.md) is now available in public preview for [TiDB Cloud Essential](/tidb-cloud/select-cluster-tier.md#essential) in the following regions: + + - Alibaba Cloud: `Singapore (ap-southeast-1)` and `Tokyo (ap-northeast-1)` + + This feature displays minute-level top RU-consuming SQL statements, helping you quickly identify the most resource-intensive queries to reduce costs. + + This feature is rolling out in phases. Contact [support@pingcap.com](mailto:support@pingcap.com) for early access. + +- **TiDB Cloud Dedicated** + + - Refine the backup and restore flow for [TiDB Cloud Dedicated](/tidb-cloud/select-cluster-tier.md#tidb-cloud-dedicated) clusters. + + - The **Restore** page for TiDB Cloud Dedicated no longer includes the **Restore From Region** option. Because TiDB Cloud Dedicated implicitly stores backup data in the same region as the cluster, you no longer need to select the region to restore from. + - The **Restore to Region** option is renamed to **Cloud Provider & Region**. + + For more information, see [Restore data to a new cluster](/tidb-cloud/backup-and-restore.md). + +- **TiDB Cloud Lake** + + - TiDB Cloud Lake is now in public preview. + + TiDB Cloud Lake is a cloud-native analytics warehouse in TiDB Cloud for modern analytics and AI-oriented data workflows. It provides elastic warehouses, ANSI SQL analytics, object storage, full-text search, vector search, and geospatial analysis in one managed service, helping teams analyze structured and semi-structured data without managing separate analytics infrastructure. + + With this public preview, you can run SQL analytics with elastic warehouses and use built-in search capabilities for BI, log analytics, semantic retrieval, and other modern analytics and AI use cases. + + To try TiDB Cloud Lake, log in to the [TiDB Cloud console](https://tidbcloud.com/), click **My Lake** in the left navigation pane, and then click **Try TiDB Cloud Lake** in the upper-right corner. + + For more information, see [TiDB Cloud Lake documentation](https://docs.pingcap.com/tidbcloudlake/). + +**Upcoming billing adjustments** + +- The following billing adjustments will take effect for [TiDB Cloud Essential](/tidb-cloud/select-cluster-tier.md#essential): + + - **Minimum RCU billing updates**: starting from **August 1, 2026**, the minimum RCU value is automatically determined based on your configured maximum RCU value (Minimum RCU = 0.1 × configured maximum RCU, with a lower bound of 2,000 RCUs). If your actual usage remains below the minimum RCU threshold, TiDB Cloud calculates charges based on the minimum RCU value. For **existing instances created before July 1, 2026**, the implementation of this minimum RCU billing policy is postponed, and the exact effective date will be announced later. + - **Additional billable features**: charges for backup usage and network egress will take effect on **September 1, 2026**. For more information, see [TiDB Cloud Essential pricing](https://www.pingcap.com/tidb-cloud-essential-pricing-details/). + +## June 16, 2026 + +**General changes** + +- Add domain verification for [Cloud Organization SSO](/tidb-cloud/tidb-cloud-org-sso-authentication.md). + + In the following scenarios, the **Allowed Email Domains** field is required. To improve security, you must verify domains before entering them in this field: + + - Enabling auto-provisioning for the OIDC or SAML authentication method + - Enabling SCIM provisioning for the SAML authentication method + + For more information, see [Add and verify domains for OIDC and SAML](/tidb-cloud/tidb-cloud-org-sso-authentication.md#add-and-verify-domains-for-oidc-and-saml). + +## June 9, 2026 + +**General changes** + +- **TiDB Cloud Starter** + + - Add a new AWS region for [full-text search](https://docs.pingcap.com/ai/vector-search-full-text-search-python/) (public preview) on [TiDB Cloud Starter](/tidb-cloud/select-cluster-tier.md#starter): `N. Virginia (us-east-1)`. The feature is now available in the following AWS regions: + + - `Tokyo (ap-northeast-1)` + - `Oregon (us-west-2)` + - `N. Virginia (us-east-1)` + - `Frankfurt (eu-central-1)` + - `Singapore (ap-southeast-1)` + + + +**High availability changes** + +- **TiDB Cloud Essential** + + - Starting from June 9, 2026, newly created [TiDB Cloud Essential](/tidb-cloud/select-cluster-tier.md#essential) instances are deployed in a single Availability Zone and do not support regional high availability. + + If you need regional high availability and cross-AZ failover, consider choosing [TiDB Cloud Premium](/tidb-cloud/select-cluster-tier.md#premium). + + This change does not affect TiDB Cloud Essential instances created before June 9, 2026. + + + +**API changes** + +- **TiDB Cloud Premium** + + - Introduce the following backup API endpoints for [TiDB Cloud Premium](/tidb-cloud/select-cluster-tier.md#premium), enabling unified management for both active and deleted instances within your organization. + + - [List backups](https://docs.pingcap.com/tidbcloud/api/v1beta2/premium/#tag/Backup/operation/BackupService_ListBackups): lists backups for both active and deleted TiDB Cloud Premium instances (in the recycle bin) within your organization. + - [Delete a backup](https://docs.pingcap.com/tidbcloud/api/v1beta2/premium/#tag/Backup/operation/BackupService_DeleteBackup): deletes a specific backup within your organization by `backupId`. + +## June 2, 2026 + +**General changes** + +- **TiDB Cloud Starter** + + - Introduce the [Instance Capacity Plan](https://www.pingcap.com/programs/agentic-ai-instance-capacity) for organizations that require a large number of [TiDB Cloud Starter](/tidb-cloud/select-cluster-tier.md#starter) instances and branches. + + By default, for each paid organization in TiDB Cloud, you can create up to 100 TiDB Cloud Starter instances and branches in total, with each branch counted as a separate instance. To exceed this limit, apply for the [Instance Capacity Plan](https://www.pingcap.com/programs/agentic-ai-instance-capacity). + +- **TiDB Cloud Essential** + + - Top RU is now available in public preview for [TiDB Cloud Essential](/tidb-cloud/select-cluster-tier.md#essential) in the following regions: + + - AWS: `N. Virginia (us-east-1)`, `Tokyo (ap-northeast-1)` + + This feature displays minute-level top RU-consuming SQL statements, helping you quickly identify the most resource-intensive queries to reduce costs. + + This feature is rolling out in phases. Contact [support@pingcap.com](mailto:support@pingcap.com) for early access. + +- **TiDB Cloud Premium** + + - Support Dual-Layer Data Encryption on Alibaba Cloud for [TiDB Cloud Premium](/tidb-cloud/select-cluster-tier.md#premium) instances. + + You can use your own keys in Alibaba Cloud Key Management Service (KMS) to encrypt data at rest, giving you greater control over data security and compliance. + + This feature is now available upon request. For more information, see [Dual-Layer Data Encryption](/tidb-cloud/premium/dual-layer-data-encryption-premium.md). + + - Provide two new TTL monitoring metrics on the **Metrics** page (**Instance Overview** tab) for TiDB Cloud Premium instances. + + - Table Count by TTL Schedule Delay + - TTL Insert/Delete Rows by Day + + These metrics help you observe TTL job health and detect data retention issues. For more information, see [{{{ .premium }}} Built-in Metrics](/tidb-cloud/premium/built-in-monitoring-premium.md). + +**API changes** + +- **TiDB Cloud Starter** + + - For a paid organization not enrolled in the [Instance Capacity Plan](https://www.pingcap.com/programs/agentic-ai-instance-capacity), TiDB Cloud API now enforces a limit of 100 TiDB Cloud Starter instances and branches in total, with each branch counted as a separate instance. + + - When the limit is reached, API requests to create new TiDB Cloud Starter instances or branches are rejected. + - To exceed this limit, apply for the [Instance Capacity Plan](https://www.pingcap.com/programs/agentic-ai-instance-capacity). + +## May 26, 2026 + +**General changes** + +- **TiDB Cloud Starter** + + - Add two new AWS regions for [full-text search](https://docs.pingcap.com/ai/vector-search-full-text-search-python/) (public preview) on [TiDB Cloud Starter](/tidb-cloud/select-cluster-tier.md#starter): `Tokyo (ap-northeast-1)` and `Oregon (us-west-2)`. The feature is now available in the following AWS regions: + + - `Tokyo (ap-northeast-1)` + - `Oregon (us-west-2)` + - `Frankfurt (eu-central-1)` + - `Singapore (ap-southeast-1)` + +- **TiDB Cloud Essential** + + - Top RU is now available in public preview for [TiDB Cloud Essential](/tidb-cloud/select-cluster-tier.md#essential) in the following regions: + + - AWS: `Oregon (us-west-2)`, `Frankfurt (eu-central-1)`, `Singapore (ap-southeast-1)` + + This feature shows the top RU-consuming SQL statements at minute-level granularity, helping you quickly identify resource-intensive queries to reduce costs. + + The feature is rolling out in phases. To request early access, contact [support@pingcap.com](mailto:support@pingcap.com). + +**API changes** + +- TiDB Cloud IAM API (v1beta1) supports managing organization members programmatically. + + The new `/members` endpoints let you manage organization membership and role assignments. You can use these endpoints to automate user lifecycle management tasks, such as onboarding new members with specific roles, adjusting permissions as responsibilities change, and removing members who leave the organization. + + For more information, see [TiDB Cloud IAM API](https://docs.pingcap.com/tidbcloud/api/v1beta1/iam/#tag/Member). + +## May 19, 2026 + +**General changes** + +- **TiDB Cloud Essential** + + - Recycle Bin is now available for [TiDB Cloud Essential](/tidb-cloud/select-cluster-tier.md#essential). It stores data of deleted TiDB Cloud resources that have valid backups. + + When a TiDB Cloud Essential instance with existing backups is deleted, its backup files are moved to the Recycle Bin. Backup files created by automatic backups are retained in the Recycle Bin for a specified period. To avoid data loss, restore the data to a new TiDB Cloud Essential instance before the retention period expires. Note that if a TiDB Cloud Essential instance **has no backup**, the deleted instance is not displayed in the Recycle Bin. + + For more information, see [Backup and Restore](/tidb-cloud/backup-and-restore-serverless.md#restore-from-recycle-bin). + + - Top RU is now available in public preview for [TiDB Cloud Essential](/tidb-cloud/select-cluster-tier.md#essential) in the following region: + + - Alibaba Cloud: `Mexico (na-south-1)` + + This feature shows the top RU-consuming SQL statements at minute-level granularity, helping you quickly identify resource-intensive queries to reduce costs. + + The feature is rolling out in phases. To request early access, contact [support@pingcap.com](mailto:support@pingcap.com). + +## May 12, 2026 + +**General changes** + +- **TiDB Cloud Premium** + + - Add the `AVG RU/s` metric to the [TiDB Cloud Premium](https://docs.pingcap.com/tidbcloud/premium/?plan=premium) **Metrics** page. + + `AVG RU/s` displays the average number of RUs consumed per second over the selected time range, helping you better understand resource consumption. + +- **TiDB Cloud Dedicated** + + - [TiDB Cloud Dedicated](/tidb-cloud/select-cluster-tier.md#tidb-cloud-dedicated) is now generally available (GA) on Microsoft Azure in **Japan East** and **East US 2**. + + It delivers three-AZ high availability with a 99.99% uptime SLA, full HTAP powered by TiFlash, independent compute and storage scaling, fully managed operations by PingCAP SRE, seamless data import and migration, continuous backup with PITR, enterprise-grade security, and integrated observability. It also supports bulk data import, migration from MySQL and other sources, and real-time replication to downstream systems. If you use [Azure Marketplace](https://azuremarketplace.microsoft.com/), you can also subscribe to TiDB Cloud Dedicated through Azure Marketplace. + + For more information, see [From Preview to Production: TiDB Cloud Dedicated on Microsoft Azure is Now Generally Available](https://www.pingcap.com/blog/tidb-cloud-dedicated-ga-microsoft-azure/). + +## April 28, 2026 + +**General changes** + +- **TiDB Cloud Premium** + + - [TiDB Cloud Premium](https://docs.pingcap.com/tidbcloud/premium/?plan=premium) is now in public preview on AWS and Alibaba Cloud. + + Powered by the [TiDB X](/tidb-cloud/tidb-x-architecture.md) kernel, TiDB Cloud Premium is specifically designed for mission-critical enterprise workloads that require hyperscale, uncompromising performance, and the cost efficiency of a cloud-native consumption model. + + TiDB Cloud Premium bridges the gap between [TiDB Cloud Essential](/tidb-cloud/select-cluster-tier.md#essential) and [TiDB Cloud Dedicated](/tidb-cloud/select-cluster-tier.md#tidb-cloud-dedicated). + + - Compared with TiDB Cloud Essential, TiDB Cloud Premium delivers significantly stronger isolation across the compute, storage, and network layers, ensuring predictable performance for critical workloads. At the same time, it retains an elastic, on-demand scaling model, allowing compute capacity to scale independently without operational overhead. + - Compared with TiDB Cloud Dedicated, TiDB Cloud Premium improves cost efficiency by eliminating idle headroom, so you only pay for the performance you actually use. + + For more information about TiDB Cloud Premium, see [TiDB Cloud Premium: Public Preview for Mission-Critical SQL](https://www.pingcap.com/blog/tidb-cloud-premium-public-preview/). + + To try TiDB Cloud Premium, go to the [TiDB Cloud console](https://tidbcloud.com/), click **Create Resource**, and select **Premium** as your plan. For more information, see [Create a TiDB Cloud Premium instance](/tidb-cloud/premium/create-tidb-instance-premium.md). + +- **TiDB Cloud Dedicated** + + - TiProxy is now generally available for [TiDB Cloud Dedicated](/tidb-cloud/select-cluster-tier.md#tidb-cloud-dedicated) clusters on AWS. It provides enhanced connection management and load balancing to improve database reliability and performance. + + Key features of TiProxy: + + - Maintains persistent client connections during scaling operations and rolling upgrades. + - Distributes traffic evenly across TiDB nodes for better resource utilization. + + For implementation details, see [Overview of TiProxy](/tidb-cloud/tiproxy-overview-for-cloud.md). + +**Console changes** + +- Improve the firewall rule management experience for public endpoints of TiDB Cloud Starter and Essential. + + The TiDB Cloud console now provides a streamlined dialog for managing firewall rules for public endpoints in TiDB Cloud Starter and Essential. You can add your current IP address, allow access from all AWS IP addresses for AWS-hosted instances, or manually specify an IP address or IP address range in one place. + + For more information, see [Create and manage a firewall rule](/tidb-cloud/configure-serverless-firewall-rules-for-public-endpoints.md#create-and-manage-a-firewall-rule). + +**API changes** + +- Introduce TiDB Cloud Premium API (v1beta2) for managing the following resources automatically and efficiently: + + - **TiDB Cloud Premium Instance**: manage the lifecycle and configuration of TiDB Cloud Premium instances, including passwords, CA certificates, and cloud provider information. + - **Backup**: manage backups for TiDB Cloud Premium instances, including backup-based restore. + - **Region**: retrieve available regions for creating TiDB Cloud Premium instances. + + For more information, see [TiDB Cloud Premium API](https://docs.pingcap.com/tidbcloud/api/v1beta2/premium/). + +>>>>>>> d96fa6c87c (tidb-cloud: remove Chat2Query documentation (#24549)) ## April 14, 2026 **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 dce7b7587369b..d98dc02f8c868 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 84544b86e9def..c5d27546166b8 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 962e86e1ba01e..9232e673815e4 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**. @@ -48,25 +48,37 @@ 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. +<<<<<<< HEAD 3. In SQL Editor, press ⌘ + I on macOS (or Control + I on Windows or Linux) to instruct [Chat2Query (beta)](/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: +>>>>>>> d96fa6c87c (tidb-cloud: remove Chat2Query documentation (#24549)) - 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.
@@ -96,6 +108,7 @@ 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. +<<<<<<< HEAD To let AI generate more SQL statements, you can type more instructions as shown in the following example: ```sql @@ -121,6 +134,8 @@ FROM `t`; ``` +======= +>>>>>>> d96fa6c87c (tidb-cloud: remove Chat2Query documentation (#24549)) ## 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. @@ -132,6 +147,6 @@ TiDB Cloud offers an interactive tutorial with carefully crafted sample datasets ## 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). diff --git a/tidb-cloud/tidb-cloud-roadmap.md b/tidb-cloud/tidb-cloud-roadmap.md index 81e3285cd9d0e..2198d458d2373 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 (beta), 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 89334757481f374c72a732b7bf6a94b684dcb33f Mon Sep 17 00:00:00 2001 From: qiancai Date: Wed, 28 Oct 2026 18:54:49 +0800 Subject: [PATCH 2/3] restore cloud files changes --- TOC-tidb-cloud-starter.md | 8 +- TOC-tidb-cloud.md | 8 +- tidb-cloud/ai-feature-concepts.md | 6 +- tidb-cloud/connect-to-tidb-cluster.md | 8 +- 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 | 15 +- 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-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 + .../releases/tidb-cloud-release-notes.md | 710 ------------------ 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 | 37 +- 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 +++ 27 files changed, 930 insertions(+), 875 deletions(-) delete mode 100644 tidb-cloud/explore-data-with-sql-editor.md create mode 100644 tidb-cloud/use-chat2query-api.md create mode 100644 tidb-cloud/use-chat2query-knowledge.md create mode 100644 tidb-cloud/use-chat2query-sessions.md diff --git a/TOC-tidb-cloud-starter.md b/TOC-tidb-cloud-starter.md index d9c9d3adf3aa1..26cd2fc4852f9 100644 --- a/TOC-tidb-cloud-starter.md +++ b/TOC-tidb-cloud-starter.md @@ -135,15 +135,15 @@ - [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 -<<<<<<< HEAD - [Chat2Query in SQL Editor](/tidb-cloud/explore-data-with-chat2query.md) ![BETA](/media/tidb-cloud/blank_transparent_placeholder.png) -======= - - [SQL Editor](/tidb-cloud/explore-data-with-sql-editor.md) ![PREVIEW](/media/tidb-cloud/blank_transparent_placeholder.png) ->>>>>>> d96fa6c87c (tidb-cloud: remove Chat2Query documentation (#24549)) - [SQL Proxy Account](/tidb-cloud/sql-proxy-account.md) - Data Service ![BETA](/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 486b5680ce489..3937d1618705a 100644 --- a/TOC-tidb-cloud.md +++ b/TOC-tidb-cloud.md @@ -166,15 +166,15 @@ - [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 -<<<<<<< HEAD - [Chat2Query in SQL Editor](/tidb-cloud/explore-data-with-chat2query.md) ![BETA](/media/tidb-cloud/blank_transparent_placeholder.png) -======= - - [SQL Editor](/tidb-cloud/explore-data-with-sql-editor.md) ![PREVIEW](/media/tidb-cloud/blank_transparent_placeholder.png) ->>>>>>> d96fa6c87c (tidb-cloud: remove Chat2Query documentation (#24549)) - [SQL Proxy Account](/tidb-cloud/sql-proxy-account.md) - Data Service ![BETA](/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/tidb-cloud/ai-feature-concepts.md b/tidb-cloud/ai-feature-concepts.md index b3b0fcd6371f4..a9a2f62c5e548 100644 --- a/tidb-cloud/ai-feature-concepts.md +++ b/tidb-cloud/ai-feature-concepts.md @@ -5,11 +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. 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. 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. This document highlights these AI features and how they enhance the TiDB experience. -<<<<<<< HEAD ## Chat2Query (Beta) 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). @@ -17,9 +16,6 @@ Chat2Query is an AI-powered feature integrated into SQL Editor that assists user 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 (Beta) -======= -## Vector search (PREVIEW) ->>>>>>> d96fa6c87c (tidb-cloud: remove Chat2Query documentation (#24549)) 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 9cf732227be34..cfaccb722bf3c 100644 --- a/tidb-cloud/connect-to-tidb-cluster.md +++ b/tidb-cloud/connect-to-tidb-cluster.md @@ -36,19 +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-sql-editor.md) +- [Built-in SQL Editor](/tidb-cloud/explore-data-with-chat2query.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 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 AI-assisted SQL Editor in the [TiDB Cloud console](https://tidbcloud.com/) to maximize your data value. -<<<<<<< HEAD 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 (beta)](/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. ->>>>>>> d96fa6c87c (tidb-cloud: remove Chat2Query documentation (#24549)) ## What's next diff --git a/tidb-cloud/data-service-api-key.md b/tidb-cloud/data-service-api-key.md index 436996e93fd10..d2b62dfeb873a 100644 --- a/tidb-cloud/data-service-api-key.md +++ b/tidb-cloud/data-service-api-key.md @@ -51,6 +51,8 @@ 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 a3eb53ae423d5..87f7a2cba3feb 100644 --- a/tidb-cloud/data-service-app-config-files.md +++ b/tidb-cloud/data-service-app-config-files.md @@ -201,6 +201,7 @@ 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 8385d6e5fb8aa..42c735f43b0f5 100644 --- a/tidb-cloud/data-service-concepts.md +++ b/tidb-cloud/data-service-concepts.md @@ -23,6 +23,12 @@ An endpoint in [Data Service (beta)](https://tidbcloud.com/project/data-service) 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 93850d077e92b..7f6bf139a2d1c 100644 --- a/tidb-cloud/data-service-get-started.md +++ b/tidb-cloud/data-service-get-started.md @@ -7,7 +7,6 @@ summary: Learn how to use TiDB Cloud Data Service to access your data with HTTPS Data Service (beta) 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. -<<<<<<< HEAD > **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. @@ -15,9 +14,6 @@ Data Service (beta) enables you to access TiDB Cloud data via an HTTPS request u > 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 (beta) 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. -======= -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. ->>>>>>> d96fa6c87c (tidb-cloud: remove Chat2Query documentation (#24549)) ## Before you begin @@ -65,6 +61,10 @@ 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,7 +116,11 @@ You can customize SQL statements for the endpoint in the +
+ ```json { "type": "sql_endpoint", @@ -67,6 +70,51 @@ 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 @@ -231,6 +279,9 @@ This status code indicates that the request exceeds the rate limit of the API ke An example response is as follows: + +
+ ```json { "type": "", @@ -251,6 +302,33 @@ 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-sql-editor.md b/tidb-cloud/explore-data-with-sql-editor.md deleted file mode 100644 index eebbe0b0298f8..0000000000000 --- a/tidb-cloud/explore-data-with-sql-editor.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -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 (Preview) - -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 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 - -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 1cc6c65023fab..165ef498bf28d 100644 --- a/tidb-cloud/manage-user-access.md +++ b/tidb-cloud/manage-user-access.md @@ -137,8 +137,8 @@ At the project level, TiDB Cloud defines four roles, in which `Project Owner` ca | Manage resource data such as data import, data backup and restore, and data migration. | ✅ | ✅ | ❌ | ❌ | | 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-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. | ✅ | ✅ | ❌ | ❌ | +| 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. | ✅ | ✅ | ❌ | ❌ | | 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. | ✅ | ✅ | ✅ | ✅ | @@ -157,8 +157,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-sql-editor.md). | ✅ | ✅ | ❌ | ❌ | -| View instance data using [SQL Editor](/tidb-cloud/explore-data-with-sql-editor.md). | ✅ | ✅ | ✅ | ❌ | +| 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). | ✅ | ✅ | ✅ | ❌ | | 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 bd9e7a3820a23..44a12144b68cf 100644 --- a/tidb-cloud/releases/release-notes-2023.md +++ b/tidb-cloud/releases/release-notes-2023.md @@ -758,12 +758,13 @@ 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, a RESTful interface that allows you to generate and execute SQL statements using AI. + 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. 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. @@ -947,7 +948,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 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](/tidb-cloud/explore-data-with-chat2query.md) 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 fa0d5193c2639..5d5fce67213c8 100644 --- a/tidb-cloud/releases/release-notes-2024.md +++ b/tidb-cloud/releases/release-notes-2024.md @@ -257,6 +257,8 @@ 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). @@ -266,6 +268,8 @@ 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/releases/tidb-cloud-release-notes.md b/tidb-cloud/releases/tidb-cloud-release-notes.md index f753343c1d7b2..46d5d9b7ad193 100644 --- a/tidb-cloud/releases/tidb-cloud-release-notes.md +++ b/tidb-cloud/releases/tidb-cloud-release-notes.md @@ -8,716 +8,6 @@ aliases: ['/tidbcloud/supported-tidb-versions','/tidbcloud/release-notes'] This page lists the release notes of [TiDB Cloud](https://www.pingcap.com/tidb-cloud/) in 2026. -<<<<<<< HEAD -======= -## October 20, 2026 - -**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). - - You can send key performance metrics from your TiDB Cloud Essential or Premium instances to New Relic and monitor them on your existing New Relic dashboards. - - For more information, see the following documentation: - - - [Integrate TiDB Cloud Essential with New Relic (PREVIEW)](https://docs.pingcap.com/tidbcloud/monitor-new-relic-integration-for-tidb-x/?plan=essential) - - [Integrate TiDB Cloud Premium with New Relic (PREVIEW)](https://docs.pingcap.com/tidbcloud/monitor-new-relic-integration-for-tidb-x/?plan=premium) - -- **TiDB Cloud Dedicated** - - - Newly created TiDB Cloud Dedicated clusters now have public endpoints disabled by default. Existing clusters retain their current public endpoint settings. - - Before connecting to a newly created cluster over the public internet, enable **Public Endpoint** under **Settings > Networking** in the [TiDB Cloud console](https://tidbcloud.com/), and then add your client IP address to the IP access list. - - For more information, see [Connect to TiDB Cloud Dedicated via Public Connection](https://docs.pingcap.com/tidbcloud/connect-via-standard-connection/). - -- **TiDB Cloud BYOC** - - - TiDB Cloud BYOC supports vCPU limit alerts to help you better monitor resource usage and control cloud costs. - - TiDB Cloud BYOC now notifies you when provisioned vCPU usage approaches the configured regional limit or when a scale-up operation is blocked because the limit has been reached. - - These alerts provide clear guidance on available scaling capacity and recommended actions. - - For more information, see [TiDB Cloud Built-in Alerting](https://docs.pingcap.com/tidbcloud/monitor-built-in-alerting/?plan=byoc). - -## October 15, 2026 - -**General changes** - -- **TiDB Cloud Starter** - - - PostgreSQL-compatible TiDB Cloud Starter is now in public preview on AWS. - - When creating a TiDB Cloud Starter instance, you can now choose between MySQL and PostgreSQL compatibility based on your application needs and technology stack. - - PostgreSQL-compatible TiDB Cloud Starter instances support core instance management operations, including connection, monitoring, backup, and restore. It also supports pgvector-compatible vector search and selected PostgreSQL extensions, enabling you to build a wide range of applications using familiar PostgreSQL ecosystem tools and capabilities. - - Currently, the public preview of PostgreSQL-compatible TiDB Cloud Starter is intended for development and evaluation and is not recommended for production workloads. - - To get started, see [PostgreSQL-compatible TiDB Cloud Starter documentation](https://docs.pingcap.com/tidbcloud/starter/?plan=starter&compatibility=postgresql). - -- **TiDB Cloud BYOC** - - - TiDB Cloud BYOC is now in public preview on AWS. - - Powered by the TiDB X kernel, [TiDB Cloud BYOC](https://docs.pingcap.com/tidbcloud/architecture-concepts/?plan=byoc#tidb-cloud-byoc) is specifically designed for mission-critical and AI workloads that require a scalable, reliable database platform while keeping the data plane within your own cloud environment. - - TiDB Cloud BYOC combines the flexibility of customer-managed infrastructure with the operational simplicity of a managed TiDB Cloud service. - - With the data plane running directly in your AWS account and VPC, your organization retains greater control over the cloud environment, ensuring strict data isolation and seamless security integration. At the same time, PingCAP manages the control plane. This allows you to benefit from TiDB's distributed SQL capabilities, scalability, and compatibility, without the full operational burden of managing the platform yourself. - - Because TiDB Cloud BYOC is deployed in your AWS account, onboarding requires coordination with the TiDB Cloud team. To start BYOC onboarding, [contact Sales](https://www.pingcap.com/contact-us/). - - For more information, see [TiDB Cloud BYOC documentation](https://docs.pingcap.com/tidbcloud/byoc/?plan=byoc). - -- **TiDB Cloud Filesystem** - - - TiDB Cloud Filesystem is now in public preview. - - TiDB Cloud Filesystem is a distributed file system designed specifically for AI coding agents. Built on the same TiDB Cloud Starter infrastructure that already powers millions of AI agents in production, it provides Git-aware, persistent workspaces across sandbox lifecycles, with always-on availability and seamless scalability. - - To get started, see [TiDB Cloud Filesystem documentation](https://docs.pingcap.com/tidbcloud-filesystem/). - -## October 13, 2026 - -**General changes** - -- **TiDB Cloud Essential** - - - TiDB Cloud Essential now lets you create an instance or update its capacity without setting Max RCU. This feature is available for TiDB Cloud Essential instances running TiDB version `CLOUD.202603.x` or later. - - - **Elastic Mode** is the default mode when you create a new TiDB Cloud Essential instance. In this mode, TiDB Cloud automatically allocates backend resources based on your workload. For workloads that consistently require more than 100,000 RCUs, consider upgrading to TiDB Cloud Premium to avoid potential performance bottlenecks. - - If you need to set a maximum capacity limit, you can switch to **Limited Mode**. - - Existing TiDB Cloud Essential instances with a configured Max RCU continue to run without any configuration changes. You can keep the current value or clear it to switch to **Elastic Mode**. - - For more information, see [Create a TiDB Cloud Essential instance](https://docs.pingcap.com/tidbcloud/create-tidb-cluster-serverless/?plan=essential). - - - TiDB Cloud Essential now supports manual backups. These manual backups are retained until you explicitly delete them. - - This feature is available for TiDB Cloud Essential instances running TiDB version `CLOUD.202603.x` or later. - - To create a manual backup, see [Manual backups](https://docs.pingcap.com/tidbcloud/backup-and-restore-serverless/?plan=essential#manual-backups). - -- **TiDB Cloud Premium** - - - TiDB Cloud Premium now lets you create an instance or update its capacity without setting Max RCU. - - - **Elastic Mode** is the default mode when you create a new TiDB Cloud Premium instance: TiDB Cloud automatically allocates backend resources based on your workload. In Elastic Mode, you can set Baseline RCU to specify the minimum provisioned capacity and minimum billable capacity. RCU consumption alerts are supported, and you can set a custom threshold to monitor usage as capacity scales. - - If you need to set a maximum capacity limit, you can still use **Limited Mode**. - - Existing TiDB Cloud Premium instances with a configured Max RCU continue to run without any configuration changes. You can keep the current value or clear it to switch to **Elastic Mode**. - - For more information, see [Create a TiDB Cloud Premium instance](https://docs.pingcap.com/tidbcloud/create-tidb-instance-premium/?plan=premium). - -## September 29, 2026 - -**General changes** - -- **TiDB Cloud Premium** - - - TiDB Cloud Premium adds query latency count threshold alerts. - - TiDB Cloud Premium now provides three built-in alert rules that notify you when more than 20 SQL statements exceed a latency threshold of 256 ms, 512 ms, or 4096 ms within one minute. These alerts help you detect periods with unusually high numbers of slow SQL statements. - - For more information, see [TiDB Cloud Built-in Alerting](https://docs.pingcap.com/tidbcloud/built-in-monitoring-premium/?plan=premium). - -- **TiDB Cloud Dedicated** - - - TiDB Cloud Dedicated supports cross-region AWS PrivateLink connections. - - With this feature, you can create an AWS interface endpoint in one region and privately connect it to a TiDB Cloud Dedicated cluster in another region. Cross-region connections use the same connection string. - - Currently, this feature is available upon request. A cross-region PrivateLink service fee applies per added region, and removing a region does not affect existing connections. To request this feature, contact [TiDB Cloud Support](/tidb-cloud/tidb-cloud-support.md). - - For more information, see [Connect to a TiDB Cloud Dedicated Cluster via AWS PrivateLink](https://docs.pingcap.com/tidbcloud/set-up-private-endpoint-connections/). - -## September 22, 2026 - -**General changes** - -- **TiDB Cloud Dedicated** - - - [TiDB Cloud Dedicated](/tidb-cloud/select-cluster-tier.md#tidb-cloud-dedicated) now supports inbound IPv6 connectivity over AWS PrivateLink, so you can connect to your cluster over either IPv4 or IPv6. - - Currently, this feature is available upon request. To access IPv6 connectivity, contact [TiDB Cloud Support](/tidb-cloud/tidb-cloud-support.md) to request it, and then create a dual-stack AWS interface endpoint. - - For more information, see [Use IPv6 connectivity over a private endpoint](https://docs.pingcap.com/tidbcloud/set-up-private-endpoint-connections#use-ipv6-connectivity-over-a-private-endpoint). - -## September 15, 2026 - -**General changes** - -* **TiDB Cloud CLI** - - [TiDB Cloud CLI (`ti`)](https://github.com/tidbcloud/ti-cli) is now available in public preview for managing [TiDB Cloud Starter](/tidb-cloud/select-cluster-tier.md#starter) instances and file systems in TiDB Cloud Filesystem. TiDB Cloud Filesystem is a serverless distributed file system designed for AI agents and automation workloads. - - You can use `ti` directly or let your scripts, CI jobs, and AI agents run it to automate TiDB Cloud workflows. With `ti`, you can create and manage TiDB Cloud Starter instances, execute SQL statements, and create and access persistent file system workspaces through file commands or supported mounts. JSON output by default, JMESPath output queries, and support for `--wait` and `--dry-run` on applicable commands simplify automation. - - For more information, see [Get Started with TiDB Cloud CLI](/ai/ti/ti-quick-start.md) and [TiDB Cloud CLI (`ti`) Overview](/ai/ti/ti-overview.md). - -## September 8, 2026 - -**Console changes** - -- **TiDB Cloud Essential** - - - [TiDB Cloud Essential](/tidb-cloud/select-cluster-tier.md#essential) instances that include the enhancements announced on [June 30, 2026](#june-30-2026) now display `CLOUD.202603.x` as their TiDB version on the instance overview page in the TiDB Cloud console. - - For more information about these enhancements, see the [June 30, 2026 release notes](#june-30-2026). - -**API changes** - -- **TiDB Cloud Premium** - - - Introduce the changefeed API endpoints for [TiDB Cloud Premium](/tidb-cloud/select-cluster-tier.md#premium), providing programmatic management of change data capture (CDC) changefeeds. - - You can use these endpoints to create, list, get, delete, pause, resume, and scale changefeeds for real-time data replication to downstream systems, including Apache Kafka, MySQL, Amazon S3, and Alibaba Cloud OSS. - - For more information, see [Changefeed API v1beta2 Reference](https://docs.pingcap.com/tidbcloud/api/v1beta2/premium/#tag/Changefeed). - -## September 1, 2026 - -**General changes** - -- **TiDB Cloud Essential** - - - TiDB Cloud Essential now lets you temporarily authorize TiDB Cloud Support to access Plan Replayer files for SQL performance troubleshooting. - - You can choose the access duration, extend it if needed, or revoke access at any time. Access is automatically revoked when the authorization expires. - - Plan Replayer files contain SQL text, table schemas, and optimizer statistics, but no actual table row data. - - For more information, see [Use Plan Replayer to Troubleshoot SQL Performance](https://docs.pingcap.com/tidbcloud/plan-replayer/?plan=essential). - -- **TiDB Cloud Premium** - - - The **Events** page is now available for TiDB Cloud Premium instances. - - You can view historical events that record changes to your Premium instance on this page, along with information such as the event type, status, message, trigger time, and trigger user. Event data is retained for 7 days. - - For more information, see [Events](https://docs.pingcap.com/tidbcloud/tidb-cloud-events/?plan=premium). - - - TiDB Cloud Premium now lets you configure filter rules for database audit logging. - - You can filter audit events by SQL user, event class, table, and execution status to control which database activities are logged, helping you focus on relevant events for security auditing and compliance. - - For more information, see [Specify audit filter rules](https://docs.pingcap.com/tidbcloud/tidb-cloud-auditing-premium/?plan=premium#specify-audit-filter-rules). - - - TiDB Cloud Premium now lets you temporarily authorize TiDB Cloud Support to access Plan Replayer files for SQL performance troubleshooting. - - You can choose the access duration, extend it if needed, or revoke access at any time. Access is automatically revoked when the authorization expires. - - Plan Replayer files contain SQL text, table schemas, and optimizer statistics, but no actual table row data. - - For more information, see [Use Plan Replayer to Troubleshoot SQL Performance](https://docs.pingcap.com/tidbcloud/plan-replayer/?plan=premium). - -**Billing adjustments** - -- **TiDB Cloud Essential** - - - Starting September 1, 2026, billing for backup usage and network egress on [TiDB Cloud Essential](/tidb-cloud/select-cluster-tier.md#essential) instances is gradually taking effect. - - Network egress is billed as a separate line item rather than being included in RCU charges. - - For more information, see [TiDB Cloud Essential Pricing Details](https://www.pingcap.com/tidb-cloud-essential-pricing-details/). - -## August 28, 2026 - -**General changes** - -- **TiDB Cloud Dedicated** - - - Upgrade the default TiDB version of new [TiDB Cloud Dedicated](/tidb-cloud/select-cluster-tier.md#tidb-cloud-dedicated) clusters from [v8.5.7](https://docs.pingcap.com/tidb/stable/release-8.5.7/) to [v8.5.8](https://docs.pingcap.com/tidb/stable/release-8.5.8/). - -## August 25, 2026 - -**General changes** - -- **TiDB Cloud Premium** - - - TiDB Cloud Premium now supports streaming changefeed data directly to Amazon S3 and Alibaba Cloud Object Storage Service (OSS). - - This feature enables you to archive change data to cloud storage for downstream analytics and long-term retention, while reducing costs by eliminating the need for intermediate message queues. - - For more information, see [Sink to Cloud Storage](https://docs.pingcap.com/tidbcloud/changefeed-sink-to-cloud-storage/?plan=premium). - -## August 18, 2026 - -**General changes** - -- **TiDB Cloud Premium** - - - Introduce **Statement Insight** (PREVIEW) for TiDB Cloud Premium instances. - - This feature provides an actionable view into SQL resource consumption in your TiDB Cloud Premium instances. - - Now you can analyze RU consumption, latency, and execution counts of SQL statements in multiple dimensions, such as DB User, SQL type, DB, table, or SQL digest. In addition, you can see top contributors at a glance, making it easier to identify the sources of high resource consumption or slowdowns. - - Currently, this feature is in public preview and available only for a limited number of TiDB Cloud Premium instances created on or after August 19. - - For more information, see [Statement Insight (PREVIEW)](https://docs.pingcap.com/tidbcloud/statement-insight/?plan=premium). - -- **TiDB Cloud Lake** - - - [TiDB Cloud Lake](https://docs.pingcap.com/tidbcloudlake/) is now available on Alibaba Cloud in Japan (Tokyo) (`ap-northeast-1`). - - For more supported regions, see [Platforms & Regions](https://docs.pingcap.com/tidbcloudlake/platforms-regions/). - - - Expand Python extensibility and analytics engineering workflows for TiDB Cloud Lake with the new external Python UDF SDK and dbt adapter. - - - With the new external Python UDF SDK, you can implement custom scalar and table functions in Python, deploy them on a UDF server, register the endpoint in TiDB Cloud Lake, and call the functions directly from SQL. The SDK supports common and complex data types, NULL handling, I/O parallelism, and per-function concurrency controls. - - With the new dbt adapter, you can connect dbt to TiDB Cloud Lake to build, test, and document data transformation workflows. The adapter supports table, view, and incremental materializations, as well as seeds, sources, custom data tests, documentation generation, snapshots, and connection retries. - - For more information, see the following documentation: - - - [External Function](https://docs.pingcap.com/tidbcloudlake/external-function/) - - [Choose a User-Defined Function Type](https://docs.pingcap.com/tidbcloudlake/choose-a-udf-type/) - - [Load Data with dbt](https://docs.pingcap.com/tidbcloudlake/load-with-dbt/) - -## August 11, 2026 - -**General changes** - -- **TiDB Cloud Essential, Premium, and Dedicated** - - - Support subscribing to alert notifications from TiDB Cloud via [Lark](https://www.larksuite.com/). - - If the [support plan](/tidb-cloud/connected-care-overview.md#connected-care) of your organization is **Enterprise** or **Premium**, you can now receive alert notifications via Lark. - - For more information, see the following documentation: - - - TiDB Cloud Essential: [Subscribe via Lark](https://docs.pingcap.com/tidbcloud/monitor-alert-lark/?plan=essential) - - TiDB Cloud Premium: [Subscribe via Lark](https://docs.pingcap.com/tidbcloud/monitor-alert-lark/?plan=premium) - - TiDB Cloud Dedicated: [Subscribe via Lark](https://docs.pingcap.com/tidbcloud/monitor-alert-lark/) - -- **TiDB Cloud Lake** - - - Expand AI, Python, and BI integrations for [TiDB Cloud Lake](https://docs.pingcap.com/tidbcloudlake/) with the new MCP server and SQLAlchemy dialect. - - - With the new MCP server, you can now connect MCP-compatible AI tools to explore database objects, inspect table schemas, and run SQL using natural-language instructions. Built-in session sandbox protection is enabled by default, keeping production objects read-only while restricting writes to session-specific sandbox objects. - - With the new SQLAlchemy dialect, you can connect Python applications and SQLAlchemy-compatible tools to TiDB Cloud Lake through the dialect. You can use tools such as Jupyter Notebook for querying and visualizing data, and Apache Superset for building charts and dashboards. - - For more information, see the following documentation: - - - [TiDB Cloud Lake MCP Server](https://docs.pingcap.com/tidbcloudlake/mcp-server) - - [Connect AI Tools to TiDB Cloud Lake Using MCP](https://docs.pingcap.com/tidbcloudlake/mcp-client-integration) - - [Connect to TiDB Cloud Lake with Jupyter Notebook](https://docs.pingcap.com/tidbcloudlake/jupyter-notebook) - - [Connect to TiDB Cloud Lake with Apache Superset](https://docs.pingcap.com/tidbcloudlake/superset) - -**Console changes** - -- Improve the networking experience across TiDB Cloud plans with the following updates in the [TiDB Cloud console](https://tidbcloud.com/): - - - The **Networking** page now uses more consistent naming for endpoint configurations across TiDB Cloud plans. - - For endpoint types with no configured endpoints, the **Networking** page now displays only the corresponding action button instead of an empty table. - - For TiDB Cloud Starter and Essential instances, you can now click **Connect** in the upper-right corner of the **Networking** page to connect to your instance after configuring network access. - - For TiDB Cloud Essential, Premium, and Dedicated, managing allowed IP addresses for public endpoints is now more intuitive. You can click **Add IP Address** to add an IP address, or click **...** for an existing IP address to edit or delete it. - -## August 5, 2026 - -**General changes** - -- **TiDB Cloud Premium** - - - Introduce **Custom Retention Mode** for automatic backups on TiDB Cloud Premium instances. - - TiDB Cloud Premium now offers two automatic backup modes: - - - **Custom Retention Mode:** lets you specify the retention period from 3 to 33 days and choose when daily snapshots are created. - - **Standard Bundle Mode:** preserves the previous default automatic backup settings for PITR, hourly snapshots, and daily snapshots. - - For more information, see [Automatic backup modes](/tidb-cloud/premium/backup-and-restore-premium.md#automatic-backup-modes). - -## August 4, 2026 - -**General changes** - -- **TiDB Cloud Essential** - - - Support subscribing to alert notifications from TiDB Cloud Essential via generic webhooks. - - If the [support plan](/tidb-cloud/connected-care-overview.md#connected-care) of your organization is **Enterprise** or **Premium**, you can now receive alert notifications via a generic webhook. For services that require custom payload formats, such as Telegram or Microsoft Teams, use a lightweight relay to transform and forward the notifications. - - For more information, see [Subscribe via Webhook](https://docs.pingcap.com/tidbcloud/monitor-alert-webhook/?plan=essential). - -- **TiDB Cloud Premium** - - - Support [Amazon MSK Provisioned](https://docs.aws.amazon.com/msk/latest/developerguide/msk-provisioned.html) clusters as changefeed sinks for TiDB Cloud Premium instances. - - For TiDB Cloud Premium instances hosted on AWS, you can now stream row change events to Amazon MSK Provisioned clusters over AWS PrivateLink. - - For more information, see [Set Up Private Endpoint for Changefeeds](/tidb-cloud/premium/set-up-sink-private-endpoint-premium.md) and [Set Up an Amazon MSK Provisioned Cluster via AWS PrivateLink](/tidb-cloud/setup-aws-msk-provisioned-private-link-service.md). - - - Support subscribing to alert notifications from TiDB Cloud Premium via generic webhooks. - - If the [support plan](/tidb-cloud/connected-care-overview.md#connected-care) of your organization is **Enterprise** or **Premium**, you can now receive alert notifications via a generic webhook. For services that require custom payload formats, such as Telegram or Microsoft Teams, use a lightweight relay to transform and forward the notifications. - - For more information, see [Subscribe via Webhook](https://docs.pingcap.com/tidbcloud/monitor-alert-webhook/?plan=premium). - -- **TiDB Cloud Dedicated** - - - Update pause requirements for TiDB Cloud Dedicated clusters. - - Before [pausing a TiDB Cloud Dedicated cluster](/tidb-cloud/pause-or-resume-tidb-cluster.md), you must turn off [Point-in-Time Restore (PITR)](/tidb-cloud/backup-and-restore.md#turn-on-point-in-time-restore) and ensure that no Data Migration (DM) job is running. If either condition is not met, TiDB Cloud rejects the pause request and displays an error message. - - - Support subscribing to alert notifications from TiDB Cloud Dedicated via generic webhooks. - - If the [support plan](/tidb-cloud/connected-care-overview.md#connected-care) of your organization is **Enterprise** or **Premium**, you can now receive alert notifications via a generic webhook. For services that require custom payload formats, such as Telegram or Microsoft Teams, use a lightweight relay to transform and forward the notifications. - - For more information, see [Subscribe via Webhook](https://docs.pingcap.com/tidbcloud/monitor-alert-webhook/). - -## July 28, 2026 - -**General changes** - -- **TiDB Cloud Dedicated** - - - Database audit logging is now available in public preview for [TiDB Cloud Dedicated](/tidb-cloud/select-cluster-tier.md#tidb-cloud-dedicated) clusters running TiDB v7.5.6 or later, or v8.5.2 or later. - - This feature records user access activities, including executed SQL statements, supports writing audit logs to Amazon S3, Google Cloud Storage (GCS), or Azure Blob Storage, and lets you configure filter rules to control which events are captured for specific SQL users. - - For more information, see [TiDB Cloud Dedicated Database Audit Logging (Preview)](/tidb-cloud/tidb-cloud-auditing.md). - -## July 21, 2026 - -**General changes** - -- **TiDB Cloud Essential** - - - [Top RU](/tidb-cloud/top-ru.md) (public preview) for [TiDB Cloud Essential](/tidb-cloud/select-cluster-tier.md#essential) now supports the following additional region: - - - Alibaba Cloud: `Jakarta (ap-southeast-5)` - - This feature displays minute-level top RU-consuming SQLs, helping you quickly identify the most resource-intensive queries to reduce costs. - -## July 14, 2026 - -**General changes** - -- **TiDB Cloud Dedicated** - - - Enhance cross-region restore for [TiDB Cloud Dedicated](/tidb-cloud/select-cluster-tier.md#tidb-cloud-dedicated). - - When the target restore region has no pre-allocated CIDR block, you can now create a CIDR block directly on the **Restore** page, eliminating the need to manually create a cluster in that region before starting the restore. - -## July 9, 2026 - -**General changes** - -- **TiDB Cloud Dedicated** - - - Upgrade the default TiDB version of new [TiDB Cloud Dedicated](/tidb-cloud/select-cluster-tier.md#tidb-cloud-dedicated) clusters from [v8.5.6](https://docs.pingcap.com/tidb/stable/release-8.5.6/) to [v8.5.7](https://docs.pingcap.com/tidb/stable/release-8.5.7/). - -## July 7, 2026 - -**General changes** - -- **TiDB Cloud Essential** - - - Support the Datadog integration (public preview). - - You can now configure TiDB Cloud to send key metrics from your [TiDB Cloud Essential](/tidb-cloud/select-cluster-tier.md#essential) instances to [Datadog](https://www.datadoghq.com/) for centralized monitoring and alerting. - - For more information, see [Integrate TiDB Cloud with Datadog](https://docs.pingcap.com/tidbcloud/monitor-datadog-integration-for-tidb-x/?plan=essential). - -- **TiDB Cloud Premium** - - - Support the Datadog integration (public preview). - - You can now configure TiDB Cloud to send key metrics from your [TiDB Cloud Premium](/tidb-cloud/select-cluster-tier.md#premium) instances to [Datadog](https://www.datadoghq.com/) for centralized monitoring and alerting. - - For more information, see [Integrate TiDB Cloud with Datadog](https://docs.pingcap.com/tidbcloud/monitor-datadog-integration-for-tidb-x/?plan=premium). - -**Console changes** - -- Standardize the label used in the [TiDB Cloud console](https://tidbcloud.com/) for public preview features as `PREVIEW`, replacing the previous mixed use of `BETA` and `PREVIEW`. - -**API changes** - -- **TiDB Cloud Dedicated** - - - Introduce the changefeed API endpoints for [TiDB Cloud Dedicated](/tidb-cloud/select-cluster-tier.md#tidb-cloud-dedicated), providing programmatic management of change data capture (CDC) changefeeds. - - You can use these endpoints to create, list, get, delete, pause, resume, and scale changefeeds for real-time data replication to downstream systems, including Apache Kafka, MySQL, Amazon S3, Google Cloud Storage (GCS), and Azure Blob Storage. - - For more information, see [Changefeed API v1beta1 Reference](https://docs.pingcap.com/tidbcloud/api/v1beta1/dedicated/#tag/Changefeed). - -## June 30, 2026 - -**General changes** - -- **TiDB Cloud Essential** - - - Enhance the stability, security, and operational experience of [TiDB Cloud Essential](/tidb-cloud/select-cluster-tier.md#essential). The following enhancements and changes are rolling out gradually to newly created TiDB Cloud Essential instances. - - - **Improve the connection experience**: support standalone endpoints for newly created TiDB Cloud Essential instances, so you no longer need to include the mandatory [account prefix](/tidb-cloud/select-cluster-tier.md#user-name-prefix) when connecting to these instances. - - **Support changing the root password**: you can change the root password directly from the TiDB Cloud console. - - **Enhance the data import experience**: after entering the source destination fields on the import data page, you can click **Test Bucket Access** to verify access to the specified object storage bucket before importing data. In addition, the import page now displays the size of files to be imported to improve visibility and management of import operations. - - **Update the availability of the Branch feature**: starting from **July 14, 2026**, newly created TiDB Cloud Essential instances no longer support the [Branch](/tidb-cloud/branch-overview.md) feature. Existing TiDB Cloud Essential instances created before this date are not affected. The Branch feature remains available in [TiDB Cloud Starter](/tidb-cloud/select-cluster-tier.md#starter). - - **Update import and export capabilities**: to enhance security, importing data from local files and exporting data to local files are no longer supported. - - **Update DB audit log storage requirements**: for security and compliance reasons, you must specify an external storage location for audit log retention. - - [Changefeed](/tidb-cloud/essential-changefeed-overview.md) will be available as a billable feature starting from **July 1, 2026**. - - These features are rolling out in phases. Contact [support@pingcap.com](mailto:support@pingcap.com) for early access. - - - [Top RU](/tidb-cloud/top-ru.md) is now available in public preview for [TiDB Cloud Essential](/tidb-cloud/select-cluster-tier.md#essential) in the following regions: - - - Alibaba Cloud: `Singapore (ap-southeast-1)` and `Tokyo (ap-northeast-1)` - - This feature displays minute-level top RU-consuming SQL statements, helping you quickly identify the most resource-intensive queries to reduce costs. - - This feature is rolling out in phases. Contact [support@pingcap.com](mailto:support@pingcap.com) for early access. - -- **TiDB Cloud Dedicated** - - - Refine the backup and restore flow for [TiDB Cloud Dedicated](/tidb-cloud/select-cluster-tier.md#tidb-cloud-dedicated) clusters. - - - The **Restore** page for TiDB Cloud Dedicated no longer includes the **Restore From Region** option. Because TiDB Cloud Dedicated implicitly stores backup data in the same region as the cluster, you no longer need to select the region to restore from. - - The **Restore to Region** option is renamed to **Cloud Provider & Region**. - - For more information, see [Restore data to a new cluster](/tidb-cloud/backup-and-restore.md). - -- **TiDB Cloud Lake** - - - TiDB Cloud Lake is now in public preview. - - TiDB Cloud Lake is a cloud-native analytics warehouse in TiDB Cloud for modern analytics and AI-oriented data workflows. It provides elastic warehouses, ANSI SQL analytics, object storage, full-text search, vector search, and geospatial analysis in one managed service, helping teams analyze structured and semi-structured data without managing separate analytics infrastructure. - - With this public preview, you can run SQL analytics with elastic warehouses and use built-in search capabilities for BI, log analytics, semantic retrieval, and other modern analytics and AI use cases. - - To try TiDB Cloud Lake, log in to the [TiDB Cloud console](https://tidbcloud.com/), click **My Lake** in the left navigation pane, and then click **Try TiDB Cloud Lake** in the upper-right corner. - - For more information, see [TiDB Cloud Lake documentation](https://docs.pingcap.com/tidbcloudlake/). - -**Upcoming billing adjustments** - -- The following billing adjustments will take effect for [TiDB Cloud Essential](/tidb-cloud/select-cluster-tier.md#essential): - - - **Minimum RCU billing updates**: starting from **August 1, 2026**, the minimum RCU value is automatically determined based on your configured maximum RCU value (Minimum RCU = 0.1 × configured maximum RCU, with a lower bound of 2,000 RCUs). If your actual usage remains below the minimum RCU threshold, TiDB Cloud calculates charges based on the minimum RCU value. For **existing instances created before July 1, 2026**, the implementation of this minimum RCU billing policy is postponed, and the exact effective date will be announced later. - - **Additional billable features**: charges for backup usage and network egress will take effect on **September 1, 2026**. For more information, see [TiDB Cloud Essential pricing](https://www.pingcap.com/tidb-cloud-essential-pricing-details/). - -## June 16, 2026 - -**General changes** - -- Add domain verification for [Cloud Organization SSO](/tidb-cloud/tidb-cloud-org-sso-authentication.md). - - In the following scenarios, the **Allowed Email Domains** field is required. To improve security, you must verify domains before entering them in this field: - - - Enabling auto-provisioning for the OIDC or SAML authentication method - - Enabling SCIM provisioning for the SAML authentication method - - For more information, see [Add and verify domains for OIDC and SAML](/tidb-cloud/tidb-cloud-org-sso-authentication.md#add-and-verify-domains-for-oidc-and-saml). - -## June 9, 2026 - -**General changes** - -- **TiDB Cloud Starter** - - - Add a new AWS region for [full-text search](https://docs.pingcap.com/ai/vector-search-full-text-search-python/) (public preview) on [TiDB Cloud Starter](/tidb-cloud/select-cluster-tier.md#starter): `N. Virginia (us-east-1)`. The feature is now available in the following AWS regions: - - - `Tokyo (ap-northeast-1)` - - `Oregon (us-west-2)` - - `N. Virginia (us-east-1)` - - `Frankfurt (eu-central-1)` - - `Singapore (ap-southeast-1)` - - - -**High availability changes** - -- **TiDB Cloud Essential** - - - Starting from June 9, 2026, newly created [TiDB Cloud Essential](/tidb-cloud/select-cluster-tier.md#essential) instances are deployed in a single Availability Zone and do not support regional high availability. - - If you need regional high availability and cross-AZ failover, consider choosing [TiDB Cloud Premium](/tidb-cloud/select-cluster-tier.md#premium). - - This change does not affect TiDB Cloud Essential instances created before June 9, 2026. - - - -**API changes** - -- **TiDB Cloud Premium** - - - Introduce the following backup API endpoints for [TiDB Cloud Premium](/tidb-cloud/select-cluster-tier.md#premium), enabling unified management for both active and deleted instances within your organization. - - - [List backups](https://docs.pingcap.com/tidbcloud/api/v1beta2/premium/#tag/Backup/operation/BackupService_ListBackups): lists backups for both active and deleted TiDB Cloud Premium instances (in the recycle bin) within your organization. - - [Delete a backup](https://docs.pingcap.com/tidbcloud/api/v1beta2/premium/#tag/Backup/operation/BackupService_DeleteBackup): deletes a specific backup within your organization by `backupId`. - -## June 2, 2026 - -**General changes** - -- **TiDB Cloud Starter** - - - Introduce the [Instance Capacity Plan](https://www.pingcap.com/programs/agentic-ai-instance-capacity) for organizations that require a large number of [TiDB Cloud Starter](/tidb-cloud/select-cluster-tier.md#starter) instances and branches. - - By default, for each paid organization in TiDB Cloud, you can create up to 100 TiDB Cloud Starter instances and branches in total, with each branch counted as a separate instance. To exceed this limit, apply for the [Instance Capacity Plan](https://www.pingcap.com/programs/agentic-ai-instance-capacity). - -- **TiDB Cloud Essential** - - - Top RU is now available in public preview for [TiDB Cloud Essential](/tidb-cloud/select-cluster-tier.md#essential) in the following regions: - - - AWS: `N. Virginia (us-east-1)`, `Tokyo (ap-northeast-1)` - - This feature displays minute-level top RU-consuming SQL statements, helping you quickly identify the most resource-intensive queries to reduce costs. - - This feature is rolling out in phases. Contact [support@pingcap.com](mailto:support@pingcap.com) for early access. - -- **TiDB Cloud Premium** - - - Support Dual-Layer Data Encryption on Alibaba Cloud for [TiDB Cloud Premium](/tidb-cloud/select-cluster-tier.md#premium) instances. - - You can use your own keys in Alibaba Cloud Key Management Service (KMS) to encrypt data at rest, giving you greater control over data security and compliance. - - This feature is now available upon request. For more information, see [Dual-Layer Data Encryption](/tidb-cloud/premium/dual-layer-data-encryption-premium.md). - - - Provide two new TTL monitoring metrics on the **Metrics** page (**Instance Overview** tab) for TiDB Cloud Premium instances. - - - Table Count by TTL Schedule Delay - - TTL Insert/Delete Rows by Day - - These metrics help you observe TTL job health and detect data retention issues. For more information, see [{{{ .premium }}} Built-in Metrics](/tidb-cloud/premium/built-in-monitoring-premium.md). - -**API changes** - -- **TiDB Cloud Starter** - - - For a paid organization not enrolled in the [Instance Capacity Plan](https://www.pingcap.com/programs/agentic-ai-instance-capacity), TiDB Cloud API now enforces a limit of 100 TiDB Cloud Starter instances and branches in total, with each branch counted as a separate instance. - - - When the limit is reached, API requests to create new TiDB Cloud Starter instances or branches are rejected. - - To exceed this limit, apply for the [Instance Capacity Plan](https://www.pingcap.com/programs/agentic-ai-instance-capacity). - -## May 26, 2026 - -**General changes** - -- **TiDB Cloud Starter** - - - Add two new AWS regions for [full-text search](https://docs.pingcap.com/ai/vector-search-full-text-search-python/) (public preview) on [TiDB Cloud Starter](/tidb-cloud/select-cluster-tier.md#starter): `Tokyo (ap-northeast-1)` and `Oregon (us-west-2)`. The feature is now available in the following AWS regions: - - - `Tokyo (ap-northeast-1)` - - `Oregon (us-west-2)` - - `Frankfurt (eu-central-1)` - - `Singapore (ap-southeast-1)` - -- **TiDB Cloud Essential** - - - Top RU is now available in public preview for [TiDB Cloud Essential](/tidb-cloud/select-cluster-tier.md#essential) in the following regions: - - - AWS: `Oregon (us-west-2)`, `Frankfurt (eu-central-1)`, `Singapore (ap-southeast-1)` - - This feature shows the top RU-consuming SQL statements at minute-level granularity, helping you quickly identify resource-intensive queries to reduce costs. - - The feature is rolling out in phases. To request early access, contact [support@pingcap.com](mailto:support@pingcap.com). - -**API changes** - -- TiDB Cloud IAM API (v1beta1) supports managing organization members programmatically. - - The new `/members` endpoints let you manage organization membership and role assignments. You can use these endpoints to automate user lifecycle management tasks, such as onboarding new members with specific roles, adjusting permissions as responsibilities change, and removing members who leave the organization. - - For more information, see [TiDB Cloud IAM API](https://docs.pingcap.com/tidbcloud/api/v1beta1/iam/#tag/Member). - -## May 19, 2026 - -**General changes** - -- **TiDB Cloud Essential** - - - Recycle Bin is now available for [TiDB Cloud Essential](/tidb-cloud/select-cluster-tier.md#essential). It stores data of deleted TiDB Cloud resources that have valid backups. - - When a TiDB Cloud Essential instance with existing backups is deleted, its backup files are moved to the Recycle Bin. Backup files created by automatic backups are retained in the Recycle Bin for a specified period. To avoid data loss, restore the data to a new TiDB Cloud Essential instance before the retention period expires. Note that if a TiDB Cloud Essential instance **has no backup**, the deleted instance is not displayed in the Recycle Bin. - - For more information, see [Backup and Restore](/tidb-cloud/backup-and-restore-serverless.md#restore-from-recycle-bin). - - - Top RU is now available in public preview for [TiDB Cloud Essential](/tidb-cloud/select-cluster-tier.md#essential) in the following region: - - - Alibaba Cloud: `Mexico (na-south-1)` - - This feature shows the top RU-consuming SQL statements at minute-level granularity, helping you quickly identify resource-intensive queries to reduce costs. - - The feature is rolling out in phases. To request early access, contact [support@pingcap.com](mailto:support@pingcap.com). - -## May 12, 2026 - -**General changes** - -- **TiDB Cloud Premium** - - - Add the `AVG RU/s` metric to the [TiDB Cloud Premium](https://docs.pingcap.com/tidbcloud/premium/?plan=premium) **Metrics** page. - - `AVG RU/s` displays the average number of RUs consumed per second over the selected time range, helping you better understand resource consumption. - -- **TiDB Cloud Dedicated** - - - [TiDB Cloud Dedicated](/tidb-cloud/select-cluster-tier.md#tidb-cloud-dedicated) is now generally available (GA) on Microsoft Azure in **Japan East** and **East US 2**. - - It delivers three-AZ high availability with a 99.99% uptime SLA, full HTAP powered by TiFlash, independent compute and storage scaling, fully managed operations by PingCAP SRE, seamless data import and migration, continuous backup with PITR, enterprise-grade security, and integrated observability. It also supports bulk data import, migration from MySQL and other sources, and real-time replication to downstream systems. If you use [Azure Marketplace](https://azuremarketplace.microsoft.com/), you can also subscribe to TiDB Cloud Dedicated through Azure Marketplace. - - For more information, see [From Preview to Production: TiDB Cloud Dedicated on Microsoft Azure is Now Generally Available](https://www.pingcap.com/blog/tidb-cloud-dedicated-ga-microsoft-azure/). - -## April 28, 2026 - -**General changes** - -- **TiDB Cloud Premium** - - - [TiDB Cloud Premium](https://docs.pingcap.com/tidbcloud/premium/?plan=premium) is now in public preview on AWS and Alibaba Cloud. - - Powered by the [TiDB X](/tidb-cloud/tidb-x-architecture.md) kernel, TiDB Cloud Premium is specifically designed for mission-critical enterprise workloads that require hyperscale, uncompromising performance, and the cost efficiency of a cloud-native consumption model. - - TiDB Cloud Premium bridges the gap between [TiDB Cloud Essential](/tidb-cloud/select-cluster-tier.md#essential) and [TiDB Cloud Dedicated](/tidb-cloud/select-cluster-tier.md#tidb-cloud-dedicated). - - - Compared with TiDB Cloud Essential, TiDB Cloud Premium delivers significantly stronger isolation across the compute, storage, and network layers, ensuring predictable performance for critical workloads. At the same time, it retains an elastic, on-demand scaling model, allowing compute capacity to scale independently without operational overhead. - - Compared with TiDB Cloud Dedicated, TiDB Cloud Premium improves cost efficiency by eliminating idle headroom, so you only pay for the performance you actually use. - - For more information about TiDB Cloud Premium, see [TiDB Cloud Premium: Public Preview for Mission-Critical SQL](https://www.pingcap.com/blog/tidb-cloud-premium-public-preview/). - - To try TiDB Cloud Premium, go to the [TiDB Cloud console](https://tidbcloud.com/), click **Create Resource**, and select **Premium** as your plan. For more information, see [Create a TiDB Cloud Premium instance](/tidb-cloud/premium/create-tidb-instance-premium.md). - -- **TiDB Cloud Dedicated** - - - TiProxy is now generally available for [TiDB Cloud Dedicated](/tidb-cloud/select-cluster-tier.md#tidb-cloud-dedicated) clusters on AWS. It provides enhanced connection management and load balancing to improve database reliability and performance. - - Key features of TiProxy: - - - Maintains persistent client connections during scaling operations and rolling upgrades. - - Distributes traffic evenly across TiDB nodes for better resource utilization. - - For implementation details, see [Overview of TiProxy](/tidb-cloud/tiproxy-overview-for-cloud.md). - -**Console changes** - -- Improve the firewall rule management experience for public endpoints of TiDB Cloud Starter and Essential. - - The TiDB Cloud console now provides a streamlined dialog for managing firewall rules for public endpoints in TiDB Cloud Starter and Essential. You can add your current IP address, allow access from all AWS IP addresses for AWS-hosted instances, or manually specify an IP address or IP address range in one place. - - For more information, see [Create and manage a firewall rule](/tidb-cloud/configure-serverless-firewall-rules-for-public-endpoints.md#create-and-manage-a-firewall-rule). - -**API changes** - -- Introduce TiDB Cloud Premium API (v1beta2) for managing the following resources automatically and efficiently: - - - **TiDB Cloud Premium Instance**: manage the lifecycle and configuration of TiDB Cloud Premium instances, including passwords, CA certificates, and cloud provider information. - - **Backup**: manage backups for TiDB Cloud Premium instances, including backup-based restore. - - **Region**: retrieve available regions for creating TiDB Cloud Premium instances. - - For more information, see [TiDB Cloud Premium API](https://docs.pingcap.com/tidbcloud/api/v1beta2/premium/). - ->>>>>>> d96fa6c87c (tidb-cloud: remove Chat2Query documentation (#24549)) ## April 14, 2026 **General changes** diff --git a/tidb-cloud/sql-proxy-account.md b/tidb-cloud/sql-proxy-account.md index 7adaa9b952717..052c80e91a865 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-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. +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. 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 d98dc02f8c868..dce7b7587369b 100644 --- a/tidb-cloud/tidb-cloud-glossary.md +++ b/tidb-cloud/tidb-cloud-glossary.md @@ -23,6 +23,12 @@ 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 c5d27546166b8..84544b86e9def 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 SQL Editor](/tidb-cloud/explore-data-with-sql-editor.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 AI-assisted SQL Editor](/tidb-cloud/explore-data-with-chat2query.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 9232e673815e4..962e86e1ba01e 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 SQL Editor](#step-2-try-sql-editor). + - 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 create a new {{{ .starter }}} instance on your own, follow these steps: 1. Click **Create Resource**. @@ -48,37 +48,25 @@ Additionally, you can try out TiDB features on [TiDB Playground](https://play.ti -## Step 2: Try SQL Editor +## Step 2: Try AI-assisted SQL Editor -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. +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. 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. Write SQL queries in SQL Editor. +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**. -<<<<<<< HEAD 3. In SQL Editor, press ⌘ + I on macOS (or Control + I on Windows or Linux) to instruct [Chat2Query (beta)](/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: ->>>>>>> d96fa6c87c (tidb-cloud: remove Chat2Query documentation (#24549)) - ```sql - USE test; + 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. - -- create a new table t with id and name - CREATE TABLE `t` (`id` INT, `name` VARCHAR(255)); + For the generated statement, you can accept it by clicking **Accept** and then further edit it if needed, or reject it by clicking **Discard**. - -- add 3 rows - INSERT INTO `t` (`id`, `name`) VALUES - (1, 'row1'), - (2, 'row2'), - (3, 'row3'); + > **Note:** + > + > SQL queries generated by AI are not 100% accurate and might still require further tweaking. - -- query all - SELECT `id`, `name` FROM `t`; - ``` - -3. Run the SQL queries. +4. Run the SQL queries.
@@ -108,7 +96,6 @@ For {{{ .starter }}} instances hosted on AWS, you can use the built-in SQL Edito After running the queries, you can immediately see the query logs and results at the bottom of the page. -<<<<<<< HEAD To let AI generate more SQL statements, you can type more instructions as shown in the following example: ```sql @@ -134,8 +121,6 @@ FROM `t`; ``` -======= ->>>>>>> d96fa6c87c (tidb-cloud: remove Chat2Query documentation (#24549)) ## 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,6 +132,6 @@ TiDB Cloud offers an interactive tutorial with carefully crafted sample datasets ## 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 to explore your data, see [Explore your data with SQL Editor](/tidb-cloud/explore-data-with-sql-editor.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 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). diff --git a/tidb-cloud/tidb-cloud-roadmap.md b/tidb-cloud/tidb-cloud-roadmap.md index 2198d458d2373..81e3285cd9d0e 100644 --- a/tidb-cloud/tidb-cloud-roadmap.md +++ b/tidb-cloud/tidb-cloud-roadmap.md @@ -29,10 +29,14 @@ 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 (beta), 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 new file mode 100644 index 0000000000000..36dd62725e630 --- /dev/null +++ b/tidb-cloud/use-chat2query-api.md @@ -0,0 +1,447 @@ +--- +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. | +| DELETE | `/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 new file mode 100644 index 0000000000000..1e8760a1d39b1 --- /dev/null +++ b/tidb-cloud/use-chat2query-knowledge.md @@ -0,0 +1,218 @@ +--- +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 new file mode 100644 index 0000000000000..6660cde4e4426 --- /dev/null +++ b/tidb-cloud/use-chat2query-sessions.md @@ -0,0 +1,101 @@ +--- +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 9d0befbf302590637c33c07b134dae1c7e23f4e4 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Wed, 28 Oct 2026 18:55:29 +0800 Subject: [PATCH 3/3] Discard changes to tidb-cloud/use-chat2query-api.md --- tidb-cloud/use-chat2query-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tidb-cloud/use-chat2query-api.md b/tidb-cloud/use-chat2query-api.md index 36dd62725e630..15b946b9ae90e 100644 --- a/tidb-cloud/use-chat2query-api.md +++ b/tidb-cloud/use-chat2query-api.md @@ -114,7 +114,7 @@ TiDB Cloud Data Service provides the following Chat2Query v3 endpoints and v2 en | 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. | -| DELETE | `/v3/knowledgeBases/{knowledge_base_id}/data/{knowledge_data_id}` | This endpoint deletes specific data from 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. |