PolarDB:Natural language to SQL with an LLM

Procédure

1. Créer une table de modèles de questions

   Le nom de la table de modèles de questions doit commencer par polar4ai_nl2sql_pattern, et son schéma doit inclure les cinq colonnes définies dans l'instruction CREATE TABLE suivante.

   DROP TABLE IF EXISTS `polar4ai_nl2sql_pattern`;
   CREATE TABLE `polar4ai_nl2sql_pattern` (
     `id` int(11) NOT NULL AUTO_INCREMENT COMMENT 'Primary key',
     `pattern_question` text COMMENT 'Template question',
     `pattern_description` text COMMENT 'Template description',
     `pattern_sql` text COMMENT 'Template SQL',
     `pattern_params` text COMMENT 'Template parameters',
     PRIMARY KEY (`id`)
   ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci;

   Description des colonnes

   Parameter	Description
   template question	Question paramétrée servant d'entrée au modèle LLM-based NL2SQL. Dans la question modèle, écrivez les paramètres au format #{XXX}.
   template description	Résumé de la question modèle, où les entités telles que les dates, années ou organisations sont extraites sous forme de paramètres. Ces entités correspondent généralement à des colonnes spécifiques d'une table. Dans la description du modèle, écrivez les paramètres au format [XXX], et respectez l'ordre des paramètres de la question modèle.
   template SQL	Instruction SQL correcte correspondant à la question modèle. Dans ce SQL, les paramètres de la question modèle sont traités comme des variables. Remarque Les paramètres de la question modèle et du SQL modèle n'ont pas besoin d'être identiques, mais ils doivent être liés. Par exemple, les paramètres peuvent partager un préfixe commun et leurs valeurs peuvent avoir un mappage un à un. Avec #{category} et #{categoryCode}, lorsque les valeurs de paramètre pour category sont « ordinary trademark », « special trademark » et « collective trademark », les valeurs correspondantes de categoryCode sont respectivement 0, 1 et 2. Pour plus de détails, consultez l'exemple ci-dessous.
   template parameters	Chaîne JSON composée de trois paramètres : table_name, param_info et explanation. table_name string : nom de la table utilisée dans le SQL modèle. param_info array : description des paramètres dans le SQL modèle. param_name string : nom du paramètre. value array : exemples de valeurs pour le paramètre. Remarque Si le paramètre possède un ensemble fini de valeurs énumérées, listez-les toutes dans le tableau value si possible. Si vous ne fournissez que des exemples de valeurs, indiquez-en 2 à 4. Si les paramètres sont interdépendants, mappez-les à l'aide de l'index du tableau. Par exemple, avec #{category} et #{categoryCode}, « ordinary trademark » dans category correspond à 0 dans categoryCode, et « special trademark » correspond à 1 dans categoryCode. Pour plus de détails, consultez l'exemple ci-dessous. explanation string : notes supplémentaires décrivant généralement les exigences relatives au SQL généré, telles que les informations à retourner ou la manière d'interpréter certains champs. Remarque Si les paramètres du modèle ne sont pas nécessaires, définissez la valeur sur l'une des options suivantes : NULL Une chaîne vide Une chaîne de liste vide : []

   Exemple

   Template question	Template description	Template SQL	Template parameters
   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": "Output the course name (course_name), course time (course_time), and course location (course_location). Note: status is a constant mapping type. The variable mapping field is statusCode."}]
   What are the national standards planned for release in year #{issueDate} with project status #{projectStat}?	What are the [Project Status] national standards planned for release in [Year]?	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":"Output standard name (projectCnName), plan number, and project status."}]
   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":"Output trademark name (tmName), application/registration number (regNo), and trademark status (status). Note: category is a constant mapping type. The variable mapping field is categoryCode. intCls is a constant mapping type. The variable mapping field is intClsCode."}] Par exemple, pour créer la première question modèle présentée dans le tableau ci-dessus, exécutez le SQL suivant :

   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】【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": "Output the course name (course_name), course time (course_time), and course location (course_location). Note: status is a constant mapping type. The variable mapping field is statusCode."}]');

2. Créer une table d'index de modèles de questions

   Vous pouvez utiliser un nom personnalisé pour la table d'index, à condition qu'il respecte les conventions de nommage de la base de données. Cet exemple utilise pattern_index. Exécutez le SQL suivant pour créer la table d'index de modèles de questions :

   /*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));

   Remarque

   • La table d'index de modèles de questions n'apparaît pas dans la liste des objets de la base de données. Pour la consulter, exécutez /*polar4ai*/SHOW TABLES;.

   • Pour supprimer la table d'index de modèles de questions, par exemple pattern_index, exécutez l'instruction SQL /*polar4ai*/DROP TABLE IF EXISTS pattern_index;.

3. Importer des données dans la table d'index

   Remarque

   La table de modèles de questions ne peut pas être vide. Avant d'exécuter le SQL d'importation, ajoutez au moins un enregistrement.

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

   Paramètres

   • _polar4ai_text2vec est le modèle de vectorisation de texte.

   • Après INTO, spécifiez le nom de la table d'index de modèles de questions créée à l'Étape 2.

   • Configurez plusieurs paramètres dans la clause WITH() :

     Parameter	Required	Description
     mode	Yes	Spécifie le mode d'écriture. Définissez-le sur async pour le mode asynchrone.
     resource	Yes	Spécifie le type de ressource. Définissez-le sur pattern pour vectoriser les informations des modèles de questions.
     pattern_table_name	No	Nom de la table de modèles de questions à vectoriser. Il s'agit du nom de table issu de l'Étape 1. La valeur par défaut est polar4ai_nl2sql_pattern, ce qui signifie que la vectorisation est effectuée sur la table polar4ai_nl2sql_pattern. Si vous définissez ce paramètre, spécifiez un nom de table commençant par polar4ai_nl2sql_pattern.

     Si vous souhaitez maintenir différentes tables d'index de modèles de questions pour divers scénarios ou domaines métier, spécifiez différents noms de tables lors de leur création. Par exemple, si vous créez une table polar4ai_nl2sql_pattern_user pour des scénarios liés aux utilisateurs, définissez le nom de l'index sur pattern_index_user à l'étape 2. Lors de l'importation des informations, utilisez l'instruction SQL suivante :

     /*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. Vérifier l'état de la tâche

   Après l'exécution de l'instruction d'importation, le système renvoie un task_id, tel que bce632ea-97e9-11ee-bdd2-492f4dfe0918. Exécutez la commande suivante pour vérifier l'état de la tâche.

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

   Lorsque l'état de la tâche est finish, l'importation est terminée et le modèle peut référencer les informations du modèle de questions. Exécutez l'instruction SQL suivante pour consulter les informations de l'index de modèles de questions :

   /*polar4ai*/SELECT * FROM pattern_index;

   Remarque

   Si les données de la table polar4ai_nl2sql_pattern changent, réexécutez la procédure décrite à l'Étape 3.

5. Exécuter une requête en ligne avec des modèles de questions

   Exécutez l'instruction SQL suivante pour effectuer une requête en ligne utilisant LLM-based NL2SQL et des modèles de questions :

   /*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;

   Paramètres

   • Après SELECT, saisissez la question à convertir en SQL.

   • basic_index_name correspond au nom de la table d'index de recherche de la base de données actuelle.

   • pattern_index_name correspond au nom de la table d'index de modèles de questions.

   • Configurez plusieurs paramètres dans la clause WITH(). Pour la description des autres paramètres, consultez Exécuter une requête en ligne avec LLM-based NL2SQL.

     Parameter	Description	Value range
     pattern_index_top	Nombre de modèles de questions les plus proches à rappeler.	Plage de valeurs : [1,10]. La valeur par défaut est 2, ce qui signifie que seuls les 2 premiers modèles sont rappelés pour la question en cours.
     pattern_index_threshold	Seuil de similarité pour le rappel d'un modèle de questions.	Plage de valeurs : (0,1]. La valeur par défaut est 0,85, ce qui signifie qu'un modèle n'est sélectionné que si son score de similarité vectorielle dépasse 0,85.

Cas d'utilisation

• Scénario 1 : Remplacer des termes spécifiques dans une question, tels que des noms, du jargon industriel ou des noms de produits.

  Par exemple : pour toutes les questions impliquant Zhang San, remplacez Zhang San par ZS001. Ainsi, pour les questions What were Zhang San's sales last month? et What are Zhang San's total sales for this year?, utilisez une table de configuration pour les prétraiter en What were ZS001's sales last month? et What are ZS001's total sales for this year? avant l'appel final au grand modèle de langage.

• Scénario 2 : Ajouter un contexte supplémentaire aux questions contenant des termes spécifiques.

  Par exemple, pour toutes les questions impliquant Total Sales, la formule de calcul Total Sales = SUM(Sales) doit être ajoutée. Avant l'appel final au grand modèle, intégrez ces informations via une table de configuration ; elles seront ajoutées lorsque la question remplit la condition correspondante.

• Scénario 3 : Mapper et remplacer des valeurs pour des tables ou colonnes spécifiques dans le SQL final.

  Par exemple, pour toutes les instructions SQL impliquant finalement la table student_courses, remplacez status = 'leave' par status = 0 comme mesure de secours pour le mappage des valeurs de colonnes.

Syntaxe

Utilisez l'instruction SQL suivante pour créer la table de configuration. Le nom de la table polar4ai_nl2sql_llm_config est fixe et ne peut pas être modifié.

DROP TABLE IF EXISTS `polar4ai_nl2sql_llm_config`;
CREATE TABLE `polar4ai_nl2sql_llm_config` (
  `id` int(11) NOT NULL AUTO_INCREMENT COMMENT 'primary key',
  `is_functional` int(11) NOT NULL DEFAULT '1' COMMENT 'Indicates if the configuration row is active',
  `text_condition` text COMMENT 'Text condition for pre-processing',
  `query_function` text COMMENT 'Query processing function',
  `formula_function` text COMMENT 'Formula information function',
  `sql_condition` text COMMENT 'SQL condition for post-processing',
  `sql_function` text COMMENT 'SQL processing function',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci;

Paramètres

Exemple

1. Exécutée sans table de configuration, la requête suivante :

   /*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. Créez la table de configuration comme décrit dans la section Syntaxe.

3. Ajoutez un enregistrement de configuration. Cette règle stipule que si une instruction SQL référence la table students ou la table student_courses, mais pas la table courses, le système remplace status = 0 par 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. Exécutez à nouveau la requête de l'étape 1. La valeur status dans le SQL généré est désormais remplacée conformément à la règle.

   /*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;

Syntaxe

L'instruction SQL suivante crée la table de commentaires personnalisés. Le nom de la table polar4ai_nl2sql_table_extra_info ne peut pas être modifié.

DROP TABLE IF EXISTS `polar4ai_nl2sql_table_extra_info`;
CREATE TABLE `polar4ai_nl2sql_table_extra_info` (
  `id` int(11) NOT NULL AUTO_INCREMENT COMMENT 'Primary key',
  `table_name` text COMMENT 'Table name',
  `table_comment` text COMMENT 'Table description',
  `column_name` text COMMENT 'Column name',
  `column_comment` text COMMENT 'Column description',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci;

Exemple

1. Créez la table de commentaires personnalisés.

2. Mettez à jour le commentaire de la colonne status dans la table student_courses. Cet exemple ajoute un nouveau mappage d'options : 2-Absent.

   INSERT INTO `polar4ai_nl2sql_table_extra_info` (`table_name`,`table_comment`,`column_name`,`column_comment`) VALUES ('student_courses','Student-course information table','status','Student status: 0-On leave, 1-Normal, 2-Absent.');

3. Réexécutez l'étape consistant à importer les informations des tables de données dans l'index de schéma.

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

4. Vérifiez l'état de la tâche.

   Après l'exécution de l'instruction d'importation, le système renvoie un task_id, tel que bce632ea-97e9-11ee-bdd2-492f4dfe0918. Utilisez la commande suivante pour vérifier l'état de l'importation. Lorsque taskStatus est finish, la tâche est terminée.

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

5. Exécutez une requête en utilisant LLM-based 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;

   Le résultat montre que le modèle LLM-based NL2SQL mappe désormais correctement Absent à la valeur 2 pour la colonne status dans la table student_courses.