HDFS

Not supported in ClickHouse Cloud

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

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

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

ENGINE = HDFS(URI, format)

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

• URI - полный URI файла в HDFS. Часть пути URI может содержать шаблоны (globs). В этом случае таблица будет только для чтения.
• 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.
  • Индексы.
  • Репликация с нулевым копированием возможна, но не рекомендуется.
  Репликация с нулевым копированием не готова для производства

  Репликация с нулевым копированием по умолчанию отключена в 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_*). Глобальная конфигурация применяется первой, а затем применяется пользовательская конфигурация (если она существует).

<!-- Global configuration options for HDFS engine type -->
<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>

<!-- Configuration specific for user "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 поддерживает HA для HDFS namenode.

• Скопируйте 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 в HDFS URI. Например, замените 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 - позволяет пропускать пустые файлы при чтении. Отключено по умолчанию.

См. также

• Виртуальные колонки