COPY INTO (Transact-SQL)

Gilt für: Azure Synapse Analytics

In diesem Artikel erfahren Sie, wie Sie die COPY-Anweisung in Azure Synapse Analytics zum Laden aus externen Speicherkonten verwenden. Die COPY-Anweisung bietet die größtmögliche Flexibilität für die Datenerfassung mit hohem Durchsatz in Azure Synapse Analytics.

Hinweis

Informationen zu Warehouse in Microsoft Fabric finden Sie unter COPY INTO.

Verwenden Sie COPY für die folgenden Funktionen:

• Benutzer mit niedrigeren Berechtigungen können ohne strikte Berechtigungen zur STEUERUNG im Data Warehouse laden
• Ausführen einer einzelnen T-SQL-Anweisung, ohne dass weitere Datenbankobjekte erstellt werden müssen
• Ordnungsgemäße Analyse und ordnungsgemäßes Laden von CSV-Dateien, bei denen Trennzeichen (Zeichenfolge, Feld, Zeile) in durch Trennzeichen getrennten Spalten mit Escapezeichen versehen sind
• Angeben eines feineren Berechtigungsmodells, ohne Speicherkontoschlüssel über SAS (Share Access Signature) verfügbar zu machen
• Verwenden eines anderen Speicherkontos für den ERRORFILE-Speicherort (REJECTED_ROW_LOCATION)
• Anpassen der Standardwerte für jede Zielspalte und Angeben der Quelldatenfelder, die in bestimmte Zielspalten geladen werden sollen
• Angeben eines benutzerdefinierten Zeilenendpunkts, Eines Feldterminators und eines Feldvorführungszeichens für CSV-Dateien
• Verwenden von SQL Server-Datumsformaten für CSV-Dateien
• Angeben von Platzhaltern und mehreren Dateien im Speicherortpfad
• Automatische Schemaermittlung zur Vereinfachung des Definierens und Zuordnens von Quelldaten zu Zieltabellen
• Automatischer Tabellenerstellungsprozess zum Erstellen von Tabellen 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.

Hinweis

Um komplexe Datentypen aus Parkettdateien zu laden, muss die automatische Tabellenerstellung mithilfe AUTO_CREATE_TABLEvon .

In den folgenden Dokumentationen finden Sie umfassende Beispiele und Schnellstarts, die die COPY-Anweisung verwenden:

• 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

Hinweis

Microsoft Entra ID war zuvor als Azure Active Directory (Azure AD) bekannt.

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

Argumente

schema_name

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

table_name

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.

(Spaltenliste)

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

Geben Sie im Fall von AUTO_CREATE_TABLE = 'ON' keine column_list 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 keine Spaltenliste angegeben ist, ordnet COPY Spalten basierend auf der Reihenfolge in Quelle und Ziel zu: Eingabefeld 1 wird Zielspalte 1 zugeordnet, Feld 2 wird Spalte 2 zugeordnet usw.

Externe Speicherorte

Speicherorte, wo die Dateien bereitgestellt werden, die die Daten enthalten. 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\>

Hinweis

Der .blob-Endpunkt ist auch für ADLS Gen2 verfügbar und führt derzeit zur besten Leistung. Verwenden Sie den .blob-Endpunkt, wenn .dfs für Ihre Authentifizierungsmethode nicht erforderlich ist.

• Konto: Der Speicherkontoname

• Container: Der Blobcontainername

• Pfad: Der Ordner- oder Dateipfad für die Daten. Der Speicherort beginnt im Container. Wenn ein Ordner angegeben ist, ruft COPY alle Dateien aus dem Ordner und seinen Unterordnern ab. COPY ignoriert ausgeblendete Ordner, und es werden keine Dateien zurückgegeben, die mit einem Unterstrich (_) oder einem Punkt (.) beginnen, es sei denn, sie werden 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 gilt:

• Bei der Pfadnamensübereinstimmung mit dem Platzhalter wird Groß-/Kleinschreibung beachtet
• Platzhalter können mithilfe des umgekehrten Schrägstrichs (\) mit Escapezeichen versehen werden.
• Die Platzhaltererweiterung wird rekursiv angewendet. Im folgenden Beispiel werden alle CSV-Dateien unter „Customer1“ (einschließlich der Unterverzeichnisse von „Customer1“) geladen: Account/Container/Customer1/*.csv.

Hinweis

Um die optimale Leistung zu erzielen, sollten Sie keine Platzhalter angeben, die auf eine größere Anzahl von Dateien erweitert werden. Listen Sie nach Möglichkeit mehrere Dateispeicherorte auf, anstatt Platzhalter anzugeben.

Es können nur mehrere Dateispeicherorte aus demselben Speicherkonto und Container über eine durch Trennzeichen getrennte Liste angegeben werden, wie z. B.:

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

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

FILE_TYPE gibt das Format der externen Daten an.

• CSV: Gibt eine CSV-Datei an, die dem Standard RFC 4180 entspricht.
• PARQUET: Gibt ein Parquet-Format an.
• ORC: Gibt ein ORC-Format (ORC = Optimized Row Columnar) an.

Hinweis

Der Dateityp „Delimited Text“ in PolyBase wird durch das Dateiformat „CSV“ ersetzt, bei dem das Standardtrennzeichen über den Parameter FIELDTERMINATOR konfiguriert werden kann.

FILE_FORMAT = Formatname_der_externen_Datei

FILE_FORMAT gilt nur für Parquet- und ORC-Dateien und gibt den Namen des externen Dateiformatobjekts an, das den Dateityp und die Komprimierungsmethode für die externen Daten enthält. 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/SERVICE PRINCIPAL/KEY/AAD	SAS/KEY	SAS/KEY
Azure Data Lake Gen2	SAS/MSI/SERVICE PRINCIPAL/KEY/AAD	SAS (Blob 1 )/MSI (DFS 2 )/SERVICE PRINCIPAL/KEY/AAD	SAS (Blob 1 )/MSI (DFS 2 )/SERVICE PRINCIPAL/KEY/AAD

1: Der .blob-Endpunkt ( .blob.core.windows.net) unter Ihrem externen Speicherortpfad ist für diese Authentifizierungsmethode erforderlich.

2: Der .dfs-Endpunkt ( .dfs.core.windows.net) unter Ihrem externen Speicherortpfad ist für diese Authentifizierungsmethode erforderlich.

Hinweis

• Bei der Authentifizierung mithilfe der Microsoft Entra-ID oder eines öffentlichen Speicherkontos muss CREDENTIAL nicht angegeben werden.
• Wenn Ihr Speicherkonto einem VNet zugeordnet ist, müssen Sie sich mit einer verwalteten Identität authentifizieren.

• Authentifizieren mit Shared Access Signatures (SAS)

  • IDENTITY: eine Konstante mit dem Wert von „Shared Access Signature“
  • GEHEIM: Die Signatur für den freigegebenen Zugriff bietet delegierten Zugriff auf Ressourcen in Ihrem Speicherkonto.
  • Erforderliche Mindestberechtigungen: READ und LIST

• Authentifizieren mit Dienstprinzipalen

  • IDENTITY: <ClientID>@<OAuth_2.0_Token_EndPoint>
  • GEHEIMER SCHLÜSSEL: 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 dem Wert von „Storage Account Key“
  • SECRET: Speicherkontoschlüssel

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

  • IDENTITY: eine Konstante mit dem 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 (vormals SQL DW), der keinem Synapse-Arbeitsbereich zugeordnet ist, ist diese RBAC-Rolle nicht erforderlich, aber für die verwaltete Identität sind Zugriffssteuerungslistenberechtigungen (Access Control List, ACL) für die Zielobjekte erforderlich, um den Lesezugriff auf die Quelldateien zu ermöglichen.

• 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

ERRORFILE = Verzeichnisspeicherort

ERRORFILE gilt nur für CSV. Gibt in der COPY-Anweisung das Verzeichnis an, in das die abgelehnten Zeilen und die entsprechende Fehlerdatei geschrieben werden sollen. Der vollständige Pfad vom Speicherkonto oder der relative Pfad zum Container kann angegeben werden. Ist der angegebene Pfad nicht vorhanden, wird ein Pfad für Sie erstellt. Es wird ein untergeordnetes Verzeichnis mit dem Namen „_rejectedrows“ erstellt. Mit dem Unterstrich (_) wird sichergestellt, dass das Verzeichnis für andere Datenverarbeitungsvorgänge übergangen wird, es sei denn, es ist explizit im LOCATION-Parameter angegeben.

Hinweis

Wenn ein relativer Pfad an ERRORFILE übergeben wird, ist der Pfad relativ zum in external_location angegebenen Containerpfad.

In diesem Verzeichnis befindet sich ein Ordner, der basierend auf der Uhrzeit der Lastübermittlung im Format „JahrMonatTag-StundeMinuteSekunde“ erstellt wurde (z. B. 20180330-173205). In diesen Ordner werden zwei Arten von Dateien geschrieben: die Ursachendatei (Fehler) und die Datendatei (Zeile), denen jeweils queryID, distributionID und eine Datei-GUID vorangestellt werden. Da die Daten und die Ursache in getrennten Dateien gespeichert sind, haben die zugehörigen Dateien ein entsprechendes Präfix.

Wenn für ERRORFILE der vollständige Pfad des Speicherkontos definiert ist, wird ERRORFILE_CREDENTIAL zum Herstellen einer Verbindung mit diesem Speicher verwendet. Andernfalls wird der für CREDENTIAL angegebene Wert verwendet. Wenn dieselben Anmeldeinformationen, die für die Quelldaten verwendet werden, für ERRORFILE verwendet werden, gelten auch Einschränkungen, die für ERRORFILE_CREDENTIAL gelten.

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

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

• Azure Blob Storage – SAS/SERVICE PRINCIPAL/AAD

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

• Authentifizieren mit Shared Access Signatures (SAS)

  • IDENTITY: eine Konstante mit dem Wert von „Shared Access Signature“
  • GEHEIM: Die Signatur für den freigegebenen Zugriff 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>
  • GEHEIMER SCHLÜSSEL: Microsoft Entra-Anwendungsdienstprinzipalschlüssel
  • Mindestens erforderliche RBAC-Rollen: Mitwirkender von Speicherblobdaten oder Besitzer von Speicherblobdaten

Hinweis

Verwenden des OAuth 2.0-Tokenendpunkts V1

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

  • IDENTITY: eine Konstante mit dem 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 wird nicht unterstützt.

Hinweis

Wenn Sie das gleiche Speicherkonto für die ERRORFILE-Datei verwenden und den ERRORFILE-Pfad relativ zum Stamm des Containers angeben, müssen Sie ERROR_CREDENTIAL nicht angeben.

MAXERRORS = maximale_Fehlerzahl

MAXERRORS gibt die maximale Anzahl von abgelehnten Zeilen an, die beim Laden zulässig sind, bevor der COPY-Vorgang fehlschlägt. Jede Zeile, die beim COPY-Vorgang nicht importiert werden kann, wird ignoriert und zählt dabei als ein Fehler. Wenn „max_errors“ nicht angegeben ist, wird der Standardwert 0 verwendet.

MAXERRORS kann nicht mit AUTO_CREATE_TABLE verwendet werden.

Wenn FILE_TYPE "BINARY" lautet, treten Ausnahmen, die durch Datentypkonvertierungsfehler (z. B. Binary in SQL integer) verursacht werden, immer noch zu einem Fehler bei COPY INTO, wobei MAXERRORS ignoriert wird.

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

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

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

Der COPY-Befehl erkennt den Komprimierungstyp automatisch basierend auf der Dateierweiterung, wenn dieser Parameter nicht angegeben ist:

• .gz – GZIP
• .snappy – Snappy
• .deflate – DefaultCodec (nur Parquet und ORC)

Der Befehl "KOPIEREN" erfordert, dass Gzip-Dateien keinen nachfolgenden Garbage enthalten, der normal ausgeführt werden kann. 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. Stellen Sie sicher, dass am Ende der Gzip-Dateien kein nachgestellter Müll vorhanden ist, um sicherzustellen, dass COPY diese Dateien erfolgreich verarbeiten kann.

FIELDQUOTE = 'Feldquote'

FIELDQUOTE gilt für CSV und gibt ein einzelnes Zeichen an, das als Anführungszeichen (Zeichenfolgen-Trennzeichen) in der CSV-Datei verwendet wird. Wenn hier kein Wert angegeben ist, wird das Anführungszeichen (") gemäß Definition im Standard RFC 4180 verwendet. Hexadezimalnotation wird auch für FIELDQUOTE unterstützt. Erweiterte ASCII- und Multibytezeichen werden mit UTF-8 für FIELDQUOTE nicht unterstützt.

Hinweis

FIELDQUOTE-Zeichen werden in Zeichenfolgenspalten mit Escapezeichen versehen, wenn ein doppeltes FIELDQUOTE-Zeichen (Trennzeichen) vorhanden ist.

FIELDTERMINATOR = 'field_terminator'

FIELDTERMINATOR Gilt nur für CSV. Gibt das Feldabschlusszeichen an, das in der CSV-Datei verwendet wird. Das Feldabschlusszeichen kann in hexadezimaler Schreibweise angegeben werden. Das Feldabschlusszeichen kann mehrere Zeichen aufweisen. Das Standard-Feldabschlusszeichen ist ein (,). Erweiterte ASCII- und Multibytezeichen werden mit UTF-8 für FIELDTERMINATOR nicht unterstützt.

ROW TERMINATOR = 'Zeilenabschlusszeichen'

ROW TERMINATOR gilt nur für CSV. Gibt das Zeilenabschlusszeichen an, das in der CSV-Datei verwendet wird. Das Zeilenabschlusszeichen kann in hexadezimaler Schreibweise angegeben werden. Das Zeilenabschlusszeichen kann mehrere Zeichen aufweisen. 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 bei Zeilenabschlusszeichen aus mehreren Zeichen in Hexadezimalschreibweise nicht „0x“ zwischen den einzelnen Zeichen an.

Erweiterte ASCII- und Multibytezeichen werden mit UTF-8 für ROW-TERMINATOR nicht unterstützt.

FIRSTROW = First_row_int

FIRSTROW gilt für CSV und gibt die Zeilennummer an, die zuerst in allen Dateien für den COPY-Befehl gelesen wird. Die Werte beginnen mit 1, dem Standardwert. Wenn der Wert auf 2 festgelegt ist, wird die erste Zeile in jeder Datei (Kopfzeile) beim Laden der Daten übersprungen. 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 = 'ON' | 'OFF'

IDENTITY_INSERT gibt an, ob die Identitätswerte oder Werte in der importierten Datendatei für die Identitätsspalte verwendet werden sollen. Wenn IDENTITY_INSERT auf OFF gesetzt ist (Standard), werden die Identitätswerte für diese Spalte überprüft, aber nicht importiert. Azure Synapse Analytics weist automatisch eindeutige Werte zu, basierend auf dem Ausgangswert und den inkrementellen Werten, die bei der Tabellenerstellung angegeben werden. Beachten Sie das folgende Verhalten beim COPY-Befehl:

• Wenn IDENTITY_INSERT aus ist und die Tabelle eine Identitätsspalte aufweist
  • Es muss eine Spaltenliste angegeben werden, die der Identitätsspalte kein Eingabefeld zuordnet.
• Wenn IDENTITY_INSERT aktiviert ist und die Tabelle über eine Identitätsspalte verfügt
  • Wenn eine Spaltenliste übermittelt wird, muss sie der Identitätsspalte ein Eingabefeld zuordnen.
• Der Standardwert wird für die IDENTITY COLUMN in der Spaltenliste nicht unterstützt.
• IDENTITY_INSERT kann nur jeweils für eine Tabelle festgelegt werden.

AUTO_CREATE_TABLE = { 'ON' | 'OFF' }

AUTO_CREATE_TABLE gibt an, ob die Tabelle zusammen mit der automatischen Schemaermittlung automatisch erstellt werden kann. Es ist nur für Parkett-Dateien 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. Kann auch mit bereits vorhandenen Tabellen verwendet werden, um die Vorteile der automatischen Schemaermittlung von Parquet-Dateien zu nutzen.
• OFF: Die automatische Tabellenerstellung ist nicht aktiviert. Standard.

Hinweis

Die automatische Tabellenerstellung funktioniert zusammen mit der automatischen Schemaermittlung. Die automatische Tabellenerstellung ist standardmäßig NICHT aktiviert.

Laden Sie keine Parquet-Dateien in Tabellen mit Hashverteilung mithilfe von COPY INTO mit AUTO_CREATE_TABLE = 'ON'.

Wenn Parquet-Dateien mit COPY INTO in Tabellen mit Hashverteilung geladen werden sollen, müssen Sie diese zuerst in eine Roundrobin-Stagingtabelle und dann mit INSERT ... SELECT aus dieser Tabelle in die Zieltabelle mit Hashverteilung kopieren.

Berechtigungen

Der Benutzer, der den COPY-Befehl ausführt, muss über die folgenden Berechtigungen verfügen:

• ADMINISTER DATABASE BULK OPERATIONS
• 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];

Hinweise

Die COPY-Anweisung akzeptiert nur UTF-8- und UTF-16 gültige Zeichen für Zeilendaten und Befehlsparameter. Quelldateien oder Parameter (z. B. ROW TERMINATOR oder FIELD TERMINATOR), die ungültige Zeichen verwenden, können von der COPY-Anweisung falsch interpretiert werden und unerwartete Ergebnisse wie Datenbeschädigung oder andere Fehler verursachen. Stellen Sie sicher, dass Die Quelldateien und -parameter UTF-8- oder UTF-16-kompatibel sind, bevor Sie die COPY-Anweisung aufrufen.

Beispiele

A. Laden aus einem öffentlichen Speicherkonto

Das folgende Beispiel ist die einfachste Form des COPY-Befehls, bei der Daten aus einem öffentlichen Speicherkonto geladen werden. In diesem Beispiel entsprechen die Standardwerte der COPY-Anweisung dem Format der Zeilenelement-CSV-Datei.

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 = DATEFORMAT (Datumsformat) der Sitzung

• MAXERRORS = 0

• COMPRESSION Standard ist nicht komprimiert

• FIELDQUOTE = '"'

• FIELDTERMINATOR = ','

• ROWTERMINATOR = '\n'

Wichtig

COPY behandelt „\n“ intern als „\r\n“. Weitere Informationen finden Sie im Abschnitt zu ROWTERMINATOR.

• 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, in denen der Zeilenvorschub als ein Zeilenabschlusszeichen verwendet wird, 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>'),
    --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: 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'
)

Häufig gestellte Fragen

Wie hoch ist die Leistung des COPY-Befehls im Vergleich zu PolyBase?

Der COPY-Befehl weist je nach Workload eine bessere Leistung auf.

• Komprimierte Dateien können nicht automatisch aufgeteilt werden. Für eine optimale Ladeleistung empfiehlt es sich, Ihre Eingaben beim Laden von komprimierten CSV-Dateien in mehrere Dateien aufzuteilen.

• Große unkomprimierte CSV-Dateien können automatisch aufgeteilt und parallel geladen werden, sodass es in den meisten Fällen nicht erforderlich ist, unkomprimierte CSV-Dateien manuell aufzuteilen. In bestimmten Fällen, in denen die automatische Dateiaufteilung aufgrund von Datenmerkmalen nicht möglich ist, kann die manuelle Aufteilung großer CSV-Dateien die Leistung jedoch verbessern.

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

Informationen zur Anzahl von Dateien finden Sie in der folgenden Tabelle. Sobald die empfohlene Dateianzahl erreicht ist, erzielen Sie eine umso bessere Leistung, je größer die Dateien sind. Die Anzahl der Dateien wird durch die Anzahl der Serverknoten multipliziert mit 60 bestimmt. Bei 6.000 DWU liegen beispielsweise 12 Serverknoten und 12 × 60 = 720 Partitionen vor. Informationen zur einfachen Dateiaufteilung finden Sie unter Maximieren des COPY-Ladedurchsatzes mit Dateiaufteilungen.

DWU	Nr. 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?

Eine Aufteilung von Parquet- und ORC-Dateien ist nicht erforderlich, da der COPY-Befehl Dateien automatisch aufteilt. Die Parquet- und ORC-Dateien im Azure Storage-Konto sollten mindestens 256 MB groß sein, damit eine optimale Leistung erzielt wird.

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

Es gibt keine Einschränkungen in Bezug auf die Anzahl oder Größe von Dateien. Um eine optimale Leistung zu erzielen, wird jedoch eine Dateigröße von mindestens 4 MB empfohlen.

Gibt es bekannte Probleme bei der COPY-Anweisung?

Wenn Sie über einen Azure Synapse-Arbeitsbereich verfügen, der vor dem 7. Dezember 2020 erstellt wurde, kann es bei der Authentifizierung mit verwalteter Identität zu einer ähnlichen Fehlermeldung gekommen sein: com.microsoft.sqlserver.jdbc.SQLServerException: Managed Service Identity has not been enabled on this server. Please enable Managed Service Identity and try again.

Gehen Sie wie folgt vor, um dieses Problem zu umgehen, indem Sie die verwaltete Identität des Arbeitsbereichs erneut registrieren:

1. Installieren Sie Azure PowerShell. Siehe Installieren von PowerShell.
2. Registrieren der verwalteten 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
   

Zugehöriger Inhalt

• Übersicht über das Laden mit Azure Synapse Analytics