> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> Avro 포맷 문서

# Avro

| 입력 | 출력 | 별칭 |
| -- | -- | -- |
| ✔  | ✔  |    |

<div id="description">
  ## 설명
</div>

[Apache Avro](https://avro.apache.org/)는 효율적인 데이터 처리를 위해 바이너리 인코딩을 사용하는 행 지향 직렬화 포맷입니다. `Avro` 포맷은 [Avro data files](https://avro.apache.org/docs/current/specification/#object-container-files)의 읽기와 쓰기를 지원합니다. 이 포맷은 스키마가 내장된 자체 기술형 메시지를 사용한다고 가정합니다. 스키마 레지스트리와 함께 Avro를 사용하는 경우 [`AvroConfluent`](/docs/ko/reference/formats/Avro/AvroConfluent) 포맷을 참고하십시오.

<div id="data-type-mapping">
  ## 데이터 타입 매핑
</div>

아래 표에는 Apache Avro 포맷이 지원하는 모든 데이터 타입과 `INSERT` 및 `SELECT` 쿼리에서 각각에 대응하는 ClickHouse [데이터 타입](/docs/ko/reference/data-types/index)이 나와 있습니다.

| Avro data type `INSERT`                     | ClickHouse data type                                                                                  | Avro data type `SELECT`          |
| ------------------------------------------- | ----------------------------------------------------------------------------------------------------- | -------------------------------- |
| `boolean`, `int`, `long`, `float`, `double` | [Int(8\16\32)](/docs/ko/reference/data-types/int-uint), [UInt(8\16\32)](/docs/ko/reference/data-types/int-uint) | `int`                            |
| `boolean`, `int`, `long`, `float`, `double` | [Int64](/docs/ko/reference/data-types/int-uint), [UInt64](/docs/ko/reference/data-types/int-uint)               | `long`                           |
| `boolean`, `int`, `long`, `float`, `double` | [Float32](/docs/ko/reference/data-types/float)                                                             | `float`                          |
| `boolean`, `int`, `long`, `float`, `double` | [Float64](/docs/ko/reference/data-types/float)                                                             | `double`                         |
| `bytes`, `string`, `fixed`, `enum`          | [String](/docs/ko/reference/data-types/string)                                                             | `bytes` 또는 `string` \*           |
| `bytes`, `string`, `fixed`                  | [FixedString(N)](/docs/ko/reference/data-types/fixedstring)                                                | `fixed(N)`                       |
| `enum`                                      | [Enum(8\16)](/docs/ko/reference/data-types/enum)                                                           | `enum`                           |
| `array(T)`                                  | [Array(T)](/docs/ko/reference/data-types/array)                                                            | `array(T)`                       |
| `map(V, K)`                                 | [Map(V, K)](/docs/ko/reference/data-types/map)                                                             | `map(string, K)`                 |
| `union(null, T)`, `union(T, null)`          | [Nullable(T)](/docs/ko/reference/data-types/date)                                                          | `union(null, T)`                 |
| `union(T1, T2, …)` \*\*                     | [Variant(T1, T2, …)](/docs/ko/reference/data-types/variant)                                                | `union(T1, T2, …)` \*\*          |
| `null`                                      | [Nullable(Nothing)](/docs/ko/reference/data-types/special-data-types/nothing)                              | `null`                           |
| `int (date)` \*\*\*                         | [Date](/docs/ko/reference/data-types/date), [Date32](/docs/ko/reference/data-types/date32)                      | `int (date)` \*\*\*              |
| `long (timestamp-millis)` \*\*\*            | [DateTime64(3)](/docs/ko/reference/data-types/datetime)                                                    | `long (timestamp-millis)` \*\*\* |
| `long (timestamp-micros)` \*\*\*            | [DateTime64(6)](/docs/ko/reference/data-types/datetime)                                                    | `long (timestamp-micros)` \*\*\* |
| `bytes (decimal)`  \*\*\*                   | [DateTime64(N)](/docs/ko/reference/data-types/datetime)                                                    | `bytes (decimal)`  \*\*\*        |
| `int`                                       | [IPv4](/docs/ko/reference/data-types/ipv4)                                                                 | `int`                            |
| `fixed(16)`                                 | [IPv6](/docs/ko/reference/data-types/ipv6)                                                                 | `fixed(16)`                      |
| `bytes (decimal)` \*\*\*                    | [Decimal(P, S)](/docs/ko/reference/data-types/decimal)                                                     | `bytes (decimal)` \*\*\*         |
| `string (uuid)` \*\*\*                      | [UUID](/docs/ko/reference/data-types/uuid)                                                                 | `string (uuid)` \*\*\*           |
| `fixed(16)`                                 | [Int128/UInt128](/docs/ko/reference/data-types/int-uint)                                                   | `fixed(16)`                      |
| `fixed(32)`                                 | [Int256/UInt256](/docs/ko/reference/data-types/int-uint)                                                   | `fixed(32)`                      |
| `record`                                    | [Tuple](/docs/ko/reference/data-types/tuple)                                                               | `record`                         |

* `bytes`가 기본값이며, 설정 [`output_format_avro_string_column_pattern`](/docs/ko/reference/settings/formats#output_format_avro_string_column_pattern)으로 제어됩니다.

\*\*  [Variant 타입](/docs/ko/reference/data-types/variant)은 필드 값으로 `null`을 암묵적으로 허용하므로, 예를 들어 Avro `union(T1, T2, null)`은 `Variant(T1, T2)`로 변환됩니다.
따라서 ClickHouse에서 Avro를 생성할 때는 스키마 추론 과정에서 실제로 어떤 값이 `null`인지 알 수 없으므로, Avro `union` 타입 집합에 항상 `null` 타입을 포함해야 합니다.

\*\*\* [Avro 논리 타입](https://avro.apache.org/docs/1.12.0/specification/#logical-types)

지원되지 않는 Avro 논리 데이터 타입:

* `time-millis`
* `time-micros`
* `duration`

<div id="format-settings">
  ## 포맷 설정
</div>

| 설정                                         | 설명                                                                                                   | 기본값     |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------- | ------- |
| `input_format_avro_allow_missing_fields`   | 스키마에서 필드를 찾을 수 없을 때 오류를 발생시키는 대신 기본값을 사용할지 여부입니다.                                                    | `0`     |
| `input_format_avro_null_as_default`        | `null` 값을 널을 허용하지 않는 컬럼에 삽입할 때 오류를 발생시키는 대신 기본값을 사용할지 여부입니다.                                         | `0`     |
| `output_format_avro_codec`                 | Avro 출력 파일의 압축 알고리즘입니다. 가능한 값: `null`, `deflate`, `snappy`, `zstd`.                                  |         |
| `output_format_avro_sync_interval`         | Avro 파일의 동기화 마커 빈도(바이트 단위)입니다.                                                                       | `16384` |
| `output_format_avro_string_column_pattern` | Avro 문자열 유형 매핑에 사용할 `String` 컬럼을 식별하는 정규식입니다. 기본적으로 ClickHouse `String` 컬럼은 Avro `bytes` 유형으로 기록됩니다. |         |
| `output_format_avro_rows_in_file`          | Avro 출력 파일당 최대 행 수입니다. 이 한도에 도달하면 새 파일이 생성됩니다(스토리지 시스템이 파일 분할을 지원하는 경우).                             | `1`     |

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

<div id="reading-avro-data">
  ### Avro 데이터 읽기
</div>

Avro 파일의 데이터를 ClickHouse 테이블로 가져오려면:

```bash theme={null}
$ cat file.avro | clickhouse-client --query="INSERT INTO {some_table} FORMAT Avro"
```

수집된 Avro 파일의 루트 스키마는 반드시 `record` 타입이어야 합니다.

테이블 컬럼과 Avro 스키마 필드 간의 대응 관계를 찾기 위해 ClickHouse는 이름을 비교합니다.
이 비교는 대소문자를 구분하며, 사용되지 않는 필드는 건너뜁니다.

ClickHouse 테이블 컬럼의 데이터 타입은 삽입되는 Avro 데이터의 해당 필드와 다를 수 있습니다. 데이터를 삽입할 때 ClickHouse는 위 표에 따라 데이터 타입을 해석한 다음, 데이터를 해당 컬럼 타입으로 [캐스팅](/docs/ko/reference/functions/regular-functions/type-conversion-functions#CAST)합니다.

데이터를 가져오는 중 스키마에서 필드를 찾을 수 없고 설정 [`input_format_avro_allow_missing_fields`](/docs/ko/reference/settings/formats#input_format_avro_allow_missing_fields)가 활성화되어 있으면, 오류를 발생시키는 대신 기본값이 사용됩니다.

<div id="writing-avro-data">
  ### Avro 파일에 데이터 쓰기
</div>

ClickHouse 테이블의 데이터를 Avro 파일에 쓰려면 다음과 같이 하십시오:

```bash theme={null}
$ clickhouse-client --query="SELECT * FROM {some_table} FORMAT Avro" > file.avro
```

컬럼 이름은 다음 조건을 충족해야 합니다:

* `[A-Za-z_]`로 시작해야 합니다
* 뒤에는 `[A-Za-z0-9_]`만 사용할 수 있습니다

Avro 파일의 출력 압축 및 동기화 인터벌은 각각 [`output_format_avro_codec`](/docs/ko/reference/settings/formats#output_format_avro_codec) 및 [`output_format_avro_sync_interval`](/docs/ko/reference/settings/formats#output_format_avro_sync_interval) 설정으로 구성할 수 있습니다.

<div id="inferring-the-avro-schema">
  ### Avro 스키마 추론
</div>

ClickHouse [`DESCRIBE`](/docs/ko/reference/statements/describe-table) 함수를 사용하면 다음 예시처럼 Avro 파일에서 추론된 포맷을 빠르게 확인할 수 있습니다.
이 예시에는 ClickHouse S3 공개 버킷에서 공개적으로 접근할 수 있는 Avro 파일의 URL이 포함되어 있습니다.

```sql theme={null}
DESCRIBE url('https://clickhouse-public-datasets.s3.eu-central-1.amazonaws.com/hits.avro', 'Avro');

┌─name───────────────────────┬─type────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐
│ WatchID                    │ Int64           │              │                    │         │                  │                │
│ JavaEnable                 │ Int32           │              │                    │         │                  │                │
│ Title                      │ String          │              │                    │         │                  │                │
│ GoodEvent                  │ Int32           │              │                    │         │                  │                │
│ EventTime                  │ Int32           │              │                    │         │                  │                │
│ EventDate                  │ Date32          │              │                    │         │                  │                │
│ CounterID                  │ Int32           │              │                    │         │                  │                │
│ ClientIP                   │ Int32           │              │                    │         │                  │                │
│ ClientIP6                  │ FixedString(16) │              │                    │         │                  │                │
│ RegionID                   │ Int32           │              │                    │         │                  │                │
...
│ IslandID                   │ FixedString(16) │              │                    │         │                  │                │
│ RequestNum                 │ Int32           │              │                    │         │                  │                │
│ RequestTry                 │ Int32           │              │                    │         │                  │                │
└────────────────────────────┴─────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘
```