gcs

Предоставляет табличный интерфейс для SELECT и INSERT данных из Google Cloud Storage. Требуется роль IAM Storage Object User.

Предоставляет табличный интерфейс для SELECT и INSERT данных из Google Cloud Storage. Требуется роль IAM Storage Object User.

Это псевдоним табличной функции s3.

Если в вашем кластере несколько реплик, вместо неё можно использовать функцию s3Cluster (она работает с GCS), чтобы распараллелить вставки.

​

Синтаксис

gcs(url [, NOSIGN | hmac_key, hmac_secret] [,format] [,structure] [,compression_method])
gcs(named_collection[, option=value [,..]])

GCS

Табличная функция GCS работает с Google Cloud Storage через GCS XML API и HMAC-ключи. Подробнее о конечной точке и HMAC см. в документации Google по совместимости.

​

Аргументы

Аргумент	Описание
url	Путь к файлу в бакете. В режиме только чтения поддерживаются следующие подстановочные шаблоны: *, **, ?, {abc,def} и {N..M}, где N, M — числа, а 'abc', 'def' — строки.
NOSIGN	Если это ключевое слово указано вместо учетных данных, запросы не будут подписываться.
hmac_key and hmac_secret	Ключи, задающие учетные данные для использования с указанной конечной точкой. Необязательны.
format	Формат файла.
structure	Структура таблицы. Формат: 'column1_name column1_type, column2_name column2_type, ...'.
compression_method	Параметр необязателен. Поддерживаемые значения: none, gzip или gz, brotli или br, xz или LZMA, zstd или zst. По умолчанию метод сжатия определяется автоматически по расширению файла.

GCS

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

  https://storage.googleapis.com/<bucket>/<folder>/<filename(s)>

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

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

Parameter	Description
access_key_id	hmac_key, необязательный параметр.
secret_access_key	hmac_secret, необязательный параметр.
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.

​

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

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

​

Примеры

Выбор первых двух строк из таблицы в файле GCS https://storage.googleapis.com/my-test-bucket-768/data.csv:

SELECT *
FROM gcs('https://storage.googleapis.com/clickhouse_public_datasets/my-test-bucket-768/data.csv.gz', 'CSV', 'column1 UInt32, column2 UInt32, column3 UInt32')
LIMIT 2;

┌─column1─┬─column2─┬─column3─┐
│       1 │       2 │       3 │
│       3 │       2 │       1 │
└─────────┴─────────┴─────────┘

То же самое, но из файла со сжатием gzip:

SELECT *
FROM gcs('https://storage.googleapis.com/clickhouse_public_datasets/my-test-bucket-768/data.csv.gz', 'CSV', 'column1 UInt32, column2 UInt32, column3 UInt32', 'gzip')
LIMIT 2;

┌─column1─┬─column2─┬─column3─┐
│       1 │       2 │       3 │
│       3 │       2 │       1 │
└─────────┴─────────┴─────────┘

​

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

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

• ‘https://storage.googleapis.com/my-test-bucket-768/some_prefix/some_file_1.csv'
• ‘https://storage.googleapis.com/my-test-bucket-768/some_prefix/some_file_2.csv'
• ‘https://storage.googleapis.com/my-test-bucket-768/some_prefix/some_file_3.csv'
• ‘https://storage.googleapis.com/my-test-bucket-768/some_prefix/some_file_4.csv'
• ‘https://storage.googleapis.com/my-test-bucket-768/another_prefix/some_file_1.csv'
• ‘https://storage.googleapis.com/my-test-bucket-768/another_prefix/some_file_2.csv'
• ‘https://storage.googleapis.com/my-test-bucket-768/another_prefix/some_file_3.csv'
• ‘https://storage.googleapis.com/my-test-bucket-768/another_prefix/some_file_4.csv'

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

SELECT count(*)
FROM gcs('https://storage.googleapis.com/clickhouse_public_datasets/my-test-bucket-768/{some,another}_prefix/some_file_{1..3}.csv', 'CSV', 'column1 UInt32, column2 UInt32, column3 UInt32')

┌─count()─┐
│      18 │
└─────────┘

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

SELECT count(*)
FROM gcs('https://storage.googleapis.com/clickhouse_public_datasets/my-test-bucket-768/{some,another}_prefix/*', 'CSV', 'column1 UInt32, column2 UInt32, column3 UInt32')

┌─count()─┐
│      24 │
└─────────┘

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

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

SELECT count(*)
FROM gcs('https://storage.googleapis.com/clickhouse_public_datasets/my-test-bucket-768/big_prefix/file-{000..999}.csv', 'CSV', 'name String, value UInt32');

┌─count()─┐
│      12 │
└─────────┘

Запишите данные в файл test-data.csv.gz:

INSERT INTO FUNCTION gcs('https://storage.googleapis.com/my-test-bucket-768/test-data.csv.gz', 'CSV', 'name String, value UInt32', 'gzip')
VALUES ('test-data', 1), ('test-data-2', 2);

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

INSERT INTO FUNCTION gcs('https://storage.googleapis.com/my-test-bucket-768/test-data.csv.gz', 'CSV', 'name String, value UInt32', 'gzip')
SELECT name, value FROM existing_table;

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

SELECT * FROM gcs('https://storage.googleapis.com/my-test-bucket-768/**', 'CSV', 'name String, value UInt32', 'gzip');

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

SELECT * FROM gcs('https://storage.googleapis.com/my-test-bucket-768/**/test-data.csv.gz', 'CSV', 'name String, value UInt32', 'gzip');

Для production-сценариев рекомендуется использовать именованные коллекции. Ниже приведён пример:

CREATE NAMED COLLECTION creds AS
        access_key_id = '***',
        secret_access_key = '***';
SELECT count(*)
FROM gcs(creds, url='https://s3-object-url.csv')

​

Запись с разбиением на партиции

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

Примеры

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

INSERT INTO TABLE FUNCTION
    gcs('http://bucket.amazonaws.com/my_bucket/file_{_partition_id}.csv', 'CSV', 'a String, b UInt32, c UInt32')
    PARTITION BY a VALUES ('x', 2, 3), ('x', 4, 5), ('y', 11, 12), ('y', 13, 14), ('z', 21, 22), ('z', 23, 24);

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

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

INSERT INTO TABLE FUNCTION
    gcs('http://bucket.amazonaws.com/my_bucket_{_partition_id}/file.csv', 'CSV', 'a UInt32, b UInt32, c UInt32')
    PARTITION BY a VALUES (1, 2, 3), (1, 4, 5), (10, 11, 12), (10, 13, 14), (20, 21, 22), (20, 23, 24);

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

​

См. также

• Табличная функция S3
• Движок S3