gcs 테이블 함수

gcs 테이블 함수 (gcs)

Google Cloud Storage에서 데이터를 SELECT하고 INSERT하는 테이블형 인터페이스를 제공해요. Storage Object User IAM 역할이 필요합니다.

이것은 s3 테이블 함수의 별칭입니다. 클러스터에 여러 레플리카가 있다면, 삽입을 병렬화하기 위해 대신 s3Cluster 함수(GCS와 함께 동작)를 사용할 수 있어요.

출처: 문서

본문

Google Cloud Storage에서 데이터를 SELECT하고 INSERT하는 테이블형 인터페이스를 제공합니다. Storage Object User IAM 역할이 필요합니다.

이것은 s3 테이블 함수의 별칭입니다. 클러스터에 여러 레플리카가 있다면, 삽입을 병렬화하기 위해 대신 s3Cluster 함수(GCS와 함께 동작)를 사용할 수 있습니다.

구문

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

GCS — GCS 테이블 함수는 GCS XML API와 HMAC 키를 사용해 Google Cloud Storage와 통합됩니다.

엔드포인트와 HMAC에 대한 자세한 내용은 Google interoperability 문서를 참고하세요.

인자

인자	설명
`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`, `deflate`, `brotli` 또는 `br`, `xz` 또는 `LZMA`, `zstd` 또는 `zst`, `lz4`, `bz2`, `snappy`. 기본적으로 파일 확장자로 압축 방법을 자동 감지합니다. `snappy`의 경우 snappy_mode 설정(`basic`이 기본값)으로 와이어 포맷을 선택합니다.
`partition_strategy`	선택 사항. 지원 값: `wildcard` 또는 `hive`. `wildcard`는 경로에 `{_partition_id}`가 필요합니다. 명시적 전략이 없으면 `{_partition_id}`가 있는 경로는 `wildcard`를 사용합니다. 다른 glob이 있는 경로는 파티션 전략이 없고 `PARTITION BY`를 무시합니다. glob이 없는 경로는 `file_like_engine_default_partition_strategy`가 `hive`일 때 `hive`를, 그 외에는 파티션 전략을 사용하지 않습니다.

GCS — GCS 경로는 Google XML API의 엔드포인트가 JSON API와 다르므로 다음 형식입니다:

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

그리고 ~~https://storage.cloud.google.com~~가 아닙니다.

인자는 named collections로도 전달할 수 있습니다. 이 경우 url, format, structure, compression_method, partition_strategy는 같은 방식으로 동작하며, 몇 가지 추가 파라미터가 지원됩니다:

파라미터	설명
`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 파일 확장자에서 압축 방법이 자동으로 감지됩니다:

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 │
└─────────┴─────────┴─────────┘

사용법

GCS에 다음과 같은 URI의 여러 파일이 있다고 가정합니다:

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 │
└─────────┘

파일 목록에 앞자리 0이 있는 숫자 범위가 포함되어 있으면, 각 자릿수에 대해 중괄호 구성을 따로 사용하거나 ?를 사용하세요.

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');

아래는 my-test-bucket 디렉터리 안의 어떤 폴더든 test-data.csv.gz 파일 모두에서 데이터를 가져옵니다:

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

프로덕션 사용 사례에서는 named collections를 사용하는 것이 권장됩니다. 예제:

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'는 선택 사항입니다. 다른 glob이 있는 경로는 파티션 전략이 없고 PARTITION BY를 무시합니다. glob이 없는 경로는 file_like_engine_default_partition_strategy가 hive일 때 hive를, 그 외에는 파티션 전략을 사용하지 않습니다.

예제

키에 파티션 ID를 사용하면 별도 파일이 생성됩니다:

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 세 파일에 기록됩니다.

버킷 이름에 파티션 ID를 사용하면 다른 버킷에 파일이 생성됩니다:

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 세 파일에 데이터가 기록됩니다.

gcs 테이블 함수