COPIA IN (Transact-SQL)

Si applica a:Azure Synapse Analytics

Tip

Microsoft Fabric Data Warehouse è un data warehouse relazionale su scala aziendale su una base data lake, con un'architettura futura, un'intelligenza artificiale predefinita e nuove funzionalità. Se non si ha familiarità con il data warehousing, iniziare con Fabric Data Warehouse. I carichi di lavoro esistenti del pool SQL dedicated possono eseguire l'aggiornamento a Fabric per accedere a nuove funzionalità tra data science, analisi in tempo reale e creazione di report.

• Inizia una prova gratuita di Fabric.
• Assistente alla migrazione per Fabric Data Warehouse.

Questo articolo illustra come usare l'istruzione /> COPY dichiarazione offre la massima flessibilità per l'ingestione dati ad alto throughput in Azure Synapse Analytics.

Note

Per Warehouse in Microsoft Fabric, vedere COPY INTO.

Utilizzo COPY per le seguenti funzionalità:

• Usare utenti con privilegi inferiori per caricare i dati senza richiedere autorizzazioni CONTROL rigorose per il data warehouse.
• Eseguire una singola istruzione T-SQL senza dover creare altri oggetti di database.
• Analizzare e caricare correttamente i file CSV in cui i delimitatori (stringa, campo, riga) vengono preceduti da un carattere di escape all'interno di colonne delimitate da stringhe.
• Specificare un modello di autorizzazione più fine senza esporre le chiavi dell'account di archiviazione usando firme di accesso condiviso.
• Usa un account di archiviazione diverso per la ERRORFILE posizione (REJECTED_ROW_LOCATION).
• Personalizzare i valori predefiniti per ogni colonna di destinazione e specificare i campi dati di origine da caricare in colonne di destinazione specifiche.
• Specifica un terminatore di riga, un terminatore di campo e una citazione di campo personalizzati per i file CSV.
• Usare SQL Server formati di data per i file CSV.
• Specificare caratteri jolly e più file nel percorso di archiviazione.
• L'individuazione automatica dello schema semplifica il processo di definizione e mapping dei dati di origine nelle tabelle di destinazione.
• Il processo di creazione automatica delle tabelle crea automaticamente le tabelle e funziona insieme all'individuazione automatica dello schema.
• Caricare direttamente tipi di dati complessi da file Parquet, ad esempio Mappe ed Elenchi in colonne stringa, senza usare altri strumenti per pre-elaborare i dati.

Note

Per caricare tipi di dati complessi da file Parquet, attivare la creazione automatica della tabella usando AUTO_CREATE_TABLE.

Per esempi completi e guide introduttive sull'uso dell'istruzione COPY , vedere:

• Guida introduttiva: Caricare in blocco i dati usando l'istruzione COPY
• Guida introduttiva: Esempi che usano l'istruzione COPY e i relativi metodi di autenticazione supportati
• Guida introduttiva: Creazione dell'istruzione COPY con l'interfaccia utente avanzata di Synapse Studio

Note

Microsoft Entra ID era precedentemente conosciuto come Azure Active Directory (Azure AD).

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

Facoltativo se lo schema predefinito per l'utente che esegue l'operazione è lo schema della tabella specificata. Se non si specifica lo schema e lo schema predefinito dell'utente che esegue l'operazione COPY è diverso dallo schema della tabella specificata, l'operazione COPY viene annullata e viene restituito un messaggio di errore.

nome_tabella

Nome della tabella in cui copiare i dati. La tabella di destinazione può essere temporanea o permanente e deve già esistere nel database. Per la modalità di rilevamento automatico dello schema, non fornire un elenco di colonne.

(column_list)

Elenco facoltativo di una o più colonne utilizzate per eseguire il mapping dei campi dati di origine alle colonne della tabella di destinazione per il caricamento dei dati.

Non specificare un column_list quando AUTO_CREATE_TABLE = 'ON'.

Il valore di column_list deve essere racchiuso tra parentesi e delimitato da virgole. L'elenco di colonne ha il formato seguente:

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

• Column_name - Nome della colonna nella tabella di destinazione.
• Default_value: valore predefinito che sostituisce qualsiasi valore NULL nel file di input. Il valore predefinito si applica a tutti i formati di file. COPY tenta di caricare NULL dal file di input quando una colonna viene omessa dall'elenco di colonne o quando è presente un campo di file di input vuoto. Il valore predefinito precede la parola chiave 'default'
• Field_number: numero di campo del file di input mappato alla colonna di destinazione.
• L'indicizzazione del campo inizia da 1.

Quando non si specifica un elenco di colonne, COPY esegue il mapping delle colonne in base all'ordine di origine e di destinazione: il campo di input 1 passa alla colonna 1 di destinazione, il campo 2 passa alla colonna 2 e così via.

Posizioni esterne

Percorso in cui vengono gestiti i file contenenti i dati. Attualmente sono supportati Azure Data Lake Storage (ADLS) Gen2 e Archiviazione BLOB di Azure:

• Percorso esterno per l'archiviazione BLOB: https://<account\>.blob.core.windows.net/<container\>/<path\>
• Percorso esterno per ADLS Gen2: https://<account\>.dfs.core.windows.net/<container\>/<path\>

Note

L'endpoint .blob è disponibile anche per ADLS Gen2 e attualmente offre le migliori prestazioni. Usare l'endpoint .blob quando .dfs non è necessario per il metodo di autenticazione.

• Account - Nome dell'account di archiviazione

• Contenitore - Nome del contenitore BLOB

• Percorso - Percorso di file o cartella per i dati. Il percorso inizia dal contenitore. Se si specifica una cartella, COPY recupera tutti i file dalla cartella e tutte le relative sottocartelle. COPY ignora le cartelle nascoste e non restituisce file che iniziano con una sottolineatura (_) o un punto (.) a meno che non venga specificato in modo esplicito nel percorso. Questo comportamento è identico anche quando si specifica un percorso con un carattere jolly.

È possibile includere caratteri jolly nel percorso in cui:

• Per la corrispondenza del nome del percorso con un carattere jolly viene fatta distinzione tra maiuscole e minuscole
• È possibile eseguire l'escape di un carattere jolly usando il carattere barra rovesciata (\)
• L'espansione del carattere jolly viene applicata in modo ricorsivo. Ad esempio, tutti i file CSV in Customer1 (incluse le sottodirectory di Customer1) vengono caricati nell'esempio seguente: Account/Container/Customer1/*.csv

Note

Per ottenere prestazioni ottimali, evitare di specificare caratteri jolly che si espandono su un numero maggiore di file. Se possibile, elencare più percorsi di file invece di specificare caratteri jolly.

È possibile specificare più percorsi di file solo dallo stesso account di archiviazione e contenitore tramite un elenco delimitato da virgole, ad esempio:

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

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

FILE_TYPE specifica il formato dei dati esterni.

• CSV: specifica un file di valori delimitati da virgole conforme allo standard RFC 4180 .
• PARQUET: specifica un formato Parquet.
• ORC: specifica un formato ORC (Optimized Row Columnar).

Note

Il tipo di file "Testo delimitato" in PolyBase viene sostituito dal formato di file "CSV". È possibile configurare il delimitatore virgola predefinito tramite il FIELDTERMINATOR parametro .

FILE_FORMAT = external_file_format_name

FILE_FORMAT si applica solo ai file Parquet e ORC. Specifica il nome dell'oggetto formato di file esterno che archivia il tipo di file e il metodo di compressione per i dati esterni. Per creare un formato di file esterno, usare CREATE EXTERNAL FILE FORMAT.

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

CREDENTIAL Specifica il meccanismo di autenticazione per accedere all'account di archiviazione esterno. I metodi di autenticazione sono i seguenti:

	CSV	Parquet	ORC
Archiviazione BLOB di Azure	SAS/MSI/PRINCIPALE DEL SERVIZIO/CHIAVE/Entra	SAS/KEY	SAS/KEY
Azure Data Lake Gen2	SAS/MSI/PRINCIPALE DEL SERVIZIO/CHIAVE/Entra	FIRMA di accesso condiviso (BLOB 1 )/MSI (dfs 2 )/ENTITÀ SERVIZIO/KEY/Entra	FIRMA di accesso condiviso (BLOB 1 )/MSI (dfs 2 )/ENTITÀ SERVIZIO/KEY/Entra

¹ L'endpoint blob (.blob.core.windows.net) nel percorso esterno è necessario per questo metodo di autenticazione.

² L'endpoint dfs (.dfs.core.windows.net) nel percorso esterno è necessario per questo metodo di autenticazione.

Note

• Quando si esegue l'autenticazione usando Microsoft Entra ID o un account di archiviazione pubblico, non è necessario specificare CREDENTIAL.
• Se l'account di archiviazione è associato a una rete virtuale, è necessario eseguire l'autenticazione usando un'identità gestita.

• Autenticazione con firme di accesso condiviso (SAS)

  • IDENTITY: costante con un valore di Shared Access Signature
  • SECRET: la firma di accesso condiviso fornisce l'accesso delegato alle risorse nell'account di archiviazione.

• Autorizzazioni minime necessarie: READ e LIST

• Autenticazione con entità servizio

  • IDENTITY: <ClientID>@<OAuth_2.0_Token_EndPoint>
  • SECRET: chiave dell'entità servizio dell'applicazione Microsoft Entra

• Ruoli di controllo degli accessi in base al ruolo minimi necessari: Collaboratore ai dati dei BLOB di archiviazione, Collaboratore ai dati dei BLOB di archiviazione, Proprietario dei dati dei BLOB di archiviazione o Lettore di dati BLOB di archiviazione

• Autenticazione con chiave dell'account di archiviazione

  • IDENTITY: costante con un valore di Storage Account Key
  • SECRET: chiave dell'account di archiviazione

• Autenticazione con identità gestita (endpoint servizio di rete virtuale)

  • IDENTITY: costante con un valore di Managed Identity

• Ruoli minimi di controllo degli accessi in base al ruolo necessari: Collaboratore ai dati dei BLOB di archiviazione o Proprietario dei dati BLOB di archiviazione per il server logico registrato da Microsoft Entra in Azure. Quando si usa un pool SQL dedicato (in precedenza SQL Data Warehouse) che non è associato a un'area di lavoro Synapse, questo ruolo controllo degli accessi in base al ruolo non è obbligatorio, ma l'identità gestita richiede autorizzazioni Controllo di accesso List (ACL) per gli oggetti di destinazione per abilitare l'accesso in lettura ai file di origine.

• Autenticazione con un utente di Microsoft Entra

  • CREDENTIAL non è obbligatorio

• Ruoli di controllo degli accessi in base al ruolo minimi richiesti: Collaboratore ai dati dei BLOB di archiviazione o Proprietario dei dati BLOB di archiviazione per l'utente Di Microsoft Entra

ERRORFILE = Percorso directory

ERRORFILE si applica solo a CSV. Specifica la directory all'interno dell'istruzione COPY in cui vengono scritte le righe rifiutate e il file di errore corrispondente. È possibile specificare il percorso completo dall'account di archiviazione o dal percorso relativo al contenitore. Se il percorso specificato non esiste, ne crea uno. Viene creata una directory figlio con il nome _rejectedrows. Il _ carattere garantisce che la directory venga preceduta da un carattere di escape per altre elaborazioni dati, a meno che non venga specificato in modo esplicito nel parametro location.

Note

Quando si passa un percorso relativo a ERRORFILE, impostarlo in relazione al percorso del contenitore specificato in external_location.

All'interno di questa directory, il warehouse crea una cartella in base al tempo di invio del carico nel formato YearMonthDay -HourMinuteSecond (ad esempio, 20180330-173205). In questa cartella il processo scrive due tipi di file: il file motivo (errore) e il file di dati (riga). Ogni file antepone il queryIDGUID di file , distributionIDe . Poiché i dati e il motivo si trovano in file distinti, i file corrispondenti hanno un prefisso corrispondente.

Se ERRORFILE ha il percorso completo dell'account di archiviazione definito, COPY usa ERRORFILE_CREDENTIAL per connettersi a tale risorsa di archiviazione. In caso contrario, usa il valore specificato per CREDENTIAL. Quando si usano le stesse credenziali per i dati di origine e ERRORFILE, le restrizioni applicabili si applicano ERRORFILE_CREDENTIAL anche.

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

ERRORFILE_CREDENTIAL si applica solo ai file CSV. Le origini dati e i metodi di autenticazione supportati sono i seguenti:

• Archiviazione BLOB di Azure: firma di accesso condiviso, entità servizio o Microsoft Entra

• Azure Data Lake Gen2: firma di accesso condiviso, identità del servizio gestita, entità servizio o Microsoft Entra

• Autenticazione con firme di accesso condiviso (SAS)

  • IDENTITY: costante con un valore di Shared Access Signature
  • SECRET: la firma di accesso condiviso fornisce l'accesso delegato alle risorse nell'account di archiviazione.

• Autorizzazioni minime necessarie: READ, LIST, WRITE, CREATE, DELETE

• Autenticazione con entità servizio

  • IDENTITY: <ClientID>@<OAuth_2.0_Token_EndPoint>
  • SECRET: chiave dell'entità servizio dell'applicazione Microsoft Entra

• Ruoli controllo degli accessi in base al ruolo minimi necessari: Collaboratore ai dati dei BLOB di archiviazione o Proprietario dei dati BLOB di archiviazione

Note

Usare l'endpoint di token OAuth 2.0 V1

• Autenticazione con identità gestita (endpoint servizio di rete virtuale)

  • IDENTITY: costante con un valore di Managed Identity

• Ruoli minimi di controllo degli accessi in base al ruolo necessari: Collaboratore ai dati dei BLOB di archiviazione o Proprietario dei dati BLOB di archiviazione per il server database SQL registrato da Microsoft Entra

• Autenticazione con un utente di Microsoft Entra

  • CREDENTIAL non è obbligatorio

• Ruoli di controllo degli accessi in base al ruolo minimi richiesti: Collaboratore ai dati dei BLOB di archiviazione o Proprietario dei dati BLOB di archiviazione per l'utente Di Microsoft Entra

L'uso di una chiave dell'account di archiviazione con ERRORFILE_CREDENTIAL non è supportato.

Note

Se si usa lo stesso account di archiviazione per il file di errore e si specifica il ERRORFILE percorso relativo alla radice del contenitore, non è necessario specificare .ERROR_CREDENTIAL

MAXERRORS = max_errors

MAXERRORS specifica il numero massimo di righe di rifiuto consentite nel carico prima che l'operazione COPY non riesca. Ogni riga che l'operazione COPY non può importare viene ignorata e conteggiata come un errore. Se non si specifica un valore per il numero massimo di errori, il valore predefinito è 0.

MAXERRORS non può essere usato con AUTO_CREATE_TABLE.

Quando FILE_TYPE è PARQUET, le eccezioni causate da errori di conversione del tipo di dati (ad esempio, binario Parquet in integer SQL) causano COPY INTO comunque errori, ignorando MAXERRORS.

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

COMPRESSION è facoltativo e specifica il metodo di compressione dei dati per i dati esterni.

• CSV supporta GZIP.
• Parquet supporta GZIP e Snappy.
• Il formato ORC supporta DefaultCodec e Snappy
• Zlib è la compressione predefinita per ORC.

Il comando COPY rileva automaticamente il tipo di compressione in base all'estensione di file quando non si specifica questo parametro:

• .gz - GZIP
• .snappy - Scattanti
• .deflate - DefaultCodec (solo Parquet e ORC)

Il comando COPY richiede che i file gzip non contengano alcun garbage finale per funzionare normalmente. Il formato gzip richiede rigorosamente che i file siano costituiti da membri validi senza informazioni aggiuntive prima, tra o dopo di esse. Qualsiasi deviazione da questo formato, ad esempio la presenza di dati finali non gzip, genera l'errore del comando COPY. Per assicurarsi che l'esecuzione di COPY venga eseguita correttamente, assicurarsi di verificare che non siano presenti operazioni di garbage finali alla fine dei file gzip.

FIELDQUOTE = 'field_quote'

FIELDQUOTE si applica a CSV e specifica un singolo carattere usato come carattere di virgolette (delimitatore di stringa) nel file CSV. Se non si specifica questo valore, il carattere virgolette (") viene usato come carattere di virgolette come definito nello standard RFC 4180. La notazione esadecimale è supportata anche per FIELDQUOTE. I caratteri ASCII estesi e multibyte non sono supportati con UTF-8 per FIELDQUOTE.

Note

I caratteri FIELDQUOTE vengono preceduti da un carattere di escape nelle colonne stringa in cui è presente un valore FIELDQUOTE (delimitatore) double.

FIELDTERMINATOR = 'field_terminator'

FIELDTERMINATOR si applica solo a CSV. Specifica il carattere di terminazione del campo usato nel file CSV. È possibile specificare il carattere di terminazione del campo usando la notazione esadecimale. Il carattere di terminazione del campo può essere multicaracter. Il carattere di terminazione del campo predefinito è (,). I caratteri ASCII estesi e multibyte non sono supportati con UTF-8 per FIELDTERMINATOR.

ROWTERMINATOR = 'row_terminator'

ROWTERMINATOR si applica solo a CSV. Specifica il carattere di terminazione della riga usato nel file CSV. È possibile specificare il terminatore di riga usando la notazione esadecimale. Il carattere di terminazione della riga può essere multicharacter. Per impostazione predefinita, il carattere di terminazione della riga è \r\n.

Il comando COPY antepone il \r carattere quando si \n specifica (nuova riga) con conseguente \r\n. Per specificare solo il carattere, usare la \n notazione esadecimale (0x0A). Quando si specificano caratteri di terminazione di riga a più caratteri in formato esadecimale, non specificare 0x tra ogni carattere.

I caratteri ASCII estesi e multibyte non sono supportati con UTF-8 per ROWTERMINATOR.

FIRSTROW = First_row_int

FIRSTROW si applica a CSV e specifica il numero di riga letto per primo in tutti i file per il comando COPY. I valori iniziano da 1, ovvero il valore predefinito. Se si imposta il valore su 2, la prima riga di ogni file (riga di intestazione) viene ignorata quando vengono caricati i dati. Le righe vengono ignorate in base alla presenza di caratteri di terminazione della riga.

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

DATEFORMAT si applica solo al formato CSV e specifica il formato di data per il mapping della data ai formati di data di SQL Server. Per una panoramica di tutte le funzioni e i tipi di dati di data e ora Transact-SQL, vedere Funzioni e tipi di dati di data e ora (Transact-SQL). DATEFORMAT all'interno del comando COPY ha la precedenza su DATEFORMAT configurato a livello di sessione.

ENCODING = 'UTF8' | 'UTF16'

ENCODING si applica solo a CSV. L'impostazione predefinita è UTF8. Specifica lo standard di codifica dei dati per i file caricati tramite il comando COPY.

IDENTITY_INSERT = 'ON' | 'OFF'

IDENTITY_INSERT specifica se il valore Identity o i valori nel file di dati importati devono essere utilizzati per la colonna Identity. Se IDENTITY_INSERT è OFF (impostazione predefinita), i valori Identity per questa colonna vengono verificati, ma non importati. Si noti il comportamento seguente con il comando COPY:

• Se IDENTITY_INSERT è OFF e la tabella ha una colonna Identity
  • È necessario specificare un elenco di colonne che non esegue il mapping di un campo di input alla colonna Identity.
• Se IDENTITY_INSERT è ON e la tabella ha una colonna Identity
  • Se si passa un elenco di colonne, è necessario eseguire il mapping di un campo di input alla colonna Identity.
• Il valore predefinito non è supportato per la colonna IDENTITY nell'elenco di colonne.
• È possibile impostare IDENTITY_INSERT per una sola tabella alla volta.

Azure Synapse Analytics assegna automaticamente valori univoci in base ai valori di inizializzazione e incremento specificati durante la creazione della tabella.

AUTO_CREATE_TABLE = { 'ON' | 'OFF' }

AUTO_CREATE_TABLE specifica se la tabella può essere creata automaticamente usando l'individuazione automatica dello schema. AUTO_CREATE_TABLE è disponibile solo per i file Parquet in Azure Synapse Analytics.

• ON: abilita la creazione automatica della tabella. Il COPY INTO processo crea automaticamente una nuova tabella individuando la struttura del file da caricare. È anche possibile usarlo con le tabelle preesistenti per sfruttare l'individuazione automatica dello schema dei file Parquet.
• OFF: la creazione automatica della tabella non è abilitata. Default.

Note

La creazione automatica della tabella funziona insieme all'individuazione automatica dello schema. La creazione automatica della tabella non è abilitata per impostazione predefinita.

Permissions

L'utente che esegue il comando COPY deve disporre delle autorizzazioni seguenti:

• AMMINISTRARE LE OPERAZIONI BULK DEL DATABASE
• INSERT

Sono necessarie le autorizzazioni INSERT e ADMINISTER BULK OPERATIONS. In Azure Synapse Analytics sono necessarie le autorizzazioni INSERT e ADMINISTER DATABASE BULK OPERATIONS.

Inoltre, se l'utente che esegue il comando COPY intende generare una nuova tabella e caricarvi dati, richiedono autorizzazioni CREATE TABLE e ALTER ON SCHEMA.

Ad esempio, per consentire l'uso di mike@contoso.com COPY per creare una nuova tabella nello HR schema e inserire i dati da un file Parquet, usare l'esempio Transact-SQL seguente:

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

L'istruzione COPY accetta solo caratteri validi UTF-8 e UTF-16 per i dati di riga e i parametri dei comandi. L'istruzione COPY potrebbe interpretare erroneamente i file o i parametri di origine (ad esempio ROWTERMINATOR o FIELDTERMINATOR) che usano caratteri non validi e causare risultati imprevisti, ad esempio il danneggiamento dei dati o altri errori. Assicurati che i file sorgente e i parametri siano conformi a UTF-8 o UTF-16 prima di invocare l'istruzione COPY .

L'hint per la MAXDOP query non è supportato con COPY INTO.

Per garantire un'esecuzione affidabile, non modificare i file e le cartelle di origine durante l'operazione COPY INTO .

• La modifica, l'eliminazione o la sostituzione di file o cartelle a cui si fa riferimento mentre il comando è in esecuzione può causare l'esito negativo dell'operazione o causare l'inserimento di dati incoerente.
• Prima di eseguire COPY INTO, verificare che tutti i dati di origine siano stabili e non verranno modificati durante il processo.

Se i dati di origine hanno una precisione maggiore rispetto alla definizione di colonna di destinazione, il valore viene troncato, non arrotondato per i tipi numerici, di data e ora.

Examples

A. Eseguire il caricamento da un account di archiviazione pubblico

L'esempio seguente illustra la forma più semplice del COPY comando, che carica i dati da un account di archiviazione pubblico. Per questo esempio, le COPY impostazioni predefinite dell'istruzione corrispondono al formato del file CSV dell'elemento di riga.

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

I valori predefiniti del comando COPY sono i seguenti:

• DATEFORMAT = Session DATEFORMAT

• MAXERRORS = 0

• COMPRESSION il predefinito è non compresso

• FIELDQUOTE = '"'

• FIELDTERMINATOR = ','

• ROWTERMINATOR = '\n'

Important

COPY Trattano \n come \r\n internamente. Per altre informazioni, vedere la sezione ROWTERMINATOR.

• FIRSTROW = 1

• ENCODING = 'UTF8'

• FILE_TYPE = 'CSV'

• IDENTITY_INSERT = 'OFF'

B. Eseguire il caricamento con l'autenticazione tramite firma di accesso condiviso

Nell'esempio seguente vengono caricati i file che usano il feed di riga come terminatore di riga, ad esempio un output UNIX. In questo esempio viene usata anche una chiave di firma di accesso condiviso per eseguire l'autenticazione per Archiviazione BLOB di Azure.

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. Eseguire il caricamento con un elenco di colonne con valori predefiniti e con l'autenticazione tramite chiave dell'account di archiviazione

Questo esempio carica i file specificando un elenco di colonne con valori predefiniti.

--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. Eseguire il caricamento di Parquet o ORC usando un oggetto formato di file esistente

In questo esempio viene usato un carattere jolly per caricare tutti i file Parquet in una cartella.

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. Eseguire il caricamento specificando caratteri jolly e più file

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. Eseguire il caricamento con credenziali MSI

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. Eseguire il caricamento con il rilevamento automatico dello schema

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

In che modo le prestazioni del comando COPY vengono confrontate con PolyBase?

Le prestazioni del comando COPY possono essere migliori a seconda del carico di lavoro.

• Il magazzino non può suddividere automaticamente i file compressi. Per ottenere prestazioni di caricamento ottimali, è consigliabile suddividere l'input in più file durante il caricamento di volumi condivisi cluster compressi.

• Il warehouse può suddividere automaticamente file CSV non compressi di grandi dimensioni per il caricamento parallelo, quindi in genere non è necessario suddividere manualmente i file CSV non compressi. In alcuni casi in cui la suddivisione automatica dei file non è fattibile a causa delle caratteristiche dei dati, la suddivisione manuale di volumi condivisi cluster di grandi dimensioni potrebbe comunque migliorare le prestazioni.

Qual è il materiale sussidiario sulla suddivisione dei file per il comando COPY che carica i file CSV compressi?

Nella tabella seguente viene descritto il numero di file da usare. Quando si raggiunge il numero consigliato di file, si ottengono prestazioni migliori con file di dimensioni maggiori. Il numero di file è determinato dal numero di nodi di calcolo moltiplicati per 60. Ad esempio, a 6000 DWU sono presenti 12 nodi di calcolo, quindi sono presenti 12 * 60 = 720 partizioni. Per una semplice esperienza di suddivisione dei file, vedere Come ottimizzare la velocità effettiva del caricamento COPY con suddivisioni di file.

DWU	Numero di file
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

Quali sono le linee guida per la divisione in file per il comando COPY che carica file Parquet o ORC?

Non è necessario dividere i file Parquet e ORC perché il comando COPY suddivide automaticamente i file. Per ottenere prestazioni ottimali, i file Parquet e ORC nell'account di archiviazione Azure devono essere di 256 MB o superiori.

Sono previste limitazioni per il numero o le dimensioni dei file?

Non esistono limitazioni per il numero o le dimensioni dei file. Tuttavia, per ottenere prestazioni ottimali, usare file di almeno 4 MB. Limitare inoltre il numero di file di origine a un massimo di 5.000 file per ottenere prestazioni migliori.

Esistono problemi noti con l'istruzione COPY?

Se si dispone di un'area di lavoro Azure Synapse creata prima del 7 dicembre 2020, è possibile che si verifichi un messaggio di errore simile durante l'autenticazione tramite Identità gestita: com.microsoft.sqlserver.jdbc.SQLServerException: Managed Service Identity isn't enabled on this server. Please enable Managed Service Identity and try again.

Per risolvere questo problema, registrare nuovamente l'identità gestita dell'area di lavoro:

1. Installare Azure PowerShell. Vedere Installare PowerShell.
2. Registrare l'identità gestita dell'area di lavoro usando PowerShell:

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

Contenuti correlati

• Panoramica del caricamento con Azure Synapse Analytics