1. ---
title: 'ChatSQL SA Spec'
disqus: hackmd
tags: Cathay
---
{%hackmd BJrTq20hE %}
## 功能名稱：ChatSQL Kernel

## 功能說明：將自然語言問句轉換成SQL語法及 DBML schema vector 的 create/update/delete

## 修訂歷程：

<table>
<thead>
<tr>
<th>版號</th>
<th>修訂日期</th>
<th>修訂內容</th>
<th>修訂原因</th>
<th>修訂者</th>
<th>審核</th>
</tr>
</thead>
<tbody>
<tr>
<td>v1.0</td>
<td>2023/07/12</td>
<td>新建文檔</td>
<td>None</td>
<td>盧林俊</td>
<td>V</td>
</tr>
<tr>
<td>v1.1</td>
<td>2023/07/17</td>
<td>功能說明</td>
<td>translator</td>
<td>盧林俊</td>
<td>V</td>
</tr>
<tr>
<td>v1.2</td>
<td>2023/07/20</td>
<td>功能說明</td>
<td>schema</td>
<td>盧林俊</td>
<td>V</td>
</tr>
<tr>
<td>v1.3</td>
<td>2023/07/26</td>
<td>功能說明</td>
<td>translator error status</td>
<td>盧林俊</td>
<td>V</td>
</tr>
<tr>
<td>v1.4</td>
<td></td>
<td></td>
<td></td>
<td>盧林俊</td>
<td></td>
</tr>
</tbody>
</table>

## API Spec

https://docs.google.com/spreadsheets/d/1o798hJV-CL1cJCPlRptWOe_rWwXdH60GCYAPXho46aU/edit?usp=sharing

**- Package Name: imgenie-gl-schema**
1. API: /v1/schema/create
2. 說明: 前端可透過此API將datamart的DBML schema上傳至後端的vectorstore。DBML schema描述了資料庫結構，而vectorstore則儲存了最佳化查詢所需的向量化資料。當前端上傳DBML schema後，後端將其存入vectorstore中，並生成對應的VECTOR_ID，方便後續的最佳化查詢操作。

**- Package Name: imgenie-gl-schema**
1. API: /v1/schema/update
2. 說明: 前端可透過此API更新vector database中已存在的datamart的DBML schema。更新DBML schema後，後端同步更新vectorstore中對應的向量，以保持資料庫結構和最佳化查詢所需的向量化資料的一致性。這樣，後續的最佳化查詢能夠基於更新後的資料進行準確查詢。

**- Package Name: imgenie-gl-schema**
1. API: /v1/schema/delete
2. 說明: 前端可透過此API刪除datamart時，後端的vector database也同步刪除對應的DBML schema的向量。當datamart被刪除時，相應的向量也不再需要存儲，保持資料庫結構和最佳化查詢所需的向量化資料的一致性。

**- Package Name: imgenie-gl-prompt-to-sql**
1. API: /v1/prompt-to-sql/translator
2. 說明: 前端透過此API將問句轉換為相應的SQL查詢語句。為了進行最佳化查詢，需要取用vectorstore中的向量來解析問句。因此，前端首先上傳datamart的DBML schema，後端將其儲存至vectorstore，並基於此結構進行向量化。接著，前端提出問句，後端根據問句解析並生成對應的SQL查詢語句，最終使用vectorstore中的向量進行最佳化查詢。

## 功能流程圖

- 以上四個API屬於Package "imgenie-gl-schema" 和 "imgenie-gl-prompt-to-sql"。前三個API用於管理datamart的DBML schema，包括上傳、更新和刪除，而第四個API則用於將前端的問句轉換為SQL查詢語句。這些API共同協作，使前端能夠上傳資料庫結構描述、進行查詢和取用vectorstore中的向量，有效地支援最佳化查詢需求。

**整體功能流程互動關係如下:**

- 1~3 為 imgenie-gl-schema package 的 /v1/schema/create 服務
1. Frontend 向 imgenie-gl-schema 服務的 /v1/schema/create API 發送請求，上傳 datamart 的 DBML schema。
1. Backend 接收到請求，將 DBML schema 存入 vectorestore 中，並生成一個對應的 VECTOR_ID。
1. Backend 將 VECTOR_ID 回傳至 Frontend，表示資料上傳成功。
- 4~6 為 imgenie-gl-prompt-to-sql package 的 /v1/prompt-to-sql/translator 服務
1. Frontend 接收到回應後，使用 imgenie-gl-prompt-to-sql 服務的 /v1/prompt-to-sql/translator API 發送問句查詢請求，並提供前面獲得的 VECTOR_ID。
1. Backend 接收到問句查詢請求，根據前端提供的問句內容進行轉換，並生成對應的 SQL 查詢語句。
1. Backend 將轉換後的 SQL 查詢語句、查詢時間和 VECTOR_ID 一起回傳至 Frontend。


<br>
**Package: imgenie-gl-prompt-to-sql:**

以下時序圖描述了一個名為 /v1/prompt-to-sql/translator 的 API 在處理前端查詢轉換成 SQL 的流程。

1. 前端首先向後端發送 /v1/prompt-to-sql/translator 的查詢請求。
2. 後端收到請求後，首先驗證前端的身份認證和 token 是否有效。
3. 身份認證成功後，後端進行查詢的解析和轉換，將前端提供的自然語言查詢轉換成對應的 SQL 查詢語句。
4. 若查詢的轉換成功，表示前端提供的查詢內容是有效的，後端將轉換後的 SQL 查詢語句回傳給前端。
5. 若查詢的轉換失敗，表示前端提供的查詢內容可能有語法錯誤或是無效，後端會回傳一個錯誤響應並附上建議的修正方式，讓前端可以進行修正。
6. 當後端完成處理後，整個流程結束。


## 關聯的服務

<table>
<thead>
<tr>
<th></th>
<th>Package Name</th>
<th>API</th>
</tr>
</thead>
<tbody>
<tr>
<td>1</td>
<td>imgenie-gl-schema</td>
<td>/v1/schema/create</td>
</tr>
<tr>
<td>2</td>
<td>imgenie-gl-schema</td>
<td>/v1/schema/update</td>
</tr>
<tr>
<td>3</td>
<td>imgenie-gl-schema</td>
<td>/v1/schema/delete</td>
</tr>
<tr>
<td>4</td>
<td>imgenie-gl-prompt-to-sql</td>
<td>/v1/prompt-to-sql/translator</td>
</tr>
</tbody>
</table>

## 功能說明

### Package:
* imgenie-gl-schema
### Type:
1. post
### Api:
1. /v1/schema/create
### Desc:
* 此 API 讓前端將 schema 上傳到 vectorstore 中, 簡單流程如下：
1. 前端將 datamart 的 DBML schema 上傳至後端
1. 後端將此 DBML schema 存入 vectorestore 中
1. 把新增的 VECTOR_ID 回傳至前端，此 VECTOR_ID 對應到前端儲存的 DATAMART_ID。

##
### Package:
* imgenie-gl-schema
### Type:
1. post
### Api:
1. /v1/schema/update
### Desc:
* 前端更新vector database中已存在的schema, 簡單流程如下：
1. 前端將更新後的 datamart DBML schema 上傳到後端。
1. 後端更新 vector database 中已存在的 DBML schema 對應的 vector。
1. 把更新後的 VECTOR_ID 回傳至前端，此 VECTOR_ID 對應到前端儲存的 DATAMART_ID。

##
### Package:
* imgenie-gl-schema
### Type:
1. post
### Api:
1. /v1/schema/delete
### Desc:
* 前端刪除datamart時, 後端的vector database也做對應的刪除動作, 簡單流程如下：
1. 前端做出刪除 datamart 動作。
1. 後端將 vector database 中對應 DBML schema 的 vector 刪除。
1. 把被刪除的 VECTOR_ID 回傳至前端，此 VECTOR_ID 對應到前端儲存的 DATAMART_ID。

藉由以上 imgenie-gl-schema package 中的三支 API，前端可以方便地管理 datamart 的 DBML schema，而後端也能夠有效地將這些資料保存在 vectorestore 中，為後續的資料處理和分析提供便利性。

##
### Package:
* imgenie-gl-prompt-to-sql
### Type:
* post
### Api:
* /v1/prompt-to-sql/translator
### Desc:
* 此 API 接收前端的問句，並將其轉換為相應的 SQL 查詢語句。有能力處理各種查詢場景，並對可能的錯誤情況進行處理並將轉換結果回傳到前端。通過此 API，前端可以方便地進行詢問，並獲得轉換後的 SQL 語法。