> ## 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.

> 该引擎支持通过 ClickHouse 管理 HDFS 上的数据，从而与 Apache Hadoop 生态系统集成。该引擎类似于 File 表引擎和 URL 引擎，但提供了 Hadoop 特有的功能。

# HDFS 表引擎

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

此引擎支持通过 ClickHouse 管理 [HDFS](https://hadoop.apache.org/docs/current/hadoop-project-dist/hadoop-hdfs/HdfsDesign.html) 上的数据，从而与 [Apache Hadoop](https://en.wikipedia.org/wiki/Apache_Hadoop) 生态系统集成。该引擎与 [File 表引擎](/zh/reference/engines/table-engines/special/file) 和 [URL](/zh/reference/engines/table-engines/special/url) 引擎类似，但提供了 Hadoop 特有的功能。

此功能不受 ClickHouse engineers 支持，且已知质量较差。如果遇到任何问题，请自行修复并提交拉取请求。

<div id="usage">
  ## 用法
</div>

```sql theme={null}
ENGINE = HDFS(URI, format)
```

**引擎参数**

* `URI` - HDFS 中文件的完整 URI。`URI` 的路径部分可以包含通配符。在这种情况下，该表将为只读。
* `格式` - 指定一种可用的文件格式。要执行
  `SELECT` 查询，该格式必须支持输入；而要执行
  `INSERT` 查询，则必须支持输出。可用格式列在
  [格式](/zh/reference/formats#formats-overview) 部分。
* \[PARTITION BY expr]

<div id="partition-by">
  ### PARTITION BY
</div>

`PARTITION BY` — 可选。在大多数情况下，不需要分区键；即使需要，通常也不必将分区划分得比按月更细。分区不会加快查询速度 (这一点与 ORDER BY 表达式不同) 。切勿使用粒度过细的分区方式。不要按客户端标识符或名称对数据进行分区 (而应将客户端标识符或名称设为 ORDER BY 表达式中的第一列) 。

如果按月分区，请使用 `toYYYYMM(date_column)` 表达式，其中 `date_column` 是一个 [Date](/zh/reference/data-types/date) 类型的日期列。这里的分区名称采用 `"YYYYMM"` 格式。

**示例：**

**1.** 设置 `hdfs_engine_table` 表：

```sql theme={null}
CREATE TABLE hdfs_engine_table (name String, value UInt32) ENGINE=HDFS('hdfs://hdfs1:9000/other_storage', 'TSV')
```

**2.** 填写文件内容：

```sql theme={null}
INSERT INTO hdfs_engine_table VALUES ('one', 1), ('two', 2), ('three', 3)
```

**3.** 查询数据：

```sql theme={null}
SELECT * FROM hdfs_engine_table LIMIT 2
```

```text theme={null}
┌─name─┬─value─┐
│ one  │     1 │
│ two  │     2 │
└──────┴───────┘
```

<div id="implementation-details">
  ## 实现细节
</div>

* 读取和写入可以并行进行。
* 不支持：
  * `ALTER` 和 `SELECT...SAMPLE` 操作。
  * 索引。
  * 支持[零拷贝](/zh/concepts/features/configuration/server-config/storing-data#zero-copy)复制，但不建议使用。

<Info>
  **零拷贝复制尚未做好用于生产环境的准备**

  在 ClickHouse 22.8 及更高版本中，零拷贝复制默认禁用。此功能不建议在生产环境中使用。
</Info>

**路径中的通配符**

路径中的多个组成部分都可以使用通配符。待处理的文件必须存在，并且要匹配完整的路径模式。文件列表是在执行 `SELECT` 时确定的 (而不是在 `CREATE` 时) 。

* `*` — 匹配任意数量的任意字符，但不包括 `/`，也包括空字符串。
* `?` — 匹配任意单个字符。
* `{some_string,another_string,yet_another_one}` — 匹配字符串 `'some_string'`、`'another_string'`、`'yet_another_one'` 中的任意一个。
* `{N..M}` — 匹配从 N 到 M 范围内的任意数字，包括两个端点。

带有 `{}` 的写法与 [remote](/zh/reference/functions/table-functions/remote) table function 类似。

**示例**

1. 假设我们在 HDFS 上有多个 TSV 格式的文件，其 URI 如下：

   * 'hdfs\://hdfs1:9000/some\_dir/some\_file\_1'
   * 'hdfs\://hdfs1:9000/some\_dir/some\_file\_2'
   * 'hdfs\://hdfs1:9000/some\_dir/some\_file\_3'
   * 'hdfs\://hdfs1:9000/another\_dir/some\_file\_1'
   * 'hdfs\://hdfs1:9000/another\_dir/some\_file\_2'
   * 'hdfs\://hdfs1:9000/another\_dir/some\_file\_3'

2. 可以通过多种方式创建一个包含这六个文件的表：

```sql theme={null}
CREATE TABLE table_with_range (name String, value UInt32) ENGINE = HDFS('hdfs://hdfs1:9000/{some,another}_dir/some_file_{1..3}', 'TSV')
```

另一种方法：

```sql theme={null}
CREATE TABLE table_with_question_mark (name String, value UInt32) ENGINE = HDFS('hdfs://hdfs1:9000/{some,another}_dir/some_file_?', 'TSV')
```

该表包含两个目录中的所有文件 (所有文件都应符合查询中描述的 格式 和 schema) ：

```sql theme={null}
CREATE TABLE table_with_asterisk (name String, value UInt32) ENGINE = HDFS('hdfs://hdfs1:9000/{some,another}_dir/*', 'TSV')
```

<Note>
  如果文件列表包含带前导零的数字范围，请对每一位数字分别使用花括号写法，或使用 `?`。
</Note>

**示例**

创建一个表，其中包含名为 `file000`、`file001`、...、`file999` 的文件：

```sql theme={null}
CREATE TABLE big_table (name String, value UInt32) ENGINE = HDFS('hdfs://hdfs1:9000/big_dir/file{0..9}{0..9}{0..9}', 'CSV')
```

<div id="configuration">
  ## 配置
</div>

与 GraphiteMergeTree 类似，HDFS 引擎支持通过 ClickHouse 配置文件进行扩展配置。你可以使用两个配置项：全局级 (`hdfs`) 和用户级 (`hdfs_*`) 。系统会先应用全局配置，然后再应用用户级配置 (如果存在) 。

```xml theme={null}
<!-- HDFS 引擎类型的全局配置选项 -->
<hdfs>
  <hadoop_kerberos_keytab>/tmp/keytab/clickhouse.keytab</hadoop_kerberos_keytab>
  <hadoop_kerberos_principal>clickuser@TEST.CLICKHOUSE.TECH</hadoop_kerberos_principal>
  <hadoop_security_authentication>kerberos</hadoop_security_authentication>
</hdfs>

<!-- 针对用户 "root" 的特定配置 -->
<hdfs_root>
  <hadoop_kerberos_principal>root@TEST.CLICKHOUSE.TECH</hadoop_kerberos_principal>
</hdfs_root>
```

<div id="configuration-options">
  ### 配置选项
</div>

<div id="supported-by-libhdfs3">
  #### libhdfs3 支持的配置项
</div>

| **参数**                                                | **默认值**                  |
| ----------------------------------------------------- | ------------------------ |
| rpc\_client\_connect\_tcpnodelay                      | true                     |
| dfs\_client\_read\_shortcircuit                       | true                     |
| output\_replace-datanode-on-failure                   | true                     |
| input\_notretry-another-node                          | false                    |
| input\_localread\_mappedfile                          | true                     |
| dfs\_client\_use\_legacy\_blockreader\_local          | false                    |
| rpc\_client\_ping\_interval                           | 10  \* 1000              |
| rpc\_client\_connect\_timeout                         | 600 \* 1000              |
| rpc\_client\_read\_timeout                            | 3600 \* 1000             |
| rpc\_client\_write\_timeout                           | 3600 \* 1000             |
| rpc\_client\_socket\_linger\_timeout                  | -1                       |
| rpc\_client\_connect\_retry                           | 10                       |
| rpc\_client\_timeout                                  | 3600 \* 1000             |
| dfs\_default\_replica                                 | 3                        |
| input\_connect\_timeout                               | 600 \* 1000              |
| input\_read\_timeout                                  | 3600 \* 1000             |
| input\_write\_timeout                                 | 3600 \* 1000             |
| input\_localread\_default\_buffersize                 | 1 \* 1024 \* 1024        |
| dfs\_prefetchsize                                     | 10                       |
| input\_read\_getblockinfo\_retry                      | 3                        |
| input\_localread\_blockinfo\_cachesize                | 1000                     |
| input\_read\_max\_retry                               | 60                       |
| output\_default\_chunksize                            | 512                      |
| output\_default\_packetsize                           | 64 \* 1024               |
| output\_default\_write\_retry                         | 10                       |
| output\_connect\_timeout                              | 600 \* 1000              |
| output\_read\_timeout                                 | 3600 \* 1000             |
| output\_write\_timeout                                | 3600 \* 1000             |
| output\_close\_timeout                                | 3600 \* 1000             |
| output\_packetpool\_size                              | 1024                     |
| output\_heartbeat\_interval                           | 10 \* 1000               |
| dfs\_client\_failover\_max\_attempts                  | 15                       |
| dfs\_client\_read\_shortcircuit\_streams\_cache\_size | 256                      |
| dfs\_client\_socketcache\_expiryMsec                  | 3000                     |
| dfs\_client\_socketcache\_capacity                    | 16                       |
| dfs\_default\_blocksize                               | 64 \* 1024 \* 1024       |
| dfs\_default\_uri                                     | "hdfs\://localhost:9000" |
| hadoop\_security\_authentication                      | "simple"                 |
| hadoop\_security\_kerberos\_ticket\_cache\_path       | ""                       |
| dfs\_client\_log\_severity                            | "INFO"                   |
| dfs\_domain\_socket\_path                             | ""                       |

[HDFS 配置参考](https://hawq.apache.org/docs/userguide/2.3.0.0-incubating/reference/HDFSConfigurationParameterReference.html) 或许可以帮助解释其中的一些参数。

<div id="clickhouse-extras">
  #### ClickHouse 额外配置
</div>

| **参数**                      | **默认值** |
| --------------------------- | ------- |
| hadoop\_kerberos\_keytab    | ""      |
| hadoop\_kerberos\_principal | ""      |
| libhdfs3\_conf              | ""      |

<div id="limitations">
  ### 限制
</div>

* `hadoop_security_kerberos_ticket_cache_path` 和 `libhdfs3_conf` 只能为全局配置，不能为用户级配置

<div id="kerberos-support">
  ## Kerberos 支持
</div>

如果 `hadoop_security_authentication` 参数的值为 `kerberos`，ClickHouse 将通过 Kerberos 进行身份验证。
参数见[这里](#clickhouse-extras)，`hadoop_security_kerberos_ticket_cache_path` 也可能会有所帮助。
请注意，由于 libhdfs3 的限制，目前仅支持较旧的方式，
datanode 通信不会受到 SASL 保护 (`HADOOP_SECURE_DN_USER` 是这种
安全方式的可靠标志) 。可参考 `tests/integration/test_storage_kerberized_hdfs/hdfs_configs/bootstrap.sh`。

如果指定了 `hadoop_kerberos_keytab`、`hadoop_kerberos_principal` 或 `hadoop_security_kerberos_ticket_cache_path`，则会使用 Kerberos 身份验证。在这种情况下，必须指定 `hadoop_kerberos_keytab` 和 `hadoop_kerberos_principal`。

<div id="namenode-ha">
  ## 支持 HDFS NameNode HA
</div>

libhdfs3 支持 HDFS NameNode 高可用 (HA) 。

* 将 `hdfs-site.xml` 从某个 HDFS 节点复制到 `/etc/clickhouse-server/`。
* 在 ClickHouse 配置文件中添加以下内容：

```xml theme={null}
  <hdfs>
    <libhdfs3_conf>/etc/clickhouse-server/hdfs-site.xml</libhdfs3_conf>
  </hdfs>
```

* 然后使用 `hdfs-site.xml` 中 `dfs.nameservices` 的值作为 HDFS URI 中的 NameNode 地址。例如，将 `hdfs://appadmin@192.168.101.11:8020/abc/` 替换为 `hdfs://appadmin@my_nameservice/abc/`。

<div id="virtual-columns">
  ## 虚拟列
</div>

* `_path` — 文件路径。类型：`LowCardinality(String)`。
* `_file` — 文件名。类型：`LowCardinality(String)`。
* `_size` — 文件大小 (单位为字节) 。类型：`Nullable(UInt64)`。如果大小未知，则值为 `NULL`。
* `_time` — 文件的最后修改时间。类型：`Nullable(DateTime)`。如果时间未知，则值为 `NULL`。

<div id="storage-settings">
  ## 存储设置
</div>

* [hdfs\_truncate\_on\_insert](/zh/reference/settings/session-settings#hdfs_truncate_on_insert) - 允许在向文件插入数据前先将其截断。默认禁用。
* [hdfs\_create\_new\_file\_on\_insert](/zh/reference/settings/session-settings#hdfs_create_new_file_on_insert) - 如果 格式 带有 suffix，则允许在每次插入时创建新文件。默认禁用。
* [hdfs\_skip\_empty\_files](/zh/reference/settings/session-settings#hdfs_skip_empty_files) - 允许在读取时跳过空文件。默认禁用。

**另请参见**

* [虚拟列](/zh/reference/engines/table-engines#table_engines-virtual_columns)