Движок таблицы HDFS

Not supported in ClickHouse Cloud

Этот движок обеспечивает интеграцию с экосистемой Apache Hadoop, позволяя управлять данными в HDFS через ClickHouse. Этот движок похож на движки File и URL, но предоставляет специфические для Hadoop возможности.

Эта функциональность не поддерживается инженерами ClickHouse и известна своим сомнительным качеством реализации. В случае любых проблем исправляйте их самостоятельно и отправляйте pull request.

Использование

ENGINE = HDFS(URI, format)

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

• URI — полный URI файла в HDFS. Часть пути в URI может содержать glob-шаблоны. В этом случае таблица будет доступна только для чтения.
• format — указывает один из доступных форматов файлов. Для выполнения SELECT-запросов формат должен поддерживаться для ввода, а для выполнения INSERT-запросов — для вывода. Доступные форматы перечислены в разделе Formats.
• [PARTITION BY expr]

PARTITION BY

PARTITION BY — необязательный параметр. В большинстве случаев ключ партиционирования не требуется, а если и требуется, обычно нет необходимости делать его более детализированным, чем по месяцам. Партиционирование не ускоряет выполнение запросов (в отличие от выражения ORDER BY). Не следует использовать излишне детализированное партиционирование. Не выполняйте партиционирование данных по идентификаторам или именам клиентов (вместо этого сделайте идентификатор или имя клиента первым столбцом в выражении ORDER BY).

Для партиционирования по месяцам используйте выражение toYYYYMM(date_column), где date_column — столбец с датой типа Date. Имена партиций в этом случае имеют формат "YYYYMM".

Пример:

1. Создайте таблицу hdfs_engine_table:

CREATE TABLE hdfs_engine_table (name String, value UInt32) ENGINE=HDFS('hdfs://hdfs1:9000/other_storage', 'TSV')

2. Заполните файл:

INSERT INTO hdfs_engine_table VALUES ('one', 1), ('two', 2), ('three', 3)

3. Выполните запрос:

SELECT * FROM hdfs_engine_table LIMIT 2

┌─name─┬─value─┐
│ one  │     1 │
│ two  │     2 │
└──────┴───────┘

Подробности реализации

• Операции чтения и записи могут выполняться параллельно.

• Не поддерживаются:

  • Операции ALTER и SELECT...SAMPLE.
  • Индексы.
  • Zero-copy репликация возможна, но не рекомендуется.
  Репликация Zero-copy не готова для продакшена

  Репликация Zero-copy по умолчанию отключена в ClickHouse версии 22.8 и выше. Эта функция не рекомендуется для использования в продакшене.

Глоб-выражения в пути

Несколько компонентов пути могут содержать глоб-выражения. Для обработки файл должен существовать и полностью соответствовать шаблону пути. Список файлов определяется при выполнении SELECT (а не при CREATE).

• * — Соответствует любой последовательности любых символов, кроме /, включая пустую строку.
• ? — Соответствует любому одиночному символу.
• {some_string,another_string,yet_another_one} — Соответствует любой из строк 'some_string', 'another_string', 'yet_another_one'.
• {N..M} — Соответствует любому числу в диапазоне от N до M включительно.

Конструкции с {} аналогичны табличной функции 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. Есть несколько способов создать таблицу, состоящую из всех шести файлов:

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

Ещё один способ:

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

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

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

Примечание

Если в списке файлов есть диапазоны номеров с ведущими нулями, используйте конструкцию с фигурными скобками для каждой цифры отдельно или используйте ?.

Пример

Создайте таблицу с файлами с именами file000, file001, ... , file999:

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

Конфигурация

Как и GraphiteMergeTree, движок HDFS поддерживает расширенную настройку с помощью конфигурационного файла ClickHouse. Доступны два ключа конфигурации: глобальный (hdfs) и пользовательский (hdfs_*). Сначала применяется глобальная конфигурация, а затем — пользовательская (если она есть).

<!-- Глобальные параметры конфигурации для типа движка 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>

Параметры конфигурации

Поддерживаемые libhdfs3

параметр	значение по умолчанию
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 может пояснить некоторые параметры.

Дополнительные параметры ClickHouse

параметр	значение по умолчанию
hadoop_kerberos_keytab	""
hadoop_kerberos_principal	""
libhdfs3_conf	""

Ограничения

• hadoop_security_kerberos_ticket_cache_path и libhdfs3_conf могут задаваться только глобально, а не на уровне пользователя

Поддержка Kerberos

Если параметр hadoop_security_authentication имеет значение kerberos, ClickHouse аутентифицируется через Kerberos. Параметры описаны здесь, также может быть полезен 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 являются обязательными.

Поддержка HDFS Namenode HA

libhdfs3 поддерживает HDFS Namenode HA.

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

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

Виртуальные столбцы

• _path — Путь к файлу. Тип: LowCardinality(String).
• _file — Имя файла. Тип: LowCardinality(String).
• _size — Размер файла в байтах. Тип: Nullable(UInt64). Если размер неизвестен, значение — NULL.
• _time — Время последнего изменения файла. Тип: Nullable(DateTime). Если время неизвестно, значение — NULL.

Настройки хранения

• hdfs_truncate_on_insert — позволяет усечь файл перед вставкой в него данных. По умолчанию отключена.
• hdfs_create_new_file_on_insert — позволяет создавать новый файл при каждой вставке, если формат имеет суффикс. По умолчанию отключена.
• hdfs_skip_empty_files — позволяет пропускать пустые файлы при чтении. По умолчанию отключена.

См. также

• Виртуальные столбцы