Перейти к основному содержимому
Перейти к основному содержимому

Функция таблицы file

Движок таблицы, который предоставляет интерфейс, похожий на таблицу, для SELECT и INSERT в файлы, аналогично табличной функции s3. Используйте file() при работе с локальными файлами и s3() при работе с ведрами в объектном хранилище, таком как S3, GCS или MinIO.

Функция file может использоваться в запросах SELECT и INSERT для чтения из или записи в файлы.

Синтаксис

Параметры

  • path — Относительный путь к файлу от user_files_path. Поддерживает в режиме только для чтения следующие глобусы: *, ?, {abc,def} (где 'abc' и 'def' являются строками) и {N..M} (где N и M — числа).
  • path_to_archive - Относительный путь к архиву zip/tar/7z. Поддерживает те же глобусы, что и path.
  • format — формат файла.
  • structure — Структура таблицы. Формат: 'column1_name column1_type, column2_name column2_type, ...'.
  • compression — Существующий тип сжатия при использовании в запросе SELECT или желаемый тип сжатия при использовании в запросе INSERT. Поддерживаемые типы сжатия: gz, br, xz, zst, lz4 и bz2.

Возвращаемое значение

Таблица для чтения или записи данных в файл.

Примеры записи в файл​

Запись в TSV файл​

В результате данные записываются в файл test.tsv:

Разделенная запись в несколько TSV файлов​

Если вы укажете выражение PARTITION BY, когда вставляете данные в табличную функцию типа file(), то для каждой секции будет создан отдельный файл. Разделение данных на отдельные файлы помогает улучшить производительность операций чтения.

В результате данные будут записаны в три файла: test_1.tsv, test_2.tsv и test_3.tsv.

Примеры чтения из файла​

SELECT из CSV файла​

Сначала установите user_files_path в конфигурации сервера и подготовьте файл test.csv:

Затем прочитайте данные из test.csv в таблицу и выберите первые две строки:

Вставка данных из файла в таблицу​

Чтение данных из table.csv, находящегося в archive1.zip или/и archive2.zip:

Глобусы в пути​

Пути могут использовать глобальные шаблоны. Файлы должны соответствовать всему шаблону пути, а не только суффиксу или префиксу. Есть одно исключение: если путь ссылается на существующий каталог и не использует глобусы, * будет автоматически добавлен к пути, чтобы выбрать все файлы в каталоге.

  • * — Представляет произвольное количество символов, кроме /, но включая пустую строку.
  • ? — Представляет произвольный один символ.
  • {some_string,another_string,yet_another_one} — Заменяет любую из строк 'some_string', 'another_string', 'yet_another_one'. Строки могут содержать символ /.
  • {N..M} — Представляет любое число >= N и <= M.
  • ** - Представляет все файлы внутри папки рекурсивно.

Конструкции с {} аналогичны табличным функциям remote и hdfs.

Пример

Предположим, что есть такие файлы со следующими относительными путями:

  • some_dir/some_file_1
  • some_dir/some_file_2
  • some_dir/some_file_3
  • another_dir/some_file_1
  • another_dir/some_file_2
  • another_dir/some_file_3

Запрос на общее количество строк во всех файлах:

Альтернативное выражение пути, достигающее того же:

Запрос на общее количество строк в some_dir с использованием неявного *:

примечание

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

Пример

Запрос на общее количество строк в файлах с именами file000, file001, ... , file999:

Пример

Запрос на общее количество строк из всех файлов внутри каталога big_dir/ рекурсивно:

Пример

Запрос на общее количество строк из всех файлов file002 внутри любой папки в каталоге big_dir/ рекурсивно:

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

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

Разделение в стиле Hive​

Когда установка use_hive_partitioning установлена в 1, ClickHouse будет обнаруживать разбиение в стиле Hive в пути (/name=value/) и позволит использовать колонки раздела как виртуальные колонки в запросе. Эти виртуальные колонки будут иметь те же имена, что и в разделенном пути, но с подчеркиванием в начале.

Пример

Используйте виртуальный столбец, созданный с помощью разбиения в стиле Hive

Настройки​

  • engine_file_empty_if_not_exists - позволяет выбирать пустые данные из несуществующего файла. Отключено по умолчанию.
  • engine_file_truncate_on_insert - позволяет обрезать файл перед вставкой в него. Отключено по умолчанию.
  • engine_file_allow_create_multiple_files - позволяет создавать новый файл при каждой вставке, если формат имеет суффикс. Отключено по умолчанию.
  • engine_file_skip_empty_files - позволяет пропускать пустые файлы при чтении. Отключено по умолчанию.
  • storage_file_read_method - метод чтения данных из файла хранилища, один из: read, pread, mmap (только для clickhouse-local). Значение по умолчанию: pread для clickhouse-server, mmap для clickhouse-local.

См. также