Freigeben über


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:

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:

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
    

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 aus externen Speicherkonten verwenden. Die COPY-Anweisung bietet größtmögliche Flexibilität für die Datenerfassung mit hohem Durchsatz in Ihr Warehouse, und ist eine Strategie für das Erfassen von Daten in Ihr Warehouse.

In Microsoft Fabric unterstützt die Anweisung COPY (Transact-SQL) derzeit die Dateiformate PARQUET und CSV. Als Datenquellen werden nur Azure Data Lake Storage Gen2-Konten unterstützt.

Weitere Informationen zu COPY INTO-Vorgängen in Ihrem Warehouse in Microsoft Fabric finden Sie unter Erfassen von Daten in Ihr Warehouse mithilfe der COPY-Anweisung.

COPY INTO Standardmäßig authentifiziert sich der ausführende Entra-ID-Benutzer.

Hinweis

Informationen zu Azure Synapse Analytics finden Sie unter COPY INTO für Azure Synapse Analytics.

Verwenden Sie COPY für die folgenden Funktionen:

  • Verwenden Sie einen Benutzer mit niedrigeren Berechtigungen, um ohne strikte CONTROL-Berechtigungen Daten in das Data Warehouse zu laden.
  • 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.
  • Geben Sie ein differenzierteres Berechtigungsmodell, ohne Speicherkontoschlüssel über SAS (Share Access Signature) verfügbar zu machen.
  • Verwenden Sie ein anderes Speicherkonto für den ERRORFILE-Speicherort (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.
  • Angeben eines benutzerdefinierten Zeilenendpunkts, Eines Feldterminators und eines Feldvorführungszeichens für CSV-Dateien
  • Geben Sie Platzhalter und mehrere Dateien im Speicherortpfad an.
  • Weitere Informationen zu Optionen und Best Practices der Datenerfassung finden Sie unter Erfassen von Daten in Ihr Warehouse mithilfe der COPY-Anweisung.

Syntax

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 ]
 [ , ENCODING = { 'UTF8' | 'UTF16' } ]
 [ , PARSER_VERSION = { '1.0' | '2.0' } ]
)

Argumente

warehouse_name

Optional, wenn das aktuelle Warehouse für die Benutzer*innen, die den Vorgang ausführen, das Warehouse der angegebenen Tabelle ist. Wenn warehouse nicht angegeben ist und das angegebene Schema und die angegebene Tabelle im aktuellen Warehouse nicht vorhanden sind, tritt beim COPY-Vorgang ein Fehler auf, 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 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. Die Zieltabelle muss bereits im Warehouse vorhanden sein.

(Spaltenliste)

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

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 wird das Schlüsselwort „default“ vorangestellt.
  • Field_number – Die Eingabedateifeldnummer, die der Zielspalte zugeordnet ist.
  • Die Feldindizierung beginnt bei 1.

Wenn column_list nicht 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.

Hinweis

Beim Arbeiten mit Parquet-Dateien in einem Warehouse in Microsoft Azure-Fabric müssen die Spaltennamen in Quelle und Ziel exakt übereinstimmen. Wenn sich der Spaltenname in der Zieltabelle vom Spaltennamen in der Parquet-Datei unterscheidet, wird die Zieltabellenspalte mit NULL gefüllt.

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.

Externer Speicherort

Hinweis

Fabric OneLake-Pfade werden derzeit nicht unterstützt, nur BLOB- und ADLS Gen2-Speicherkonten werden unterstützt.

Gibt an, 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\>

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.

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 Folgendes gilt:

  • Bei der Pfadnamensübereinstimmung mit dem Platzhalter wird Groß-/Kleinschreibung beachtet
  • Bei Platzhaltern kann der umgekehrte Schrägstrich (\) als Escapezeichen verwendet werden.

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\>

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' | 'PARQUET' }

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.

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

CREDENTIAL gibt den Authentifizierungsmechanismus für den Zugriff auf das externe Speicherkonto an. In Warehouses in Microsoft Azure-Fabric werden nur Shared Access Signatures (SAS) und Speicherkontoschlüssel (Storage Account Key, SAK) als Authentifizierungsmechanismen unterstützt. Die EntraID-Authentifizierung des Benutzers ist standardmäßig, es müssen keine Anmeldeinformationen angegeben werden.

Hinweis

Bei Verwendung eines öffentlichen Speicherkontos muss CREDENTIAL nicht angegeben werden. Standardmäßig wird die Entra-ID des ausführenden Benutzers verwendet.

  • Authentifizieren mit Shared Access Signature (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 einem Speicherkontoschlüssel

    • IDENTITY: eine Konstante mit dem Wert von „Storage Account Key“
    • SECRET: Speicherkontoschlüssel

ERRORFILE = Verzeichnisspeicherort

ERRORFILE gilt nur für CSV. Gibt 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 diesem Ordner wird ein Ordner mit der Anweisungs-ID erstellt, in den zwei Arten von Dateien geschrieben werden: eine error.Json-Datei mit den Gründen für die Ablehnung und eine row.csv-Datei mit den abgelehnten Zeilen.

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. In Warehouse in Microsoft Fabric ist Shared Access Signature (SAS) der einzige unterstützte Authentifizierungsmechanismus.

  • Authentifizieren mit Freigegebenen Zugriffssignaturen (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

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 vom COPY-Vorgang nicht importiert werden kann, wird ignoriert und als ein Fehler gezählt. Wenn „max_errors“ nicht angegeben ist, wird der Standardwert 0 verwendet.

In Microsoft Fabric kann MAXERRORS nicht verwendet werden, wenn FILE_TYPE "LAMINAT" ist.

COMPRESSION = { '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.

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

  • .gz – GZIP

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

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 nur für CSV. Gibt ein einzelnes Zeichen an, das in der CSV-Datei als Anführungszeichen (Zeichenfolgen-Trennzeichen) 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 auch 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.

ROWTERMINATOR = 'row_terminator'

ROWTERMINATOR 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. Die Standardterminatoren sind \r\n, \nund \r.

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 ROWTERMINATOR nicht unterstützt.

FIRSTROW = First_row_int

FIRSTROW gilt nur für CSV. Gibt die Zeilennummer an, die für den COPY-Befehl in allen Dateien zuerst 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.

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.

PARSER_VERSION = { '1.0' | '2.0' }

PARSER_VERSION gilt nur für CSV. Der Standardwert ist 2.0. 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, FIELDTERMINATOR oder FIELDQUOTE wird nicht unterstützt. '\r\n' wird jedoch als STANDARDZEILETERMINATOR akzeptiert.

Bei Verwendung von Parser Version 1.0 mit UTF-8-Dateien werden Multibyte- und Multicharacter-Terminatoren für FIELDTERMINATOR nicht unterstützt.

Parser Version 1.0 ist nur für Abwärtskompatibilität verfügbar und sollte nur verwendet werden, wenn diese Einschränkungen auftreten.

Hinweis

Wenn COPY INTO mit komprimierten CSV-Dateien oder -Dateien mit UTF-16-Codierung verwendet wird, wechselt COPY INTO automatisch zu PARSER_VERSION 1.0, ohne dass eine Benutzeraktion erforderlich ist. Bei mehrstelligen Terminatoren für FIELDTERMINATOR oder ROWTERMINATOR schlägt die COPY INTO-Anweisung fehl. Verwenden Sie PARSER_VERSION = '1,0', wenn mehrstellige Trennzeichen erforderlich sind.

Hinweise

Bei COPY INTO in Warehouse ist das Festlegen eines Datumsformats zum Interpretieren von Datumszeichenfolgen nicht zulässig. Standardmäßig wird davon ausgegangen, dass alle Datumsangaben das Format „Monat-Tag-Jahr“ aufweisen. Verwenden Sie zum Erfassen einer CSV-Datei mit einem anderen Datumsformat SET DATEFORMAT, um das gewünschte Datumsformat auf Sitzungsebene anzugeben. Weitere Informationen finden Sie unter SET DATEFORMAT (Transact-SQL).

Darüber hinaus akzeptiert die COPY-Anweisung 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

Weitere Informationen zu COPY INTO-Vorgängen in Ihrem Warehouse in Microsoft Fabric finden Sie unter Erfassen von Daten in Ihr Warehouse mithilfe der COPY-Anweisung.

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'

Die Standardwerte des COPY-Befehls lauten wie folgt:

  • 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'

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

In diesem Beispiel wird ein Wildcard verwendet, um alle Parkettdateien mithilfe der EntraID des ausführenden Benutzers unter einem Ordner zu laden.

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

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= 'Shared Access Signature', SECRET='<Your_SAS_Token>')
    FIELDTERMINATOR = '|'
)

Häufig gestellte Fragen

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

Erwägen Sie, große CSV-Dateien aufzuteilen, insbesondere, wenn die Anzahl der Dateien klein ist, aber dateien mindestens 4 MB für eine bessere Leistung beibehalten.

Was muss bei der Dateiaufteilung für den COPY-Befehl zum Laden von Parquet-Dateien beachtet werden?

Erwägen Sie, große Parkettdateien aufzuteilen, insbesondere, wenn die Anzahl der Dateien klein ist.

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.

Welche Authentifizierungsmethode wird verwendet, wenn ich keine Anmeldeinformationen angibt?

COPY INTRO Standardmäßig wird die Entra-ID des ausgeführten Benutzers verwendet.