PolarDB:NL2SQL: Kueri bahasa alami

Petunjuk

1. Buat tabel templat pertanyaan

   Nama tabel templat pertanyaan harus diawali dengan polar4ai_nl2sql_pattern, dan skemanya harus mencakup lima kolom dari 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 templat pertanyaan

   Nama kolom	Deskripsi
   Template question	Pertanyaan dengan parameter, disediakan sebagai input ke model LLM-based NL2SQL. Dalam templat pertanyaan, tulis parameter dalam format #{XXX}.
   Template description	Rangkuman templat pertanyaan, dengan beberapa entitas sebagai parameter, seperti tanggal, tahun, atau organisasi. Entitas ini biasanya sesuai dengan kolom tertentu di tabel. Dalam deskripsi templat, tulis parameter dalam format [XXX], dan urutannya harus sama dengan parameter dalam templat pertanyaan.
   Template SQL	Pernyataan SQL yang benar sesuai dengan templat pertanyaan. Pernyataan SQL ini harus memperlakukan parameter dari templat pertanyaan sebagai variabel. Catatan Parameter dalam templat pertanyaan dan templat SQL dapat berbeda, tetapi harus saling terkait. Misalnya, parameter harus memiliki awalan yang sama, dan nilainya harus memiliki pemetaan satu-ke-satu. Untuk #{category} dan #{categoryCode}, jika nilai parameter untuk category adalah common trademark, special trademark, dan collective trademark, maka nilai categoryCode yang sesuai adalah 0, 1, dan 2. Untuk informasi selengkapnya, lihat contoh di bawah.
   Template parameters	Parameter templat adalah string JSON dengan struktur yang terdiri dari tiga parameter: table_name, param_info, dan explanation. Parameter-parameter tersebut adalah sebagai berikut: table_name string: Nama tabel dalam templat SQL. param_info array: Deskripsi parameter dalam templat SQL. param_name string: Nama parameter. value array: Nilai sampel untuk parameter. Catatan Jika parameter sesuai dengan himpunan nilai enumerasi terbatas, cantumkan semua nilai dalam value. Jika hanya nilai sampel, Anda dapat mencantumkan 2 hingga 4 nilai. Jika ada parameter yang saling berkaitan, Anda perlu memetakannya menggunakan indeks array. Untuk #{category} dan #{categoryCode}, "common trademark" dalam category sesuai dengan 0 dalam categoryCode, dan "special trademark" sesuai dengan 2 dalam categoryCode. Untuk informasi selengkapnya, lihat contoh di bawah. explanation string: Informasi tambahan. Biasanya mencakup persyaratan untuk pernyataan SQL yang dihasilkan, seperti informasi apa yang harus ditampilkan atau deskripsi bidang. Catatan Jika Anda tidak perlu menentukan parameter templat, Anda dapat mengatur nilai parameter templat 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 status #{status}	What are the courses with [Course Name] and [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 the year #{issueDate} for projects with the status #{projectStat}?	What are the national standards planned for release in [Year] for projects 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":"Output the standard name (projectCnName), plan number, and project status"}]
   What are the trademarks of type #{category} and international classification #{intCls}?	What are the trademarks of [Trademark Type] and [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 and varnishes","Cosmetics and cleaning preparations","Industrial oils and greases","Pharmaceuticals"]},{"param_name":"#{category}","value":["Common trademark","Special trademark","Collective trademark"]},{"param_name":"#{intClsCode}","value":[1,2,3,4,5]},{"param_name":"#{categoryCode}","value":[0,1,2]}],"explanation":"Output the 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."}]

   Menggunakan skenario dalam topik ini sebagai contoh, buat templat pertanyaan pertama dalam tabel di atas. Jalankan pernyataan SQL berikut:

   INSERT INTO `polar4ai_nl2sql_pattern` (`pattern_question`,`pattern_description`,`pattern_sql`,`pattern_params`) VALUES ('Query for courses with course name #{courseName} and status #{status}','What are the courses with [Course Name] and [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 tabel indeks kustom yang sesuai dengan spesifikasi database. Topik ini menggunakan pattern_index sebagai contoh. Pernyataan SQL untuk membuat tabel indeks templat pertanyaan adalah sebagai berikut:

   /*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 ditampilkan secara langsung di database. Untuk melihat informasi terkait, Anda dapat menjalankan pernyataan SQL /*polar4ai*/SHOW TABLES;.

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

3. Impor informasi dari tabel templat pertanyaan ke tabel indeks

   Catatan

   Tabel templat pertanyaan tidak boleh kosong. Sebelum menjalankan pernyataan SQL untuk mengimpor data ke tabel indeks, Anda harus menambahkan setidaknya satu catatan.

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

   Deskripsi parameter

   • _polar4ai_text2vec adalah model teks-ke-vektor.

   • Setelah INTO, tentukan nama tabel indeks templat pertanyaan yang Anda buat di Langkah 2. Buat tabel indeks templat pertanyaan.

   • Anda dapat mengonfigurasi beberapa parameter dalam WITH() untuk mengatur perilaku terkait:

     Parameter	Wajib	Deskripsi
     mode	Ya	Mode penulisan data. Nilainya tetap `async` untuk mode asinkron.
     resource	Ya	Jenis resource. Nilainya tetap `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: Buat tabel templat pertanyaan. Nilai default adalah polar4ai_nl2sql_pattern, yang melakukan vektorisasi pada tabel polar4ai_nl2sql_pattern. Saat mengatur ini, tentukan nama tabel templat pertanyaan yang diawali dengan polar4ai_nl2sql_pattern.

     Jika Anda ingin mempertahankan tabel indeks templat pertanyaan yang berbeda untuk skenario atau bisnis yang berbeda, Anda dapat menentukan nama tabel yang berbeda saat membuat tabel indeks templat pertanyaan. Misalnya, Anda dapat membuat tabel polar4ai_nl2sql_pattern_user untuk skenario terkait pengguna, lalu pada langkah kedua pembuatan indeks templat pertanyaan, atur nama indeks menjadi pattern_index_user. Saat mengimpor informasi ke tabel indeks, 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 untuk mengimpor data ke tabel indeks, task_id untuk tugas tersebut dikembalikan, misalnya bce632ea-97e9-11ee-bdd2-492f4dfe0918. Anda dapat menggunakan perintah berikut untuk memeriksa status impor.

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

   Saat nilai kembali adalah finish, tugas telah selesai. Informasi templat pertanyaan kemudian dapat dirujuk oleh model. 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 Langkah 3. Impor informasi dari tabel templat pertanyaan ke tabel indeks.

5. Gunakan templat pertanyaan online

   Anda dapat menjalankan pernyataan SQL berikut untuk menggunakan LLM-based NL2SQL dan templat pertanyaan secara online:

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

   Deskripsi parameter

   • Setelah SELECT, masukkan pertanyaan yang ingin Anda ubah menjadi pernyataan 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 WITH() untuk mengatur perilaku terkait. Untuk informasi selengkapnya tentang parameter lainnya, lihat Gunakan LLM-based NL2SQL online:

     Nama parameter	Deskripsi parameter	Rentang nilai
     pattern_index_top	Jumlah templat pertanyaan paling mirip yang diambil.	Nilai yang valid: [1,10]. Nilai default adalah 2, yang memilih 2 templat paling optimal untuk templat pertanyaan saat ini.
     pattern_index_threshold	Ambang batas yang digunakan untuk menentukan kesamaan templat pertanyaan yang diambil.	Nilai yang valid: (0,1]. Nilai default adalah 0,85. Templat pertanyaan dipilih hanya jika skor kecocokan vektornya melebihi 0,85.

Skenario

• Skenario 1: Ganti kata deterministik dalam pertanyaan, seperti nama, istilah industri, atau nama produk.

  Misalnya, untuk semua pertanyaan yang melibatkan Zhang San, Anda dapat mengganti Zhang San dengan ZS001. Dalam hal ini, untuk pertanyaan What were Zhang San's sales last month? dan What are Zhang San's total sales this year?, Anda dapat menggunakan tabel konfigurasi untuk pra-prosesnya menjadi What were ZS001's sales last month? dan What are ZS001's total sales this year? sebelum memanggil model bahasa besar.

• Skenario 2: Tambahkan informasi tambahan ke pertanyaan yang mengandung kata tertentu.

  Misalnya, untuk semua pertanyaan yang melibatkan total sales, Anda dapat menambahkan rumus perhitungan untuk total sales: Total sales = SUM(sales). Sebelum memanggil model bahasa besar, Anda dapat menggunakan tabel konfigurasi untuk menambahkan informasi jenis ini, yang ditambahkan saat pertanyaan memenuhi kondisi yang sesuai.

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

  Misalnya, untuk semua pernyataan SQL akhir yang melibatkan tabel student_courses, Anda dapat mengganti status = 'on leave' dengan status = 0 sebagai langkah cadangan untuk pemetaan nilai kolom.

Sintaks

Pernyataan SQL untuk membuat tabel konfigurasi adalah sebagai berikut. 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 'Whether it is effective',
  `text_condition` text COMMENT 'Text condition',
  `query_function` text COMMENT 'Query processing',
  `formula_function` text COMMENT 'Formula information',
  `sql_condition` text COMMENT 'SQL condition',
  `sql_function` text COMMENT 'SQL processing',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci;

Deskripsi parameter

Contoh

1. Sebelum menambahkan tabel konfigurasi, jalankan pernyataan SQL berikut:

   /*polar4ai*/SELECT * FROM PREDICT (MODEL _polar4ai_nl2sql, SELECT 'Filter untuk 2 siswa dengan ketidakhadiran terbanyak, urutkan berdasarkan jumlah ketidakhadiran secara menurun, dan tampilkan nama serta jumlah ketidakhadiran mereka.') 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 sesuai dengan Sintaks.

3. Tambahkan catatan konfigurasi. Jika tabel students atau tabel student_courses ada dalam pernyataan SQL, dan tabel courses tidak ada, ganti 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 pernyataan SQL dari Langkah 1. Pernyataan SQL yang dihasilkan sekarang memiliki nilai status yang diganti.

   /*polar4ai*/SELECT * FROM PREDICT (MODEL _polar4ai_nl2sql, SELECT 'Filter untuk 2 siswa dengan ketidakhadiran terbanyak, urutkan berdasarkan jumlah ketidakhadiran secara menurun, dan tampilkan nama serta jumlah ketidakhadiran mereka.') 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 untuk membuat tabel komentar tabel dan kolom kustom adalah sebagai berikut. Nama tabel polar4ai_nl2sql_table_extra_info bersifat tetap dan 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 untuk tabel dan kolom kustom.

2. Ubah komentar untuk kolom status di tabel student_courses. Dalam contoh ini, deskripsi opsi baru ditambahkan untuk kolom status: 2-Absent.

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

3. Jalankan kembali langkah untuk mengimpor data dari tabel data ke tabel indeks pencarian.

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

4. Periksa status tugas.

   Setelah menjalankan pernyataan untuk mengimpor data ke tabel indeks pencarian, task_id untuk tugas tersebut dikembalikan, misalnya bce632ea-97e9-11ee-bdd2-492f4dfe0918. Anda dapat menggunakan perintah berikut untuk memeriksa status impor. Saat taskStatus adalah finish, tugas telah selesai.

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

5. Gunakan LLM-based NL2SQL online.

   /*polar4ai*/SELECT * FROM PREDICT (MODEL _polar4ai_nl2sql, SELECT 'Filter untuk 2 siswa dengan ketidakhadiran terbanyak, urutkan berdasarkan jumlah ketidakhadiran secara menurun, dan tampilkan nama serta jumlah ketidakhadiran mereka.') 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;

   Dari output di atas, Anda dapat melihat bahwa model LLM-based NL2SQL telah memetakan absent ke nilai kolom 2 untuk kolom status di tabel student_courses.