> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> 지정된 클러스터의 여러 노드에서 Amazon S3 및 Google Cloud Storage의 파일을 병렬로 처리할 수 있도록 하는 s3 테이블 함수의 확장입니다.

# s3Cluster

[s3](/ko/reference/functions/table-functions/s3) 테이블 함수의 확장입니다.

지정된 클러스터의 여러 노드를 사용해 [Amazon S3](https://aws.amazon.com/s3/) 및 Google Cloud Storage [Google Cloud Storage](https://cloud.google.com/storage/)의 파일을 병렬로 처리할 수 있습니다. initiator 노드는 클러스터의 모든 노드에 connection을 생성하고, S3 파일 경로의 와일드카드(\*)를 전개한 다음 각 파일을 동적으로 분배합니다. worker 노드는 initiator에 다음에 처리할 작업을 요청해 이를 처리합니다. 이 과정은 모든 작업이 완료될 때까지 반복됩니다.

<div id="syntax">
  ## 구문
</div>

```sql theme={null}
s3Cluster(cluster_name, url[, NOSIGN | access_key_id, secret_access_key,[session_token]][, format][, structure][, compression_method][, headers][, extra_credentials])
s3Cluster(cluster_name, named_collection[, option=value [,..]])
```

<div id="arguments">
  ## 인수
</div>

| 인수                                      | 설명                                                                                                                                                                                                                                                   |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cluster_name`                          | 원격 및 로컬 서버의 주소 집합과 연결 매개변수를 구성하는 데 사용되는 클러스터 이름입니다.                                                                                                                                                                                                  |
| `url`                                   | 파일 하나 또는 여러 파일의 경로입니다. 읽기 전용 모드에서는 다음 와일드카드를 지원합니다: `*`, `**`, `?`, `{'abc','def'}` 및 `{N..M}`. 여기서 `N`, `M`은 숫자이고 `abc`, `def`는 문자열입니다. 자세한 내용은 [Wildcards In Path](/ko/reference/engines/table-engines/integrations/s3#wildcards-in-path)를 참조하십시오. |
| `NOSIGN`                                | 자격 증명 대신 이 키워드를 지정하면 모든 요청에 서명하지 않습니다.                                                                                                                                                                                                               |
| `access_key_id` and `secret_access_key` | 지정된 엔드포인트에 사용할 자격 증명을 지정하는 키입니다. 선택 사항입니다.                                                                                                                                                                                                           |
| `session_token`                         | 지정된 키와 함께 사용할 세션 토큰입니다. 키를 전달하는 경우 선택 사항입니다.                                                                                                                                                                                                         |
| `format`                                | 파일의 [포맷](/ko/reference/formats)입니다.                                                                                                                                                                                                                  |
| `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')`. 사용 예시는 [here](/ko/reference/functions/table-functions/s3#accessing-requester-pays-buckets)를 참조하십시오.                      |
| `extra_credentials`                     | 선택 사항입니다. `roleARN`은 이 매개변수를 통해 전달할 수 있습니다. 예시는 [here](/ko/products/cloud/guides/data-sources/accessing-s3-data-securely#access-your-s3-bucket-with-the-clickhouseaccess-role)를 참조하십시오.                                                              |

인수는 [이름이 지정된 컬렉션](/ko/concepts/features/configuration/server-config/named-collections)을 사용해 전달할 수도 있습니다. 이 경우 `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입니다.                                                                                                                                                                                      |

<div id="returned_value">
  ## 반환 값
</div>

지정된 파일의 데이터를 읽거나 쓰기 위한, 지정된 구조의 테이블입니다.

<div id="examples">
  ## 예시
</div>

`cluster_simple` 클러스터의 모든 노드를 사용해 `/root/data/clickhouse` 및 `/root/data/database/` 폴더에 있는 모든 파일에서 데이터를 조회합니다:

```sql theme={null}
SELECT * FROM s3Cluster(
    'cluster_simple',
    'http://minio1:9001/root/data/{clickhouse,database}/*',
    'minio',
    'ClickHouse_Minio_P@ssw0rd',
    'CSV',
    'name String, value UInt32, polygon Array(Array(Tuple(Float64, Float64)))'
) ORDER BY (name, value, polygon);
```

`cluster_simple` 클러스터의 모든 파일에 있는 전체 행 수를 계산합니다:

<Tip>
  파일 목록에 앞자리가 0인 숫자 범위가 포함된 경우, 각 자릿수별로 중괄호를 사용하는 구문을 사용하거나 `?`를 사용하십시오.
</Tip>

프로덕션 환경에서는 [이름이 지정된 컬렉션](/ko/concepts/features/configuration/server-config/named-collections)을 사용하는 것이 좋습니다. 다음은 예시입니다:

```sql theme={null}

CREATE NAMED COLLECTION creds AS
        access_key_id = 'minio',
        secret_access_key = 'ClickHouse_Minio_P@ssw0rd';
SELECT count(*) FROM s3Cluster(
    'cluster_simple', creds, url='https://s3-object-url.csv',
    format='CSV', structure='name String, value UInt32, polygon Array(Array(Tuple(Float64, Float64)))'
)
```

<div id="accessing-private-and-public-buckets">
  ## 비공개 및 공개 버킷 액세스
</div>

사용자는 [여기](/ko/reference/functions/table-functions/s3#accessing-public-buckets)에 설명된 s3 함수와 동일한 방법을 사용할 수 있습니다.

<div id="optimizing-performance">
  ## 성능 최적화
</div>

s3 함수의 성능을 최적화하는 방법에 대한 자세한 내용은 [상세 가이드](/ko/integrations/connectors/data-ingestion/AWS/performance)를 참조하십시오.

<div id="related">
  ## 관련
</div>

* [S3 엔진](/ko/reference/engines/table-engines/integrations/s3)
* [S3 테이블 함수](/ko/reference/functions/table-functions/s3)