Azure Depolama dış tablolarını oluşturma ve değiştirme

Makale
11/23/2024

Şunlar için geçerlidir: ✅Microsoft Fabric✅Azure Veri Gezgini

Bu makaledeki komutlar, komutun yürütüldiği veritabanında bir Azure Depolama dış tablosu oluşturmak veya değiştirmek için kullanılabilir. Azure Depolama dış tablosu Azure Blob Depolama, Azure Data Lake Store 1. Nesil veya Azure Data Lake Store 2. Nesil'de bulunan verilere başvurur.

Not

Tablo varsa, .create komut bir hatayla başarısız olur. Mevcut tabloları değiştirmek için veya .alter kullanın.create-or-alter.

İzinler

Için .create en az Veritabanı Kullanıcısı izinleri ve .alter en az Tablo Yöneticisi izinleri gerekir.

Yönetilen kimlik kimlik doğrulaması kullanan bir dış tablo için .create-or-alter AllDatabasesAdmin izinleri gerekir.

Sözdizimi

(.create | .create-or-alter | .alter) external table TableName (Şeması) storage = kind [partition by(Partitions) [pathformat(= PathFormat)]] dataformat = DataFormat (StorageConnectionString [, ...] ) [with (Özellik [, ...])]

Not

kind tüm storage Azure Depolama dış veri deposu türleri içindir. blob ve adl kullanım dışı bırakılmış terimlerdir.

Söz dizimi kuralları hakkında daha fazla bilgi edinin.

Parametreler

Ad	Tür	Zorunlu	Açıklama
TableName	`string`	✔️	Varlık adları kurallarına bağlı olan bir dış tablo adı . Dış tablo, aynı veritabanındaki normal tabloyla aynı ada sahip olamaz.
Şema	`string`	✔️	Dış veri şeması, bir veya daha fazla sütun adının ve veri türünün virgülle ayrılmış bir listesidir ve her öğe şu biçime uyar: ColumnName `:` ColumnType. Şema bilinmiyorsa, dış dosya içeriğine göre şemayı çıkarsamak için infer_storage_schema kullanın.
Bölümler	`string`		Dış tablonun bölümlendiği sütunların virgülle ayrılmış listesi. Bölüm sütunu veri dosyasının kendisinde veya dosya yolunun bir parçası olarak bulunabilir. Bu değerin nasıl görünmesi gerektiğini öğrenmek için bölüm biçimlendirmesine bakın.
PathFormat	`string`		Bölümler ile kullanılacak bir dış veri klasörü URI yolu biçimi. Bkz. yol biçimi.
Veri Biçimi	`string`	✔️	Veri biçimi; alım biçimlerinden herhangi biri olabilir. Yol eşleme kullanmadığınız `Parquet` sürece sorgu ve dışarı aktarma performansını geliştirmek için dış tablolar biçimini kullanmanızı `JSON` öneririz. Dışarı aktarma senaryosu için dış tablo kullanırken, şu biçimler ile sınırlısınız: `CSV`, `TSV`ve `JSON` `Parquet`.
StorageConnectionString	`string`	✔️	Azure Blob Depolama blob kapsayıcılarına, Azure Data Lake 2. Nesil dosya sistemlerine veya kimlik bilgileri de dahil olmak üzere Azure Data Lake 1. Nesil kapsayıcılarına yönelik virgülle ayrılmış bir veya daha fazla yol. Dış tablo depolama türü, sağlanan bağlantı dizesi tarafından belirlenir. Bkz. depolama bağlantı dizesi.
Özellik	`string`		PropertyName `=` PropertyValue biçiminde bir anahtar-değer özellik çifti. bkz. isteğe bağlı özellikler.

Not

Aynı olmayan şemaya sahip CSV dosyaları verilerin kaydırılmış veya eksik görünmesine neden olabilir. Ayrı şemalara sahip CSV dosyalarını ayrı depolama kapsayıcılarına ayırmanızı ve uygun şemaya sahip her depolama kapsayıcısı için bir dış tablo tanımlamanızı öneririz.

İpucu

Büyük miktarda veriyi dış tabloya aktarırken depolama azaltmasını önlemek için tek bir depolama hesabından daha fazlasını sağlayın. Dışarı aktarma, sağlanan tüm hesaplar arasında yazmaları dağıtır.

Kimlik doğrulaması ve yetkilendirme

Dış tabloya erişmek için kullanılan kimlik doğrulama yöntemi, oluşturma sırasında sağlanan bağlantı dizesi temel alır ve tabloya erişmek için gereken izinler kimlik doğrulama yöntemine bağlı olarak değişir.

Aşağıdaki tabloda, Azure Depolama dış tabloları için desteklenen kimlik doğrulama yöntemleri ve tabloyu okumak veya tabloya yazmak için gereken izinler listelenmektedir.

Kimlik doğrulama yöntemi	Azure Blob Depolama / Data Lake Storage 2. Nesil	Data Lake Storage 1. Nesil
Kim -liğe bürünme	Okuma izinleri: Depolama Blobu Veri Okuyucusu Yazma izinleri: Depolama Blob Verileri Katkıda Bulunanı	Okuma izinleri: Okuyucu Yazma izinleri: Katkıda Bulunan
Yönetilen kimlik	Okuma izinleri: Depolama Blobu Veri Okuyucusu Yazma izinleri: Depolama Blob Verileri Katkıda Bulunanı	Okuma izinleri: Okuyucu Yazma izinleri: Katkıda Bulunan
Paylaşılan Erişim (SAS) belirteci	Okuma izinleri: Liste + Okuma Yazma izinleri: Yazma	Bu kimlik doğrulama yöntemi 1. Nesil'de desteklenmez.
Microsoft Entra erişim belirteci	Ek izin gerekmez.	Ek izin gerekmez.
Depolama hesabı erişim anahtarı	Ek izin gerekmez.	Bu kimlik doğrulama yöntemi 1. Nesil'de desteklenmez.

Bölümleri biçimlendirme

Bölümler listesi, aşağıdaki tabloda gösterilen formlardan biri kullanılarak belirtilen bölüm sütunlarının herhangi bir bileşimidir.

Bölüm Türü	Sözdizimi	Notlar
Sanal sütun	PartitionName `:` (`datetime` \| `string`)	Sanal sütunlar hakkında daha fazla bilgi edinin.
Dize sütun değeri	PartitionName `=` `:` `string` ColumnName
Dize sütun değeri hash()	PartitionName `=``long` `hash(:` ColumnName Numarası`,` `)`	Karma mod Numarası'dır.
Kesilmiş tarih saat sütunu (değer)	PartitionName `datetime` `:` `=` (`startofyearstartofweek` \| \| \| `startofdaystartofmonth`) `(` ColumnName `)`	startofyear, startofmonth , startofweek veya startofday işlevleriyle ilgili belgelere bakın.
Kesilmiş Tarih Saat Sütun Değeri `=` `(` `bin` ColumnName `,` TimeSpan `)`	Bin işlevi hakkında daha fazla bilgi edinin.

Yol biçimi

PathFormat parametresi, bölümlere ek olarak dış veri klasörü URI yolunun biçimini belirtmenize olanak tanır. Bir dizi bölüm öğesinden ve metin ayırıcılarından oluşur. Bölüm öğesi, bölüm yan tümcesinde bildirilen bir bölüme by başvurur ve metin ayırıcısı tırnak içine alınmış herhangi bir metindir. Ardışık bölüm öğeleri, metin ayırıcısı kullanılarak ayrılmalıdır.

[ StringSeparator ] Partition [ StringSeparator ] [Partition [ StringSeparator ] ...]

Özgün dosya yolu ön ekini oluşturmak için bölüm öğeleri dize olarak işlenir ve karşılık gelen metin ayırıcılarıyla ayrılır. Tarih saat bölüm değerini işlemek için kullanılan biçimi belirtmek için makroyu (DateTimeFormat, PartitionName)) kullanabilirsiniz.datetime_patterndatetime_pattern( Makro .NET biçim belirtimine bağlıdır ve biçim tanımlayıcılarının küme ayraç içine alınmasına izin verir. Örneğin, aşağıdaki iki biçim eşdeğerdir:

'year='yyyy'/month='MM
year={yyyy}/month={MM}

Varsayılan olarak, datetime değerleri aşağıdaki biçimler kullanılarak işlenir:

Bölüm işlevi	Varsayılan biçim
`startofyear`	`yyyy`
`startofmonth`	`yyyy/MM`
`startofweek`	`yyyy/MM/dd`
`startofday`	`yyyy/MM/dd`
`bin(`Sütun`, 1d)`	`yyyy/MM/dd`
`bin(`Sütun`, 1h)`	`yyyy/MM/dd/HH`
`bin(`Sütun`, 1m)`	`yyyy/MM/dd/HH/mm`

İpucu

Bölümler ve PathFormat tanımı doğruluğunu denetlemek için veya dış tablo oluştururken özelliğini sampleUris filesPreview kullanın.

Sanal sütunlar

Spark'tan veri dışarı aktarıldığında, bölüm sütunları (veri çerçevesi yazıcısının partitionBy yöntemine sağlanır) veri dosyalarına yazılamaz. Bu işlem, veriler klasör adlarında (örneğin) column1=<value>/column2=<value>/zaten bulunduğundan ve Spark okunduktan sonra bunu tanıyabildiğinden, veri yinelemesini önler.

Dış tablolar bu verilerin biçiminde virtual columsokunmasını destekler. Sanal sütunlar veya datetimetüründe string olabilir ve aşağıdaki söz dizimi kullanılarak belirtilir:

.create external table ExternalTable (EventName:string, Revenue:double)  
kind=storage  
partition by (CustomerName:string, Date:datetime)  
pathformat=("customer=" CustomerName "/date=" datetime_pattern("yyyyMMdd", Date))  
dataformat=parquet
( 
   h@'https://storageaccount.blob.core.windows.net/container1;secretKey'
)

Sorgudaki sanal sütunlara göre filtrelemek için sorgu koşulunda bölüm adlarını belirtin:

external_table("ExternalTable")
 | where Date between (datetime(2020-01-01) .. datetime(2020-02-01))
 | where CustomerName in ("John.Doe", "Ivan.Ivanov")

İsteğe bağlı özellikler

Özellik	Türü	Açıklama
`folder`	`string`	Tablonun klasörü
`docString`	`string`	Tabloyu belgeleme dizesi
`compressed`	`bool`	Ayarlanırsa, dosyaların dosya olarak `.gz` sıkıştırılıp sıkıştırılmadığını gösterir (yalnızca dışarı aktarma senaryosunda kullanılır)
`includeHeaders`	`string`	Sınırlandırılmış metin biçimleri için (CSV, TSV, ...), dosyaların üst bilgi içerip içermediğini gösterir. Olası değerler şunlardır: `All` (tüm dosyalar üst bilgi içerir), `FirstFile` (klasördeki ilk dosya üst bilgi içerir), `None` (hiçbir dosya üst bilgi içermez).
`namePrefix`	`string`	Ayarlanırsa, dosyaların ön ekini gösterir. Yazma işlemlerinde, tüm dosyalar bu ön ek ile yazılır. Okuma işlemlerinde yalnızca bu ön eke sahip dosyalar okunur.
`fileExtension`	`string`	Ayarlanırsa, dosyaların dosya uzantılarını gösterir. Yazmada, dosya adları bu son ekle sona erer. Okumada, yalnızca bu dosya uzantısına sahip dosyalar okunur.
`encoding`	`string`	Metnin nasıl kodlanmış olduğunu gösterir: `UTF8NoBOM` (varsayılan) veya `UTF8BOM`.
`sampleUris`	`bool`	Ayarlanırsa, komut sonucu, dış tablo tanımı tarafından beklendiği gibi sanal dış veri dosyaları URI'si örnekleri sağlar. Bu seçenek, Bölümler ve PathFormat parametrelerinin düzgün tanımlanıp tanımlanmadığını doğrulamaya yardımcı olur.
`filesPreview`	`bool`	Ayarlanırsa, komut sonuç tablolarından biri .show external table artifacts komutunun önizlemesini içerir. gibi `sampleUri`seçeneği de dış tablo tanımının Bölümler ve PathFormat parametrelerini doğrulamaya yardımcı olur.
`validateNotEmpty`	`bool`	Ayarlanırsa, bağlantı dizesi içinde içerik olduğu doğrulanır. Belirtilen URI konumu yoksa veya erişim için yeterli izin yoksa komut başarısız olur.
`dryRun`	`bool`	Ayarlanırsa, dış tablo tanımı kalıcı olmaz. Bu seçenek, özellikle veya `sampleUris` parametresiyle `filesPreview` birlikte dış tablo tanımını doğrulamak için kullanışlıdır.

Not

Dış tabloya oluşturma sırasında, yalnızca sorgu ve dışarı aktarma sırasında erişilir. Tablo tanımının validateNotEmpty geçerli olduğundan ve depolama alanının erişilebilir olduğundan emin olmak için oluşturma sırasında isteğe bağlı özelliğini kullanın.

İpucu

Sorgu sırasında veri dosyası filtrelemesinde rol ve özelliklerin oynadığı rol namePrefix ve fileExtension özellikler hakkında daha fazla bilgi edinmek için dosya filtreleme mantığı bölümüne bakın.

Dosya filtreleme mantığı

Dış tablo sorgulanırken, ilgisiz dış depolama dosyaları filtrelenerek performans iyileştirilir. Dosyaları yineleme ve bir dosyanın işlenip işlenmeyeceğine karar verme işlemi aşağıdaki gibidir:

Dosyaların bulunduğu bir yeri temsil eden bir URI deseni oluşturun. Başlangıçta, URI deseni dış tablo tanımının bir parçası olarak sağlanan bir bağlantı dizesi eşittir. Tanımlanmış bölümler varsa, bunlar PathFormat kullanılarak işlenir ve ardından URI desenine eklenir.
Oluşturulan URI desenleri altında bulunan tüm dosyalar için şunları denetleyin:
- Bölüm değerleri, sorguda kullanılan koşullarla eşleşmektedir.
- Blob adı, böyle bir özellik tanımlanmışsa ile NamePrefixbaşlar.
- Böyle bir özellik tanımlanmışsa blob adı ile FileExtensionbiter.

Tüm koşullar karşılandıktan sonra dosya getirilir ve işlenir.

Not

İlk URI düzeni sorgu koşulu değerleri kullanılarak oluşturulur. Bu, hem sınırlı bir dize değerleri kümesi hem de kapalı zaman aralıkları için en iyi sonucu verir.

Örnekler

Bölümlenmemiş dış tablo

Aşağıdaki bölümlenmemiş dış tabloda, dosyaların doğrudan tanımlanan kapsayıcıların altına yerleştirilmesi beklenir:

.create external table ExternalTable (x:long, s:string)  
kind=storage 
dataformat=csv 
( 
   h@'https://storageaccount.blob.core.windows.net/container1;secretKey' 
)

Tarihe göre bölümlendi

Tarihe göre bölümlenmiş aşağıdaki dış tabloda, dosyaların varsayılan datetime biçimindeki yyyy/MM/dddizinlere yerleştirilmesi beklenir:

.create external table ExternalTable (Timestamp:datetime, x:long, s:string) 
kind=storage
partition by (Date:datetime = bin(Timestamp, 1d)) 
dataformat=csv 
( 
   h@'abfss://filesystem@storageaccount.dfs.core.windows.net/path;secretKey'
)

Aya göre bölümlenmiş

Aya göre bölümlenmiş aşağıdaki dış tabloda dizin biçimi:year=yyyy/month=MM

.create external table ExternalTable (Timestamp:datetime, x:long, s:string) 
kind=storage 
partition by (Month:datetime = startofmonth(Timestamp)) 
pathformat=(datetime_pattern("'year='yyyy'/month='MM", Month)) 
dataformat=csv 
( 
   h@'https://storageaccount.blob.core.windows.net/container1;secretKey' 
)

Ada ve tarihe göre bölümlenmiş

Aşağıdaki dış tabloda veriler önce müşteri adına ve sonra tarihe göre bölümlenir; bu da beklenen dizin yapısının şöyle olduğu customer_name=Softworks/2019/02/01anlamına gelir:

.create external table ExternalTable (Timestamp:datetime, CustomerName:string) 
kind=storage 
partition by (CustomerNamePart:string = CustomerName, Date:datetime = startofday(Timestamp)) 
pathformat=("customer_name=" CustomerNamePart "/" Date)
dataformat=csv 
(  
   h@'https://storageaccount.blob.core.windows.net/container1;secretKey' 
)

Karma ve tarihe göre bölümlenmiş

Aşağıdaki dış tablo önce müşteri adı karması (mod on) ve ardından tarihe göre bölümlenmiştir. Beklenen dizin yapısı şöyledir: , customer_id=5/dt=20190201ve veri dosyası adları uzantıyla .txt biter:

.create external table ExternalTable (Timestamp:datetime, CustomerName:string) 
kind=storage 
partition by (CustomerId:long = hash(CustomerName, 10), Date:datetime = startofday(Timestamp)) 
pathformat=("customer_id=" CustomerId "/dt=" datetime_pattern("yyyyMMdd", Date)) 
dataformat=csv 
( 
   h@'https://storageaccount.blob.core.windows.net/container1;secretKey'
)
with (fileExtension = ".txt")

Sorgudaki bölüm sütunlarına göre filtreleme

Sorgudaki bölüm sütunlarına göre filtrelemek için, sorgu koşulunda özgün sütun adını belirtin:

external_table("ExternalTable")
 | where Timestamp between (datetime(2020-01-01) .. datetime(2020-02-01))
 | where CustomerName in ("John.Doe", "Ivan.Ivanov")

Örnek Çıkış

TableName	TableType	Klasör	DocString	Properties	ConnectionStrings	Bölümler	PathFormat
ExternalTable	Blob	ExternalTable'lar	Belgeler	{"Format":"Csv","Compressed":false,"CompressionType":null,"FileExtension":null,"IncludeHeaders":"None","Encoding":null,"NamePrefix":null}	["https://storageaccount.blob.core.windows.net/container1;*******"]	[{"Mod":10,"Name":"CustomerId","ColumnName":"CustomerName","Ordinal":0},{"Function":"StartOfDay","Name":"Date","ColumnName":"Timestamp","Ordinal":1}]	"customer_id=" CustomerId "/dt=" datetime_pattern("yyyyMDd",Date)

Dış tabloları sorgula.

Verileri dış tabloya aktarın.
Dış tabloya sürekli veri dışarı aktarma.

Aracılığıyla paylaş

Azure Depolama dış tablolarını oluşturma ve değiştirme

İzinler

Sözdizimi

Parametreler

Kimlik doğrulaması ve yetkilendirme

Bölümleri biçimlendirme

Yol biçimi

Sanal sütunlar

İsteğe bağlı özellikler

Dosya filtreleme mantığı

Örnekler

Bölümlenmemiş dış tablo

Tarihe göre bölümlendi

Aya göre bölümlenmiş

Ada ve tarihe göre bölümlenmiş

Karma ve tarihe göre bölümlenmiş

Sorgudaki bölüm sütunlarına göre filtreleme

Geri Bildirim

Ek kaynaklar

Aracılığıyla paylaş

Azure Depolama dış tablolarını oluşturma ve değiştirme

İzinler

Sözdizimi

Parametreler

Kimlik doğrulaması ve yetkilendirme

Bölümleri biçimlendirme

Yol biçimi

Sanal sütunlar

İsteğe bağlı özellikler

Dosya filtreleme mantığı

Örnekler

Bölümlenmemiş dış tablo

Tarihe göre bölümlendi

Aya göre bölümlenmiş

Ada ve tarihe göre bölümlenmiş

Karma ve tarihe göre bölümlenmiş

Sorgudaki bölüm sütunlarına göre filtreleme

İlgili içerik

Geri Bildirim

Ek kaynaklar