Memecahkan masalah integrasi Git untuk pengembangan gudang

Berlaku untuk: ✅ Gudang di Microsoft Fabric

Artikel ini mencakup topik pemecahan masalah untuk mengembangkan dan menerapkan Fabric Data Warehouse dengan integrasi Git bawaan Fabric.

Important

Fitur ini sedang dalam tahap pratinjau.

Referensi ke objek gudang sendiri dengan menggunakan nama tiga bagian

Sebuah objek dapat merujuk objek lain di gudang yang sama dengan menggunakan nama tiga bagian, [warehouse_name].[schema_name].[object_name].

Penamaan tiga bagian dimaksudkan untuk merujuk pada gudang yang berbeda . Ketika bagian database menamai gudang saat ini, build memperlakukan referensi sebagai eksternal, dan objek tersebut akhirnya didefinisikan dua kali dalam model.

Hapus bagian database dari referensi ke objek gudang sendiri:

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

Hanya referensi ke objek gudang sendiri yang perlu diubar. Referensi lintas basis data asli ke gudang lain, seperti [Other_Warehouse].[Sales].[Orders], didukung dan harus tetap as-is.

Important

Gunakan penamaan tiga bagian (database.schema.object) hanya untuk referensi endpoint analitik lintas gudang atau lintas-SQL, bukan untuk merujuk objek dalam gudang yang sama. Melakukan referensi sendiri pada objek dalam gudang yang sama dengan menggunakan penamaan tiga bagian bukanlah praktik pemodelan standar, dan dapat menciptakan referensi eksternal yang tidak disengaja.

Jika memungkinkan, modelkan objek dengan menggunakan penamaan dua bagian (schema.object) daripada penamaan tiga bagian, bahkan untuk referensi diri dalam gudang yang sama. Konvensi ini meningkatkan konsistensi antar alat klien dan menghindari ambiguitas yang diperkenalkan oleh referensi tiga bagian.

.sqlproj yang sudah usang di repositori Git

Repositori Git dapat berisi .sqlproj file yang merujuk pada versi SDK yang lebih lama Microsoft.Build.Sql . SDK lama tidak mengenali sintaks Fabric Data Warehouse baru seperti IDENTITY kolom dan CLUSTER BY.

Masalah ini memengaruhi repositori yang isinya sudah dikomitmenkan sebelum gudang dipindahkan ke format definisi saat ini. Situasi paling umum yang menyebabkan file .sqlproj yang sudah usang adalah:

  • Menghubungkan workspace baru ke repositori yang sudah ada. Gudang dibuat dari apa pun yang dikomitmenkan di sana.
  • Memperluas ke ruang kerja baru.
  • Memulihkan gudang yang terhapus dari Git.
  • Sinkronisasi dari Git segera setelah warehouse berpindah ke format definisi saat ini, sebelum sinkronisasi ke arah lain berjalan.

Gudang yang tidak dipindahkan ke format definisi saat ini tidak terpengaruh, karena file proyek lama tidak digunakan untuk membangun.

Cara mengonfirmasi versi .sqlproj SDK

Buka file gudang .sqlproj di repositori dan periksa versi SDK di XML:

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

Versi yang berada di belakang Microsoft saat ini. Versi paket Build.Sql menunjukkan file proyek yang sudah usang. Misalnya, jika versi Anda dimulai dengan 0.1.. Untuk informasi lebih lanjut, lihat Microsoft. Rilis Build.SQL dan Template.

Perbarui opsi versi .sqlproj SDK A: sinkronisasi gudang ke Git terlebih dahulu

Jika gudang sudah ada di workspace dan sehat, commit dari workspace ke Git sebelum sinkronisasi ke arah sebaliknya. Tindakan ini akan meregenerasi file proyek dengan versi SDK saat ini, setelah itu sinkronisasi dari Git berjalan normal.

Opsi ini lebih disukai jika tersedia, karena memperbarui seluruh definisi, bukan hanya atribut SDK.

Gudang harus sudah menggunakan format definisi saat ini agar opsi ini dapat berfungsi. Jika belum, upgrade dulu di panel Fabric Git, lalu commit ke Git. Melakukan commit dari gudang yang masih menggunakan format definisi lama akan menulis format lama kembali ke repositori dan tidak menyegarkan versi SDK, sehingga sinkronisasi berikutnya gagal dengan cara yang sama. Jika Anda tidak bisa upgrade, gunakan opsi perbaikan B sebagai gantinya.

Perbarui opsi versi .sqlproj SDK B: perbarui file .sqlproj di Git secara langsung

Gunakan opsi ini ketika gudang belum ada di workspace target, misalnya saat Anda menghubungkan workspace baru ke repositori yang sudah ada, melakukan cabang keluar, atau memulihkan gudang yang dihapus. Dalam kasus tersebut, tidak ada gudang untuk disinkronkan, jadi opsi perbaikan A tidak tersedia.

Edit .sqlproj file di repositori untuk menggunakan Microsoft terbaru. Build.Sql versi paket dan komit perubahan. Contohnya:

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

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

Menjalankan ekspor atau diff sendiri tidak memperbarui file proyek. File hanya ditulis ulang ketika commit dari workspace ke Git selesai, atau saat Anda mengeditnya secara manual.

Kolom tanpa kualifikasi pada objek yang merujuk pada dua atau lebih tabel di gudang lain

Selalu berikan dan gunakan alias tabel saat merujuk kolom dalam kueri T-SQL.

  • Ketika query T-SQL merujuk pada dua atau lebih tabel di gudang lain, build tidak dapat memvalidasi kolom yang ditulis tanpa alias tabel ke tabel tertentu. Tabel-tabel tersebut tidak perlu berbagi nama kolom agar ambiguitas ini ada. Ambiguitas ini ada pada build validasi.
  • Ambiguitas ini memengaruhi kueri T-SQL di dalam objek yang merujuk pada dua atau lebih tabel di gudang lain dalam badan pernyataan yang sama.
  • Ambiguitas ini tidak memengaruhi kueri T-SQL di dalam objek yang hanya merujuk pada satu tabel di gudang lain, karena dengan satu sumber tidak ada yang perlu diragukan.
  • Ambiguitas ini tidak memengaruhi kueri T-SQL yang sepenuhnya berada dalam satu gudang.

Dalam contoh berikut, hanya fieldinfo memiliki finame, sehingga SQL valid dan berjalan dengan benar terhadap gudang, tetapi ada ambiguitas dalam build validasi.

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

Tambahkan alias tabel ke setiap referensi kolom di objek yang terdampak:

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

Kapitalisasi nama skema yang tidak konsisten

Gudang Anda bisa menggunakan kolasi tanpa huruf besar/kecil, jadi sales skema Sales dan sama, tapi skrip Anda mungkin mengejanya dua arah di tempat yang berbeda. Basis data yang tidak sensitif huruf besar/kecil selalu menerima hal itu, jadi ketidakkonsistenan biasanya sudah lama dan tidak berbahaya.

Ketika skrip Anda merujuk pada dua atau lebih objek berbeda dalam skema yang sama di gudang lain, dan mengeja skema tersebut berbeda di setiap referensi, build akan menghasilkan CREATE SCHEMA pernyataan untuk setiap ejaan. Masalah ini hanya memengaruhi gudang yang merujuk pada gudang lain dan menggunakan kolasi tanpa huruf besar/kecil.

  • Secara default, gudang di Fabric menggunakan Latin1_General_100_BIN2_UTF8, kolasi sensitif huruf besar. Gudang sensitif terhadap huruf besar tidak terpengaruh. Di gudang-gudang itu, sales dan Sales ada dua skema yang berbeda, apakah Anda bermaksud demikian atau tidak.
  • Database yang tidak sensitif huruf besar/kecil tidak dapat memuat keduanya sales dan Sales. Duplikat hanya berasal dari ejaan yang berbeda dalam teks SQL Anda.

Periksa kolasi gudang dan yang ditentukan ModelCollation dalam .sqlproj file. Cari ( CI tidak sensitif huruf besar) atau CS (sensitif huruf kecil).

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

Perbaiki

Untuk mengidentifikasi kapitalisasi nama skema yang tidak konsisten dalam definisi objek gudang Anda, bandingkan kapitalisasi skema yang disebutkan dalam kesalahan di semua skrip Anda. Cari dua referensi cross-warehouse ke skema yang sama yang hanya berbeda jika terjadi kasus tertentu.

Gunakan satu kapitalisasi yang konsisten di mana-mana, sesuai dengan nama skema sebenarnya di gudang yang direferensikan. Misalnya, gunakan hanya Sales atau hanya 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];

Anda menghadapi masalah ini ketika Anda memiliki dua objek berbeda dengan dua kapitalisasi skema yang berbeda. Dua referensi ke objek yang sama dengan huruf kapital berbeda dilipat dengan benar dan tidak gagal.

Pengaturan kolom

Jika klausa kolom COLLATE secara eksplisit menentukan kolasi yang sama dengan kolasi default gudang, ekstraksi skema Fabric (berbasis DacFx) memperlakukan kolasi eksplisit tersebut setara dengan tidak menentukan kolasi sama sekali. Dalam hal ini:

  • Klausa eksplisit COLLATE tidak muncul dalam definisi item yang diekstrak ke repositori Git.
  • Kolom tersebut tidak muncul sebagai perbedaan dalam Git Changes, Updates, atau perbandingan pipeline deployment, karena tidak ada perbedaan efektif dari kolasi default gudang.

Hanya kolom yang kolasinya berbeda dari kolasi default gudang yang mempertahankan klausa eksplisit COLLATE dalam kontrol sumber, dan hanya perubahan pada kolasi kolom tersebut yang muncul sebagai perbedaan.

Misalnya, pertimbangkan sebuah gudang yang kolasinya adalah 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 tidak memiliki kolasi eksplisit dan mewarisi kolasi default gudang.
  • LastNameBin memiliki kolasi eksplisit yang berbeda dari kolasi default gudang, sehingga tetap terjaga dalam definisi yang diekstrak dan selalu muncul dalam perbandingan jika berubah.
  • Email memiliki kolasi eksplisit yang sesuai dengan kolasi default gudang. Meskipun COLLATE klausa ini ada di T-SQL, klausa tersebut tidak muncul dalam definisi yang diekstrak Git atau dalam perbandingan pipeline Git atau deployment, karena setara dengan default.

Kesalahan kolom ambigu dengan objek kandidat duplikat

Commit atau pembaruan dari Git dapat gagal dengan kesalahan kolom ambigu yang daftar kandidatnya berisi :: pemisah, misalnya:

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

Pemisah :: membedakan kesalahan ini dari ambiguitas asli yang dijelaskan dalam kolom Unqualified pada objek yang merujuk pada dua atau lebih tabel di gudang lain. Menambahkan alias tabel tidak menyelesaikannya karena alias muncul di daftar kandidat dan kesalahan tetap terjadi.

  1. Pertama, singkirkan dua penyebab yang lebih umum ini:

    • Sebuah objek yang benar-benar hilang atau salah nama. Jika commit atau pembaruan yang sama juga melaporkan referensi yang belum terselesaikan ke objek tertentu yang hilang, misalnya, SQL71501: View: [dbo].[v_report] has an unresolved reference to object [dbo].[MissingTable]perbaiki referensi tersebut terlebih dahulu. Para :: kandidat biasanya juga lulus bersamaan dengan itu.
    • Kolom yang benar-benar ambigu. Jika kolom tanpa kualifikasi dipilih di atas gabungan dua sumber yang keduanya menampilkan kolom dengan nama yang sama, kualifikasi kolom tersebut dengan alias tabelnya, misalnya a.[NCESID]. SQL Server juga akan menolak kueri ini, jadi ini tidak spesifik untuk integrasi Git.

  2. Jika setiap objek yang direferensikan ada dan tidak ada kolom yang benar-benar ambigu :: , kandidat tersebut menjadi masalah yang diketahui dalam validasi yang berjalan selama commit dan pembaruan dari Git, dilacak oleh tim produk. Coba solusi alternatif berikut, berurutan:

    1. Ganti SELECT * CTE di dalam dan tabel turunan dengan daftar kolom eksplisit.
    2. Pisahkan tampilan sehingga setiap sumber ambigu didefinisikan dalam pandangannya sendiri, dan referensikan tampilan tersebut daripada mengulangi kueri dasarnya.
    3. Hindari bergabung OPENROWSET(BULK ...) ke sumber lain yang berbentuk dinamis dalam pernyataan yang sama.

Jika tidak ada yang menyelesaikan kesalahan, kumpulkan definisi objek yang disebutkan dalam kesalahan dan buka permintaan dukungan. Untuk keterbatasan spesifik pada pipeline deployment, lihat Keterbatasan.

Konten terkait

  • Terakhir diperbarui pada