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.

For more granular control, you can also specify custom instructions for individual modules in the SQL generation pipeline. See Instruções personalizadas do módulo for more information.

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.

For more information about the semantic model syntax, see Utilização dos comandos SQL para criar e gerenciar exibições semânticas.

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."

Consulta SQL gerada

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

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."

Consulta SQL gerada

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

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."

Consulta SQL gerada

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

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."

Consulta SQL gerada

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

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."

Depois:

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

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.

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.

Custom instructions through Cortex Agents

When Cortex Analyst is used as a tool within a Cortex Agent, the agent follows your custom instructions with higher fidelity. In this mode, the agent interprets your natural-language instructions directly, rather than relying on specific state keywords like UNCLEAR.

You can write custom instructions in plain language without referencing categorization states. For example:

module_custom_instructions:
  question_categorization: |
    - If the question asks for users without providing a product_type, ask the user to specify product_type.
    - Reject all questions about salary data and tell the user this information is not available.

The categorization state keywords (such as UNCLEAR) continue to work when using the Cortex Analyst API directly. However, when your semantic model is accessed through a Cortex Agent, writing instructions in plain natural language is recommended, as the agent can follow nuanced instructions more precisely.

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.