Condividi tramite


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:

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:

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
    

Si applica a: Warehouse in Microsoft Fabric

Questo articolo illustra come usare l'istruzione COPY in Warehouse in Microsoft Fabric per il caricamento da account di archiviazione esterni. L'istruzione COPY offre la massima flessibilità per l'inserimento di dati a velocità effettiva elevata nel warehouse ed è la strategia per inserire i dati nel warehouse.

In Microsoft Fabric l'istruzione COPY (Transact-SQL) supporta attualmente i formati di file PARQUET e CSV. Per le origini dati, sono supportati solo gli account Azure Data Lake Storage Gen2.

Per altre informazioni sull'uso di COPY INTO nel warehouse in Microsoft Fabric, vedere Inserire dati nel warehouse usando l'istruzione COPY.

Per impostazione predefinita, COPY INTO eseguirà l'autenticazione come utente entra ID.

Nota

Per Azure Synapse Analytics, vedere COPY INTO per Azure Synapse Analytics.

Usare COPY per le funzionalità seguenti:

  • Usare utenti con privilegi inferiori per caricare senza bisogno di 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 .
  • Usare un account di archiviazione diverso per il percorso ERRORFILE (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.
  • Specificare un carattere di terminazione di riga personalizzato, un carattere di terminazione del campo e un'offerta di campo per i file CSV
  • Specificare caratteri jolly e più file nel percorso di archiviazione.
  • Per altre informazioni sulle opzioni di inserimento dati e sulle procedure consigliate, vedere Inserire dati nel warehouse usando l'istruzione COPY.

Sintassi

COPY INTO [ warehouse_name. ] [ schema_name. ] table_name
[ (Column_list) ]
FROM '<external_location>' [ , ...n ]
WITH
 (
 [ FILE_TYPE = { 'CSV' | 'PARQUET' } ]
 [ , CREDENTIAL = (AZURE CREDENTIAL) ]
 [ , ERRORFILE = ' [ http(s)://storageaccount/container ] /errorfile_directory [ / ] ] '
 [ , ERRORFILE_CREDENTIAL = (AZURE CREDENTIAL) ]
 [ , MAXERRORS = max_errors ]
 [ , COMPRESSION = { 'Gzip' | 'Snappy' } ]
 [ , FIELDQUOTE = 'string_delimiter' ]
 [ , FIELDTERMINATOR =  'field_terminator' ]
 [ , ROWTERMINATOR = 'row_terminator' ]
 [ , FIRSTROW = first_row ]
 [ , ENCODING = { 'UTF8' | 'UTF16' } ]
 [ , PARSER_VERSION = { '1.0' | '2.0' } ]
)

Argomenti

warehouse_name

Facoltativo se il magazzino corrente per l'utente che esegue l'operazione è il magazzino della tabella specificata. Se il warehouse non è specificato e lo schema e la tabella specificati non esistono nel warehouse corrente, COPY ha esito negativo e viene restituito un messaggio di errore.

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 deve esistere già nel magazzino.

(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.

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 è preceduto dalla 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 column_list non viene specificato, 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.

Nota

Quando si utilizzano file Parquet in Warehouse in Microsoft Fabric, i nomi delle colonne devono corrispondere esattamente all'origine e alla destinazione. Se il nome della colonna nella tabella di destinazione è diverso da quello del nome della colonna nel file parquet, la colonna della tabella di destinazione viene riempita con NULL.

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.

Posizione esterna

Nota

I percorsi OneLake dell'infrastruttura non sono attualmente supportati, sono supportati solo gli account di archiviazione BLOB e ADLS Gen2.

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

Azure Data Lake Storage (ADLS) Gen2 offre prestazioni migliori rispetto ad Archiviazione BLOB di Azure (legacy). Prendere in considerazione l'uso di un account ADLS Gen2 quando possibile.

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 i file che iniziano con un carattere di 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.

I caratteri jolly possono essere inclusi nel percorso in cui

  • 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 (\)

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

Percorsi esterni dietro il firewall

Per accedere ai file in Azure Data Lake Storage (ADLS) Gen2 e Archiviazione BLOB di Azure percorsi protetti da un firewall, si applicano i prerequisiti seguenti:

  • È necessario effettuare il provisioning di un'identità dell'area di lavoro per l'area di lavoro che ospita il warehouse. Per altre informazioni su come configurare un'identità dell'area di lavoro, vedere Identità dell'area di lavoro.
  • L'account Entra ID deve essere in grado di usare l'identità dell'area di lavoro.
  • L'account Entra ID deve avere accesso ai file sottostanti tramite il controllo degli accessi in base al ruolo di Azure o gli ACL del data lake.
  • L'area di lavoro infrastruttura che ospita il warehouse deve essere aggiunta come regola di istanza della risorsa. Per altre informazioni su come aggiungere l'area di lavoro infrastruttura con una regola dell'istanza di risorsa, vedere Regola dell'istanza di risorsa.

FILE_TYPE = { 'CSV' | 'PARQUET' }

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.

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

CREDENTIAL specifica il meccanismo di autenticazione per accedere all'account di archiviazione esterno. In Warehouse in Microsoft Fabric, gli unici meccanismi di autenticazione supportati sono firma di accesso condiviso (SAS) e chiave dell'account di archiviazione (SAK). L'autenticazione EntraID dell'utente è predefinita, non è necessario specificare credenziali.

Nota

Quando si usa un account di archiviazione pubblico, non è necessario specificare CREDENTIAL. Per impostazione predefinita viene usato l'ID Entra dell'utente in esecuzione.

  • Autenticazione con firma di accesso condiviso

    • 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 chiave dell'account di archiviazione

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

ERRORFILE = Percorso directory

ERRORFILE si applica solo al formato CSV. Specifica la directory in cui devono essere scritte le righe rifiutate e il file di errore 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 viene creata una cartella con l'ID istruzione e in tale cartella vengono scritti due tipi di file: un errore. File JSON contenente i motivi di rifiuto e un file row.csv contenente le righe rifiutate.

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. In Warehouse in Microsoft Fabric, l'unico meccanismo di autenticazione supportato è firma di accesso condiviso (SAS).

  • Autenticazione con firme di accesso condiviso
    • 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

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 l'operazione COPY non può importare viene ignorata e conteggiata come un errore. Se non viene specificato max_errors, il valore predefinito è 0.

In Microsoft Fabric, MAXERRORS non può essere usato quando FILE_TYPE è "PARQUET".

COMPRESSION = { '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 comando COPY rileva automaticamente il tipo di compressione in base all'estensione del file quando questo parametro non viene specificato:

  • .gz - GZIP

Il caricamento di file compressi è attualmente supportato solo con PARSER_VERSION 1.0.

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 solo a CSV. Specifica un singolo carattere utilizzato come carattere di virgolette (delimitatore di 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 a CSV. Specifica il carattere di terminazione del campo utilizzato nel file CSV. È anche possibile specificare il carattere di terminazione del campo 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.

ROWTERMINATOR = 'row_terminator'

ROWTERMINATOR si applica solo a 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. I caratteri di terminazione predefiniti sono \r\n, \ne \r.

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 ROWTERMINATOR.

FIRSTROW = First_row_int

FIRSTROW si applica solo a CSV. Specifica il numero di riga letto per primo in tutti i file per 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.

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.

PARSER_VERSION = { '1.0' | '2.0' }

PARSER_VERSION si applica solo a CSV. Il valore predefinito è 2.0. Specifica il parser di file usato per l'inserimento quando il tipo di file di origine è CSV. Il parser 2.0 offre prestazioni migliorate per l'inserimento di file CSV.

Parser versione 2.0 presenta le limitazioni seguenti:

  • I file CSV compressi non sono supportati
  • I file con codifica UTF-16 non sono supportati
  • Il multicharacter o multibyte ROWTERMINATOR, FIELDTERMINATOR o FIELDQUOTE non è supportato. Tuttavia, '\r\n' viene accettato come ROWTERMINATOR predefinito

Quando si usa parser versione 1.0 con file UTF-8, i caratteri di terminazione multibyte e multicaracter non sono supportati per FIELDTERMINATOR.

Parser versione 1.0 è disponibile solo per la compatibilità con le versioni precedenti e deve essere usato solo quando vengono rilevate queste limitazioni.

Nota

Quando COPY INTO viene usato con file CSV compressi o file con codifica UTF-16, COPY INTO passa automaticamente a PARSER_VERSION 1.0, senza che sia necessaria l'azione dell'utente. Per i caratteri di terminazione multi-carattere in FIELDTERMINATOR o ROWTERMINATOR, l'istruzione COPY INTO avrà esito negativo. Usare PARSER_VERSION = '1,0' se sono necessari separatori a più caratteri.

Osservazioni:

COPY INTO in Warehouse non consente di impostare un formato di data per interpretare le stringhe di caratteri di data. Per impostazione predefinita, tutte le date sono considerate in formato mese-giorno-anno. Per inserire un file CSV con un formato di data diverso, usare SET DATEFORMAT per specificare il formato di data desiderato a livello di sessione. Per altre informazioni, vedere SET DATEFORMAT (Transact-SQL).

Inoltre, 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

Per altre informazioni sull'uso di COPY INTO nel warehouse in Microsoft Fabric, vedere Inserire dati nel warehouse usando l'istruzione COPY.

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'

I valori predefiniti del comando COPY sono i seguenti:

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

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',
    MAXERRORS = 10,
    ERRORFILE = '/errorsfolder'--path starting from the storage container
)

C. Caricare con un elenco di colonne con valori predefiniti che eseguono l'autenticazione tramite la chiave dell'account di archiviazione (SAK)

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

In questo esempio viene usato un carattere jolly per caricare tutti i file Parquet in una cartella usando entraID dell'utente in esecuzione.

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

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

Domande frequenti

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

Valutare la possibilità di suddividere file CSV di grandi dimensioni, soprattutto quando il numero di file è ridotto, ma mantenere i file almeno 4 MB ciascuno per ottenere prestazioni migliori.

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

Valutare la possibilità di suddividere file Parquet di grandi dimensioni, soprattutto quando il numero di file è ridotto.

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.

Quale metodo di autenticazione viene usato quando non si specificano credenziali?

Per impostazione predefinita, COPY INTRO userà l'ID Entra dell'utente in esecuzione.