PolarDB：自然語言到SQL語言轉義（基於大語言模型的NL2SQL）

使用說明

1. 建立問題範本表

   問題範本表的名稱必須以polar4ai_nl2sql_pattern開頭，且表結構必須包含下述建表語句中的五個列。

   DROP TABLE IF EXISTS `polar4ai_nl2sql_pattern`;
   CREATE TABLE `polar4ai_nl2sql_pattern` (
     `id` int(11) NOT NULL AUTO_INCREMENT COMMENT '主鍵',
     `pattern_question` text COMMENT '模板問題',
     `pattern_description` text COMMENT '模板描述',
     `pattern_sql` text COMMENT '模板SQL',
     `pattern_params` text COMMENT '模板參數',
     PRIMARY KEY (`id`)
   ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci;

   問題範本列說明

   列名	說明
   模板問題	帶參數的問題，作為輸入提供給LLM-based NL2SQL模型。 在模板問題中，需要按照#{XXX}格式來寫入參數。
   模板描述	對模板問題進行提煉，並將一些實體作為參數，例如日期、年份、機構等。這些實體通常對應於表中的特定列。 在模板描述中，需要按照【XXX】格式來寫入參數，並且需要與模板問題中的參數順序保持一致。
   模板SQL	與模板問題相對應的正確SQL語句。該SQL語句中需將模板問題中的參數作為變數進行處理。 說明 模板問題與模板SQL中的參數可不相同，但需具備關聯關係。例如，參數應具有相同的首碼，並且參數值之間存在一一映射關係。以#{category}和#{categoryCode}為例，當category的參數值為普通商標、特殊商標和集體商標時，相應的categoryCode值分別為0、1和2。詳細說明，請參見下述樣本。
   模板參數	模板參數為一個JSON字串，其結構由table_name、param_info和explanation三個參數組成，具體參數如下： table_name string：模板SQL中的表名。 param_info array：模板SQL中的參數說明。 param_name string：參數名稱。 value array：參數的取值範例。 說明 如果參數對應的是有限的枚舉值，則盡量在value中將所有的值列出來。 如果只是範例值，可以列出2～4個值。 如果存在相互對應的參數，則需要通過數組索引來映射。以#{category}和#{categoryCode}為例，category中的普通商標對應categoryCode中的1，特殊商標對應categoryCode中的2。詳細說明，請參見下述樣本。 explanation string：補充說明。通常是對產生SQL語句的一些要求。比如，輸出哪些資訊或者對欄位的一些說明。 說明 當不需要填寫模板參數時，您可以將模板參數值設定為以下任意一種形式： NULL Null 字元串 空的list字串[]

   樣本

   模板問題	模板描述	模板SQL	模板參數
   查詢課程名稱為#{courseName}授課狀態為#{status}的課程	【課程名稱】【授課狀態】的課程有哪些？	SELECT course_name, course_time, course_location FROM courses WHERE course_name=#{courseName} AND status=#{statusCode}	[{"table_name":"courses","param_info":[{"param_name":"#{courseName}","value":["數學","物理","化學","英語","歷史","地理","生物","電腦科學","藝術","音樂","體育","編程","文學","心理學","哲學","經濟學","社會學","物理學實驗","化學實驗","生物學實驗"]},{"param_name": "#{status}", "value": ["未開課","授課中"]},{"param_name": "#{statusCode}","value": [0,1]}], "explanation": "輸出課程名稱course_name、課程時間course_time、課程地點course_location。註：status為常量映射類型。變數映射欄位：statusCode。"}]
   查詢年份為#{issueDate}年專案狀態為#{projectStat}狀態計劃發布的國家標準有哪些？	【年份】【專案狀態】計劃發布的國家標準有哪些？	SELECT DISTINCT planNum, projectCnName, projectStat FROM sy_cd_me_buss_std_gjbzjh WHERE `planNum` IS NOT NULL AND `dataStatus` != 3 AND `isValid` = 1 AND projectStat=#{projectStat} AND DATE_FORMAT(`issueDate`, '%Y')=#{issueDate}	[{"table_name":"sy_cd_me_buss_std_gjbzjh","param_info":[{"param_name":"#{issueDate}","value":[2009,2010,2011,2012]},{"param_name":"#{projectStat}","value":["正在徵求意見","發行","正在審查"]}],"explanation":"輸出標準名稱projectCnName、計劃號、專案狀態"}]
   查詢商標類型為#{category}國際分類為#{intCls}類型的商標有哪些？	【商標類型】【國際分類】的商標有哪些？	SELECT DISTINCT tmName, regNo, status FROM sy_cd_me_buss_ip_tdmk_new WHERE dataStatus!=3 AND isValid = 1 AND category=#{categoryCode} AND intCls=#{intClsCode}	[{"table_name":"sy_cd_me_buss_ip_tdmk_new","param_info":[{"param_name":"#{intCls}","value":["化學原料","顏料油漆","日化用品","燃料油脂","醫藥"]},{"param_name":"#{category}","value":["普通商標","特殊商標","集體商標"]},{"param_name":"#{intClsCode}","value":[1,2,3,4,5]},{"param_name":"#{categoryCode}","value":[0,1,2]}],"explanation":"輸出商標名稱tmName、regNo申請號/註冊號、status商標狀態。註：category為常量映射類型。變數映射欄位：categoryCode。intCls為常量映射類型。變數映射欄位：intClsCode。"}]

   以本文樣本情境為例，建立上述表格中第一條模板問題。執行SQL如下：

   INSERT INTO `polar4ai_nl2sql_pattern` (`pattern_question`,`pattern_description`,`pattern_sql`,`pattern_params`) VALUES ('查詢課程名稱為#{courseName}授課狀態為#{status}的課程','【課程名稱】【授課狀態】的課程有哪些？','SELECT course_name, course_time, course_location FROM courses WHERE course_name=#{courseName} AND status=#{statusCode}','[{"table_name":"courses","param_info":[{"param_name":"#{courseName}","value":["數學","物理","化學","英語","歷史","地理","生物","電腦科學","藝術","音樂","體育","編程","文學","心理學","哲學","經濟學","社會學","物理學實驗","化學實驗","生物學實驗"]},{"param_name": "#{status}", "value": ["未開課","授課中"]},{"param_name": "#{statusCode}","value": [0,1]}], "explanation": "輸出課程名稱course_name、課程時間course_time、課程地點course_location。註：status為常量映射類型。變數映射欄位：statusCode。"}]');

2. 建立問題範本索引表

   支援自訂索引表名（需符合資料庫規範）。本文以pattern_index為例，建立問題範本索引表的SQL語句如下：

   /*polar4ai*/CREATE TABLE pattern_index(id integer, pattern_question text_ik_max_word, pattern_description text_ik_max_word, pattern_sql text_ik_max_word, pattern_params text_ik_max_word, pattern_tables text_ik_max_word, vecs vector_768, PRIMARY KEY (id));

   說明

   • 問題範本索引表不會直接展示於資料庫中。如需查看相關資訊，請使用SQL語句/*polar4ai*/SHOW TABLES;進行查詢。

   • 如果需要刪除問題範本索引表，以pattern_index為例，可以執行此SQL語句/*polar4ai*/DROP TABLE IF EXISTS pattern_index;。

3. 將問題範本表中資訊匯入索引表

   說明

   問題範本表中的資訊不得為空白。在執行匯入索引表的SQL語句之前，您需至少添加一條記錄。

   /*polar4ai*/SELECT * FROM PREDICT (MODEL _polar4ai_text2vec, SELECT '') WITH (mode='async', resource='pattern') INTO pattern_index;

   參數說明

   • _polar4ai_text2vec為文本轉向量化模型。

   • INTO後需要填寫之前建立的問題範本索引表名，該名稱為步驟2：建立問題範本索引表的表名。

   • WITH()內支援配置多個參數，以便對相關行為進行設定：

     參數	必填	說明
     mode	是	資料寫入模式。固定為async，表示為非同步模式。
     resource	是	資源類型。固定為pattern，表示對問題範本資訊進行向量化。
     pattern_table_name	否	設定轉向量的問題範本表的表名，該名稱為步驟1：建立問題範本表中的表名。 預設為polar4ai_nl2sql_pattern，表示對polar4ai_nl2sql_pattern表執行轉向量操作。設定時，需填寫以polar4ai_nl2sql_pattern開頭的問題範本表的表名。

     若您希望為不同情境或業務維護不同的問題範本索引表，可以在建立問題範本索引表時指定不同的表名。例如，為使用者相關情境建立polar4ai_nl2sql_pattern_user表，隨後在第二步建立問題範本索引時，將索引名設定為pattern_index_user。在將資訊匯入索引表時，使用如下SQL語句：

     /*polar4ai*/SELECT * FROM PREDICT (MODEL _polar4ai_text2vec, SELECT '') WITH (mode='async', resource='pattern', pattern_table_name='polar4ai_nl2sql_pattern_user') INTO pattern_index_user;

4. 查看任務狀態

   執行完上述匯入索引表的語句後，將返回該任務的task_id，例如bce632ea-97e9-11ee-bdd2-492f4dfe0918。您可以通過以下命令查看匯入狀態，

   /*polar4ai*/SHOW TASK `bce632ea-97e9-11ee-bdd2-492f4dfe0918`;

   當傳回值顯示為finish時，表示任務已完成。問題範本資訊可被模型引用。您可以執行以下SQL語句來查看問題範本索引資訊：

   /*polar4ai*/SELECT * FROM pattern_index;

   說明

   如果polar4ai_nl2sql_pattern表中的資料發生了變更，則需要重新執行步驟3：將問題範本資訊匯入索引表。

5. 線上使用問題範本

   您可以執行以下SQL語句來線上使用LLM-based NL2SQL和問題範本：

   /*polar4ai*/SELECT * FROM PREDICT (MODEL _polar4ai_nl2sql, SELECT '查詢課程名稱為數學，授課狀態為授課中的課程') WITH (basic_index_name='schema_index', pattern_index_name='pattern_index');

   SELECT course_name, course_time, course_location FROM courses WHERE course_name='數學' AND status=1;

   參數說明

   • SELECT後需要輸入待轉換為SQL語句的問題。

   • basic_index_name為當前資料庫檢索索引表名稱。

   • pattern_index_name為問題範本索引表名稱。

   • WITH()內支援配置多個參數，以便對相關行為進行設定（其他參數說明請參見線上使用LLM-based NL2SQL）：

     參數名稱	參數描述	取值範圍
     pattern_index_top	召回問題範本的最相近個數。	取值範圍：[1,10]。 預設值為2，表示對當前問題範本只選出最優的2條模板。
     pattern_index_threshold	召回問題範本是否相近時所使用的閾值。	取值範圍：(0,1]。 預設值為0.85，表示當問題範本向量匹配超過0.85時才會被選中。

適用情境

• 情境一：對問題中的確定性詞語進行替換，如人名、行業用語、商品名替換等。

  例如：對於所有涉及張三的問題，將張三替換為ZS001。在此情況下，對於問題張三上個月的銷售額是多少？和張三今年的總銷售額是多少？，在最終調用大模型之前，可以通過配置表將其全部預先處理為ZS001上個月的銷售額是多少？和ZS001今年的總銷售額是多少？。

• 情境二：對包含特定詞語的問題補充額外資訊。

  例如，對於所有涉及總銷售額的問題，應補充總銷售額的計算公式：總銷售額 = SUM(銷售額)。在最終調用大型模型之前，可以通過配置表添加此類資訊，當問題滿足相應條件時進行補充。

• 情境三：對特定表或列的值進行映射替換。

  例如：對所有最終涉及student_courses表的SQL，將其中的status = '請假'替換為status = 0，以作為一種列值對應的兜底措施。

文法說明

構建配置表的SQL語句如下，表名polar4ai_nl2sql_llm_config固定不可變。

DROP TABLE IF EXISTS `polar4ai_nl2sql_llm_config`;
CREATE TABLE `polar4ai_nl2sql_llm_config` (
  `id` int(11) NOT NULL AUTO_INCREMENT COMMENT '主鍵',
  `is_functional` int(11) NOT NULL DEFAULT '1' COMMENT '是否生效',
  `text_condition` text COMMENT '文本條件',
  `query_function` text COMMENT '查詢處理',
  `formula_function` text COMMENT '公式資訊',
  `sql_condition` text COMMENT 'SQL條件',
  `sql_function` text COMMENT 'SQL處理',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci;

參數說明

樣本

1. 未添加配置表前，執行以下SQL語句：

   /*polar4ai*/SELECT * FROM PREDICT (MODEL _polar4ai_nl2sql, SELECT '篩選出2個請假次數最多的學生，按照學生的請假次數降序排列，顯示學生的名字和請假次數。') WITH (basic_index_name='schema_index');

   SELECT s.student_name, COUNT(sc.id) AS leave_count FROM students s JOIN student_courses sc ON s.id = sc.student_id WHERE sc.status = 0 GROUP BY s.student_name ORDER BY leave_count DESC LIMIT 2;

2. 按照文法說明構建配置表。

3. 添加配置記錄。如果表students或表student_courses在SQL中，且表courses不在SQL中時，將status = 0替換成status = 10。

   INSERT INTO `polar4ai_nl2sql_llm_config` (`is_functional`,`sql_condition`,`sql_function`) VALUES (1,'students||student_courses&&!!courses','{"replace":{"status = 0":"status = 10"}}');

4. 執行步驟1的SQL語句。可以看出產生的SQL語句已將status的值進行了替換。

   /*polar4ai*/SELECT * FROM PREDICT (MODEL _polar4ai_nl2sql, SELECT '篩選出2個請假次數最多的學生，按照學生的請假次數降序排列，顯示學生的名字和請假次數。') WITH (basic_index_name='schema_index');

   SELECT s.student_name, COUNT(sc.id) AS leave_count FROM students s JOIN student_courses sc ON s.id = sc.student_id WHERE sc.status = 10 GROUP BY s.student_name ORDER BY leave_count DESC LIMIT 2;

文法說明

建立自訂表格列注釋表的SQL語句如下，表名polar4ai_nl2sql_table_extra_info固定不可變。

DROP TABLE IF EXISTS `polar4ai_nl2sql_table_extra_info`;
CREATE TABLE `polar4ai_nl2sql_table_extra_info` (
  `id` int(11) NOT NULL AUTO_INCREMENT COMMENT '主鍵',
  `table_name` text COMMENT '表名稱',
  `table_comment` text COMMENT '表說明',
  `column_name` text COMMENT '列名稱',
  `column_comment` text COMMENT '列說明',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci;

樣本

1. 建立自訂表格列注釋表。

2. 對student_courses表中status列的注釋進行修改。此處，為status列新增了一個選項說明：2-缺勤。

   INSERT INTO `polar4ai_nl2sql_table_extra_info` (`table_name`,`table_comment`,`column_name`,`column_comment`) VALUES ('student_courses','課程學生資訊表','status','學生狀態 0-請假，1-正常，2-缺勤。');

3. 重新執行步驟：將資料表中的資訊匯入檢索索引表。

   /*polar4ai*/SELECT * FROM PREDICT (MODEL _polar4ai_text2vec, SELECT '') WITH (mode='async', resource='schema') INTO schema_index;

4. 查看任務狀態。

   執行完上述匯入檢索索引表的語句後，將返回該任務的task_id，例如bce632ea-97e9-11ee-bdd2-492f4dfe0918。您可以通過以下命令查看匯入狀態，當taskStatus顯示為finish時，表示任務已完成。

   /*polar4ai*/SHOW TASK `bce632ea-97e9-11ee-bdd2-492f4dfe0918`;

5. 線上使用LLM-based NL2SQL。

   /*polar4ai*/SELECT * FROM PREDICT (MODEL _polar4ai_nl2sql, SELECT '篩選出2個缺勤次數最多的學生，按照學生的缺勤次數降序排列，顯示學生的名字和缺勤次數。') WITH (basic_index_name='schema_index');

   SELECT s.student_name, COUNT(sc.id) AS absence_count FROM student_courses sc JOIN students s ON sc.student_id = s.id WHERE sc.status = 2 GROUP BY s.student_name ORDER BY absence_count DESC LIMIT 2;

   從上述輸出結果中可以看出，LLM-based NL2SQL模型已經將缺勤對應為student_courses表中status列的列值2。