:Natural language to SQL with an LLM

Procedimento

1. Criar uma tabela de modelo de pergunta

   O nome da tabela de modelo de pergunta deve começar com polar4ai_nl2sql_pattern, e seu esquema deve incluir as cinco colunas definidas na seguinte instrução CREATE TABLE.

   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;

   Descrições das colunas

   Parâmetro	Descrição
   template question	Uma pergunta parametrizada que serve como entrada para o modelo de NL2SQL baseado em LLM. Na pergunta do modelo, escreva os parâmetros no formato #{XXX}.
   template description	Um resumo da pergunta do modelo, com entidades como datas, anos ou organizações extraídas como parâmetros. Essas entidades geralmente mapeiam para colunas específicas em uma tabela. Na descrição do modelo, escreva os parâmetros no formato [XXX], e sua ordem deve ser consistente com a ordem dos parâmetros na pergunta do modelo.
   template SQL	O SQL correto para a pergunta do modelo. Neste SQL, os parâmetros da pergunta do modelo são tratados como variáveis. Nota Os parâmetros na pergunta do modelo e no SQL do modelo não precisam ser idênticos, mas devem estar relacionados. Por exemplo, os parâmetros podem compartilhar um prefixo comum, e seus valores podem ter um mapeamento um para um. Com #{category} e #{categoryCode}, quando os valores de parâmetro para category são "marca ordinária", "marca especial" e "marca coletiva", os valores correspondentes de categoryCode são 0, 1 e 2, respectivamente. Para detalhes, veja o exemplo abaixo.
   template parameters	Uma string JSON composta por três parâmetros: table_name, param_info e explanation. table_name string: o nome da tabela usado no SQL do modelo. param_info array: descrição dos parâmetros no SQL do modelo. param_name string: o nome do parâmetro. value array: valores de amostra para o parâmetro. Nota Se o parâmetro tiver um conjunto finito de valores enumerados, liste todos eles no array value, se possível. Se você fornecer apenas valores de amostra, liste de 2 a 4 exemplos. Se os parâmetros forem interdependentes, mapeie-os usando o índice do array. Por exemplo, com #{category} e #{categoryCode}, "marca ordinária" em category corresponde a 0 em categoryCode, e "marca especial" corresponde a 1 em categoryCode. Para detalhes, veja o exemplo abaixo. explanation string: notas adicionais, que geralmente descrevem requisitos para o SQL gerado, como quais informações retornar ou como interpretar campos específicos. Nota Se os parâmetros do modelo não forem necessários, defina o valor como um dos seguintes: NULL Uma string vazia Uma string de lista vazia: []

   Exemplo

   Pergunta do modelo	Descrição do modelo	SQL do modelo	Parâmetros do modelo
   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."}] Por exemplo, para criar a primeira pergunta de modelo mostrada na tabela acima, execute o seguinte 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】【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. Criar uma tabela de índice de modelo de pergunta

   Use um nome personalizado para a tabela de índice, desde que siga as convenções de nomenclatura do banco de dados. Este exemplo usa pattern_index. Execute o seguinte SQL para criar a tabela de índice de modelo de pergunta:

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

   Nota

   • A tabela de índice de modelo de pergunta não aparece na lista de objetos do banco de dados. Para visualizá-la, execute /*polar4ai*/SHOW TABLES;.

   • Para excluir a tabela de índice de modelo de pergunta, por exemplo, pattern_index, execute a instrução SQL /*polar4ai*/DROP TABLE IF EXISTS pattern_index;.

3. Importar dados para a tabela de índice

   Nota

   A tabela de modelo de pergunta não pode estar vazia. Antes de executar o SQL para importar dados, adicione pelo menos um registro.

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

   Parâmetros

   • _polar4ai_text2vec é o modelo de vetorização de texto.

   • Após INTO, especifique o nome da tabela de índice de modelo de pergunta criada na Etapa 2.

   • Configure vários parâmetros na cláusula WITH():

     Parâmetro	Obrigatório	Descrição
     mode	Sim	Especifica o modo de gravação. Deve ser async para modo assíncrono.
     resource	Sim	Especifica o tipo de recurso. Deve ser pattern para vetorizar informações do modelo de pergunta.
     pattern_table_name	Não	Nome da tabela de modelo de pergunta a ser vetorizada. Este é o nome da tabela da Etapa 1. O valor padrão é polar4ai_nl2sql_pattern, o que significa que a vetorização ocorre na tabela polar4ai_nl2sql_pattern. Se você definir este parâmetro, deverá especificar um nome de tabela que comece com polar4ai_nl2sql_pattern.

     Para manter tabelas de índice de modelo de pergunta diferentes para cenários ou domínios de negócios distintos, especifique nomes de tabela diferentes ao criá-las. Por exemplo, se você criar uma tabela polar4ai_nl2sql_pattern_user para cenários relacionados a usuários, poderá definir o nome do índice como pattern_index_user na Etapa 2. Ao importar as informações, use a seguinte instrução 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. Verificar o status da tarefa

   Após executar a instrução de importação, o sistema retorna um task_id, como bce632ea-97e9-11ee-bdd2-492f4dfe0918. Execute o comando a seguir para verificar o status da tarefa.

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

   Quando o status da tarefa for finish, a importação estará concluída e o modelo poderá referenciar as informações do modelo de pergunta. Execute a seguinte instrução SQL para visualizar as informações do índice de modelo de pergunta:

   /*polar4ai*/SELECT * FROM pattern_index;

   Nota

   Se os dados na tabela polar4ai_nl2sql_pattern forem alterados, execute novamente o procedimento na Etapa 3.

5. Executar uma consulta online com modelos de pergunta

   Execute a seguinte instrução SQL para realizar uma consulta online usando NL2SQL baseado em LLM e modelos de pergunta:

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

   Parâmetros

   • Após SELECT, insira a pergunta a ser convertida em SQL.

   • basic_index_name é o nome da tabela de índice de busca do banco de dados atual.

   • pattern_index_name é o nome da tabela de índice de modelo de pergunta.

   • Configure vários parâmetros na cláusula WITH(). Para descrições de outros parâmetros, consulte Executar uma consulta online com NL2SQL baseado em LLM.

     Parâmetro	Descrição	Intervalo de valores
     pattern_index_top	Número de modelos de pergunta mais próximos a serem recuperados.	Intervalo de valores: [1,10]. O valor padrão é 2, o que significa que apenas os 2 principais modelos são recuperados para a pergunta atual.
     pattern_index_threshold	Limiar de similaridade para recuperar um modelo de pergunta.	Intervalo de valores: (0,1]. O valor padrão é 0,85, o que significa que um modelo só é selecionado se sua pontuação de similaridade vetorial exceder 0,85.

Casos de uso

• Cenário 1: Substituir termos específicos em uma pergunta, como nomes, jargões do setor ou nomes de produtos.

  Por exemplo: para todas as perguntas envolvendo Zhang San, substitua Zhang San por ZS001. Nesse caso, para as perguntas What were Zhang San's sales last month? e What are Zhang San's total sales for this year?, use uma tabela de configuração para pré-processá-las em What were ZS001's sales last month? e What are ZS001's total sales for this year? antes da chamada final ao modelo de linguagem grande.

• Cenário 2: Adicionar contexto extra a perguntas que contêm termos específicos.

  Por exemplo, para todas as perguntas envolvendo Total Sales, a fórmula de cálculo Total Sales = SUM(Sales) deve ser anexada. Antes da chamada final ao modelo grande, essas informações podem ser adicionadas por meio de uma tabela de configuração e são anexadas quando a pergunta atende à condição correspondente.

• Cenário 3: Mapear e substituir valores para tabelas ou colunas específicas no SQL final.

  Por exemplo, para todas as instruções SQL que envolvem a tabela student_courses, substitua status = 'leave' por status = 0 como medida alternativa para mapeamento de valores de coluna.

Sintaxe

Use a seguinte instrução SQL para criar a tabela de configuração. O nome da tabela polar4ai_nl2sql_llm_config é fixo e não pode ser alterado.

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;

Parâmetros

Exemplo

1. Ao executar sem uma tabela de configuração, a seguinte consulta:

   /*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. Crie a tabela de configuração conforme descrito na seção Sintaxe.

3. Adicione um registro de configuração. Esta regra especifica que, se uma instrução SQL referenciar a tabela students ou a tabela student_courses, mas não a tabela courses, o sistema substituirá status = 0 por 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. Execute a consulta da Etapa 1 novamente. O valor de status no SQL gerado agora é substituído conforme especificado pela regra.

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

Sintaxe

A seguinte instrução SQL cria a tabela de comentários personalizados. O nome da tabela polar4ai_nl2sql_table_extra_info não pode ser alterado.

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;

Exemplo

1. Crie a tabela de comentários personalizados.

2. Atualize o comentário da coluna status na tabela student_courses. Este exemplo adiciona um novo mapeamento de opção: 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. Execute novamente a etapa para importar informações da tabela de dados para o índice de esquema.

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

4. Verifique o status da tarefa.

   Após executar a instrução de importação, o sistema retorna um task_id, como bce632ea-97e9-11ee-bdd2-492f4dfe0918. Use o comando a seguir para verificar o status da importação. Quando taskStatus for finish, a tarefa estará concluída.

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

5. Execute uma consulta usando o NL2SQL baseado em LLM.

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

   A saída mostra que o modelo NL2SQL baseado em LLM agora mapeia corretamente Absent para o valor 2 na coluna status da tabela student_courses.