COPY INTO (Transact-SQL)

Si applica a: Azure Synapse Analytics

Questo articolo illustra come usare l'istruzione COPY in Azure Synapse Analytics per il caricamento da account di archiviazione esterni. L'istruzione COPY offre la massima flessibilità per l'inserimento di dati con velocità effettiva elevata in Azure Synapse Analytics.

Nota

Per Warehouse in Microsoft Fabric, visitare COPY INTO.

Usare COPY per le funzionalità seguenti:

• Usare utenti con privilegi inferiori per caricare 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ù preciso senza esporre le chiavi dell'account di archiviazione usando le firme di accesso condiviso (SAS)
• Usare un account di archiviazione diverso per il percorso di ERRORFILE (REJECTED_ROW_LOCATION)
• Personalizzare i valori predefiniti per ogni colonna di destinazione e specificare i campi dei dati di origine da caricare in colonne di destinazione specifiche
• Specificare un carattere di terminazione di riga personalizzato, un carattere di terminazione del campo e un'offerta di campo per i file CSV
• Usare i formati di data di SQL Server per i file CSV
• Specificare caratteri jolly e più file nel percorso della posizione di archiviazione
• L'individuazione automatica dello schema semplifica il processo di definizione e mapping dei dati di origine alle tabelle di destinazione
• Il processo di creazione automatica di 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

Nota

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

Per esempi completi e argomenti di avvio rapido relativi all'istruzione COPY, vedere la documentazione seguente:

• 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

Nota

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

Sintassi

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

Argomenti

schema_name

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

table_name

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 Default_value] [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 viene specificato 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.

Percorsi esterni

Posizione di gestione temporanea dei 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\>

Nota

L'endpoint .blob è disponibile anche per ADLS Gen2 e attualmente garantisce le migliori prestazioni. Usare l'endpoint .blob quando non è richiesto .dfs 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, con le regole seguenti:

• Per la corrispondenza del nome del percorso con un carattere jolly viene fatta distinzione tra maiuscole e minuscole
• È possibile applicare una sequenza di escape al carattere jolly usando la 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

Nota

Per ottenere prestazioni ottimali, evitare di specificare caratteri jolly che prevedono l'espansione in un numero elevato di file. Se possibile, elencare più percorsi di file invece di specificare caratteri jolly.

È possibile specificare più percorsi di file inclusi nello stesso account di archiviazione e contenitore usando 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).

Nota

Il tipo di file 'Delimited Text' in PolyBase viene sostituito dal formato di file 'CSV', in cui è possibile configurare il delimitatore virgola predefinito tramite il parametro FIELDTERMINATOR.

FILE_FORMAT = external_file_format_name

FILE_FORMAT si applica solo ai file Parquet e ORC e 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	FIRMA DI ACCESSO CONDIVISO/IDENTITÀ DEL SERVIZIO GESTITA/ENTITÀ SERVIZIO/CHIAVE/AAD	FIRMA DI ACCESSO CONDIVISO/CHIAVE	FIRMA DI ACCESSO CONDIVISO/CHIAVE
Azure Data Lake Gen2	FIRMA DI ACCESSO CONDIVISO/IDENTITÀ DEL SERVIZIO GESTITA/ENTITÀ SERVIZIO/CHIAVE/AAD	FIRMA di accesso condiviso (BLOB 1 )/MSI (dfs 2 )/ENTITÀ SERVIZIO/CHIAVE/AAD	FIRMA di accesso condiviso (BLOB 1 )/MSI (dfs 2 )/ENTITÀ SERVIZIO/CHIAVE/AAD

1: l'endpoint BLOB (.blob.core.windows.net) nel percorso esterno è necessario per questo metodo di autenticazione.

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

Nota

• Quando si esegue l'autenticazione con Microsoft Entra ID o in 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: una costante con valore '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: una costante con valore 'Storage Account Key'
  • SECRET: chiave dell'account di archiviazione

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

  • IDENTITY: una costante con valore '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) 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 al formato CSV. Specifica la directory all'interno dell'istruzione COPY in cui scrivere le righe rifiutate e il file di errori corrispondente. È possibile specificare il percorso completo dall'account di archiviazione oppure il percorso relativo al contenitore. Se il percorso specificato non esiste, ne viene creato uno per conto dell'utente. Viene creata una directory figlio con nome "_rejectedrows". Il carattere "_" assicura che la directory venga ignorata da altre attività di elaborazione dati, salvo se indicata in modo esplicito nel parametro del percorso.

Nota

Quando un percorso relativo viene passato a ERRORFILE, il percorso è relativo al percorso del contenitore specificato in external_location.

Questa directory include una cartella creata in base all'ora di inoltro del carico, con il formato AnnoMeseGiorno - OraMinutoSecondo, ad esempio 20180330-173205. In questa cartella vengono scritti due tipi di file, il file reason (Error) e il file di dati (Row) ogni preappending con queryID, distributionID e un GUID di file. 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, il ERRORFILE_CREDENTIAL viene usato per connettersi a tale archiviazione. In caso contrario, viene usato il valore indicato per CREDENTIAL. Quando vengono usate le stesse credenziali usate per i dati di origine per ERRORFILE, vengono applicate anche restrizioni che si applicano a ERRORFILE_CREDENTIAL

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/AAD

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

• Autenticazione con firme di accesso condiviso (SAS)

  • IDENTITY: una costante con valore '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

Nota

Usare l'endpoint di token OAuth 2.0 V1

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

  • IDENTITY: una costante con valore '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.

Nota

Se si usa lo stesso account di archiviazione per ERRORFILE e si specifica il percorso di ERRORFILE 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 non può essere importata dall'operazione COPY viene ignorata e conteggiata come un errore. Se non viene specificato max_errors, 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, binari Parquet in integer SQL) causano comunque l'esito negativo di COPY INTO, ignorando MAXERRORS.

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

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

• Il formato CSV supporta GZIP
• Il formato Parquet supporta GZIP e Snappy
• Il formato ORC supporta DefaultCodec e Snappy
• Zlib è il tipo di compressione predefinito per ORC

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

• .gz - GZIP
• Estensione snappy - Snappy
• .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, genererà l'errore del comando COPY. Assicurarsi di verificare che alla fine dei file gzip non siano presenti operazioni di garbage finali per assicurarsi che COPY possa elaborare correttamente questi file.

FIELDQUOTE = 'field_quote'

FIELDQUOTE si applica a CSV e specifica un singolo carattere usato come carattere di virgolette (delimitatore stringa) nel file CSV. Se non specificato, 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 multi byte non sono supportati con UTF-8 per FIELDQUOTE.

Nota

Ai caratteri FIELDQUOTE viene applicata una sequenza di escape nelle colonne stringa in cui è presente un oggetto FIELDQUOTE (delimitatore) doppio.

FIELDTERMINATOR = 'field_terminator'

FIELDTERMINATOR si applica solo al formato CSV. Specifica il carattere di terminazione del campo utilizzato nel file CSV. Il carattere di terminazione del campo può essere specificato usando la notazione esadecimale. Il carattere di terminazione del campo può essere costituito da più caratteri. Il carattere di terminazione del campo predefinito è una virgola (,). I caratteri ASCII estesi e multi byte non sono supportati con UTF-8 per FIELDTERMINATOR.

ROW TERMINATOR = 'row_terminator'

ROW TERMINATOR si applica solo al formato CSV. Specifica il carattere di terminazione di riga utilizzato nel file CSV. Il carattere di terminazione della riga può essere specificato usando la notazione esadecimale. Il carattere di terminazione della riga può essere costituito da più caratteri. 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 multi byte non sono supportati con UTF-8 per ROW TERMINATOR.

FIRSTROW = First_row_int

FIRSTROW si applica al formato CSV e specifica il numero della riga che viene letta per prima in tutti i file con il comando COPY. I valori iniziano da 1, che è il valore predefinito. Se il valore è impostato su due, la prima riga di ogni file (riga di intestazione) viene ignorata quando i dati vengono caricati. 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 al formato 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 o i valori Identity presenti nel file di dati importato devono essere usati per la colonna Identity. Se il valore di IDENTITY_INSERT è OFF (impostazione predefinita), i valori Identity per questa colonna vengono verificati ma non importati. Azure Synapse Analytics assegna automaticamente valori univoci in base ai valori di inizializzazione e incremento specificati durante la creazione della tabella. 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 viene passato un elenco di colonne, deve eseguire il mapping di un campo di input alla colonna Identity.
• Il valore predefinito non è supportato per IDENTITY COLUMN nell'elenco di colonne.
• È possibile impostare IDENTITY_INSERT solo per una tabella alla volta.

AUTO_CREATE_TABLE = { 'ON' | 'OFF' }

AUTO_CREATE_TABLE specifica se la tabella può essere creata automaticamente insieme all'individuazione automatica dello schema. È disponibile solo per i file Parquet.

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

Nota

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

Non caricare nelle tabelle distribuite hash dai file Parquet usando COPY INTO con AUTO_CREATE_TABLE = 'ON'.

Se i file Parquet devono essere caricati in tabelle con distribuzione hash con COPY INTO, caricarlo in una tabella di staging round robin seguita da INSERT ... SELECT da tale tabella alla tabella hash distribuita di destinazione.

Autorizzazioni

L'utente che esegue il comando Copy deve avere le autorizzazioni seguenti:

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

Osservazioni:

L'istruzione COPY accetta solo caratteri validi UTF-8 e UTF-16 per i parametri di riga e di comando. I file o i parametri di origine ( ad esempio ROW TERMINATOR o FIELD TERMINATOR) che usano caratteri non validi possono essere interpretati in modo non corretto dall'istruzione COPY e causare risultati imprevisti, ad esempio il danneggiamento dei dati o altri errori. Assicurarsi che i file e i parametri di origine siano conformi a UTF-8 o UTF-16 prima di richiamare l'istruzione COPY.

Esempi

R. Eseguire il caricamento da un account di archiviazione pubblico

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

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 = Valore DATEFORMAT della sessione

• MAXERRORS = 0

• COMPRESSION - Per impostazione predefinita non viene applicata la compressione

• FIELDQUOTE = '"'

• FIELDTERMINATOR = ','

• ROWTERMINATOR = '\n'

Importante

COPY considera \n \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

L'esempio seguente carica file che usano il carattere di avanzamento riga come carattere di terminazione della riga, come nel caso di 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>'),
    --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. 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'
)

Domande frequenti

Quali sono le prestazioni del comando COPY rispetto a PolyBase?

Il comando COPY offre prestazioni migliori a seconda del carico di lavoro.

• I file compressi non possono essere suddivisi automaticamente. Per prestazioni di caricamento ottimali, è consigliabile suddividere l'input in più file durante il caricamento di volumi condivisi cluster compressi.

• I file CSV non compressi di grandi dimensioni possono essere suddivisi e caricati automaticamente in parallelo, quindi nella maggior parte dei casi 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 può comunque migliorare le prestazioni.

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

Le indicazioni sul numero di file sono descritte nella tabella seguente. Una volta raggiunto il numero consigliato di file, è possibile ottenere prestazioni migliori per i file più grandi. Il numero di file è determinato dal numero di nodi di calcolo moltiplicati per 60. Ad esempio, a 6000DWU sono presenti 12 nodi di calcolo e 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	#Files
100	60
200	60
300	60
400	60
500	60
1.000	120
1.500	180
2.000	240
2500	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 prestazioni ottimali, i file Parquet e ORC nell'account di archiviazione di Azure devono avere dimensioni minime di 256 MB.

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

Non sono previste limitazioni per il numero o le dimensioni dei file. Per assicurare prestazioni ottimali, tuttavia, è consigliabile usare file di almeno 4 MB.

Esistono problemi noti con l'istruzione COPY?

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

Seguire questa procedura per risolvere il problema registrando di nuovo l'identità gestita dell'area di lavoro:

1. Installare Azure PowerShell. Fare riferimento a 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
   

Contenuto correlato

• Panoramica del caricamento con Azure Synapse Analytics