COPY INTO(Transact-SQL)

적용 대상:Azure Synapse Analytics

이 글에서는 Azure Synapse Analytics에서 외부 스토리지 계정에서 해당 문장을 사용하는 COPY 방법을 설명합니다. 이 성명은 COPY Azure Synapse Analytics에 대한 고처리량 데이터 인데이스를 위한 가장 큰 유연성을 제공합니다.

Note

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

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

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

Note

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

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

Note

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

Syntax

COPY INTO [ schema. ] table_name
[ (Column_list) ]
FROM '<external_location>' [ , ...n ]
WITH
 (
 [ FILE_TYPE = { 'CSV' | 'PARQUET' | 'ORC' } ]
 [ , FILE_FORMAT = EXTERNAL FILE FORMAT OBJECT ]
 [ , CREDENTIAL = (AZURE CREDENTIAL) ]
 [ , ERRORFILE = ' [ http(s)://storageaccount/container ] /errorfile_directory [ / ] ] '
 [ , ERRORFILE_CREDENTIAL = (AZURE CREDENTIAL) ]
 [ , MAXERRORS = max_errors ]
 [ , COMPRESSION = { 'Gzip' | 'DefaultCodec' | 'Snappy' } ]
 [ , FIELDQUOTE = 'string_delimiter' ]
 [ , FIELDTERMINATOR =  'field_terminator' ]
 [ , ROWTERMINATOR = 'row_terminator' ]
 [ , FIRSTROW = first_row ]
 [ , DATEFORMAT = 'date_format' ]
 [ , ENCODING = { 'UTF8' | 'UTF16' } ]
 [ , IDENTITY_INSERT = { 'ON' | 'OFF' } ]
 [ , AUTO_CREATE_TABLE = { 'ON' | 'OFF' } ]
)

Arguments

schema_name

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

table_name

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

(column_list)

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

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

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

[(Column_name [기본 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\>

Note

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

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

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

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

Note

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

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

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

FILE_TYPE = { 'CSV' | '마루' | '옥스'}

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

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

Note

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

FILE_FORMAT = external_file_format_name

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

자격 증명(IDENTITY = '', SECRET = '')

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

	CSV	Parquet	ORC
Azure Blob Storage	SAS/MSI/SERVICE PRINCIPAL/KEY/Entra	SAS/KEY	SAS/KEY
Azure 데이터 레이크 Gen2	SAS/MSI/SERVICE PRINCIPAL/KEY/Entra	SAS(blob ¹)/MSI(dfs ²)/SERVICE PRINCIPAL/KEY/Entra	SAS(blob ¹)/MSI(dfs ²)/SERVICE PRINCIPAL/KEY/Entra

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

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

Note

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

SAS(공유 액세스 서명)를 사용하여 인증
- 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만들어집니다. 이 문자는 _ 위치 매개 변수에 명시적으로 이름을 지정하지 않는 한 다른 데이터 처리를 위해 디렉터리가 이스케이프되도록 합니다.

Note

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

Note

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 스토리지 계정 키 사용은 지원되지 않습니다.

Note

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

MAXERRORS = max_errors

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

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

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

압축 = { 'DefaultCodec ' | '스내피' | 'GZIP' | '전혀'}

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

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

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

.gz - 지지프
.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에서 지원되지 않습니다.

Note

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

필드터미네이터 = 'field_terminator'

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

행 종결자 = 'row_terminator'

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

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

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

1열 = First_row_int

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

DATEFORM = { 'mdy' | 'DMY' | 'ymd' | 'ydm' | '마이드' | 'dym'}

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

인코딩 = 'UTF8' | 'UTF16'

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

IDENTITY_INSERT = '켜' | '꺼져'

IDENTITY_INSERT는 가져온 데이터 파일의 ID 값 또는 값을 ID 열에 사용할지 여부를 지정합니다. IDENTITY_INSERT가 OFF(기본값)이면 이 열의 ID 값은 확인되지만 가져오지는 않습니다. COPY 명령을 사용하여 다음 동작을 기록합니다.

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

Azure Synapse Analytics는 테이블을 만드는 동안 지정된 초기값 및 증가 값을 기반으로 고유 값을 자동으로 할당합니다.

AUTO_CREATE_TABLE = { '온' | '꺼짐' }

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

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

Note

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

Permissions

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

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

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

예를 들어 COPY를 사용하여 스키마에 mike@contoso.com 새 테이블을 만들고 Parquet 파일의 데이터를 삽입하려면 HR 다음 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];

Remarks

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

쿼리 힌트는 MAXDOPCOPY INTO.

신뢰할 수 있는 실행을 보장하려면 작업 기간 COPY INTO 동안 원본 파일 및 폴더가 변경되지 않은 상태로 유지되어야 합니다.

명령이 실행되는 동안 참조된 파일 또는 폴더를 수정, 삭제 또는 교체하면 작업이 실패하거나 일관되지 않은 데이터 수집이 발생할 수 있습니다.
실행하기 COPY INTO전에 모든 원본 데이터가 안정적이며 프로세스 중에 변경되지 않는지 확인합니다.

Examples

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

다음 예시는 공공 저장소 계정에서 데이터를 불러오는 명령어 COPY 의 가장 단순한 형태입니다. 이 예제에서 COPY 문의 기본값은 줄 항목 csv 파일의 형식과 일치합니다.

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

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

DATEFORM = 세션 DATEFORM
맥스에러 = 0
압축 기본값은 압축되지 않음
FIELDQUOTE = '"'
필드터미네이터 = ','
행 터미네이터 = '\n'

Important

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

1열 = 1
인코딩 = 'UTF8'
FILE_TYPE = 'CSV'
IDENTITY_INSERT = '오프'

다음 예제에서는 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
10,000	1200
15,000	1800
30,000	3600

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

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

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

파일 개수 또는 크기에 제한이 없습니다. 하지만 최상의 성능을 위해 4MB 이상의 파일을 사용하는 것이 좋습니다. 또한 성능 향상을 위해 원본 파일 수를 최대 5,000개의 파일로 제한합니다.

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 계정 및 OneLake 원본이 지원됩니다.

Microsoft Fabric에서 웨어하우스를 사용하는 COPY INTO 방법에 대한 자세한 내용은 COPY 문으로 데이터를 웨어하우스에 인젝트하는 항목을 참조하세요.

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

다음 기능에 대한 사용 COPY :

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

Syntax

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 ]
 [ , DATEFORMAT = 'date_format' ]
 [ , ENCODING = { 'UTF8' | 'UTF16' } ]
 [ , PARSER_VERSION = { '1.0' | '2.0' } ]
 [ , MATCH_COLUMN_COUNT = { 'ON' | 'OFF' } ]
)

Arguments

warehouse_name

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

schema_name

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

table_name

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

(column_list)

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

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

[(Column_name [기본 Default_value] [Field_number] [,... n])]

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

column_list가 지정되지 않을 경우, COPY 소스와 대상 순서에 따라 열을 매핑합니다: 입력 필드 1은 타겟 열 1로, 필드 2는 열 2로 가는 식입니다.

Note

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

열 목록이 지정되지 않을 경우, COPY 입력 필드 1은 대상 열 1로, 필드 2는 2열 등으로 이동하는 등 열을 매핑합니다.

외부 위치

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

Blob Storage의 외부 위치 : https://<account\>.blob.core.windows.net/<container\>/<path\>
ADLS Gen2의 외부 위치 : https://<account\>.dfs.core.windows.net/<container\>/<path\>
OneLake의 외부 위치(미리 보기):https://onelake.dfs.fabric.microsoft.com/<workspaceId>/<lakehouseId>/Files/

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

Note

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

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

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

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

Note

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

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' | '파케' }

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

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

자격 증명(IDENTITY = '', SECRET = '')

CREDENTIAL 외부 스토리지 계정에 액세스하기 위한 인증 메커니즘을 지정합니다.

패브릭 데이터 웨어하우스에서:

COPY INTO 공용 액세스가 비활성화된 경우에는 지원되지 않습니다.
공용 스토리지 계정의 경우 지원되는 인증 메커니즘은 Microsoft Entra ID, SAS(공유 액세스 서명) 또는 SAK(스토리지 계정 키)입니다.
방화벽 뒤에 있는 공용 스토리지 계정의 경우 Microsoft Entra ID 인증이 유일하게 지원되는 인증 방법입니다. COPY INTO OneLake를 원본으로 사용하면 EntraID 인증만 지원됩니다.

사용자의 EntraID 인증은 기본값입니다. 자격 증명을 지정할 필요가 없습니다.

SAS(공유 액세스 서명)를 사용하여 인증
- IDENTITY: 값이 'Shared Access Signature'인 상수입니다.
- SECRET: 공유 액세스 서명 은 스토리지 계정의 리소스에 대한 위임된 액세스를 제공합니다.
- 필요한 최소 권한: READ 및 LIST.
스토리지 계정 키를 사용하여 인증
- IDENTITY: 값이 '스토리지 계정 키'인 상수입니다.
- SECRET: 스토리지 계정 키입니다.

ERRORFILE = 디렉터리 위치

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

Note

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

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

방화벽으로 보호되는 Azure Storage 계정을 사용하는 경우 오류 파일은 스토리지 계정 경로에 지정된 동일한 컨테이너에 만들어집니다. 이 시나리오에서 ERRORFILES 옵션을 사용하는 경우 MAXERROR 매개 변수를 지정해야 합니다. ERRORFILE에 정의된 스토리지 계정의 전체 경로가 있는 경우 ERRORFILE_CREDENTIAL 해당 스토리지에 연결하는 데 사용됩니다. 그렇지 않으면 CREDENTIAL에 대해 언급된 값이 사용됩니다.

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

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

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

Note

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

MAXERRORS = max_errors

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

Microsoft Fabric에서는 FILE_TYPE때 PARQUET를 사용할 수 없습니다.

압축 = { '스냅' | 'GZIP' | '전혀'}

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

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

이 명령어는 COPY 이 매개변수가 지정되지 않은 경우 파일 확장자를 기반으로 압축 유형을 자동으로 감지합니다:

.gz - 지지프

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

이 명령어는 COPY 정상적으로 작동하려면 gzip 파일에 뒤따르는 가비지를 포함하지 않아야 합니다. gzip 형식을 사용하려면 파일이 이전, 사이 또는 그 이후의 추가 정보 없이 유효한 멤버로 구성되어야 합니다. 이 형식에서 벗어나면, 예를 들어 뒤에 비-gzip 데이터가 존재하면 명령어가 COPY 실패합니다. gzip 파일 끝에 쓰레기가 없는지 꼭 확인해서 COPY 파일을 제대로 처리할 수 있도록 하세요.

FIELDQUOTE = 'field_quote'

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

Note

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

필드터미네이터 = 'field_terminator'

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

ROWTERMINATOR = 'row_terminator'

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

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

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

1열 = First_row_int

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

DATEFORM = { 'mdy' | 'DMY' | 'ymd' | 'ydm' | '마이드' | 'dym'}

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

인코딩 = '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은 이전 버전과의 호환성에서만 사용할 수 있으며 이러한 제한 사항이 발생한 경우에만 사용해야 합니다.

Note

압축된 CSV 파일이나 UTF-16 인코딩 파일이 사용될 때 COPY INTO 는 COPY INTO 사용자 조작 없이 자동으로 1.0으로 PARSER_VERSION 전환됩니다. 또는 에 대한 FIELDTERMINATORROWTERMINATOR다중 문자 종말자에 대해서는 문 COPY INTO 장이 실패합니다. 다중 문자 구분자가 필요할 때 사용됩니다 PARSER_VERSION = '1.0' .

MATCH_COLUMN_COUNT = { '온' | '꺼짐' }

MATCH_COLUMN_COUNT CSV에만 적용됩니다. 기본값은 OFF. COPY 명령에서 원본 파일의 열 개수 행이 대상 테이블의 열 개수와 일치하는지 여부를 지정합니다. 다음 동작이 적용됩니다.

MATCH_COLUMN_COUNTOFF경우:
- 원본 행에서 열을 초과하면 무시됩니다.
- 열 수가 적은 행은 null 허용 열에 null로 삽입됩니다.
- 비공허 열에 값이 제공되지 않으면 명령어가 COPY 실패합니다.
MATCH_COLUMN_COUNTON경우:
- 이 명령어는 COPY 소스에서 각 파일의 각 행의 열 수가 목적지 테이블의 열 개수와 일치하는지 확인합니다.
열 수 불일치가 있으면 명령어가 COPY 실패합니다.

Note

MATCH_COLUMN_COUNTMAXERRORS독립적으로 작동합니다. 열 개수가 일치하지 않는 경우 COPY INTOMAXERRORS관계없이 실패합니다.

OneLake에서 COPY INTO 사용

패브릭 OneLake에 저장된 파일, 특히 Fabric Lakehouse의 COPY INTO에서 직접 데이터를 로드하는 데 사용할 수 있습니다. 이렇게 하면 외부 스테이징 계정(예: ADLS Gen2 또는 Blob Storage)이 필요하지 않으며 패브릭 권한을 사용하여 작업 영역 관리 SaaS 네이티브 수집을 사용할 수 있습니다. 이 기능은 다음을 지원합니다.

Lakehouses의 폴더에서 Files 읽기
동일한 테넌트 내에서 작업 영역-웨어하우스 로드
Microsoft Entra ID를 사용하는 네이티브 ID 적용

Example:

COPY INTO t1
FROM 'https://onelake.dfs.fabric.microsoft.com/<workspaceId>/<lakehouseId>/Files/*.csv'
WITH (
    FILE_TYPE = 'CSV',
    FIRSTROW = 2
);

Permissions

컨트롤 플레인 사용 권한

명령을 실행하려면 사용자에게 최소한 뷰어 역할을 사용하여 작업 영역액세스 관리 통해 작업 영역 역할을 멤버 자격을 부여해야 합니다. 또는 웨어하우스 액세스는 적어도 읽기 권한으로 패브릭 포털에서 항목 권한 통해 사용자와 공유할 수 있습니다. 최소 권한 원칙에 맞게 읽기 권한으로 충분합니다.

데이터 평면 사용 권한

사용자에게 작업 영역 역할 또는 항목 권한을 통해 제어 평면 권한이 부여되면 데이터 평면 수준읽기 권한만 있는 경우 사용자에게 T-SQL 명령을 통해 및 권한도 부여해야 합니다.

예를 들어 다음 T-SQL 스크립트는 Microsoft Entra ID를 통해 개별 사용자에게 이러한 권한을 부여합니다.

GRANT ADMINISTER DATABASE BULK OPERATIONS to [mike@contoso.com];
GO

GRANT INSERT to [mike@contoso.com];
GO

ErrorFile 옵션을 사용하는 경우 사용자는 Storage 계정 컨테이너에 대한 Blob Storage 기여자의 최소 권한이 있어야 합니다.

OneLake를 원본으로 사용하는 경우 사용자는 원본 작업 영역(Lakehouse가 있는 위치)과 대상 작업 영역(웨어하우스가 있는 위치)에 대한 기여자 이상의 권한이 있어야 합니다. 모든 액세스는 Microsoft Entra ID 및 패브릭 작업 영역 역할을 통해 제어됩니다.

Remarks

이 문장은 COPY 행 데이터와 명령 매개변수에 대해 UTF-8과 UTF-16 유효 문자만 허용합니다. 잘못된 문자를 사용하는 소스 파일이나 매개변수(예: ROW TERMINATOR 또는 FIELD TERMINATOR)는 문장에 COPY 의해 잘못 해석되어 데이터 손상이나 기타 실패와 같은 예상치 못한 결과를 초래할 수 있습니다. 문장을 호출 COPY 하기 전에 소스 파일과 매개변수가 UTF-8 또는 UTF-16 준수 여부를 반드시 확인하세요.

이 문장은 COPY INTO 개별 varchar(max) 및 varbinary(max) 열의 크기와 인제스트할 수 있는 전체 행 크기에 제한이 있습니다.

Parquet: 최대 varchar(max)/varbinary(max) 열 크기 16MB, 최대 행 크기 1GB.
CSV: 최대 varchar(max)/varbinary(max) 열 크기 1MB, 최대 행 크기 16MB.

신뢰할 수 있는 실행을 보장하려면 작업 기간 COPY INTO 동안 원본 파일 및 폴더가 변경되지 않은 상태로 유지되어야 합니다.

명령이 실행되는 동안 참조된 파일 또는 폴더를 수정, 삭제 또는 교체하면 작업이 실패하거나 일관되지 않은 데이터 수집이 발생할 수 있습니다.
실행하기 COPY INTO전에 모든 원본 데이터가 안정적이며 프로세스 중에 변경되지 않는지 확인합니다.

OneLake를 원본으로 사용하는 제한 사항

패브릭 OneLake 스토리지는 둘 다 COPY INTO 에 대한 원본이며 OPENROWSET(BULK)미리 보기 기능입니다.

Microsoft Entra ID 인증만 지원됩니다. SAS 토큰, 공유 키 또는 연결 문자열과 같은 다른 인증 방법은 허용되지 않습니다.
Lakehouse 폴더 Files 만 원본으로 지원됩니다. 하위 폴더, 바로 가기 또는 다른 OneLake 위치에 대한 액세스는 현재 사용할 수 없습니다.
OneLake 경로는 작업 영역 및 웨어하우스 ID를 사용해야 합니다. 작업 영역 또는 Lakehouses에 대한 친숙한 이름은 현재 지원되지 않습니다.
참가자 권한은 두 작업 영역에서 모두 필요합니다. 실행 중인 사용자에게는 원본 Lakehouse 작업 영역 및 대상 웨어하우스 작업 영역에서 적어도 기여자 역할이 있어야 합니다.

Examples

Microsoft Fabric에서 웨어하우스를 사용하는 COPY INTO 방법에 대한 자세한 내용은 COPY 문으로 데이터를 웨어하우스에 인젝트하는 항목을 참조하세요.

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

다음 예시는 공공 저장소 계정에서 데이터를 불러오는 명령어 COPY 의 가장 단순한 형태입니다. 이 예시 COPY 에서 문장의 기본값은 라인 항목 csv 파일의 형식과 일치합니다.

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

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

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

Important

COPY 내부적으로 다루는 것으로 간주 \n\r\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 로드

이 예제에서는 와일드카드를 사용하여 실행 중인 사용자의 Entra ID를 사용하여 폴더 아래에 있는 모든 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 = '|'
)

F. OneLake에서 데이터 로드(공개 미리 보기)

COPY INTO t1
FROM 'https://onelake.dfs.fabric.microsoft.com/<workspaceId>/<lakehouseId>/Files/*.csv'
WITH (
    FILE_TYPE = 'CSV',
    FIRSTROW = 2
);

FAQ

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

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

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

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

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

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

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

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

피드백

이 페이지가 도움이 되었나요?

Last updated on 2025-11-19

다음을 통해 공유

COPY INTO(Transact-SQL)

Syntax

Arguments

schema_name

table_name

(column_list)

외부 위치

FILE_TYPE = { 'CSV' | '마루' | '옥스'}

FILE_FORMAT = external_file_format_name

자격 증명(IDENTITY = '', SECRET = '')

ERRORFILE = 디렉터리 위치

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

MAXERRORS = max_errors

압축 = { 'DefaultCodec ' | '스내피' | 'GZIP' | '전혀'}

FIELDQUOTE = 'field_quote'

필드터미네이터 = 'field_terminator'

행 종결자 = 'row_terminator'

1열 = First_row_int

DATEFORM = { 'mdy' | 'DMY' | 'ymd' | 'ydm' | '마이드' | 'dym'}

인코딩 = 'UTF8' | 'UTF16'

IDENTITY_INSERT = '켜' | '꺼져'

AUTO_CREATE_TABLE = { '온' | '꺼짐' }

Permissions

Remarks

Examples

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

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

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

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

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

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

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

FAQ

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

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

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

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

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

관련 콘텐츠

Syntax

Arguments

warehouse_name

schema_name

table_name

(column_list)

외부 위치

FILE_TYPE = { 'CSV' | '파케' }

자격 증명(IDENTITY = '', SECRET = '')

ERRORFILE = 디렉터리 위치

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

MAXERRORS = max_errors

압축 = { '스냅' | 'GZIP' | '전혀'}

FIELDQUOTE = 'field_quote'

필드터미네이터 = 'field_terminator'

ROWTERMINATOR = 'row_terminator'

1열 = First_row_int

DATEFORM = { 'mdy' | 'DMY' | 'ymd' | 'ydm' | '마이드' | 'dym'}

인코딩 = 'UTF8' | 'UTF16'

PARSER_VERSION = { '1.0' | '2.0' }

MATCH_COLUMN_COUNT = { '온' | '꺼짐' }

OneLake에서 COPY INTO 사용

Permissions

컨트롤 플레인 사용 권한

데이터 평면 사용 권한

Remarks

OneLake를 원본으로 사용하는 제한 사항

Examples

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

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

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

D. Parquet 로드

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

F. OneLake에서 데이터 로드(공개 미리 보기)

FAQ

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

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

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

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

관련 콘텐츠