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

s3

description: 'Предоставляет интерфейс, похожий на таблицу, для выбора/вставки файлов в Amazon S3 и Google Cloud Storage. Эта табличная функция аналогична функции hdfs, но предоставляет функции, специфичные для S3.' keywords: ['s3', 'gcs', 'bucket'] sidebar_label: 's3' sidebar_position: 180 slug: /sql-reference/table-functions/s3 title: 'Функция таблицы 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 имеет следующий формат, так как конечная точка для 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 - позволяет пропускать пустые файлы при чтении. Включена по умолчанию.

См. также