azureBlobStorage 테이블 함수

azureBlobStorage 테이블 함수 (azureBlobStorage)

Azure Blob Storage의 파일을 SELECT/INSERT하는 테이블형 인터페이스를 제공해요. s3 함수와 비슷한 테이블 함수입니다.

출처: 문서

본문

Azure Blob Storage의 파일을 select/insert하기 위한 테이블형 인터페이스를 제공합니다. 이 테이블 함수는 s3 함수와 비슷합니다.

구문

  • 연결 문자열(connection string)
  • 스토리지 계정 URL
  • named collection

자격 증명이 연결 문자열에 포함되어 있으므로 별도의 account_name/account_key는 필요 없습니다:

azureBlobStorage(connection_string, container_name, blobpath [, format, compression, partition_strategy, structure])

account_name과 account_key를 별도 인자로 요구합니다:

azureBlobStorage(storage_account_url, container_name, blobpath, account_name, account_key [, format, compression, partition_strategy, structure])

지원되는 키 전체 목록은 아래 Named Collections를 참고해요:

azureBlobStorage(named_collection[, option=value [,..]])

인자

인자 설명
connection_string 포함된 자격 증명(계정 이름 + 계정 키 또는 SAS 토큰)이 있는 연결 문자열. 이 형태를 쓰면 account_name과 account_key를 별도로 전달하지 않아야 합니다. 연결 문자열 구성 참고.
storage_account_url 스토리지 계정 엔드포인트 URL(예: https://myaccount.blob.core.windows.net/). 이 형태를 쓰면 반드시 account_name과 account_key도 전달해야 합니다.
container_name 컨테이너 이름.
blobpath 파일 경로. 읽기 전용 모드에서 다음 와일드카드를 지원합니다: *, **, ?, {abc,def} 및 {N..M}(N, M은 숫자, 'abc', 'def'는 문자열).
account_name 스토리지 계정 이름. SAS 없이 storage_account_url을 쓸 때 필수; connection_string을 쓸 때는 전달하면 안 됩니다.
account_key 스토리지 계정 키. SAS 없이 storage_account_url을 쓸 때 필수; connection_string을 쓸 때는 전달하면 안 됩니다.
format 파일의 포맷.
compression 지원 값: none, gzip/gz, deflate, brotli/br, xz/LZMA, zstd/zst, lz4, bz2, snappy. 기본적으로 파일 확장자로 압축을 자동 감지합니다(auto로 설정한 것과 동일). snappy의 경우 snappy_mode 설정(basic이 기본값)으로 와이어 포맷을 선택합니다.
structure 테이블 구조. 'column1_name column1_type, column2_name column2_type, ...' 형식.
partition_strategy 선택 사항. 지원 값: WILDCARD 또는 HIVE. WILDCARD는 경로에 {_partition_id}가 필요하며, 파티션 키로 치환됩니다. HIVE는 와일드카드를 허용하지 않고, 경로를 테이블 루트로 간주하며, Snowflake ID를 파일 이름으로, 파일 포맷을 확장자로 사용하는 Hive 스타일 파티션 디렉터리를 생성합니다. 명시적 전략이 없으면 {_partition_id}가 있는 경로는 WILDCARD를 사용합니다. 다른 glob이 있는 경로는 파티션 전략이 없고 PARTITION BY를 무시합니다. glob이 없는 경로는 file_like_engine_default_partition_strategy가 HIVE일 때 HIVE를, 그 외에는 파티션 전략을 사용하지 않습니다.
partition_columns_in_data_file 선택 사항. HIVE 파티션 전략에서만 사용됩니다. 파티션 컬럼이 데이터 파일에 기록될 것으로 예상할지 ClickHouse에 알립니다. 기본값 false.
extra_credentials 인증에 client_id와 tenant_id를 사용합니다. extra_credentials가 제공되면 account_name과 account_key보다 우선합니다.

Named Collections

인자를 named collections로 전달할 수도 있습니다. 이 경우 다음 키가 지원됩니다:

키 필수 설명
container 예 컨테이너 이름. 위치 인자 container_name에 대응합니다.
blob_path 예 파일 경로(선택적 와일드카드 포함). 위치 인자 blobpath에 대응합니다.
connection_string 아니오* 포함된 자격 증명이 있는 연결 문자열. *connection_string 또는 storage_account_url 중 하나는 반드시 제공해야 합니다.
storage_account_url 아니오* 스토리지 계정 엔드포인트 URL. *connection_string 또는 storage_account_url 중 하나는 반드시 제공해야 합니다.
account_name 아니오 storage_account_url을 쓸 때 필수
account_key 아니오 storage_account_url을 쓸 때 필수
format 아니오 파일 포맷.
compression 아니오 압축 타입.
structure 아니오 테이블 구조.
client_id 아니오 인증용 클라이언트 ID.
tenant_id 아니오 인증용 테넌트 ID.

named collection 키 이름은 위치 함수 인자 이름과 다릅니다: container(container_name 아님)와 blob_path(blobpath 아님)입니다.

예제:

CREATE NAMED COLLECTION azure_my_data AS
    storage_account_url = 'https://myaccount.blob.core.windows.net/',
    container = 'mycontainer',
    blob_path = 'data/*.parquet',
    account_name = 'myaccount',
    account_key = 'mykey...==',
    format = 'Parquet';

SELECT *
FROM azureBlobStorage(azure_my_data)
LIMIT 5;

쿼리 시점에 named collection 값을 덮어쓸 수도 있습니다:

SELECT *
FROM azureBlobStorage(azure_my_data, blob_path = 'other_data/*.csv', format = 'CSVWithNames')
LIMIT 5;

반환 값

지정된 파일에서 데이터를 읽거나 쓸 수 있는, 지정된 구조의 테이블.

예제

storage_account_url 형태로 읽기

SELECT *
FROM azureBlobStorage(
    'https://myaccount.blob.core.windows.net/',
    'mycontainer',
    'data/*.parquet',
    'myaccount',
    'mykey...==',
    'Parquet'
)
LIMIT 5;

connection_string 형태로 읽기

SELECT *
FROM azureBlobStorage(
    'DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey...==;EndPointSuffix=core.windows.net',
    'mycontainer',
    'data/*.csv',
    'CSVWithNames'
)
LIMIT 5;

파티션으로 쓰기

{_partition_id}가 있는 경로는 WILDCARD 파티션 전략을 의미합니다. 다른 glob이 있는 경로는 파티션 전략이 없고 PARTITION BY를 무시합니다. glob이 없는 경로는 file_like_engine_default_partition_strategy가 HIVE일 때 HIVE를, 그 외에는 파티션 전략을 사용하지 않습니다.

INSERT INTO TABLE FUNCTION azureBlobStorage(
    'DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey...==;EndPointSuffix=core.windows.net',
    'mycontainer',
    'test_{_partition_id}.csv',
    'CSV',
    'auto',
    'wildcard',
    'column1 UInt32, column2 UInt32, column3 UInt32'
) PARTITION BY column3
VALUES (1, 2, 3), (3, 2, 1), (78, 43, 3);

그런 다음 특정 파티션을 다시 읽습니다:

SELECT *
FROM azureBlobStorage(
    'DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey...==;EndPointSuffix=core.windows.net',
    'mycontainer',
    'test_1.csv',
    'CSV',
    'auto',
    'column1 UInt32, column2 UInt32, column3 UInt32'
);

┌─column1─┬─column2─┬─column3─┐
│       3 │       2 │       1 │
└─────────┴─────────┴─────────┘

가상 컬럼

  • _path — 파일 경로. 타입: LowCardinality(String).
  • _file — 파일 이름. 타입: LowCardinality(String).
  • _size — 파일 크기(바이트). 타입: Nullable(UInt64). 파일 크기를 알 수 없으면 NULL.
  • _time — 파일의 마지막 수정 시간. 타입: Nullable(DateTime). 시간을 알 수 없으면 NULL.

파티션 쓰기

파티션 전략

INSERT 쿼리에서만 지원됩니다.

WILDCARD: 파일 경로의 {_partition_id} 와일드카드를 실제 파티션 키로 치환합니다. 경로에 {_partition_id}가 있으면 기본으로 선택됩니다.

partition_strategy가 설정되지 않으면, 다른 glob이 있는 경로는 파티션 전략이 없고 PARTITION BY를 무시합니다. glob이 없는 경로는 file_like_engine_default_partition_strategy가 HIVE일 때 HIVE를, 그 외에는 파티션 전략을 사용하지 않습니다.

HIVE는 읽기와 쓰기에 hive 스타일 파티셔닝을 구현합니다. 다음 형식으로 파일을 생성합니다: <prefix>/<key1=val1/key2=val2...>/<snowflakeid>.<toLower(file_format)>.

HIVE 파티션 전략 예제

INSERT INTO TABLE FUNCTION azureBlobStorage(
    azure_conf2,
    storage_account_url = 'https://myaccount.blob.core.windows.net/',
    container = 'cont',
    blob_path = 'azure_table_root',
    format = 'CSVWithNames',
    compression = 'auto',
    structure = 'year UInt16, country String, id Int32',
    partition_strategy = 'hive'
) PARTITION BY (year, country)
VALUES (2020, 'Russia', 1), (2021, 'Brazil', 2);

SELECT _path, * FROM azureBlobStorage(
    azure_conf2,
    storage_account_url = 'https://myaccount.blob.core.windows.net/',
    container = 'cont',
    blob_path = 'azure_table_root/**.csvwithnames'
)

   ┌─_path───────────────────────────────────────────────────────────────────────────┬─id─┬─year─┬─country─┐
1. │ cont/azure_table_root/year=2021/country=Brazil/7351307847391293440.csvwithnames │  2 │ 2021 │ Brazil  │
2. │ cont/azure_table_root/year=2020/country=Russia/7351307847378710528.csvwithnames │  1 │ 2020 │ Russia  │
   └─────────────────────────────────────────────────────────────────────────────────┴────┴──────┴─────────┘

use_hive_partitioning 설정

읽기 시점에 hive 스타일 파티션 파일을 파싱하라는 ClickHouse의 힌트입니다. 쓰기에는 효과가 없습니다. 읽기와 쓰기 대칭을 원하면 partition_strategy 인자를 사용하세요.

use_hive_partitioning을 1로 설정하면 ClickHouse가 경로(/name=value/)에서 Hive 스타일 파티셔닝을 감지하고, 파티션 컬럼을 쿼리의 가상 컬럼으로 사용할 수 있게 합니다. 이 가상 컬럼들은 파티션 경로와 같은 이름을 갖습니다.

예제

Hive 스타일 파티셔닝으로 만든 가상 컬럼 사용

SELECT * FROM azureBlobStorage(config, storage_account_url='...', container='...', blob_path='http://data/path/date=*/country=*/code=*/*.parquet') WHERE date > '2020-01-01' AND country = 'Netherlands' AND code = 42;

SAS(공유 액세스 서명) 사용

SAS(Shared Access Signature)는 Azure Storage 컨테이너 또는 파일에 제한된 액세스를 부여하는 URI입니다. 스토리지 계정 키를 공유하지 않고 계정 리소스에 시간 제한 액세스를 제공할 때 사용합니다. 자세한 내용은 여기를 참고하세요.

azureBlobStorage 함수는 SAS(공유 액세스 서명)를 지원합니다.

Blob SAS 토큰은 대상 blob, 권한, 유효 기간을 포함해 요청 인증에 필요한 모든 정보를 담고 있습니다. Blob URL을 만들려면 blob 서비스 엔드포인트에 SAS 토큰을 붙이세요. 예를 들어 엔드포인트가 https://clickhousedocstest.blob.core.windows.net/이면 요청은 다음과 같아집니다:

SELECT count()
FROM azureBlobStorage('BlobEndpoint=https://clickhousedocstest.blob.core.windows.net/;SharedAccessSignature=sp=r&st=2025-01-29T14:58:11Z&se=2025-01-29T22:58:11Z&spr=https&sv=2022-11-02&sr=c&sig=Ac2U0xl4tm%2Fp7m55IilWl1yHwk%2FJG0Uk6rMVuOiD0eE%3D', 'exampledatasets', 'example.csv')

┌─count()─┐
│      10 │
└─────────┘

1 row in set. Elapsed: 0.425 sec.

또는 생성된 Blob SAS URL을 사용할 수도 있습니다:

SELECT count()
FROM azureBlobStorage('https://clickhousedocstest.blob.core.windows.net/?sp=r&st=2025-01-29T14:58:11Z&se=2025-01-29T22:58:11Z&spr=https&sv=2022-11-02&sr=c&sig=Ac2U0xl4tm%2Fp7m55IilWl1yHwk%2FJG0Uk6rMVuOiD0eE%3D', 'exampledatasets', 'example.csv')

┌─count()─┐
│      10 │
└─────────┘

1 row in set. Elapsed: 0.153 sec.

더 알아보기 (Learn more)