OVERSCHRIJVEN NAAR (Transact-SQL)

van toepassing op:Azure Synapse Analytics-

In dit artikel wordt uitgelegd hoe u de instructie COPY gebruikt in Azure Synapse Analytics voor het laden van gegevens uit externe opslagaccounts. De COPY instructie biedt de meeste flexibiliteit voor het invoeren van hoogdoorvoerdata in Azure Synapse Analytics.

Gebruik COPY voor de volgende mogelijkheden:

• Gebruik gebruikers met lagere bevoegdheden om gegevens te laden zonder strikte CONTROL-machtigingen voor het datawarehouse nodig te hebben.
• Voer één T-SQL-instructie uit zonder dat u andere databaseobjecten hoeft te maken.
• CSV-bestanden op de juiste manier parseren en laden, waarbij scheidingstekens (tekenreeks, veld, rij) worden ontsnapt in kolommen met tekenreeksscheidingstekens.
• Geef een nauwkeuriger machtigingsmodel op zonder opslagaccountsleutels beschikbaar te maken met behulp van Shared Access Signatures (SAS).
• Gebruik een ander opslagaccount voor de ERRORFILE locatie (REJECTED_ROW_LOCATION).
• Pas standaardwaarden voor elke doelkolom aan en geef brongegevensvelden op die moeten worden geladen in specifieke doelkolommen.
• Specificeer een aangepaste rijterminator, veldterminator en veldquote voor CSV-bestanden.
• Gebruik SQL Server datumnotaties voor CSV-bestanden.
• Geef jokertekens en meerdere bestanden op in het pad naar de opslaglocatie.
• Automatische schemadetectie vereenvoudigt het definiëren en toewijzen van brongegevens in doeltabellen.
• Het proces voor het automatisch maken van tabellen maakt automatisch de tabellen en werkt samen met automatische schemadetectie.
• Laad rechtstreeks complexe gegevenstypen uit Parquet-bestanden, zoals Kaarten en Lijsten, in tekenreekskolommen, zonder andere hulpprogramma's te gebruiken om de gegevens vooraf te verwerken.

Zie voor uitgebreide voorbeelden en quickstarts met behulp van de COPY instructie:

• quickstart: Gegevens bulksgewijs laden met behulp van de COPY-instructie
• quickstart: Voorbeelden met behulp van de COPY-instructie en de ondersteunde verificatiemethoden
• quickstart: de INSTRUCTIE COPY maken met behulp van de uitgebreide Synapse Studio-gebruikersinterface

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

Optioneel als het standaardschema voor de gebruiker die de bewerking uitvoert, het schema van de opgegeven tabel is. Als u geen schema opgeeft en het standaardschema van de gebruiker die de COPY bewerking uitvoert, verschilt van het schema van de opgegeven tabel, wordt de COPY bewerking geannuleerd en wordt er een foutbericht geretourneerd.

tabelnaam

De naam van de tabel waarnaar u gegevens wilt kopiëren. De doeltabel kan een tijdelijke of permanente tabel zijn en moet al aanwezig zijn in de database. Geef voor de automatische schemadetectiemodus geen kolomlijst op.

(column_list)

Een optionele lijst met een of meer kolommen die worden gebruikt om brongegevensvelden toe te wijzen aan tabelkolommen voor het laden van gegevens.

Geef geen column_list op wanneer AUTO_CREATE_TABLE = 'ON'.

column_list moet tussen haakjes staan en gescheiden door komma's. De kolomlijst heeft de volgende indeling:

[(Column_name [standaard Default_value] [Field_number] [,... n])]

• Column_name : de naam van de kolom in de doeltabel.
• Default_value: de standaardwaarde die een NULL-waarde in het invoerbestand vervangt. De standaardwaarde is van toepassing op alle bestandsindelingen. COPY probeert NULL uit het invoerbestand te laden wanneer een kolom wordt weggelaten uit de kolomlijst of wanneer er een leeg invoerbestandsveld is. De standaardwaarde gaat vooraf aan het trefwoord 'standaard'
• Field_number: het veldnummer van het invoerbestand dat is toegewezen aan de doelkolom.
• De veldindexering begint bij 1.

Wanneer u geen kolomlijst opgeeft, COPY worden kolommen toegewezen op basis van de bron- en doelvolgorde: Invoerveld 1 gaat naar doelkolom 1, veld 2 gaat naar kolom 2, enzovoort.

Externe locaties

De locatie waar de bestanden met de gegevens zijn gefaseerd. Momenteel worden Azure Data Lake Storage (ADLS) Gen2 en Azure Blob Storage ondersteund:

• externe locatie voor Blob Storage: https://<account\>.blob.core.windows.net/<container\>/<path\>
• externe locatie voor ADLS Gen2: https://<account\>.dfs.core.windows.net/<container\>/<path\>

• account - De naam van het opslagaccount

• Container - De naam van de blobcontainer

• pad : de map of het bestandspad voor de gegevens. De locatie begint vanuit de container. Als u een map opgeeft, COPY haalt u alle bestanden op uit de map en alle bijbehorende submappen. COPY negeert verborgen mappen en retourneert geen bestanden die beginnen met een onderstreping (_) of een punt (.), tenzij expliciet is opgegeven in het pad. Dit gedrag is hetzelfde, zelfs wanneer u een pad met een jokerteken opgeeft.

U kunt jokertekens opnemen in het pad waar:

• Naam van jokertekenpad komt overeen met hoofdlettergevoelig
• U kunt een jokerteken escapen met behulp van het backslash-teken (\)
• Jokertekenuitbreiding wordt recursief toegepast. Alle CSV-bestanden onder Customer1 (inclusief submappen van Customer1) worden bijvoorbeeld geladen in het volgende voorbeeld: Account/Container/Customer1/*.csv

U kunt meerdere bestandslocaties alleen vanuit hetzelfde opslagaccount en dezelfde container opgeven via een door komma's gescheiden lijst, zoals:

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

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

FILE_TYPE hiermee geeft u de indeling van de externe gegevens.

• CSV: Hiermee geeft u een bestand met door komma's gescheiden waarden op dat voldoet aan de RFC 4180-standaard .
• PARQUET: Hiermee geeft u een Parquet-indeling op.
• ORC: Hiermee geeft u de indeling Geoptimaliseerde rijkolommen (ORC) op.

FILE_FORMAT = external_file_format_name

FILE_FORMAT is alleen van toepassing op Parquet- en ORC-bestanden. Hiermee geeft u de naam op van het externe bestandsindelingsobject waarin het bestandstype en de compressiemethode voor de externe gegevens worden opgeslagen. Als u een externe bestandsindeling wilt maken, gebruikt u CREATE EXTERNAL FILE FORMAT.

REFERENTIE (IDENTITEIT = '', SECRET = '')

CREDENTIAL Hiermee geeft u het verificatiemechanisme op voor toegang tot het externe opslagaccount. Verificatiemethoden zijn:

	CSV	Parquet	ORC
Azure Blob Storage-	SAS/MSI/SERVICE PRINCIPAL/KEY/Entra	SAS/KEY	SAS/KEY
Azure Data Lake Gen2-	SAS/MSI/SERVICE PRINCIPAL/KEY/Entra	SAS (blob 1 )/MSI (dfs 2 )/SERVICE PRINCIPAL/KEY/Entra	SAS (blob 1 )/MSI (dfs 2 )/SERVICE PRINCIPAL/KEY/Entra

¹ Het blob-eindpunt (.blob.core.windows.net) in het pad naar de externe locatie is vereist voor deze verificatiemethode.

² Het dfs-eindpunt (.dfs.core.windows.net) in uw externe locatiepad is vereist voor deze verificatiemethode.

• Verifiëren met Shared Access Signatures (SAS)

  • IDENTITY: Een constante met een waarde van Shared Access Signature
  • SECRET: de handtekening voor gedeelde toegang biedt gedelegeerde toegang tot resources in uw opslagaccount.

• Minimale machtigingen vereist: LEZEN en LIJST

• Verifiëren met service-principals

  • IDENTITY: <ClientID>@<OAuth_2.0_Token_EndPoint>
  • SECRET: Microsoft Entra sleutel voor de service-principal van de toepassing

• Minimale RBAC-rollen vereist: Inzender voor opslagblobgegevens, Inzender voor opslagblobgegevens, eigenaar van opslagblobgegevens of Lezer van opslagblobgegevens

• Verifiëren met opslagaccountsleutel

  • IDENTITY: Een constante met een waarde van Storage Account Key
  • SECRET: Sleutel van opslagaccount

• Verifiëren met Managed Identity (VNet-service-eindpunten)

  • IDENTITY: Een constante met een waarde van Managed Identity

• Minimale RBAC-rollen vereist: inzender voor opslagblobgegevens of eigenaar van opslagblobgegevens voor de geregistreerde Microsoft Entra-logische server in Azure. Wanneer u een toegewezen SQL-pool (voorheen SQL DW) gebruikt die niet is gekoppeld aan een Synapse-werkruimte, is deze RBAC-rol niet vereist, maar vereist de beheerde identiteit Access Control lijstmachtigingen (ACL) voor de doelobjecten om leestoegang tot de bronbestanden in te schakelen.

• Verifiëren met een Microsoft Entra-gebruiker

  • CREDENTIAL is niet vereist

• Minimale RBAC-rollen vereist: Inzender voor opslagblobgegevens of eigenaar van opslagblobgegevens voor de Microsoft Entra-gebruiker

ERRORFILE = Maplocatie

ERRORFILE is alleen van toepassing op CSV. Hiermee geeft u de map in de COPY instructie waarin de geweigerde rijen en het bijbehorende foutbestand worden geschreven. U kunt het volledige pad opgeven vanuit het opslagaccount of het pad ten opzichte van de container. Als het opgegeven pad niet bestaat, maakt het magazijn er een. Er wordt een onderliggende map gemaakt met de naam _rejectedrows. Het _ teken zorgt ervoor dat de map wordt ontsnapt voor andere gegevensverwerking, tenzij deze expliciet is benoemd in de locatieparameter.

Binnen deze map maakt het magazijn een map op basis van de tijd van het laden in de indeling YearMonthDay -HourMinuteSecond (bijvoorbeeld 20180330-173205). In deze map schrijft het proces twee typen bestanden: het redenbestand (fout) en het gegevensbestand (rijbestand). Elk bestand prependeert de queryID, distributionIDen een bestands-GUID. Omdat de gegevens en de reden zich in afzonderlijke bestanden bevinden, hebben de bijbehorende bestanden een overeenkomend voorvoegsel.

Als ERRORFILE het volledige pad van het opslagaccount is gedefinieerd, COPY gebruikt ERRORFILE_CREDENTIAL om verbinding te maken met die opslag. Anders wordt de waarde gebruikt die u opgeeft.CREDENTIAL Wanneer u dezelfde referentie gebruikt voor de brongegevens en ERRORFILEbeperkingen die ook van toepassing zijn ERRORFILE_CREDENTIAL .

ERRORFILE_CREDENTIAL = (IDENTITEIT = '', SECRET = '')

ERRORFILE_CREDENTIAL is alleen van toepassing op CSV-bestanden. Ondersteunde gegevensbron- en verificatiemethoden zijn:

• Azure Blob Storage: SAS, service-principal of Microsoft Entra

• Azure Data Lake Gen2: SAS, MSI, service-principal of Microsoft Entra

• Verifiëren met Shared Access Signatures (SAS)

  • IDENTITY: Een constante met een waarde van Shared Access Signature
  • SECRET: de handtekening voor gedeelde toegang biedt gedelegeerde toegang tot resources in uw opslagaccount.

• Minimale machtigingen vereist: LEZEN, LIJST, SCHRIJVEN, MAKEN, VERWIJDEREN

• Verifiëren met service-principals

  • IDENTITY: <ClientID>@<OAuth_2.0_Token_EndPoint>
  • SECRET: Microsoft Entra sleutel voor de service-principal van de toepassing

• Minimale RBAC-rollen vereist: Inzender voor opslagblobgegevens of eigenaar van opslagblobgegevens

• Verifiëren met Managed Identity (VNet-service-eindpunten)

  • IDENTITY: Een constante met een waarde van Managed Identity

• Minimale RBAC-rollen vereist: Inzender voor opslagblobgegevens of eigenaar van opslagblobgegevens voor de geregistreerde SQL Database-server van Microsoft Entra

• Verifiëren met een Microsoft Entra-gebruiker

  • CREDENTIAL is niet vereist

• Minimale RBAC-rollen vereist: Inzender voor opslagblobgegevens of eigenaar van opslagblobgegevens voor de Microsoft Entra-gebruiker

Het gebruik van een opslagaccountsleutel met ERRORFILE_CREDENTIAL wordt niet ondersteund.

MAXERRORS = max_errors

MAXERRORS geeft het maximum aantal geweigerde rijen op dat is toegestaan in de belasting voordat de COPY-bewerking mislukt. Elke rij die de COPY-bewerking niet kan importeren, wordt genegeerd en geteld als één fout. Als u geen waarde opgeeft voor het maximum aantal fouten, is de standaardwaarde 0.

MAXERRORS kan niet worden gebruikt met AUTO_CREATE_TABLE.

Wanneer FILE_TYPE zijn PARQUETer uitzonderingen die worden veroorzaakt door conversiefouten van gegevenstypen (bijvoorbeeld parquet binair naar SQL-geheel getal) nog steeds COPY INTO mislukt, waarbij wordt MAXERRORSgenegeerd.

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

COMPRESSION is optioneel en geeft de methode voor gegevenscompressie voor de externe gegevens op.

• CSV ondersteunt GZIP.
• Parquet ondersteunt GZIP en Snappy.
• ORC ondersteunt DefaultCodec en Snappy.
• Zlib is de standaardcompressie voor ORC.

Met de opdracht COPY wordt het compressietype automatisch gedefinieerd op basis van de bestandsextensie wanneer u deze parameter niet opgeeft:

• .gz - GZIP
• .snappy - Bits
• .deflate - DefaultCodec (alleen Parquet en ORC)

De opdracht COPY vereist dat gzip-bestanden geen volgvuil bevatten om normaal te werken. De gzip-indeling vereist strikt dat bestanden bestaan uit geldige leden zonder aanvullende informatie voor, tussen of na de bestanden. Elke afwijking van deze indeling, zoals de aanwezigheid van niet-gzip-gegevens, resulteert in de fout van de opdracht COPY. Om ervoor te zorgen dat COPY correct wordt uitgevoerd, controleert u of er geen volgvuil is aan het einde van gzip-bestanden.

FIELDQUOTE = 'field_quote'

FIELDQUOTE is van toepassing op CSV en geeft één teken op dat wordt gebruikt als het aanhalingsteken (tekenreeksscheidingsteken) in het CSV-bestand. Als u deze waarde niet opgeeft, wordt het aanhalingsteken (") gebruikt als het aanhalingsteken zoals gedefinieerd in de RFC 4180-standaard. Hexadecimale notatie wordt ook ondersteund voor FIELDQUOTE. Uitgebreide ASCII- en multibytetekens worden niet ondersteund met UTF-8 voor FIELDQUOTE.

FIELDTERMINATOR = 'field_terminator'

FIELDTERMINATOR is alleen van toepassing op CSV. Hiermee geeft u het veldeindteken op dat wordt gebruikt in het CSV-bestand. U kunt het veldeindteken opgeven met behulp van hexadecimale notatie. Het veldeindteken kan multicharacter zijn. Het standaardveldeindteken is een (,). Uitgebreide ASCII- en multibytetekens worden niet ondersteund met UTF-8 voor FIELDTERMINATOR.

ROWTERMINATOR = 'row_terminator'

ROWTERMINATOR is alleen van toepassing op CSV. Hiermee geeft u het rijeindteken op dat wordt gebruikt in het CSV-bestand. U kunt het rijeindteken opgeven met behulp van hexadecimale notatie. Het rijeindteken kan multicharacter zijn. Standaard is het rijeindteken \r\n.

Met de opdracht COPY wordt het \r teken voorafgegaan bij het opgeven van \n (nieuwe regel) wat resulteert in \r\n. Als u alleen het \n teken wilt opgeven, gebruikt u hexadecimale notatie (0x0A). Wanneer u rijeindtekens voor meerdere tekens opgeeft in hexadecimaal, moet u niet tussen elk teken opgeven 0x .

Uitgebreide ASCII- en multibytetekens worden niet ondersteund met UTF-8 voor ROWTERMINATOR.

FIRSTROW = First_row_int

FIRSTROW is van toepassing op CSV en geeft het rijnummer op dat eerst wordt gelezen in alle bestanden voor de opdracht COPY. Waarden beginnen vanaf 1, wat de standaardwaarde is. Als u de waarde 2instelt op, wordt de eerste rij in elk bestand (veldnamenrij) overgeslagen wanneer de gegevens worden geladen. Rijen worden overgeslagen op basis van het bestaan van rijeindtekens.

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

DATEFORMAT is alleen van toepassing op CSV en geeft de datumnotatie van de datumtoewijzing aan SQL Server-datumnotaties op. Zie datum- en tijdgegevenstypen en -functies (Transact-SQL)voor een overzicht van alle Transact-SQL datum- en tijdgegevenstypen en -functies. DATEFORMAT in de opdracht COPY heeft voorrang op DATEFORMAT geconfigureerd op sessieniveau.

ENCODING = 'UTF8' | 'UTF16'

ENCODING is alleen van toepassing op CSV. De standaardwaarde is UTF8. Hiermee geeft u de gegevenscoderingsstandaard op voor de bestanden die door de opdracht COPY zijn geladen.

IDENTITY_INSERT = 'AAN' | 'UIT'

IDENTITY_INSERT geeft aan of de identiteitswaarde of -waarden in het geïmporteerde gegevensbestand moeten worden gebruikt voor de identiteitskolom. Als IDENTITY_INSERT dit is OFF (standaard), worden de identiteitswaarden voor deze kolom geverifieerd, maar niet geïmporteerd. Let op het volgende gedrag met de opdracht COPY:

• Als IDENTITY_INSERT uit is, heeft de tabel een identiteitskolom
  • U moet een kolomlijst opgeven waarmee geen invoerveld aan de identiteitskolom wordt toegewezen.
• Als IDENTITY_INSERT is ingeschakeld en de tabel een identiteitskolom heeft
  • Als u een kolomlijst doorgeeft, moet er een invoerveld aan de identiteitskolom worden toegewezen.
• De standaardwaarde wordt niet ondersteund voor de kolom IDENTITY in de kolomlijst.
• U kunt slechts één tabel tegelijk instellen IDENTITY_INSERT .

In Azure Synapse Analytics worden automatisch unieke waarden toegewezen op basis van de seed- en incrementele waarden die zijn opgegeven tijdens het maken van de tabel.

AUTO_CREATE_TABLE = { 'AAN' | 'UIT' }

AUTO_CREATE_TABLE geeft aan of de tabel automatisch kan worden gemaakt door naast automatische schemadetectie te werken. AUTO_CREATE_TABLE is alleen beschikbaar voor Parquet-bestanden in Azure Synapse Analytics.

• AAN: Hiermee schakelt u het automatisch maken van tabellen in. Tijdens COPY INTO het proces wordt automatisch een nieuwe tabel gemaakt door de structuur van het bestand te detecteren dat moet worden geladen. U kunt het ook gebruiken met vooraf bestaande tabellen om te profiteren van automatische schemadetectie van Parquet-bestanden.
• UIT: Het automatisch maken van tabellen is niet ingeschakeld. Default.

Permissions

De gebruiker die de opdracht COPY uitvoert, moet de volgende machtigingen hebben:

• DATABASE BULKBEWERKINGEN BEHEREN
• INSERT

Hiervoor zijn INSERT- en BEHEERMACHTIGINGEN VOOR BULKBEWERKINGen vereist. In Azure Synapse Analytics zijn MACHTIGINGEN VOOR BULKBEWERKINGEN VOOR DATABASES VEREIST.

Als de gebruiker die de opdracht COPY uitvoert ook van plan is een nieuwe tabel te genereren en er gegevens in te laden, hebben ze CREATE TABLE en ALTER ON SCHEMA-machtigingen nodig.

Als u bijvoorbeeld wilt toestaan dat mike@contoso.com copy gebruikt om een nieuwe tabel te maken in het HR schema en de gegevens uit een Parquet-bestand in te voegen, gebruikt u het volgende Transact-SQL voorbeeld:

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

De COPY instructie accepteert alleen UTF-8 en UTF-16 geldige tekens voor rijgegevens en commandoparameters. De COPY instructie kan bronbestanden of -parameters (zoals ROWTERMINATOR of FIELDTERMINATOR) die ongeldige tekens gebruiken, onjuist interpreteren en onverwachte resultaten veroorzaken, zoals beschadiging van gegevens of andere fouten. Zorg ervoor dat je bronbestanden en parameters UTF-8 of UTF-16 compatibel zijn voordat je de COPY instructie aanroept.

De MAXDOP queryhint wordt niet ondersteund met COPY INTO.

Wijzig de bronbestanden en mappen tijdens de COPY INTO bewerking niet om een betrouwbare uitvoering te garanderen.

• Het wijzigen, verwijderen of vervangen van eventuele bestanden of mappen waarnaar wordt verwezen terwijl de opdracht wordt uitgevoerd, kan ertoe leiden dat de bewerking mislukt of leidt tot inconsistente gegevensopname.
• Controleer voordat u COPY INTOdeze uitvoert of alle brongegevens stabiel zijn en niet worden gewijzigd tijdens het proces.

Als de brongegevens een grotere precisie hebben dan de definitie van de doelkolom, wordt de waarde afgekapt, niet afgerond voor numerieke, datum- en tijdtypen.

Examples

A. Laden vanuit een openbaar opslagaccount

In het volgende voorbeeld ziet u de eenvoudigste vorm van de COPY opdracht, waarmee gegevens uit een openbaar opslagaccount worden geladen. In dit voorbeeld komen de standaardwaarden van de COPY instructie overeen met de indeling van het CSV-bestand met regelitems.

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

De standaardwaarden van de opdracht COPY zijn:

• DATEFORMAT = Sessie DATEFORMAT

• MAXERRORS = 0

• COMPRESSION Standaard is ongecomprimeerd

• FIELDQUOTE = '"'

• FIELDTERMINATOR = ','

• ROWTERMINATOR = '\n'

• FIRSTROW = 1

• ENCODING = 'UTF8'

• FILE_TYPE = 'CSV'

• IDENTITY_INSERT = 'UIT'

B. Verificatie laden via Share Access Signature (SAS)

In het volgende voorbeeld worden bestanden geladen die gebruikmaken van de regelfeed als een rijeindteken, zoals een UNIX-uitvoer. In dit voorbeeld wordt ook een SAS-sleutel gebruikt om te verifiëren bij Azure Blob Storage.

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

C. Laden met een kolomlijst met standaardwaarden die worden geverifieerd via opslagaccountsleutel

In dit voorbeeld worden bestanden geladen die een kolomlijst met standaardwaarden opgeven.

--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. Parquet of ORC laden met een bestaand bestandsindelingsobject

In dit voorbeeld wordt een jokerteken gebruikt om alle Parquet-bestanden onder een map te 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 met jokertekens en meerdere bestanden

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 met MSI-referenties

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 met automatische schemadetectie

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

Hoe verhoudt de prestaties van de opdracht COPY zich tot PolyBase?

De prestaties van de opdracht COPY kunnen beter zijn, afhankelijk van uw workload.

• Het magazijn kan gecomprimeerde bestanden niet automatisch splitsen. Voor de beste laadprestaties kunt u overwegen uw invoer op te splitsen in meerdere bestanden bij het laden van gecomprimeerde CSV's.

• Het magazijn kan automatisch grote niet-gecomprimeerde CSV-bestanden splitsen voor parallel laden, zodat u meestal niet handmatig niet-gecomprimeerde CSV-bestanden hoeft te splitsen. In bepaalde gevallen waarin automatische bestandssplitsing niet haalbaar is vanwege gegevenskenmerken, kan het handmatig splitsen van grote CSV's nog steeds de prestaties verbeteren.

Wat is de richtlijnen voor het splitsen van bestanden voor de opdracht COPY voor het laden van gecomprimeerde CSV-bestanden?

De volgende tabel bevat een overzicht van het aantal bestanden dat u moet gebruiken. Wanneer u het aanbevolen aantal bestanden bereikt, krijgt u betere prestaties met grotere bestanden. Het aantal bestanden wordt bepaald door het aantal rekenknooppunten vermenigvuldigd met 60. Bij 6000 DWU hebt u bijvoorbeeld 12 rekenknooppunten, dus u hebt 12 * 60 = 720 partities. Zie Copy Load Throughput maximaliseren met bestandssplitsingen voor een eenvoudige ervaring voor het splitsen van bestanden.

DWU	Aantal bestanden
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

Wat zijn de richtlijnen voor het splitsen van bestanden voor de COPY-opdracht voor het laden van Parquet- of ORC-bestanden?

U hoeft Parquet- en ORC-bestanden niet te splitsen omdat de opdracht COPY bestanden automatisch splitst. Voor de beste prestaties moeten Parquet- en ORC-bestanden in het Azure-opslagaccount 256 MB of groter zijn.

Zijn er beperkingen voor het aantal of de grootte van bestanden?

Er gelden geen beperkingen voor het aantal bestanden of de grootte van bestanden. Gebruik voor de beste prestaties echter bestanden die ten minste 4 MB zijn. Beperk ook het aantal bronbestanden tot maximaal 5000 bestanden voor betere prestaties.

Zijn er bekende problemen met de COPY-instructie?

Als u een Azure Synapse werkruimte hebt die u vóór 7 december 2020 hebt gemaakt, treedt er mogelijk een vergelijkbaar foutbericht op bij het verifiëren met behulp van beheerde identiteit: com.microsoft.sqlserver.jdbc.SQLServerException: Managed Service Identity isn't enabled on this server. Please enable Managed Service Identity and try again.

U kunt dit probleem omzeilen door de beheerde identiteit van de werkruimte opnieuw te registreren:

1. Installeer Azure PowerShell. Zie PowerShell installeren.
2. Registreer de beheerde identiteit van uw werkruimte met behulp van PowerShell:

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

Verwante inhoud

• overzicht Laden met Azure Synapse Analytics-

van toepassing op:Warehouse in Microsoft Fabric

In dit artikel wordt uitgelegd hoe u de instructie COPY in Warehouse gebruikt in Microsoft Fabric voor het laden van externe opslagaccounts. De instructie COPY biedt de meeste flexibiliteit voor gegevensopname met hoge doorvoer in uw warehouse in Microsoft Fabric en is als strategie voor het Ingest gegevens in uw warehouse in Microsoft Fabric.

In Fabric Data Warehouse ondersteunt de instructie COPY momenteel CSV-, JSONL- en PARQUET-bestandsindelingen. Voor gegevensbronnen worden Azure Data Lake Storage Gen2 accounts en OneLake-bronnen ondersteund.

Zie Gegevens opnemen COPY INTO voor meer informatie over het gebruik van uw magazijn in Microsoft Fabric.

Standaard wordt COPY INTO geverifieerd als de gebruiker die Microsoft Entra ID uitvoert.

Gebruik COPY voor de volgende mogelijkheden:

• Gebruik gebruikers met lagere bevoegdheden om gegevens te laden zonder strikte CONTROL-machtigingen voor het magazijn nodig te hebben.
• Voer één T-SQL-instructie uit zonder dat u andere databaseobjecten hoeft te maken.
• CSV-bestanden correct parseren en laden, waarbij scheidingstekens (tekenreeks, veld, rij) worden ge escaped binnen kolommen met tekenreeksscheidingstekens.
• JSONL-bestanden correct parseren en laden waarbij elke regel een geldig JSON-object is en velden worden toegewezen met behulp van JSON-padexpressies.
• Geef een nauwkeuriger machtigingsmodel op zonder opslagaccountsleutels beschikbaar te maken met behulp van Shared Access Signatures (SAS).
• Gebruik een ander opslagaccount voor de ERRORFILE locatie (REJECTED_ROW_LOCATION).
• Pas standaardwaarden voor elke doelkolom aan en geef brongegevensvelden op die moeten worden geladen in specifieke doelkolommen.
• Specificeer een aangepaste rijterminator, veldterminator en veldquote voor CSV-bestanden.
• Geef jokertekens en meerdere bestanden op in het pad naar de opslaglocatie.
• Zie Gegevens opnemen in uw warehouse in Microsoft Fabric met behulp van de copy-instructie voor meer informatie over opties en aanbevolen procedures voor gegevensopname.

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

Optioneel als het huidige magazijn voor de gebruiker die de bewerking uitvoert het magazijn van de opgegeven tabel is. Als u geen magazijn opgeeft en het opgegeven schema en de opgegeven tabel niet bestaan in het huidige magazijn, COPY mislukt en wordt er een foutbericht geretourneerd.

schema_name

Optioneel als het standaardschema voor de gebruiker die de bewerking uitvoert, het schema van de opgegeven tabel is. Als u geen schema opgeeft en het standaardschema van de gebruiker die de COPY bewerking uitvoert, verschilt van het schema van de opgegeven tabel, COPY wordt geannuleerd en wordt er een foutbericht geretourneerd.

tabelnaam

De naam van de tabel om in te COPY data. De doeltabel moet al aanwezig zijn in het magazijn.

(column_list)

Een optionele lijst met kolommen die worden gebruikt om brongegevensvelden toe te wijzen aan tabelkolommen tijdens het laden van gegevens.

column_list moet tussen haakjes staan en gescheiden door komma's. De structuur is als volgt:

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

• Column_name : de naam van de kolom in de doeltabel.
• Default_value - de standaardwaarde die elke NULL waarde in het invoerbestand vervangt. De standaardwaarde is van toepassing op alle bestandsindelingen. COPY Probeert te laden NULL vanuit het invoerbestand wanneer een kolom wordt weggelaten uit de kolomlijst of wanneer er een leeg invoerbestand is. De standaardwaarde wordt voorafgegaan door het trefwoord 'standaard'
• Field_number : alleen van toepassing op CSV-bestanden. Hiermee geeft u de rangtelpositie van het veld in de invoergegevens. De veldindexering begint bij 1.
• JSON_path : alleen van toepassing op JSONL-bestanden. Hiermee geeft u een JSON-padexpressie op waarmee het veld wordt geïdentificeerd dat moet worden geëxtraheerd uit elk JSON-object (bijvoorbeeld $.CustomerName).

Wanneer u geen column_list opgeeft, COPY worden kolommen toegewezen op basis van de bron- en doelvolgorde: invoerveld 1 gaat naar doelkolom 1, veld 2 gaat naar kolom 2, enzovoort.

Wanneer u geen kolomlijst opgeeft, COPY worden kolommen toegewezen op basis van de bron- en doelvolgorde: Invoerveld 1 gaat naar doelkolom 1, veld 2 gaat naar kolom 2, enzovoort.

Externe locatie

Hiermee geeft u op waar de bestanden met de gegevens worden gefaseerd. Momenteel worden Azure Data Lake Storage (ADLS) Gen2, Azure Blob Storage en OneLake ondersteund:

• externe locatie voor Blob Storage: https://<account\>.blob.core.windows.net/<container\>/<path\>
• externe locatie voor ADLS Gen2: https://<account\>.dfs.core.windows.net/<container\>/<path\>
• Externe locatie voor OneLake: https://onelake.dfs.fabric.microsoft.com/<workspaceId>/<lakehouseId>/Files/

Azure Data Lake Storage (ADLS) Gen2 biedt betere prestaties dan Azure Blob Storage (verouderd). Overweeg waar mogelijk een ADLS Gen2-account te gebruiken.

• account - De naam van het opslagaccount

• Container - De naam van de blobcontainer

• pad : de map of het bestandspad voor de gegevens. De locatie begint vanuit de container. Als u een map opgeeft, COPY haalt u alle bestanden op uit de map en alle bijbehorende submappen. COPY negeert verborgen mappen en retourneert geen bestanden die beginnen met een onderstreping (_) of een punt (.), tenzij expliciet is opgegeven in het pad. Dit gedrag is hetzelfde, zelfs wanneer u een pad met een jokerteken opgeeft.

Jokertekens kunnen worden opgenomen in het pad waar

• Naam van jokertekenpad komt overeen met hoofdlettergevoelig
• U kunt een jokerteken escapen met behulp van het backslash-teken (\)

U kunt meerdere bestandslocaties alleen vanuit hetzelfde opslagaccount en dezelfde container opgeven via een door komma's gescheiden lijst, zoals:

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

externe locaties achter firewall-

Voor toegang tot bestanden op Azure Data Lake Storage (ADLS) Gen2- en Azure Blob Storage-locaties die zich achter een firewall bevinden, zijn de volgende vereisten van toepassing:

• Een werkruimte-id voor de werkruimte die als host fungeert voor uw magazijn, moet worden ingericht. Zie Werkruimte-identiteitvoor meer informatie over het instellen van een werkruimte-id.
• Uw Entra ID-account moet de werkruimte-id kunnen gebruiken.
• Uw Entra ID-account moet toegang hebben tot de onderliggende bestanden via op rollen gebaseerd toegangsbeheer (RBAC) van Azure of data lake-ACL's.
• Uw Fabric-werkruimte die als host fungeert voor het magazijn, moet worden toegevoegd als een regel voor resource-exemplaar. Zie Regel voor resource-exemplarenvoor meer informatie over het toevoegen van uw Infrastructuurwerkruimte met een regel voor een resource-exemplaar.

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

FILE_TYPE hiermee geeft u de indeling van de externe gegevens.

• CSV: Hiermee geeft u een bestand met door komma's gescheiden waarden op dat voldoet aan de RFC 4180-standaard .
• JSONL: Hiermee geeft u een JSON-bestand (JSON-regels) met nieuwe regels op, waarbij elke regel een geldig JSON-object is.
• PARQUET: Hiermee geeft u een Parquet-indeling op.

REFERENTIE (IDENTITEIT = '', SECRET = '')

CREDENTIAL Hiermee geeft u het verificatiemechanisme op voor toegang tot het externe opslagaccount.

In Fabric Data Warehouse:

• COPY INTO wordt niet ondersteund wanneer openbare toegang is uitgeschakeld.
• Voor accounts met openbare opslag zijn de ondersteunde verificatiemechanismen Microsoft Entra ID, Shared Access Signature (SAS) of Storage Account Key (SAK).
• Voor accounts met openbare opslag achter een firewall is Microsoft Entra ID-verificatie de enige ondersteunde verificatiemethode. COPY INTO het gebruik van OneLake als bron ondersteunt alleen EntraID-verificatie.

De Microsoft Entra ID-verificatie van de gebruiker is standaard. Er hoeft geen referentie te worden opgegeven.

• Verifiëren met Shared Access Signature (SAS)
  • IDENTITY: Een constante met een waarde van Shared Access Signature.
  • SECRET: de handtekening voor gedeelde toegang biedt gedelegeerde toegang tot resources in uw opslagaccount.
  • Minimaal vereiste machtigingen: LEZEN en LIJSTEN.
• Verifiëren met opslagaccountsleutel
  • IDENTITY: Een constante met een waarde van Storage Account Key.
  • SECRET: Sleutel opslagaccount.

ERRORFILE = Maplocatie

ERRORFILE van toepassing op CSV en JSONL. Hiermee geeft u de map waarin de geweigerde rijen en het bijbehorende foutbestand moeten worden geschreven. U kunt het volledige pad opgeven vanuit het opslagaccount of het pad ten opzichte van de container. Als het opgegeven pad niet bestaat, maakt het systeem er een namens u. Er wordt een onderliggende map gemaakt met de naam _rejectedrows. Het _ teken zorgt ervoor dat de map wordt ontsnapt voor andere gegevensverwerking, tenzij deze expliciet is benoemd in de locatieparameter.

Binnen deze map maakt het magazijn een map op basis van de tijd van het laden in de indeling YearMonthDay -HourMinuteSecond (bijvoorbeeld 20180330-173205). In deze map maakt het magazijn een map met de instructie-id en onder die map worden twee typen bestanden geschreven: een fout. Json-bestand met de weigeringsredenen en een row.csv-bestand met de geweigerde rijen.

Als ERRORFILE het volledige pad van het opslagaccount is gedefinieerd, wordt het ERRORFILE_CREDENTIAL gebruikt om verbinding te maken met die opslag. Anders wordt de vermelde waarde CREDENTIAL gebruikt. Wanneer dezelfde referentie wordt gebruikt voor de brongegevens ERRORFILE, gelden er beperkingen die ook van ERRORFILE_CREDENTIAL toepassing zijn.

Wanneer u een met een firewall beveiligd Azure Storage-account gebruikt, wordt het foutenbestand gemaakt in dezelfde container die is opgegeven in het pad van het opslagaccount. Bij het gebruik van de ERRORFILE optie in dit scenario is het ook vereist om de MAXERROR parameter op te geven. Als ERRORFILE het volledige pad van het opslagaccount is gedefinieerd, wordt het ERRORFILE_CREDENTIAL gebruikt om verbinding te maken met die opslag. Anders wordt de vermelde waarde CREDENTIAL gebruikt.

ERRORFILE_CREDENTIAL = (IDENTITEIT = '', SECRET = '')

ERRORFILE_CREDENTIAL van toepassing op CSV- en JSONL-bestanden. In Warehouse in Microsoft Fabric is het enige ondersteunde verificatiemechanisme Shared Access Signature (SAS).

• Verifiëren met Shared Access Signatures (SAS)
  • IDENTITY: Een constante met een waarde van Shared Access Signature
  • SECRET: de handtekening voor gedeelde toegang biedt gedelegeerde toegang tot resources in uw opslagaccount.
• Minimale machtigingen vereist: LEZEN, LIJST, SCHRIJVEN, MAKEN, VERWIJDEREN

MAXERRORS = max_errors

MAXERRORS van toepassing op CSV en JSONL. Hiermee geeft u het maximum aantal geweigerde rijen op dat is toegestaan in de belasting voordat de COPY bewerking mislukt. Elke rij die de COPY bewerking niet kan importeren wordt genegeerd en als één fout geteld. Als u geen maximum aantal fouten opgeeft, is de standaardwaarde 0.

In Fabric Data Warehouse kunt u MAXERRORS niet gebruiken wanneer FILE_TYPE is PARQUET.

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

COMPRESSION is optioneel en geeft de methode voor gegevenscompressie voor de externe gegevens op.

• CSV ondersteunt GZIP.
• Parquet ondersteunt GZIP en Snappy.
• Niet ondersteund voor JSONL

Het COPY commando detecteert automatisch het compressietype op basis van de bestandsextensie wanneer deze parameter niet is opgegeven:

• .gz - GZIP

Het laden van gecomprimeerde bestanden wordt momenteel alleen ondersteund met parserversie 1.0.

De COPY opdracht vereist dat gzip-bestanden geen volgvuil bevatten om normaal te werken. De gzip-indeling vereist strikt dat bestanden bestaan uit geldige leden zonder aanvullende informatie voor, tussen of na de bestanden. Elke afwijking van deze indeling, zoals de aanwezigheid van niet-gzip-gegevens, resulteert in de fout van de COPY opdracht. Om ervoor te zorgen dat COPY de uitvoering is geslaagd, controleert u of er geen volgvuil is aan het einde van gzip-bestanden.

FIELDQUOTE = 'field_quote'

FIELDQUOTE is alleen van toepassing op CSV. Hiermee geeft u één teken op dat wordt gebruikt als het aanhalingsteken (tekenreeksscheidingsteken) in het CSV-bestand. Als u dit niet opgeeft FIELDQUOTE, wordt het aanhalingsteken (") gebruikt als het aanhalingsteken zoals gedefinieerd in de RFC 4180-standaard. Hexadecimale notatie wordt ook ondersteund voor FIELDQUOTE. Uitgebreide ASCII- en multibytetekens worden niet ondersteund met UTF-8 voor FIELDQUOTE.

FIELDTERMINATOR = 'field_terminator'

FIELDTERMINATOR is alleen van toepassing op CSV. Hiermee geeft u het veldeindteken op dat wordt gebruikt in het CSV-bestand. U kunt ook het veldeindteken opgeven met behulp van hexadecimale notatie. Het veldeindteken kan multicharacter zijn. Het standaardveldeindteken is een (,). Uitgebreide ASCII- en multibytetekens worden niet ondersteund met UTF-8 voor FIELDTERMINATOR.

ROWTERMINATOR = 'row_terminator'

ROWTERMINATOR is alleen van toepassing op CSV. Hiermee geeft u het rijeindteken op dat wordt gebruikt in het CSV-bestand. U kunt het rijeindteken opgeven met behulp van hexadecimale notatie. Het rijeindteken kan multicharacter zijn. De standaardeindtekens zijn \r\n, \nen \r.

Het COPY commando geeft het \r teken een voorvoegsel wanneer (nieuwe regel) wordt gespecificeerd \n , wat resulteert in \r\n. Als u alleen het \n teken wilt opgeven, gebruikt u hexadecimale notatie (0x0A). Wanneer u rijeindtekens voor meerdere tekens opgeeft in hexadecimaal, geeft u niet 0x op tussen elk teken.

Uitgebreide ASCII- en multibytetekens worden niet ondersteund met UTF-8 voor ROWTERMINATOR.

FIRSTROW = First_row_int

FIRSTROW is alleen van toepassing op CSV. Geeft het rijnummer aan dat als eerste wordt gelezen in alle bestanden voor het COPY commando. Waarden beginnen vanaf 1, wat de standaardwaarde is. Als u de waarde 2instelt op, wordt de eerste rij in elk bestand (veldnamenrij) overgeslagen wanneer de gegevens worden geladen. Rijen worden overgeslagen op basis van het bestaan van rijeindtekens.

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

DATEFORMAT is van toepassing op CSV en JSONL. Hiermee geeft u de datumnotatie van de datumtoewijzing aan SQL Server datumnotaties. Zie datum- en tijdgegevenstypen en -functies (Transact-SQL)voor een overzicht van alle Transact-SQL datum- en tijdgegevenstypen en -functies. DATEFORMAT binnen het COPY commando heeft voorrang boven DATEFORMAT dat op sessieniveau is geconfigureerd.

ENCODING = 'UTF8' | 'UTF16'

ENCODING van toepassing op CSV en JSONL. De standaardwaarde is UTF8. Specificeert de datacoderingsstandaard voor de bestanden die door het commando COPY worden geladen.

PARSER_VERSION = { '1,0' | '2.0' }

PARSER_VERSION is alleen van toepassing op CSV-bestanden. De standaardwaarde is 2.0. PARSER_VERSION hiermee geeft u de bestandsparser die wordt gebruikt voor opname wanneer het bronbestandstype CSV is. De 2.0-parser biedt verbeterde prestaties voor het opnemen van CSV-bestanden.

Parser versie 2.0 heeft de volgende beperkingen:

• Gecomprimeerde CSV-bestanden worden niet ondersteund.
• Bestanden met UTF-16-codering worden niet ondersteund.
• Multicharacter of multibyte ROWTERMINATOR, FIELDTERMINATORof FIELDQUOTE wordt niet ondersteund. Wordt echter \r\n als standaard ROWTERMINATORgeaccepteerd.

Wanneer u parserversie 1.0 gebruikt met UTF-8-bestanden, worden multibyte- en multicharacter-eindtekens niet ondersteund voor FIELDTERMINATOR.

Parser versie 1.0 is alleen beschikbaar voor compatibiliteit met eerdere versies. Gebruik deze alleen wanneer u deze beperkingen ondervindt.

MATCH_COLUMN_COUNT = { 'AAN' | 'UIT' }

MATCH_COLUMN_COUNT is alleen van toepassing op CSV-bestanden. De standaardwaarde is OFF. Hiermee wordt aangegeven of de COPY opdracht moet controleren of de rijen met het aantal kolommen in bronbestanden overeenkomen met het aantal kolommen van de doeltabel. Het volgende gedrag is van toepassing:

• Als MATCH_COLUMN_COUNT dit het volgende is OFF:
  • De opdracht negeert het overschrijden van kolommen uit bronrijen.
    • Met de opdracht worden waarden ingevoegd NULL in null-kolommen voor rijen met minder kolommen.
  • Als een waarde niet is opgegeven voor een niet-null-bare kolom, mislukt de COPY opdracht.
• Als MATCH_COLUMN_COUNT dit het volgende is ON:
  • Het COPY commando controleert of het kolomaantal op elke rij in elk bestand uit de bron overeenkomt met het aantal kolommen van de bestemmingstabel.
• Als het aantal kolommen niet overeenkomt, mislukt de COPY opdracht.

COPY INTO gebruiken met OneLake

Gebruik COPY INTO om gegevens rechtstreeks te laden uit bestanden die zijn opgeslagen in de Fabric OneLake, onder bestaande items. Deze methode elimineert de noodzaak voor externe faseringsaccounts, zoals ADLS Gen2 of Blob Storage, en maakt systeemeigen SaaS-opname met behulp van Fabric machtigingen mogelijk. Deze functionaliteit ondersteunt:

• Lezen vanaf elke locatie in een werkruimte en een item
• Werkruimte-naar-magazijnbelastingen binnen dezelfde tenant
• Systeemeigen identiteits afdwingen met behulp van 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

Machtigingen voor besturingsvlak

Als u de COPY INTO opdracht wilt uitvoeren, moet u lid zijn van een werkruimterol via Toegang beheren in de werkruimte, met ten minste de rol Viewer. U kunt ook magazijntoegang delen met een gebruiker via M-machtigingen in de Fabric-portal, met ten minste leesmachtigingen. Leesmachtigingen zijn voldoende om te voldoen aan het principe van minimale bevoegdheden.

Machtigingen voor het gegevensvlak

Nadat u machtigingen voor het besturingsvlak hebt verleend via werkruimterollen of itemmachtigingen, verleent de gebruiker, als de gebruiker alleen leesmachtigingen heeft op het niveau van het gegevensvlak, ook de gebruiker INSERT en ADMINISTER DATABASE BULK OPERATIONS machtigingen met behulp van T-SQL-opdrachten.

Het volgende T-SQL-script verleent deze machtigingen bijvoorbeeld aan een afzonderlijke gebruiker met behulp van hun Microsoft Entra ID.

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

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

Wanneer u de optie foutbestand gebruikt, moet de gebruiker de minimale machtiging van Blob Storage Inzender hebben voor de container van het opslagaccount.

Wanneer u OneLake als bron gebruikt, moet de gebruiker inzender - of hogere machtigingen hebben voor zowel de bronwerkruimte (waar Lakehouse zich bevindt) als de doelwerkruimte (waar het magazijn zich bevindt). Microsoft Entra ID en Fabric werkruimterollen bepalen alle toegang.

Remarks

De COPY instructie accepteert alleen UTF-8 en UTF-16 geldige tekens voor rijgegevens en commandoparameters. Als u bronbestanden of parameters (zoals ROWTERMINATOR of FIELDTERMINATOR) gebruikt die ongeldige tekens bevatten, kan de COPY instructie deze onjuist interpreteren en onverwachte resultaten veroorzaken, zoals beschadiging van gegevens of andere fouten. Voordat u de COPY instructie aanroept, moet u ervoor zorgen dat uw bronbestanden en -parameters UTF-8- of UTF-16-compatibel zijn.

De COPY INTO instructie heeft beperkingen voor de grootte van afzonderlijke kolommen varchar(max) en varbinary(max) en voor de totale rijgrootte die u kunt opnemen.

• Parquet: maximale varchar(max)/varbinary(max) kolomgrootte 16 MB, maximale rijgrootte 1 GB.
• CSV en JSONL: maximale varchar(max)/varbinary(max) kolomgrootte 1 MB, maximale rijgrootte 16 MB.

Wijzig de bronbestanden en mappen tijdens de COPY INTO bewerking niet om een betrouwbare uitvoering te garanderen.

• Het wijzigen, verwijderen of vervangen van eventuele bestanden of mappen waarnaar wordt verwezen terwijl de opdracht wordt uitgevoerd, kan ertoe leiden dat de bewerking mislukt of leidt tot inconsistente gegevensopname.
• Controleer voordat u COPY INTOdeze uitvoert of alle brongegevens stabiel zijn en niet tijdens het proces worden gewijzigd.

Als de brongegevens een grotere precisie hebben dan de definitie van de doelkolom, wordt de waarde afgekapt, niet afgerond voor numerieke, datum- en tijdtypen.

Beperkingen voor OneLake als bron

• Alleen Microsoft Entra ID-verificatie wordt ondersteund. Andere verificatiemethoden, zoals SAS-tokens, gedeelde sleutels of verbindingsreeksen, zijn niet toegestaan.

• Magazijnitems worden niet ondersteund als bronlocaties. Bestanden moeten afkomstig zijn van andere Fabric-items die bestanden beschikbaar maken via OneLake-opslag.

• OneLake-paden moeten werkruimte- en magazijn-id's gebruiken. Beschrijvende namen voor werkruimten of Lakehouses worden momenteel niet ondersteund.

• Inzendermachtigingen zijn vereist voor beide werkruimten. De uitvoerende gebruiker moet ten minste de rol Inzender hebben voor de bronwerkruimte Lakehouse en de doelwerkruimte Warehouse.

Examples

Zie Gegevens opnemen COPY INTO voor meer informatie over het gebruik van uw magazijn in Microsoft Fabric.

A. Laden vanuit een openbaar opslagaccount

In het volgende voorbeeld ziet u de eenvoudigste vorm van de COPY opdracht, waarmee gegevens uit een openbaar opslagaccount worden geladen. In dit voorbeeld komen de standaardwaarden van de COPY instructie overeen met de indeling van het CSV-bestand met regelitems.

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

De standaardwaarden van het COPY commando zijn:

• MAXERRORS = 0

• COMPRESSION (standaard is niet gecomprimeerd)

• FIELDQUOTE = '"'

• FIELDTERMINATOR = ','

• ROWTERMINATOR = '\n'

  Important

  COPY behandelt \n het intern \r\n . Zie de ROWTERMINATOR sectie voor meer informatie.

• FIRSTROW = 1

• ENCODING = 'UTF8'

• FILE_TYPE = 'CSV'

B. Verificatie laden via Share Access Signature (SAS)

In het volgende voorbeeld worden bestanden geladen die gebruikmaken van de regelfeed als een rijeindteken, zoals een UNIX-uitvoer. In dit voorbeeld wordt ook een SAS-sleutel gebruikt om te verifiëren bij Azure Blob Storage.

COPY INTO test_1
FROM 'https://myaccount.blob.core.windows.net/myblobcontainer/folder1/'
WITH (
    FILE_TYPE = 'CSV',
    CREDENTIAL=(IDENTITY= 'Shared Access Signature', SECRET='<Your_SAS_Token>'),
    FIELDQUOTE = '"',
    FIELDTERMINATOR = ';',
    ROWTERMINATOR = '0X0A',
    ENCODING = 'UTF8',
    MAXERRORS = 10,
    ERRORFILE = '/errorsfolder'--path starting from the storage container
)

C. Laden met een kolomlijst met standaardwaarden die worden geverifieerd via SAK (Storage Account Key)

In dit voorbeeld worden bestanden geladen die een kolomlijst met standaardwaarden opgeven.

--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. Parquet laden

In dit voorbeeld wordt een jokerteken gebruikt om alle Parquet-bestanden onder een map te laden met behulp van de Entra ID van de gebruiker die wordt uitgevoerd.

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

E. JSONL laden

In dit voorbeeld wordt een jokerteken gebruikt om alle JSONL-bestanden onder een map te laden met behulp van de Entra ID van de gebruiker.

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

F. Kolomnamen toewijzen aan veldpaden in JSONL-documenten

In het volgende voorbeeld ziet u een JSON Lines-bestand (JSONL), waarbij elke regel één JSON-object vertegenwoordigt:

{"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 INTOkunt u tabelkolommen toewijzen aan specifieke JSON-velden met behulp van JSON-padexpressies. Met deze toewijzing kunt u alleen de vereiste velden uit de brongegevens opnemen.

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. Gegevens laden door jokertekens en meerdere bestanden op te geven

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. Gegevens laden uit OneLake

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

Verwante inhoud

• gegevens opnemen in uw warehouse in Microsoft Fabric
• gegevens opnemen in uw magazijn met behulp van de COPY-instructie