From 314234821b0fe1cc0c2ada9909a2d7141e9d0317 Mon Sep 17 00:00:00 2001
From: ChihYu Yeh <chihyu.jimmy.yeh@gmail.com>
Date: Fri, 29 Nov 2024 13:39:55 +0800
Subject: [PATCH] update api doc

---
 .../web/v1/routers/sql_pairs_preparation.py   | 37 +++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/wren-ai-service/src/web/v1/routers/sql_pairs_preparation.py b/wren-ai-service/src/web/v1/routers/sql_pairs_preparation.py
index 808c820d0..cea0bab93 100644
--- a/wren-ai-service/src/web/v1/routers/sql_pairs_preparation.py
+++ b/wren-ai-service/src/web/v1/routers/sql_pairs_preparation.py
@@ -25,6 +25,43 @@
 Sql Pairs Preparation Router
 
 This router manages the endpoints related to users uploading SQL pairs and retrieving their status.
+
+Endpoints:
+1. **POST /sql-pairs-preparations**
+   - Initiates the preparation of SQL pairs for processing.
+   - **Request Body**: SqlPairsPreparationRequest
+     - `sql_pairs`: List of SQL pairs, each containing:
+       - `sql`: The SQL statement
+       - `id`: Unique identifier for the SQL pair
+     - `project_id`: (Optional) Identifier for the project context
+   - **Response**: SqlPairsPreparationResponse
+     - `sql_pairs_preparation_id`: A unique identifier (UUID) for tracking the preparation process
+
+2. **DELETE /sql-pairs-preparations**
+   - Deletes specified SQL pairs.
+   - **Request Body**: DeleteSqlPairsRequest
+     - `ids`: List of SQL pair IDs to delete
+     - `project_id`: (Optional) Project identifier
+   - **Response**: DeleteSqlPairsResponse
+     - `sql_pairs_preparation_id`: A unique identifier (UUID) for tracking the deletion process
+
+3. **GET /sql-pairs-preparations/{sql_pairs_preparation_id}/status**
+   - Retrieves the current status of a SQL pairs preparation or deletion process.
+   - **Path Parameter**:
+     - `sql_pairs_preparation_id`: The unique identifier of the process
+   - **Response**: SqlPairsPreparationStatusResponse
+     - `status`: Current status ("indexing", "deleting", "finished", or "failed")
+     - `error`: (Optional) Error information if the process failed, including:
+       - `code`: Error code ("OTHERS")
+       - `message`: Detailed error message
+
+Process:
+1. Submit SQL pairs using the POST endpoint to initiate preparation. This returns a preparation ID.
+2. Use the DELETE endpoint to remove specific SQL pairs from the system.
+3. Track the status of any operation using the GET endpoint with the preparation ID.
+
+Note: All operations are processed asynchronously using background tasks. The status can be polled 
+via the GET endpoint. Results are cached with a TTL of 120 seconds.
 """