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

> 提供类似表的接口，用于在 Azure Blob 存储中查询/插入文件。与 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 存储](https://azure.microsoft.com/en-us/products/storage/blobs) 中查询/插入文件。与 [s3 函数](/zh/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>

| 参数                               | 说明                                                                                                                                                                                                                                                                                                                                                            |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `connection_string`              | 包含内嵌凭据 (账户名 + 账户密钥或 SAS token) 的连接字符串。使用这种形式时，**不应**再单独传递 `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`                         | 文件的[格式](/zh/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` 不允许使用通配符，假定该路径是表根路径，并生成 Hive 风格的分区目录，以 Snowflake ID 作为文件名、以文件格式作为扩展名。默认为 `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>

参数也可以通过[命名集合](/zh/concepts/features/configuration/server-config/named-collections)传递。此时支持以下键：

| 键                     | 必需  | 描述                                                                    |
| --------------------- | --- | --------------------------------------------------------------------- |
| `container`           | 是   | 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。                                                         |

<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;
```

你也可以在查询时覆盖 named collection 中的值：

```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}` 通配符替换为实际分区键。

`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 会检测路径中的 Hive 风格分区 (`/name=value/`) ，并允许在查询中将分区列用作虚拟列。这些虚拟列的名称将与分区路径中的名称相同。

**示例**

使用通过 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">
  ## 使用共享访问签名 (SAS)
</div>

共享访问签名 (SAS) 是一种 URI，可授予对 Azure Storage 容器或文件的受限访问权限。使用它可以在不共享存储账户密钥的情况下，为存储账户资源提供限时访问。更多详情请参见[此处](https://learn.microsoft.com/en-us/rest/api/storageservices/delegate-access-with-shared-access-signature)。

`azureBlobStorage` 函数支持共享访问签名 (SAS)。

[Blob SAS token](https://learn.microsoft.com/en-us/azure/ai-services/translator/document-translation/how-to-guides/create-sas-tokens?tabs=Containers) 包含对请求进行身份验证所需的全部信息，包括目标 blob、权限和有效期。要构造 blob URL，请将 SAS token 追加到 blob 服务端点之后。例如，如果端点是 `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 表引擎](/zh/reference/engines/table-engines/integrations/azureBlobStorage)