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

> Этот движок обеспечивает интеграцию с экосистемой Apache Hadoop, позволяя управлять данными в HDFS через ClickHouse. Он похож на движки 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>;
};

Этот движок обеспечивает интеграцию с экосистемой [Apache Hadoop](https://en.wikipedia.org/wiki/Apache_Hadoop), позволяя управлять данными в [HDFS](https://hadoop.apache.org/docs/current/hadoop-project-dist/hadoop-hdfs/HdfsDesign.html) через ClickHouse. Этот движок похож на движки [File](/ru/reference/engines/table-engines/special/file) и [URL](/ru/reference/engines/table-engines/special/url), но предоставляет возможности, специфичные для Hadoop.

Эта возможность не поддерживается инженерами ClickHouse, и её качество, как известно, оставляет желать лучшего. Если возникнут какие-либо проблемы, исправляйте их самостоятельно и отправляйте pull request.

<div id="usage">
  ## Использование
</div>

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

**Параметры движка**

* `URI` — полный URI файла в HDFS. Часть пути в `URI` может содержать глоб-шаблоны. В этом случае таблица будет доступна только для чтения.
* `format` — задаёт один из доступных форматов файлов. Чтобы выполнять
  запросы `SELECT`, формат должен поддерживать ввод, а для выполнения
  запросов `INSERT` — вывод. Доступные форматы перечислены в разделе
  [Форматы](/ru/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](/ru/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`.
  * Индексы.
  * [Репликация с нулевым копированием](/ru/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](/ru/reference/functions/table-functions/remote).

**Пример**

1. Предположим, у нас есть несколько файлов в формате TSV со следующими URI в HDFS:

   * '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')
```

Таблица включает все файлы из обоих каталогов (все файлы должны соответствовать формату и схеме, описанным в запросе):

```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">
  ## Поддержка HA для NameNode в HDFS
</div>

libhdfs3 поддерживает HA для NameNode в HDFS.

* Скопируйте `hdfs-site.xml` с узла HDFS в `/etc/clickhouse-server/`.
* Добавьте следующий фрагмент в config-файл ClickHouse:

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

* Затем используйте значение тега `dfs.nameservices` из `hdfs-site.xml` в качестве адреса NameNode в URI HDFS. Например, замените `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](/ru/reference/settings/session-settings#hdfs_truncate_on_insert) - позволяет обрезать файл перед вставкой в него. По умолчанию отключено.
* [hdfs\_create\_new\_file\_on\_insert](/ru/reference/settings/session-settings#hdfs_create_new_file_on_insert) - позволяет создавать новый файл при каждой вставке, если у формата есть суффикс. По умолчанию отключено.
* [hdfs\_skip\_empty\_files](/ru/reference/settings/session-settings#hdfs_skip_empty_files) - позволяет пропускать пустые файлы при чтении. По умолчанию отключено.

**См. также**

* [Виртуальные столбцы](/ru/reference/engines/table-engines#table_engines-virtual_columns)