Dépannage de l’intégration Git pour le développement d’entrepôt

S’applique à : ✅ Entrepôt dans Microsoft Fabric

Cet article aborde des sujets de dépannage pour développer et déployer Fabric Data Warehouse avec l'intégration intégrée à Git de Fabric.

Important

Cette fonctionnalité est en version préliminaire.

Références aux objets propres de l’entrepôt en utilisant un nom en trois parties

Un objet peut référencer un autre objet dans le même entrepôt en utilisant un nom en trois parties, [warehouse_name].[schema_name].[object_name].

La dénomination en trois parties est destinée à faire référence à un entrepôt différent . Lorsque la partie base de données nomme l’entrepôt courant, la compilation traite la référence comme externe, et l’objet finit par être défini deux fois dans le modèle.

Supprimez la partie base de données des références aux objets propres à l’entrepôt :

-- 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;

Seules les références aux objets propres à l’entrepôt doivent changer. Les références inter-bases de données authentiques à d’autres entrepôts, telles que [Other_Warehouse].[Sales].[Orders], sont prises en charge et doivent rester as-is.

Important

Utilisez la nomenclature en trois parties (database.schema.object) uniquement pour les références d’analyse cross-warehouse ou cross-SQL, pas pour référencer des objets au sein du même entrepôt. L’auto-référencement des objets dans le même entrepôt en utilisant la nomenclature en trois parties n’est pas une pratique standard de modélisation, et peut créer des références externes involontaires.

Lorsque possible, modéliser les objets en utilisant la dénomination en deux parties (schema.object) au lieu de la dénomination en trois parties, même pour les auto-références au sein du même entrepôt. Cette convention améliore la cohérence entre les outils clients et évite l’ambiguïté introduite par les références en trois parties.

.sqlproj obsolète dans le dépôt Git

Le dépôt Git peut contenir un .sqlproj fichier qui fait référence à une ancienne Microsoft.Build.Sql version du SDK. L'ancien SDK ne reconnaît pas la Fabric Data Warehouse plus récente comme IDENTITY les colonnes et CLUSTER BY.

Ce problème concerne les dépôts dont le contenu a été engagé avant que l’entrepôt ne passe au format de définition actuel. Les situations les plus courantes qui entraînent un fichier .sqlproj obsolète sont :

Connexion d’un nouvel espace de travail à un dépôt existant. L’entrepôt est créé à partir de ce qui y est engagé.
Je me suis lancé dans un nouvel espace de travail.
Restauration d’un entrepôt supprimé depuis Git.
Synchronisation depuis Git immédiatement après que l’entrepôt soit passé au format de définition actuel, avant que toute synchronisation dans l’autre direction ne soit lancée.

Les entrepôts qui ne sont pas déplacés au format de définition actuel ne sont pas affectés, car l’ancien fichier de projet n’est pas utilisé pour la construction.

Comment confirmer la version du SDK .sqlproj

Ouvrez le fichier de .sqlproj l’entrepôt dans le dépôt et vérifiez la version du SDK dans le XML :

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

Une version qui est en retard sur Microsoft actuelle. La version du package Build.SQL indique un fichier de projet obsolète. Par exemple, si votre version commence par 0.1.. Pour plus d’informations, voir Microsoft. Build.SQL et Templates Releases.

Mettre à jour l’option A de la version du SDK .sqlproj : synchroniser d’abord l’entrepôt vers Git

Si l’entrepôt existe déjà dans l’espace de travail et est en bonne santé, commet depuis l’espace de travail vers Git avant de synchroniser dans l’autre sens. Cette action régénère le fichier projet avec la version actuelle du SDK, après quoi la synchronisation depuis Git fonctionne normalement.

Cette option est préférée lorsque disponible, car elle met à jour toute la définition plutôt que seulement l’attribut SDK.

L’entrepôt doit déjà être sous le format de définition actuel pour que cette option fonctionne. Si ce n'est pas le cas, mettez-le à jour d'abord dans le panneau Git de Fabric, puis commencez à faire un commit sur Git. Faire un commit depuis un entrepôt encore sur l’ancien format de définition réécrit l’ancien format dans le dépôt et ne rafraîchit pas la version SDK, donc la synchronisation suivante échoue de la même manière. Si tu ne peux pas upgrader, utilise plutôt l’option de réparation B .

Mettre à jour la version B du SDK .sqlproj : mettre à jour directement le fichier .sqlproj dans Git

Utilisez cette option lorsque l’entrepôt n’existe pas encore dans l’espace de travail cible, par exemple lorsque vous connectez un nouvel espace de travail à un dépôt existant, que vous vous diversifiez ou que vous restaurez un entrepôt supprimé. Dans ces cas, il n’y a pas d’entrepôt à se synchroniser, donc l’option de réparation A n’est pas disponible.

Modifie le .sqlproj fichier dans le dépôt pour utiliser la dernière version de Microsoft. Build.Sql version du package et commit du changement. Par exemple:

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

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

Lancer une exportation ou un diff seul ne met pas à jour le fichier projet. Le fichier n’est réécrit que lorsqu’un commit de l’espace de travail vers Git est terminé, ou lorsque vous l’éditez manuellement.

Colonnes non qualifiées dans des objets qui font référence à deux tables ou plus dans un autre entrepôt

Fournissez toujours et utilisez des alias de table lors du référencement des colonnes dans les requêtes T-SQL.

Lorsqu’une requête T-SQL fait référence à deux tables ou plus dans un autre entrepôt, la compilation ne peut pas valider une colonne écrite sans alias de table vers une table spécifique. Les tables n’ont pas besoin de partager un nom de colonne pour que cette ambiguïté existe. Cette ambiguïté existe dans la version de validation.
Cette ambiguïté affecte les requêtes T-SQL à l’intérieur d’objets qui font référence à deux tables ou plus dans un autre entrepôt au sein du même corps d’énoncé.
Cette ambiguïté n’affecte pas les requêtes T-SQL à l’intérieur d’objets qui ne référencent qu’une seule table dans un autre entrepôt, car avec une seule source, il n’y a rien entre lequel être ambigu.
Cette ambiguïté n’affecte pas les requêtes T-SQL qui restent entièrement dans un seul entrepôt.

Dans l’exemple suivant, n’a fieldinfoque finame , donc le SQL est valide et s’exécute correctement sur l’entrepôt, mais une ambiguïté existe dans la version de validation.

-- 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];

Ajoutez un alias de table à chaque référence de colonne dans l’objet concerné :

-- 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];

Capitalisation incohérente des noms de schéma

Votre entrepôt peut utiliser une collation insensible aux cas, donc sales et Sales sont le même schéma, mais vos scripts peuvent l’épeler des deux façons à différents endroits. Les bases de données insensibles à la casse ont toujours accepté cela, donc l’incohérence est généralement ancienne et inoffensive.

Lorsque vos scripts font référence à deux objets différents ou plus dans le même schéma d’un autre entrepôt, et qu’ils écrivent ce schéma différemment à chaque référence, la compilation génère une CREATE SCHEMA instruction pour chaque orthographe. Ce problème concerne uniquement les entrepôts qui font référence à un autre entrepôt et utilisent une classification insensible aux cas-minuscules.

Par défaut, les entrepôts dans Fabric utilisent Latin1_General_100_BIN2_UTF8une collation sensible aux casse. Les entrepôts sensibles à la casse ne sont pas affectés. Dans ces entrepôts, sales il Sales y a deux schémas différents, que vous le vouliez ou non.
Une base de données insensible à la casse ne peut pas contenir à la fois sales et Sales. Le doublon ne vient que des différentes orthographes dans votre texte SQL.

Vérifiez la classification de l’entrepôt et les spécifications ModelCollation dans le .sqlproj fichier. Cherchez ( CI insensible à la majuscule) ou CS (sensible à la majuscule).

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

Réparer

Pour identifier une capitalisation incohérente des noms de schéma dans les définitions de vos objets d’entrepôt, comparez la capitalisation du schéma nommé dans l’erreur à travers tous vos scripts. Cherchez deux références cross-entrepôt au même schéma qui ne diffèrent que dans le cas vertu.

Utilisez une capitalisation cohérente partout, correspondant au nom réel du schéma dans l’entrepôt référencé. Par exemple, utiliser seulement Sales ou seulement 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];

Vous rencontrez ce problème lorsque vous avez deux objets différents avec deux capitalisations de schéma différentes. Deux références au même objet avec des majuscules différentes sont correctement pliées et ne ratent pas.

Classement des colonnes

Si la clause dCOLLATE'une colonne spécifie explicitement la même collation que la collation par défaut de l'entrepôt, l'extraction de schéma de Fabric (basée sur DacFx) considère la collation explicite comme équivalente à ne pas en spécifier une du tout. Dans ce cas :

La clause explicite COLLATE n’apparaît pas dans la définition de l’élément extraite dans le dépôt Git.
La colonne n’apparaît pas comme une différence dans les modifications Git, les mises à jour ou les comparaisons de pipelines de déploiement, car il n’y a pas de différence effective par rapport à la collation par défaut de l’entrepôt.

Seules les colonnes dont la collation diffère de celle par défaut de l’entrepôt conservent une clause explicite COLLATE dans le contrôle de versions, et seules les modifications apportées à la collation de ces colonnes apparaissent comme différences.

Par exemple, considérons un entrepôt dont la collation est 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’a pas de collation explicite et hérite de la collation par défaut de l’entrepôt.
LastNameBin possède une collation explicite qui diffère de la collation par défaut de l’entrepôt, donc elle est conservée dans la définition extraite et apparaît toujours dans les comparaisons si elle change.
Email possède une collation explicite qui correspond à la collation par défaut de l’entrepôt. Même si la COLLATE clause est présente dans le T-SQL, elle n’apparaît pas dans la définition extraite par Git, ni dans Git ni dans les comparaisons de pipelines de déploiement, car elle est équivalente à la valeur par défaut.

Erreurs de colonne ambiguës avec des objets candidats dupliqués

L’envoi ou la mise à jour depuis Git peut échouer avec une erreur de colonne ambiguë dont la liste candidate contient un :: séparateur, par exemple :

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].

Le :: séparateur distingue cette erreur de l’ambiguïté réelle décrite dans les colonnes non qualifiées dans les objets qui font référence à deux tables ou plus dans un autre entrepôt. Ajouter un alias de table ne résout pas le problème car l’alias apparaît dans la liste des candidats et l’erreur se produit toujours.

Tout d’abord, écartez ces deux causes plus fréquentes :
- Un objet vraiment manquant ou mal nommé. Si le même commit ou mise à jour rapporte également une référence non résolue à un objet manquant spécifique, comme SQL71501: View: [dbo].[v_report] has an unresolved reference to object [dbo].[MissingTable], corrigez cette référence en premier. Les :: candidats passent généralement avec elle.
- Une chronique véritablement ambiguë. Si une colonne non qualifiée est sélectionnée sur une jonction de deux sources qui exposent toutes deux une colonne du même nom, qualifiez la colonne avec son alias de table, par a.[NCESID]exemple . SQL Server rejetterait aussi cette requête, donc elle n'est pas spécifique à l'intégration Git.
Si chaque objet référencé existe et qu’aucune colonne n’est réellement ambiguë, les :: candidats sont un problème connu dans la validation qui s’exécute lors des commits et mises à jour depuis Git, suivie par l’équipe produit. Essayez ces solutions de contournement, dans l’ordre :
1. Remplacez SELECT * les CTE à l’intérieur et les tables dérivées par une liste de colonnes explicite.
2. Divisez la vue de façon à ce que chaque source ambiguë soit définie dans sa propre vue, et référencez cette vue au lieu de répéter la requête sous-jacente.
3. Évitez de rejoindre OPENROWSET(BULK ...) une autre source dynamique dans la même déclaration.

Si aucune de ces solutions ne résout l’erreur, collectez la définition de l’objet nommé dans l’erreur et ouvrez une requête de support. Pour les limitations spécifiques aux pipelines de déploiement, voir Limitations.

Commentaires

Est-ce que cette page vous a été utile?

Last updated on 2026-07-31