Melhores práticas para melhorar a geração de consultas de agentes de dados

Um agente de dados gera consultas melhores quando possui um contexto focado e preciso sobre os dados que pode usar. Nomes de objetos e metadados de esquemas fornecem um ponto de partida, mas podem não explicar o significado de negócio, valores esperados, relacionamentos ou a lógica de consulta necessária para responder a uma pergunta.

Use a configuração que melhor corresponde ao contexto que você precisa fornecer:

Para uma visão geral dessas configurações, veja Configurações do agente de dados.

Use nomes claros de esquemas

Use nomes descritivos para fontes de dados, tabelas e colunas quando você controlar o esquema. Nomes como CustomerOrders, , e product_unit_price dão ao agente sinais mais úteis do que nomes como Table1, date1, e valueorder_submission_date.

Não confie apenas nos nomes. Mesmo um nome técnico claro pode não comunicar o significado comercial do objeto, o nível de detalhe, as unidades ou os valores válidos. Use descrições e instruções de fontes de dados para fornecer esse contexto.

Limite o esquema selecionado

Selecione apenas as tabelas, colunas, vistas e funções necessárias para as perguntas que o agente de dados deve responder. Objetos irrelevantes aumentam a ambiguidade e dão à ferramenta de geração de consultas mais caminhos possíveis para considerar.

Por exemplo, se os usuários perguntarem sobre pedidos atuais dos clientes, não inclua tabelas de staging arquivadas nem tabelas financeiras não relacionadas. Quando dois objetos selecionados contêm dados semelhantes, explique qual deles é autoritativo e quando usar cada um.

Descrever objetos de esquema (Prévia)

Para esquemas SQL grandes ou ambíguos, use descrições de objetos de esquema para explicar o que tabelas individuais, colunas e outros elementos de esquema representam. Descrições de objetos de esquema estão disponíveis apenas quando o agente de dados usa o tempo de execução prévia.

Descrições são úteis quando:

• Os nomes dos objetos são abreviados, genéricos ou semelhantes entre si.
• O grão ou o propósito comercial de uma mesa não é evidente pelo nome.
• Uma coluna contém códigos, flags, unidades ou valores de categoria que exigem interpretação.
• Uma coluna de data representa um evento comercial específico, como o envio do pedido, e não o cumprimento.
• O esquema é grande demais para explicar claramente cada objeto nas instruções da fonte de dados.

Descreva tanto o significado quanto os valores esperados quando essas informações afetam a geração de consultas. Por exemplo:

Priorize descrições para objetos difíceis de inferir. Evite repetir um nome óbvio sem adicionar contexto de negócios.

Use instruções de fonte de dados para regras entre objetos

Instruções de fonte de dados fornecem orientações de geração de consultas para uma fonte de dados específica. Use-os para contextos que abrangem múltiplos objetos de esquema ou definam como uma consulta deve ser construída, incluindo:

• Tabelas oficiais para um assunto.
• Chaves de junção e caminhos de junção obrigatórios.
• Granularidade da tabela e regras de eliminação de duplicatas.
• Filtros padrão, como usar apenas registros atuais ou ativos.
• Lógica de datas, calendários fiscais e suposições de fusos horários.
• Cálculos ou colunas de saída necessárias.

Escreva instruções diretas que digam o que o agente deve fazer. Por exemplo, use "Faça JOIN de EmployeeStatusFact com EmployeeDim em EmployeeID" em vez de "Evite unir incorretamente tabelas de funcionários."

Mantenha as instruções focadas. Coloque definições específicas de objeto nas descrições dos objetos do esquema em vez de usar espaço limitado de instruções como glossário para cada tabela e coluna.

Defina termos de negócio e valores esperados

Defina terminologia que os usuários possam incluir em suas perguntas, mas que não corresponda diretamente ao esquema. Exemplos incluem siglas como "MAU", significados específicos da organização para "cliente ativo" e distinções como ano fiscal versus ano civil.

Também documente os valores que o agente precisa para construir os filtros corretamente:

• Se uma coluna de status usa "CA" ou "California".
• Se um valor booleano é armazenado como 1 e 0, Y e N, ou texto.
• Se os valores da moeda são armazenados em dólares ou centavos.
• Quais valores de status representam registros concluídos, cancelados ou ativos.
• Se nulo, zero ou uma data sentinela têm significado especial.

Coloque uma definição na descrição do objeto do esquema quando ela se aplica a um objeto. Coloque-o nas instruções da fonte de dados quando se aplica à fonte de dados ou afeta a lógica de consulta multi-objeto.

Explique relações e granulação de tabela

As junções precisas dependem de mais do que apenas nomes de colunas correspondentes. Identifique o grão das tabelas importantes, caminhos de relacionamento válidos e chaves que não são óbvias a partir dos metadados.

Por exemplo, explique se uma tabela de vendas contém uma linha por pedido, item do pedido ou total diário por produto. Se a união de duas tabelas de fatos duplicar linhas, instrua o agente a agregar cada tabela antes da junção ou a usar a tabela de dimensão apropriada.

Inclua orientações sobre relacionamentos, como:

- Join `OrderItems` to `Orders` on `OrderID`.
- Join `Orders` to `Customers` on `CustomerID`.
- Aggregate `OrderItems` to one row per `OrderID` before joining to order-level payment totals.

Use consultas de exemplo para lógica complexa

Use consultas de exemplo ao mostrar que a consulta é mais clara do que descrever a lógica em prosa. Um bom exemplo combina uma pergunta representativa em linguagem natural com uma consulta válida que demonstra o padrão esperado.

Priorize exemplos que demonstrem:

• Junções de múltiplas tabelas ou pré-agregação obrigatória.
• Cálculos específicos do negócio.
• Datas relativas, períodos fiscais ou lógica de snapshots.
• Filtros que mapeiam a terminologia do usuário para valores armazenados.
• Classificação, funções de janela ou outros padrões complexos de consulta.

Mantenha cada exemplo focado em um padrão reutilizável. Evite exemplos sobrepostos ou contraditórios e verifique se todos os exemplos ainda correspondem ao esquema atual.

Teste e refine o contexto

Teste perguntas do representante, inspecione a consulta gerada e identifique qual contexto faltou ou foi mal compreendido. Atualize a configuração mais próxima do problema:

• Remova objetos irrelevantes ou adicione os que faltam na seleção de esquemas.
• Esclareça o significado ou valores esperados de um objeto em sua descrição do esquema.
• Adicione lógica de negócio entre objetos ou de junção às instruções da fonte de dados.
• Adicione uma consulta de exemplo quando o agente precisar aprender um padrão específico de consulta.

Repita esse processo conforme o esquema e as perguntas dos usuários evoluem. Para um fluxo de trabalho estruturado de testes, veja Desenvolver um agente de dados usando um processo iterativo.

Próximas etapas

• Configurações do agente de dados
• Adicionar descrições de objetos de esquema a um agente de dados
• runtime do agente de dados do Fabric
• Consultas de exemplo
• Adicionar e configurar fontes de dados