azureBlobStorage

Azure Blob Storage의 파일에 대해 SELECT/INSERT를 수행할 수 있는 테이블형 인터페이스를 제공합니다. s3 함수와 유사합니다.

​

azureBlobStorage 테이블 함수

Azure Blob Storage의 파일에 대해 SELECT/INSERT를 수행할 수 있는 테이블형 인터페이스를 제공합니다. 이 테이블 함수는 s3 함수와 유사합니다.

​

구문

연결 문자열

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

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

스토리지 계정 URL

account_name 및 account_key를 별도의 인수로 지정해야 합니다:

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

명명된 컬렉션

지원되는 키의 전체 목록은 아래의 이름이 지정된 컬렉션을 참조하십시오:

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

​

인수

Argument	Description
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, brotli/br, xz/LZMA, zstd/zst. 기본적으로는 파일 확장자를 기준으로 압축을 자동 감지합니다(auto로 설정한 경우와 동일).
structure	테이블 구조입니다. 형식: 'column1_name column1_type, column2_name column2_type, ...'.
partition_strategy	선택 사항입니다. 지원되는 값: WILDCARD 또는 HIVE. WILDCARD는 경로에 {_partition_id}가 있어야 하며, 이 값은 파티션 키로 대체됩니다. HIVE는 와일드카드를 허용하지 않으며 경로를 테이블 루트로 가정하고, 파일 이름으로 Snowflake ID를 사용하며 파일 포맷을 확장자로 하는 Hive 스타일의 파티션 디렉터리를 생성합니다. 기본값은 file_like_engine_default_partition_strategy 설정입니다(26.6보다 오래된 compatibility 설정에서는 WILDCARD, 그 외에는 HIVE).
partition_columns_in_data_file	선택 사항입니다. HIVE 파티션 전략에서만 사용됩니다. 데이터 파일에 파티션 컬럼이 기록되어 있다고 예상할지 여부를 ClickHouse에 지정합니다. 기본값은 false입니다.
extra_credentials	인증에 client_id 및 tenant_id를 사용합니다. extra_credentials가 제공되면 account_name 및 account_key보다 우선합니다.

​

이름이 지정된 컬렉션

인수는 이름이 지정된 컬렉션을 사용해 전달할 수도 있습니다. 이 경우 다음 키를 사용할 수 있습니다:

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

명명된 컬렉션의 키 이름은 위치 함수 인수 이름과 다릅니다. 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;

명명된 컬렉션의 값을 쿼리 시점에 재정의할 수도 있습니다:

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;

​

파티션을 사용한 쓰기

INSERT INTO TABLE FUNCTION azureBlobStorage(
    'DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey...==;EndPointSuffix=core.windows.net',
    'mycontainer',
    'test_{_partition_id}.csv',
    'CSV',
    'auto',
    '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 key)로 대체합니다. 26.6 이전의 compatibility 설정에서만 기본값으로 선택되며, 그 외에는 기본값이 HIVE입니다(file_like_engine_default_partition_strategy 설정 참조).

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 설정

이 설정은 읽는 시점에 ClickHouse가 Hive 스타일로 파티셔닝된 파일을 파싱하도록 돕는 힌트입니다. 쓰기에는 영향을 주지 않습니다. 읽기와 쓰기 동작을 일관되게 맞추려면 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;

​

Shared Access Signatures (SAS) 사용

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

azureBlobStorage 함수는 Shared Access Signatures(SAS)를 지원합니다.

Blob SAS 토큰에는 대상 blob, 권한, 유효 기간을 포함해 요청을 인증하는 데 필요한 모든 정보가 포함되어 있습니다. blob URL을 구성하려면 blob 서비스 endpoint에 SAS 토큰을 추가하십시오. 예를 들어 endpoint가 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.

​

관련 문서

• AzureBlobStorage 테이블 엔진