Fabric倉庫開発のためのGit統合のトラブルシューティング

適用対象: Microsoft Fabric のウェアハウス✅

この記事では、Fabricの組み込みGit統合を使ったFabric Data Warehouseの開発とデプロイに関するトラブルシューティングトピックを含みます。

Important

倉庫自身のオブジェクトへの三部構成名による言及

オブジェクトは、3 つの部分からなる名前 [warehouse_name].[schema_name].[object_name]を用いて同じウェアハウス内の別のオブジェクトを参照することができます。

三部構成の命名は 、異なる 倉庫を参照するためのものです。データベース部分が現在のウェアハウスに名前を付けると、ビルドはその参照を外部として扱い、そのオブジェクトはモデル内で2回定義されます。

倉庫自身のオブジェクトへの参照からデータベース部分を削除する:

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

ウェアハウス自身のオブジェクトへの参照だけを変更する必要があります。 [Other_Warehouse].[Sales].[Orders]など他のウェアハウスへの本物のデータベース間参照はサポートされており、as-isに留めておくべきです。

Important

3部指定(database.schema.object)は、クロスウェアハウスやクロスSQLの分析エンドポイント参照にのみ使用し、同じウェアハウス内のオブジェクトを参照には使いません。同じウェアハウス内のオブジェクトを三部指定で自己参照するのは標準的なモデリング手法ではなく、意図しない外部参照を生み出すことがあります。

可能な限り、同じ倉庫内の自己参照であっても、3部名ではなく二部構成(schema.object)でオブジェクトをモデル化します。この慣習によりクライアントツール間の一貫性が向上し、三部構成参照による曖昧さを回避できます。

Gitリポジトリ内の.sqlprojの最新情報

Gitリポジトリには、古いMicrosoft.Build.SqlSDKバージョンを参照する.sqlprojファイルを含めることができます。古いSDKは、IDENTITY列やCLUSTER BYなどの新しいFabric Data Warehouse構文を認識していません。

この問題は、ウェアハウスが現在の定義形式に移行する前に内容がコミットされたリポジトリに影響します。 .sqlprojファイルが古くなる最も一般的な状況は以下の通りです:

新しいワークスペースを既存のリポジトリに接続すること。 倉庫はそこにコミットされたものから作られます。
新しい職場に挑戦すること。
Gitから削除された倉庫を復元する。
ウェアハウスが現在の定義フォーマットに移行した直後にGitから同期が行われ、逆方向の同期が行われる前に行われました。

現在の定義フォーマットに移行されていない倉庫は影響を受けません。なぜなら、古いプロジェクトファイルはビルドに使われていないからです。

.sqlproj SDK バージョンの確認方法

リポジトリ内の倉庫の .sqlproj ファイルを開き、XMLのSDKバージョンを確認してください:

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

現在のMicrosoftよりも遅れているバージョンです。Build.SQLパッケージのバージョンは、古いプロジェクトファイルを示します。例えば、あなたのバージョンが 0.1.で始まる場合。詳細はMicrosoftをご覧ください。Build.SQLとテンプレートのリリース。

Update .sqlproj SDK バージョンオプションA:まずWarehouseをGitに同期してください

ウェアハウスがすでにワークスペースに存在していて健全であれば、同期する前にワークスペースからGitにコミットしてください。この操作でプロジェクトファイルは現在のSDKバージョンで再生成され、その後Gitとの同期は通常通り動作します。

このオプションは、SDK属性だけでなく定義全体を最新の状態にするため、利用可能な場合に好まれます。

このオプションを有効にするには、倉庫がすでに現在の定義フォーマットである必要があります。もし対応していなければ、まずFabric Gitパネルでアップグレードし、その後Gitにコミットしてください。古い定義フォーマットのウェアハウスからコミットすると、古いフォーマットがリポジトリに書き戻され、SDKバージョンは更新されないため、次の同期も同じように失敗します。アップグレードできない場合は、修正オプションB を使いましょう。

.sqlproj SDKのバージョンを更新するオプションB:Gitの.sqlprojファイルを直接更新してください

このオプションは、新しいワークスペースを既存のリポジトリに接続する際、分岐する、削除した倉庫を復元するなど、ターゲットワークスペースにまだ存在しない場合に使います。その場合、同期できる倉庫がないため、修正オプションAは利用できません。

リポジトリ内の.sqlprojファイルを編集して最新のMicrosoftを使います。Build.SQLパッケージのバージョンを表示し、変更をコミットします。例えば次が挙げられます。

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

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

エクスポートやdiffを単独で実行してもプロジェクトファイルは更新されません。ワークスペースからGitへのコミットが完了するか、手動で編集した場合にのみファイルが書き換えられます。

別のウェアハウスの2つ以上のテーブルを参照するオブジェクト内の無条件列

T-SQLクエリで列を参照する際は、必ずテーブルエイリアスを提供し、使用してください。

T-SQLクエリが別のウェアハウス内の2つ以上のテーブルを参照する場合、ビルドは特定のテーブルにテーブルエイリアスなしで書かれた列を検証できません。この曖昧さが存在するために、テーブル同士が同じ列名を共有している必要はありません。この曖昧さは検証ビルドにも存在します。
この曖昧さは、同じ文体内の別の倉庫内の2つ以上のテーブルを参照するオブジェクト内のT-SQLクエリに影響を与えます。
この曖昧さは、別のウェアハウスのテーブルを1つだけ参照するオブジェクト内のT-SQLクエリには影響しません。なぜなら、単一のソースであれば曖昧さが何もないからです。
この曖昧さは、完全に一つの倉庫内にとどまるT-SQLクエリには影響しません。

以下の例では、finameを持つのはfieldinfoだけなので、SQLは有効でウェアハウスに対して正しく動作しますが、検証ビルドには曖昧さが存在します。

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

影響を受けるオブジェクト内のすべての列参照にテーブルエイリアスを追加します:

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

スキーマ名の不一致な大文字表記

倉庫では大文字に区別されない照合が使えるので、 sales と Sales は同じスキーマですが、スクリプトが異なる場所で両方の意味で綴っていることがあります。大文字に区別されないデータベースは常にそれを受け入れてきたため、この不整合は通常長く続いていて無害です。

スクリプトが別のウェアハウスの同じスキーマ内の2つ以上の異なるオブジェクトを参照し、そのスキーマのスペルがそれぞれ異なる場合、ビルドはそれぞれのスペルに対して CREATE SCHEMA 文を生成します。この問題は、他の倉庫を参照し、大文字に区別されない照合を使用している倉庫にのみ影響します。

デフォルトでは、Fabricの倉庫は大文字Latin1_General_100_BIN2_UTF8を区別するコレーションを使用します。ケースに配慮された倉庫は影響を受けません。そうした倉庫では、 sales と Sales は意図的かどうかに関わらず、異なるスキーマです。
大文字に区別されないデータベースは、 sales と Salesの両方を含むことはできません。重複はSQLテキストの綴りの違いから生じます。

倉庫の照合と.sqlprojファイルに指定されたModelCollationを確認してください。 CI(大文字区別なし)かCS(大文字区別)を探してください。

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

修正

ウェアハウスオブジェクトの定義におけるスキーマ名の大文字の不一致を特定するには、エラーに記載されたスキーマの大文字をすべてのスクリプトで比較してください。同じスキーマに対するクロスウェアハウスの参照が2つあれば、異なる場合は探してください。

参照されたウェアハウスの実際のスキーマ名と一致する、すべての場所で一貫した大文字を使いましょう。例えば、単 Sales または 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];

この問題は、異なる2つの異なるスキーマ大文字を持つ2つのオブジェクトがある場合に発生します。同じオブジェクトの大文字が異なる2つの参照は正しく折りたたまれ、失敗しません。

列の照合順序

もしある列のCOLLATE節がウェアハウスのデフォルトの結合と明示的に同じ照合を指定している場合、Fabricのスキーマ抽出(DacFxベース)は、明示的な照合を明示的な照合を指定しないのと同等扱います。この場合、次のようになります。

明示的な COLLATE 節は、Gitリポジトリに抽出されたアイテム定義には現れません。
この列は、倉庫のデフォルトのコレーションと実質的な差がないため、Git の変更、更新、デプロイメントパイプラインの比較では違いとして表示されません。

倉庫のデフォルトの照合と異なる列のみがソース管理で明示的な COLLATE 節を持ち、その列の照合の変更のみが違いとして現れます。

例えば、集合が 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 は明示的なコレーションを持たず、ウェアハウスのデフォルトのコレーションを継承します。
LastNameBin はウェアハウスのデフォルトコレーションとは異なる明示的なコレーションを持ち、抽出された定義に保持され、変更された場合でも常に比較に表示されます。
Email 倉庫のデフォルトの集合と一致する明示的なコレーションを持っています。 COLLATE節はT-SQLに存在しますが、Git抽出された定義やGit、デプロイメントパイプラインの比較には現れません。なぜならデフォルトと同等だからです。

重複候補オブジェクトを伴う曖昧な列エラー

Gitからのコミットや更新は、候補リストに :: 区切りを含む曖昧な列エラーで失敗することがあります。例えば:

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

::区切りは、この誤りを別のウェアハウスの2つ以上のテーブルを参照するオブジェクトの無条件列に見られる真の曖昧さと区別します。テーブルエイリアスを追加しても解決しません。エイリアスは候補リストに表示されてもエラーは発生します。

まず、これら二つのより一般的な原因を除外します。
- 本当に行方不明か、名前が誤って使われている物体。 同じコミットや更新で特定の欠落オブジェクト(例えば SQL71501: View: [dbo].[v_report] has an unresolved reference to object [dbo].[MissingTable])への未解決参照も報告された場合は、まずその参照を修正してください。 ::候補者も通常それに同意します。
- 本当に曖昧なコラムです。 もし無条件の列が、その名前の列を公開している2つのソースの結合の上で選択された場合、その列にテーブルの別名で条件付けします。例えば a.[NCESID]。 SQL Serverもこのクエリを拒否するので、Git統合に特有のものではありません。
参照されるすべてのオブジェクトが存在し、どの列も本当に曖昧であれば、 :: 候補はGitからのコミットや更新時に実行される検証で既知の問題であり、製品チームが追跡しています。以下の回避策を順に試してみてください:
1. CTEや派生テーブル内の SELECT * を明示的なカラムリストに置き換えます。
2. 各曖昧なソースが独立したビューで定義されるようにビューを分割し、基礎となるクエリを繰り返す代わりにそのビューを参照します。
3. 同じ文で他の動的に形状 OPENROWSET(BULK ...) 源と結合するのは避けてください。

これらのどれもエラーを解決しない場合は、エラーに記載されたオブジェクトの定義を取得し、サポートリクエストを開きます。デプロイメントパイプラインに特有の制限については、「制限事項」を参照してください。

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-07-31