Resolução de problemas da integração Git para desenvolvimento de armazém

Aplica-se a: ✅ Armazém no Microsoft Fabric

Este artigo inclui tópicos de resolução de problemas para desenvolver e implementar Fabric Data Warehouse com a integração Git integrada da Fabric.

Importante

Este recurso está em pré-visualização.

Referências aos próprios objetos do armazém usando um nome em três partes

Um objeto pode referenciar outro objeto no mesmo armazém usando um nome em três partes, [warehouse_name].[schema_name].[object_name].

A nomenclatura em três partes destina-se a referir-se a um armazém diferente . Quando a parte da base de dados nomeia o armazém atual, a build trata a referência como externa, e o objeto acaba por ser definido duas vezes no modelo.

Remover a parte da base de dados das referências aos próprios objetos do armazém:

-- Fails: the warehouse is named MyWarehouse and references itself by name
CREATE VIEW [Sales].[CustomerSummary] AS
SELECT c.[CustomerId], c.[OrderDate]
FROM [MyWarehouse].[Sales].[Customers] AS c;

-- Works
CREATE VIEW [Sales].[CustomerSummary] AS
SELECT c.[CustomerId], c.[OrderDate]
FROM [Sales].[Customers] AS c;

Apenas as referências aos próprios objetos do armazém precisam de mudar. Referências genuínas entre bases de dados a outros armazéns, como [Other_Warehouse].[Sales].[Orders], são suportadas e devem permanecer as-is.

Importante

Use a nomenclatura em três partes (database.schema.object) apenas para referências de endpoints de análise cross-warehouse ou cross-SQL, não para referenciar objetos dentro do mesmo warehouse. Auto-referenciar objetos no mesmo armazém usando nomes em três partes não é uma prática padrão de modelação e pode criar referências externas inadvertidas.

Sempre que possível, modele os objetos usando a nomenclatura em duas partes (schema.object) em vez da nomeação em três partes, mesmo para autorreferências dentro do mesmo armazém. Esta convenção melhora a consistência entre as ferramentas do cliente e evita a ambiguidade introduzida pelas referências em três partes.

.sqlproj desatualizado no repositório Git

O repositório Git pode conter um .sqlproj ficheiro que faz referência a uma versão mais antiga Microsoft.Build.Sql do SDK. O SDK mais antigo não reconhece sintaxe Fabric Data Warehouse mais recente, como IDENTITY colunas e CLUSTER BY.

Este problema afeta repositórios cujos conteúdos foram comprometidos antes do armazém passar para o formato de definição atual. As situações mais comuns que resultam num ficheiro .sqlproj desatualizado são:

• Ligar um novo espaço de trabalho a um repositório existente. O armazém é criado a partir do que lá é feito.
• A expandir-me para um novo espaço de trabalho.
• Restaurar um armazém apagado do Git.
• Sincronização a partir do Git imediatamente após o warehouse passar para o formato de definição atual, antes de qualquer sincronização na outra direção ter sido executada.

Os armazéns que não são movidos para o formato de definição atual não são afetados, porque o ficheiro de projeto mais antigo não é usado para construir.

Como confirmar a versão do SDK .sqlproj

Abre o ficheiro do .sqlproj armazém no repositório e verifica a versão do SDK no XML:

<Sdk Name="Microsoft.Build.Sql" Version="2.2.0" />

Uma versão que está atrás da atual Microsoft. A versão do pacote Build.SQL indica um ficheiro de projeto desatualizado. Por exemplo, se a sua versão começar com 0.1.. Para mais informações, consulte Microsoft. Build.SQL e Templates Releases.

Atualizar a opção A da versão do SDK .sqlproj: sincronizar o armazém para o Git primeiro

Se o warehouse já existir no workspace e estiver saudável, commit do workspace para o Git antes de sincronizar na direção oposta. Esta ação regenera o ficheiro do projeto com a versão atual do SDK, após o que a sincronização a partir do Git funciona normalmente.

Esta opção é preferida quando disponível, porque atualiza toda a definição em vez de apenas o atributo SDK.

O armazém deve já estar no formato de definição atual para que esta opção funcione. Se não estiver, atualiza-o primeiro no painel Git do Fabric e depois compromete-se com o Git. Fazer commit a partir de um armazém que ainda está no formato de definição antiga escreve o formato antigo de volta no repositório e não atualiza a versão do SDK, por isso a próxima sincronização falha da mesma forma. Se não conseguires melhorar, usa a opção de reparação B em vez disso.

Atualizar a versão do SDK .sqlproj opção B: atualizar diretamente o ficheiro .sqlproj no Git

Use esta opção quando o armazém ainda não existe no espaço de trabalho alvo, como quando está a ligar um novo espaço de trabalho a um repositório existente, a expandir ramificações ou a restaurar um armazém eliminado. Nesses casos, não há armazém para sincronizar, por isso a opção de correção A não está disponível.

Edita o .sqlproj ficheiro no repositório para usar a versão mais recente da Microsoft. Compila a versão do pacote Build.SQL e compromete a alteração. Por exemplo:

<!-- Before -->
<Sdk Name="Microsoft.Build.Sql" Version="0.1.19-preview" />

<!-- After -->
<Sdk Name="Microsoft.Build.Sql" Version="2.2.0" />

Executar uma exportação ou um diferencial sozinho não atualiza o ficheiro do projeto. O ficheiro só é reescrito quando um commit do workspace para o Git é concluído, ou quando o edita manualmente.

Colunas não qualificadas em objetos que fazem referência a duas ou mais tabelas noutro armazém

Fornece e usa sempre pseudónimos de tabela ao referenciar colunas em consultas T-SQL.

• Quando uma consulta T-SQL faz referência a duas ou mais tabelas noutro warehouse, a build não pode validar uma coluna escrita sem um alias de tabela para uma tabela específica. As tabelas não precisam de partilhar um nome de coluna para que esta ambiguidade exista. Esta ambiguidade existe na versão de validação.
• Esta ambiguidade afeta consultas T-SQL dentro de objetos que referenciam duas ou mais tabelas noutro armazém dentro do mesmo corpo de instrução.
• Esta ambiguidade não afeta as consultas T-SQL dentro de objetos que referenciam apenas uma tabela noutro armazém, porque com uma única fonte não há nada entre que seja ambíguo.
• Esta ambiguidade não afeta as consultas T-SQL que permanecem inteiramente dentro de um único armazém.

No exemplo seguinte, só fieldinfo tem finame, pelo que o SQL é válido e corre corretamente contra o warehouse, mas existe ambiguidade na compilação de validação.

-- Fails: two tables from another warehouse, and 'finame' isn't alias-qualified
CREATE PROCEDURE [dbo].[LoadFieldInfo] AS
SELECT finame
FROM   [OtherWarehouse].[halo].[fieldinfo] AS f
INNER JOIN   [OtherWarehouse].[halo].[lookup]    AS l ON f.[id] = l.[id];

Adicione um alias de tabela a cada referência de coluna no objeto afetado:

-- Works: every column carries its table alias
CREATE PROCEDURE [dbo].[LoadFieldInfo] AS
SELECT f.[finame]
FROM   [OtherWarehouse].[halo].[fieldinfo] AS f
INNER JOIN   [OtherWarehouse].[halo].[lookup]    AS l ON f.[id] = l.[id];

Capitalização inconsistente dos nomes de esquemas

O seu armazém pode usar uma colação insensível a maiúsculas e minúsculas, ou seja sales , e Sales são o mesmo esquema, mas os seus scripts podem escrever de ambas as formas em locais diferentes. Bases de dados insensíveis a maiúsculas e minúsculas sempre aceitaram isso, por isso a inconsistência é geralmente antiga e inofensiva.

Quando os teus scripts referenciam dois ou mais objetos diferentes no mesmo esquema de outro armazém, e escrevem esse esquema de forma diferente em cada referência, a build gera uma CREATE SCHEMA instrução para cada grafia. Este problema afeta apenas armazéns que fazem referência a outro armazém e utilizam uma colação insensível a maiúsculos e minúsculos.

• Por defeito, os armazéns no Fabric usam Latin1_General_100_BIN2_UTF8, uma colação com sensibilidade a maiúsculas minúsculas. Os armazéns com sensíveis a maiúsculas minúsculas não são afetados. Nesses armazéns, sales e Sales existem dois esquemas diferentes, quer queiras isso ou não.
• Uma base de dados insensível a maiúsculas minúsculas e minúsculas não pode conter tanto sales como Sales. A duplicação vem apenas das diferentes grafias no teu texto SQL.

Verifique a organização do armazém e o ModelCollation especificado no .sqlproj ficheiro. Procure por CI (indistinto a maiúsculas) ou CS (sensível a maiúsculas).

<ModelCollation>1033, CI</ModelCollation>   <!-- case-insensitive: affected -->
<ModelCollation>1033, CS</ModelCollation>   <!-- case-sensitive: not affected -->

Corrigir

Para identificar capitalizações inconsistentes dos nomes de esquemas nas definições dos teus objetos de armazém, compara a capitalização do esquema nomeado no erro em todos os teus scripts. Procure duas referências cross-warehouse ao mesmo esquema que só diferem em caso de situação.

Use uma capitalização consistente em todo o lado, correspondendo ao nome real do esquema no armazém referenciado. Por exemplo, use apenas Sales ou apenas sales.

-- Fails: two objects in the same schema, referenced with different capitalization
CREATE VIEW [dbo].[v_one] AS SELECT * FROM [OtherWarehouse].[sales].[Orders];
GO
CREATE VIEW [dbo].[v_two] AS SELECT * FROM [OtherWarehouse].[Sales].[Customers];

-- Works: same capitalization in both references
CREATE VIEW [dbo].[v_one] AS SELECT * FROM [OtherWarehouse].[Sales].[Orders];
GO
CREATE VIEW [dbo].[v_two] AS SELECT * FROM [OtherWarehouse].[Sales].[Customers];

Encontra-se este problema quando tem dois objetos diferentes com duas capitalizações de esquemas distintas. Duas referências ao mesmo objeto com maiúsculas diferentes são dobradas corretamente e não falham.

Colação de colunas

Se a cláusula de COLLATE uma coluna especificar explicitamente a mesma colação que a colação padrão do armazém, a extração de esquema do Fabric (baseada em DacFx) trata a colação explícita como equivalente a não especificar nenhuma. Neste caso:

• A cláusula explícita COLLATE não aparece na definição de item extraída para o repositório Git.
• A coluna não aparece como diferença nas Alterações Git, Atualizações ou comparações de pipelines de implementação, porque não há diferença efetiva em relação à colação padrão do armazém.

Apenas as colunas cuja colação difere da colação padrão do armazém mantêm uma cláusula explícita COLLATE no controlo de versão, e apenas alterações à colação dessas colunas aparecem como diferenças.

Por exemplo, considere um armazém cuja colação é Latin1_General_100_CI_AS_KS_WS_SC_UTF8:

CREATE TABLE dbo.MixedCollationExample
(
    CustomerId      INT             NOT NULL,
    FirstName       VARCHAR(100)    NOT NULL,                                               -- inherits warehouse collation
    LastNameBin     VARCHAR(100)    COLLATE Latin1_General_100_BIN2_UTF8 NOT NULL,          -- column override, differs from warehouse collation
    Email           VARCHAR(256)    COLLATE Latin1_General_100_CI_AS_KS_WS_SC_UTF8 NULL     -- explicit collation, matches warehouse collation
);

• FirstName não tem colação explícita e herda a colação padrão do armazém.
• LastNameBin tem uma colação explícita que difere da colação padrão do armazém, por isso é preservada na definição extraída e aparece sempre nas comparações se mudar.
• Email tem uma colação explícita que corresponde à colação padrão do armazém. Embora a COLLATE cláusula esteja presente no T-SQL, não aparece na definição extraída pelo Git, nem nas comparações do Git ou do pipeline de deployment, porque é equivalente ao padrão.

Erros ambíguos de coluna com objetos candidatos duplicados

A confirmação ou atualização a partir do Git pode falhar com um erro ambíguo de coluna cuja lista de candidatos contém um :: separador, por exemplo:

SQL71501: View: [dbo].[SchoolSummary] contains an unresolved reference to an object.
Either the object does not exist or the reference is ambiguous because it could refer
to any of the following objects: [dbo].[SchoolSummary].[NCESID] or
[dbo].[SchoolSummary].[ss]::[NCESID].

O :: separador distingue este erro da ambiguidade genuína descrita em colunas Não qualificadas em objetos que referenciam duas ou mais tabelas noutro armazém. Adicionar um alias de tabela não resolve o problema, pois o alias aparece na lista de candidatos e o erro continua a ocorrer.

1. Primeiro, exclua estas duas causas mais comuns:

   • Um objeto genuinamente em falta ou com um nome errado. Se o mesmo commit ou atualização também reportar uma referência não resolvida a um objeto específico em falta, como SQL71501: View: [dbo].[v_report] has an unresolved reference to object [dbo].[MissingTable], corrige essa referência primeiro. Os :: candidatos normalmente passam juntamente com ela.
   • Uma coluna genuinamente ambígua. Se uma coluna não qualificada for selecionada sobre uma junção de duas fontes que ambas expõem uma coluna com esse nome, qualifica a coluna com o seu alias de tabela, por exemplo a.[NCESID]. O SQL Server também rejeitaria esta consulta, por isso não é específica da integração com o Git.

2. Se todos os objetos referenciados existirem e nenhuma coluna for genuinamente ambígua, os :: candidatos são um problema conhecido na validação que é executada durante commits e atualizações do Git, acompanhada pela equipa de produto. Experimente estas soluções alternativas, por ordem:

   1. Substitua SELECT * CTEs internos e tabelas derivadas por uma lista explícita de colunas.
   2. Divida a vista para que cada fonte ambígua esteja definida na sua própria visão, e faça referência a essa vista em vez de repetir a consulta subjacente.
   3. Evite juntar-se OPENROWSET(BULK ...) a outra fonte com forma dinâmica na mesma afirmação.

Se nenhum destes resolver o erro, recolha a definição do objeto nomeado no erro e abra um pedido de suporte. Para limitações específicas dos pipelines de implementação, consulte Limitações.

Conteúdo relacionado

• Inicie com a integração do Git
• Use a Integração Git para desenvolvimento e implementação de armazém