COPY INTO (Transact-SQL)

Dotyczy: Azure Synapse Analytics

W tym artykule wyjaśniono, jak używać instrukcji COPY w usłudze Azure Synapse Analytics do ładowania z zewnętrznych kont magazynu. Instrukcja COPY zapewnia największą elastyczność pozyskiwania danych o wysokiej przepływności w usłudze Azure Synapse Analytics.

Użyj funkcji COPY, aby uzyskać następujące możliwości:

• Ładowanie użytkowników o niższych uprawnieniach uprzywilejowanych bez konieczności ścisłego kontrolowania uprawnień do magazynu danych
• Wykonywanie pojedynczej instrukcji języka T-SQL bez konieczności tworzenia innych obiektów bazy danych
• Poprawnie przeanalizuj i załaduj pliki CSV, w których ograniczniki (ciąg, pole, wiersz) są usuwane w kolumnach rozdzielanych ciągami
• Określanie bardziej szczegółowego modelu uprawnień bez uwidaczniania kluczy konta magazynu przy użyciu sygnatur dostępu współdzielonego (SAS)
• Użyj innego konta magazynu dla lokalizacji ERRORFILE (REJECTED_ROW_LOCATION)
• Dostosowywanie wartości domyślnych dla każdej kolumny docelowej i określanie pól danych źródłowych do załadowania do określonych kolumn docelowych
• Określ niestandardowy terminator wierszy, terminator pól i cudzysłów pól dla plików CSV
• Używanie formatów dat programu SQL Server dla plików CSV
• Określanie symboli wieloznacznych i wielu plików w ścieżce lokalizacji magazynu
• Automatyczne odnajdywanie schematów upraszcza proces definiowania i mapowania danych źródłowych na tabele docelowe
• Proces automatycznego tworzenia tabel automatycznie tworzy tabele i współpracuje z automatycznym odnajdywaniem schematów
• Bezpośrednie ładowanie złożonych typów danych z plików Parquet, takich jak Mapy i Listy do kolumn ciągów, bez użycia innych narzędzi do wstępnego przetwarzania danych

Zapoznaj się z następującą dokumentacją, aby zapoznać się z kompleksowymi przykładami i przewodnikami Szybki start, korzystając z instrukcji COPY:

• Szybki start: ładowanie zbiorcze danych przy użyciu instrukcji COPY
• Szybki start: przykłady użycia instrukcji COPY i obsługiwanych metod uwierzytelniania
• Szybki start: tworzenie instrukcji COPY przy użyciu rozbudowanego interfejsu użytkownika programu Synapse Studio

Składnia

COPY INTO [ schema. ] table_name
[ (Column_list) ]
FROM '<external_location>' [ , ...n ]
WITH
 (
 [ FILE_TYPE = { 'CSV' | 'PARQUET' | 'ORC' } ]
 [ , FILE_FORMAT = EXTERNAL FILE FORMAT OBJECT ]
 [ , CREDENTIAL = (AZURE CREDENTIAL) ]
 [ , ERRORFILE = ' [ http(s)://storageaccount/container ] /errorfile_directory [ / ] ] '
 [ , ERRORFILE_CREDENTIAL = (AZURE CREDENTIAL) ]
 [ , MAXERRORS = max_errors ]
 [ , COMPRESSION = { 'Gzip' | 'DefaultCodec' | 'Snappy' } ]
 [ , FIELDQUOTE = 'string_delimiter' ]
 [ , FIELDTERMINATOR =  'field_terminator' ]
 [ , ROWTERMINATOR = 'row_terminator' ]
 [ , FIRSTROW = first_row ]
 [ , DATEFORMAT = 'date_format' ]
 [ , ENCODING = { 'UTF8' | 'UTF16' } ]
 [ , IDENTITY_INSERT = { 'ON' | 'OFF' } ]
 [ , AUTO_CREATE_TABLE = { 'ON' | 'OFF' } ]
)

Argumenty

schema_name

Opcjonalnie, jeśli domyślny schemat dla użytkownika wykonującego operację jest schematem określonej tabeli. Jeśli nie określono schematu, a domyślny schemat użytkownika wykonującego operację COPY różni się od schematu określonej tabeli, funkcja COPY zostanie anulowana i zostanie zwrócony komunikat o błędzie.

table_name

Nazwa tabeli do skopiowania danych. Tabela docelowa może być tabelą tymczasową lub stałą i musi już istnieć w bazie danych. W przypadku trybu automatycznego wykrywania schematu nie udostępniaj listy kolumn.

(column_list)

Opcjonalna lista co najmniej jednej kolumny używanej do mapowania pól danych źródłowych na kolumny tabeli docelowej na potrzeby ładowania danych.

Nie określaj column_list w przypadku AUTO_CREATE_TABLE = 'ON'.

column_list muszą być ujęte w nawiasy i rozdzielane przecinkami. Lista kolumn ma następujący format:

[(Column_name [Default_value domyślne] [Field_number] [,... n])]

• Column_name — nazwa kolumny w tabeli docelowej.
• Default_value — wartość domyślna, która zastępuje dowolną wartość NULL w pliku wejściowym. Wartość domyślna ma zastosowanie do wszystkich formatów plików. Funkcja COPY próbuje załadować wartość NULL z pliku wejściowego, gdy kolumna zostanie pominięta z listy kolumn lub gdy istnieje puste pole pliku wejściowego. Wartość domyślna poprzedza słowo kluczowe "default"
• Field_number — numer pola pliku wejściowego mapowany na kolumnę docelową.
• Indeksowanie pól rozpoczyna się od 1.

Gdy lista kolumn nie jest określona, funkcja COPY mapuje kolumny na podstawie kolejności źródłowej i docelowej: pole wejściowe 1 przechodzi do kolumny docelowej 1, pole 2 przechodzi do kolumny 2 itd.

lokalizacji zewnętrznych

To miejsce, w którym są przygotowane pliki zawierające dane. Obecnie obsługiwane są usługi Azure Data Lake Storage (ADLS) Gen2 i Azure Blob Storage:

• lokalizacji zewnętrznej dla usługi Blob Storage: https://<account\>.blob.core.windows.net/<container\>/<path\>
• lokalizacji zewnętrznej dla usługi ADLS Gen2: https://<account\>.dfs.core.windows.net/<container\>/<path\>

• konto — nazwa konta magazynu

• Container — nazwa kontenera obiektów blob

• ścieżka — folder lub ścieżka pliku dla danych. Lokalizacja rozpoczyna się od kontenera. Jeśli zostanie określony folder, funkcja COPY pobiera wszystkie pliki z folderu i wszystkich jego podfolderów. FUNKCJA COPY ignoruje ukryte foldery i nie zwraca plików rozpoczynających się od podkreśleń (_) lub kropki (.), chyba że jawnie określono w ścieżce. To zachowanie jest takie samo, nawet w przypadku określania ścieżki z symbolem wieloznacznym.

Karty wieloznaczne można uwzględnić w ścieżce, w której

• Dopasowanie nazwy ścieżki wieloznacznej jest uwzględniane w wielkości liter
• Symbol wieloznaczny można użyć znaku ukośnika odwrotnego (\)
• Rozszerzanie symboli wieloznacznych jest stosowane rekursywnie. Na przykład wszystkie pliki CSV w obszarze Customer1 (w tym podkatalogi Customer1) są ładowane w następującym przykładzie: Account/Container/Customer1/*.csv

Wiele lokalizacji plików można określić tylko z tego samego konta magazynu i kontenera za pośrednictwem listy rozdzielanej przecinkami, takich jak:

• https://<account>.blob.core.windows.net/<container\>/<path\>, https://<account\>.blob.core.windows.net/<container\>/<path\>

FILE_TYPE = { "CSV" | "PARQUET" | "ORC" }

FILE_TYPE określa format danych zewnętrznych.

• CSV: określa plik wartości rozdzielonych przecinkami zgodny ze standardem RFC 4180.
• PARQUET: określa format Parquet.
• ORC: określa format ORC (Optimized Row Columnar).

FILE_FORMAT = external_file_format_name

FILE_FORMAT dotyczy tylko plików Parquet i ORC i określa nazwę obiektu formatu pliku zewnętrznego, który przechowuje typ pliku i metodę kompresji dla danych zewnętrznych. Aby utworzyć format pliku zewnętrznego, użyj CREATE EXTERNAL FILE FORMAT.

CREDENTIAL (IDENTITY = '', SECRET = '')

CREDENTIAL określa mechanizm uwierzytelniania umożliwiający dostęp do zewnętrznego konta magazynu. Metody uwierzytelniania to:

1. Punkt końcowy obiektu blob (.blob.core.windows.net) w ścieżce lokalizacji zewnętrznej jest wymagany dla tej metody uwierzytelniania.

2: Punkt końcowy dfs (.dfs.core.windows.net) w ścieżce lokalizacji zewnętrznej jest wymagany dla tej metody uwierzytelniania.

• Uwierzytelnianie przy użyciu sygnatur dostępu współdzielonego (SAS)

  • IDENTITY: stała z wartością "Sygnatura dostępu współdzielonego"
  • SECRET: sygnatura dostępu współdzielonegozapewnia delegowany dostęp do zasobów na koncie magazynu.
  • Wymagane minimalne uprawnienia: ODCZYT i LISTA

• Uwierzytelnianie za pomocą jednostek usługi

  • IDENTITY: <ClientID>@<OAuth_2.0_Token_EndPoint>
  • SECRET: klucz jednostki usługi aplikacji firmy Microsoft Entra
  • Wymagane są minimalne role kontroli dostępu opartej na rolach: współautor danych obiektu blob usługi Storage, współautor danych obiektu blob usługi Storage, właściciel danych obiektu blob usługi Storage lub czytelnik danych obiektu blob usługi Storage

• Uwierzytelnianie przy użyciu klucza konta magazynu

  • IDENTITY: stała z wartością "Klucz konta magazynu"
  • SECRET: klucz konta magazynu

• Uwierzytelnianie za pomocą tożsamości zarządzanej (punkty końcowe usługi sieci wirtualnej)

  • IDENTITY: stała z wartością "Tożsamość zarządzana"
  • Wymagane są minimalne role RBAC: współautor danych obiektu blob usługi Storage lub właściciel danych obiektu blob usługi Storage dla zarejestrowanego serwera logicznego firmy Microsoft w usłudze Azure. W przypadku korzystania z dedykowanej puli SQL (dawniej SQL DW), która nie jest skojarzona z obszarem roboczym usługi Synapse, ta rola RBAC nie jest wymagana, ale tożsamość zarządzana wymaga uprawnień listy kontroli dostępu (ACL) do obiektów docelowych w celu umożliwienia dostępu do odczytu do plików źródłowych

• Uwierzytelnianie za pomocą użytkownika entra firmy Microsoft

  • CREDENTIAL nie jest wymagane
  • Wymagane są minimalne role kontroli dostępu opartej na rolach: współautor danych obiektu blob usługi Storage lub właściciel danych obiektu blob usługi Storage dla użytkownika firmy Microsoft Entra

ERRORFILE = lokalizacji katalogu

ERRORFILE dotyczy tylko pliku CSV. Określa katalog w instrukcji COPY, w której powinny zostać zapisane odrzucone wiersze i odpowiedni plik błędu. Można określić pełną ścieżkę z konta magazynu lub ścieżkę względem kontenera. Jeśli określona ścieżka nie istnieje, zostanie ona utworzona w Twoim imieniu. Zostanie utworzony katalog podrzędny o nazwie "_rejectedrows". Znak "_" gwarantuje, że katalog zostanie uniknięty dla innego przetwarzania danych, chyba że jawnie nazwany w parametrze location.

W tym katalogu istnieje folder utworzony na podstawie czasu przesłania obciążenia w formacie YearMonthDay -HourMinuteSecond (np. 20180330-173205). W tym folderze są zapisywane dwa typy plików, plik przyczyny (Błąd) i plik danych (Wiersz) każdego wstępnego zastosowania z identyfikatorem queryID, distributionID i identyfikatorem GUID pliku. Ponieważ dane i przyczyna znajdują się w osobnych plikach, odpowiadające im pliki mają pasujący prefiks.

Jeśli plik ERRORFILE ma zdefiniowaną pełną ścieżkę konta magazynu, ERRORFILE_CREDENTIAL jest używana do nawiązywania połączenia z tym magazynem. W przeciwnym razie jest używana wartość podana dla funkcji CREDENTIAL. Gdy to samo poświadczenie używane dla danych źródłowych jest używane dla pliku ERRORFILE, obowiązują również ograniczenia dotyczące ERRORFILE_CREDENTIAL

ERRORFILE_CREDENTIAL = (IDENTITY= '', SECRET = '')

ERRORFILE_CREDENTIAL dotyczy tylko plików CSV. Obsługiwane metody źródła danych i uwierzytelniania to:

• Azure Blob Storage — SAS/SERVICE PRINCIPAL/AAD

• Azure Data Lake Gen2 — SAS/MSI/SERVICE PRINCIPAL/AAD

• Uwierzytelnianie przy użyciu sygnatur dostępu współdzielonego (SAS)

  • IDENTITY: stała z wartością "Sygnatura dostępu współdzielonego"
  • SECRET: sygnatura dostępu współdzielonegozapewnia delegowany dostęp do zasobów na koncie magazynu.
  • Wymagane minimalne uprawnienia: READ, LIST, WRITE, CREATE, DELETE

• Uwierzytelnianie za pomocą jednostek usługi

  • IDENTITY: <ClientID>@<OAuth_2.0_Token_EndPoint>
  • SECRET: klucz jednostki usługi aplikacji firmy Microsoft Entra
  • Wymagane są minimalne role RBAC: współautor danych obiektu blob usługi Storage lub właściciel danych obiektu blob usługi Storage

• Uwierzytelnianie za pomocą tożsamości zarządzanej (punkty końcowe usługi sieci wirtualnej)

  • IDENTITY: stała z wartością "Tożsamość zarządzana"
  • Wymagane są minimalne role RBAC: współautor danych obiektu blob usługi Storage lub właściciel danych obiektu blob usługi Storage dla zarejestrowanego serwera usługi SQL Database firmy Microsoft

• Uwierzytelnianie za pomocą użytkownika entra firmy Microsoft

  • CREDENTIAL nie jest wymagane
  • Wymagane są minimalne role kontroli dostępu opartej na rolach: współautor danych obiektu blob usługi Storage lub właściciel danych obiektu blob usługi Storage dla użytkownika firmy Microsoft Entra

Używanie klucza konta magazynu z ERRORFILE_CREDENTIAL nie jest obsługiwane.

MAXERRORS = max_errors

MAXERRORS określa maksymalną liczbę wierszy odrzucania dozwolonych w obciążeniu przed niepowodzeniem operacji KOPIOWANIa. Każdy wiersz, którego nie można zaimportować przez operację KOPIOWANIa, jest ignorowany i liowany jako jeden błąd. Jeśli max_errors nie zostanie określona, wartość domyślna to 0.

MAXERRORS nie można używać z AUTO_CREATE_TABLE.

Jeśli FILE_TYPE to "PARQUET", wyjątki spowodowane przez błędy konwersji typu danych (np. plik binarny Parquet do liczby całkowitej SQL) nadal powodują niepowodzenie kopiowania DO, ignorując MAXERRORS.

COMPRESSION = { 'DefaultCodec ' | "Snappy" | "GZIP" | "NONE"}

COMPRESSION jest opcjonalna i określa metodę kompresji danych dla danych zewnętrznych.

• Plik CSV obsługuje GZIP
• Parquet obsługuje GZIP i Snappy
• Usługa ORC obsługuje metodę DefaultCodec i Snappy.
• Zlib jest domyślną kompresją ORC

Polecenie COPY automatycznie wykrywa typ kompresji na podstawie rozszerzenia pliku, gdy ten parametr nie jest określony:

• .gz — GZIP
• .snappy — snappy
• .deflate — DefaultCodec (tylko Parquet i ORC)

Polecenie COPY wymaga, aby pliki gzip nie zawierały żadnych końcowych elementów bezużytecznych do normalnego działania. Format gzip ściśle wymaga, aby pliki składały się z prawidłowych elementów członkowskich bez dodatkowych informacji przed, między nimi lub po nich. Każde odchylenie od tego formatu, takie jak obecność końcowych danych innych niż gzip, spowoduje niepowodzenie polecenia COPY. Upewnij się, że na końcu plików gzip nie ma żadnych końcowych elementów bezużytecznych, aby upewnić się, że funkcja COPY może pomyślnie przetworzyć te pliki.

FIELDQUOTE = "field_quote"

FIELDQUOTE dotyczy pliku CSV i określa pojedynczy znak, który jest używany jako znak cudzysłowu (ogranicznik ciągu) w pliku CSV. Jeśli nie zostanie określony, znak cudzysłowu (") jest używany jako znak cudzysłowu zdefiniowany w standardzie RFC 4180. Notacja szesnastkowa jest również obsługiwana w przypadku funkcji FIELDQUOTE. Rozszerzone znaki ASCII i wielo bajtowe nie są obsługiwane w przypadku formatu UTF-8 dla funkcji FIELDQUOTE.

FIELDTERMINATOR = "field_terminator"

FIELDTERMINATOR dotyczy tylko woluminów CSV. Określa terminator pola używany w pliku CSV. Terminator pola można określić przy użyciu notacji szesnastkowej. Terminator pola może być wieloznaczny. Domyślny terminator pola to (,). Rozszerzone znaki ASCII i wielo bajtowe nie są obsługiwane w przypadku protokołu UTF-8 dla funkcji FIELDTERMINATOR.

TERMINATOR WIERSZY = "row_terminator"

TERMINATOR WIERSZY dotyczy tylko woluminów CSV. Określa terminator wierszy używany w pliku CSV. Terminator wierszy można określić przy użyciu notacji szesnastkowej. Terminator wierszy może być wieloznaczny. Domyślnie terminator wierszy jest \r\n.

Polecenie COPY prefiksuje znak \r podczas określania \n (nowy wiersz), co powoduje \r\n. Aby określić tylko znak \n, użyj notacji szesnastkowej (0x0A). Podczas określania wieloznakowych terminatorów wierszy w szesnastkowym znaku nie należy określać 0x między poszczególnymi znakami.

Rozszerzone znaki ASCII i wiele bajtów nie są obsługiwane w przypadku terminatora WIERSZy UTF-8.

FIRSTROW = First_row_int

FIRSTROW ma zastosowanie do woluminu CSV i określa numer wiersza odczytywany jako pierwszy we wszystkich plikach polecenia COPY. Wartości zaczynają się od 1, czyli wartości domyślnej. Jeśli wartość jest ustawiona na dwa, pierwszy wiersz w każdym pliku (wiersz nagłówka) jest pomijany po załadowaniu danych. Wiersze są pomijane na podstawie istnienia terminatorów wierszy.

DATEFORMAT = { 'mdy' | 'dmy' | 'ymd' | 'ydm' | 'myd' | "dym" }

Format DATEFORMAT dotyczy tylko pliku CSV i określa format daty mapowania daty na formaty dat programu SQL Server. Aby zapoznać się z omówieniem wszystkich typów danych i funkcji daty i godziny Transact-SQL, zobacz Typy danych i funkcje daty i godziny (Transact-SQL). Format DATEFORMAT w poleceniu COPY ma pierwszeństwo przed DATEFORMAT skonfigurowanym na poziomie sesji.

kodowanie = "UTF8" | "UTF16"

kodowanie dotyczy tylko woluminów CSV. Wartość domyślna to UTF8. Określa standard kodowania danych dla plików załadowanych przez polecenie COPY.

IDENTITY_INSERT = 'ON' | "OFF"

IDENTITY_INSERT określa, czy wartość tożsamości lub wartości w zaimportowanych plikach danych mają być używane dla kolumny tożsamości. Jeśli IDENTITY_INSERT jest wyłączone (ustawienie domyślne), wartości tożsamości dla tej kolumny są weryfikowane, ale nie są importowane. Usługa Azure Synapse Analytics automatycznie przypisuje unikatowe wartości na podstawie wartości inicjacji i przyrostów określonych podczas tworzenia tabeli. Zanotuj następujące zachowanie za pomocą polecenia COPY:

• Jeśli IDENTITY_INSERT jest wyłączona, a tabela ma kolumnę tożsamości
  • Należy określić listę kolumn, która nie mapuje pola wejściowego na kolumnę tożsamości.
• Jeśli IDENTITY_INSERT jest włączona, a tabela ma kolumnę tożsamości
  • Jeśli lista kolumn jest przekazywana, musi mapować pole wejściowe na kolumnę tożsamości.
• Wartość domyślna nie jest obsługiwana dla kolumny IDENTITY COLUMN na liście kolumn.
• IDENTITY_INSERT można ustawić tylko dla jednej tabeli jednocześnie.

AUTO_CREATE_TABLE = { 'ON' | 'OFF' }

AUTO_CREATE_TABLE określa, czy tabela może zostać utworzona automatycznie, współpracując z automatycznym odnajdywaniem schematów. Jest ona dostępna tylko dla plików Parquet.

• WŁĄCZONE: Włącza automatyczne tworzenie tabel. Proces COPY INTO tworzy nową tabelę automatycznie, odnajdując strukturę pliku do załadowania. Można również używać z wcześniej istniejących tabel, aby korzystać z automatycznego odnajdywania schematów plików Parquet.
• OFF: Automatyczne tworzenie tabeli nie jest włączone. Domyślny.

Nie należy ładować do tabel rozproszonych skrótów z plików Parquet przy użyciu funkcji COPY INTO z AUTO_CREATE_TABLE = 'ON'.

Jeśli pliki Parquet mają zostać załadowane do tabel rozproszonych skrótów przy użyciu funkcji COPY INTO, załaduj je do tabeli przejściowej działania okrężnego, a następnie wstaw ... WYBIERZ z tej tabeli do tabeli rozproszonej skrótu docelowego.

Uprawnienia

Użytkownik wykonujący polecenie COPY musi mieć następujące uprawnienia:

• ADMINISTROWANIE OPERACJAMI ZBIORCZYM BAZY DANYCH
• INSERT

Wymaga uprawnień INSERT i ADMINISTER BULK OPERATIONS. W usłudze Azure Synapse Analytics wymagane są uprawnienia WSTAWIANIE i ADMINISTROWANIE OPERACJAMI ZBIORCZYM BAZY DANYCH.

Ponadto jeśli użytkownik wykonujący polecenie COPY zamierza również wygenerować nową tabelę i załadować do niej dane, wymaga uprawnień CREATE TABLE i ALTER ON SCHEMA.

Aby na przykład zezwolić mike@contoso.com na utworzenie nowej tabeli w schemacie HR i wstawienie danych z pliku Parquet, użyj następującego przykładu Transact-SQL:

GRANT ADMINISTER DATABASE BULK OPERATIONS to [mike@contoso.com];
GRANT INSERT to [mike@contoso.com];

GRANT CREATE TABLE to [mike@contoso.com];
GRANT ALTER on SCHEMA::HR to [mike@contoso.com];

Uwagi

Instrukcja COPY akceptuje tylko prawidłowe znaki UTF-8 i UTF-16 dla danych wierszy i parametrów polecenia. Pliki źródłowe lub parametry (takie jak TERMINATOR WIERSZy lub TERMINATOR PÓL), które używają nieprawidłowych znaków, mogą być niepoprawnie interpretowane przez instrukcję COPY i powodować nieoczekiwane wyniki, takie jak uszkodzenie danych lub inne błędy. Przed wywołania instrukcji COPY upewnij się, że pliki źródłowe i parametry są zgodne ze standardem UTF-8 lub UTF-16.

Przykłady

A. Ładowanie z publicznego konta magazynu

Poniższy przykład to najprostsza forma polecenia COPY, które ładuje dane z konta magazynu publicznego. W tym przykładzie wartości domyślne instrukcji COPY są zgodne z formatem pliku CSV elementu wiersza.

COPY INTO dbo.[lineitem]
FROM 'https://unsecureaccount.blob.core.windows.net/customerdatasets/folder1/lineitem.csv'
WITH (FIELDTERMINATOR = '|')

Wartości domyślne polecenia COPY to:

• DATEFORMAT = Session DATEFORMAT

• MAXERRORS = 0

• Domyślna kompresja jest nieskompresowana

• FIELDQUOTE = '"'

• FIELDTERMINATOR = ','

• ROWTERMINATOR = '\n'

• FIRSTROW = 1

• KODOWANIE = "UTF8"

• FILE_TYPE = "CSV"

• IDENTITY_INSERT = 'OFF'

B. Ładowanie uwierzytelniania za pośrednictwem sygnatury dostępu współdzielonego (SAS)

W poniższym przykładzie są ładowane pliki, które używają kanału informacyjnego wiersza jako terminatora wiersza, takiego jak dane wyjściowe systemu UNIX. W tym przykładzie użyto również klucza sygnatury dostępu współdzielonego do uwierzytelniania w usłudze Azure Blob Storage.

COPY INTO test_1
FROM 'https://myaccount.blob.core.windows.net/myblobcontainer/folder1/'
WITH (
    FILE_TYPE = 'CSV',
    CREDENTIAL=(IDENTITY= 'Shared Access Signature', SECRET='<Your_SAS_Token>'),
    --CREDENTIAL should look something like this:
    --CREDENTIAL=(IDENTITY= 'Shared Access Signature', SECRET='?sv=2018-03-28&ss=bfqt&srt=sco&sp=rl&st=2016-10-17T20%3A14%3A55Z&se=2021-10-18T20%3A19%3A00Z&sig=IEoOdmeYnE9%2FKiJDSHFSYsz4AkNa%2F%2BTx61FuQ%2FfKHefqoBE%3D'),
    FIELDQUOTE = '"',
    FIELDTERMINATOR=';',
    ROWTERMINATOR='0X0A',
    ENCODING = 'UTF8',
    DATEFORMAT = 'ymd',
    MAXERRORS = 10,
    ERRORFILE = '/errorsfolder',--path starting from the storage container
    IDENTITY_INSERT = 'ON'
)

C. Załaduj listę kolumn z wartościami domyślnymi uwierzytelnianymi za pomocą klucza konta magazynu

W tym przykładzie są ładowane pliki określające listę kolumn z wartościami domyślnymi.

--Note when specifying the column list, input field numbers start from 1
COPY INTO test_1 (Col_one default 'myStringDefault' 1, Col_two default 1 3)
FROM 'https://myaccount.blob.core.windows.net/myblobcontainer/folder1/'
WITH (
    FILE_TYPE = 'CSV',
    CREDENTIAL=(IDENTITY= 'Storage Account Key', SECRET='<Your_Account_Key>'),
    --CREDENTIAL should look something like this:
    --CREDENTIAL=(IDENTITY= 'Storage Account Key', SECRET='x6RWv4It5F2msnjelv3H4DA80n0PQW0daPdw43jM0nyetx4c6CpDkdj3986DX5AHFMIf/YN4y6kkCnU8lb+Wx0Pj+6MDw=='),
    FIELDQUOTE = '"',
    FIELDTERMINATOR=',',
    ROWTERMINATOR='0x0A',
    ENCODING = 'UTF8',
    FIRSTROW = 2
)

D. Ładowanie parquet lub ORC przy użyciu istniejącego obiektu formatu pliku

W tym przykładzie użyto symbolu wieloznakowego do załadowania wszystkich plików Parquet w folderze.

COPY INTO test_parquet
FROM 'https://myaccount.blob.core.windows.net/myblobcontainer/folder1/*.parquet'
WITH (
    FILE_FORMAT = myFileFormat,
    CREDENTIAL=(IDENTITY= 'Shared Access Signature', SECRET='<Your_SAS_Token>')
)

E. Ładowanie określania symboli wieloznacznych i wielu plików

COPY INTO t1
FROM
'https://myaccount.blob.core.windows.net/myblobcontainer/folder0/*.txt',
    'https://myaccount.blob.core.windows.net/myblobcontainer/folder1'
WITH (
    FILE_TYPE = 'CSV',
    CREDENTIAL=(IDENTITY= '<client_id>@<OAuth_2.0_Token_EndPoint>',SECRET='<key>'),
    FIELDTERMINATOR = '|'
)

F. Ładowanie przy użyciu poświadczeń tożsamości usługi zarządzanej

COPY INTO dbo.myCOPYDemoTable
FROM 'https://myaccount.blob.core.windows.net/myblobcontainer/folder0/*.txt'
WITH (
    FILE_TYPE = 'CSV',
    CREDENTIAL = (IDENTITY = 'Managed Identity'),
    FIELDQUOTE = '"',
    FIELDTERMINATOR=','
)

G. Ładowanie przy użyciu automatycznego wykrywania schematu

COPY INTO [myCOPYDemoTable]
FROM 'https://myaccount.blob.core.windows.net/customerdatasets/folder1/lineitem.parquet'
WITH (
    FILE_TYPE = 'Parquet',
    CREDENTIAL = ( IDENTITY = 'Shared Access Signature',  SECRET='<key>'),
    AUTO_CREATE_TABLE = 'ON'
)

FAQ

Jaka jest wydajność polecenia COPY w porównaniu z technologią PolyBase?

Polecenie COPY ma lepszą wydajność w zależności od obciążenia.

• Skompresowanych plików nie można podzielić automatycznie. Aby uzyskać najlepszą wydajność ładowania, rozważ podzielenie danych wejściowych na wiele plików podczas ładowania skompresowanych woluminów CSV.

• Duże nieskompresowane pliki CSV można podzielić i załadować równolegle automatycznie, więc w większości przypadków nie ma potrzeby ręcznego dzielenia nieskompresowanych plików CSV. W niektórych przypadkach, gdy automatyczne dzielenie plików nie jest możliwe ze względu na cechy danych, ręczne dzielenie dużych woluminów CSV może nadal przynieść korzyść z wydajności.

Jakie są wskazówki dotyczące dzielenia plików dla polecenia COPY ładujące skompresowane pliki CSV?

Wskazówki dotyczące liczby plików opisano w poniższej tabeli. Gdy zostanie osiągnięta zalecana liczba plików, tym większa wydajność plików jest większa. Liczba plików jest określana przez liczbę węzłów obliczeniowych pomnożonych przez 60. Na przykład w 6000DWU mamy 12 węzłów obliczeniowych i 12*60 = 720 partycji. Aby uzyskać proste środowisko dzielenia plików, zobacz Jak zmaksymalizować przepływność ładowania KOPIOWANIa przy użyciu podziałów plików.

Jakie są wskazówki dotyczące dzielenia plików dla polecenia COPY ładujące pliki Parquet lub ORC?

Nie ma potrzeby dzielenia plików Parquet i ORC, ponieważ polecenie COPY automatycznie dzieli pliki. Pliki Parquet i ORC na koncie usługi Azure Storage powinny mieć rozmiar 256 MB lub większy, aby uzyskać najlepszą wydajność.

Czy istnieją ograniczenia dotyczące liczby lub rozmiaru plików?

Nie ma żadnych ograniczeń dotyczących liczby lub rozmiaru plików; jednak w celu uzyskania najlepszej wydajności zalecamy pliki, które są co najmniej 4 MB.

Czy istnieją znane problemy z instrukcją COPY?

Jeśli masz obszar roboczy usługi Azure Synapse utworzony przed 7 grudnia 2020 r., podczas uwierzytelniania przy użyciu tożsamości zarządzanej może wystąpić podobny komunikat o błędzie: com.microsoft.sqlserver.jdbc.SQLServerException: Managed Service Identity has not been enabled on this server. Please enable Managed Service Identity and try again.

Wykonaj następujące kroki, aby obejść ten problem, rejestrując ponownie tożsamość zarządzaną obszaru roboczego:

1. Zainstaluj program Azure PowerShell. Zapoznaj się z Instalowanie programu PowerShell.
2. Zarejestruj tożsamość zarządzaną obszaru roboczego przy użyciu programu PowerShell:

   Connect-AzAccount
   Select-AzSubscription -SubscriptionId <subscriptionId>
   Set-AzSqlServer -ResourceGroupName your-database-server-resourceGroup -ServerName your-SQL-servername -AssignIdentity
   

Powiązana zawartość

• omówienie ładowania za pomocą usługi Azure Synapse Analytics

Dotyczy:Warehouse w usłudze Microsoft Fabric

W tym artykule wyjaśniono, jak używać instrukcji COPY w magazynie w usłudze Microsoft Fabric do ładowania z zewnętrznych kont magazynu. Instrukcja COPY zapewnia największą elastyczność pozyskiwania danych o wysokiej przepływności w magazynie i jest strategią pozyskiwania danych do magazynu.

W usłudze Microsoft Fabric instrukcja COPY (Transact-SQL) obecnie obsługuje formaty plików PARQUET i CSV. W przypadku źródeł danych obsługiwane są tylko konta usługi Azure Data Lake Storage Gen2.

Aby uzyskać więcej informacji na temat używania funkcji COPY INTO w magazynie w usłudze Microsoft Fabric, zobacz Pozyskiwanie danych do magazynu przy użyciu instrukcji COPY.

Domyślnie COPY INTO uwierzytelnia się jako użytkownik wykonujący identyfikator Entra.

Użyj funkcji COPY, aby uzyskać następujące możliwości:

• Użyj użytkowników o niższych uprawnieniach uprzywilejowanych do załadowania bez konieczności posiadania rygorystycznych uprawnień KONTROLI w magazynie danych.
• Wykonaj pojedynczą instrukcję języka T-SQL bez konieczności tworzenia innych obiektów bazy danych.
• Poprawnie przeanalizuj i załaduj pliki CSV, w których ograniczniki (ciąg, pole, wiersz) są blokowane w kolumnach rozdzielanych ciągami.
• Określ bardziej precyzyjny model uprawnień bez uwidaczniania kluczy konta magazynu przy użyciu sygnatur dostępu współdzielonego (SAS).
• Użyj innego konta magazynu dla lokalizacji ERRORFILE (REJECTED_ROW_LOCATION).
• Dostosuj wartości domyślne dla każdej kolumny docelowej i określ pola danych źródłowych do załadowania do określonych kolumn docelowych.
• Określ niestandardowy terminator wierszy, terminator pól i cudzysłów pól dla plików CSV
• Określ symbole wieloznaczne i wiele plików w ścieżce lokalizacji magazynu.
• Aby uzyskać więcej informacji na temat opcji pozyskiwania danych i najlepszych rozwiązań, zobacz pozyskiwanie danych do magazynu przy użyciu instrukcji COPY.

Składnia

COPY INTO [ warehouse_name. ] [ schema_name. ] table_name
[ (Column_list) ]
FROM '<external_location>' [ , ...n ]
WITH
 (
 [ FILE_TYPE = { 'CSV' | 'PARQUET' } ]
 [ , CREDENTIAL = (AZURE CREDENTIAL) ]
 [ , ERRORFILE = ' [ http(s)://storageaccount/container ] /errorfile_directory [ / ] ] '
 [ , ERRORFILE_CREDENTIAL = (AZURE CREDENTIAL) ]
 [ , MAXERRORS = max_errors ]
 [ , COMPRESSION = { 'Gzip' | 'Snappy' } ]
 [ , FIELDQUOTE = 'string_delimiter' ]
 [ , FIELDTERMINATOR =  'field_terminator' ]
 [ , ROWTERMINATOR = 'row_terminator' ]
 [ , FIRSTROW = first_row ]
 [ , DATEFORMAT = 'date_format' ]
 [ , ENCODING = { 'UTF8' | 'UTF16' } ]
 [ , PARSER_VERSION = { '1.0' | '2.0' } ]
)

Argumenty

warehouse_name

Opcjonalnie, jeśli bieżący magazyn użytkownika wykonującego operację jest magazynem określonej tabeli. Jeśli nie określono magazynu, a określona schemat i tabela nie istnieją w bieżącym magazynie, funkcja COPY nie powiedzie się i zostanie zwrócony komunikat o błędzie.

schema_name

Opcjonalnie, jeśli domyślny schemat dla użytkownika wykonującego operację jest schematem określonej tabeli. Jeśli nie określono schematu, a domyślny schemat użytkownika wykonującego operację COPY różni się od schematu określonej tabeli, funkcja COPY zostanie anulowana i zostanie zwrócony komunikat o błędzie.

table_name

Nazwa tabeli do skopiowania danych. Tabela docelowa musi już istnieć w magazynie.

(column_list)

Opcjonalna lista co najmniej jednej kolumny używanej do mapowania pól danych źródłowych na kolumny tabeli docelowej na potrzeby ładowania danych.

column_list muszą być ujęte w nawiasy i rozdzielane przecinkami. Lista kolumn ma następujący format:

[(Column_name [Default_value domyślne] [Field_number] [,... n])]

• Column_name — nazwa kolumny w tabeli docelowej.
• Default_value — wartość domyślna, która zastępuje dowolną wartość NULL w pliku wejściowym. Wartość domyślna ma zastosowanie do wszystkich formatów plików. Funkcja COPY próbuje załadować wartość NULL z pliku wejściowego, gdy kolumna zostanie pominięta z listy kolumn lub gdy istnieje puste pole pliku wejściowego. Wartość domyślna jest poprzedzona słowem kluczowym "default"
• Field_number — numer pola pliku wejściowego mapowany na kolumnę docelową.
• Indeksowanie pól rozpoczyna się od 1.

Jeśli column_list nie zostanie określony, funkcja COPY mapuje kolumny na podstawie kolejności źródłowej i docelowej: pole wejściowe 1 przechodzi do kolumny docelowej 1, pole 2 przechodzi do kolumny 2 itd.

Gdy lista kolumn nie jest określona, funkcja COPY mapuje kolumny na podstawie kolejności źródłowej i docelowej: pole wejściowe 1 przechodzi do kolumny docelowej 1, pole 2 przechodzi do kolumny 2 itd.

lokalizacji zewnętrznej

Określa, gdzie są przygotowane pliki zawierające dane. Obecnie obsługiwane są usługi Azure Data Lake Storage (ADLS) Gen2 i Azure Blob Storage:

• lokalizacji zewnętrznej dla usługi Blob Storage: https://<account\>.blob.core.windows.net/<container\>/<path\>
• lokalizacji zewnętrznej dla usługi ADLS Gen2: https://<account\>.dfs.core.windows.net/<container\>/<path\>

Usługa Azure Data Lake Storage (ADLS) Gen2 oferuje lepszą wydajność niż usługa Azure Blob Storage (starsza wersja). Jeśli to możliwe, rozważ użycie konta usługi ADLS Gen2.

• konto — nazwa konta magazynu

• Container — nazwa kontenera obiektów blob

• ścieżka — folder lub ścieżka pliku dla danych. Lokalizacja rozpoczyna się od kontenera. Jeśli zostanie określony folder, funkcja COPY pobiera wszystkie pliki z folderu i wszystkich jego podfolderów. Funkcja COPY ignoruje ukryte foldery i nie zwraca plików rozpoczynających się od podkreślonego znaku (_) ani kropki (.), chyba że jawnie określono w ścieżce. To zachowanie jest takie samo, nawet w przypadku określania ścieżki z symbolem wieloznacznym.

Symbole wieloznaczne można uwzględnić w ścieżce, w której

• Dopasowanie nazwy ścieżki wieloznacznej jest uwzględniane w wielkości liter
• Symbol wieloznaczny można użyć znaku ukośnika odwrotnego (\)

Wiele lokalizacji plików można określić tylko z tego samego konta magazynu i kontenera za pośrednictwem listy rozdzielanej przecinkami, takich jak:

• https://<account>.blob.core.windows.net/<container\>/<path\>, https://<account\>.blob.core.windows.net/<container\>/<path\>

lokalizacje zewnętrzne za zaporą

Aby uzyskać dostęp do plików w usłudze Azure Data Lake Storage (ADLS) Gen2 i lokalizacjach usługi Azure Blob Storage, które znajdują się za zaporą, obowiązują następujące wymagania wstępne:

• Należy aprowizować tożsamość obszaru roboczego dla obszaru roboczego hostowanego magazyn. Aby uzyskać więcej informacji na temat konfigurowania tożsamości obszaru roboczego, zobacz Tożsamość obszaru roboczego.
• Konto Entra ID musi mieć możliwość korzystania z tożsamości obszaru roboczego.
• Konto entra ID musi mieć dostęp do plików bazowych za pośrednictwem kontroli dostępu opartej na rolach (RBAC) platformy Azure lub list ACL usługi Data Lake.
• Obszar roboczy usługi Fabric hostująca magazyn musi zostać dodany jako reguła wystąpienia zasobu . Aby uzyskać więcej informacji na temat dodawania obszaru roboczego usługi Fabric przy użyciu reguły wystąpienia zasobu, zobacz reguła wystąpienia zasobu.

FILE_TYPE = { "CSV" | "PARQUET" }

FILE_TYPE określa format danych zewnętrznych.

• CSV: określa plik wartości rozdzielonych przecinkami zgodny ze standardem RFC 4180.
• PARQUET: określa format Parquet.

CREDENTIAL (IDENTITY = '', SECRET = '')

CREDENTIAL określa mechanizm uwierzytelniania umożliwiający dostęp do zewnętrznego konta magazynu. W magazynie w usłudze Microsoft Fabric jedynymi obsługiwanymi mechanizmami uwierzytelniania są sygnatura dostępu współdzielonego (SAS) i klucz konta magazynu (SAK). Uwierzytelnianie EntraID użytkownika jest domyślne, nie trzeba określać poświadczeń.

• Uwierzytelnianie przy użyciu sygnatury dostępu współdzielonego (SAS)

  • IDENTITY: stała z wartością "Sygnatura dostępu współdzielonego"
  • SECRET: sygnatura dostępu współdzielonegozapewnia delegowany dostęp do zasobów na koncie magazynu.
  • Wymagane minimalne uprawnienia: ODCZYT i LISTA

• Uwierzytelnianie przy użyciu klucza konta magazynu

  • IDENTITY: stała z wartością "Klucz konta magazynu"
  • SECRET: klucz konta magazynu

ERRORFILE = lokalizacji katalogu

ERRORFILE dotyczy tylko pliku CSV. Określa katalog, w którym powinny zostać zapisane odrzucone wiersze i odpowiedni plik błędu. Można określić pełną ścieżkę z konta magazynu lub ścieżkę względem kontenera. Jeśli określona ścieżka nie istnieje, zostanie ona utworzona w Twoim imieniu. Zostanie utworzony katalog podrzędny o nazwie "_rejectedrows". Znak "_" gwarantuje, że katalog zostanie uniknięty dla innego przetwarzania danych, chyba że jawnie nazwany w parametrze location.

W tym katalogu istnieje folder utworzony na podstawie czasu przesłania obciążenia w formacie YearMonthDay -HourMinuteSecond (np. 20180330-173205). W tym folderze tworzony jest folder o identyfikatorze instrukcji, a w tym folderze są zapisywane dwa typy plików: błąd. Plik Json zawierający przyczyny odrzucenia i plik row.csv zawierający odrzucone wiersze.

Jeśli plik ERRORFILE ma zdefiniowaną pełną ścieżkę konta magazynu, ERRORFILE_CREDENTIAL jest używana do nawiązywania połączenia z tym magazynem. W przeciwnym razie jest używana wartość podana dla funkcji CREDENTIAL. Gdy to samo poświadczenie używane dla danych źródłowych jest używane dla pliku ERRORFILE, obowiązują również ograniczenia dotyczące ERRORFILE_CREDENTIAL.

ERRORFILE_CREDENTIAL = (IDENTITY= '', SECRET = '')

ERRORFILE_CREDENTIAL dotyczy tylko plików CSV. W magazynie w usłudze Microsoft Fabric jedynym obsługiwanym mechanizmem uwierzytelniania jest sygnatura dostępu współdzielonego (SAS).

• Uwierzytelnianie przy użyciu sygnatur dostępu współdzielonego (SAS)
  • IDENTITY: stała z wartością "Sygnatura dostępu współdzielonego"
  • SECRET: sygnatura dostępu współdzielonegozapewnia delegowany dostęp do zasobów na koncie magazynu.
  • Wymagane minimalne uprawnienia: READ, LIST, WRITE, CREATE, DELETE

MAXERRORS = max_errors

MAXERRORS określa maksymalną liczbę wierszy odrzucania dozwolonych w obciążeniu przed niepowodzeniem operacji KOPIOWANIa. Każdy wiersz, którego operacja KOPIOWANIa nie może zaimportować, jest ignorowany i liczone jako jeden błąd. Jeśli max_errors nie zostanie określona, wartość domyślna to 0.

W usłudze Microsoft Fabric MAXERRORS nie można używać, gdy FILE_TYPE jest "PARQUET".

COMPRESSION = { 'Snappy' | "GZIP" | "NONE"}

COMPRESSION jest opcjonalna i określa metodę kompresji danych dla danych zewnętrznych.

• Plik CSV obsługuje GZIP
• Parquet obsługuje GZIP i Snappy

Polecenie COPY automatycznie wykrywa typ kompresji na podstawie rozszerzenia pliku, gdy ten parametr nie jest określony:

• .gz — GZIP

Ładowanie skompresowanych plików jest obecnie obsługiwane tylko w przypadku PARSER_VERSION 1.0.

Polecenie COPY wymaga, aby pliki gzip nie zawierały żadnych końcowych elementów bezużytecznych do normalnego działania. Format gzip ściśle wymaga, aby pliki składały się z prawidłowych elementów członkowskich bez dodatkowych informacji przed, między nimi lub po nich. Każde odchylenie od tego formatu, takie jak obecność końcowych danych innych niż gzip, spowoduje niepowodzenie polecenia COPY. Upewnij się, że na końcu plików gzip nie ma żadnych końcowych elementów bezużytecznych, aby upewnić się, że funkcja COPY może pomyślnie przetworzyć te pliki.

FIELDQUOTE = "field_quote"

FIELDQUOTE dotyczy tylko woluminów CSV. Określa pojedynczy znak, który jest używany jako znak cudzysłowu (ogranicznik ciągu) w pliku CSV. Jeśli nie zostanie określony, znak cudzysłowu (") jest używany jako znak cudzysłowu zdefiniowany w standardzie RFC 4180. Notacja szesnastkowa jest również obsługiwana w przypadku funkcji FIELDQUOTE. Rozszerzone znaki ASCII i wielo bajtowe nie są obsługiwane w przypadku formatu UTF-8 dla funkcji FIELDQUOTE.

FIELDTERMINATOR = "field_terminator"

FIELDTERMINATOR dotyczy tylko woluminów CSV. Określa terminator pola używany w pliku CSV. Terminator pola można również określić przy użyciu notacji szesnastkowej. Terminator pola może być wieloznaczny. Domyślny terminator pola to (,). Rozszerzone znaki ASCII i wielo bajtowe nie są obsługiwane w przypadku protokołu UTF-8 dla funkcji FIELDTERMINATOR.

ROWTERMINATOR = 'row_terminator'

ROWTERMINATOR dotyczy tylko woluminów CSV. Określa terminator wierszy używany w pliku CSV. Terminator wierszy można określić przy użyciu notacji szesnastkowej. Terminator wierszy może być wieloznaczny. Domyślne terminatory to \r\n, \ni \r.

Polecenie COPY prefiksuje znak \r podczas określania \n (nowy wiersz), co powoduje \r\n. Aby określić tylko znak \n, użyj notacji szesnastkowej (0x0A). Podczas określania wieloznakowych terminatorów wierszy w szesnastkowym znaku nie należy określać 0x między poszczególnymi znakami.

Rozszerzone znaki ASCII i wiele bajtów nie są obsługiwane w przypadku protokołu UTF-8 dla modułu ROWTERMINATOR.

FIRSTROW = First_row_int

FIRSTROW dotyczy tylko woluminów CSV. Określa numer wiersza, który jest odczytywany jako pierwszy we wszystkich plikach dla polecenia COPY. Wartości zaczynają się od 1, czyli wartości domyślnej. Jeśli wartość jest ustawiona na dwa, pierwszy wiersz w każdym pliku (wiersz nagłówka) jest pomijany po załadowaniu danych. Wiersze są pomijane na podstawie istnienia terminatorów wierszy.

DATEFORMAT = { 'mdy' | 'dmy' | 'ymd' | 'ydm' | 'myd' | "dym" }

Format DATEFORMAT dotyczy tylko pliku CSV i określa format daty mapowania daty na formaty dat programu SQL Server. Aby zapoznać się z omówieniem wszystkich typów danych i funkcji daty i godziny Transact-SQL, zobacz Typy danych i funkcje daty i godziny (Transact-SQL). Format DATEFORMAT w poleceniu COPY ma pierwszeństwo przed DATEFORMAT skonfigurowanym na poziomie sesji.

kodowanie = "UTF8" | "UTF16"

kodowanie dotyczy tylko woluminów CSV. Wartość domyślna to UTF8. Określa standard kodowania danych dla plików załadowanych przez polecenie COPY.

PARSER_VERSION = { '1.0' | '2.0' }

PARSER_VERSION dotyczy tylko woluminów CSV. Wartość domyślna to 2.0. Określa analizator plików używany do pozyskiwania, gdy typ pliku źródłowego to CSV. Analizator 2.0 oferuje lepszą wydajność pozyskiwania plików CSV.

Analizator w wersji 2.0 ma następujące ograniczenia:

• Skompresowane pliki CSV nie są obsługiwane
• Pliki z kodowaniem UTF-16 nie są obsługiwane
• Multicharacter lub wielobajtowy MODUŁ ROWTERMINATOR, FIELDTERMINATOR lub FIELDQUOTE nie jest obsługiwany. Jednak element "\r\n" jest akceptowany jako domyślny MODUŁ ROWTERMINATOR

W przypadku korzystania z analizatora w wersji 1.0 z plikami UTF-8 terminatory wielobajtowe i wielobajtowe nie są obsługiwane w przypadku narzędzia FIELDTERMINATOR.

Analizator w wersji 1.0 jest dostępny tylko dla zgodności z poprzednimi wersjami i powinien być używany tylko wtedy, gdy te ograniczenia zostaną napotkane.

Uprawnienia

Polecenie COPY wymaga minimalnej roli współautora na poziomie obszaru roboczego lub alternatywnie rola VIEWER na poziomie obszaru roboczego oraz ADMINISTROWANIE OPERACJAMI ZBIORCZYMI BAZY DANYCH uprawnienia bazy danych i INSERT uprawnienia do obiektów tabeli.

Uwagi

Instrukcja COPY akceptuje tylko prawidłowe znaki UTF-8 i UTF-16 dla danych wierszy i parametrów polecenia. Pliki źródłowe lub parametry (takie jak TERMINATOR WIERSZy lub TERMINATOR PÓL), które używają nieprawidłowych znaków, mogą być niepoprawnie interpretowane przez instrukcję COPY i powodować nieoczekiwane wyniki, takie jak uszkodzenie danych lub inne błędy. Przed wywołania instrukcji COPY upewnij się, że pliki źródłowe i parametry są zgodne ze standardem UTF-8 lub UTF-16.

Przykłady

Aby uzyskać więcej informacji na temat używania funkcji COPY INTO w magazynie w usłudze Microsoft Fabric, zobacz Pozyskiwanie danych do magazynu przy użyciu instrukcji COPY.

A. Ładowanie z publicznego konta magazynu

Poniższy przykład to najprostsza forma polecenia COPY, które ładuje dane z konta magazynu publicznego. W tym przykładzie wartości domyślne instrukcji COPY są zgodne z formatem pliku CSV elementu wiersza.

COPY INTO dbo.[lineitem]
FROM 'https://unsecureaccount.blob.core.windows.net/customerdatasets/folder1/lineitem.csv'

Wartości domyślne polecenia COPY to:

• MAXERRORS = 0

• Domyślna kompresja jest nieskompresowana

• FIELDQUOTE = '"'

• FIELDTERMINATOR = ','

• ROWTERMINATOR = '\n'

• FIRSTROW = 1

• KODOWANIE = "UTF8"

• FILE_TYPE = "CSV"

B. Ładowanie uwierzytelniania za pośrednictwem sygnatury dostępu współdzielonego (SAS)

W poniższym przykładzie są ładowane pliki, które używają kanału informacyjnego wiersza jako terminatora wiersza, takiego jak dane wyjściowe systemu UNIX. W tym przykładzie użyto również klucza sygnatury dostępu współdzielonego do uwierzytelniania w usłudze Azure Blob Storage.

COPY INTO test_1
FROM 'https://myaccount.blob.core.windows.net/myblobcontainer/folder1/'
WITH (
    FILE_TYPE = 'CSV',
    CREDENTIAL=(IDENTITY= 'Shared Access Signature', SECRET='<Your_SAS_Token>'),
    --CREDENTIAL should look something like this:
    --CREDENTIAL=(IDENTITY= 'Shared Access Signature', SECRET='?sv=2018-03-28&ss=bfqt&srt=sco&sp=rl&st=2016-10-17T20%3A14%3A55Z&se=2021-10-18T20%3A19%3A00Z&sig=IEoOdmeYnE9%2FKiJDSHFSYsz4AkNa%2F%2BTx61FuQ%2FfKHefqoBE%3D'),
    FIELDQUOTE = '"',
    FIELDTERMINATOR = ';',
    ROWTERMINATOR = '0X0A',
    ENCODING = 'UTF8',
    MAXERRORS = 10,
    ERRORFILE = '/errorsfolder'--path starting from the storage container
)

C. Załaduj listę kolumn z wartościami domyślnymi uwierzytelnianymi za pomocą klucza konta magazynu (SAK)

W tym przykładzie są ładowane pliki określające listę kolumn z wartościami domyślnymi.

--Note when specifying the column list, input field numbers start from 1
COPY INTO test_1 (Col_one default 'myStringDefault' 1, Col_two default 1 3)
FROM 'https://myaccount.blob.core.windows.net/myblobcontainer/folder1/'
WITH (
    FILE_TYPE = 'CSV',
    CREDENTIAL=(IDENTITY= 'Storage Account Key', SECRET='<Your_account_key>'),
    --CREDENTIAL should look something like this:
    --CREDENTIAL=(IDENTITY= 'Storage Account Key', SECRET='x6RWv4It5F2msnjelv3H4DA80n0PQW0daPdw43jM0nyetx4c6CpDkdj3986DX5AHFMIf/YN4y6kkCnU8lb+Wx0Pj+6MDw=='),
    FIELDQUOTE = '"',
    FIELDTERMINATOR=',',
    ROWTERMINATOR='0x0A',
    ENCODING = 'UTF8',
    FIRSTROW = 2
)

D. Załaduj parquet

W tym przykładzie użyto symbolu wieloznakowego do załadowania wszystkich plików Parquet w folderze przy użyciu identyfikatora EntraID wykonywania użytkownika.

COPY INTO test_parquet
FROM 'https://myaccount.blob.core.windows.net/myblobcontainer/folder1/*.parquet'
WITH (
    FILE_TYPE = 'PARQUET'
)

E. Ładowanie określania symboli wieloznacznych i wielu plików

COPY INTO t1
FROM
'https://myaccount.blob.core.windows.net/myblobcontainer/folder0/*.txt',
    'https://myaccount.blob.core.windows.net/myblobcontainer/folder1'
WITH (
    FILE_TYPE = 'CSV',
    CREDENTIAL=(IDENTITY= 'Shared Access Signature', SECRET='<Your_SAS_Token>')
    FIELDTERMINATOR = '|'
)

FAQ

Jakie są wskazówki dotyczące dzielenia plików dla polecenia COPY ładujące skompresowane pliki CSV?

Rozważ podzielenie dużych plików CSV, zwłaszcza gdy liczba plików jest mała, ale zachowaj co najmniej 4 MB plików, aby uzyskać lepszą wydajność.

Jakie są wskazówki dotyczące dzielenia plików dla polecenia COPY ładujące pliki Parquet?

Rozważ podzielenie dużych plików Parquet, zwłaszcza gdy liczba plików jest mała.

Czy istnieją ograniczenia dotyczące liczby lub rozmiaru plików?

Nie ma żadnych ograniczeń dotyczących liczby lub rozmiaru plików; jednak w celu uzyskania najlepszej wydajności zalecamy pliki, które są co najmniej 4 MB.

Jaka metoda uwierzytelniania jest używana, gdy nie określam poświadczeń?

Domyślnie COPY INTRO będzie używać identyfikatora Entra wykonywanego użytkownika.

Powiązana zawartość

• pozyskiwania danych do magazynu w usłudze Microsoft Fabric
• pozyskiwania danych do magazynu przy użyciu instrukcji COPY