Usar parâmetros em consultas SQL

Este artigo explica como usar parâmetros ao escrever instruções SQL de exemplo em um espaço Genie.

Porquê utilizar parâmetros?

Os parâmetros permitem escrever consultas de exemplo com espaços reservados para valores específicos a serem substituídos em tempo de execução. Com parâmetros, o Genie pode receber entradas específicas de perguntas do usuário e reutilizar a estrutura de uma consulta de exemplo para fornecer respostas verificadas como ativos confiáveis. Por exemplo, você pode ajustar a consulta SQL anterior para incluir um parâmetro que filtra pelo valor o.forecastcategory, permitindo que a consulta responda a perguntas sobre oportunidades marcadas em diferentes categorias de previsão. Para obter mais informações sobre como usar consultas parametrizadas para gerar respostas rotuladas como ativos confiáveis, consulte Usar ativos confiáveis em espaços do AI/BI Genie.

O exemplo de consulta a seguir calcula o valor total das oportunidades de vendas no pipeline aberto por região. Inclui um parâmetro para o valor o.forecastcategory. Os parâmetros usam a mesma sintaxe que os marcadores de parâmetros nomeados. Para obter mais orientações sobre como usar parâmetros em um espaço Genie, consulte Trabalhar com parâmetros de consulta e Marcadores de parâmetros nomeados.

-- Return our current pipeline at a stage by region.
-- Opportunities are only considered pipelines if they are tagged as such.
  SELECT
    a.region__c AS `Region`,
    sum(o.amount) AS `Open Pipeline`
  FROM
    sales.crm.opportunity o
    JOIN sales.crm.accounts a ON o.accountid = a.id
  WHERE
    o.forecastcategory = :forecast_category AND
    o.stagename NOT ILIKE '%closed%'
  GROUP BY ALL;

Para adicionar um parâmetro a uma consulta:

1. Coloque o cursor onde pretende colocar o parâmetro na consulta.

2. Clique em Adicionar parâmetro para inserir um novo parâmetro.

   Isso cria um novo parâmetro com o nome padrão parameter. Para alterar o nome padrão, substitua-o no editor de consultas. Você também pode adicionar parâmetros digitando dois pontos seguidos por um nome de parâmetro (:parameter_name) no editor.

Editar um parâmetro de consulta

Para editar um parâmetro, faça o seguinte:

1. Clique no ao lado do nome do parâmetro. Uma caixa de diálogo Parameter details é exibida e inclui as seguintes opções de configuração:

   • Keyword: A palavra-chave que representa o parâmetro na consulta. A palavra-chave só pode ser alterada atualizando diretamente o texto na consulta.

   • Nome de exibição: O nome legível por humanos que o Genie usa na experiência de bate-papo. Quando o Genie gera uma resposta usando uma consulta parametrizada, ele inclui o nome para exibição e o valor associado na resposta.

   • Tipo: Os tipos suportados incluem String, Data, Data e Horae Numérica.

     • O tipo padrão é String.
     • O tipo de dados numérico permite especificar entre decimal e inteiro. O tipo numérico padrão é Decimal.

     Observação

     Se o valor de entrada real não corresponder ao tipo de parâmetro selecionado, o Genie tratará o valor de entrada como o tipo incorreto, o que pode levar a resultados imprecisos.

2. Clique em outra parte da interface do usuário para fechar a caixa de diálogo.

Respostas de consulta parametrizadas

Quando o texto exato de um parâmetro é usado em uma resposta, a resposta é marcada como confiável. Isso significa que o Genie identificou, com base no contexto do espaço, que a pergunta do usuário correspondia à intenção de uma pergunta ou consulta de exemplo.

O rótulo Trusted permite que os usuários de espaço saibam que a resposta do Genie é baseada em uma consulta SQL verificada. Eles podem ver os valores SQL e paramter gerados que são usados na resposta.