KOPIEREN IN (Transact-SQL)

Gilt für:Azure Synapse Analytics

• Starten Sie eine kostenlose Testversion von Fabric.
• Migration Assistant für Fabric Data Warehouse.

In diesem Artikel wird erläutert, wie Sie die COPY-Anweisung in Azure Synapse Analytics zum Laden von Daten aus externen Speicherkonten verwenden. Die Anweisung COPY bietet die größte Flexibilität für die Hochdurchsatz-Datenaufnahme in Azure Synapse Analytics.

Verwendung COPY für die folgenden Funktionen:

• Verwenden Sie weniger privilegierte Benutzer, um Daten zu laden, ohne strenge CONTROL-Berechtigungen für das Data Warehouse zu benötigen.
• Führen Sie eine einzelne T-SQL-Anweisung aus, ohne weitere Datenbankobjekte erstellen zu müssen.
• Analysieren und Laden von CSV-Dateien, bei denen Trennzeichen (Zeichenfolge, Feld, Zeile) innerhalb von durch Zeichenfolgen getrennten Spalten escapen.
• Geben Sie ein feines Berechtigungsmodell an, ohne Speicherkontoschlüssel mithilfe von Freigegebenen Zugriffssignaturen (SHARED Access Signatures, SAS) verfügbar zu machen.
• Verwenden Sie ein anderes Speicherkonto für den Standort ERRORFILE (REJECTED_ROW_LOCATION).
• Passen Sie die Standardwerte für jede Zielspalte an, und geben Sie die Quelldatenfelder an, die in bestimmte Zielspalten geladen werden sollen.
• Geben Sie für CSV-Dateien einen benutzerdefinierten Zeilenterminator, Feldterminator und Feldquote an.
• Verwenden Sie SQL Server Datumsformate für CSV-Dateien.
• Geben Sie Platzhalter und mehrere Dateien im Speicherortpfad an.
• Die automatische Schemaermittlung vereinfacht das Definieren und Zuordnen von Quelldaten in Zieltabellen.
• Der automatische Tabellenerstellungsprozess erstellt automatisch die Tabellen und funktioniert zusammen mit der automatischen Schemaermittlung.
• Laden Sie komplexe Datentypen aus Parkettdateien wie Karten und Listen direkt in Zeichenfolgenspalten, ohne andere Tools zur Vorverarbeitung der Daten zu verwenden.

Umfassende Beispiele und Schnellstarts mit der COPY Anweisung finden Sie unter:

• Schnellstart: Massenladen von Daten mit der COPY-Anweisung
• Schnellstart: Beispiele zur Verwendung der COPY-Anweisung und der unterstützten Authentifizierungsmethoden
• Schnellstart: Erstellen der COPY-Anweisung mithilfe der umfassenden Benutzeroberfläche von Synapse Studio

Syntax

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' } ]
)

Arguments

schema_name

Optional, wenn das Standardschema der Benutzer*innen, die den Vorgang ausführen, das Schema der angegebenen Tabelle ist. Wenn Sie kein Schema angeben und das Standardschema des Benutzers, der den COPY Vorgang ausführt, vom Schema der angegebenen Tabelle unterscheidet, wird der COPY Vorgang abgebrochen, und eine Fehlermeldung wird zurückgegeben.

Tabellenname

Der Name der Tabelle, in die mit COPY Daten kopiert werden sollen. Bei der Zieltabelle kann es sich um eine temporäre oder eine dauerhafte Tabelle handeln, die bereits in der Datenbank vorhanden sein muss. Geben Sie im Modus der automatischen Schemaerkennung keine Spaltenliste an.

(column_list)

Eine optionale Liste mit einer oder mehreren Spalten, mit denen Quelldatenfelder zum Laden von Daten Zieltabellenspalten zugeordnet werden.

Geben Sie im Fall von keine AUTO_CREATE_TABLE = 'ON' an.

column_list muss in Klammern eingeschlossen und durch ein Trennzeichen getrennt werden. Die Spaltenliste liegt im folgenden Format vor:

[(Spaltenname [default Standardwert] [Feldnummer] [,...n])]

• Spaltenname: Der Name der Spalte in der Zieltabelle.
• Default_value: der Standardwert, durch den alle NULL-Werte in der Eingabedatei ersetzt werden. Der Standardwert gilt für alle Dateiformate. Der COPY-Vorgang versucht, NULL aus der Eingabedatei zu laden, wenn eine Spalte aus der Spaltenliste ausgelassen wird oder ein leeres Eingabedateifeld vorhanden ist. Dem Standardwert ist das Schlüsselwort „default“ vorangestellt.
• Field_number – die Eingabedateifeldnummer, die der Zielspalte zugeordnet ist.
• Die Feldindizierung beginnt bei 1.

Wenn Sie keine Spaltenliste angeben, COPY werden Spalten basierend auf der Quell- und Zielreihenfolge zugeordnet: Das Eingabefeld 1 wird zu Zielspalte 1, Feld 2 wird zu Spalte 2 usw. zugeordnet.

Externe Standorte

Der Speicherort, an dem die Dateien, die die Daten enthalten, in die Phase verschoben werden. Derzeit werden Azure Data Lake Storage (ADLS) Gen2 und Azure Blob Storage unterstützt:

• Externer Speicherort für Blob Storage: https://<account\>.blob.core.windows.net/<container\>/<path\>
• Externer Speicherort für ADLS Gen2: https://<account\>.dfs.core.windows.net/<container\>/<path\>

• Konto: Der Speicherkontoname

• Container: Der Blobcontainername

• Pfad: Der Ordner- oder Dateipfad für die Daten. Der Speicherort beginnt im Container. Wenn Sie einen Ordner angeben, COPY werden alle Dateien aus dem Ordner und allen unterordnern abgerufen. COPY ignoriert ausgeblendete Ordner und gibt keine Dateien zurück, die mit einer Unterstreichung (_) oder einem Punkt () beginnen., sofern nicht explizit im Pfad angegeben. Dieses Verhalten gilt auch dann, wenn ein Pfad mit einem Platzhalter angegeben wird.

Sie können In den Pfad, in dem:

• Bei der Pfadnamensübereinstimmung mit dem Platzhalter wird Groß-/Kleinschreibung beachtet
• Mithilfe des umgekehrten Schrägstrichs () können Sie einem Wildcardzeichen escapen.\
• Die Platzhaltererweiterung wird rekursiv angewendet. Beispielsweise werden alle CSV-Dateien unter Customer1 (einschließlich Unterverzeichnissen von Customer1) im folgenden Beispiel geladen: Account/Container/Customer1/*.csv

Sie können mehrere Dateispeicherorte nur aus demselben Speicherkonto und Container über eine durch Kommas getrennte Liste angeben, z. B.:

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

FILE_TYPE = { 'CSV' | "PARKETT" | 'ORC' }

FILE_TYPE Gibt das Format der externen Daten an.

• CSV: Gibt eine durch Trennzeichen getrennte Wertedatei an, die mit dem RFC 4180-Standard kompatibel ist.
• PARQUET: Gibt ein Parquet-Format an.
• ORC: Gibt ein ORC-Format (ORC = Optimized Row Columnar) an.

FILE_FORMAT = external_file_format_name

FILE_FORMAT gilt nur für Parkett- und ORC-Dateien. Es gibt den Namen des externen Dateiformatobjekts an, das den Dateityp und die Komprimierungsmethode für die externen Daten speichert. Verwenden Sie zum Erstellen eines externen Dateiformats CREATE EXTERNAL FILE FORMAT.

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

CREDENTIAL Gibt den Authentifizierungsmechanismus für den Zugriff auf das externe Speicherkonto an. Authentifizierungsmethoden sind:

	CSV	Parquet	ORC
Azure Blob Storage	SAS/MSI/DIENSTPRINZIPAL/SCHLÜSSEL/Entra	SAS/KEY	SAS/KEY
Azure Data Lake Gen2	SAS/MSI/DIENSTPRINZIPAL/SCHLÜSSEL/Entra	SAS (Blob 1 )/MSI (dfs 2 )/SERVICE PRINCIPAL/KEY/Entra	SAS (Blob 1 )/MSI (dfs 2 )/SERVICE PRINCIPAL/KEY/Entra

¹ Der blob Endpunkt (.blob.core.windows.net) in Ihrem externen Standortpfad ist für diese Authentifizierungsmethode erforderlich.

² Der dfs Endpunkt (.dfs.core.windows.net) in Ihrem externen Standortpfad ist für diese Authentifizierungsmethode erforderlich.

• Authentifizieren mit Shared Access Signatures (SAS)

  • IDENTITY: Eine Konstante mit einem Wert von Shared Access Signature
  • SECRET: Die Shared Access Signature bietet delegierten Zugriff auf Ressourcen in Ihrem Speicherkonto.

• Erforderliche Mindestberechtigungen: READ und LIST

• Authentifizieren mit Dienstprinzipalen

  • IDENTITY: <ClientID>@<OAuth_2.0_Token_EndPoint>
  • SECRET: Microsoft Entra Anwendungsdienstprinzipalschlüssel

• Mindestens erforderliche RBAC-Rollen: Mitwirkender von Speicherblobdaten, Besitzer von Speicherblobdaten oder Leser von Speicherblobdaten

• Authentifizieren mit dem Speicherkontoschlüssel

  • IDENTITY: Eine Konstante mit einem Wert von Storage Account Key
  • SECRET: Speicherkontoschlüssel

• Authentifizieren mit verwalteter Identität (VNET-Dienstendpunkte)

  • IDENTITY: Eine Konstante mit einem Wert von Managed Identity

• Minimale RBAC-Rollen erforderlich: Speicher-BLOB-Datenmitwirkender oder Speicher-BLOB-Datenbesitzer für den registrierten logischen Server von Microsoft Entra in Azure. Bei Verwendung eines dedizierten SQL-Pools (früher SQL DW), der keinem Synapse-Arbeitsbereich zugeordnet ist, ist diese RBAC-Rolle nicht erforderlich, die verwaltete Identität erfordert jedoch Access Control Listenberechtigungen (List, ACL) für die Zielobjekte, um den Lesezugriff auf die Quelldateien zu ermöglichen.

• Authentifizieren mit einem Microsoft Entra-Benutzer

  • Anmeldeinformationen sind nicht erforderlich.

• Minimale RBAC-Rollen erforderlich: Speicher-BLOB-Datenmitwirkender oder Speicher-Blob-Datenbesitzer für den Microsoft Entra-Benutzer

ERRORFILE = Verzeichnisspeicherort

ERRORFILE gilt nur für CSV. Es gibt das Verzeichnis innerhalb der COPY Anweisung an, in dem die abgelehnten Zeilen und die entsprechende Fehlerdatei geschrieben werden. Sie können den vollständigen Pfad aus dem Speicherkonto oder dem Pfad relativ zum Container angeben. Wenn der angegebene Pfad nicht vorhanden ist, erstellt das Lager einen. Ein untergeordnetes Verzeichnis wird mit dem Namen _rejectedrowserstellt. Das _ Zeichen stellt sicher, dass das Verzeichnis für andere Datenverarbeitungen escaped ist, es sei denn, es wird explizit im Standortparameter benannt.

Innerhalb dieses Verzeichnisses erstellt das Lager einen Ordner basierend auf dem Zeitpunkt der Ladeübermittlung im Format YearMonthDay -HourMinuteSecond (z. B 20180330-173205. ). In diesem Ordner schreibt der Prozess zwei Dateitypen: die Ursache (Fehlerdatei) und die Datendatei (Zeilendatei). Jede Datei stellt die GUID distributionIDund die queryIDGUID der Datei voran. Da die Daten und die Ursache in getrennten Dateien gespeichert sind, haben die zugehörigen Dateien ein entsprechendes Präfix.

Wenn ERRORFILE der vollständige Pfad des Speicherkontos definiert ist, COPY wird zum Herstellen einer Verbindung mit diesem Speicher verwendet ERRORFILE_CREDENTIAL . Andernfalls wird der von Ihnen angegebene Wert verwendet CREDENTIAL. Wenn Sie die gleichen Anmeldeinformationen für die Quelldaten und ERRORFILEeinschränkungen verwenden, die ebenfalls gelten ERRORFILE_CREDENTIAL .

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

ERRORFILE_CREDENTIAL gilt nur für CSV-Dateien. Unterstützte Datenquellen und Authentifizierungsmethoden sind:

• Azure Blob Storage: SAS, Dienstprinzipal oder Microsoft Entra

• Azure Data Lake Gen2: SAS, MSI, Dienstprinzipal oder Microsoft Entra

• Authentifizieren mit Shared Access Signatures (SAS)

  • IDENTITY: Eine Konstante mit einem Wert von Shared Access Signature
  • SECRET: Die Shared Access Signature bietet delegierten Zugriff auf Ressourcen in Ihrem Speicherkonto.

• Erforderliche Mindestberechtigungen: READ, LIST, WRITE, CREATE, DELETE

• Authentifizieren mit Dienstprinzipalen

  • IDENTITY: <ClientID>@<OAuth_2.0_Token_EndPoint>
  • SECRET: Microsoft Entra Anwendungsdienstprinzipalschlüssel

• Mindestens erforderliche RBAC-Rollen: Mitwirkender von Speicherblobdaten oder Besitzer von Speicherblobdaten

• Authentifizieren mit verwalteter Identität (VNET-Dienstendpunkte)

  • IDENTITY: Eine Konstante mit einem Wert von Managed Identity

• Minimale RBAC-Rollen erforderlich: Speicher-BLOB-Datenmitwirkender oder Speicher-BLOB-Datenbesitzer für den microsoft Entra registrierten SQL-Datenbank-Server

• Authentifizieren mit einem Microsoft Entra-Benutzer

  • CREDENTIAL ist nicht erforderlich

• Minimale RBAC-Rollen erforderlich: Speicher-BLOB-Datenmitwirkender oder Speicher-Blob-Datenbesitzer für den Microsoft Entra-Benutzer

Die Verwendung eines Speicherkontoschlüssels mit ERRORFILE_CREDENTIAL diesem Schlüssel wird nicht unterstützt.

MAXERRORS = max_errors

MAXERRORS Gibt die maximale Anzahl von abgelehnten Zeilen an, die beim Laden zulässig sind, bevor der COPY-Vorgang fehlschlägt. Jede Zeile, die vom COPY-Vorgang nicht importiert werden kann, wird ignoriert und als ein Fehler gezählt. Wenn Sie keinen Wert für die maximale Anzahl von Fehlern angeben, lautet 0der Standardwert .

MAXERRORS kann nicht mit AUTO_CREATE_TABLE.

Wenn FILE_TYPE dies der Grund ist PARQUET, führen COPY INTO Ausnahmen, die durch Datentypkonvertierungsfehler verursacht werden (z. B. Binary in SQL integer), immer noch zu Einem Fehler führen, wird ignoriert MAXERRORS.

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

COMPRESSION ist optional und gibt die Datenkomprimierungsmethode für die externen Daten an.

• CSV unterstützt GZIP.
• Parkett unterstützt GZIP und Snappy.
• ORC unterstützt DefaultCodec und Snappy.
• Zlib ist die Standardkomprimierung für ORC.

Der BEFEHL COPY bestimmt den Komprimierungstyp basierend auf der Dateierweiterung automatisch, wenn Sie diesen Parameter nicht angeben:

• .gz - GZIP
• .snappy - Bissig
• .deflate - DefaultCodec (nur Parkett und ORC)

Der Befehl "KOPIEREN" erfordert, dass Gzip-Dateien keine nachgestellten Garbages enthalten, damit sie normal ausgeführt werden können. Das gzip-Format erfordert unbedingt, dass Dateien ohne zusätzliche Informationen vor, zwischen oder nach ihnen aus gültigen Membern bestehen. Jede Abweichung von diesem Format, z. B. das Vorhandensein von nachgestellten Nicht-Gzip-Daten, führt zu einem Fehler des Befehls KOPIEREN. Um sicherzustellen, dass COPY erfolgreich ausgeführt wird, stellen Sie sicher, dass am Ende der Gzip-Dateien kein nachgestellter Garbage vorhanden ist.

FIELDQUOTE = 'field_quote'

FIELDQUOTE gilt für CSV und gibt ein einzelnes Zeichen an, das als Anführungszeichen (Zeichenfolgentrennzeichen) in der CSV-Datei verwendet wird. Wenn Sie diesen Wert nicht angeben, wird das Anführungszeichen (") als Anführungszeichen verwendet, wie im RFC 4180-Standard definiert. Hexadezimalnotation wird auch für FIELDQUOTE. Erweiterte ASCII- und Multibyte-Zeichen werden mit UTF-8 für FIELDQUOTEnicht unterstützt.

FIELDTERMINATOR = 'field_terminator'

FIELDTERMINATOR gilt nur für CSV. Gibt den Feldterminator an, der in der CSV-Datei verwendet wird. Sie können den Feldterminator mithilfe der Hexadezimalnotation angeben. Der Feldterminator kann multicharacter sein. Der Standard-Feldendpunktator ist ein (,). Erweiterte ASCII- und Multibyte-Zeichen werden mit UTF-8 für FIELDTERMINATORnicht unterstützt.

ROWTERMINATOR = 'row_terminator'

ROWTERMINATOR gilt nur für CSV. Gibt den Zeilenterminator an, der in der CSV-Datei verwendet wird. Sie können den Zeilenendpunkt mithilfe der Hexadezimalnotation angeben. Der Zeilenendpunktator kann multicharacter sein. Standardmäßig ist das Zeilenabschlusszeichen „\r\n“.

Der COPY-Befehl stellt bei der Angabe von „\r“ (Zeilenumbruch) das Zeichen „\n“ (Zeilenvorschub) voran, woraus „\r\n“ resultiert. Um nur das Zeichen „\n“ anzugeben, verwenden Sie die Hexadezimalschreibweise (0x0A). Geben Sie beim Angeben von Mehrzeichenzeilenterminatoren im Hexadezimalzeichen nicht zwischen jedem Zeichen an 0x .

Erweiterte ASCII- und Multibyte-Zeichen werden mit UTF-8 für ROWTERMINATORnicht unterstützt.

FIRSTROW = First_row_int

FIRSTROW gilt für CSV und gibt die Zeilennummer an, die zuerst in allen Dateien für den Befehl KOPIEREN gelesen wird. Werte beginnen von 1, bei denen es sich um den Standardwert handelt. Wenn Sie den Wert auf 2"" festlegen, wird die erste Zeile in jeder Datei (Kopfzeile) übersprungen, wenn die Daten geladen werden. Zeilen werden basierend auf dem Vorhandensein von Zeilenabschlusszeichen übersprungen.

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

DATEFORMAT gilt nur für CSV und gibt das Datumsformat der Datumszuordnung zu SQL Server-Datumsformaten an. Eine Übersicht über alle Datums- und Uhrzeitdatentypen und zugehörigen Funktionen für Transact-SQL finden Sie unter Datums- und Uhrzeitdatentypen und zugehörige Funktionen (Transact-SQL). DATEFORMAT im COPY-Befehl hat Vorrang vor auf Sitzungsebene konfiguriertem DATEFORMAT.

ENCODING = 'UTF8' | 'UTF16'

ENCODING gilt nur für CSV. Der Standardwert ist UTF8. Gibt den Datencodierungsstandard für die Dateien an, die vom COPY-Befehl geladen werden.

IDENTITY_INSERT = 'EIN' | "AUS"

IDENTITY_INSERT Gibt an, ob der Identitätswert oder die Werte in der importierten Datendatei für die Identitätsspalte verwendet werden sollen. Wenn IDENTITY_INSERT dies der Fall ist OFF (Standard), werden die Identitätswerte für diese Spalte überprüft, aber nicht importiert. Beachten Sie das folgende Verhalten beim COPY-Befehl:

• Wenn IDENTITY_INSERT deaktiviert ist und die Tabelle über eine Identitätsspalte verfügt
  • Sie müssen eine Spaltenliste angeben, die der Identitätsspalte kein Eingabefeld zuzuordnen.
• Wenn IDENTITY_INSERT aktiviert ist, und die Tabelle über eine Identitätsspalte verfügt
  • Wenn Sie eine Spaltenliste übergeben, muss ein Eingabefeld der Identitätsspalte zugeordnet werden.
• Der Standardwert wird für die IDENTITY-Spalte in der Spaltenliste nicht unterstützt.
• Sie können jeweils nur für eine Tabelle festlegen IDENTITY_INSERT .

Azure Synapse Analytics weist automatisch eindeutige Werte zu, basierend auf dem Ausgangswert und den inkrementellen Werten, die bei der Tabellenerstellung angegeben werden.

AUTO_CREATE_TABLE = { 'ON' | 'OFF' }

AUTO_CREATE_TABLE gibt an, ob die Tabelle automatisch erstellt werden kann, indem sie zusammen mit der automatischen Schemaermittlung arbeitet. AUTO_CREATE_TABLE ist nur für Parkettdateien in Azure Synapse Analytics verfügbar.

• ON: Aktiviert die automatische Tabellenerstellung. Der COPY INTO Prozess erstellt automatisch eine neue Tabelle, indem die Struktur der zu ladenden Datei ermittelt wird. Sie können es auch mit bereits vorhandenen Tabellen verwenden, um die automatische Schemaermittlung von Parkettdateien zu nutzen.
• OFF: Die automatische Tabellenerstellung ist nicht aktiviert. Default.

Permissions

Der Benutzer, der den BEFEHL KOPIEREN ausführt, muss über die folgenden Berechtigungen verfügen:

• VERWALTEN VON MASSENVORGÄNGEN FÜR DATENBANKEN
• INSERT

Erfordert die Berechtigungen INSERT und ADMINISTER BULK OPERATIONS. In Azure Synapse Analytics sind INSERT- und ADMINISTER DATABASE BULK OPERATIONS-Berechtigungen erforderlich.

Wenn Benutzer*innen, die den COPY-Befehl ausführen, außerdem eine neue Tabelle generieren und Daten in diese laden möchten, benötigten sie die Berechtigungen CREATE TABLE und ALTER ON SCHEMA.

Verwenden Sie beispielsweise das folgende Transact-SQL-Beispiel, wenn Sie mike@contoso.com erlauben möchten, mit COPY eine neue Tabelle im Schema HR zu erstellen und die Daten aus einer Parquet-Datei einzufügen:

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

Remarks

Die Anweisung COPY akzeptiert nur gültige UTF-8- und UTF-16-Zeichen für Zeilendaten und Befehlsparameter. Die COPY Anweisung interpretiert möglicherweise nicht ordnungsgemäß Quelldateien oder Parameter (z ROWTERMINATOR . B. oder FIELDTERMINATOR), die ungültige Zeichen verwenden und unerwartete Ergebnisse wie Datenbeschädigung oder andere Fehler verursachen. Stelle sicher, dass deine Quelldateien und Parameter UTF-8- oder UTF-16-konform sind, bevor du die COPY Anweisung aufrufst.

Der MAXDOP Abfragehinweis wird von COPY INTO.

Um eine zuverlässige Ausführung sicherzustellen, ändern Sie die Quelldateien und -ordner während des COPY INTO Vorgangs nicht.

• Das Ändern, Löschen oder Ersetzen von referenzierten Dateien oder Ordnern, während der Befehl ausgeführt wird, kann dazu führen, dass der Vorgang fehlschlägt oder zu einer inkonsistenten Datenaufnahme führt.
• Überprüfen Sie vor der COPY INTOAusführung, ob alle Quelldaten stabil sind und während des Prozesses nicht geändert werden.

Wenn die Quelldaten eine höhere Genauigkeit als die Definition der Zielspalte aufweisen, wird der Wert abgeschnitten, nicht gerundet, für numerische, Datums- und Uhrzeittypen.

Examples

A. Laden aus einem öffentlichen Speicherkonto

Das folgende Beispiel zeigt die einfachste Form des COPY Befehls, mit dem Daten aus einem öffentlichen Speicherkonto geladen werden. In diesem Beispiel stimmen die Standardwerte der COPY Anweisung mit dem Format der CSV-Datei des Zeilenelements überein.

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

Die Standardwerte des COPY-Befehls lauten wie folgt:

• DATEFORMAT = Session DATEFORMAT

• MAXERRORS = 0

• COMPRESSION Standard ist unkomprimiert

• FIELDQUOTE = '"'

• FIELDTERMINATOR = ','

• ROWTERMINATOR = '\n'

• FIRSTROW = 1

• ENCODING = 'UTF8'

• FILE_TYPE = 'CSV'

• IDENTITY_INSERT = 'OFF'

B. Laden der Authentifizierung über SAS (Share Access Signature)

Im folgenden Beispiel werden Dateien geladen, die den Zeilenvorschub als Zeilenendpunkt verwenden, z. B. eine UNIX-Ausgabe. In diesem Beispiel wird zur Authentifizierung bei Azure Blob Storage auch ein SAS-Schlüssel verwendet.

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. Laden mit einer Spaltenliste mit Standardwerten zur Authentifizierung über den Speicherkontoschlüssel

In diesem Beispiel werden Dateien mit Angabe einer Spaltenliste mit Standardwerten geladen.

--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>'),
    FIELDQUOTE = '"',
    FIELDTERMINATOR=',',
    ROWTERMINATOR='0x0A',
    ENCODING = 'UTF8',
    FIRSTROW = 2
)

D. Laden von Parquet oder ORC mithilfe eines vorhandenen Dateiformatobjekts

In diesem Beispiel wird ein Platzhalter verwendet, um alle Parquet-Dateien in einem Ordner zu laden.

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. Laden mit Angabe von Platzhaltern und mehreren Dateien

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. Laden mit MSI-Anmeldeinformationen

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. Laden mit automatischer Schemaerkennung

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

Wie wird die Leistung des BEFEHLS KOPIEREN mit PolyBase verglichen?

Die Leistung des Befehls KOPIEREN kann je nach Workload besser sein.

• Das Lager kann komprimierte Dateien nicht automatisch aufteilen. Um eine optimale Ladeleistung zu erzielen, sollten Sie die Eingabe in mehrere Dateien aufteilen, wenn komprimierte CSVs geladen werden.

• Das Lager kann große unkomprimierte CSV-Dateien automatisch für das parallele Laden aufteilen, sodass Sie in der Regel keine nicht komprimierten CSV-Dateien manuell teilen müssen. In bestimmten Fällen, in denen die automatische Dateiteilung aufgrund von Datenmerkmalen nicht machbar ist, kann das manuelle Aufteilen großer CSVs weiterhin von der Leistung profitieren.

Welche Anweisungen gibt es zur Dateiaufteilung für den COPY-Befehl beim Laden von komprimierten CSV-Dateien?

In der folgenden Tabelle wird die Anzahl der Dateien beschrieben, die Sie verwenden sollten. Wenn Sie die empfohlene Anzahl von Dateien erreichen, erhalten Sie eine bessere Leistung mit größeren Dateien. Die Anzahl der Dateien wird durch die Anzahl der berechneten Knoten multipliziert mit 60 bestimmt. Bei 6000 DWU verfügen Sie beispielsweise über 12 Computeknoten, sodass Sie 12 * 60 = 720 Partitionen haben. Eine einfache Dateiteilungserfahrung finden Sie unter Maximieren des KOPIERlastdurchsatzes mit Dateiaufteilungen.

DWU	Anzahl von Dateien
100	60
200	60
300	60
400	60
500	60
1,000	120
1,500	180
2,000	240
2,500	300
3,000	360
5,000	600
6,000	720
7,500	900
10,000	1200
15,000	1800
30,000	3600

Welche Anweisungen gibt es zur Dateiaufteilung für den COPY-Befehl beim Laden von Parquet- oder ORC-Dateien?

Sie müssen keine Parkett- und ORC-Dateien aufteilen, da der Befehl KOPIEREN automatisch Dateien aufteilt. Für optimale Leistung sollten Parkett- und ORC-Dateien im Azure Speicherkonto 256 MB oder größer sein.

Gibt es Einschränkungen hinsichtlich der Anzahl oder Größe von Dateien?

Es gibt keine Einschränkungen für die Anzahl oder Größe von Dateien. Verwenden Sie jedoch für optimale Leistung Dateien mit mindestens 4 MB. Beschränken Sie außerdem die Anzahl der Quelldateien auf maximal 5.000 Dateien, um eine bessere Leistung zu erzielen.

Gibt es bekannte Probleme bei der COPY-Anweisung?

Wenn Sie einen Azure Synapse Arbeitsbereich haben, den Sie vor dem 7. Dezember 2020 erstellt haben, tritt bei der Authentifizierung mit verwalteter Identität möglicherweise eine ähnliche Fehlermeldung auf: com.microsoft.sqlserver.jdbc.SQLServerException: Managed Service Identity isn't enabled on this server. Please enable Managed Service Identity and try again.

Um dieses Problem zu umgehen, registrieren Sie die verwaltete Identität des Arbeitsbereichs erneut:

1. Installieren Sie Azure PowerShell. Siehe Installieren von PowerShell.
2. Registrieren Sie die verwaltete Identität Ihres Arbeitsbereichs mithilfe von PowerShell:

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

Verwandte Inhalte

• Übersicht über das Laden mit Azure Synapse Analytics

Gilt für:Warehouse in Microsoft Fabric

In diesem Artikel wird erläutert, wie Sie die COPY-Anweisung in Warehouse in Microsoft Fabric zum Laden von externen Speicherkonten verwenden. Die COPY-Anweisung bietet die größte Flexibilität für die Erfassung von Daten mit hohem Durchsatz in Ihrem Warehouse in Microsoft Fabric und ist als Strategie für Ingest-Daten in Ihrem Warehouse in Microsoft Fabric.

In Fabric Data Warehouse unterstützt die COPY-Anweisung derzeit CSV-, JSONL- und LAMINAT-Dateiformate. Bei Datenquellen werden Azure Data Lake Storage Gen2 Konten und OneLake-Quellen unterstützt.

Weitere Informationen zur Verwendung COPY INTO in Ihrem Warehouse in Microsoft Fabric finden Sie unter "Erfassen von Daten in Ihrem Warehouse in Microsoft Fabric mithilfe der COPY-Anweisung".

Standardmäßig authentifiziert sich COPY INTO als ausgeführter Microsoft Entra ID Benutzer.

Verwendung COPY für die folgenden Funktionen:

• Verwenden Sie weniger privilegierte Benutzer, um Daten zu laden, ohne strenge CONTROL-Berechtigungen für das Lager zu benötigen.
• Führen Sie eine einzelne T-SQL-Anweisung aus, ohne weitere Datenbankobjekte erstellen zu müssen.
• Sie können CSV-Dateien, bei denen Trennzeichen (Zeichenfolge, Feld, Zeile) in durch Trennzeichen getrennten Spalten mit Escapezeichen versehen sind, ordnungsgemäß laden.
• Analysieren und laden Sie JSONL-Dateien ordnungsgemäß, wobei jede Zeile ein gültiges JSON-Objekt ist und Felder mithilfe von JSON-Pfadausdrücken zugeordnet werden.
• Geben Sie ein feines Berechtigungsmodell an, ohne Speicherkontoschlüssel mithilfe von Freigegebenen Zugriffssignaturen (SHARED Access Signatures, SAS) verfügbar zu machen.
• Verwenden Sie ein anderes Speicherkonto für den Standort ERRORFILE (REJECTED_ROW_LOCATION).
• Passen Sie die Standardwerte für jede Zielspalte an, und geben Sie die Quelldatenfelder an, die in bestimmte Zielspalten geladen werden sollen.
• Geben Sie für CSV-Dateien einen benutzerdefinierten Zeilenterminator, Feldterminator und Feldquote an.
• Geben Sie Platzhalter und mehrere Dateien im Speicherortpfad an.
• Weitere Informationen zu Datenaufnahmeoptionen und bewährten Methoden finden Sie unter "Ingest data into your Warehouse in Microsoft Fabric" mithilfe der COPY-Anweisung.

Syntax

COPY INTO [ warehouse_name. ] [ schema_name. ] table_name
[ (Column_list) ]
FROM '<external_location>' [ , ...n ]
WITH
 (
 [ FILE_TYPE = { 'CSV' | 'JSONL' | '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' } ]
 [ , MATCH_COLUMN_COUNT = { 'ON' | 'OFF' } ]
)

Arguments

warehouse_name

Optional, wenn das aktuelle Warehouse für die Benutzer*innen, die den Vorgang ausführen, das Warehouse der angegebenen Tabelle ist. Wenn Sie kein Lager angeben und das angegebene Schema und die angegebene Tabelle im aktuellen Lager nicht vorhanden sind, schlägt ein Fehler fehl, COPY und es wird eine Fehlermeldung zurückgegeben.

schema_name

Optional, wenn das Standardschema der Benutzer*innen, die den Vorgang ausführen, das Schema der angegebenen Tabelle ist. Wenn Sie kein Schema angeben und das Standardschema des Benutzers, der den COPY Vorgang ausführt, vom Schema der angegebenen Tabelle abweicht, COPY wird abgebrochen, und eine Fehlermeldung wird zurückgegeben.

Tabellenname

Der Name der Tabelle, in die man Daten aufnehmen kann COPY . Die Zieltabelle muss bereits im Warehouse vorhanden sein.

(column_list)

Eine optionale Liste von Spalten, die zum Zuordnen von Quelldatenfeldern zu Zieltabellenspalten während des Datenladevorgangs verwendet werden.

column_list muss in Klammern eingeschlossen und durch ein Trennzeichen getrennt werden. Die Syntax lautet:

[(Column_name [Standard-Default_value] [Field_number | JSON_path] [,... n])]

• Spaltenname: Der Name der Spalte in der Zieltabelle.
• Default_value – der Standardwert, der jeden NULL Wert in der Eingabedatei ersetzt. Der Standardwert gilt für alle Dateiformate. COPY versucht, aus der Eingabedatei zu laden NULL , wenn eine Spalte aus der Spaltenliste weggelassen wird oder wenn ein Eingabedateifeld leer ist. Dem Standardwert wird das Schlüsselwort „default“ vorangestellt.
• Field_number – Gilt nur für CSV-Dateien. Gibt die Ordnungsposition des Felds in den Eingabedaten an. Die Feldindizierung beginnt bei 1.
• JSON_path – Gilt nur für JSONL-Dateien. Gibt einen JSON-Pfadausdruck an, der das Feld identifiziert, das aus jedem JSON-Objekt extrahiert werden soll (z. B $.CustomerName. ).

Wenn Sie keine column_list angeben, COPY werden Spalten basierend auf der Quell- und Zielreihenfolge zugeordnet: Das Eingabefeld 1 wird zu Zielspalte 1, Feld 2 wird zu Spalte 2 usw. zugeordnet.

Wenn Sie keine Spaltenliste angeben, COPY werden Spalten basierend auf der Quell- und Zielreihenfolge zugeordnet: Das Eingabefeld 1 wird zu Zielspalte 1, Feld 2 wird zu Spalte 2 usw. zugeordnet.

Externer Speicherort

Gibt an, wo die Dateien, die die Daten enthalten, mehrstufige Daten enthalten. Derzeit werden Azure Data Lake Storage (ADLS) Gen2, Azure Blob Storage und OneLake unterstützt:

• Externer Speicherort für Blob Storage: https://<account\>.blob.core.windows.net/<container\>/<path\>
• Externer Speicherort für ADLS Gen2: https://<account\>.dfs.core.windows.net/<container\>/<path\>
• Externer Speicherort für OneLake: https://onelake.dfs.fabric.microsoft.com/<workspaceId>/<lakehouseId>/Files/

Azure Data Lake Storage Gen2 (ADLS) bietet eine bessere Leistung als Azure Blob Storage (Legacy). Ziehen Sie nach Möglichkeit die Verwendung eines ADLS Gen2-Kontos in Betracht.

• Konto: Der Speicherkontoname

• Container: Der Blobcontainername

• Pfad: Der Ordner- oder Dateipfad für die Daten. Der Speicherort beginnt im Container. Wenn Sie einen Ordner angeben, COPY werden alle Dateien aus dem Ordner und allen unterordnern abgerufen. COPY ignoriert ausgeblendete Ordner und gibt keine Dateien zurück, die mit einer Unterstreichung (_) oder einem Punkt () beginnen., sofern nicht explizit im Pfad angegeben. Dieses Verhalten gilt auch dann, wenn ein Pfad mit einem Platzhalter angegeben wird.

Platzhalter können im Pfad enthalten sein, wobei Folgendes gilt:

• Bei der Pfadnamensübereinstimmung mit dem Platzhalter wird Groß-/Kleinschreibung beachtet
• Mithilfe des umgekehrten Schrägstrichs () können Sie einem Wildcardzeichen escapen.\

Sie können mehrere Dateispeicherorte nur aus demselben Speicherkonto und Container über eine durch Kommas getrennte Liste angeben, z. B.:

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

Externe Speicherorte hinter der Firewall

Um auf Dateien in Azure Data Lake Storage (ADLS) Gen2- und Azure Blob Storage-Speicherorten zuzugreifen, die sich hinter einer Firewall befinden, gelten die folgenden Voraussetzungen:

• Eine Arbeitsbereichsidentität für den Arbeitsbereich, in dem Ihr Lager gehostet wird, muss bereitgestellt werden. Weitere Informationen zum Einrichten einer Arbeitsbereichsidentität finden Sie unter Arbeitsbereichsidentität.
• Ihr Entra-ID-Konto muss in der Lage sein, die Arbeitsbereichsidentität zu verwenden.
• Ihr Entra-ID-Konto muss Über azure role-based access control (RBAC) oder Data Lake ACLs Zugriff auf die zugrunde liegenden Dateien haben.
• Ihr Fabric-Arbeitsbereich, in dem das Lager gehostet wird, muss als Ressourceninstanzregel hinzugefügt werden. Weitere Informationen zum Hinzufügen des Fabric-Arbeitsbereichs mit einer Ressourceninstanzregel finden Sie in der Ressourceninstanzregel.

FILE_TYPE = { 'CSV' | 'JSONL' | 'PARKETT' }

FILE_TYPE Gibt das Format der externen Daten an.

• CSV: Gibt eine durch Trennzeichen getrennte Wertedatei an, die mit dem RFC 4180-Standard kompatibel ist.
• JSONL: Gibt eine JSON-Datei (newline-delimited JSON Lines) an, wobei jede Zeile ein gültiges JSON-Objekt ist.
• PARQUET: Gibt ein Parquet-Format an.

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

CREDENTIAL Gibt den Authentifizierungsmechanismus für den Zugriff auf das externe Speicherkonto an.

Im Fabric Data Warehouse:

• COPY INTO wird nicht unterstützt, wenn der öffentliche Zugriff deaktiviert ist.
• Für öffentliche Speicherkonten sind die unterstützten Authentifizierungsmechanismen Microsoft Entra ID, Shared Access Signature (SAS) oder Storage Account Key (SAK).
• Für öffentliche Speicherkonten hinter einer Firewall ist die Microsoft Entra ID-Authentifizierung die einzige unterstützte Authentifizierungsmethode. COPY INTO Die Verwendung von OneLake als Quelle unterstützt nur die EntraID-Authentifizierung.

Die Microsoft Entra ID Authentifizierung des Benutzers ist standard. Es müssen keine Anmeldeinformationen angegeben werden.

• Authentifizieren mit freigegebener Zugriffssignatur (SAS)
  • IDENTITY: Eine Konstante mit einem Wert von Shared Access Signature.
  • SECRET: Die Shared Access Signature bietet delegierten Zugriff auf Ressourcen in Ihrem Speicherkonto.
  • Erforderliche Mindestberechtigungen: READ und LIST.
• Authentifizieren mit Speicherkontoschlüssel
  • IDENTITY: Eine Konstante mit einem Wert von Storage Account Key.
  • SECRET: Schlüssel für das Speicherkonto.

ERRORFILE = Verzeichnisspeicherort

ERRORFILE gilt für CSV und JSONL. Gibt das Verzeichnis an, in das die abgelehnten Zeilen und die entsprechende Fehlerdatei geschrieben werden sollen. Sie können den vollständigen Pfad aus dem Speicherkonto oder dem Pfad relativ zum Container angeben. Wenn der angegebene Pfad nicht vorhanden ist, erstellt das System einen in Ihrem Auftrag. Ein untergeordnetes Verzeichnis wird mit dem Namen _rejectedrowserstellt. Das _ Zeichen stellt sicher, dass das Verzeichnis für andere Datenverarbeitungen escaped ist, es sei denn, es wird explizit im Standortparameter benannt.

Innerhalb dieses Verzeichnisses erstellt das Lager einen Ordner basierend auf dem Zeitpunkt der Ladeübermittlung im Format YearMonthDay -HourMinuteSecond (z. B 20180330-173205. ). In diesem Ordner erstellt das Lager einen Ordner mit der Anweisungs-ID, und unter diesem Ordner werden zwei Dateitypen geschrieben: ein Fehler. Json-Datei mit den Ablehnungsgründen und einer row.csv Datei, die die abgelehnten Zeilen enthält.

Wenn ERRORFILE der vollständige Pfad des Speicherkontos definiert ist, wird die ERRORFILE_CREDENTIAL Verbindung zu diesem Speicher verwendet. Andernfalls wird der für CREDENTIAL sie genannte Wert verwendet. Wenn die gleichen Anmeldeinformationen, die für die Quelldaten verwendet werden, verwendet ERRORFILEwerden, gelten ERRORFILE_CREDENTIAL auch Einschränkungen.

Bei Verwendung eines firewallgeschützten Azure Storage-Kontos wird die Fehlerdatei im gleichen Container erstellt, der im Pfad des Speicherkontos angegeben ist. Bei der Verwendung der ERRORFILE Option in diesem Szenario ist es auch erforderlich, den MAXERROR Parameter anzugeben. Wenn ERRORFILE der vollständige Pfad des Speicherkontos definiert ist, wird die ERRORFILE_CREDENTIAL Verbindung zu diesem Speicher verwendet. Andernfalls wird der für CREDENTIAL sie genannte Wert verwendet.

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

ERRORFILE_CREDENTIAL gilt für CSV- und JSONL-Dateien. In Warehouse in Microsoft Fabric ist Shared Access Signature (SAS) der einzige unterstützte Authentifizierungsmechanismus.

• Authentifizieren mit Freigegebenen Zugriffssignaturen (SAS)
  • IDENTITY: Eine Konstante mit einem Wert von Shared Access Signature
  • SECRET: Die Shared Access Signature bietet delegierten Zugriff auf Ressourcen in Ihrem Speicherkonto.
• Erforderliche Mindestberechtigungen: READ, LIST, WRITE, CREATE, DELETE

MAXERRORS = max_errors

MAXERRORS gilt für CSV und JSONL. Gibt die maximale Anzahl an abgelehnten Zeilen an, die beim Laden zulässig sind, bevor der COPY Vorgang fehlschlägt. Jede Zeile, die die Operation COPY nicht importieren kann, wird ignoriert und als ein Fehler gezählt. Wenn Sie keine maximale Anzahl von Fehlern angeben, ist 0die Standardeinstellung .

In Fabric Data Warehouse können Sie MAXERRORS nicht verwenden, wenn FILE_TYPEPARQUET ist.

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

COMPRESSION ist optional und gibt die Datenkomprimierungsmethode für die externen Daten an.

• CSV unterstützt GZIP.
• Parkett unterstützt GZIP und Snappy.
• Für JSONL nicht unterstützt

Der COPY Befehl erkennt den Kompressionstyp automatisch basierend auf der Dateiendung, wenn dieser Parameter nicht angegeben ist:

• .gz - GZIP

Das Laden komprimierter Dateien wird derzeit nur mit parser Version 1.0 unterstützt.

Der COPY Befehl erfordert, dass Gzip-Dateien keinen nachfolgenden Garbage enthalten, um normal zu funktionieren. Das gzip-Format erfordert unbedingt, dass Dateien ohne zusätzliche Informationen vor, zwischen oder nach ihnen aus gültigen Membern bestehen. Jede Abweichung von diesem Format, z. B. das Vorhandensein von nachgestellten Nicht-Gzip-Daten, führt zu einem Fehler des COPY Befehls. Um sicherzustellen, dass COPY die Ausführung erfolgreich ausgeführt wird, stellen Sie sicher, dass am Ende der Gzip-Dateien kein nachgestellter Garbage vorhanden ist.

FIELDQUOTE = 'field_quote'

FIELDQUOTE gilt nur für CSV. Gibt ein einzelnes Zeichen an, das in der CSV-Datei als Anführungszeichen (Zeichenfolgen-Trennzeichen) verwendet wird. Wenn Sie nicht angeben FIELDQUOTE, wird das Anführungszeichen (") als Anführungszeichen verwendet, wie im RFC 4180-Standard definiert. Hexadezimalnotation wird auch für FIELDQUOTE. Erweiterte ASCII- und Multibyte-Zeichen werden mit UTF-8 für FIELDQUOTEnicht unterstützt.

FIELDTERMINATOR = 'field_terminator'

FIELDTERMINATOR gilt nur für CSV. Gibt das Feldabschlusszeichen an, das in der CSV-Datei verwendet wird. Sie können den Feldterminator auch mit hexadezimaler Schreibweise angeben. Der Feldterminator kann multicharacter sein. Das Standard-Feldabschlusszeichen ist ein (,). Erweiterte ASCII- und Multibyte-Zeichen werden mit UTF-8 für FIELDTERMINATOR nicht unterstützt.

ROWTERMINATOR = 'row_terminator'

ROWTERMINATOR gilt nur für CSV. Gibt das Zeilenabschlusszeichen an, das in der CSV-Datei verwendet wird. Sie können den Zeilenendpunkt mit hexadezimaler Schreibweise angeben. Der Zeilenendpunktator kann multicharacter sein. Die Standardterminatoren sind \r\n, \nund \r.

Der COPY Befehl setzt das Zeichen vor das \r Zeichen, wenn \n (Zeilenumschreibung) angegeben wird, was zu resultiert.\r\n Um nur das Zeichen „\n“ anzugeben, verwenden Sie die Hexadezimalschreibweise (0x0A). Geben Sie beim Angeben von Mehrzeichenzeilenterminatoren in hexadezimaler Zeilen nicht 0x zwischen jedem Zeichen an.

Erweiterte ASCII- und Multibyte-Zeichen werden mit UTF-8 für ROWTERMINATORnicht unterstützt.

FIRSTROW = First_row_int

FIRSTROW gilt nur für CSV. Gibt die Zeilennummer an, die in allen Dateien für den COPY Befehl zuerst gelesen wird. Werte beginnen von 1, bei denen es sich um den Standardwert handelt. Wenn Sie den Wert auf 2"" festlegen, wird die erste Zeile in jeder Datei (Kopfzeile) übersprungen, wenn die Daten geladen werden. Zeilen werden basierend auf dem Vorhandensein von Zeilenabschlusszeichen übersprungen.

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

DATEFORMAT gilt für CSV und JSONL. Gibt das Datumsformat der Datumszuordnung zu SQL Server Datumsformaten an. Eine Übersicht über alle Datums- und Uhrzeitdatentypen und zugehörigen Funktionen für Transact-SQL finden Sie unter Datums- und Uhrzeitdatentypen und zugehörige Funktionen (Transact-SQL). DATEFORMAT innerhalb des COPY Befehls hat Vorrang gegenüber DATEFORMAT, das auf Sitzungsebene konfiguriert ist.

ENCODING = 'UTF8' | 'UTF16'

ENCODING gilt für CSV und JSONL. Der Standardwert ist UTF8. Spezifiziert den Datenkodierungsstandard für die vom Befehl COPY geladenen Dateien.

PARSER_VERSION = { '1.0' | '2.0' }

PARSER_VERSION gilt nur für CSV-Dateien. Der Standardwert ist 2,0. PARSER_VERSION Gibt den Dateiparser an, der für die Aufnahme verwendet wird, wenn der Quelldateityp CSV ist. Der 2.0-Parser bietet eine verbesserte Leistung für die Aufnahme von CSV-Dateien.

Parser Version 2.0 hat die folgenden Einschränkungen:

• Komprimierte CSV-Dateien werden nicht unterstützt.
• Dateien mit UTF-16-Codierung werden nicht unterstützt.
• Multicharacter oder Multibyte ROWTERMINATOR, FIELDTERMINATORoder FIELDQUOTE wird nicht unterstützt. Wird jedoch \r\n als Standard ROWTERMINATORakzeptiert.

Wenn Sie parser Version 1.0 mit UTF-8-Dateien verwenden, werden Multibyte- und Multicharacter-Terminatoren für FIELDTERMINATOR.

Die Parserversion 1.0 ist nur aus Gründen der Abwärtskompatibilität verfügbar. Verwenden Sie sie nur, wenn Sie auf diese Einschränkungen stoßen.

MATCH_COLUMN_COUNT = { 'AN' | 'OFF' }

MATCH_COLUMN_COUNT gilt nur für CSV-Dateien. Der Standardwert ist OFF. Es gibt an, ob der COPY Befehl überprüfen soll, ob die Spaltenanzahlzeilen in Quelldateien mit der Spaltenanzahl der Zieltabelle übereinstimmen. Das folgende Verhalten gilt:

• Wenn MATCH_COLUMN_COUNT lautet OFF:
  • Der Befehl ignoriert die Überschreitung von Spalten aus Quellzeilen.
    • Der Befehl fügt NULL Werte in Nullwerte für Zeilen mit weniger Spalten ein.
  • Wenn ein Wert nicht für eine nicht nullable Spalte bereitgestellt wird, schlägt der COPY Befehl fehl.
• Wenn MATCH_COLUMN_COUNT lautet ON:
  • Der COPY Befehl prüft, ob die Spaltenanzahl in jeder Zeile jeder Datei aus der Quelle mit der Spaltenzahl der Zieltabelle übereinstimmt.
• Wenn eine Spaltenanzahl nicht übereinstimmen kann, schlägt der COPY Befehl fehl.

Verwenden von COPY INTO mit OneLake

Verwenden Sie COPY INTO, um Daten direkt aus Dateien zu laden, die im Fabric OneLake gespeichert sind, unter vorhandenen Elementen. Diese Methode beseitigt die Notwendigkeit externer Stagingkonten, z. B. ADLS Gen2 oder Blob Storage, und ermöglicht die arbeitsbereichsgesteuerte SaaS-native Aufnahme mithilfe von Fabric Berechtigungen. Diese Funktionalität unterstützt Folgendes:

• Lesen von beliebigen Speicherorten innerhalb eines Arbeitsbereichs und eines Elements
• Arbeitsbereich-zu-Lager-Lasten innerhalb desselben Mandanten
• Erzwingen der nativen Identität mithilfe von Microsoft Entra ID

Example:

COPY INTO t1
FROM 'https://onelake.dfs.fabric.microsoft.com/<workspaceId>/<lakehouseId>/Files/*.csv'
WITH (
    FILE_TYPE = 'CSV',
    FIRSTROW = 2
);

Permissions

Steuern von Flugzeugberechtigungen

Um den COPY INTO Befehl auszuführen, müssen Sie einer Arbeitsbereichsrolle über " Zugriff verwalten" im Arbeitsbereich mit mindestens der Viewer-Rolle mitgliedschaften. Alternativ können Sie den Lagerzugriff für einen Benutzer über Item-Berechtigungen im Fabric-Portal mit mindestens Leseberechtigungen freigeben. Um das Prinzip der geringsten Rechte auszurichten, reicht Lesen-Berechtigung aus.

Berechtigungen für Datenebene

Nachdem Sie Berechtigungen für die Steuerungsebene über Arbeitsbereichsrollen oder Elementberechtigungen erteilt haben, erteilen Sie dem Benutzer INSERTADMINISTER DATABASE BULK OPERATIONS mithilfe von T-SQL-Befehlen auch Leseberechtigungen auf Ebene der Datenebene.

Beispielsweise gewährt das folgende T-SQL-Skript diesen Berechtigungen einem einzelnen Benutzer mithilfe seiner Microsoft Entra ID.

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

GRANT INSERT to [mike@contoso.com];
GO

Wenn Sie die Fehlerdateioption verwenden, muss der Benutzer über die minimale Berechtigung Blob Storage Mitwirkenden im Container "Speicherkonto" verfügen.

Wenn Sie OneLake als Quelle verwenden, muss der Benutzer sowohl für den Quellarbeitsbereich (in dem sich das Lakehouse befindet) als auch den Zielarbeitsbereich (in dem sich das Lager befindet) über Mitwirkende oder höhere Berechtigungen verfügen. Microsoft Entra ID- und Fabric-Arbeitsbereichsrollen steuern den gesamten Zugriff.

Remarks

Die Anweisung COPY akzeptiert nur gültige UTF-8- und UTF-16-Zeichen für Zeilendaten und Befehlsparameter. Wenn Sie Quelldateien oder Parameter (z ROWTERMINATOR . B. oder FIELDTERMINATOR) verwenden, die ungültige Zeichen enthalten, kann die COPY Anweisung sie falsch interpretieren und unerwartete Ergebnisse verursachen, z. B. Datenbeschädigung oder andere Fehler. Stellen Sie vor dem Aufrufen der COPY Anweisung sicher, dass Die Quelldateien und -parameter UTF-8- oder UTF-16-kompatibel sind.

Die COPY INTO Anweisung hat Einschränkungen für die Größe einzelner varchar(max) und varbinary(max) -Spalten sowie für die Gesamtzeilengröße, die Sie aufnehmen können.

• Parkett: maximale Varchar(max)/varbinary(max) Spaltengröße 16 MB, max. Zeilengröße 1 GB.
• CSV und JSONL: maximale Varchar(max)/varbinary(max) Spaltengröße 1 MB, max. Zeilengröße 16 MB.

Um eine zuverlässige Ausführung sicherzustellen, ändern Sie die Quelldateien und -ordner während des COPY INTO Vorgangs nicht.

• Das Ändern, Löschen oder Ersetzen von referenzierten Dateien oder Ordnern, während der Befehl ausgeführt wird, kann dazu führen, dass der Vorgang fehlschlägt oder zu einer inkonsistenten Datenaufnahme führt.
• Stellen Sie vor der Ausführung COPY INTOsicher, dass alle Quelldaten stabil sind und während des Prozesses nicht geändert werden.

Wenn die Quelldaten eine höhere Genauigkeit als die Definition der Zielspalte aufweisen, wird der Wert abgeschnitten, nicht gerundet, für numerische, Datums- und Uhrzeittypen.

Einschränkungen für OneLake als Quelle

• Es wird nur die Microsoft Entra ID-Authentifizierung unterstützt. Andere Authentifizierungsmethoden wie SAS-Token, freigegebene Schlüssel oder Verbindungszeichenfolgen sind nicht zulässig.

• Lagerelemente werden nicht als Quellspeicherorte unterstützt. Dateien müssen aus anderen Fabric-Elementen stammen, die Dateien über oneLake-Speicher verfügbar machen.

• OneLake-Pfade müssen Arbeitsbereichs- und Lager-IDs verwenden. Anzeigenamen für Arbeitsbereiche oder Lakehouses werden derzeit nicht unterstützt.

• Für beide Arbeitsbereiche sind Mitwirkendeberechtigungen erforderlich. Der ausführende Benutzer muss mindestens über die Rolle "Mitwirkender" im Quellarbeitsbereich lakehouse und im Ziellagerarbeitsbereich verfügen.

Examples

Weitere Informationen zur Verwendung COPY INTO in Ihrem Warehouse in Microsoft Fabric finden Sie unter "Erfassen von Daten in Ihrem Warehouse in Microsoft Fabric mithilfe der COPY-Anweisung".

A. Laden aus einem öffentlichen Speicherkonto

Das folgende Beispiel zeigt die einfachste Form des COPY Befehls, mit dem Daten aus einem öffentlichen Speicherkonto geladen werden. In diesem Beispiel stimmen die Standardwerte der COPY Anweisung mit dem Format der CSV-Datei des Zeilenelements überein.

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

Die Standardwerte des Befehls COPY sind:

• MAXERRORS = 0

• COMPRESSION (Standardwert ist nicht komprimiert)

• FIELDQUOTE = '"'

• FIELDTERMINATOR = ','

• ROWTERMINATOR = '\n'

  Important

  COPY behandelt \n es als \r\n intern. Weitere Informationen finden Sie im Abschnitt ROWTERMINATOR.

• FIRSTROW = 1

• ENCODING = 'UTF8'

• FILE_TYPE = 'CSV'

B. Laden der Authentifizierung über SAS (Share Access Signature)

Im folgenden Beispiel werden Dateien geladen, die den Zeilenvorschub als Zeilenendpunkt verwenden, z. B. eine UNIX-Ausgabe. In diesem Beispiel wird zur Authentifizierung bei Azure Blob Storage auch ein SAS-Schlüssel verwendet.

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>'),
    FIELDQUOTE = '"',
    FIELDTERMINATOR = ';',
    ROWTERMINATOR = '0X0A',
    ENCODING = 'UTF8',
    MAXERRORS = 10,
    ERRORFILE = '/errorsfolder'--path starting from the storage container
)

C. Laden mit einer Spaltenliste mit Standardwerten zur Authentifizierung über einen Speicherkontoschlüssel (Storage Account Key, SAK)

In diesem Beispiel werden Dateien mit Angabe einer Spaltenliste mit Standardwerten geladen.

--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>'),
    FIELDQUOTE = '"',
    FIELDTERMINATOR=',',
    ROWTERMINATOR='0x0A',
    ENCODING = 'UTF8',
    FIRSTROW = 2
)

D. Ladeparkett

In diesem Beispiel wird ein Wildcard verwendet, um alle Parkettdateien unter einem Ordner zu laden, indem die Entra ID des ausgeführten Benutzers verwendet wird.

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

E. JSONL laden

In diesem Beispiel wird ein Wildcard verwendet, um alle JSONL-Dateien unter einem Ordner mithilfe der Entra ID des ausgeführten Benutzers zu laden.

COPY INTO test_jsonl
FROM 'https://myaccount.blob.core.windows.net/myblobcontainer/folder1/*.jsonl'
WITH (
    FILE_TYPE = 'JSONL'
)

F. Zuordnen von Spaltennamen zu Feldpfaden in JSONL-Dokumenten

Das folgende Beispiel zeigt eine JSON Lines (JSONL)-Datei, wobei jede Zeile ein einzelnes JSON-Objekt darstellt:

{"CountryKey": 0, "CountryName": "ALGERIA", "RegionID": 0, "Population": 34800000}
{"CountryKey": 1, "CountryName": "ARGENTINA", "RegionID": 1, "Population": 46044703}
{"CountryKey": 2, "CountryName": "BRAZIL", "RegionID": 1, "Population": 203080756}

In COPY INTO, können Sie Tabellenspalten bestimmten JSON-Feldern mithilfe von JSON-Pfadausdrücken zuordnen. Mit dieser Zuordnung können Sie nur die erforderlichen Felder aus den Quelldaten aufnehmen.

COPY INTO Countries (
  CountryID '$.CountryKey', 
  CountryName '$.CountryName', 
  RegionID '$.RegionKey', 
  Population '$.Population'
)
FROM 'https://myaccount.blob.core.windows.net/myblobcontainer/folder1/countries.jsonl'
WITH (   
    FILE_TYPE = 'JSONL' 
)

G. Laden von Daten durch Angeben von Wildcards und mehreren Dateien

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 = '|'
)

H. Laden von Daten aus OneLake

COPY INTO t1
FROM 'https://onelake.dfs.fabric.microsoft.com/<workspaceId>/<lakehouseId>/Files/*.csv'
WITH (
    FILE_TYPE = 'CSV',
    FIRSTROW = 2
);

Verwandte Inhalte

• Erfassen von Daten in Ihr Warehouse in Microsoft Fabric
• Erfassen von Daten in Ihr Warehouse mithilfe der COPY-Anweisung