Solução de problemas com integração Git para desenvolvimento de armazém

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

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

Referências aos próprios objetos do depósito usando um nome dividido em três partes

Um objeto pode referenciar outro objeto no mesmo depósito usando um nome em três partes, [warehouse_name].[schema_name].[object_name].

A nomenclatura em três partes é destinada a referenciar um armazém diferente . Quando a parte do banco de dados nomeia o depósito atual, a build trata a referência como externa, e o objeto acaba sendo definido duas vezes no modelo.

Remova a parte do banco de dados das referências aos próprios objetos do depósito:

-- 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 mudar. Referências genuínas entre bancos de dados a outros depósitos, como [Other_Warehouse].[Sales].[Orders], são suportadas e devem permanecer as-is.

.sqlproj desatualizado no repositório Git

O repositório Git pode conter um .sqlproj arquivo que faz referência a uma versão 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.

Esse problema afeta repositórios cujos conteúdos foram comprometidos antes do depósito migrar para o formato de definição atual. As situações mais comuns que resultam em um arquivo .sqlproj desatualizado são:

• Conectando um novo espaço de trabalho a um repositório existente. O depósito é criado a partir do que for feito ali.
• Expandindo para um novo espaço de trabalho.
• Restaurando um depósito excluído do Git.
• Sincronização do Git imediatamente após o depósito passar para o formato de definição atual, antes que qualquer sincronização na outra direção tenha sido executada.

Warehouses que não são movidos para o formato de definição atual não são afetados, porque o arquivo de projeto antigo não é usado para construir.

Como confirmar a versão do SDK .sqlproj

Abra o arquivo do .sqlproj depósito no repositório e verifique a versão do SDK no XML:

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

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

Atualizar a opção A da versão do SDK .sqlproj: sincronizar o warehouse com o Git primeiro

Se o warehouse já existir no workspace e estiver saudável, faça commit do workspace para o Git antes de sincronizar na outra direção. Essa ação regenera o arquivo do projeto com a versão atual do SDK, após o qual a sincronização do Git funciona normalmente.

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

O depósito já deve estar no formato de definição atual para que essa opção funcione. Se não estiver, atualize primeiro no painel Git do Fabric e depois commit no Git. Fazer commit a partir de um warehouse que ainda está no formato de definição mais antiga grava o formato antigo de volta no repositório e não atualiza a versão do SDK, então a próxima sincronização falha da mesma forma. Se não puder fazer upgrade, use a opção de reparo B .

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

Use essa opção quando o depósito ainda não existir no workspace de destino, como quando você estiver conectando um novo workspace a um repositório existente, expandindo ou restaurando um warehouse deletado. Nesses casos, não há um depósito para sincronizar, então a opção A de conserto não está disponível.

Edite o .sqlproj arquivo no repositório para usar a versão mais recente da Microsoft. Build.SQL e faça commit da 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" />

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

Colunas não qualificadas em objetos que referenciam duas ou mais tabelas em outro depósito

Sempre forneça e use aliases de tabela ao referenciar colunas em consultas T-SQL.

• Quando uma consulta T-SQL faz referência a duas ou mais tabelas em outro 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 compartilhar o nome de uma coluna para que essa ambiguidade exista. Essa ambiguidade existe na versão de validação.
• Essa ambiguidade afeta consultas T-SQL dentro de objetos que referenciam duas ou mais tabelas em outro warehouse dentro do mesmo corpo de instrução.
• Essa ambiguidade não afeta consultas T-SQL dentro de objetos que referenciam apenas uma tabela em outro warehouse, porque com uma única fonte não há nada entre os quais ser ambíguo.
• Essa ambiguidade não afeta consultas T-SQL que ficam inteiramente dentro de um único depósito.

No exemplo a seguir, tem fieldinfoapenas finame , então o SQL é válido e roda corretamente contra o warehouse, mas existe ambiguidade na build 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

Seu warehouse pode usar uma colação insensível a maiúsculas minúsculas, então sales e Sales são o mesmo esquema, mas seus scripts podem soletrar os dois lados em lugares diferentes. Bancos de dados insensíveis a maiúsculas e minúsculas sempre aceitaram isso, então a inconsistência geralmente é antiga e inofensiva.

Quando seus scripts referenciam dois ou mais objetos diferentes no mesmo esquema de outro warehouse, e escrevem esse esquema de forma diferente em cada referência, a build gera uma CREATE SCHEMA instrução para cada ortografia. Esse problema afeta apenas armazéns que fazem referência a outro armazém e usam uma classificação insensível a maiúsculas minúsculas.

• Por padrão, os depósitos no Fabric usam Latin1_General_100_BIN2_UTF8, uma colação sensível a maiúsculas e minúsculas. Depósitos com sensíveis de maiúsculas minúsculas não são afetados. Nesses depósitos, sales e Sales existem dois esquemas diferentes, quer você queira isso ou não.
• Um banco de dados insensível a maiúsculas minúsculas não pode conter tanto sales quanto Sales. A duplicação vem apenas das diferentes grafias no seu texto SQL.

Verifique a coleta do depósito e o ModelCollation especificado no .sqlproj arquivo. Procure por CI (indistinto a maiúsculas minúsculas) ou CS (distinto a maiúsculas).

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

Corrigir

Para identificar capitalizações inconsistentes de nomes de esquemas nas definições dos seus objetos de warehouse, compare a capitalização do esquema nomeado no erro entre todos os seus scripts. Procure por duas referências cross-warehouse ao mesmo esquema que diferem apenas em casos de casos.

Use uma capitalização consistente em todos os lugares, correspondendo ao nome real do esquema no warehouse 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];

Você encontra esse 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.

Ordenação de coluna

Se a cláusula de COLLATE uma coluna especificar explicitamente a mesma colação que a colação padrão do warehouse, a extração de esquema do Fabric (baseada em DacFx) trata a colação explícita como equivalente a não especificar nenhuma dela. 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 do Git, Atualizações ou comparações de pipeline de implantação, porque não há diferença efetiva em relação à colação padrão do warehouse.

Apenas colunas cuja colação difere da colação padrão do warehouse mantêm uma cláusula explícita COLLATE no controle de versão, e apenas alterações na 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 possui colação explícita e herda a colação padrão do depósito.
• LastNameBin tem uma colação explícita que difere da colação padrão do depósito, então ela é preservada na definição extraída e sempre aparece nas comparações caso mude.
• Email possui uma colação explícita que corresponde à colação padrão do depósito. Mesmo que a COLLATE cláusula esteja presente no T-SQL, ela não aparece na definição extraída pelo Git, nem nas comparações do Git ou do pipeline de implantação, porque é equivalente ao padrão.

Erros ambíguos de coluna com objetos candidatos duplicados

Confirmar ou atualizar 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 esse erro da ambiguidade genuína descrita nas colunas Não Qualificadas em objetos que referenciam duas ou mais tabelas em outro depósito. Adicionar um alias de tabela não resolve o problema, pois o alias aparece na lista de candidatos e o erro ainda ocorre.

1. Primeiro, descarte essas duas causas mais comuns:

   • Um objeto realmente ausente ou com nome errado. Se o mesmo commit ou atualização também reporta uma referência não resolvida a um objeto específico ausente, como SQL71501: View: [dbo].[v_report] has an unresolved reference to object [dbo].[MissingTable], corriga essa referência primeiro. Os :: candidatos geralmente passam junto com ele.
   • 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, qualifique a coluna com seu alias de tabela, por exemplo a.[NCESID]. O SQL Server também rejeitaria essa consulta, então não é específica para integração com Git.

2. Se todos os objetos referenciados existem e nenhuma coluna for genuinamente ambígua, os :: candidatos são um problema conhecido na validação que roda durante commits e atualizações do Git, acompanhada pela equipe de produto. Tente estas soluções, em ordem:

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

Se nenhum desses resolver o erro, colete a definição do objeto nomeado no erro e abra uma solicitação de suporte. Para limitações específicas dos pipelines de implantação, veja Limitações.

Conteúdo relacionado

• Comece com a integração com o Git
• Use a integração do Git para desenvolvimento e implantação de armazéns