클라우드 스토리지로 데이터 내보내기

아티클
01/18/2024

쿼리를 실행하고 스토리지 연결 문자열 지정된 외부 클라우드 스토리지에 첫 번째 결과 집합을 씁니다.

사용 권한

이 명령을 실행하려면 데이터베이스 뷰어 이상의 권한이 있어야 합니다.

Syntax

.export [async] [compressed] toOutputDataFormat(StorageConnectionString [, ...] ) [with(PropertyName=PropertyValue [, ...] )] <|쿼리

구문 규칙에 대해 자세히 알아봅니다.

매개 변수

이름	형식	필수	Description
`async`	`string`		지정된 경우 명령은 비동기 모드에서 실행됩니다. 비동기 모드를 참조하세요.
`compressed`	`string`		지정된 경우 출력 스토리지 아티팩트가 파일로 `.gz` 압축됩니다. `compressionType` Parquet 파일을 snappy로 압축하는 데 지원되는 속성을 참조하세요.
OutputDataFormat	`string`	✔️	명령에서 작성한 스토리지 아티팩트 데이터 형식을 나타냅니다. 지원되는 값은 `csv`, `tsv`, `json` 및 `parquet`입니다.
StorageConnectionString	`string`		데이터를 쓸 스토리지를 나타내는 하나 이상의 스토리지 연결 문자열 입니다. 확장 가능한 쓰기에 대해 둘 이상의 스토리지 연결 문자열 지정할 수 있습니다. 이러한 각 연결 문자열 스토리지에 쓸 때 사용할 자격 증명을 나타내야 합니다. 예를 들어 Azure Blob Storage 쓸 때 자격 증명은 Blob을 읽고, 쓰고, 나열할 수 있는 권한이 있는 스토리지 계정 키 또는 SAS(공유 액세스 키)일 수 있습니다.
PropertyName, PropertyValue	`string`		키-값 속성 쌍의 쉼표로 구분된 목록입니다. 지원되는 속성을 참조하세요.

참고

클러스터 자체와 동일한 지역에 있는 스토리지로 데이터를 내보내는 것이 좋습니다. 여기에는 다른 지역의 다른 클라우드 서비스로 전송할 수 있도록 내보내는 데이터가 포함됩니다. 읽기는 원격으로 발생할 수 있지만 쓰기는 로컬로 수행해야 합니다.

지원되는 속성

속성	형식	Description
`includeHeaders`	`string`	출력의 경우 `csv`/`tsv` 열 헤더 생성을 제어합니다. (기본값, 내보낸 헤더 줄 없음), `all` (모든 스토리지 아티팩트로 헤더 줄 내보내기) 또는 `firstFile` (헤더 줄을 첫 번째 스토리지 아티팩트로만 내보내기) 중 하나 `none` 일 수 있습니다.
`fileExtension`	`string`	스토리지 아티팩트(예: `.csv` 또는 `.tsv`)의 "확장" 부분을 나타냅니다. 압축을 사용하는 경우 도 `.gz` 가 추가됩니다.
`namePrefix`	`string`	생성된 각 스토리지 아티팩트 이름에 추가할 접두사를 나타냅니다. 임의 접두사는 지정되지 않은 상태로 두면 사용됩니다.
`encoding`	`string`	(기본값) 또는 `UTF8BOM`텍스트를 `UTF8NoBOM` 인코딩하는 방법을 나타냅니다.
`compressionType`	`string`	사용할 압축 유형을 나타냅니다. 가능한 값은 `gzip` 또는 `snappy`입니다. 기본값은 `gzip`입니다. `snappy` 형식에 사용할 `parquet` 수 있습니다(선택 사항).
`distribution`	`string`	배포 힌트(`single`, `per_node`, `per_shard`). 값이 이 `single`면 단일 스레드가 스토리지에 씁니다. 그렇지 않으면 쿼리를 실행하는 모든 노드에서 쓰기를 병렬로 내보냅니다. 플러그 인 연산자 평가를 참조하세요. 기본값은 `per_shard`입니다.
`persistDetails`	`bool`	명령이 결과를 유지해야 했음을 나타냅니다(플래그 참조 `async` ). 기본값은 `true` 비동기 실행에서 로 설정되지만 호출자에게 결과가 필요하지 않은 경우 해제할 수 있습니다.) 기본값은 `false` 동기 실행에서 로 설정되지만 해당 실행에서도 설정할 수 있습니다.
`sizeLimit`	`long`	단일 스토리지 아티팩트(압축 전)의 크기 제한(바이트)입니다. 유효한 범위: 100MB(기본값)~4GB.
`parquetRowGroupSize`	`int`	데이터 형식이 Parquet인 경우에만 관련됩니다. 내보낸 파일의 행 그룹 크기를 제어합니다. 기본 행 그룹 크기는 100,000 레코드입니다.
`distributed`	`bool`	분산 내보내기 사용 안 함/사용 false로 설정하는 것은 배포 힌트와 `single` 동일합니다. 기본값은 true입니다.
`parquetDatetimePrecision`	`string`	값을 Parquet로 내보낼 때 사용할 전체 자릿수를 `datetime` 지정합니다. 가능한 값은 밀리초 및 마이크로초입니다. 기본값은 밀리초입니다.

인증 및 권한 부여

인증 방법은 제공된 연결 문자열 기반으로 하며 필요한 권한은 인증 방법에 따라 달라집니다.

다음 표에는 지원되는 인증 방법 및 스토리지 유형별로 외부 스토리지로 데이터를 내보내는 데 필요한 권한이 나와 있습니다.

인증 방법	Azure Blob Storage/Data Lake Storage Gen2	Data Lake Storage Gen1
가장	Storage Blob 데이터 기여자	참가자
SAS(공유 액세스) 토큰	쓰기	쓰기
액세스 토큰 Microsoft Entra	추가 권한이 필요하지 않음	추가 권한이 필요하지 않음
스토리지 계정 액세스 키	추가 권한이 필요하지 않음	추가 권한이 필요하지 않음

반환

명령은 생성된 스토리지 아티팩트 설명 테이블을 반환합니다. 각 레코드는 단일 아티팩트에 대해 설명하고 아티팩트에 대한 스토리지 경로와 아티팩트가 보유하는 레코드 수를 포함합니다.

경로	NumRecords
http://storage1.blob.core.windows.net/containerName/export_1_d08afcae2f044c1092b279412dcb571b.csv	10
http://storage1.blob.core.windows.net/containerName/export_2_454c0f1359e24795b6529da8a0101330.csv	15

비동기 모드

플래그를 async 지정하면 명령이 비동기 모드로 실행됩니다. 이 모드에서는 명령이 작업 ID로 즉시 반환되고 완료될 때까지 백그라운드에서 데이터 내보내기를 계속합니다. 명령에서 반환된 작업 ID를 사용하여 다음 명령을 통해 진행률 및 궁극적으로 결과를 추적할 수 있습니다.

.show operations: 진행률을 추적합니다.
.show operation details: 완료 결과를 가져옵니다.

예를 들어 성공적으로 완료된 후 다음을 사용하여 결과를 검색할 수 있습니다.

.show operation f008dc1e-2710-47d8-8d34-0d562f5f8615 details

예제

이 예제에서 Kusto는 쿼리를 실행한 다음 쿼리에서 생성된 첫 번째 레코드 집합을 압축하기 전에 최대 1GB의 하나 이상의 압축된 CSV Blob으로 내보냅니다. 열 이름 레이블은 각 Blob의 첫 번째 행으로 추가됩니다.

.export
  async compressed
  to csv (
    h@"https://storage1.blob.core.windows.net/containerName;secretKey",
    h@"https://storage1.blob.core.windows.net/containerName2;secretKey"
  ) with (
    sizeLimit=1000000000,
    namePrefix="export",
    includeHeaders="all",
    encoding="UTF8NoBOM"
  )
  <| 
  Logs | where id == "1234"

내보내기 명령 중 오류

내보내기 명령은 실행 중에 일시적으로 실패할 수 있습니다. 연속 내보내 기에서 명령을 자동으로 다시 시도합니다. 일반 내보내기 명령(스토리지로 내보내기, 외부 테이블로 내보내기)은 재시도를 수행하지 않습니다.

내보내기 명령이 실패하면 스토리지에 이미 기록된 아티팩트가 삭제되지 않습니다. 이러한 아티팩트가 스토리지에 남아 있습니다. 명령이 실패하면 일부 아티팩트가 기록된 경우에도 내보내기 완료가 완료되지 않은 것으로 가정합니다.
명령의 완료와 성공적으로 완료될 때 내보낸 아티팩트 모두를 추적하는 가장 좋은 방법은 및 .show operation details 명령을 사용하는 .show operations 것입니다.

스토리지 오류

기본적으로 내보내기 명령은 스토리지에 많은 동시 쓰기가 있을 수 있도록 분산됩니다. 배포 수준은 내보내기 명령의 유형에 따라 달라집니다.

일반 .export 명령에 대한 기본 분포는 입니다 per_shard. 즉, 스토리지에 쓰기를 동시에 내보낼 데이터가 포함된 모든 익 스텐트입니다.
외부 테이블 명령으로 내보내기의 기본 분포는 입니다per_node. 즉, 동시성은 클러스터의 노드 수입니다.

익스텐트/노드 수가 많으면 스토리지 부하가 높아 스토리지 제한 또는 일시적인 스토리지 오류가 발생할 수 있습니다. 다음 제안은 우선 순위에 따라 이러한 오류를 극복할 수 있습니다.

내보내기 명령 또는 외부 테이블 정의 에 제공된 스토리지 계정 수를 늘입니다(로드는 계정 간에 균등하게 분산됨).
배포 힌트 per_node 를 로 설정하여 동시성을 줄입니다(명령 속성 참조).
클라이언트 요청 속성을query_fanout_nodes_percent 원하는 동시성(노드의 백분율)로 설정하여 내보내는 노드 수의 동시성을 줄입니다. 속성은 내보내기 쿼리의 일부로 설정할 수 있습니다. 예를 들어 다음 명령은 스토리지에 동시에 쓰는 노드 수를 클러스터 노드의 50%로 제한합니다.
```
.export async  to csv
    ( h@"https://storage1.blob.core.windows.net/containerName;secretKey" ) 
    with
    (
        distribution="per_node"
    ) 
    <| 
    set query_fanout_nodes_percent = 50;
    ExportQuery
```
클라이언트 요청 속성을query_fanout_threads_percent 원하는 동시성(스레드의 백분율)로 설정하여 분할된 데이터베이스별 내보내기를 사용할 때 각 노드에서 내보내는 스레드 수의 동시성을 줄입니다. 속성은 내보내기 쿼리의 일부로 설정할 수 있습니다. 예를 들어 다음 명령은 각 클러스터 노드에서 동시에 스토리지에 쓰는 스레드 수를 50%로 제한합니다.
```
.export async  to csv
    ( h@"https://storage1.blob.core.windows.net/containerName;secretKey" ) 
    with
    (
        distribution="per_shard"
    ) 
    <| 
    set query_fanout_threads_percent = 50;
    ExportQuery
```
분할된 외부 테이블로 내보내는 경우 속성을 설정 spread/concurrency 하면 동시성을 줄일 수 있습니다( 명령 속성의 세부 정보 참조).
위의 작업 중 어느 것도 작동하지 않으면 속성을 false로 설정하여 배포를 distributed 완전히 사용하지 않도록 설정할 수 있습니다. 그러나 명령 성능에 크게 영향을 줄 수 있으므로 그렇게 하지 않는 것이 좋습니다.

권한 부여 실패

내보내기 명령 중 인증 또는 권한 부여 실패는 스토리지 연결 문자열 제공된 자격 증명이 스토리지에 쓸 수 없는 경우에 발생할 수 있습니다. 내보내기 명령에 대해 또는 사용자가 위임한 SAS 토큰을 사용하는 impersonate 경우 스토리지 계정에 쓰려면 Storage Blob 데이터 기여자 역할이 필요합니다. 자세한 내용은 스토리지 연결 문자열을 참조하세요.

데이터 형식 매핑

Parquet 데이터 형식 매핑

내보내기에서 Kusto 데이터 형식은 다음 규칙을 사용하여 Parquet 데이터 형식에 매핑됩니다.

Kusto 데이터 형식	Parquet 데이터 형식	Parquet 주석	의견
`bool`	`BOOLEAN`
`datetime`	`INT64`	TIMESTAMP_MICROS
`dynamic`	`BYTE_ARRAY`	UTF-8	JSON 문자열로 직렬화됨
`guid`	`BYTE_ARRAY`	UTF-8
`int`	`INT32`
`long`	`INT64`
`real`	`DOUBLE`
`string`	`BYTE_ARRAY`	UTF-8
`timespan`	`INT64`		틱으로 저장(100나노초 단위) 수
`decimal`	`FIXED_LENGTH_BYTE_ARRAY`	DECIMAL