Marcas de linhagem para modelos semânticos do Power BI

Artigo
01/06/2025

Você pode usar marcas de linhagem em objetos de modelo semântico para habilitar a identificação estável desses objetos em diferentes modelos semânticos. O uso de marcas de linhagem permite que recursos do Power BI, como modelos compostos manter sua associação a tabelas ou colunas referenciadas (usando SourceLineageTag), mesmo que o objeto de modelo semântico de origem seja renomeado.

As marcas de linhagem devem ser exclusivas dentro do escopo; por exemplo, duas tabelas no mesmo modelo semântico não podem ter a mesma marca de linhagem. O Power BI Desktop normalmente atribui um GUID para cada objeto de modelo semântico que exige linhagem, mas essa atribuição não é obrigatória e as marcas de linhagem podem ser alteradas para qualquer outro formato de cadeia de caracteres.

Importante

Se os objetos de modelo semântico não tiverem uma marca de linhagem, o Power BI usará o nome do objeto, o que poderá levar à perda de personalizações se o objeto for renomeado.

Acompanhamento de personalizações de usuário para modelos semânticos

Modelos semânticos podem incluir objetos e propriedades derivados de outros modelos ou fontes de dados. Por exemplo, ao criar um modelo composto em modelos semânticos do Power BI, os nomes de tabela e coluna, tipos de dados, cadeias de caracteres de formato e outras propriedades se originam do modelo de origem.

Ao personalizar propriedades ou remover objetos no modelo que foram sincronizados da fonte de dados, o Power BI espera que a propriedade changedProperties e PBI_RemovedChildren anotação sejam definidas para indicar uma personalização do usuário para que as personalizações sejam mantidas durante a próxima sincronização de esquema com a fonte de dados.

Os seguintes objetos/propriedades são sincronizados com a fonte de dados e exigem que você declare as propriedades modificadas e as remoções de objeto:

Cenário	Objetos	Personalização de propriedade	Personalização de remoção
Importação/DirectQuery	Tabelas, colunas, relações	Nome, DataType	Relações ¹
Composto	Tabelas, colunas, relações, medidas, hierarquias, níveis	Name, DataType, IsHidden, FormatString, Description, SummarizeBy, DataCategory, SortByColumn, GroupByColumns, DisplayFolder, IsNullable	Todas as tabelas no modelo remoto não incluídas no modelo local
DirectLake	Tabelas, Colunas	Nome, DataType	Todas as tabelas no Lakehouse não incluídas no modelo

[1] o Power BI cria automaticamente relações com base em informações de chave primária e estrangeira da fonte de dados. Se os usuários removerem essas relações, o Power BI manterá o controle das alterações para impedir a adição durante a sincronização futura do esquema.

A coleção ChangedProperties

A coleção ChangedProperties permite especificar quais valores de propriedade de objeto foram modificados, indicando que esses valores podem não ser mais sincronizados com a origem.

Por exemplo, ao criar um modelo composto em modelos semânticos do Power BI, os nomes de coluna são originários do modelo de origem. Se você renomear uma coluna em seu modelo local, precisará especificar a propriedade Name como uma propriedade alterada.

No exemplo a seguir, a coluna ProductID do modelo de origem foi renomeada para ProductKey:

table Products 

    column ProductKey 
        dataType: int64          
        lineageTag: 9636345e-0328-43fb-acd3-e7894734d08a 
        sourceLineageTag: 6890686b-4899-4916-9ec2-2e8ff5a05eb7               
        sourceColumn: ProductID 

        changedProperty = Name

A anotação PBI_RemovedChildren

A anotação PBI_RemovedChildren é uma anotação de modelo declarada no objeto pai do item removido que declara a intenção do usuário de excluir um objeto do objeto local. Por exemplo, ao construir um modelo composto, você pode escolher quais tabelas carregare todas as tabelas não selecionadas são incluídas na anotação PBI_RemovedChildren armazenada no namedExpression da fonte de dados. Nos modelos Import e DirectQuery, a anotação é armazenada dentro do modelo para acompanhar as remoções de relação.

Não declarar essa anotação faz com que objetos de modelo semântico sejam recuperados durante a sincronização de esquema com a origem.

No exemplo a seguir, uma tabela é removida do modelo composto. A marca de linhagem da tabela de modelo de origem é usada em vez de seu nome para garantir uma identificação estável:

expression 'DirectQuery to AS - AdventureWorks' = 
        let 
            Source = AnalysisServices.Database("[XMLA Endpoint]"), 
            Cubes = Table.Combine(Source[Data]), 
            Cube = Cubes{[Id="Model", Kind="Cube"]}[Data] 
        in 
            Cube 

    annotation PBI_RemovedChildren = [{"remoteItemId":{"analysisServicesObject":{"sourceName":null,"sourceLineageTag":"8e47b52e-1c1a-4029-b6cc-25200d213fcf"}},"objectType":"Table"}]

Considerações e limitações

Para modelos Import/DirectQuery, o changedProperty é necessário somente quando a alteração não pode ser dobrada na consulta M da tabela, como em tabelas DirectQuery utilizando uma consulta nativa.
Para modelos DirectLake, o sourceLineageTag deve ser o nome da tabela/coluna no Lakehouse/data warehouse.

Próxima etapa

Os seguintes artigos contêm informações adicionais úteis:

suporte de gravação do modelo com o ponto de extremidade XMLA
modificações XMLA e modelos compostos

Compartilhar via