PolarDB:Natural language to SQL dengan LLM

Prosedur

1. Buat tabel templat pertanyaan

   Nama tabel templat pertanyaan harus diawali dengan polar4ai_nl2sql_pattern, dan skemanya harus mencakup lima kolom yang didefinisikan dalam pernyataan CREATE TABLE berikut.

   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;

   Deskripsi kolom

   Parameter	Deskripsi
   template question	Pertanyaan berparameter yang merupakan input untuk model LLM-based NL2SQL. Dalam pertanyaan templat, tulis parameter dalam format #{XXX}.
   template description	Rangkuman pertanyaan templat, dengan entitas seperti tanggal, tahun, atau organisasi diekstraksi sebagai parameter. Entitas ini biasanya dipetakan ke kolom tertentu dalam tabel. Dalam deskripsi templat, Anda harus menulis parameter dalam format [XXX], dan urutannya harus konsisten dengan urutan parameter dalam pertanyaan templat.
   template SQL	SQL yang benar untuk pertanyaan templat. Dalam SQL ini, parameter dari pertanyaan templat diperlakukan sebagai variabel. Catatan Parameter dalam pertanyaan templat dan SQL templat tidak harus identik, tetapi harus saling terkait. Misalnya, parameter dapat memiliki awalan umum, dan nilainya dapat memiliki pemetaan satu-ke-satu. Dengan #{category} dan #{categoryCode}, ketika nilai parameter untuk category adalah "ordinary trademark", "special trademark", dan "collective trademark", nilai categoryCode yang sesuai adalah 0, 1, dan 2. Untuk detailnya, lihat contoh di bawah.
   template parameters	String JSON yang terdiri dari tiga parameter: table_name, param_info, dan explanation. table_name string: Nama tabel yang digunakan dalam SQL templat. param_info array: Deskripsi parameter dalam SQL templat. param_name string: Nama parameter. value array: Nilai sampel untuk parameter. Catatan Jika parameter memiliki himpunan nilai terbatas, cantumkan semua nilai tersebut dalam array value jika memungkinkan. Jika Anda hanya memberikan nilai sampel, cantumkan 2 hingga 4 contoh. Jika parameter saling bergantung, petakan menggunakan indeks array. Misalnya, dengan #{category} dan #{categoryCode}, "ordinary trademark" dalam category berkorespondensi dengan 0 dalam categoryCode, dan "special trademark" berkorespondensi dengan 1 dalam categoryCode. Untuk detailnya, lihat contoh di bawah. explanation string: Catatan tambahan, yang biasanya menjelaskan persyaratan untuk SQL yang dihasilkan, seperti informasi apa yang harus dikembalikan atau bagaimana menginterpretasikan bidang tertentu. Catatan Jika parameter templat tidak diperlukan, Anda dapat mengatur nilainya ke salah satu berikut: NULL String kosong String daftar kosong: []

   Contoh

   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."}] Sebagai contoh, untuk membuat pertanyaan templat pertama yang ditunjukkan dalam tabel di atas, jalankan SQL berikut:

   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. Buat tabel indeks templat pertanyaan

   Anda dapat menggunakan nama kustom untuk tabel indeks, asalkan mengikuti konvensi penamaan database. Contoh ini menggunakan pattern_index. Jalankan SQL berikut untuk membuat tabel indeks templat pertanyaan:

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

   Catatan

   • Tabel indeks templat pertanyaan tidak muncul dalam daftar objek basis data. Untuk melihatnya, jalankan /*polar4ai*/SHOW TABLES;.

   • Untuk menghapus tabel indeks templat pertanyaan, misalnya pattern_index, jalankan pernyataan SQL /*polar4ai*/DROP TABLE IF EXISTS pattern_index;.

3. Impor data ke tabel indeks

   Catatan

   Tabel templat pertanyaan tidak boleh kosong. Sebelum menjalankan SQL untuk mengimpor data, tambahkan setidaknya satu catatan.

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

   Parameter

   • _polar4ai_text2vec adalah model text-to-vectorization.

   • Setelah INTO, tentukan nama tabel indeks templat pertanyaan yang dibuat di Langkah 2.

   • Anda dapat mengonfigurasi beberapa parameter dalam klausa WITH():

     Parameter	Wajib	Deskripsi
     mode	Ya	Menentukan mode penulisan. Harus async untuk mode asinkron.
     resource	Ya	Menentukan jenis resource. Harus pattern untuk melakukan vektorisasi informasi templat pertanyaan.
     pattern_table_name	Tidak	Nama tabel templat pertanyaan yang akan divectorisasi. Ini adalah nama tabel dari Langkah 1. Nilai default adalah polar4ai_nl2sql_pattern, artinya vektorisasi dilakukan pada tabel polar4ai_nl2sql_pattern. Jika Anda mengatur parameter ini, Anda harus menentukan nama tabel yang diawali dengan polar4ai_nl2sql_pattern.

     Jika Anda ingin mempertahankan tabel indeks templat pertanyaan yang berbeda untuk skenario atau domain bisnis yang berbeda, Anda dapat menentukan nama tabel yang berbeda saat membuatnya. Misalnya, jika Anda membuat tabel polar4ai_nl2sql_pattern_user untuk skenario terkait pengguna, Anda dapat mengatur nama indeks menjadi pattern_index_user di Langkah 2. Saat mengimpor informasi, gunakan pernyataan SQL berikut:

     /*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. Periksa status tugas

   Setelah menjalankan pernyataan impor, sistem mengembalikan task_id, seperti bce632ea-97e9-11ee-bdd2-492f4dfe0918. Anda dapat menjalankan perintah berikut untuk memeriksa status tugas.

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

   Ketika status tugas adalah finish, impor selesai, dan model dapat mereferensikan informasi templat pertanyaan. Anda dapat menjalankan pernyataan SQL berikut untuk melihat informasi indeks templat pertanyaan:

   /*polar4ai*/SELECT * FROM pattern_index;

   Catatan

   Jika data dalam tabel polar4ai_nl2sql_pattern berubah, Anda harus menjalankan kembali prosedur di Langkah 3.

5. Jalankan kueri online dengan templat pertanyaan

   Jalankan pernyataan SQL berikut untuk melakukan kueri online menggunakan LLM-based NL2SQL dan templat pertanyaan:

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

   Parameter

   • Setelah SELECT, masukkan pertanyaan yang akan dikonversi menjadi SQL.

   • basic_index_name adalah nama tabel indeks pencarian di database saat ini.

   • pattern_index_name adalah nama tabel indeks templat pertanyaan.

   • Anda dapat mengonfigurasi beberapa parameter dalam klausa WITH(). Untuk deskripsi parameter lainnya, lihat Jalankan kueri online dengan LLM-based NL2SQL.

     Parameter	Deskripsi	Rentang nilai
     pattern_index_top	Jumlah templat pertanyaan terdekat yang akan di-recall.	Rentang nilai: [1,10]. Nilai default adalah 2, yang berarti hanya 2 templat teratas yang di-recall untuk pertanyaan saat ini.
     pattern_index_threshold	Ambang batas kemiripan untuk meng-recall templat pertanyaan.	Rentang nilai: (0,1]. Nilai default adalah 0,85, yang berarti templat dipilih hanya jika skor kemiripan vektornya melebihi 0,85.

Kasus penggunaan

• Skenario 1: Ganti istilah tertentu dalam pertanyaan, seperti nama, jargon industri, atau nama produk.

  Contohnya: untuk semua pertanyaan yang melibatkan Zhang San, ganti Zhang San dengan ZS001. Dalam kasus ini, untuk pertanyaan What were Zhang San's sales last month? dan What are Zhang San's total sales for this year?, Anda dapat menggunakan tabel konfigurasi untuk memprosesnya menjadi What were ZS001's sales last month? dan What are ZS001's total sales for this year? sebelum panggilan akhir ke large language model.

• Skenario 2: Tambahkan konteks tambahan ke pertanyaan yang mengandung istilah tertentu.

  Contohnya: untuk semua pertanyaan yang melibatkan Total Sales, formula perhitungan Total Sales = SUM(Sales) harus ditambahkan. Sebelum panggilan akhir ke large model, informasi ini dapat ditambahkan melalui tabel konfigurasi dan ditambahkan saat pertanyaan memenuhi kondisi yang sesuai.

• Skenario 3: Petakan dan ganti nilai untuk tabel atau kolom tertentu dalam SQL akhir.

  Contohnya: untuk semua pernyataan SQL yang akhirnya melibatkan tabel student_courses, ganti status = 'leave' dengan status = 0 sebagai langkah cadangan untuk pemetaan nilai kolom.

Sintaks

Gunakan pernyataan SQL berikut untuk membuat tabel konfigurasi. Nama tabel polar4ai_nl2sql_llm_config bersifat tetap dan tidak dapat diubah.

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;

Parameter

Contoh

1. Saat dijalankan tanpa tabel konfigurasi, kueri berikut:

   /*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. Buat tabel konfigurasi seperti yang dijelaskan di bagian Sintaks.

3. Tambahkan catatan konfigurasi. Aturan ini menentukan bahwa jika pernyataan SQL mereferensikan tabel students atau tabel student_courses, tetapi tidak mereferensikan tabel courses, sistem mengganti status = 0 dengan 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. Jalankan kembali kueri dari Langkah 1. Nilai status dalam SQL yang dihasilkan sekarang diganti sesuai aturan yang ditentukan.

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

Sintaks

Pernyataan SQL berikut membuat tabel komentar kustom. Nama tabel polar4ai_nl2sql_table_extra_info tidak dapat diubah.

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;

Contoh

1. Buat tabel komentar kustom.

2. Perbarui komentar untuk kolom status di tabel student_courses. Contoh ini menambahkan pemetaan opsi baru: 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. Jalankan kembali langkah untuk mengimpor informasi tabel data ke indeks skema.

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

4. Periksa status tugas.

   Setelah menjalankan pernyataan impor, sistem mengembalikan task_id, seperti bce632ea-97e9-11ee-bdd2-492f4dfe0918. Gunakan perintah berikut untuk memeriksa status impor. Ketika taskStatus adalah finish, tugas selesai.

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

5. Jalankan kueri menggunakan 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;

   Output menunjukkan bahwa model LLM-based NL2SQL sekarang secara benar memetakan Absent ke nilai 2 untuk kolom status di tabel student_courses.