Adicionar descrições de objetos de esquema a um agente de dados (prévia)

Descrições de objetos de esquema fornecem ao agente de dados contexto de negócio sobre tabelas, colunas e outros elementos em um esquema fonte de dados. Esse contexto ajuda o agente a distinguir entre objetos com nomes semelhantes ou ambíguos, entender o propósito de cada objeto e gerar consultas mais precisas. Descrições são especialmente úteis para esquemas grandes onde nomes de objetos sozinhos não transmitem claramente seu significado.

Há suporte para descrições de objetos do esquema em fontes de dados SQL, incluindo lakehouses, warehouses, bancos de dados SQL do Fabric e bancos de dados espelhados.

Observação

As descrições dos objetos do esquema estão atualmente em pré-visualização pública.

Observação

As descrições dos objetos de esquema estão disponíveis apenas quando seu agente de dados usa o tempo de execução prévia.

Adicione ou edite uma descrição

Por padrão, o agente de dados herda as descrições disponíveis da fonte de dados e as atualiza automaticamente. Quando você edita uma descrição herdada no data agent, a alteração se aplica apenas ao data agent. Ele não sobrescreve a descrição na fonte, e esse objeto não recebe mais atualizações de descrição da fonte.

  1. Abra seu agente de dados e então selecione Configurar.
  2. Na fonte de dados, selecione Descrições de objetos de esquema.
  3. Expanda o esquema para encontrar o objeto que você quer descrever.
  4. Selecione o ícone Editar ao lado do objeto.
  5. Insira uma descrição e então selecione Pronto.

Captura de tela da edição de uma descrição de tabela no painel de descrições de objetos Schema de um agente de dados.

Adicione uma descrição com o SDK Python

Use o Fabric Data Agent Python SDK para gerenciar descrições de objetos de esquema programaticamente. O exemplo a seguir estabelece uma descrição para uma tabela na primeira fonte de dados de um agente de dados existente:

from fabric.dataagent.client import FabricDataAgentManagement

agent = FabricDataAgentManagement("<data-agent-name>")
datasource = agent.get_datasources()[0]

table_path = ("Schemas", "dbo", "Tables", "adoptions")
datasource.update_description({
    table_path: "Contains one row for each pet adoption transaction."
})

A tupla identifica o elemento do esquema pelo seu caminho na fonte de dados. Para descrever uma coluna, adicione seu nome ao caminho da tabela. Por exemplo, use table_path + ("adoption_date",). Os nomes dos caminhos são sensíveis a maiúsculas e minúsculas e devem corresponder à hierarquia mostrada para a fonte de dados.

Escreva descrições efetivas

Use descrições para explicar o significado do negócio que não seja evidente no nome de um objeto. Mantenha cada descrição concisa e específica.

  • Para tabelas, descreva as entidades ou eventos do negócio representados, o nível de detalhe da tabela e seu propósito principal.
  • Para as colunas, defina o significado comercial, o formato, a unidade ou os valores esperados de um valor, caso isso não esteja claro.
  • Para outros elementos do esquema, explique seu papel e quando o agente de dados deve usá-los.
  • Esclareça abreviações, terminologia interna e objetos com nomes semelhantes.
  • Inclua contexto que ajude o agente a selecionar os objetos e relacionamentos corretos ao gerar uma consulta.

Conteúdo relacionado

  • Last updated on