> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-parallel-read-in-order-multi-part.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > Предоставляет табличный интерфейс для `SELECT` и `INSERT` данных из Google Cloud Storage. Требуется роль IAM `Storage Object User`. # gcs Предоставляет табличный интерфейс для `SELECT` и `INSERT` данных из [Google Cloud Storage](https://cloud.google.com/storage/). Требуется [роль IAM `Storage Object User`](https://cloud.google.com/storage/docs/access-control/iam-roles). Это псевдоним [табличной функции s3](/ru/reference/functions/table-functions/s3). Если в вашем кластере несколько реплик, вместо неё можно использовать [функцию s3Cluster](/ru/reference/functions/table-functions/s3Cluster) (она работает с GCS), чтобы распараллелить вставки. ## Синтаксис ```sql theme={null} gcs(url [, NOSIGN | hmac_key, hmac_secret] [,format] [,structure] [,compression_method] [,partition_strategy]) gcs(named_collection[, option=value [,..]]) ``` **GCS** Табличная функция GCS работает с Google Cloud Storage через GCS XML API и HMAC-ключи. Подробнее о конечной точке и HMAC см. в [документации Google по совместимости](https://cloud.google.com/storage/docs/interoperability). ## Аргументы | Аргумент | Описание | | - | - | | `url` | Путь к файлу в бакете. В режиме только для чтения поддерживаются следующие подстановочные шаблоны: `*`, `**`, `?`, `{abc,def}` и `{N..M}`, где `N`, `M` — числа, а `'abc'`, `'def'` — строки. | | `NOSIGN` | Если это ключевое слово указано вместо учетных данных, запросы не будут подписываться. | | `hmac_key` and `hmac_secret` | Ключи, задающие учетные данные для использования с указанной конечной точкой. Необязательны. | | `format` | [Формат](/ru/reference/formats/index) файла. | | `structure` | Структура таблицы. Формат: `'column1_name column1_type, column2_name column2_type, ...'`. | | `compression_method` | Параметр необязателен. Поддерживаемые значения: `none`, `gzip` или `gz`, `deflate`, `brotli` или `br`, `xz` или `LZMA`, `zstd` или `zst`, `lz4`, `bz2`, `snappy`. По умолчанию метод сжатия определяется автоматически по расширению файла. Для `snappy` формат передачи данных выбирается настройкой [snappy\_mode](/ru/reference/settings/session-settings/other#snappy_mode) (`basic` по умолчанию). | | `partition_strategy` | Необязательный параметр. Поддерживаемые значения: `wildcard` или `hive`. Для `wildcard` требуется `{_partition_id}` в пути. Если стратегия явно не указана, для пути с `{_partition_id}` используется `wildcard`. Для пути с другим глоб-шаблоном стратегия партиционирования не используется, а `PARTITION BY` игнорируется. Для пути без глоб-шаблона используется `hive`, если `file_like_engine_default_partition_strategy` имеет значение `hive`; в противном случае стратегия партиционирования не используется. | **GCS** Путь GCS имеет следующий формат, поскольку конечная точка Google XML API отличается от JSON API: ```text theme={null} https://storage.googleapis.com/// ``` а не ~~[https://storage.cloud.google.com](https://storage.cloud.google.com)~~. Аргументы также можно передавать с помощью [именованных коллекций](/ru/concepts/features/configuration/server-config/named-collections). В этом случае `url`, `format`, `structure`, `compression_method`, `partition_strategy` работают так же, а также поддерживаются дополнительные параметры: | 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/clickhouse_public_datasets/my-test-bucket-768/data.csv.gz`. Метод сжатия автоматически определяется по расширению файла `.gz`: ```sql theme={null} 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; ``` ```text theme={null} ┌─column1─┬─column2─┬─column3─┐ │ 1 │ 2 │ 3 │ │ 3 │ 2 │ 1 │ └─────────┴─────────┴─────────┘ ``` Тот же запрос, что и выше, но с явно указанным методом сжатия `gzip` вместо автоопределения: ```sql theme={null} 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; ``` ```text theme={null} ┌─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\_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\_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\_3.csv\'); * '[https://storage.googleapis.com/my-test-bucket-768/some\_prefix/some\_file\_4.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\_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\_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\_3.csv\'); * '[https://storage.googleapis.com/my-test-bucket-768/another\_prefix/some\_file\_4.csv\'](https://storage.googleapis.com/my-test-bucket-768/another\_prefix/some\_file\_4.csv\'); Подсчитайте количество строк в файлах, имена которых оканчиваются числами от 1 до 3: ```sql theme={null} 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') ``` ```text theme={null} ┌─count()─┐ │ 18 │ └─────────┘ ``` Подсчитайте общее количество строк во всех файлах этих двух каталогов: ```sql theme={null} 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') ``` ```text theme={null} ┌─count()─┐ │ 24 │ └─────────┘ ``` Если в списке файлов есть диапазоны чисел с ведущими нулями, используйте конструкцию с фигурными скобками для каждой цифры отдельно или символ `?`. Подсчитайте общее количество строк в файлах с именами `file-000.csv`, `file-001.csv`, ... , `file-999.csv`: ```sql theme={null} 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'); ``` ```text theme={null} ┌─count()─┐ │ 12 │ └─────────┘ ``` Запишите данные в файл `test-data.csv.gz`: ```sql theme={null} 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`: ```sql theme={null} 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`: ```sql theme={null} SELECT * FROM gcs('https://storage.googleapis.com/my-test-bucket-768/**', 'CSV', 'name String, value UInt32', 'gzip'); ``` Ниже рекурсивно извлекаются данные из всех файлов `test-data.csv.gz` во всех папках внутри каталога `my-test-bucket`: ```sql theme={null} SELECT * FROM gcs('https://storage.googleapis.com/my-test-bucket-768/**/test-data.csv.gz', 'CSV', 'name String, value UInt32', 'gzip'); ``` Для production-сценариев рекомендуется использовать [именованные коллекции](/ru/concepts/features/configuration/server-config/named-collections). Ниже приведён пример: ```sql theme={null} 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`, для каждого значения партиции будет создан отдельный файл. Разбиение данных на отдельные файлы помогает повысить эффективность чтения. Путь, содержащий `{_partition_id}`, подразумевает стратегию партиционирования `wildcard`, поэтому явное указание `partition_strategy='wildcard'` в приведенных ниже примерах необязательно. Путь с другим глоб-шаблоном не использует стратегию партиционирования и игнорирует `PARTITION BY`. Путь без глоб-шаблона использует `hive`, если `file_like_engine_default_partition_strategy` имеет значение `hive`; в противном случае стратегия партиционирования не используется. **Примеры** 1. Использование идентификатора партиции в ключе создает отдельные файлы: ```sql theme={null} INSERT INTO TABLE FUNCTION gcs('http://bucket.amazonaws.com/my_bucket/file_{_partition_id}.csv', 'CSV', 'a String, b UInt32, c UInt32', partition_strategy='wildcard') 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. Использование идентификатора партиции в имени бакета приводит к созданию файлов в разных бакетах: ```sql theme={null} INSERT INTO TABLE FUNCTION gcs('http://bucket.amazonaws.com/my_bucket_{_partition_id}/file.csv', 'CSV', 'a UInt32, b UInt32, c UInt32', partition_strategy='wildcard') 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](/ru/reference/functions/table-functions/s3) * [Движок S3](/ru/reference/engines/table-engines/integrations/s3)