PolarDB:LLM による自然言語から SQL へ

操作手順

1. 質問テンプレートテーブルの作成

   質問テンプレートテーブル名は polar4ai_nl2sql_pattern で始まる必要があります。また、スキーマには、次の CREATE TABLE ステートメントで定義されている 5 つのカラムを含める必要があります。

   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 ベースの NL2SQL モデルへの入力となるパラメーター化された質問です。 テンプレート質問では、パラメーターを #{XXX} 形式で記述します。
   テンプレートの説明	テンプレート質問の要約です。日付、年、組織などのエンティティをパラメーターとして抽出します。これらのエンティティは通常、テーブル内の特定のカラムにマッピングされます。 テンプレートの説明では、パラメーターを [XXX] 形式で記述する必要があります。また、パラメーターの順序は、テンプレート質問内のパラメーターの順序と一致させる必要があります。
   テンプレート SQL	テンプレート質問に対する正しい SQL です。この SQL では、テンプレート質問のパラメーターは変数として扱います。 説明 テンプレート質問とテンプレート SQL のパラメーターは同一である必要はありませんが、関連している必要があります。例えば、パラメーターが共通のプレフィックスを共有し、値が 1 対 1 のマッピングになる場合があります。#{category} と #{categoryCode} では、category のパラメーター値が "ordinary trademark"、"special trademark"、"collective trademark" の場合、対応する categoryCode の値はそれぞれ 0、1、2 です。詳細については、次の例をご参照ください。
   テンプレートパラメーター	table_name、param_info、explanation の 3 つのパラメーターで構成される JSON 文字列です。 table_name string：テンプレート SQL で使用するテーブル名です。 param_info array：テンプレート SQL 内のパラメーターの説明です。 param_name string：パラメーター名です。 value array：パラメーターのサンプル値です。 説明 パラメーターに有限の列挙値セットがある場合は、可能であれば value 配列にすべて列挙してください。 サンプル値のみを指定する場合は、2 ～ 4 個の例を列挙してください。 パラメーターが相互依存する場合は、配列インデックスを使用してマッピングします。例えば、#{category} と #{categoryCode} では、category の "ordinary trademark" は categoryCode の 0 に対応し、"special trademark" は categoryCode の 1 に対応します。詳細については、次の例をご参照ください。 explanation string：補足事項です。通常は、返す情報や特定のフィールドの解釈方法など、生成される SQL の要件を記述します。 説明 テンプレートパラメーターが不要な場合は、値を次のいずれかに設定できます： NULL 空の文字列 空のリスト文字列： []

   例

   テンプレート質問	テンプレートの説明	テンプレート SQL	テンプレートパラメーター
   Query for courses with course name #{courseName} and teaching status #{status}	What are the courses with [Course Name] and [Teaching 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":["Mathematics","Physics","Chemistry","English","History","Geography","Biology","Computer Science","Art","Music","Physical Education","Programming","Literature","Psychology","Philosophy","Economics","Sociology","Physics Lab","Chemistry Lab","Biology Lab"]},{"param_name": "#{status}", "value": ["Not started","In progress"]},{"param_name": "#{statusCode}","value": [0,1]}], "explanation": "コース名 (course_name)、コース時間 (course_time)、およびコース場所 (course_location) を出力します。注：status は定数マッピングタイプです。変数マッピングフィールドは statusCode です。"}]
   What are the national standards planned for release in year #{issueDate} with project status #{projectStat}?	What are the national standards planned for release in [Year] with [Project Status]?	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":["Seeking comments","Published","Under review"]}],"explanation":"標準名 (projectCnName)、計画番号、およびプロジェクトステータスを出力します。"}]
   What are the trademarks with category #{category} and international classification #{intCls}?	What are the trademarks for [Trademark Type] in [International Classification]?	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":["Chemical raw materials","Paints","Cosmetics and cleaning preparations","Fuels and lubricants","Pharmaceuticals"]},{"param_name":"#{category}","value":["ordinary trademark","special trademark","collective trademark"]},{"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 ('Query for courses with course name #{courseName} and teaching status #{status}','What are the courses with [Course Name] and [Teaching 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":["Mathematics","Physics","Chemistry","English","History","Geography","Biology","Computer Science","Art","Music","Physical Education","Programming","Literature","Psychology","Philosophy","Economics","Sociology","Physics Lab","Chemistry Lab","Biology Lab"]},{"param_name": "#{status}", "value": ["Not started","In progress"]},{"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));

   説明

   • 質問テンプレートインデックス テーブルは、データベースオブジェクトのリストには表示されません。表示するには、 /*polar4ai*/SHOW TABLES; を実行します。

   • 例えば pattern_index などの質問テンプレートインデックス テーブルを削除するには、SQL ステートメント /*polar4ai*/DROP TABLE IF EXISTS pattern_index; を実行します。

3. インデックス テーブルへのデータのインポート

   説明

   質問テンプレートテーブルは空にできません。データをインポートする SQL を実行する前に、少なくとも 1 件のレコードを追加してください。

   /*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 テーブルを作成する場合は、手順 2 でインデックス名を 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 ベースの NL2SQL と質問テンプレートを使用したオンラインクエリを実行します：

   /*polar4ai*/SELECT * FROM PREDICT (MODEL _polar4ai_nl2sql, SELECT 'Query for courses with the course name Mathematics and status in progress') WITH (basic_index_name='schema_index', pattern_index_name='pattern_index');

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

   パラメーター

   • SELECT の後に、SQL に変換する質問を入力します。

   • basic_index_name は、現在のデータベースの検索インデックス テーブル名です。

   • pattern_index_name は、質問テンプレートインデックス テーブル名です。

   • WITH() 句では、複数のパラメーターを設定できます。その他のパラメーターの説明については、「Run an online query with LLM-based NL2SQL」をご参照ください。

     パラメーター	説明	値の範囲
     pattern_index_top	リコールする最も近い質問テンプレートの数です。	値の範囲： [1,10]。 デフォルト値は 2 で、現在の質問に対して上位 2 件のテンプレートのみがリコールされることを意味します。
     pattern_index_threshold	質問テンプレートをリコールするための類似度のしきい値です。	値の範囲： (0,1]。 デフォルト値は 0.85 で、ベクトル類似度スコアが 0.85 を超える場合にのみテンプレートが選択されることを意味します。

ユースケース

• シナリオ1：名前、専門用語、製品名など、質問内の特定の用語を置換します。

  たとえば、Zhang San を含むすべての質問に対して、Zhang San を ZS001 に置換します。この場合、「What were Zhang San's sales last month?」 および 「What are Zhang San's total sales for this year?」 という質問は、大規模言語モデルを最終的に呼び出す前に、設定テーブルを使用して 「What were ZS001's sales last month?」 および 「What are ZS001's total sales for this year?」 に前処理できます。

• シナリオ2：特定の用語を含む質問に追加のコンテキストを付加します。

  たとえば、Total Sales を含むすべての質問には、計算式 Total Sales = SUM(Sales) を追加する必要があります。この情報は、大規模言語モデルを最終的に呼び出す前に設定テーブルによって追加でき、質問が対応する条件を満たした際に付加されます。

• シナリオ3：最終的な SQL 内の特定のテーブルまたは列の値をマッピングして置換します。

  たとえば、最終的に student_courses テーブルを含むすべての SQL ステートメントに対して、カラム値のマッピングのフォールバック手段として、status = 'on leave' を 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. 設定テーブルなしでクエリを実行すると、次のようになります。

   /*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. 設定レコードを追加します。このルールでは、SQL ステートメントが students テーブルまたは student_courses テーブルを参照し、かつ courses テーブルを参照しない場合に、システムが 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 の 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 カラムのコメントを更新します。この例では、新しいオプションマッピング： 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. タスクステータスを確認します。

   インポートステートメントを実行すると、システムは bce632ea-97e9-11ee-bdd2-492f4dfe0918 のような task_id を返します。次のコマンドを使用してインポートステータスを確認します。taskStatus が finish の場合、タスクは完了しています。

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

5. LLM ベースの NL2SQL を使用してクエリを実行します。

   /*polar4ai*/SELECT * FROM PREDICT (MODEL _polar4ai_nl2sql, SELECT 'Show the names and number of absences for the 2 students with the most absences, sorted in descending order.') 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 ベースの NL2SQL モデルが student_courses テーブルの status カラムにおいて、欠席 を 値 2 に正しくマッピングしたことを示しています。