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

s3

GCS

Функция таблицы S3 интегрируется с Google Cloud Storage, используя GCS XML API и 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 в этом формате, так как конечная точка API Google XML отличается от API JSON:

и не 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 из существующей таблицы:

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

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

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

В результате данные записываются в три файла в разных корзинах: 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 - позволяет пропускать пустые файлы во время чтения. Включен по умолчанию.

См. также