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

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

Предоставляет интерфейс, похожий на таблицу, для выбора/вставки файлов в Amazon S3 и Google Cloud Storage. Эта табличная функция схожа с функцией hdfs, но предоставляет специфические для S3 функции.

Если у вас есть несколько реплик в кластере, вы можете использовать функцию s3Cluster вместо этого, чтобы параллелизировать вставки.

Когда вы используете s3 table function с INSERT INTO...SELECT, данные читаются и вставляются в потоковом режиме. В памяти находится только несколько блоков данных, в то время как блоки непрерывно читаются из S3 и вставляются в целевую таблицу.

Синтаксис

GCS

Функция таблицы S3 интегрируется с Google Cloud Storage, используя XML API GCS и HMAC ключи. Смотрите документацию по совместимости Google для получения дополнительных деталей о конечной точке и HMAC.

Для GCS замените свой HMAC ключ и HMAC секрет там, где указаны access_key_id и secret_access_key.

Параметры

Функция таблицы s3 поддерживает следующие простые параметры:

  • url — URL бакета с путем к файлу. Поддерживает следующие подстановочные знаки в режиме только для чтения: *, **, ?, {abc,def} и {N..M}, где N, M — числа, 'abc', 'def' — строки. Для получения дополнительной информации смотрите здесь.
    GCS

    URL GCS имеет следующий формат, так как конечная точка для Google XML API отличается от JSON API:

а не https://storage.cloud.google.com. :::

  • NOSIGN — Если это ключевое слово указано вместо учетных данных, все запросы не будут подписаны.
  • access_key_id и secret_access_key — Ключи, которые указывают учетные данные для использования с указанной конечной точкой. Необязательный.
  • session_token - Токен сессии для использования с указанными ключами. Необязателен при передаче ключей.
  • format — формат файла.
  • structure — Структура таблицы. Формат 'column1_name column1_type, column2_name column2_type, ...'.
  • compression_method — Параметр является необязательным. Поддерживаемые значения: none, gzip или gz, brotli или br, xz или LZMA, zstd или zst. По умолчанию он будет автоматически определять метод сжатия по расширению файла.
  • headers - Параметр является необязательным. Позволяет передавать заголовки в запросе S3. Передайте в формате headers(key=value), например, headers('x-amz-request-payer' = 'requester').

Аргументы также могут передаваться с использованием именованных коллекций. В этом случае url, access_key_id, secret_access_key, format, structure, compression_method работают так же, и поддерживаются некоторые дополнительные параметры:

  • filename — добавлен к URL, если указан.
  • use_environment_credentials — включен по умолчанию, позволяет передавать дополнительные параметры с использованием переменных окружения AWS_CONTAINER_CREDENTIALS_RELATIVE_URI, AWS_CONTAINER_CREDENTIALS_FULL_URI, AWS_CONTAINER_AUTHORIZATION_TOKEN, AWS_EC2_METADATA_DISABLED.
  • no_sign_request — отключен по умолчанию.
  • expiration_window_seconds — значение по умолчанию 120.

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

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

Примеры

Выбор первых 5 строк из таблицы из файла S3 https://datasets-documentation.s3.eu-west-3.amazonaws.com/aapl_stock.csv:

примечание

ClickHouse использует расширения имен файлов для определения формата данных. Например, мы могли бы выполнить предыдущую команду без CSVWithNames:

ClickHouse также может определить метод сжатия файла. Например, если файл был сжат с расширением .csv.gz, ClickHouse автоматически декомпрессирует файл.

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

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

Посчитаем количество строк в файлах, оканчивающихся на номера от 1 до 3:

Посчитаем общее количество строк во всех файлах в этих двух директориях:

подсказка

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

Посчитаем общее количество строк в файлах с именами file-000.csv, file-001.csv, ... , file-999.csv:

Вставим данные в файл test-data.csv.gz:

Вставим данные в файл test-data.csv.gz из существующей таблицы:

Glob ** может использоваться для рекурсивного обхода директорий. Рассмотрим следующий пример, он будет извлекать все файлы из директории my-test-bucket-768 рекурсивно:

Следующий запрос извлекает данные из всех файлов test-data.csv.gz из любой папки внутри директории my-test-bucket рекурсивно:

Примечание. Возможно указать собственные сопоставления URL в файле конфигурации сервера. Пример:

URL 's3://clickhouse-public-datasets/my-test-bucket-768/**/test-data.csv.gz' будет заменен на 'http://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/**/test-data.csv.gz'.

Пользовательское сопоставление можно добавить в config.xml:

Для производственных случаев рекомендуется использовать именованные коллекции. Вот пример:

Разделенные записи​

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

Примеры

  1. Использование идентификатора раздела в ключе создает отдельные файлы:

В результате данные записываются в три файла: file_x.csv, file_y.csv и file_z.csv.

  1. Использование идентификатора раздела в имени бакета создает файлы в разных бакетах:

В результате данные записываются в три файла в разных бакетах: my_bucket_1/file.csv, my_bucket_10/file.csv и my_bucket_20/file.csv.

Доступ к общедоступным бакетам​

ClickHouse пытается получить учетные данные из многих различных источников. Иногда это может вызвать проблемы при доступе к некоторым бакетам, которые являются общедоступными, заставляя клиента вернуть код ошибки 403. Эту проблему можно избежать, используя ключевое слово NOSIGN, заставляющее клиента игнорировать все учетные данные и не подписывать запросы.

Использование учетных данных S3 (ClickHouse Cloud)​

Для не общедоступных бакетов пользователи могут передавать aws_access_key_id и aws_secret_access_key в функцию. Например:

Это подходит для разового доступа или в случаях, когда учетные данные можно легко заменить. Однако это не рекомендуется как долгосрочное решение для повторяющегося доступа или в случаях, когда учетные данные являются конфиденциальными. В этом случае мы рекомендуем пользователям полагаться на контроль доступа на основе ролей.

Контроль доступа на основе ролей для S3 в ClickHouse Cloud задокументирован здесь.

После настройки roleARN можно передать функции s3 через параметр extra_credentials. Например:

Дополнительные примеры можно найти здесь.

Работа с архивами​

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

Извлечение данных из этих архивов возможно, используя ::. Подстановочные знаки могут использоваться как в части URL, так и в части после :: (отвечает за имя файла внутри архива).

примечание

ClickHouse поддерживает три формата архивов: ZIP TAR 7Z В то время как архивы ZIP и TAR можно получить из любого поддерживаемого хранилища, архивы 7Z можно читать только с локальной файловой системы, где установлен ClickHouse.

Вставка данных​

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

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

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

Разделение по стилю Hive​

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

Пример

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

Доступ к бакетам с оплатой по запросу​

Для доступа к бакету с оплатой по запросу необходимо передать заголовок x-amz-request-payer = requester в любые запросы. Это достигается путем передачи параметра headers('x-amz-request-payer' = 'requester') в функцию s3. Например:

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

  • s3_truncate_on_insert - позволяет обрезать файл перед вставкой в него. Отключено по умолчанию.
  • s3_create_new_file_on_insert - позволяет создавать новый файл при каждой вставке, если формат имеет суффикс. Отключено по умолчанию.
  • s3_skip_empty_files - позволяет пропускать пустые файлы при чтении. Включено по умолчанию.

Смотрите также