SALIN KE (Transact-SQL)

Berlaku untuk:Azure Synapse Analytics

Tip

Microsoft Fabric Data Warehouse adalah gudang relasional skala perusahaan pada fondasi data lake, dengan arsitektur siap masa depan, AI bawaan, dan fitur baru. Jika Anda baru menggunakan pergudangan data, mulailah dengan Fabric Data Warehouse. Beban kerja kumpulan SQL terdedikasi yang ada dapat ditingkatkan ke Fabric untuk mengakses kemampuan baru di seluruh ilmu data, analitik waktu nyata, dan pelaporan.

• Mulai uji coba gratis Fabric.
• Asisten Migrasi untuk Fabric Data Warehouse.

Artikel ini menjelaskan cara menggunakan pernyataan COPY di Azure Synapse Analytics untuk memuat data dari akun penyimpanan eksternal. Pernyataan ini COPY memberikan fleksibilitas paling besar untuk penyerapan data throughput tinggi ke Azure Synapse Analytics.

Note

Untuk Gudang di Microsoft Fabric, lihat COPY INTO.

Gunakan COPY untuk kemampuan berikut:

• Gunakan pengguna dengan hak istimewa yang lebih rendah untuk memuat data tanpa memerlukan izin CONTROL yang ketat pada gudang data.
• Jalankan satu pernyataan T-SQL tanpa harus membuat objek database lainnya.
• Uraikan dan muat file CSV dengan benar di mana pemisah (string, bidang, baris) diloloskan dalam kolom yang dibatasi string.
• Tentukan model izin yang lebih halus tanpa mengekspos kunci akun penyimpanan dengan menggunakan Tanda Tangan Akses Bersama (SAS).
• Gunakan akun penyimpanan yang berbeda untuk ERRORFILE lokasi (REJECTED_ROW_LOCATION).
• Kustomisasi nilai default untuk setiap kolom target dan tentukan bidang data sumber untuk dimuat ke dalam kolom target tertentu.
• Tentukan terminator baris kustom, terminator bidang, dan kutipan bidang untuk file CSV.
• Gunakan format tanggal SQL Server untuk file CSV.
• Tentukan kartubebas dan beberapa file di jalur lokasi penyimpanan.
• Penemuan skema otomatis menyederhanakan proses penentuan dan pemetaan data sumber ke dalam tabel target.
• Proses pembuatan tabel otomatis secara otomatis membuat tabel dan bekerja bersama penemuan skema otomatis.
• Muat langsung jenis data kompleks dari file Parquet seperti Peta dan Daftar ke dalam kolom string, tanpa menggunakan alat lain untuk memproses data sebelumnya.

Note

Untuk memuat jenis data kompleks dari file Parquet, aktifkan pembuatan tabel otomatis dengan menggunakan AUTO_CREATE_TABLE.

Untuk contoh komprehensif dan mulai cepat menggunakan COPY pernyataan, lihat:

• Mulai cepat: Memuat data secara massal menggunakan pernyataan COPY
• Mulai cepat: Contoh menggunakan pernyataan COPY dan metode autentikasi yang didukung
• Mulai cepat: Membuat pernyataan COPY menggunakan antarmuka pengguna Synapse Studio yang kaya

Note

ID Microsoft Entra sebelumnya dikenal sebagai 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

nama_skema

Opsional jika skema default untuk pengguna yang melakukan operasi adalah skema tabel yang ditentukan. Jika Anda tidak menentukan skema, dan skema default pengguna yang melakukan COPY operasi berbeda dari skema tabel yang ditentukan, COPY operasi dibatalkan dan pesan kesalahan dikembalikan.

nama_tabel

Nama tabel yang akan diSALIN datanya. Tabel target bisa berupa tabel sementara atau permanen dan harus sudah ada dalam database. Untuk mode deteksi skema otomatis, jangan berikan daftar kolom.

(column_list)

Daftar opsional dari satu atau beberapa kolom yang digunakan untuk memetakan bidang data sumber ke kolom tabel target untuk memuat data.

Jangan tentukan column_list saat AUTO_CREATE_TABLE = 'ON'.

column_list harus diapit tanda kurung dan dibatasi oleh koma. Daftar kolom adalah format berikut:

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

• Column_name - nama kolom dalam tabel target.
• Default_value - nilai default yang menggantikan nilai NULL apa pun dalam file input. Nilai default berlaku untuk semua format file. COPY mencoba memuat NULL dari file input saat kolom dihilangkan dari daftar kolom atau ketika ada bidang file input kosong. Nilai default mendahului kata kunci 'default'
• Field_number - nomor bidang file input yang dipetakan ke kolom target.
• Pengindeksan bidang dimulai pada 1.

Saat Anda tidak menentukan daftar kolom, COPY petakan kolom berdasarkan urutan sumber dan target: Bidang input 1 masuk ke kolom target 1, bidang 2 masuk ke kolom 2, dan sebagainya.

Lokasi eksternal

Lokasi tempat file yang berisi data ditahapkan. Saat ini, Azure Data Lake Storage (ADLS) Gen2 dan Azure Blob Storage didukung:

• Lokasi eksternal untuk Blob Storage: https://<account\>.blob.core.windows.net/<container\>/<path\>
• Lokasi eksternal untuk ADLS Gen2: https://<account\>.dfs.core.windows.net/<container\>/<path\>

Note

Titik .blob akhir juga tersedia untuk ADLS Gen2 dan saat ini menghasilkan performa terbaik. .blob Gunakan titik akhir saat .dfs tidak diperlukan untuk metode autentikasi Anda.

• Akun - Nama akun penyimpanan

• Kontainer - Nama kontainer blob

• Jalur - folder atau jalur file untuk data. Lokasi dimulai dari kontainer. Jika Anda menentukan folder, COPY mengambil semua file dari folder dan semua subfoldernya. COPY mengabaikan folder tersembunyi dan tidak mengembalikan file yang dimulai dengan garis bawah (_) atau titik (.) kecuali ditentukan secara eksplisit di jalur. Perilaku ini sama bahkan ketika menentukan jalur dengan kartubebas.

Anda dapat menyertakan kartubebas di jalur tempat:

• Pencocokan nama jalur kartubebas peka huruf besar/kecil
• Anda dapat keluar dari kartubebas dengan menggunakan karakter garis miring terbalik (\)
• Ekspansi wildcard diterapkan secara rekursif. Misalnya, semua file CSV di bawah Customer1 (termasuk subdirektori Customer1) dimuat dalam contoh berikut: Account/Container/Customer1/*.csv

Note

Untuk performa terbaik, hindari menentukan kartubebas yang memperluas lebih dari sejumlah besar file. Jika memungkinkan, cantumkan beberapa lokasi file alih-alih menentukan kartubebas.

Anda dapat menentukan beberapa lokasi file hanya dari akun penyimpanan dan kontainer yang sama melalui daftar yang dipisahkan koma seperti:

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

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

FILE_TYPE menentukan format data eksternal.

• CSV: Menentukan file nilai yang dipisahkan koma yang sesuai dengan standar RFC 4180 .
• PARQUET: Menentukan format Parquet.
• ORC: Menentukan format Optimized Row Columnar (ORC).

Note

Jenis file 'Teks Berbatas' di PolyBase digantikan oleh format file 'CSV'. Anda dapat mengonfigurasi pemisah koma default melalui FIELDTERMINATOR parameter .

FILE_FORMAT = external_file_format_name

FILE_FORMAT hanya berlaku untuk file Parquet dan ORC. Ini menentukan nama objek format file eksternal yang menyimpan jenis file dan metode pemadatan untuk data eksternal. Untuk membuat format file eksternal, gunakan CREATE EXTERNAL FILE FORMAT.

KREDENSIAL (IDENTITAS = '', RAHASIA = '')

CREDENTIAL menentukan mekanisme autentikasi untuk mengakses akun penyimpanan eksternal. Metode autentikasi adalah:

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

¹ Titik akhir blob (.blob.core.windows.net) di jalur lokasi eksternal Anda diperlukan untuk metode autentikasi ini.

² Titik akhir dfs (.dfs.core.windows.net) di jalur lokasi eksternal Anda diperlukan untuk metode autentikasi ini.

Note

• Saat mengautentikasi dengan menggunakan Microsoft Entra ID atau ke akun penyimpanan publik, Anda tidak perlu menentukan CREDENTIAL.
• Jika akun penyimpanan Anda dikaitkan dengan VNet, Anda harus mengautentikasi dengan menggunakan identitas terkelola.

• Mengautentikasi dengan Tanda Tangan Akses Bersama (SAS)

  • IDENTITY: Konstanta dengan nilai Shared Access Signature
  • SECRET: Tanda tangan akses bersama memberikan akses yang didelegasikan ke sumber daya di akun penyimpanan Anda.

• Izin minimum yang diperlukan: READ dan LIST

• Mengautentikasi dengan Perwakilan Layanan

  • IDENTITY: <ClientID>@<OAuth_2.0_Token_EndPoint>
  • SECRET: kunci perwakilan layanan aplikasi Microsoft Entra

• Peran RBAC minimum yang diperlukan: Kontributor data blob penyimpanan, kontributor data blob Penyimpanan, pemilik data blob Penyimpanan, atau pembaca data blob Penyimpanan

• Mengautentikasi dengan kunci akun Penyimpanan

  • IDENTITY: Konstanta dengan nilai Storage Account Key
  • SECRET: Kunci akun penyimpanan

• Mengautentikasi dengan Identitas Terkelola (Titik Akhir Layanan VNet)

  • IDENTITY: Konstanta dengan nilai Managed Identity

• Peran RBAC minimum diperlukan: Kontributor data blob penyimpanan atau Pemilik data blob Penyimpanan untuk server logis terdaftar Microsoft Entra di Azure. Saat menggunakan kumpulan SQL khusus (sebelumnya SQL DW) yang tidak terkait dengan Ruang Kerja Synapse, peran RBAC ini tidak diperlukan, tetapi identitas terkelola memerlukan izin Access Control List (ACL) pada objek target untuk mengaktifkan akses baca ke file sumber.

• Mengautentikasi dengan pengguna Microsoft Entra

  • KREDENSIAL tidak diperlukan

• Peran RBAC minimum diperlukan: Kontributor data blob penyimpanan atau Pemilik data blob Penyimpanan untuk pengguna Microsoft Entra

ERRORFILE = Lokasi Direktori

ERRORFILE hanya berlaku untuk CSV. Ini menentukan direktori dalam COPY pernyataan di mana baris yang ditolak dan file kesalahan yang sesuai ditulis. Anda dapat menentukan jalur lengkap dari akun penyimpanan atau jalur relatif terhadap kontainer. Jika jalur yang ditentukan tidak ada, gudang akan membuatnya. Direktori anak dibuat dengan nama _rejectedrows. Karakter _ memastikan bahwa direktori lolos untuk pemrosesan data lain kecuali dinamai secara eksplisit dalam parameter lokasi.

Note

Ketika Anda meneruskan jalur relatif ke ERRORFILE, jadikan relatif terhadap jalur kontainer yang Anda tentukan di external_location.

Dalam direktori ini, gudang membuat folder berdasarkan waktu pengiriman beban dalam format YearMonthDay -HourMinuteSecond (misalnya, 20180330-173205). Dalam folder ini, proses menulis dua jenis file: file alasan (kesalahan) dan file data (baris). Setiap file menambahkan queryID, , distributionIDdan GUID file. Karena data dan alasannya ada dalam file terpisah, file yang sesuai memiliki awalan yang cocok.

Jika ERRORFILE memiliki jalur lengkap akun penyimpanan yang ditentukan, COPY gunakan ERRORFILE_CREDENTIAL untuk menyambungkan ke penyimpanan tersebut. Jika tidak, ia menggunakan nilai yang Anda tentukan untuk CREDENTIAL. Saat Anda menggunakan kredensial yang sama untuk data sumber dan ERRORFILE, pembatasan yang berlaku untuk ERRORFILE_CREDENTIAL juga berlaku.

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

ERRORFILE_CREDENTIAL hanya berlaku untuk file CSV. Sumber data dan metode autentikasi yang didukung adalah:

• Azure Blob Storage: SAS, perwakilan layanan, atau Microsoft Entra

• Azure Data Lake Gen2: SAS, MSI, perwakilan layanan, atau Microsoft Entra

• Mengautentikasi dengan Tanda Tangan Akses Bersama (SAS)

  • IDENTITY: Konstanta dengan nilai Shared Access Signature
  • SECRET: Tanda tangan akses bersama memberikan akses yang didelegasikan ke sumber daya di akun penyimpanan Anda.

• Izin minimum yang diperlukan: BACA, DAFTAR, TULIS, BUAT, HAPUS

• Mengautentikasi dengan Perwakilan Layanan

  • IDENTITY: <ClientID>@<OAuth_2.0_Token_EndPoint>
  • SECRET: kunci perwakilan layanan aplikasi Microsoft Entra

• Peran RBAC minimum yang diperlukan: Kontributor data blob penyimpanan atau pemilik data blob Penyimpanan

Note

Menggunakan titik akhir token OAuth 2.0 V1

• Mengautentikasi dengan Identitas Terkelola (Titik Akhir Layanan VNet)

  • IDENTITY: Konstanta dengan nilai Managed Identity

• Peran RBAC minimum yang diperlukan: Kontributor data blob penyimpanan atau Pemilik data blob Penyimpanan untuk server SQL Database terdaftar Microsoft Entra

• Mengautentikasi dengan pengguna Microsoft Entra

  • CREDENTIAL tidak diperlukan

• Peran RBAC minimum diperlukan: Kontributor data blob penyimpanan atau Pemilik data blob Penyimpanan untuk pengguna Microsoft Entra

Menggunakan kunci akun penyimpanan dengan ERRORFILE_CREDENTIAL tidak didukung.

Note

Jika Anda menggunakan akun penyimpanan yang sama untuk file kesalahan Anda dan menentukan ERRORFILE jalur relatif terhadap akar kontainer, Anda tidak perlu menentukan ERROR_CREDENTIAL.

MAXERRORS = max_errors

MAXERRORS menentukan jumlah maksimum baris penolakan yang diizinkan dalam beban sebelum operasi COPY gagal. Setiap baris yang tidak dapat diimpor oleh operasi COPY diabaikan dan dihitung sebagai satu kesalahan. Jika Anda tidak menentukan nilai untuk jumlah kesalahan maksimum, defaultnya adalah 0.

MAXERRORS tidak dapat digunakan dengan AUTO_CREATE_TABLE.

Ketika FILE_TYPE adalah PARQUET, pengecualian yang disebabkan oleh kesalahan konversi jenis data (misalnya, biner Parquet ke bilangan bulat SQL) masih menyebabkan COPY INTO gagal, mengabaikan MAXERRORS.

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

COMPRESSION bersifat opsional dan menentukan metode kompresi data untuk data eksternal.

• CSV mendukung GZIP.
• Parquet mendukung GZIP dan Snappy.
• ORC mendukung DefaultCodec dan Snappy.
• Zlib adalah kompresi default untuk ORC.

Perintah COPY otomatis memetakan jenis kompresi berdasarkan ekstensi file saat Anda tidak menentukan parameter ini:

• .gz - GZIP
• .snappy - Tajam
• .deflate - DefaultCodec (hanya Parquet dan ORC)

Perintah COPY mengharuskan file gzip tidak berisi sampah berikutnya untuk beroperasi secara normal. Format gzip secara ketat mengharuskan file terdiri dari anggota yang valid tanpa informasi tambahan sebelum, antara, atau sesudahnya. Setiap penyimpangan dari format ini, seperti adanya data non-gzip berikutnya, mengakibatkan kegagalan perintah COPY. Untuk memastikan COPY berjalan dengan sukses, pastikan untuk memverifikasi tidak ada sampah berikutnya di akhir file gzip.

FIELDQUOTE = 'field_quote'

FIELDQUOTE berlaku untuk CSV dan menentukan satu karakter yang digunakan sebagai karakter kutipan (pembatas string) dalam file CSV. Jika Anda tidak menentukan nilai ini, karakter kuotasi (") digunakan sebagai karakter kuotasi seperti yang didefinisikan dalam standar RFC 4180. Notasi heksadesimal juga didukung untuk FIELDQUOTE. Karakter ASCII dan multibyte yang diperluas tidak didukung dengan UTF-8 untuk FIELDQUOTE.

Note

Karakter FIELDQUOTE diloloskan dalam kolom string di mana ada kehadiran FIELDQUOTE ganda (pemisah).

FIELDTERMINATOR = 'field_terminator'

FIELDTERMINATOR hanya berlaku untuk CSV. Menentukan terminator bidang yang digunakan dalam file CSV. Anda dapat menentukan terminator bidang dengan menggunakan notasi heksadesimal. Terminator bidang dapat berupa multicharacter. Terminator bidang default adalah (,). Karakter ASCII dan multibyte yang diperluas tidak didukung dengan UTF-8 untuk FIELDTERMINATOR.

ROWTERMINATOR = 'row_terminator'

ROWTERMINATOR hanya berlaku untuk CSV. Menentukan terminator baris yang digunakan dalam file CSV. Anda dapat menentukan terminator baris dengan menggunakan notasi heksadesimal. Terminator baris dapat berupa multicharacter. Secara default, terminator baris adalah \r\n.

Perintah COPY mengawali \r karakter saat menentukan \n (baris baru) menghasilkan \r\n. Untuk menentukan hanya \n karakter, gunakan notasi heksadesimal (0x0A). Saat menentukan terminator baris multikarakter dalam heksadesimal, jangan tentukan 0x di antara setiap karakter.

Karakter ASCII dan multibyte yang diperluas tidak didukung dengan UTF-8 untuk ROWTERMINATOR.

FIRSTROW = First_row_int

FIRSTROW berlaku untuk CSV dan menentukan nomor baris yang dibaca terlebih dahulu di semua file untuk perintah COPY. Nilai dimulai dari 1, yang merupakan nilai default. Jika Anda mengatur nilai ke 2, baris pertama di setiap file (baris header) dilewati saat data dimuat. Baris dilewati berdasarkan keberadaan terminator baris.

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

DATEFORMAT hanya berlaku untuk CSV dan menentukan format tanggal pemetaan tanggal ke format tanggal SQL Server. Untuk gambaran umum semua jenis dan fungsi data tanggal dan waktu Transact-SQL, lihat Jenis dan Fungsi Data Tanggal dan Waktu (Transact-SQL). DATEFORMAT dalam perintah COPY lebih diutamakan daripada DATEFORMAT yang dikonfigurasi pada tingkat sesi.

PENGODEAN = 'UTF8' | 'UTF16'

ENCODING hanya berlaku untuk CSV. Defaultnya adalah UTF8. Menentukan standar pengodean data untuk file yang dimuat oleh perintah COPY.

IDENTITY_INSERT = 'ON' | 'NONAKTIF'

IDENTITY_INSERT menentukan apakah nilai identitas atau nilai dalam file data yang diimpor akan digunakan untuk kolom identitas. Jika IDENTITY_INSERT adalah OFF (default), nilai identitas untuk kolom ini diverifikasi, tetapi tidak diimpor. Perhatikan perilaku berikut dengan perintah COPY:

• Jika IDENTITY_INSERT NONAKTIF, dan tabel memiliki kolom identitas
  • Anda harus menentukan daftar kolom yang tidak memetakan bidang input ke kolom identitas.
• Jika IDENTITY_INSERT AKTIF, dan tabel memiliki kolom identitas
  • Jika Anda meneruskan daftar kolom, kolom tersebut harus memetakan bidang input ke kolom identitas.
• Nilai default tidak didukung untuk kolom IDENTITY di daftar kolom.
• Anda hanya dapat mengatur IDENTITY_INSERT untuk satu tabel pada satu waktu.

Azure Synapse Analytics secara otomatis menetapkan nilai unik berdasarkan nilai benih dan kenaikan yang ditentukan selama pembuatan tabel.

AUTO_CREATE_TABLE = { 'ON' | 'OFF' }

AUTO_CREATE_TABLE menentukan apakah tabel dapat dibuat secara otomatis dengan bekerja bersama penemuan skema otomatis. AUTO_CREATE_TABLE hanya tersedia untuk file Parquet di Azure Synapse Analytics.

• AKTIF: Mengaktifkan pembuatan tabel otomatis. Proses ini COPY INTO secara otomatis membuat tabel baru dengan menemukan struktur file yang akan dimuat. Anda juga dapat menggunakannya dengan tabel yang sudah ada sebelumnya untuk memanfaatkan penemuan skema otomatis file Parquet.
• NONAKTIF: Pembuatan tabel otomatis tidak diaktifkan. Default.

Note

Pembuatan tabel otomatis berfungsi bersama penemuan skema otomatis. Pembuatan tabel otomatis tidak diaktifkan secara default.

Permissions

Pengguna yang menjalankan perintah COPY harus memiliki izin berikut:

• MENGELOLA OPERASI MASSAL DATABASE
• INSERT

Memerlukan izin INSERT dan ADMINISTER BULK OPERATIONS. Di Izin Azure Synapse Analytics, INSERT, dan ADMINISTER DATABASE BULK OPERATIONS diperlukan.

Selain itu, jika pengguna yang menjalankan perintah COPY juga berniat untuk menghasilkan tabel baru dan memuat data ke dalamnya, mereka memerlukan izin CREATE TABLE dan ALTER ON SCHEMA.

Misalnya, untuk mengizinkan mike@contoso.com penggunaan COPY untuk membuat tabel baru dalam HR skema, dan menyisipkan data dari file Parquet, gunakan sampel Transact-SQL berikut:

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

Pernyataan hanya COPY menerima karakter UTF-8 dan UTF-16 yang valid untuk data baris dan parameter perintah. Pernyataan mungkin COPY salah menginterpretasikan file atau parameter sumber (seperti ROWTERMINATOR atau FIELDTERMINATOR) yang menggunakan karakter yang tidak valid dan menyebabkan hasil yang tidak terduga seperti kerusakan data atau kegagalan lainnya. Pastikan file dan parameter sumber Anda sesuai dengan UTF-8 atau UTF-16 sebelum Anda memanggil COPY pernyataan.

MAXDOP Petunjuk kueri tidak didukung dengan COPY INTO.

Untuk memastikan eksekusi yang andal, jangan ubah file dan folder sumber selama COPY INTO operasi.

• Memodifikasi, menghapus, atau mengganti file atau folder yang direferensikan saat perintah berjalan dapat menyebabkan operasi gagal atau mengakibatkan penyerapan data yang tidak konsisten.
• Sebelum menjalankan COPY INTO, verifikasi bahwa semua data sumber stabil dan tidak akan diubah selama proses.

Jika data sumber memiliki presisi yang lebih besar daripada definisi kolom tujuan, nilainya dipotong, tidak dibulatkan, untuk jenis numerik, tanggal, dan waktu.

Examples

A. Memuat dari akun penyimpanan publik

Contoh berikut menunjukkan bentuk COPY perintah paling sederhana, yang memuat data dari akun penyimpanan publik. Untuk contoh ini, COPY default pernyataan cocok dengan format file CSV item baris.

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

Nilai default perintah COPY adalah:

• DATEFORMAT = DATEFORMAT Sesi

• MAXERRORS = 0

• COMPRESSION default tidak terkompresi

• FIELDQUOTE = '"'

• FIELDTERMINATOR = ','

• ROWTERMINATOR = '\n'

Important

COPY memperlakukan \n sebagai \r\n internal. Untuk informasi selengkapnya, lihat bagian ROWTERMINATOR .

• FIRSTROW = 1

• ENCODING = 'UTF8'

• FILE_TYPE = 'CSV'

• IDENTITY_INSERT = 'NONAKTIF'

B. Memuat autentikasi melalui Share Access Signature (SAS)

Contoh berikut memuat file yang menggunakan umpan baris sebagai terminator baris, seperti output UNIX. Contoh ini juga menggunakan kunci SAS untuk mengautentikasi ke Azure Blob Storage.

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

C. Muat dengan daftar kolom dengan nilai default yang mengautentikasi melalui Kunci Akun Penyimpanan

Contoh ini memuat file yang menentukan daftar kolom dengan nilai default.

--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. Muat Parquet atau ORC menggunakan objek format file yang ada

Contoh ini menggunakan kartubebas untuk memuat semua file Parquet di bawah folder.

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. Memuat yang menentukan kartubebas dan beberapa 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. Memuat menggunakan kredensial 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. Muat menggunakan deteksi skema otomatis

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

Bagaimana performa perintah COPY dibandingkan dengan PolyBase?

Performa perintah COPY bisa lebih baik tergantung pada beban kerja Anda.

• Gudang tidak dapat secara otomatis membagi file terkompresi. Untuk performa pemuatan terbaik, pertimbangkan untuk membagi input Anda menjadi beberapa file saat memuat CSV terkompresi.

• Gudang dapat secara otomatis membagi file CSV besar yang tidak dikompresi untuk pemuatan paralel, jadi Anda biasanya tidak perlu membagi file CSV yang tidak dikompresi secara manual. Dalam kasus tertentu di mana pemisahan file otomatis tidak layak karena karakteristik data, pemisahan CSV besar secara manual mungkin masih menguntungkan performa.

Apa panduan pemisahan file untuk perintah COPY yang memuat file CSV terkompresi?

Tabel berikut menguraikan jumlah file yang harus Anda gunakan. Ketika Anda mencapai jumlah file yang direkomendasikan, Anda mendapatkan performa yang lebih baik dengan file yang lebih besar. Jumlah file ditentukan oleh jumlah simpul komputasi yang dikalikan dengan 60. Misalnya, pada 6000 DWU, Anda memiliki 12 simpul komputasi, sehingga Anda memiliki 12 * 60 = 720 partisi. Untuk pengalaman pemisahan file sederhana, lihat Cara memaksimalkan throughput beban COPY dengan pemisahan file.

DWU	Jumlah 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

Apa panduan pemisahan file untuk perintah COPY yang memuat file Parquet atau ORC?

Anda tidak perlu membagi file Parquet dan ORC karena perintah COPY secara otomatis membagi file. Untuk performa terbaik, file Parquet dan ORC di akun penyimpanan Azure harus 256 MB atau lebih besar.

Apakah ada batasan pada jumlah atau ukuran file?

Tidak ada batasan pada jumlah atau ukuran file. Namun, untuk performa terbaik, gunakan file yang setidaknya 4 MB. Selain itu, batasi jumlah file sumber hingga maksimum 5.000 file untuk performa yang lebih baik.

Apakah ada masalah yang diketahui dengan pernyataan COPY?

Jika Anda memiliki ruang kerja Azure Synapse yang Anda buat sebelum 7 Desember 2020, Anda mungkin mengalami pesan kesalahan serupa saat mengautentikasi dengan menggunakan Identitas Terkelola: com.microsoft.sqlserver.jdbc.SQLServerException: Managed Service Identity isn't enabled on this server. Please enable Managed Service Identity and try again.

Untuk mengatasi masalah ini, daftarkan ulang identitas terkelola ruang kerja:

1. Pasang Azure PowerShell. Lihat Menginstal PowerShell.
2. Daftarkan identitas terkelola ruang kerja Anda dengan menggunakan PowerShell:

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

Konten terkait

• Memuat gambaran umum dengan Azure Synapse Analytics