Instruções personalizadas no Cortex Analyst

As instruções personalizadas permitem que você tenha maior controle sobre a geração do SQL. Usando linguagem natural, você pode informar ao Cortex Analyst exatamente como gerar consultas SQL a partir do seu arquivo de modelo semântico YAML. Por exemplo, use instruções personalizadas para informar ao Cortex Analyst o que você quer dizer com desempenho ou ano financeiro. Dessa forma, você pode melhorar a precisão do SQL gerado incorporando lógica personalizada ou elementos adicionais.

Para obter um controle mais granular, você também pode especificar instruções personalizadas para módulos individuais no pipeline de geração do SQL. Consulte Instruções personalizadas do módulo para obter mais informações.

Como funcionam as instruções personalizadas

O Cortex Analyst introduz o campo custom_instructions no arquivo YAML do modelo semântico. Esse campo permite que você aplique modificações ou acréscimos de definição à geração de SQL.

Para obter mais informações sobre a sintaxe do modelo semântico, consulte Especificação do modelo semântico Cortex Analyst.

Exemplos

Para explorar possíveis casos de uso de instruções personalizadas, considere os exemplos a seguir.

Formatação da saída de dados

Certifique-se de que todos os números na saída sejam arredondados para duas casas decimais.

O campo custom_instructions no arquivo YAML do modelo semântico

custom_instructions: "Ensure that all numeric columns are rounded to 2 decimal points in the output."
Copy

Consulta SQL gerada

SELECT
  ROUND(column_name, 2) AS column_name,
  ...
FROM
  your_table;
Copy

Ajuste de porcentagens

Multiplicar automaticamente os cálculos de porcentagem ou taxa por 100 para manter a consistência.

O campo custom_instructions no arquivo YAML do modelo semântico

custom_instructions: "For any percentage or rate calculation, multiply the result by 100."
Copy

Consulta SQL gerada

SELECT
  (column_a / column_b) * 100 AS percentage_rate,
  ...
FROM
  your_table;
Copy

Como adicionar filtros padrão

Aplique um filtro se o usuário não especificar um (por exemplo, padrão para o último ano).

O campo custom_instructions no arquivo YAML do modelo semântico

custom_instructions: "If no date filter is provided, apply a filter for the last year."
Copy

Consulta SQL gerada

SELECT
  ...
FROM
  your_table
WHERE
  date_column >= DATEADD(YEAR, -1, CURRENT_DATE);
Copy

Vinculação de filtros de coluna

Aplique filtros adicionais em colunas relacionadas com base na entrada do usuário.

O campo custom_instructions no arquivo YAML do modelo semântico

custom_instructions: "If a filter is applied on column X, ensure that the same filter is applied to dimension Y."
Copy

Consulta SQL gerada

SELECT
  ...
FROM
  your_table
WHERE
  column_x = 'filter_value' AND
  dimension_y = 'filter_value';
Copy

Instruções personalizadas do módulo

Defina a chave module_custom_instructions no nível superior de seu modelo semântico para definir instruções personalizadas para componentes específicos no pipeline de geração SQL. Esse recurso é útil para casos de uso como os seguintes:

  • Defina a lógica que influencia como as perguntas do usuário são interpretadas antes da geração do SQL

  • Mantenha as instruções separadas e mais estruturadas para diferentes partes do fluxo de trabalho do Analyst

  • Transição do custom_instructions existente para um formato mais modular à medida que seu uso cresce

Atualmente, module_custom_instructions é compatível com os seguintes componentes:

  • question_categorization: defina como o Cortex Analyst deve classificar as perguntas dos usuários (por exemplo, bloqueando determinados tópicos ou orientando o comportamento do usuário).

  • sql_generation: especifique como o SQL deve ser gerado (por exemplo, formatação e filtragem de dados).

As instruções para um ou ambos os componentes podem ser definidas na chave module_custom_instructions.

Importante

Migre qualquer custom_instructions existente para o componente sql_generation, conforme mostrado no exemplo a seguir.

Migração de instruções personalizadas existentes

Se seu modelo já tiver um campo custom_instructions, migre seu conteúdo para o campo sql_generation em module_custom_instructions.

Antes:

custom_instructions: "Ensure that all numeric columns are rounded to 2 decimal points."
Copy

Depois:

module_custom_instructions:
  sql_generation: |
     "Ensure that all numeric columns are rounded to 2 decimal points."
Copy

Bloqueio de perguntas sobre tópicos específicos

Você pode usar o componente question_categorization para bloquear perguntas sobre tópicos específicos. Por exemplo, se quiser bloquear perguntas sobre usuários, você pode definir as seguintes instruções. Cortex Analyst rejeita perguntas sobre usuários com uma mensagem dizendo para entrarem em contato com o administrador.

module_custom_instructions:
  question_categorization: |
     Reject all questions asking about users. Ask users to contact their admin.
Copy

Você também pode usar as instruções de categorização de perguntas para solicitar os detalhes que faltam. No exemplo a seguir, o Cortex Analyst solicita que o usuário forneça um tipo de produto se ele perguntar sobre usuários e não especificar um.

module_custom_instructions:
  question_categorization: |
    - If the question asks for users without providing a product_type, consider this question UNCLEAR and ask the user to specify product_type.
Copy

Práticas recomendadas

Seja específico.

Descreva claramente as modificações; por exemplo, «Adicione uma coluna com um valor fixo de 42» ou «Inclua um cálculo de soma para a coluna X».

Comece com pouco.

Comece com modificações simples, como adicionar uma coluna estática ou filtros padrão, antes de passar para cenários mais complexos.

Visualize a consulta SQL gerada.

Certifique-se de que as instruções sejam aplicadas como pretendido e que a consulta SQL gerada esteja correta.

Itere gradualmente.

Faça experiências com casos de uso mais complexos à medida que sua familiaridade com o recurso aumentar.

Linguagem: Português