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

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

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

ENGINE = HDFS(URI, format)

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

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

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.
  • Индексы.
  • Репликация с нулевым копированием возможна, но не рекомендуется.

Глоб-шаблоны в пути

Несколько компонентов пути могут содержать глоб-шаблоны. Чтобы файл был обработан, он должен существовать и соответствовать всему шаблону пути. Список файлов формируется во время 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>

Некоторые параметры могут быть описаны в справочнике по конфигурации HDFS.

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

Если параметр 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 обязательны.

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

• Скопируйте 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.
• _etag — ETag файла. Тип: LowCardinality(String). В HDFS нет нативного ETag, поэтому значение синтезируется на основе времени изменения и размера файла в виде <mtime_seconds>_<size>. Поскольку libhdfs3 предоставляет время изменения только с точностью до секунды, перезапись в пределах той же секунды с сохранением того же размера даёт то же значение; поэтому этот синтезированный ETag не используется в качестве ключа кэша содержимого.

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

См. также

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