> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

# azureBlobStorage 테이블 함수

export const CloudNotSupportedBadge = () => {
  return <div className="cloudNotSupportedBadge">
            <div className="cloudNotSupportedIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.5" d="M6.33366 12.6666L12.3739 12.6667C13.6593 12.6667 14.7073 11.6187 14.7073 10.3334C14.7073 9.04804 13.6593 8.00003 12.3739 8.00003C12.3739 8.00003 12.3337 7.66659 12.0003 7.33325M10.667 5.33322C8.00033 2.33325 4.45395 4.78537 4.14195 6.68203C2.55728 6.7627 1.29395 8.06203 1.29395 9.6667C1.29395 11.3234 2.66699 12.6666 4.00033 12.6666" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.5" d="M2.66699 14L12.0003 4.66663" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>

        </div>
            Not supported in ClickHouse Cloud
        </div>;
};

export const ExperimentalBadge = () => {
  return <div className="experimentalBadge">
            <div className="experimentalIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.25" d="M5.5 2H10.5" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M9.50015 2V6.19625L13.4283 12.7425C13.4738 12.8183 13.4985 12.9049 13.4996 12.9934C13.5008 13.0818 13.4785 13.169 13.435 13.246C13.3914 13.323 13.3283 13.3871 13.2519 13.4317C13.1755 13.4764 13.0886 13.4999 13.0002 13.5H3.00015C2.91164 13.5 2.8247 13.4766 2.74822 13.432C2.67174 13.3874 2.60847 13.3233 2.56487 13.2463C2.52126 13.1693 2.49889 13.082 2.50004 12.9935C2.50119 12.905 2.52582 12.8184 2.5714 12.7425L6.50015 6.19625V2" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M4.47656 9.56754C5.30344 9.41254 6.47656 9.47942 7.99969 10.25C10.0153 11.2707 11.4216 11.0569 12.2184 10.7282" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>
        </div>
            Experimental feature. <u><a href="/docs/beta-and-experimental-features#experimental-features">Learn more.</a></u>
        </div>;
};

[Azure Blob Storage](https://azure.microsoft.com/en-us/products/storage/blobs)의 파일에 대해 SELECT/INSERT를 수행할 수 있는 테이블형 인터페이스를 제공합니다. 이 테이블 함수는 [s3 함수](/ko/reference/functions/table-functions/s3)와 유사합니다.

<div id="syntax">
  ## 구문
</div>

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

    ```sql theme={null}
    azureBlobStorage(connection_string, container_name, blobpath [, format, compression, structure])
    ```
  </Tab>

  <Tab title="스토리지 계정 URL">
    `account_name` 및 `account_key`를 별도의 인수로 지정해야 합니다:

    ```sql theme={null}
    azureBlobStorage(storage_account_url, container_name, blobpath, account_name, account_key [, format, compression, structure])
    ```
  </Tab>

  <Tab title="명명된 컬렉션">
    지원되는 키의 전체 목록은 아래의 [이름이 지정된 컬렉션](#named-collections)을 참조하십시오:

    ```sql theme={null}
    azureBlobStorage(named_collection[, option=value [,..]])
    ```
  </Tab>
</Tabs>

<div id="arguments">
  ## 인수
</div>

| Argument                         | Description                                                                                                                                                                                                                                                                                                                                                                                  |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `connection_string`              | 자격 증명이 포함된 연결 문자열입니다(계정 이름 + 계정 키 또는 SAS 토큰). 이 형식을 사용할 때는 `account_name` 및 `account_key`를 별도로 전달해서는 **안 됩니다**. [연결 문자열 구성](https://learn.microsoft.com/en-us/azure/storage/common/storage-configure-connection-string?toc=%2Fazure%2Fstorage%2Fblobs%2Ftoc.json\&bc=%2Fazure%2Fstorage%2Fblobs%2Fbreadcrumb%2Ftoc.json#configure-a-connection-string-for-an-azure-storage-account)을 참고하십시오. |
| `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`                         | 파일의 [포맷](/ko/reference/formats)입니다.                                                                                                                                                                                                                                                                                                                                                          |
| `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 스타일의 파티션 디렉터리를 생성합니다. 기본값은 `WILDCARD`입니다.                                                                                                                                                     |
| `partition_columns_in_data_file` | 선택 사항입니다. `HIVE` 파티션 전략에서만 사용됩니다. 데이터 파일에 파티션 컬럼이 기록되어 있다고 예상할지 여부를 ClickHouse에 지정합니다. 기본값은 `false`입니다.                                                                                                                                                                                                                                                                                      |
| `extra_credentials`              | 인증에 `client_id` 및 `tenant_id`를 사용합니다. `extra_credentials`가 제공되면 `account_name` 및 `account_key`보다 우선합니다.                                                                                                                                                                                                                                                                                      |

<div id="named-collections">
  ## 이름이 지정된 컬렉션
</div>

인수는 [이름이 지정된 컬렉션](/ko/concepts/features/configuration/server-config/named-collections)을 사용해 전달할 수도 있습니다. 이 경우 다음 키를 사용할 수 있습니다:

| 키                     | 필수    | 설명                                                                                      |
| --------------------- | ----- | --------------------------------------------------------------------------------------- |
| `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입니다.                                                          |

<Note>
  명명된 컬렉션의 키 이름은 위치 함수 인수 이름과 다릅니다. `container`는 `container_name`이 아니며, `blob_path`는 `blobpath`가 아닙니다.
</Note>

**예시:**

```sql theme={null}
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;
```

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

```sql theme={null}
SELECT *
FROM azureBlobStorage(azure_my_data, blob_path = 'other_data/*.csv', format = 'CSVWithNames')
LIMIT 5;
```

<div id="returned_value">
  ## 반환 값
</div>

지정된 파일에서 데이터를 읽거나 쓰는 데 사용되는, 지정된 구조의 테이블입니다.

<div id="examples">
  ## 예시
</div>

<div id="reading-with-storage-account-url">
  ### `storage_account_url` 방식으로 읽기
</div>

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

<div id="reading-with-connection-string">
  ### `connection_string` 형식으로 읽기
</div>

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

<div id="writing-with-partitions">
  ### 파티션을 사용한 쓰기
</div>

```sql theme={null}
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);
```

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

```sql theme={null}
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'
);
```

```response theme={null}
┌─column1─┬─column2─┬─column3─┐
│       3 │       2 │       1 │
└─────────┴─────────┴─────────┘
```

<div id="virtual-columns">
  ## 가상 컬럼
</div>

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

<div id="partitioned-write">
  ## 파티션별 쓰기
</div>

<div id="partition-strategy">
  ### 파티션 전략
</div>

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

`WILDCARD` (기본값): 파일 경로의 `{_partition_id}` 와일드카드를 실제 파티션 키(partition key)로 대체합니다.

`HIVE`는 읽기와 쓰기에서 Hive 스타일 파티셔닝을 사용합니다. 다음 포맷으로 파일을 생성합니다: `<prefix>/<key1=val1/key2=val2...>/<snowflakeid>.<toLower(file_format)>`.

**`HIVE` 파티션 전략 예시**

```sql theme={null}
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);
```

```result theme={null}
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  │
   └─────────────────────────────────────────────────────────────────────────────────┴────┴──────┴─────────┘
```

<div id="hive-style-partitioning">
  ## use\_hive\_partitioning 설정
</div>

이 설정은 읽는 시점에 ClickHouse가 Hive 스타일로 파티셔닝된 파일을 파싱하도록 돕는 힌트입니다. 쓰기에는 영향을 주지 않습니다. 읽기와 쓰기 동작을 일관되게 맞추려면 `partition_strategy` 인수를 사용하십시오.

`use_hive_partitioning` 설정을 1로 지정하면 ClickHouse가 경로(`/name=value/`)에서 Hive 스타일 파티셔닝을 감지하고, 쿼리에서 파티션 컬럼을 가상 컬럼으로 사용할 수 있습니다. 이러한 가상 컬럼은 파티셔닝된 경로의 이름과 동일한 이름을 가집니다.

**예시**

Hive 스타일 파티셔닝으로 생성된 가상 컬럼 사용

```sql theme={null}
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;
```

<div id="using-shared-access-signatures-sas-sas-tokens">
  ## Shared Access Signatures (SAS) 사용
</div>

Shared Access Signature(SAS)는 Azure Storage 컨테이너 또는 파일에 대한 제한된 액세스를 부여하는 URI입니다. 스토리지 계정 키를 공유하지 않고도 스토리지 계정 리소스에 일정 기간 동안만 액세스할 수 있도록 할 때 사용합니다. 자세한 내용은 [여기](https://learn.microsoft.com/en-us/rest/api/storageservices/delegate-access-with-shared-access-signature)를 참조하십시오.

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

[Blob SAS 토큰](https://learn.microsoft.com/en-us/azure/ai-services/translator/document-translation/how-to-guides/create-sas-tokens?tabs=Containers)에는 대상 blob, 권한, 유효 기간을 포함해 요청을 인증하는 데 필요한 모든 정보가 포함되어 있습니다. blob URL을 구성하려면 blob 서비스 endpoint에 SAS 토큰을 추가하십시오. 예를 들어 endpoint가 `https://clickhousedocstest.blob.core.windows.net/`이면 요청은 다음과 같습니다.

```sql theme={null}
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](https://learn.microsoft.com/en-us/azure/ai-services/translator/document-translation/how-to-guides/create-sas-tokens?tabs=Containers)을 사용할 수 있습니다:

```sql theme={null}
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.
```

<div id="related">
  ## 관련 문서
</div>

* [AzureBlobStorage 테이블 엔진](/ko/reference/engines/table-engines/integrations/azureBlobStorage)