Eksportowanie danych do tabeli zewnętrznej

Artykuł
01/18/2024

Dane można wyeksportować, definiując tabelę zewnętrzną i eksportując do niej dane. Właściwości tabeli są określane podczas tworzenia tabeli zewnętrznej. Polecenie eksportu odwołuje się do tabeli zewnętrznej według nazwy.

Uprawnienia

Aby uruchomić to polecenie, musisz mieć co najmniej uprawnienia do Administracja tabeli.

Składnia

.export [async] totableexternalTableName
[with(propertyName=propertyValue [, ...])] <|Kwerendy

Dowiedz się więcej o konwencjach składniowych.

Parametry

Nazwa	Typ	Wymagane	Opis
externalTableName	`string`	✔️	Nazwa tabeli zewnętrznej, do której ma być eksportowany.
propertyName, propertyValue	`string`		Rozdzielona przecinkami lista właściwości opcjonalnych.
Kwerendy	`string`	✔️	Zapytanie eksportu.

Obsługiwane właściwości

Następujące właściwości są obsługiwane w ramach eksportowania do zewnętrznej tabeli polecenia.

Właściwość	Typ	Opis	Default
`sizeLimit`	`long`	Limit rozmiaru w bajtach zapisywanego pojedynczego artefaktu magazynu (przed kompresją). Przed sprawdzeniem, czy ta grupa wierszy osiągnęła limit rozmiaru `parquetRowGroupSize` , zostanie zapisana pełna grupa wierszy i powinna rozpocząć nowy artefakt. Prawidłowy zakres: 100 MB (domyślnie) do 1 GB.
`distributed`	`bool`	Wyłącz/włącz eksport rozproszony. Ustawienie wartości false jest równoważne `single` wskazówce dystrybucji.	Wartość domyślna to `true`.
`distribution`	`string`	Wskazówka dystrybucji (`single`, `per_node`, `per_shard`). Zobacz więcej szczegółów w temacie Ustawienia dystrybucji	Wartość domyślna to `per_node`.
`distributionKind`	`string`	Opcjonalnie przełącza się na jednolitą dystrybucję, gdy tabela zewnętrzna jest partycjonowana według partycji ciągu. Prawidłowe wartości to `uniform` lub `default`. Zobacz więcej szczegółów w temacie Ustawienia dystrybucji
`concurrency`	Liczba	Wskazuje system, ile partycji ma być uruchamianych równolegle. Zobacz więcej szczegółów w temacie Ustawienia dystrybucji	Wartość domyślna to 16.
`spread`	Liczba	Wskazuje systemowi sposób dystrybucji partycji między węzłami klastra. Zobacz więcej szczegółów w temacie Ustawienia dystrybucji	Wartość domyślna to `Min(64, number-of-nodes)`.
`parquetRowGroupSize`	`int`	Dotyczy tylko wtedy, gdy format danych to Parquet. Steruje rozmiarem grupy wierszy w wyeksportowanych plikach. Ta wartość ma pierwszeństwo przed `sizeLimit`wartością , co oznacza, że przed sprawdzeniem, czy ta grupa wierszy osiągnęła limit rozmiaru i powinna rozpocząć nowy artefakt.	Domyślny rozmiar grupy wierszy to 100 000 rekordów.

Ustawienia dystrybucji

Rozkład eksportu do operacji tabeli zewnętrznej wskazuje liczbę węzłów i wątków zapisywanych jednocześnie w magazynie. Domyślna dystrybucja zależy od partycjonowania tabeli zewnętrznej:

Partycjonowanie tabeli zewnętrznej Rozkład domyślny

Tabela zewnętrzna nie jest partycjonowana ani partycjonowana tylko według datetime kolumn Eksport jest dystrybuowany per_node — wszystkie węzły w klastrze są eksportowane współbieżnie. Każdy węzeł zapisuje dane przypisane do tego węzła. Liczba plików wyeksportowanych przez węzeł będzie większa niż jedna, tylko wtedy, gdy rozmiar danych z tego węzła przekroczy sizeLimitwartość .

Tabela zewnętrzna jest partycjonowana według kolumny ciągu Dane do wyeksportowania są przenoszone między węzłami, tak aby każdy węzeł zapisywał podzestaw wartości partycji. Pojedyncza partycja jest zawsze zapisywana przez jeden węzeł. Liczba plików zapisywanych na partycję powinna być większa niż jedna tylko wtedy, gdy dane przekraczają sizeLimitwartość . Jeśli tabela zewnętrzna zawiera kilka partycji ciągów, dane są partycjonowane między węzłem na podstawie pierwszej partycji. Dlatego zaleca się zdefiniowanie partycji z najbardziej jednolitą dystrybucją jako pierwszą.

Partycjonowanie tabeli zewnętrznej	Rozkład domyślny
Tabela zewnętrzna nie jest partycjonowana ani partycjonowana tylko według `datetime` kolumn	Eksport jest dystrybuowany `per_node` — wszystkie węzły w klastrze są eksportowane współbieżnie. Każdy węzeł zapisuje dane przypisane do tego węzła. Liczba plików wyeksportowanych przez węzeł będzie większa niż jedna, tylko wtedy, gdy rozmiar danych z tego węzła przekroczy `sizeLimit`wartość .
Tabela zewnętrzna jest partycjonowana według kolumny ciągu	Dane do wyeksportowania są przenoszone między węzłami, tak aby każdy węzeł zapisywał podzestaw wartości partycji. Pojedyncza partycja jest zawsze zapisywana przez jeden węzeł. Liczba plików zapisywanych na partycję powinna być większa niż jedna tylko wtedy, gdy dane przekraczają `sizeLimit`wartość . Jeśli tabela zewnętrzna zawiera kilka partycji ciągów, dane są partycjonowane między węzłem na podstawie pierwszej partycji. Dlatego zaleca się zdefiniowanie partycji z najbardziej jednolitą dystrybucją jako pierwszą.

Zmienianie domyślnych ustawień dystrybucji

Zmiana domyślnych ustawień dystrybucji może być przydatna w następujących przypadkach:

Przypadek użycia	Opis	Zalecenie
Zmniejsz liczbę wyeksportowanych plików	Eksport tworzy zbyt wiele małych plików i chcesz utworzyć mniejszą liczbę większych plików.	Ustaw `distribution`=`single` lub `distributed`=`false` (oba są równoważne) we właściwościach polecenia. Eksport wykonuje tylko jeden wątek. Wadą tego jest to, że operacja eksportowania może być wolniejsza, ponieważ współbieżność jest znacznie zmniejszona.
Zmniejsz czas trwania eksportu	Zwiększenie współbieżności operacji eksportowania w celu skrócenia czasu trwania operacji.	Ustaw `distribution`=`per_shard` we właściwościach polecenia. Oznacza to współbieżność operacji zapisu na fragmenty danych, a nie na węzeł. Jest to istotne tylko w przypadku eksportowania do tabeli zewnętrznej, która nie jest partycjonowana przez partycję ciągu. Może to spowodować zbyt duże obciążenie magazynu, co może spowodować ograniczenie przepustowości. Zobacz Błędy magazynu.
Zmniejsz czas trwania eksportu dla tabel zewnętrznych partycjonowanych przez partycję ciągu	Jeśli partycje nie są równomiernie rozłożone między węzłami, uruchomienie eksportu może potrwać dłużej. Jeśli na przykład istnieje jedna partycja, która jest znacznie większa niż inne, większość pracy eksportu jest wykonywana przez pojedynczy węzeł przypisany do tej partycji, podczas gdy inne węzły będą w większości bezczynne. Zobacz Ustawienia dystrybucji.	Istnieje kilka ustawień, które można zmienić: * Jeśli istnieje więcej niż jedna partycja ciągu, najpierw zdefiniuj partycję z najlepszą dystrybucją. * Ustaw `distributionKind`=`uniform` we właściwościach polecenia. To ustawienie wyłącza domyślne ustawienia dystrybucji dla tabel zewnętrznych partycjonowanych w ciągu. Eksport zostanie uruchomiony z dystrybucją `per-node` , a każdy węzeł wyeksportuje dane przypisane do węzła. Pojedyncza partycja może być zapisywana przez kilka węzłów, a liczba plików zwiększa się odpowiednio. Aby jeszcze bardziej zwiększyć współbieżność, należy ustawić `distributionKind`=`uniform` element wraz z `distribution`=`per_shard` największą współbieżnością (kosztem potencjalnie większej liczby zapisanych plików) * Jeśli przyczyną powolnego eksportu nie są wartości odstające w danych, zmniejsz czas trwania, zwiększając współbieżność, bez zmieniania ustawień partycjonowania. `hint.spread` Użyj właściwości i`hint.concurrency`, które określają współbieżność partycjonowania. Zobacz operator partycji. Domyślnie liczba węzłów eksportowanych współbieżnie (wartość `spread`) będzie minimalną wartością z zakresu od 64 do liczby węzłów klastra. Ustawienie `spread` na wyższą liczbę niż liczba węzłów zwiększa współbieżność w każdym węźle (maksymalna wartość wynosi `spread` 64).

Uwierzytelnianie i autoryzacja

Aby wyeksportować do tabeli zewnętrznej, należy skonfigurować uprawnienia do zapisu. Aby uzyskać więcej informacji, zobacz uprawnienia do zapisu dla tabeli zewnętrznej usługi Azure Storage lub tabeli zewnętrznej SQL Server.

Dane wyjściowe

Parametr wyjściowy	Typ	Opis
ExternalTableName	`string`	Nazwa tabeli zewnętrznej.
Ścieżka	`string`	Ścieżka wyjściowa.
NumRecords	`string`	Liczba rekordów wyeksportowanych do ścieżki.

Uwagi

Schemat danych wyjściowych kwerendy eksportu musi być zgodny ze schematem tabeli zewnętrznej, w tym ze wszystkimi kolumnami zdefiniowanymi przez partycje. Jeśli na przykład tabela jest partycjonowana według daty/godziny, schemat danych wyjściowych zapytania musi mieć kolumnę Sygnatura czasowa zgodna z wartością TimestampColumnName. Ta nazwa kolumny jest zdefiniowana w definicji partycjonowania tabeli zewnętrznej.
Nie można zastąpić właściwości tabeli zewnętrznej za pomocą polecenia eksportu. Na przykład nie można wyeksportować danych w formacie Parquet do tabeli zewnętrznej, której format danych to CSV.
Jeśli tabela zewnętrzna jest partycjonowana, wyeksportowane artefakty są zapisywane w odpowiednich katalogach zgodnie z definicjami partycji, jak pokazano w przykładzie partycjonowanej tabeli zewnętrznej.
- Jeśli wartość partycji ma wartość null/empty lub jest nieprawidłową wartością katalogu, zgodnie z definicjami magazynu docelowego wartość partycji jest zastępowana wartością __DEFAULT_PARTITION__domyślną .
Aby uzyskać sugestie dotyczące rozwiązywania błędów magazynu podczas eksportowania poleceń, zobacz błędy podczas eksportowania poleceń.
Kolumny tabeli zewnętrznej są mapowane na odpowiednie typy danych formatu docelowego zgodnie z regułami mapowania typów danych .
Eksport natywny Parquet jest bardziej wydajnym mechanizmem eksportu światła zasobów. Wyeksportowana kolumna "datetime" jest obecnie nieobsługiwana przez usługę Synapse SQL "COPY".

Liczba plików

Liczba plików zapisanych na partycję zależy od ustawień dystrybucji operacji eksportowania:

Jeśli tabela zewnętrzna zawiera tylko partycje daty/godziny lub w ogóle nie ma partycji, liczba plików zapisanych (jeśli istnieje) powinna być podobna do liczby węzłów w klastrze (lub więcej, jeśli sizeLimit zostanie osiągnięta). Gdy operacja eksportowania jest dystrybuowana, wszystkie węzły w klastrze eksportują jednocześnie. Aby wyłączyć dystrybucję, tak aby zapisy odbywały się tylko w jednym węźle, ustaw distributed wartość false. Ten proces tworzy mniej plików, ale zmniejszy wydajność eksportu.
Jeśli tabela zewnętrzna zawiera partycję według kolumny ciągu, liczba wyeksportowanych plików powinna być pojedynczym plikiem na partycję (lub więcej, jeśli sizeLimit zostanie osiągnięta). Wszystkie węzły nadal uczestniczą w eksporcie (operacja jest dystrybuowana), ale każda partycja jest przypisana do określonego węzła. Ustawienie distributed wartości false spowoduje wyeksportowanie tylko jednego węzła, ale zachowanie pozostanie takie samo (pojedynczy plik zapisany na partycję).

Przykłady

Przykład tabeli zewnętrznej bez partycjonowania

ExternalBlob to niezdzielona tabela zewnętrzna.

.export to table ExternalBlob <| T

ExternalTableName	Ścieżka	NumRecords
ExternalBlob	http://storage1.blob.core.windows.net/externaltable1cont1/1_58017c550b384c0db0fea61a8661333e.csv	10

Przykład partycjonowanej tabeli zewnętrznej

PartitionedExternalBlob to tabela zewnętrzna zdefiniowana w następujący sposób:

.create external table PartitionedExternalBlob (Timestamp:datetime, CustomerName:string) 
kind=blob
partition by (CustomerName:string=CustomerName, Date:datetime=startofday(Timestamp))   
pathformat = ("CustomerName=" CustomerName "/" datetime_pattern("yyyy/MM/dd", Date))   
dataformat=csv
( 
   h@'http://storageaccount.blob.core.windows.net/container1;secretKey'
)

.export to table PartitionedExternalBlob <| T

ExternalTableName	Ścieżka	NumRecords
ExternalBlob	http://storageaccount.blob.core.windows.net/container1/CustomerName=customer1/2019/01/01/fa36f35c-c064-414d-b8e2-e75cf157ec35_1_58017c550b384c0db0fea61a8661333e.csv	10
ExternalBlob	http://storageaccount.blob.core.windows.net/container1/CustomerName=customer2/2019/01/01/fa36f35c-c064-414d-b8e2-e75cf157ec35_2_b785beec2c004d93b7cd531208424dc9.csv	10

Jeśli polecenie jest wykonywane asynchronicznie (przy użyciu słowa kluczowego async ), dane wyjściowe są dostępne przy użyciu polecenia pokaż szczegóły operacji .