COPY INTO(Transact-SQL)

아티클
08/15/2024

이 문서에서는 Azure Synapse Analytics의 COPY 문을 사용하여 외부 스토리지 계정에서 로드하는 방법을 설명합니다. COPY 문은 높은 처리량으로 데이터를 Azure Synapse Analytics로 수집할 수 있도록 가장 뛰어난 유연성을 제공합니다.

참고 항목

Microsoft Fabric의 웨어하우스는 COPY INTO를 방문하세요.

다음 기능에 COPY를 사용합니다.

권한이 낮은 사용자를 사용하여 데이터 웨어하우스에 대한 엄격한 제어 권한 없이 로드
다른 데이터베이스 개체를 만들지 않고 단일 T-SQL 문을 실행합니다.
문자열로 구분된 열 내에서 구분 기호(문자열, 필드, 행)가 이스케이프되는 CSV 파일을 올바르게 구문 분석하고 로드합니다.
SAS(공유 액세스 서명)를 사용하여 스토리지 계정 키를 노출하지 않고 보다 세부적인 사용 권한 모델을 지정
ERRORFILE 위치(REJECTED_ROW_LOCATION)에 대해 다른 스토리지 계정을 사용
각 대상 열에 대한 기본값을 사용자 지정하고 원본 데이터 필드를 지정하여 특정 대상 열에 로드
CSV 파일에 대한 사용자 지정 행 종결자, 필드 종결자 및 필드 따옴표 지정
CSV 파일에 SQL Server 날짜 형식 사용
스토리지 위치 경로에 와일드카드 및 여러 파일 지정
자동 스키마 검색은 원본 데이터를 정의하고 대상 테이블에 매핑하는 프로세스를 간소화합니다.
자동 테이블 만들기 프로세스는 자동으로 테이블을 만들고 자동 스키마 검색과 함께 작동합니다.
다른 도구를 사용하여 데이터를 전처리하지 않고도 Maps 및 Lists와 같은 Parquet 파일에서 문자열 열로 복잡한 데이터 형식을 직접 로드합니다.

참고 항목

Parquet 파일에서 복잡한 데이터 형식을 로드하려면 .를 사용하여 AUTO_CREATE_TABLE자동 테이블 만들기를 설정해야 합니다.

COPY 문을 사용하는 포괄적인 예제 및 빠른 시작은 다음 설명서를 참조하세요.

참고 항목

Microsoft Entra ID는 이전에 Azure Active Directory(Azure AD)로 알려졌습니다.

구문

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

인수

schema_name

작업을 수행하는 사용자의 기본 스키마가 지정된 테이블의 스키마인 경우 선택 사항입니다. 스키마를 지정하지 않고 COPY 작업을 수행하는 사용자의 기본 스키마가 지정된 테이블의 스키마와 다르면 COPY가 취소되고 오류 메시지가 반환됩니다.

table_name

데이터를 복사할 테이블의 이름입니다. 대상 테이블은 임시 또는 영구 테이블일 수 있으며, 데이터베이스에 이미 있어야 합니다. 자동 스키마 검색 모드의 경우 열 목록을 제공하지 마세요.

(column_list)

데이터 로드를 위해 원본 데이터 필드를 대상 테이블 열에 매핑하는 데 사용되는 하나 이상의 열의 선택적 목록입니다.

column_list AUTO_CREATE_TABLE = 'ON'지정 하지 마세요.

column_list는 괄호로 묶고 쉼표로 구분해야 합니다. 열 목록은 다음과 같은 형식입니다.

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

Column_name - 대상 테이블에 있는 열의 이름입니다.
Default_value - 입력 파일의 NULL 값을 대체하는 기본값입니다. 기본값은 모든 파일 형식에 적용됩니다. 열 목록에서 열을 생략하거나 입력 파일 필드가 비어 있는 경우 COPY는 입력 파일에서 NULL을 로드하려고 시도합니다. 기본값은 'default' 키워드 앞에 섰습니다.
Field_number - 대상 열에 매핑되는 입력 파일 필드 번호입니다.
필드 인덱싱은 1에서 시작합니다.

열 목록을 지정하지 않으면 COPY는 원본 및 대상 순서에 따라 열을 매핑합니다. 입력 필드 1은 대상 열 1로, 필드 2는 열 2로 이동합니다.

외부 위치

데이터가 포함된 파일이 준비되는 위치입니다. 현재 ADLS(Azure Data Lake Storage) Gen2 및 Azure Blob Storage가 지원됩니다.

Blob Storage의 외부 위치 : https://<account\>.blob.core.windows.net/<container\>/<path\>
ADLS Gen2의 외부 위치 : https://<account\>.dfs.core.windows.net/<container\>/<path\>

참고 항목

.blob 엔드포인트는 ADLS Gen2에서도 사용할 수 있으며 현재 최상의 성능을 제공합니다. 인증 방법에 .dfs가 필요하지 않은 경우에는 .blob 엔드포인트를 사용합니다.

계정 - 스토리지 계정 이름
컨테이너 - Blob 컨테이너 이름
경로 - 데이터의 폴더 또는 파일 경로입니다. 위치는 컨테이너에서 시작합니다. 폴더가 지정된 경우 COPY는 폴더 및 모든 하위 폴더에서 모든 파일을 검색합니다. COPY는 숨겨진 폴더를 무시하고 경로에 명시적으로 지정하지 않는 한 밑줄(_) 또는 마침표(.)로 시작하는 파일을 반환하지 않습니다. 와일드카드를 사용하여 경로를 지정하는 경우에도 이 동작은 동일합니다.

와일드카드 카드는 다음 경로에 포함될 수 있습니다.

와일드카드 경로 이름 일치는 대/소문자를 구분합니다.
와일드카드는 백슬래시 문자(\)를 사용하여 이스케이프할 수 있습니다.
와일드카드 확장은 재귀적으로 적용됩니다. 예를 들어 Customer1의 모든 CSV 파일(Customer1의 하위 디렉터리 포함)은 다음 예제에서 로드됩니다. Account/Container/Customer1/*.csv

참고 항목

최상의 성능을 위해 더 많은 수의 파일로 확장되는 와일드카드를 지정하지 마세요. 가능하면 와일드카드를 지정하는 대신 여러 파일 위치를 나열합니다.

여러 파일 위치는 다음과 같이 쉼표로 구분된 목록을 통해 동일한 스토리지 계정 및 컨테이너에서만 지정할 수 있습니다.

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

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

FILE_TYPE은 외부 데이터의 형식을 지정합니다.

CSV: RFC 4180 표준을 준수하는 쉼표로 구분된 값 파일을 지정합니다.
PARQUET: Parquet 형식을 지정합니다.
ORC: ORC(최적화된 행 열 형식) 형식을 지정합니다.

참고

PolyBase의 '구분된 텍스트' 파일 형식은 FIELDTERMINATOR 매개 변수를 통해 기본 쉼표 구분 기호를 구성할 수 있는 ‘CSV’ 파일 형식으로 대체됩니다.

FILE_FORMAT = external_file_format_name

FILE_FORMAT은 Parquet 및 ORC 파일에만 적용되면 외부 데이터에 대한 파일 형식과 압축 방법을 저장하는 외부 파일 형식 개체의 이름을 지정합니다. 외부 파일 형식을 만들려면 CREATE EXTERNAL FILE FORMAT을 사용합니다.

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

자격 증명은 외부 스토리지 계정에 액세스하기 위한 인증 메커니즘을 지정합니다. 인증 방법은 다음과 같습니다.

	CSV	Parquet	ORC
Azure Blob Storage	SAS/MSI/SERVICE PRINCIPAL/KEY/AAD	SAS/KEY	SAS/KEY
Azure Data Lake Gen2	SAS/MSI/SERVICE PRINCIPAL/KEY/AAD	SAS(Blob ¹ )/MSI(dfs ² )/SERVICE PRINCIPAL/KEY/AAD	SAS(Blob ¹ )/MSI(dfs ² )/SERVICE PRINCIPAL/KEY/AAD

1: 이 인증 방법에는 외부 위치 경로의 .blob 엔드포인트( .blob.core.windows.net)가 필요합니다.

2: 이 인증 방법에는 외부 위치 경로의 .dfs 엔드포인트( .dfs.core.windows.net)가 필요합니다.

참고 항목

Microsoft Entra ID 또는 공용 스토리지 계정을 사용하여 인증하는 경우 CREDENTIAL을 지정할 필요가 없습니다.
스토리지 계정이 VNet과 연결된 경우 관리 ID를 사용하여 인증해야 합니다.

SAS(공유 액세스 서명)를 사용하여 인증
- IDENTITY: ‘공유 액세스 서명’의 값이 있는 상수
- 비밀: 공유 액세스 서명 은 스토리지 계정의 리소스에 대한 위임된 액세스를 제공합니다.
- 필요한 최소 권한: 읽기 및 목록
서비스 사용자로 인증
- IDENTITY: <ClientID>@<OAuth_2.0_Token_EndPoint>
- 비밀: Microsoft Entra 애플리케이션 서비스 주체 키
- 필요한 최소 RBAC 역할: Storage Blob 데이터 기여자, Storage Blob 데이터 기여자, Storage Blob 데이터 소유자 또는 Storage Blob 데이터 reader
Storage 계정 키를 사용하여 인증
- IDENTITY: ‘Storage 계정 키’의 값이 있는 상수
- SECRET: 스토리지 계정 키
관리 ID(VNet 서비스 엔드포인트)를 사용하여 인증
- IDENTITY: ‘관리 ID’ 값이 있는 상수
- 필요한 최소 RBAC 역할: Azure에서 Microsoft Entra 등록 논리 서버에 대한 스토리지 Blob 데이터 기여자 또는 Storage Blob 데이터 소유자입니다. Synapse 작업 영역과 연결되지 않은 전용 SQL 풀(이전의 SQL DW)을 사용하는 경우 이 RBAC 역할은 필요하지 않지만 관리 ID에는 원본 파일에 대한 읽기 액세스를 사용하도록 설정하기 위해 대상 개체에 대한 ACL(액세스 제어 목록) 권한이 필요합니다.
Microsoft Entra 사용자로 인증
- CREDENTIAL이 필요하지 않습니다.
- 필요한 최소 RBAC 역할: Microsoft Entra 사용자에 대한 스토리지 Blob 데이터 기여자 또는 Storage Blob 데이터 소유자

ERRORFILE = 디렉터리 위치

ERRORFILE는 CSV에만 적용됩니다. 거부된 행과 해당 오류 파일을 작성해야 하는 COPY 문 내의 디렉터리를 지정합니다. 스토리지 계정의 전체 경로를 지정하거나 컨테이너와 관련된 경로를 지정할 수 있습니다. 지정된 경로가 없으면 사용자를 대신하여 경로가 만들어집니다. "_rejectedrows"라는 이름의 자식 디렉터리가 생성됩니다. "_" 문자는 위치 매개 변수에 명시적으로 명명되지 않는 한 다른 데이터 처리를 위해 디렉터리를 이스케이프합니다.

참고 항목

상대 경로가 ERRORFILE에 전달되면 경로는 external_location 지정된 컨테이너 경로를 기준으로 합니다.

이 디렉터리 내에는 로드 제출 시간을 기준으로 YearMonthDay -HourMinuteSecond 형식에 따라 생성된 폴더가 있습니다(예: 20180330-173205). 이 폴더에는 두 가지 형식의 파일이 작성됩니다. 이유(오류) 파일과 데이터(행) 파일은 각각 queryID, distributionID 및 파일 GUID와 함께 미리 추가됩니다. data와 reason은 별도의 파일에 있으므로 해당 파일에는 일치하는 접두사가 있습니다.

ERRORFILE에 정의된 스토리지 계정의 전체 경로가 있는 경우 ERRORFILE_CREDENTIAL 해당 스토리지에 연결하는 데 사용됩니다. 그렇지 않으면 CREDENTIAL에 대해 언급된 값이 사용됩니다. 원본 데이터에 사용되는 동일한 자격 증명이 ERRORFILE에 사용되는 경우 ERRORFILE_CREDENTIAL 적용되는 제한 사항도 적용됩니다.

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

ERRORFILE_CREDENTIAL은 CSV 파일에만 적용됩니다. 지원되는 데이터 원본 및 인증 방법은 다음과 같습니다.

Azure Blob Storage - SAS/서비스 주체/AAD
Azure Data Lake Gen2 - SAS/MSI/서비스 주체/AAD
SAS(공유 액세스 서명)를 사용하여 인증
- IDENTITY: ‘공유 액세스 서명’의 값이 있는 상수
- 비밀: 공유 액세스 서명 은 스토리지 계정의 리소스에 대한 위임된 액세스를 제공합니다.
- 필요한 최소 권한: 읽기, 나열, 쓰기, 만들기, 삭제
서비스 사용자로 인증
- IDENTITY: <ClientID>@<OAuth_2.0_Token_EndPoint>
- 비밀: Microsoft Entra 애플리케이션 서비스 주체 키
- 필요한 최소 RBAC 역할: Storage Blob 데이터 기여자 또는 Storage Blob 데이터 소유자

참고

OAuth 2.0 토큰 엔드포인트 V1 사용

관리 ID(VNet 서비스 엔드포인트)를 사용하여 인증
- IDENTITY: ‘관리 ID’ 값이 있는 상수
- 필요한 최소 RBAC 역할: Microsoft Entra 등록 SQL Database 서버에 대한 스토리지 Blob 데이터 기여자 또는 Storage Blob 데이터 소유자
Microsoft Entra 사용자로 인증
- CREDENTIAL이 필요하지 않습니다.
- 필요한 최소 RBAC 역할: Microsoft Entra 사용자에 대한 스토리지 Blob 데이터 기여자 또는 Storage Blob 데이터 소유자

ERRORFILE_CREDENTIAL 스토리지 계정 키 사용은 지원되지 않습니다.

참고 항목

ERRORFILE에 동일한 스토리지 계정을 사용하고 컨테이너 루트에 상대적인 ERRORFILE 경로를 지정하는 경우 ERROR_CREDENTIAL을 지정할 필요가 없습니다.

MAXERRORS = max_errors

MAXERRORS 는 COPY 작업이 실패하기 전에 로드에 허용되는 최대 거부 행 수를 지정합니다. COPY 작업에서 가져올 수 없는 각 행은 무시되고 하나의 오류로 계산됩니다. max_errors 지정하지 않으면 기본값은 0입니다.

MAXERRORS 는 AUTO_CREATE_TABLE 사용할 수 없습니다.

FILE_TYPE 'PARQUET'인 경우 데이터 형식 변환 오류(예: Parquet 이진-SQL 정수)로 인해 발생하는 예외로 인해 COPY INTO가 실패하고 MAXERRORS가 무시됩니다.

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

COMPRESSION은 선택 사항이며 외부 데이터에 대한 데이터 압축 메서드를 지정합니다.

CSV에서 GZIP 지원
Parquet은 GZIP 및 Snappy를 지원합니다.
ORC는 DefaultCodec 및 Snappy를 지원합니다.
Zlib는 ORC의 기본 압축입니다.

COPY 명령은 이 매개 변수가 지정되지 않은 경우 파일 확장명을 기반으로 압축 형식을 자동으로 검색합니다.

.gz - GZIP
.snappy – Snappy
.deflate - DefaultCodec(Parquet 및 ORC만 해당)

COPY 명령을 사용하려면 gzip 파일에 정상적으로 작동하기 위해 후행 가비지가 포함되지 않도록 해야 합니다. gzip 형식을 사용하려면 파일이 이전, 사이 또는 그 이후의 추가 정보 없이 유효한 멤버로 구성되어야 합니다. 이 형식의 모든 편차(예: 후행 비 gzip 데이터의 존재)는 COPY 명령의 실패를 초래합니다. COPY가 이러한 파일을 성공적으로 처리할 수 있도록 gzip 파일 끝에 후행 가비지가 없는지 확인합니다.

FIELDQUOTE = 'field_quote'

FIELDQUOTE 는 CSV에 적용되며 CSV 파일에서 따옴표 문자(문자열 구분 기호)로 사용되는 단일 문자를 지정합니다. 지정하지 않으면 RFC 4180 표준에 정의된 따옴표 문자(")가 따옴표 문자로 사용됩니다. FIELDQUOTE에도 16진수 표기법이 지원됩니다. 확장 ASCII 및 멀티 바이트 문자는 FIELDQUOTE용 UTF-8에서 지원되지 않습니다.

참고 항목

FIELDQUOTE 문자는 이중 FIELDQUOTE(구분 기호)가 있는 문자열 열에서 이스케이프됩니다.

FIELDTERMINATOR = 'field_terminator'

FIELDTERMINATOR CSV에만 적용됩니다. CSV 파일에 사용되는 필드 종결자를 지정합니다. 16진수 표기법을 사용하여 필드 종결자를 지정할 수 있습니다. 필드 종결자는 여러 문자일 수 있습니다. 기본 필드 종결자는 (,)입니다. 확장 ASCII 및 멀티 바이트 문자는 FIELDTERMINATOR에 대해 UTF-8에서 지원되지 않습니다.

ROW TERMINATOR = 'row_terminator'

ROW TERMINATOR CSV에만 적용됩니다. CSV 파일에 사용되는 행 종결자를 지정합니다. 16진수 표기법을 사용하여 행 종결자를 지정할 수 있습니다. 행 종결자는 여러 문자일 수 있습니다. 기본적으로 행 종결자는 .입니다 \r\n.

COPY 명령은 (줄 바꿈)을 \n 지정할 때 문자 앞에 접두 \r 사를 지정합니다\r\n. 문자만 \n 지정하려면 16진수 표기법(0x0A)을 사용합니다. 16진수로 다중 문자 행 종결자를 지정하는 경우 각 문자 사이에 0x를 지정하지 마세요.

확장 ASCII 및 멀티 바이트 문자는 ROW TERMINATOR에 대해 UTF-8에서 지원되지 않습니다.

FIRSTROW = First_row_int

FIRSTROW는 CSV에 적용되며 COPY 명령의 모든 파일에서 먼저 읽을 행 번호를 지정합니다. 값은 1부터 시작되며 이것이 기본값입니다. 값이 2로 설정되면 데이터를 로드할 때 모든 파일의 첫 행(헤더 행)을 건너뜁니다. 행 종결자의 존재에 따라 행을 건너뜁니다.

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

DATEFORMAT은 CSV에만 적용되며 SQL Server 날짜 형식에 대한 날짜 매핑의 날짜 형식을 지정합니다. 모든 Transact-SQL 날짜/시간 데이터 형식 및 함수에 대한 개요는 날짜/시간 데이터 형식 및 함수(Transact-SQL)를 참조하세요. COPY 명령 내의 DATEFORMAT은 세션 수준에서 구성된 DATEFORMAT보다 우선합니다.

ENCODING = 'UTF8' | 'UTF16'

ENCODING은 CSV에만 적용됩니다. 기본값은 UTF8입니다. COPY 명령으로 로드된 파일의 데이터 인코딩 표준을 지정합니다.

IDENTITY_INSERT = 'ON' | 'OFF'

IDENTITY_INSERT는 가져온 데이터 파일의 ID 값 또는 값을 ID 열에 사용할지 여부를 지정합니다. IDENTITY_INSERT가 OFF(기본값)이면 이 열의 ID 값은 확인되지만 가져오지는 않습니다. Azure Synapse Analytics는 테이블을 만드는 동안 지정된 초기값 및 증가 값을 기반으로 고유 값을 자동으로 할당합니다. COPY 명령을 사용하여 다음 동작을 기록합니다.

IDENTITY_INSERT OFF이고 테이블에 ID 열이 있는 경우
- 입력 필드를 ID 열에 매핑하지 않는 열 목록을 지정해야 합니다.
IDENTITY_INSERT ON이고 테이블에 ID 열이 있는 경우
- 열 목록이 전달되면 입력 필드를 ID 열에 매핑해야 합니다.
열 목록의 IDENTITY COLUMN에는 기본값이 지원되지 않습니다.
IDENTITY_INSERT는 한 번에 하나의 테이블에 대해서만 설정할 수 있습니다.

AUTO_CREATE_TABLE = { 'ON' | 'OFF' }

AUTO_CREATE_TABLE은 테이블이 자동 스키마 검색과 함께 작동하여 자동으로 생성될 수 있는지를 지정합니다. Parquet 파일에만 사용할 수 있습니다.

ON: 자동 테이블 만들기를 사용하도록 설정합니다. COPY INTO 프로세스는 로드할 파일의 구조를 검색하여 자동으로 새 테이블을 만듭니다. Parquet 파일의 자동 스키마 검색을 활용하기 위해 기존 테이블과 함께 사용할 수도 있습니다.
OFF: 자동 테이블 만들기를 사용할 수 없습니다. 기본값

참고

자동 테이블 생성은 자동 스키마 검색과 함께 작동합니다. 자동 테이블 생성은 기본적으로 사용 설정되어 있지 않습니다.

COPY INTO와 AUTO_CREATE_TABLE = 'ON'을 사용하여 Parquet 파일의 해시 분산 테이블에 로드하지 마세요.

Parquet 파일을 COPY INTO를 사용하여 해시 분산 테이블에 로드해야 하는 경우 라운드 로빈 준비 테이블에 로드한 다음 INSERT... 해당 테이블에서 대상 해시 분산 테이블로 SELECT합니다.

사용 권한

복사 명령을 실행하는 사용자는 다음 권한을 가지고 있어야 합니다.

INSERT 및 ADMINISTER BULK OPERATIONS 권한이 필요합니다. Azure Synapse Analytics에서는 INSERT 및 ADMINISTER DATABASE BULK OPERATIONS 권한이 필요합니다.

또한 COPY 명령을 실행하는 사용자도 새 테이블을 생성하고 데이터를 로드하려는 경우 CREATE TABLE 및 ALTER ON SCHEMA 권한이 필요합니다.

예를 들어 COPY를 사용하여 스키마에 HR 새 테이블을 만들고 Parquet 파일의 데이터를 삽입하려면 mike@contoso.com 다음 Transact-SQL 샘플을 사용합니다.

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];

설명

COPY 문은 행 데이터 및 명령 매개 변수에 대해 UTF-8 및 UTF-16 유효한 문자만 허용합니다. 잘못된 문자를 사용하는 원본 파일 또는 매개 변수(예: ROW TERMINATOR 또는 FIELD TERMINATOR)는 COPY 문에 의해 잘못 해석되어 데이터 손상 또는 기타 오류와 같은 예기치 않은 결과를 초래할 수 있습니다. COPY 문을 호출하기 전에 원본 파일 및 매개 변수가 UTF-8 또는 UTF-16 규격인지 확인합니다.

예제

A. 퍼블릭 스토리지 계정에서 로드

다음 예제는 퍼블릭 스토리지 계정에서 데이터를 로드하는 COPY 명령의 가장 간단한 형태입니다. 이 예제에서 COPY 문의 기본값은 줄 항목 csv 파일의 형식과 일치합니다.

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

COPY 명령의 기본값은 다음과 같습니다.

DATEFORMAT = Session DATEFORMAT
MAXERRORS = 0
압축 기본값은 압축되지 않음
FIELDQUOTE = '"'
FIELDTERMINATOR = ','
ROWTERMINATOR = '\n'

Important

COPY는 내부적으로 \r\n 처리됩니다\n. 자세한 내용은 ROWTERMINATOR 섹션을 참조하세요.

FIRSTROW = 1
ENCODING = 'UTF8'
FILE_TYPE = 'CSV'
IDENTITY_INSERT = 'OFF'

다음 예제에서는 UNIX 출력과 같은 행 종결자로 줄 바꿈을 사용하는 파일을 로드합니다. 이 예제에서는 SAS 키를 사용하여 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. 스토리지 계정 키를 통해 인증되는 기본값이 있는 열 목록으로 로드

이 예제에서는 기본값을 사용하여 열 목록을 지정하는 파일을 로드합니다.

--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. 기존 파일 형식 개체를 사용하여 Parquet 또는 ORC 로드

이 예제에서는 와일드카드를 사용하여 폴더 아래에 모든 Parquet 파일을 로드합니다.

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. 와일드카드 및 여러 파일을 지정하여 로드

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. 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. 자동 스키마 검색을 사용하여 로드

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

PolyBase 대비 COPY 명령의 성능은 어떤가요?

COPY 명령은 워크로드에 따라 성능이 향상됩니다.

압축된 파일은 자동으로 분할할 수 없습니다. 최상의 로드 성능을 위해 압축된 CSV를 로드할 때 입력을 여러 파일로 분할하는 것이 좋습니다.
압축되지 않은 대형 CSV 파일은 자동으로 분할 및 로드될 수 있으므로 대부분의 경우 압축되지 않은 CSV 파일을 수동으로 분할할 필요가 없습니다. 데이터 특성으로 인해 자동 파일 분할이 가능하지 않은 경우 대형 CSV를 수동으로 분할해도 성능에 도움이 될 수 있습니다.

압축된 CSV 파일을 로드하는 COPY 명령에 대한 파일 분할 지침은 무엇인가요?

파일 수에 대한 지침은 다음 표에 설명되어 있습니다. 권장되는 파일 수에 도달하면 파일이 클수록 성능이 향상됩니다. 파일 수는 컴퓨팅 노드 수에 60을 곱하여 결정됩니다. 예를 들어 6000DWU에는 12개의 컴퓨팅 노드와 12*60 = 720개의 파티션이 있습니다. 간단한 파일 분할 환경은 파일 분할을 사용하여 COPY 로드 처리량을 최대화하는 방법을 참조하세요.

DWU	#Files
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
10000	1200
15,000	1800
30,000	3600

Parquet 또는 ORC 파일을 로드하는 COPY 명령의 파일 분할 지침은 무엇인가요?

COPY 명령은 파일을 자동으로 분할하므로 Parquet 및 ORC 파일을 분할할 필요가 없습니다. 최상의 성능을 얻으려면 Azure Storage 계정의 Parquet 및 ORC 파일이 256MB 이상이어야 합니다.

파일 개수 또는 크기에 제한이 있나요?

파일 개수 또는 크기에 제한이 없습니다. 하지만 최상의 성능을 위해 4MB 이상의 파일을 사용하는 것이 좋습니다.

COPY 문에 알려진 문제가 있나요?

2020년 12월 7일 이전에 만든 Azure Synapse 작업 영역이 있는 경우 관리 ID를 사용하여 인증할 때 유사한 오류 메시지가 나타날 수 있습니다. com.microsoft.sqlserver.jdbc.SQLServerException: Managed Service Identity has not been enabled on this server. Please enable Managed Service Identity and try again.

다음 단계에 따라 작업 영역의 관리 ID를 다시 등록하여 이 문제를 해결하세요.

Azure PowerShell을 설치합니다. PowerShell 설치를 참조하세요.

PowerShell을 사용하여 작업 영역의 관리 ID를 등록합니다.

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

Azure Synapse Analytics를 사용한 로드 개요

적용 대상: Microsoft Fabric의 웨어하우스

이 문서에서는 외부 스토리지 계정에서 로드하기 위해 Microsoft Fabric의 Warehouse에 있는 COPY 문을 사용하는 방법을 설명합니다. COPY 문은 웨어하우스로 높은 처리량 데이터 수집을 위한 가장 유연한 기능을 제공하며, 웨어하우스로 데이터를 수집하는 전략입니다.

Microsoft Fabric 에서 COPY(Transact-SQL) 문은 현재 PARQUET 및 CSV 파일 형식을 지원합니다. 데이터 원본의 경우 Azure Data Lake Storage Gen2 계정만 지원됩니다.

Microsoft Fabric의 웨어하우스에서 COPY INTO를 사용하는 방법에 대한 자세한 내용은 COPY 문을 사용하여 웨어하우스로 데이터 수집을 참조하세요.

기본적으로 COPY INTO 실행 중인 Entra ID 사용자로 인증됩니다.

참고 항목

Azure Synapse Analytics의 경우 Azure Synapse Analytics용 COPY INTO를 방문 하세요.

다음 기능에 COPY를 사용합니다.

데이터 웨어하우스에 대한 엄격한 CONTROL 권한 없이 낮은 권한의 사용자를 사용하여 로드합니다.
다른 데이터베이스 개체를 만들지 않고도 단일 T-SQL 문을 실행합니다.
구분 기호(문자열, 필드, 행)가 문자열로 구분된 열 내에서 이스케이프되는 CSV 파일을 올바르게 구문 분석하고 로드합니다.
SAS(공유 액세스 서명)를 사용하여 스토리지 계정 키를 노출하지 않고 더 세부적인 권한 모델을 지정합니다.
ERRORFILE 위치(REJECTED_ROW_LOCATION)에 다른 스토리지 계정을 사용합니다.
각 대상 열에 대한 기본값을 사용자 지정하고 특정 대상 열에 로드할 원본 데이터 필드를 지정합니다.
CSV 파일에 대한 사용자 지정 행 종결자, 필드 종결자 및 필드 따옴표 지정
스토리지 위치 경로에 와일드카드 및 여러 파일을 지정합니다.
데이터 수집 옵션 및 모범 사례에 대한 자세한 내용은 COPY 문을 사용하여 웨어하우스로 데이터 수집을 참조하세요.

구문

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

인수

warehouse_name

작업을 수행하는 사용자의 현재 웨어하우스가 지정된 테이블의 웨어하우스인 경우 선택 사항입니다. 웨어하우스를 지정하지 않고 지정된 스키마와 테이블이 현재 웨어하우스에 없으면 COPY가 실패하고 오류 메시지가 반환됩니다.

schema_name

table_name

데이터를 복사할 테이블의 이름입니다. 대상 테이블은 웨어하우스에 이미 있어야 합니다.

(column_list)

데이터 로드를 위해 원본 데이터 필드를 대상 테이블 열에 매핑하는 데 사용되는 하나 이상의 열의 선택적 목록입니다.

column_list는 괄호로 묶고 쉼표로 구분해야 합니다. 열 목록은 다음과 같은 형식입니다.

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

Column_name - 대상 테이블에 있는 열의 이름입니다.
Default_value - 입력 파일의 NULL 값을 대체하는 기본값입니다. 기본값은 모든 파일 형식에 적용됩니다. 열 목록에서 열을 생략하거나 입력 파일 필드가 비어 있는 경우 COPY는 입력 파일에서 NULL을 로드하려고 시도합니다. 기본값 앞에 키워드 'default'가 옵니다.
Field_number - 대상 열에 매핑되는 입력 파일 필드 번호입니다.
필드 인덱싱은 1에서 시작합니다.

column_list 지정되지 않은 경우 COPY는 원본 및 대상 순서에 따라 열을 매핑합니다. 입력 필드 1은 대상 열 1로, 필드 2는 열 2로 이동합니다.

참고 항목

Microsoft Fabric의 Warehouse에서 Parquet 파일을 사용하는 경우 열 이름은 원본 및 대상에서 정확히 일치해야 합니다. 대상 테이블의 열 이름이 parquet 파일의 열 이름과 다른 경우 대상 테이블 열은 NULL로 채워집니다.

열 목록을 지정하지 않으면 COPY는 원본 및 대상 순서에 따라 열을 매핑합니다. 입력 필드 1은 대상 열 1로, 필드 2는 열 2로 이동합니다.

외부 위치

참고 항목

패브릭 OneLake 경로는 현재 지원되지 않으며 BLOB 및 ADLS Gen2 스토리지 계정만 지원됩니다.

데이터가 포함된 파일이 준비되는 위치를 지정합니다. 현재 ADLS(Azure Data Lake Storage) Gen2 및 Azure Blob Storage가 지원됩니다.

Blob Storage의 외부 위치 : https://<account\>.blob.core.windows.net/<container\>/<path\>
ADLS Gen2의 외부 위치 : https://<account\>.dfs.core.windows.net/<container\>/<path\>

ADLS(Azure Data Lake Storage) Gen2는 Azure Blob Storage(레거시)보다 더 나은 성능을 제공합니다. 가능하면 ADLS Gen2 계정을 사용하는 것이 좋습니다.

참고 항목

계정 - 스토리지 계정 이름
컨테이너 - Blob 컨테이너 이름
경로 - 데이터의 폴더 또는 파일 경로입니다. 위치는 컨테이너에서 시작합니다. 폴더가 지정된 경우 COPY는 폴더 및 모든 하위 폴더에서 모든 파일을 검색합니다. COPY는 숨겨진 폴더를 무시하고 경로에 명시적으로 지정되지 않은 경우 밑줄(_) 또는 마침표(.)로 시작하는 파일을 반환하지 않습니다. 와일드카드를 사용하여 경로를 지정하는 경우에도 이 동작은 동일합니다.

와일드카드는 경로에 포함할 수 있습니다.

와일드카드 경로 이름 일치는 대/소문자를 구분합니다.
백슬래시 문자(\)를 사용하여 와일드카드를 이스케이프할 수 있습니다.

참고 항목

여러 파일 위치는 다음과 같이 쉼표로 구분된 목록을 통해 동일한 스토리지 계정 및 컨테이너에서만 지정할 수 있습니다.

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

방화벽 뒤의 외부 위치

방화벽 뒤에 있는 Azure ADLS(Data Lake Storage) Gen2 및 Azure Blob Storage 위치의 파일에 액세스하려면 다음 필수 구성 요소가 적용됩니다.

웨어하우스를 호스팅하는 작업 영역에 대한 작업 영역 ID 를 프로비전해야 합니다. 작업 영역 ID를 설정하는 방법에 대한 자세한 내용은 작업 영역 ID를 참조 하세요.
Entra ID 계정은 작업 영역 ID를 사용할 수 있어야 합니다.
Entra ID 계정은 Azure RBAC(역할 기반 액세스 제어) 또는 데이터 레이크 ACL을 통해 기본 파일에 액세스할 수 있어야 합니다.
웨어하우스를 호스팅하는 패브릭 작업 영역을 리소스 인스턴스 규칙으로 추가해야 합니다. 리소스 인스턴스 규칙을 사용하여 패브릭 작업 영역을 추가하는 방법에 대한 자세한 내용은 리소스 인스턴스 규칙을 참조하세요.

FILE_TYPE = { 'CSV' | 'PARQUET' }

FILE_TYPE은 외부 데이터의 형식을 지정합니다.

CSV: RFC 4180 표준을 준수하는 쉼표로 구분된 값 파일을 지정합니다.
PARQUET: Parquet 형식을 지정합니다.

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

자격 증명은 외부 스토리지 계정에 액세스하기 위한 인증 메커니즘을 지정합니다. Microsoft Fabric의 Warehouse에서 유일하게 지원되는 인증 메커니즘은 SAS(공유 액세스 서명) 및 SAK(스토리지 계정 키)입니다. 사용자의 EntraID 인증은 기본값이며 자격 증명을 지정할 필요가 없습니다.

참고 항목

공용 스토리지 계정을 사용하는 경우 CREDENTIAL을 지정할 필요가 없습니다. 기본적으로 실행 중인 사용자의 Entra ID가 사용됩니다.

SAS(공유 액세스 서명)를 사용하여 인증
- IDENTITY: ‘공유 액세스 서명’의 값이 있는 상수
- 비밀: 공유 액세스 서명 은 스토리지 계정의 리소스에 대한 위임된 액세스를 제공합니다.
- 필요한 최소 권한: 읽기 및 목록
스토리지 계정 키를 사용하여 인증
- IDENTITY: ‘Storage 계정 키’의 값이 있는 상수
- SECRET: 스토리지 계정 키

ERRORFILE = 디렉터리 위치

ERRORFILE는 CSV에만 적용됩니다. 거부된 행과 해당 오류 파일을 쓸 디렉터리를 지정합니다. 스토리지 계정의 전체 경로를 지정하거나 컨테이너와 관련된 경로를 지정할 수 있습니다. 지정된 경로가 없으면 사용자를 대신하여 경로가 만들어집니다. "_rejectedrows"라는 이름의 자식 디렉터리가 생성됩니다. "_" 문자는 위치 매개 변수에 명시적으로 명명되지 않는 한 다른 데이터 처리를 위해 디렉터리를 이스케이프합니다.

참고 항목

상대 경로가 ERRORFILE에 전달되면 경로는 external_location 지정된 컨테이너 경로를 기준으로 합니다.

이 디렉터리 내에는 로드 제출 시간을 기준으로 YearMonthDay -HourMinuteSecond 형식에 따라 생성된 폴더가 있습니다(예: 20180330-173205). 이 폴더에서 문 ID가 있는 폴더가 만들어지고 해당 폴더 아래에 두 가지 유형의 파일이 기록됩니다. 오류입니다. 거부 이유가 포함된 Json 파일 및 거부된 행이 포함된 row.csv 파일입니다.

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

ERRORFILE_CREDENTIAL은 CSV 파일에만 적용됩니다. Microsoft Fabric의 Warehouse에서 유일하게 지원되는 인증 메커니즘은 SAS(공유 액세스 서명)입니다.

SAS(공유 액세스 서명)를 사용하여 인증
- IDENTITY: ‘공유 액세스 서명’의 값이 있는 상수
- 비밀: 공유 액세스 서명 은 스토리지 계정의 리소스에 대한 위임된 액세스를 제공합니다.
- 필요한 최소 권한: 읽기, 나열, 쓰기, 만들기, 삭제

참고 항목

ERRORFILE에 동일한 스토리지 계정을 사용하고 컨테이너 루트에 상대적인 ERRORFILE 경로를 지정하는 경우 ERROR_CREDENTIAL을 지정할 필요가 없습니다.

MAXERRORS = max_errors

MAXERRORS 는 COPY 작업이 실패하기 전에 로드에 허용되는 최대 거부 행 수를 지정합니다. COPY 작업을 가져올 수 없는 각 행은 무시되고 하나의 오류로 계산됩니다. max_errors 지정하지 않으면 기본값은 0입니다.

Microsoft Fabric에서는 FILE_TYPE 'PARQUET'인 경우 MAXERRORS를 사용할 수 없습니다.

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

COMPRESSION은 선택 사항이며 외부 데이터에 대한 데이터 압축 메서드를 지정합니다.

CSV에서 GZIP 지원
Parquet은 GZIP 및 Snappy를 지원합니다.

COPY 명령은 이 매개 변수가 지정되지 않은 경우 파일 확장명을 기반으로 압축 형식을 자동으로 검색합니다.

.gz - GZIP

압축 파일 로드는 현재 PARSER_VERSION 1.0에서만 지원됩니다.

FIELDQUOTE = 'field_quote'

FIELDQUOTE 는 CSV에만 적용됩니다. CSV 파일에서 따옴표 문자(문자열 구분 기호)로 사용되는 단일 문자를 지정합니다. 지정하지 않으면 RFC 4180 표준에 정의된 따옴표 문자(")가 따옴표 문자로 사용됩니다. FIELDQUOTE에도 16진수 표기법이 지원됩니다. 확장 ASCII 및 멀티 바이트 문자는 FIELDQUOTE용 UTF-8에서 지원되지 않습니다.

참고 항목

FIELDQUOTE 문자는 이중 FIELDQUOTE(구분 기호)가 있는 문자열 열에서 이스케이프됩니다.

FIELDTERMINATOR = 'field_terminator'

FIELDTERMINATOR 는 CSV에만 적용됩니다. CSV 파일에 사용되는 필드 종결자를 지정합니다. 필드 종결자는 16진수 표기법을 사용하여 지정할 수도 있습니다. 필드 종결자는 여러 문자일 수 있습니다. 기본 필드 종결자는 (,)입니다. 확장 ASCII 및 멀티 바이트 문자는 FIELDTERMINATOR에 대해 UTF-8에서 지원되지 않습니다.

ROWTERMINATOR = 'row_terminator'

ROWTERMINATOR 는 CSV에만 적용됩니다. CSV 파일에 사용되는 행 종결자를 지정합니다. 16진수 표기법을 사용하여 행 종결자를 지정할 수 있습니다. 행 종결자는 여러 문자일 수 있습니다. 기본 종결자는 \r\n, \n및 \r.

확장 ASCII 및 멀티 바이트 문자는 ROWTERMINATOR에 대해 UTF-8에서 지원되지 않습니다.

FIRSTROW = First_row_int

FIRSTROW 는 CSV에만 적용됩니다. COPY 명령에 대한 모든 파일에서 먼저 읽는 행 번호를 지정합니다. 값은 1부터 시작되며 이것이 기본값입니다. 값이 2로 설정되면 데이터를 로드할 때 모든 파일의 첫 행(헤더 행)을 건너뜁니다. 행 종결자의 존재에 따라 행을 건너뜁니다.

ENCODING = 'UTF8' | 'UTF16'

ENCODING은 CSV에만 적용됩니다. 기본값은 UTF8입니다. COPY 명령으로 로드된 파일의 데이터 인코딩 표준을 지정합니다.

PARSER_VERSION = { '1.0' | '2.0' }

PARSER_VERSION CSV에만 적용됩니다. 기본값은 2.0입니다. 원본 파일 형식이 CSV일 때 수집에 사용되는 파일 파서입니다. 2.0 파서는 CSV 파일 수집을 위한 향상된 성능을 제공합니다.

파서 버전 2.0에는 다음과 같은 제한 사항이 있습니다.

압축된 CSV 파일은 지원되지 않습니다.
UTF-16 인코딩이 있는 파일은 지원되지 않습니다.
다중 문자 또는 멀티바이트 ROWTERMINATOR, FIELDTERMINATOR 또는 FIELDQUOTE는 지원되지 않습니다. 그러나 '\r\n'은 기본 ROWTERMINATOR로 허용됩니다.

UTF-8 파일과 함께 파서 버전 1.0을 사용하는 경우 FIELDTERMINATOR에는 멀티바이트 및 다중 문자 종결자가 지원되지 않습니다.

파서 버전 1.0은 이전 버전과의 호환성에서만 사용할 수 있으며 이러한 제한 사항이 발생한 경우에만 사용해야 합니다.

참고 항목

COPY INTO를 압축된 CSV 파일 또는 UTF-16 인코딩이 있는 파일과 함께 사용하면 사용자 작업 없이 COPY INTO가 자동으로 PARSER_VERSION 1.0으로 전환됩니다. FIELDTERMINATOR 또는 ROWTERMINATOR의 다중 문자 종결자의 경우 COPY INTO 문이 실패합니다. 여러 문자 구분 기호가 필요한 경우 PARSER_VERSION = '1.0'을 사용합니다.

설명

WAREHOUSE의 COPY INTO에서는 날짜 문자열을 해석하기 위한 날짜 형식 설정을 허용하지 않습니다. 기본적으로 모든 날짜는 월-일-연도 형식으로 간주됩니다. 다른 날짜 형식의 CSV 파일을 수집하려면 SET DATEFORMAT을 사용하여 세션 수준에서 원하는 날짜 형식을 지정합니다. 자세한 내용은 SET DATEFORMAT(Transact-SQL)를 참조하세요.

또한 COPY 문은 행 데이터 및 명령 매개 변수에 대해 UTF-8 및 UTF-16 유효한 문자만 허용합니다. 잘못된 문자를 사용하는 원본 파일 또는 매개 변수(예: ROW TERMINATOR 또는 FIELD TERMINATOR)는 COPY 문에 의해 잘못 해석되어 데이터 손상 또는 기타 오류와 같은 예기치 않은 결과를 초래할 수 있습니다. COPY 문을 호출하기 전에 원본 파일 및 매개 변수가 UTF-8 또는 UTF-16 규격인지 확인합니다.

예제

Microsoft Fabric의 웨어하우스에서 COPY INTO를 사용하는 방법에 대한 자세한 내용은 COPY 문을 사용하여 웨어하우스로 데이터 수집을 참조하세요.

A. 퍼블릭 스토리지 계정에서 로드

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

COPY 명령의 기본값은 다음과 같습니다.

MAXERRORS = 0
압축 기본값은 압축되지 않음
FIELDQUOTE = '"'
FIELDTERMINATOR = ','
ROWTERMINATOR = '\n'

Important

COPY는 내부적으로 \r\n 처리됩니다\n. 자세한 내용은 ROWTERMINATOR 섹션을 참조하세요.

FIRSTROW = 1
ENCODING = 'UTF8'
FILE_TYPE = 'CSV'

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. SAK(Storage 계정 키)를 통해 인증되는 기본값이 있는 열 목록으로 로드

이 예제에서는 기본값을 사용하여 열 목록을 지정하는 파일을 로드합니다.

--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. Parquet 로드

이 예제에서는 와일드카드를 사용하여 실행 중인 사용자의 EntraID를 사용하여 폴더 아래에 있는 모든 Parquet 파일을 로드합니다.

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

E. 와일드카드 및 여러 파일을 지정하여 로드

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 = '|'
)

FAQ

압축된 CSV 파일을 로드하는 COPY 명령에 대한 파일 분할 지침은 무엇인가요?

특히 파일 수가 작지만 성능 향상을 위해 파일을 각각 최소 4MB로 유지하는 경우 큰 CSV 파일을 분할하는 것이 좋습니다.

Parquet 파일을 로드하는 COPY 명령에 대한 파일 분할 지침은 무엇인가요?

특히 파일 수가 적은 경우 큰 Parquet 파일을 분할하는 것이 좋습니다.

파일 개수 또는 크기에 제한이 있나요?

파일 개수 또는 크기에 제한이 없습니다. 하지만 최상의 성능을 위해 4MB 이상의 파일을 사용하는 것이 좋습니다.

자격 증명을 지정하지 않을 때 사용되는 인증 방법은 무엇인가요?

기본적으로 COPY INTRO 실행 중인 사용자의 Entra ID를 사용합니다.

다음을 통해 공유

COPY INTO(Transact-SQL)

구문

인수

schema_name

table_name

(column_list)

외부 위치

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

FILE_FORMAT = external_file_format_name

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

ERRORFILE = 디렉터리 위치

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

MAXERRORS = max_errors

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

FIELDQUOTE = 'field_quote'

FIELDTERMINATOR = 'field_terminator'

ROW TERMINATOR = 'row_terminator'

FIRSTROW = First_row_int

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

ENCODING = 'UTF8' | 'UTF16'

IDENTITY_INSERT = 'ON' | 'OFF'

AUTO_CREATE_TABLE = { 'ON' | 'OFF' }

사용 권한

설명

예제

A. 퍼블릭 스토리지 계정에서 로드

B. SAS(공유 액세스 서명)를 통한 로드 인증

C. 스토리지 계정 키를 통해 인증되는 기본값이 있는 열 목록으로 로드

D. 기존 파일 형식 개체를 사용하여 Parquet 또는 ORC 로드

E. 와일드카드 및 여러 파일을 지정하여 로드

F. MSI 자격 증명을 사용하여 로드하기

G. 자동 스키마 검색을 사용하여 로드

FAQ

PolyBase 대비 COPY 명령의 성능은 어떤가요?

압축된 CSV 파일을 로드하는 COPY 명령에 대한 파일 분할 지침은 무엇인가요?

Parquet 또는 ORC 파일을 로드하는 COPY 명령의 파일 분할 지침은 무엇인가요?

파일 개수 또는 크기에 제한이 있나요?

COPY 문에 알려진 문제가 있나요?

관련 콘텐츠

구문

인수

warehouse_name

schema_name

table_name

(column_list)

외부 위치

FILE_TYPE = { 'CSV' | 'PARQUET' }

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

ERRORFILE = 디렉터리 위치

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

MAXERRORS = max_errors

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

FIELDQUOTE = 'field_quote'

FIELDTERMINATOR = 'field_terminator'

ROWTERMINATOR = 'row_terminator'

FIRSTROW = First_row_int

ENCODING = 'UTF8' | 'UTF16'

PARSER_VERSION = { '1.0' | '2.0' }

설명

예제

A. 퍼블릭 스토리지 계정에서 로드

B. SAS(공유 액세스 서명)를 통한 로드 인증

C. SAK(Storage 계정 키)를 통해 인증되는 기본값이 있는 열 목록으로 로드

D. Parquet 로드

E. 와일드카드 및 여러 파일을 지정하여 로드

FAQ

압축된 CSV 파일을 로드하는 COPY 명령에 대한 파일 분할 지침은 무엇인가요?

Parquet 파일을 로드하는 COPY 명령에 대한 파일 분할 지침은 무엇인가요?

파일 개수 또는 크기에 제한이 있나요?

자격 증명을 지정하지 않을 때 사용되는 인증 방법은 무엇인가요?

관련 콘텐츠

피드백

추가 리소스