외부 테이블로 데이터 내보내기
적용 대상: ✅Microsoft Fabric✅Azure Data Explorer
외부 테이블을 정의하고 해당 테이블로 데이터를 내보내 데이터를 내보낼 수 있습니다. 테이블 속성은 외부 테이블을 만들 때 지정됩니다. 내보내기 명령은 이름으로 외부 테이블을 참조합니다.
사용 권한
이 명령을 실행하려면 테이블 관리자 이상의 권한이 있어야 합니다.
구문
.export [async] to table externalTableName
[with (propertyName = propertyValue [, ...]] <| )쿼리
구문 규칙에 대해 자세히 알아봅니다.
매개 변수
| 이름 | Type | 필수 | 설명 |
|---|---|---|---|
| externalTableName | string |
✔️ | 내보낼 외부 테이블의 이름입니다. |
| propertyName, propertyValue | string |
선택적 속성의 쉼표로 구분된 목록입니다. | |
| query | string |
✔️ | 내보내기 쿼리입니다. |
지원되는 속성
다음 속성은 외부 테이블로 내보내기 명령의 일부로 지원됩니다.
| 속성 | Type | 설명 | 기본값 |
|---|---|---|---|
sizeLimit |
long |
단일 스토리지 아티팩트(압축 전)의 크기 제한(바이트)입니다. 이 행 그룹이 크기 제한에 도달하여 새 아티팩트를 시작해야 하는지 여부를 확인하기 전에 전체 행 크기 parquetRowGroupSize 그룹이 작성됩니다. 유효한 범위: 100MB(기본값)~1GB |
|
distributed |
bool |
분산 내보내기 사용 안 함/사용 false로 설정하는 것은 배포 힌트와 single 동일합니다. |
기본값은 true입니다. |
distribution |
string |
배포 힌트(single, per_node, per_shard). 배포 설정에서 자세한 정보 보기 |
기본값은 per_node입니다. |
distributionKind |
string |
필요에 따라 외부 테이블이 문자열 파티션으로 분할될 때 균일한 분포로 전환됩니다. 유효한 값은 uniform 또는 default입니다. 배포 설정에서 자세한 정보 보기 |
|
concurrency |
숫자 | 병렬로 실행할 파티션 수를 시스템에 암시합니다. 배포 설정에서 자세한 정보 보기 | 기본값은 16입니다. |
spread |
숫자 | 노드 간에 파티션을 배포하는 방법을 시스템에 암시합니다. 배포 설정에서 자세한 정보 보기 | 기본값은 Min(64, number-of-nodes)입니다. |
parquetRowGroupSize |
int |
데이터 형식이 Parquet인 경우에만 관련됩니다. 내보낸 파일의 행 그룹 크기를 제어합니다. 이 값이 우선 sizeLimit합니다. 즉, 이 행 그룹이 크기 제한에 도달했는지 여부를 확인하기 전에 전체 행 그룹이 내보내지고 새 아티팩트를 시작해야 합니다. |
기본 행 그룹 크기는 100,000개의 레코드입니다. |
배포 설정
외부 테이블로 내보내기 작업의 분포는 스토리지에 동시에 쓰는 노드 및 스레드의 수를 나타냅니다. 기본 분포는 외부 테이블 분할에 따라 달라집니다.
| 외부 테이블 분할 | 기본 배포 |
|---|---|
외부 테이블이 분할되지 않거나 열로 datetime 만 분할되지 않음 |
내보내기가 분산됩니다 per_node . 모든 노드가 동시에 내보내고 있습니다. 각 노드는 해당 노드에 할당된 데이터를 씁니다. 노드에서 내보낸 파일 수는 해당 노드의 데이터 크기가 초과하는 경우에만 1보다 큽니다 sizeLimit. |
| 외부 테이블은 문자열 열로 분할됩니다. | 내보낼 데이터는 노드 간에 이동되므로 각 노드는 파티션 값의 하위 집합을 작성합니다. 단일 파티션은 항상 단일 노드에 의해 작성됩니다. 파티션당 기록된 파일 수는 데이터가 초과하는 경우에만 1보다 커야 합니다 sizeLimit. 외부 테이블에 여러 문자열 파티션이 포함된 경우 데이터는 첫 번째 파티션을 기반으로 노드 간에 분할됩니다. 따라서 가장 균일한 배포를 사용하여 파티션을 첫 번째 파티션으로 정의하는 것이 좋습니다. |
기본 배포 설정 변경
기본 배포 설정을 변경하는 것은 다음과 같은 경우에 유용할 수 있습니다.
| 사용 사례 | 설명 | 권장 |
|---|---|---|
| 내보낸 파일 수 줄이기 | 내보내기가 너무 많은 작은 파일을 만들고 있으므로 더 적은 수의 더 큰 파일을 만들려고 합니다. | 명령 속성에서 설정 distribution=single 하거나 distributed=false (둘 다 동일) 단일 스레드만 내보내기를 수행합니다. 단점은 동시성이 훨씬 감소하므로 내보내기 작업이 느려질 수 있다는 것입니다. |
| 내보내기 기간 줄이기 | 내보내기 작업의 동시성을 늘려 기간을 줄입니다. | 명령 속성에서 설정합니다 distribution=per_shard . 즉, 쓰기 작업의 동시성은 노드당이 아니라 데이터 분할된 데이터베이스당입니다. 이는 문자열 파티션으로 분할되지 않은 외부 테이블로 내보낼 때만 관련이 있습니다. 이로 인해 스토리지에 부하가 너무 많이 발생하여 제한이 발생할 수 있습니다. 스토리지 오류를 참조 하세요. |
| 문자열 파티션으로 분할된 외부 테이블의 내보내기 기간 줄이기 | 파티션이 노드 간에 균일하게 분산되지 않으면 내보내기를 실행하는 데 시간이 더 오래 걸릴 수 있습니다. 예를 들어 다른 파티션보다 훨씬 큰 단일 파티션이 있는 경우 대부분의 내보내기 작업은 해당 파티션에 할당된 단일 노드에 의해 수행되지만 다른 노드는 대부분 유휴 상태입니다. 배포 설정을 참조하세요. | 변경할 수 있는 몇 가지 설정은 다음과 같습니다. * 둘 이상의 문자열 파티션이 있는 경우 가장 적합한 분포를 가진 파티션을 먼저 정의합니다. * 명령 속성에서 설정합니다 distributionKind=uniform . 이 설정은 문자열로 분할된 외부 테이블에 대한 기본 배포 설정을 사용하지 않도록 설정합니다. 내보내기가 배포와 함께 per-node 실행되고 각 노드는 노드에 할당된 데이터를 내보냅니다. 여러 노드에서 단일 파티션을 작성할 수 있으며 그에 따라 파일 수가 증가합니다. 동시성을 한층 더 높이려면 가장 높은 동시성을 위해 설정합니다 distributionKindper_shard=uniform distribution=(잠재적으로 더 많은 파일이 기록될 수 있는 비용).* 느린 내보내기 원인이 데이터의 이상값이 아닌 경우 분할 설정을 변경하지 않고 동시성을 증가시켜 기간을 줄입니다. 분할의 hint.spread 동시성을 결정하는 및 hint.concurrency 속성을 사용합니다. 파티션 연산자 참조 기본적으로 동시에 내보내는 노드 수() spread는 64개와 노드 수 사이의 최소값입니다. 노드 수보다 높은 수로 설정 spread 하면 각 노드의 동시성이 증가합니다(최대값 spread 은 64). |
인증 및 권한 부여
외부 테이블로 내보내려면 쓰기 권한을 설정해야 합니다. 자세한 내용은 Azure Storage 외부 테이블 또는 SQL Server 외부 테이블에 대한 쓰기 권한을 참조하세요.
출력
| 출력 매개 변수 | Type | 설명 |
|---|---|---|
| ExternalTableName | string |
외부 테이블의 이름입니다. |
| Path | string |
출력 경로. |
| NumRecords | string |
경로로 내보낸 레코드 수입니다. |
주의
내보내기 쿼리 출력 스키마는 파티션에 의해 정의된 모든 열을 포함하여 외부 테이블의 스키마와 일치해야 합니다. 예를 들어 테이블이 DateTime으로 분할된 경우 쿼리 출력 스키마에는 TimestampColumnName과 일치하는 타임스탬프 열이 있어야 합니다. 이 열 이름은 외부 테이블 분할 정의에 정의되어 있습니다.
내보내기 명령을 사용하여 외부 테이블 속성을 재정의할 수 없습니다. 예를 들어 Parquet 형식의 데이터를 CSV 데이터 형식의 외부 테이블로 내보낼 수 없습니다.
외부 테이블이 분할된 경우 내보낸 아티팩트가 분할된 외부 테이블 예제와 같이 파티션 정의에 따라 해당 디렉터리에 기록됩니다.
- 파티션 값이 null/empty이거나 잘못된 디렉터리 값인 경우 대상 스토리지의 정의에 따라 파티션 값이 기본값
__DEFAULT_PARTITION__으로 바뀝니다.
- 파티션 값이 null/empty이거나 잘못된 디렉터리 값인 경우 대상 스토리지의 정의에 따라 파티션 값이 기본값
내보내기 명령 중 스토리지 오류를 극복하기 위한 제안 사항은 내보내기 명령 중 오류를 참조 하세요.
외부 테이블 열은 데이터 형식 매핑 규칙에 따라 적절한 대상 형식 데이터 형식에 매핑됩니다.
Parquet 네이티브 내보내기는 보다 성능이 좋은 리소스 조명 내보내기 메커니즘입니다. 내보낸 'datetime' 열은 현재 Synapse SQL 'COPY'에서 지원되지 않습니다.
파일 수
파티션당 기록된 파일 수는 내보내기 작업의 배포 설정에 따라 달라집니다.
외부 테이블에 날짜/시간 파티션만 포함하거나 파티션이 전혀 없는 경우 기록된 파일 수(있는 경우 각 파티션에 대해)는 노드 수(또는 도달한 경우
sizeLimit이상)와 유사해야 합니다. 내보내기 작업이 분산되면 모든 노드가 동시에 내보냅니다. 배포를 사용하지 않도록 설정하려면 단일 노드만 쓰기를 수행하도록 하려면 false로 설정합니다distributed. 이 프로세스는 파일을 더 적게 만들지만 내보내기 성능은 저하됩니다.외부 테이블에 문자열 열로 파티션이 포함된 경우 내보낸 파일 수는 파티션당 단일 파일(또는 도달한 경우
sizeLimit이상)이어야 합니다. 모든 노드는 여전히 내보내기(작업이 분산됨)에 참여하지만 각 파티션은 특정 노드에 할당됩니다. false로 설정distributed하면 단일 노드만 내보내기를 수행하지만 동작은 동일하게 유지됩니다(파티션당 작성된 단일 파일).
예제
분할되지 않은 외부 테이블 예제
ExternalBlob은 분할되지 않은 외부 테이블입니다.
.export to table ExternalBlob <| T
| ExternalTableName | Path | NumRecords |
|---|---|---|
| ExternalBlob | http://storage1.blob.core.windows.net/externaltable1cont1/1_58017c550b384c0db0fea61a8661333e.csv | 10 |
분할된 외부 테이블 예제
PartitionedExternalBlob은 다음과 같이 정의된 외부 테이블입니다.
.create external table PartitionedExternalBlob (Timestamp:datetime, CustomerName:string)
kind=blob
partition by (CustomerName:string=CustomerName, Date:datetime=startofday(Timestamp))
pathformat = ("CustomerName=" CustomerName "/" datetime_pattern("yyyy/MM/dd", Date))
dataformat=csv
(
h@'http://storageaccount.blob.core.windows.net/container1;secretKey'
)
.export to table PartitionedExternalBlob <| T
| ExternalTableName | Path | NumRecords |
|---|---|---|
| ExternalBlob | http://storageaccount.blob.core.windows.net/container1/CustomerName=customer1/2019/01/01/fa36f35c-c064-414d-b8e2-e75cf157ec35_1_58017c550b384c0db0fea61a8661333e.csv | 10 |
| ExternalBlob | http://storageaccount.blob.core.windows.net/container1/CustomerName=customer2/2019/01/01/fa36f35c-c064-414d-b8e2-e75cf157ec35_2_b785beec2c004d93b7cd531208424dc9.csv | 10 |
키워드를 사용하여 async 명령이 비동기적으로 실행되는 경우 작업 세부 정보 표시 명령을 사용하여 출력을 사용할 수 있습니다.