Azure Storage 외부 테이블 만들기 및 변경
적용 대상: ✅Microsoft Fabric✅Azure Data Explorer
이 문서의 명령을 사용하여 명령이 실행되는 데이터베이스에서 Azure Storage 외부 테이블을 만들거나 변경할 수 있습니다. Azure Storage 외부 테이블은 Azure Blob Storage, Azure Data Lake Store Gen1 또는 Azure Data Lake Store Gen2에 있는 데이터를 참조합니다.
참고 항목
테이블이 있는 .create 경우 오류와 함께 명령이 실패합니다. 기존 테이블을 사용 .create-or-alter 하거나 .alter 수정합니다.
사용 권한
.create 데이터베이스 사용자 이상의 권한이 필요하고 .alter 테이블 관리자 이상의 권한이 필요합니다.
관리 ID 인증을 사용하는 외부 테이블에는 .create-or-alter AllDatabasesAdmin 권한이 필요합니다.
구문
(.create.alter | | .create-or-alter) external table TableName( 스키마= kind storage) [partitionby (파티션) [pathformat= (PathFormat)]] dataformat = DataFormat (StorageConnectionString [, ...] ) [with (속성 [, ...])]
참고 항목
kind 는 storage 모든 Azure Storage 외부 데이터 저장소 유형에 대한 것입니다. blob 더 adl 이상 사용되지 않는 용어입니다.
구문 규칙에 대해 자세히 알아봅니다.
매개 변수
| 이름 | Type | 필수 | 설명 |
|---|---|---|---|
| TableName | string |
✔️ | 엔터티 이름 규칙을 준수하는 외부 테이블 이름 입니다. 외부 테이블은 동일한 데이터베이스의 일반 테이블과 같은 이름을 가질 수 없습니다. |
| 스키마 | string |
✔️ | 외부 데이터 스키마는 하나 이상의 열 이름과 데이터 형식의 쉼표로 구분된 목록으로, 각 항목은 ColumnName : ColumnType 형식을 따릅니다. 스키마를 알 수 없는 경우 infer_storage_schema 사용하여 외부 파일 내용을 기반으로 스키마를 유추합니다. |
| 파티션 | string |
외부 테이블이 분할되는 열의 쉼표로 구분된 목록입니다. 파티션 열은 데이터 파일 자체 또는 파일 경로의 일부로 존재할 수 있습니다. 이 값의 모양을 알아보려면 파티션 서식을 참조하세요. | |
| PathFormat | string |
파티션과 함께 사용할 외부 데이터 폴더 URI 경로 형식입니다. 경로 형식을 참조하세요. | |
| DataFormat | string |
✔️ | 수집 형식일 수 있는 데이터 형식입니다. 경로 매핑을 Parquet 사용하지 않는 한 외부 테이블의 형식을 사용하여 JSON 쿼리 및 내보내기 성능을 개선하는 것이 좋습니다. 내보내기 시나리오에 외부 테이블을 사용하는 경우 다음과 같은 형식으로 제한됩니다. JSON CSVTSVParquet |
| StorageConnectionString | string |
✔️ | 자격 증명을 포함하여 Azure Blob Storage Blob 컨테이너, Azure Data Lake Gen 2 파일 시스템 또는 Azure Data Lake Gen 1 컨테이너에 대한 하나 이상의 쉼표로 구분된 경로입니다. 외부 테이블 스토리지 유형은 제공된 연결 문자열 따라 결정됩니다. 스토리지 연결 문자열 참조하세요. |
| 속성 | string |
PropertyName PropertyValue= 형식의 키-값 속성 쌍입니다. 선택적 속성을 참조하세요. |
참고 항목
동일하지 않은 스키마가 있는 CSV 파일은 데이터가 이동되거나 누락된 것처럼 보일 수 있습니다. CSV 파일을 고유 스키마로 분리하여 스토리지 컨테이너를 분리하고 적절한 스키마를 사용하여 각 스토리지 컨테이너에 대한 외부 테이블을 정의하는 것이 좋습니다.
팁
많은 양의 데이터를 외부 테이블로 내보내는 동안 스토리지 제한이 발생하지 않도록 단일 스토리지 계정을 제공합니다. 내보내기에서는 제공된 모든 계정 간에 쓰기를 분산합니다.
인증 및 권한 부여
외부 테이블에 액세스하는 인증 방법은 만드는 동안 제공된 연결 문자열 기반으로 하며 테이블에 액세스하는 데 필요한 권한은 인증 방법에 따라 달라집니다.
다음 표에서는 Azure Storage 외부 테이블에 대해 지원되는 인증 방법과 테이블을 읽거나 쓰는 데 필요한 권한을 나열합니다.
| 인증 방법 | Azure Blob Storage/Data Lake Storage Gen2 | Data Lake Storage Gen1 |
|---|---|---|
| 가장 | 읽기 권한: Storage Blob 데이터 읽기 권한자 쓰기 권한: Storage Blob 데이터 기여자 |
읽기 권한: 읽기 권한자 쓰기 권한: 기여자 |
| 관리 ID | 읽기 권한: Storage Blob 데이터 읽기 권한자 쓰기 권한: Storage Blob 데이터 기여자 |
읽기 권한: 읽기 권한자 쓰기 권한: 기여자 |
| 공유 액세스 (SAS) 토큰 | 읽기 권한: 목록 + 읽기 쓰기 권한: 쓰기 |
이 인증 방법은 Gen1에서 지원되지 않습니다. |
| Microsoft Entra 액세스 토큰 | 추가 권한이 필요하지 않습니다. | 추가 권한이 필요하지 않습니다. |
| 스토리지 계정 액세스 키 | 추가 권한이 필요하지 않습니다. | 이 인증 방법은 Gen1에서 지원되지 않습니다. |
파티션 서식 지정
파티션 목록은 다음 표에 표시된 양식 중 하나를 사용하여 지정된 파티션 열의 조합입니다.
| 파티션 유형 | 구문 | 주의 |
|---|---|---|
| 가상 열 | PartitionName : (datetime | string) |
가상 열에 대해 자세히 읽어보세요. |
| 문자열 열 값 | PartitionName = : string ColumnName |
|
| 문자열 열 값 hash() | PartitionName hash(long = : ColumnName 번호, ) |
해시는 모듈로 번호입니다. |
| 잘린 날짜/시간 열(값) | PartitionName datetime : = (startofyearstartofweek | | | startofdaystartofmonth) ( ColumnName ) |
startofyear, startofmonth, startofweek 또는 startofday 함수에 대한 설명서를 참조하세요. |
잘린 날짜/시간 열 값 = bin ( ColumnName , TimeSpan ) |
bin 함수에 대해 자세히 알아보세요. |
경로 형식
PathFormat 매개 변수를 사용하면 파티션 외에도 외부 데이터 폴더 URI 경로의 형식을 지정할 수 있습니다. 파티션 요소와 텍스트 구분 기호의 시퀀스로 구성됩니다. 파티션 요소는 파티션 절에 by 선언된 파티션을 참조하고 텍스트 구분 기호는 따옴표로 묶인 텍스트입니다. 연속 파티션 요소는 텍스트 구분 기호를 사용하여 구분해야 합니다.
[ StringSeparator ] Partition [ StringSeparator ] [Partition [ StringSeparator ] ...]
원래 파일 경로 접두사를 생성하기 위해 파티션 요소는 문자열로 렌더링되고 해당 텍스트 구분 기호로 구분됩니다. 매크로(datetime_pattern(DateTimeFormat, PartitionName))를 사용하여 datetime_pattern datetime 파티션 값을 렌더링하는 데 사용되는 형식을 지정할 수 있습니다. 매크로는 .NET 형식 사양을 준수하며 서식 지정자를 중괄호로 묶을 수 있습니다. 예를 들어 다음 두 형식은 동일합니다.
- 'year='yyyy'/month='MM
- year={yyyy}/month={MM}
기본적으로 datetime 값은 다음 형식을 사용하여 렌더링됩니다.
| 파티션 함수 | 기본 형식 |
|---|---|
startofyear |
yyyy |
startofmonth |
yyyy/MM |
startofweek |
yyyy/MM/dd |
startofday |
yyyy/MM/dd |
bin(열, 1d) |
yyyy/MM/dd |
bin(열, 1h) |
yyyy/MM/dd/HH |
bin(열, 1m) |
yyyy/MM/dd/HH/mm |
팁
파티션 및 PathFormat 정의의 정확성을 확인하려면 속성을 sampleUris 사용하거나 filesPreview 외부 테이블을 만들 때 사용합니다.
가상 열
Spark에서 데이터를 내보낼 때 데이터 프레임 작성기 partitionBy 메서드에 제공되는 파티션 열은 데이터 파일에 기록되지 않습니다.
이 프로세스는 데이터가 폴더 이름(예 column1=<value>/column2=<value>/: )에 이미 있으므로 데이터 중복을 방지하고 Spark는 읽을 때 데이터를 인식할 수 있습니다.
외부 테이블은 이 데이터를 다음과 같은 형식 virtual colums으로 읽을 수 있습니다. 가상 열은 형식 string 또는 datetime형식일 수 있으며 다음 구문을 사용하여 지정됩니다.
.create external table ExternalTable (EventName:string, Revenue:double)
kind=storage
partition by (CustomerName:string, Date:datetime)
pathformat=("customer=" CustomerName "/date=" datetime_pattern("yyyyMMdd", Date))
dataformat=parquet
(
h@'https://storageaccount.blob.core.windows.net/container1;secretKey'
)
쿼리의 가상 열을 필터링하려면 쿼리 조건자에서 파티션 이름을 지정합니다.
external_table("ExternalTable")
| where Date between (datetime(2020-01-01) .. datetime(2020-02-01))
| where CustomerName in ("John.Doe", "Ivan.Ivanov")
선택적 속성
| 속성 | Type | 설명 |
|---|---|---|
folder |
string |
테이블의 폴더 |
docString |
string |
테이블을 문서화하는 문자열 |
compressed |
bool |
설정된 경우 파일이 파일로 .gz 압축되는지 여부를 나타냅니다(내보내기 시나리오에서만 사용됨). |
includeHeaders |
string |
구분된 텍스트 형식(CSV, TSV, ...)의 경우 파일에 헤더가 포함되어 있는지 여부를 나타냅니다. 가능한 값은 다음과 All 같습니다(모든 파일에 헤더 포함), FirstFile (폴더의 첫 번째 파일에 헤더 포함), None (헤더가 포함된 파일 없음) |
namePrefix |
string |
설정된 경우 파일의 접두사를 나타냅니다. 쓰기 작업 시 모든 파일은 이 접두사를 사용하여 작성됩니다. 읽기 작업에서는 이 접두사를 가진 파일만 읽습니다. |
fileExtension |
string |
설정된 경우 파일의 파일 확장자를 나타냅니다. 쓰기 시 파일 이름은 이 접미사로 끝납니다. 읽기 시 이 파일 확장자를 가진 파일만 읽습니다. |
encoding |
string |
텍스트가 인코딩되는 UTF8NoBOM 방법(기본값) 또는 UTF8BOM. |
sampleUris |
bool |
설정되면 명령 결과는 외부 테이블 정의에서 예상한 대로 시뮬레이션된 외부 데이터 파일 URI의 몇 가지 예를 제공합니다. 이 옵션은 파티션 및 PathFormat 매개 변수가 올바르게 정의되었는지 여부를 확인하는 데 도움이 됩니다. |
filesPreview |
bool |
설정되면 명령 결과 테이블 중 하나에 .show 외부 테이블 아티팩트 명령의 미리 보기가 포함됩니다 . 마찬가지로 sampleUri이 옵션은 외부 테이블 정의의 파티션 및 PathFormat 매개 변수의 유효성을 검사하는 데 도움이 됩니다. |
validateNotEmpty |
bool |
설정된 경우 연결 문자열 콘텐츠가 있는지 유효성이 검사됩니다. 지정된 URI 위치가 없거나 액세스 권한이 부족한 경우 명령이 실패합니다. |
dryRun |
bool |
설정하면 외부 테이블 정의가 유지되지 않습니다. 이 옵션은 특히 또는 sampleUris 매개 변수와 함께 외부 테이블 정의의 유효성을 검사하는 filesPreview 데 유용합니다. |
참고 항목
외부 테이블은 쿼리 및 내보내기 중에만 생성 중에 액세스되지 않습니다. validateNotEmpty 만드는 동안 선택적 속성을 사용하여 테이블 정의가 유효하고 스토리지에 액세스할 수 있는지 확인합니다.
팁
쿼리 중에 데이터 파일 필터링에서 수행하는 역할 namePrefix 및 fileExtension 속성에 대한 자세한 내용은 파일 필터링 논리 섹션을 참조하세요.
파일 필터링 논리
외부 테이블을 쿼리할 때 관련이 없는 외부 스토리지 파일을 필터링하여 성능이 향상됩니다. 파일을 반복하고 파일을 처리할지 여부를 결정하는 프로세스는 다음과 같습니다.
파일이 있는 위치를 나타내는 URI 패턴을 빌드합니다. 처음에 URI 패턴은 외부 테이블 정의의 일부로 제공된 연결 문자열 같습니다. 정의된 파티션이 있는 경우 PathFormat을 사용하여 렌더링된 다음 URI 패턴에 추가됩니다.
생성된 URI 패턴 아래에 있는 모든 파일의 경우 다음을 확인합니다.
- 파티션 값은 쿼리에 사용되는 조건자와 일치합니다.
- Blob 이름은 이러한 속성이 정의된 경우 로 시작
NamePrefix합니다. - Blob 이름은 이러한 속성이 정의된 경우 로 끝납니다
FileExtension.
모든 조건이 충족되면 파일이 페치되고 처리됩니다.
참고 항목
초기 URI 패턴은 쿼리 조건자 값을 사용하여 빌드됩니다. 이는 제한된 문자열 값 집합과 닫힌 시간 범위에 가장 적합합니다.
예제
분할되지 않은 외부 테이블
다음 분할되지 않은 외부 테이블에서는 파일이 정의된 컨테이너 바로 아래에 배치되어야 합니다.
.create external table ExternalTable (x:long, s:string)
kind=storage
dataformat=csv
(
h@'https://storageaccount.blob.core.windows.net/container1;secretKey'
)
날짜별로 분할됨
날짜별로 분할된 다음 외부 테이블에서 파일은 기본 datetime 형식 yyyy/MM/dd의 디렉터리 아래에 배치되어야 합니다.
.create external table ExternalTable (Timestamp:datetime, x:long, s:string)
kind=storage
partition by (Date:datetime = bin(Timestamp, 1d))
dataformat=csv
(
h@'abfss://filesystem@storageaccount.dfs.core.windows.net/path;secretKey'
)
월별로 분할
월별로 분할된 다음 외부 테이블에서 디렉터리 형식은 다음과 같습니다 year=yyyy/month=MM.
.create external table ExternalTable (Timestamp:datetime, x:long, s:string)
kind=storage
partition by (Month:datetime = startofmonth(Timestamp))
pathformat=(datetime_pattern("'year='yyyy'/month='MM", Month))
dataformat=csv
(
h@'https://storageaccount.blob.core.windows.net/container1;secretKey'
)
이름 및 날짜별로 분할
다음 외부 테이블에서 데이터는 먼저 고객 이름으로 분할된 다음 날짜별로 분할됩니다. 즉, 예상 디렉터리 구조가 다음과 같습니다 customer_name=Softworks/2019/02/01.
.create external table ExternalTable (Timestamp:datetime, CustomerName:string)
kind=storage
partition by (CustomerNamePart:string = CustomerName, Date:datetime = startofday(Timestamp))
pathformat=("customer_name=" CustomerNamePart "/" Date)
dataformat=csv
(
h@'https://storageaccount.blob.core.windows.net/container1;secretKey'
)
해시 및 날짜별로 분할
다음 외부 테이블은 먼저 고객 이름 해시(modulo 10)로 분할된 다음 날짜별로 분할됩니다. 예를 들어 customer_id=5/dt=20190201필요한 디렉터리 구조는 데이터 파일 이름이 확장명으로 끝납니다 .txt .
.create external table ExternalTable (Timestamp:datetime, CustomerName:string)
kind=storage
partition by (CustomerId:long = hash(CustomerName, 10), Date:datetime = startofday(Timestamp))
pathformat=("customer_id=" CustomerId "/dt=" datetime_pattern("yyyyMMdd", Date))
dataformat=csv
(
h@'https://storageaccount.blob.core.windows.net/container1;secretKey'
)
with (fileExtension = ".txt")
쿼리의 파티션 열별로 필터링
쿼리의 파티션 열을 필터링하려면 쿼리 조건자에서 원래 열 이름을 지정합니다.
external_table("ExternalTable")
| where Timestamp between (datetime(2020-01-01) .. datetime(2020-02-01))
| where CustomerName in ("John.Doe", "Ivan.Ivanov")
샘플 출력
| TableName | TableType | 폴더 | DocString | 속성 | ConnectionStrings | 파티션 | PathFormat |
|---|---|---|---|---|---|---|---|
| ExternalTable | Blob | ExternalTables | 문서 | {"Format":"Csv","Compressed":false,"CompressionType":null,"FileExtension":null,"IncludeHeaders":"None","Encoding":null,"NamePrefix":null} | ["https://storageaccount.blob.core.windows.net/container1;*******"] | [{"Mod":10,"Name":"CustomerId","ColumnName":"CustomerName","Ordinal":0},{"Function":"StartOfDay","Name":"Date","ColumnName":"Timestamp","Ordinal":1}] | "customer_id=" CustomerId "/dt=" datetime_pattern("yyyyMMdd",Date) |
관련 콘텐츠
연속 데이터를 외부 테이블로 내보냅니다.