> ## 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.

> ClickHouse 연결을 위한 공식 Rust 클라이언트입니다.

# ClickHouse Rust 클라이언트

ClickHouse 연결을 위한 공식 Rust 클라이언트입니다. 최초 개발자는 [Paul Loyd](https://github.com/loyd)이며, 클라이언트 소스 코드는 [GitHub 리포지토리](https://github.com/ClickHouse/clickhouse-rs)에서 확인할 수 있습니다.

<div id="overview">
  ## 개요
</div>

* 행 인코딩/디코딩에 `serde`를 사용합니다.
* `serde` 속성인 `skip_serializing`, `skip_deserializing`, `rename`을 지원합니다.
* HTTP 전송을 통해 [`RowBinary`](/docs/ko/reference/formats/RowBinary/RowBinary) 포맷을 사용합니다.
  * 향후 TCP를 통해 [`Native`](/docs/ko/reference/formats/Native)를 사용하도록 전환할 계획입니다.
* TLS(`native-tls` 및 `rustls-tls` 기능 사용)를 지원합니다.
* 압축 및 압축 해제(LZ4)를 지원합니다.
* 데이터 조회 및 삽입, DDL 실행, 클라이언트 측 배칭을 위한 API를 제공합니다.
* 단위 테스트를 위한 편리한 모의 객체를 제공합니다.

<div id="installation">
  ## 설치
</div>

크레이트를 사용하려면 다음을 `Cargo.toml`에 추가하십시오:

```toml theme={null}
[dependencies]
clickhouse = "0.12.2"

[dev-dependencies]
clickhouse = { version = "0.12.2", features = ["test-util"] }
```

관련 항목: [crates.io 페이지](https://crates.io/crates/clickhouse).

<div id="cargo-features">
  ## Cargo 기능
</div>

* `lz4` (기본적으로 활성화됨) — `Compression::Lz4` 및 `Compression::Lz4Hc(_)` variant를 활성화합니다. 활성화되면 `WATCH`를 제외한 모든 쿼리에 기본적으로 `Compression::Lz4`가 사용됩니다.
* `native-tls` — OpenSSL에 링크되는 `hyper-tls`를 통해 `HTTPS` 스키마의 URL을 지원합니다.
* `rustls-tls` — OpenSSL에 링크되지 않는 `hyper-rustls`를 통해 `HTTPS` 스키마의 URL을 지원합니다.
* `inserter` — `client.inserter()`를 활성화합니다.
* `test-util` — 모의 객체를 추가합니다. [예시](https://github.com/ClickHouse/clickhouse-rs/tree/main/examples/mock.rs)를 참조하십시오. `dev-dependencies`에서만 사용하십시오.
* `watch` — `client.watch` 기능을 활성화합니다. 자세한 내용은 해당 섹션을 참조하십시오.
* `uuid` — [uuid](https://docs.rs/uuid) 크레이트와 함께 사용할 수 있도록 `serde::uuid`를 추가합니다.
* `time` — [time](https://docs.rs/time) 크레이트와 함께 사용할 수 있도록 `serde::time`를 추가합니다.

<Warning>
  `HTTPS` URL을 통해 ClickHouse에 연결할 때는 `native-tls` 또는 `rustls-tls` 기능 중 하나를 활성화해야 합니다.
  둘 다 활성화된 경우 `rustls-tls` 기능이 우선 적용됩니다.
</Warning>

<div id="clickhouse-versions-compatibility">
  ## ClickHouse 버전 호환성
</div>

이 클라이언트는 LTS 및 그 이후 버전의 ClickHouse는 물론 ClickHouse Cloud와도 호환됩니다.

v22.6 이전의 ClickHouse 서버는 드물게 일부 경우에 RowBinary를 [잘못 처리합니다](https://github.com/ClickHouse/ClickHouse/issues/37420).
이 문제를 해결하려면 v0.11+를 사용하고 `wa-37420` 기능을 활성화할 수 있습니다. 참고: 이 기능은 더 최신 버전의 ClickHouse에서는 사용하지 않아야 합니다.

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

클라이언트 리포지토리의 [예시](https://github.com/ClickHouse/clickhouse-rs/blob/main/examples)를 통해 클라이언트 사용의 다양한 시나리오를 다루고자 합니다. 개요는 [예시 README](https://github.com/ClickHouse/clickhouse-rs/blob/main/examples/README.md#overview)에서 확인할 수 있습니다.

예시나 아래 문서에서 불명확하거나 누락된 내용이 있으면 언제든지 [문의해 주세요](/docs/ko/integrations/language-clients/rust/index#contact-us).

<div id="usage">
  ## 사용법
</div>

<Note>
  [ch2rs](https://github.com/ClickHouse/ch2rs) 크레이트는 ClickHouse로부터 행 타입을 생성하는 데 유용합니다.
</Note>

<div id="creating-a-client-instance">
  ### 클라이언트 인스턴스 생성
</div>

<Tip>
  기반이 되는 hyper 연결 풀을 재사용하려면, 생성한 클라이언트를 재사용하거나 복제하세요.
</Tip>

```rust theme={null}
use clickhouse::Client;

let client = Client::default()
    // should include both protocol and port
    .with_url("http://localhost:8123")
    .with_user("name")
    .with_password("123")
    .with_database("test");
```

<div id="https-or-clickhouse-cloud-connection">
  ### HTTPS 또는 ClickHouse Cloud 연결
</div>

HTTPS는 cargo 기능인 `rustls-tls` 또는 `native-tls`와 함께 사용할 수 있습니다.

그런 다음 평소와 같이 클라이언트를 생성합니다. 이 예시에서는 연결 정보를 저장하는 데 환경 변수를 사용합니다:

<Warning>
  URL에는 프로토콜과 포트가 모두 포함되어야 합니다. 예: `https://instance.clickhouse.cloud:8443`.
</Warning>

```rust theme={null}
fn read_env_var(key: &str) -> String {
    env::var(key).unwrap_or_else(|_| panic!("{key} env variable should be set"))
}

let client = Client::default()
    .with_url(read_env_var("CLICKHOUSE_URL"))
    .with_user(read_env_var("CLICKHOUSE_USER"))
    .with_password(read_env_var("CLICKHOUSE_PASSWORD"));
```

관련 항목:

* 클라이언트 리포지토리의 [ClickHouse Cloud HTTPS 예시](https://github.com/ClickHouse/clickhouse-rs/blob/main/examples/clickhouse_cloud.rs)를 참조하십시오. 이는 온프레미스 환경의 HTTPS 연결에도 적용됩니다.

<div id="selecting-rows">
  ### 행 조회
</div>

```rust theme={null}
use serde::Deserialize;
use clickhouse::Row;
use clickhouse::sql::Identifier;

#[derive(Row, Deserialize)]
struct MyRow<'a> {
    no: u32,
    name: &'a str,
}

let table_name = "some";
let mut cursor = client
    .query("SELECT ?fields FROM ? WHERE no BETWEEN ? AND ?")
    .bind(Identifier(table_name))
    .bind(500)
    .bind(504)
    .fetch::<MyRow<'_>>()?;

while let Some(row) = cursor.next().await? { .. }
```

* 플레이스홀더 `?fields`는 `no, name`(`Row`의 필드)으로 대체됩니다.
* 플레이스홀더 `?`는 이어지는 `bind()` 호출의 값으로 대체됩니다.
* 첫 번째 행 또는 모든 행을 각각 가져오려면 `fetch_one::<Row>()` 및 `fetch_all::<Row>()` 메서드를 편리하게 사용할 수 있습니다.
* 테이블 이름을 바인딩하는 데 `sql::Identifier`를 사용할 수 있습니다.

참고: 전체 응답이 스트리밍되므로 커서는 일부 행을 반환한 후에도 오류를 반환할 수 있습니다. 사용 사례에서 이런 문제가 발생하면 서버 측 응답 버퍼링을 활성화하기 위해 `query(...).with_option("wait_end_of_query", "1")`를 시도해 볼 수 있습니다. [자세한 내용](/docs/ko/concepts/features/interfaces/http#response-buffering). `buffer_size` 옵션도 유용할 수 있습니다.

<Warning>
  행을 조회할 때는 `wait_end_of_query`를 주의해서 사용하십시오. 서버 측 메모리 사용량이 증가할 수 있으며, 전체 성능도 저하될 가능성이 높습니다.
</Warning>

<div id="inserting-rows">
  ### 행 삽입
</div>

```rust theme={null}
use serde::Serialize;
use clickhouse::Row;

#[derive(Row, Serialize)]
struct MyRow {
    no: u32,
    name: String,
}

let mut insert = client.insert("some")?;
insert.write(&MyRow { no: 0, name: "foo".into() }).await?;
insert.write(&MyRow { no: 1, name: "bar".into() }).await?;
insert.end().await?;
```

* `end()`가 호출되지 않으면 `INSERT`가 취소됩니다.
* 네트워크 부하를 분산하기 위해 행은 스트림 형태로 순차적으로 전송됩니다.
* ClickHouse는 모든 행이 동일한 파티션에 속하고 행 수가 [`max_insert_block_size`](/docs/ko/reference/settings/session-settings#max_insert_block_size) 미만인 경우에만 배치를 원자적으로 삽입합니다.

<div id="async-insert-server-side-batching">
  ### Async insert (서버 측 배칭)
</div>

수신 데이터에 대해 클라이언트 측 배칭을 하지 않으려면 [ClickHouse asynchronous inserts](/docs/ko/concepts/features/operations/insert/asyncinserts)를 사용할 수 있습니다. 이렇게 하려면 `insert` 메서드에 `async_insert` 옵션만 지정하면 됩니다(또는 `Client` 인스턴스 자체에 지정하여 모든 `insert` 호출에 적용되도록 할 수도 있습니다).

```rust theme={null}
let client = Client::default()
    .with_url("http://localhost:8123")
    .with_option("async_insert", "1")
    .with_option("wait_for_async_insert", "0");
```

관련 항목:

* 클라이언트 리포지토리의 [async insert 예시](https://github.com/ClickHouse/clickhouse-rs/blob/main/examples/async_insert.rs)

<div id="inserter-feature-client-side-batching">
  ### Inserter 기능(클라이언트 측 배칭)
</div>

`inserter` Cargo 기능이 필요합니다.

```rust theme={null}
let mut inserter = client.inserter("some")?
    .with_timeouts(Some(Duration::from_secs(5)), Some(Duration::from_secs(20)))
    .with_max_bytes(50_000_000)
    .with_max_rows(750_000)
    .with_period(Some(Duration::from_secs(15)));

inserter.write(&MyRow { no: 0, name: "foo".into() })?;
inserter.write(&MyRow { no: 1, name: "bar".into() })?;
let stats = inserter.commit().await?;
if stats.rows > 0 {
    println!(
        "{} bytes, {} rows, {} transactions have been inserted",
        stats.bytes, stats.rows, stats.transactions,
    );
}

// don't forget to finalize the inserter during the application shutdown
// and commit the remaining rows. `.end()` will provide stats as well.
inserter.end().await?;
```

* `Inserter`는 임계값(`max_bytes`, `max_rows`, `period`) 중 하나에 도달하면 `commit()`에서 진행 중인 삽입을 종료합니다.
* 진행 중인 `INSERT` 종료 간격에는 `with_period_bias`로 바이어스를 적용할 수 있으며, 이를 통해 병렬 inserter로 인한 부하 급증을 방지할 수 있습니다.
* `Inserter::time_left()`는 현재 주기가 언제 끝나는지 감지하는 데 사용할 수 있습니다. 스트림에서 항목이 드물게 들어오는 경우, 한도를 확인하려면 `Inserter::commit()`을 다시 호출하십시오.
* 시간 임계값은 `inserter`의 성능을 높이기 위해 [quanta](https://docs.rs/quanta) 크레이트를 사용해 구현됩니다. `test-util`이 활성화된 경우에는 사용되지 않으므로, 사용자 정의 테스트에서는 `tokio::time::advance()`로 시간을 관리할 수 있습니다.
* `commit()` 호출 사이의 모든 행은 동일한 `INSERT` 문에 삽입됩니다.

<Warning>
  삽입을 종료하거나 마무리하려면 플러시하는 것을 잊지 마십시오:

  ```rust theme={null}
  inserter.end().await?;
  ```
</Warning>

<div id="executing-ddls">
  ### DDL 실행
</div>

단일 노드로 배포한 경우 다음과 같이 DDL을 실행하면 됩니다:

```rust theme={null}
client.query("DROP TABLE IF EXISTS some").execute().await?;
```

그러나 로드 밸런서가 있는 클러스터형 배포 환경이나 ClickHouse Cloud에서는 `wait_end_of_query` 옵션을 사용해 DDL이 모든 레플리카에 적용될 때까지 기다리는 것이 좋습니다. 다음과 같이 수행할 수 있습니다:

```rust theme={null}
client
    .query("DROP TABLE IF EXISTS some")
    .with_option("wait_end_of_query", "1")
    .execute()
    .await?;
```

<div id="clickhouse-settings">
  ### ClickHouse 설정
</div>

`with_option` 메서드로 다양한 [ClickHouse 설정](/docs/ko/reference/settings/session-settings)을 적용할 수 있습니다. 예시는 다음과 같습니다:

```rust theme={null}
let numbers = client
    .query("SELECT number FROM system.numbers")
    // This setting will be applied to this particular query only;
    // it will override the global client setting.
    .with_option("limit", "3")
    .fetch_all::<u64>()
    .await?;
```

`query`뿐만 아니라 `insert` 및 `inserter` 메서드도 같은 방식으로 동작하며, 또한 `Client` 인스턴스에서 동일한 메서드를 호출해 모든 쿼리에 적용되는 전역 설정을 지정할 수 있습니다.

<div id="query-id">
  ### 쿼리 ID
</div>

`.with_option`을 사용하면 `query_id` 옵션을 설정해 ClickHouse query log에서 쿼리를 식별할 수 있습니다.

```rust theme={null}
let numbers = client
    .query("SELECT number FROM system.numbers LIMIT 1")
    .with_option("query_id", "some-query-id")
    .fetch_all::<u64>()
    .await?;
```

`query`뿐만 아니라 `insert` 및 `inserter` 메서드에도 비슷하게 적용됩니다.

<Danger>
  `query_id`를 수동으로 설정하는 경우 고유한 값이어야 합니다. 이를 위해 UUID가 적합합니다.
</Danger>

관련 항목: 클라이언트 리포지토리의 [query\_id 예시](https://github.com/ClickHouse/clickhouse-rs/blob/main/examples/query_id.rs).

<div id="session-id">
  ### 세션 ID
</div>

`query_id`와 마찬가지로 `session_id`를 설정하면 동일한 session에서 SQL 문을 실행할 수 있습니다. `session_id`는 클라이언트 수준에서 전역으로 설정하거나 각 `query`, `insert` 또는 `inserter` 호출별로 설정할 수 있습니다.

```rust theme={null}
let client = Client::default()
    .with_url("http://localhost:8123")
    .with_option("session_id", "my-session");
```

<Danger>
  클러스터형 배포 환경에서는 "sticky sessions"가 없기 때문에, 이 기능을 제대로 활용하려면 *특정 클러스터 노드*에 연결되어 있어야 합니다. 예를 들어, 라운드 로빈 로드 밸런서는 후속 요청이 동일한 ClickHouse 노드에서 처리된다고 보장하지 않습니다.
</Danger>

관련 항목: 클라이언트 리포지토리의 [session\_id 예시](https://github.com/ClickHouse/clickhouse-rs/blob/main/examples/session_id.rs).

<div id="custom-http-headers">
  ### 사용자 지정 HTTP 헤더
</div>

프록시 인증을 사용하거나 사용자 지정 헤더를 전달해야 하는 경우, 다음과 같이 할 수 있습니다:

```rust theme={null}
let client = Client::default()
    .with_url("http://localhost:8123")
    .with_header("X-My-Header", "hello");
```

관련 항목: 클라이언트 리포지토리의 [사용자 지정 HTTP 헤더 예시](https://github.com/ClickHouse/clickhouse-rs/blob/main/examples/custom_http_headers.rs)를 참조하십시오.

<div id="custom-http-client">
  ### 사용자 지정 HTTP 클라이언트
</div>

이 기능은 내부 HTTP 연결 풀 설정을 조정할 때 유용할 수 있습니다.

```rust theme={null}
use hyper_util::client::legacy::connect::HttpConnector;
use hyper_util::client::legacy::Client as HyperClient;
use hyper_util::rt::TokioExecutor;

let connector = HttpConnector::new(); // or HttpsConnectorBuilder
let hyper_client = HyperClient::builder(TokioExecutor::new())
    // For how long keep a particular idle socket alive on the client side (in milliseconds).
    // It is supposed to be a fair bit less that the ClickHouse server KeepAlive timeout,
    // which was by default 3 seconds for pre-23.11 versions, and 10 seconds after that.
    .pool_idle_timeout(Duration::from_millis(2_500))
    // Sets the maximum idle Keep-Alive connections allowed in the pool.
    .pool_max_idle_per_host(4)
    .build(connector);

let client = Client::with_http_client(hyper_client).with_url("http://localhost:8123");
```

<Warning>
  이 예시는 기존 Hyper API를 사용하므로, 향후 변경될 수 있습니다.
</Warning>

관련 항목: 클라이언트 리포지토리의 [사용자 지정 HTTP 클라이언트 예시](https://github.com/ClickHouse/clickhouse-rs/blob/main/examples/custom_http_client.rs).

<div id="data-types">
  ## 데이터 타입
</div>

<Info>
  추가 예시는 다음을 참조하십시오:

  * [더 간단한 ClickHouse 데이터 타입](https://github.com/ClickHouse/clickhouse-rs/blob/main/examples/data_types_derive_simple.rs)
  * [컨테이너형 ClickHouse 데이터 타입](https://github.com/ClickHouse/clickhouse-rs/blob/main/examples/data_types_derive_containers.rs)
</Info>

* `(U)Int(8|16|32|64|128)`는 해당 `(u|i)(8|16|32|64|128)` 타입 또는 이를 감싼 newtype에 매핑되거나, 그 반대로도 매핑될 수 있습니다.
* `(U)Int256`은 직접 지원되지 않지만, [이를 위한 우회 방법](https://github.com/ClickHouse/clickhouse-rs/issues/48)이 있습니다.
* `Float(32|64)`는 해당 `f(32|64)` 또는 이를 감싼 newtype에 매핑되거나, 그 반대로도 매핑될 수 있습니다.
* `Decimal(32|64|128)`는 해당 `i(32|64|128)` 또는 이를 감싼 newtype에 매핑되거나, 그 반대로도 매핑될 수 있습니다. 부호 있는 고정소수점 수를 구현하려면 [`fixnum`](https://github.com/loyd/fixnum) 또는 다른 구현체를 사용하는 편이 더 편리합니다.
* `Boolean`은 `bool` 또는 이를 감싼 newtype에 매핑되거나, 그 반대로도 매핑될 수 있습니다.
* `String`은 모든 문자열 또는 바이트 타입(예: `&str`, `&[u8]`, `String`, `Vec<u8>`, [`SmartString`](https://docs.rs/smartstring/latest/smartstring/struct.SmartString.html))에 매핑되거나, 그 반대로도 매핑될 수 있습니다. newtype도 지원됩니다. 바이트를 저장할 때는 [`serde_bytes`](https://docs.rs/serde_bytes/latest/serde_bytes/)가 더 효율적이므로 사용을 고려하십시오.

```rust theme={null}
#[derive(Row, Debug, Serialize, Deserialize)]
struct MyRow<'a> {
    str: &'a str,
    string: String,
    #[serde(with = "serde_bytes")]
    bytes: Vec<u8>,
    #[serde(with = "serde_bytes")]
    byte_slice: &'a [u8],
}
```

* `FixedString(N)`은(는) 바이트 배열로 지원되며, 예를 들어 `[u8; N]`와 같습니다.

```rust theme={null}
#[derive(Row, Debug, Serialize, Deserialize)]
struct MyRow {
    fixed_str: [u8; 16], // FixedString(16)
}
```

* `Enum(8|16)`은 [`serde_repr`](https://docs.rs/serde_repr/latest/serde_repr/)를 통해 지원됩니다.

```rust theme={null}
use serde_repr::{Deserialize_repr, Serialize_repr};

#[derive(Row, Serialize, Deserialize)]
struct MyRow {
    level: Level,
}

#[derive(Debug, Serialize_repr, Deserialize_repr)]
#[repr(u8)]
enum Level {
    Debug = 1,
    Info = 2,
    Warn = 3,
    Error = 4,
}
```

* `UUID`는 `serde::uuid`를 사용해 [`uuid::Uuid`](https://docs.rs/uuid/latest/uuid/struct.Uuid.html)로 또는 그 반대로 매핑됩니다. `uuid` 기능이 필요합니다.

```rust theme={null}
#[derive(Row, Serialize, Deserialize)]
struct MyRow {
    #[serde(with = "clickhouse::serde::uuid")]
    uuid: uuid::Uuid,
}
```

* `IPv6`는 [`std::net::Ipv6Addr`](https://doc.rust-lang.org/stable/std/net/struct.Ipv6Addr.html)와 상호 매핑됩니다.
* `IPv4`는 `serde::ipv4`를 사용해 [`std::net::Ipv4Addr`](https://doc.rust-lang.org/stable/std/net/struct.Ipv4Addr.html)와 상호 매핑됩니다.

```rust theme={null}
#[derive(Row, Serialize, Deserialize)]
struct MyRow {
    #[serde(with = "clickhouse::serde::ipv4")]
    ipv4: std::net::Ipv4Addr,
}
```

* `Date`는 `u16` 또는 이를 감싼 newtype과 상호 매핑되며, `1970-01-01` 이후 경과한 일수를 나타냅니다. 또한 [`time::Date`](https://docs.rs/time/latest/time/struct.Date.html)는 `serde::time::date`를 통해 지원되며, 이를 사용하려면 `time` 기능이 필요합니다.

```rust theme={null}
#[derive(Row, Serialize, Deserialize)]
struct MyRow {
    days: u16,
    #[serde(with = "clickhouse::serde::time::date")]
    date: Date,
}
```

* `Date32`는 `i32` 또는 이를 감싼 newtype로/에서 매핑되며, `1970-01-01` 이후 경과한 일수를 나타냅니다. 또한 `time` 기능이 필요하며, `serde::time::date32`를 사용하면 [`time::Date`](https://docs.rs/time/latest/time/struct.Date.html)도 지원합니다.

```rust theme={null}
#[derive(Row, Serialize, Deserialize)]
struct MyRow {
    days: i32,
    #[serde(with = "clickhouse::serde::time::date32")]
    date: Date,
}
```

* `DateTime`은 `u32` 또는 이를 래핑한 newtype에 매핑되거나 그로부터 매핑되며, UNIX epoch 이후 경과한 초 수를 나타냅니다. 또한 [`time::OffsetDateTime`](https://docs.rs/time/latest/time/struct.OffsetDateTime.html)도 `serde::time::datetime`을 사용해 지원되며, 이 경우 `time` 기능이 필요합니다.

```rust theme={null}
#[derive(Row, Serialize, Deserialize)]
struct MyRow {
    ts: u32,
    #[serde(with = "clickhouse::serde::time::datetime")]
    dt: OffsetDateTime,
}
```

* `DateTime64(_)`는 `i32` 또는 이를 감싼 newtype에 매핑되거나 그로부터 매핑되며, Unix epoch 이후 경과한 시간을 나타냅니다. 또한 [`time::OffsetDateTime`](https://docs.rs/time/latest/time/struct.OffsetDateTime.html)도 `serde::time::datetime64::*`를 사용해 지원되며, 이 경우 `time` 기능이 필요합니다.

```rust theme={null}
#[derive(Row, Serialize, Deserialize)]
struct MyRow {
    ts: i64, // elapsed s/us/ms/ns depending on `DateTime64(X)`
    #[serde(with = "clickhouse::serde::time::datetime64::secs")]
    dt64s: OffsetDateTime,  // `DateTime64(0)`
    #[serde(with = "clickhouse::serde::time::datetime64::millis")]
    dt64ms: OffsetDateTime, // `DateTime64(3)`
    #[serde(with = "clickhouse::serde::time::datetime64::micros")]
    dt64us: OffsetDateTime, // `DateTime64(6)`
    #[serde(with = "clickhouse::serde::time::datetime64::nanos")]
    dt64ns: OffsetDateTime, // `DateTime64(9)`
}
```

* `Tuple(A, B, ...)`는 `(A, B, ...)` 또는 이를 감싼 `newtype`으로/에서 매핑됩니다.
* `Array(_)`는 모든 슬라이스로/에서 매핑됩니다. 예: `Vec<_>`, `&[_]`. 사용자 정의 타입도 지원됩니다.
* `Map(K, V)`는 `Array((K, V))`처럼 동작합니다.
* `LowCardinality(_)`는 별도 처리 없이 지원됩니다.
* `Nullable(_)`는 `Option<_>`으로/에서 매핑됩니다. `clickhouse::serde::*` helpers를 사용할 때는 `::option`을 추가하십시오.

```rust theme={null}
#[derive(Row, Serialize, Deserialize)]
struct MyRow {
    #[serde(with = "clickhouse::serde::ipv4::option")]
    ipv4_opt: Option<Ipv4Addr>,
}
```

* `Nested`는 이름을 변경한 여러 배열을 지정하는 방식으로 지원됩니다.

```rust theme={null}
// CREATE TABLE test(items Nested(name String, count UInt32))
#[derive(Row, Serialize, Deserialize)]
struct MyRow {
    #[serde(rename = "items.name")]
    items_name: Vec<String>,
    #[serde(rename = "items.count")]
    items_count: Vec<u32>,
}
```

* `Geo` 타입이 지원됩니다. `Point`는 튜플 `(f64, f64)`처럼 동작하며, 나머지 타입은 모두 `Point`의 슬라이스입니다.

```rust theme={null}
type Point = (f64, f64);
type Ring = Vec<Point>;
type Polygon = Vec<Ring>;
type MultiPolygon = Vec<Polygon>;
type LineString = Vec<Point>;
type MultiLineString = Vec<LineString>;

#[derive(Row, Serialize, Deserialize)]
struct MyRow {
    point: Point,
    ring: Ring,
    polygon: Polygon,
    multi_polygon: MultiPolygon,
    line_string: LineString,
    multi_line_string: MultiLineString,
}
```

* `Variant`, `Dynamic`, (새로운) `JSON` 데이터 타입은 아직 지원되지 않습니다.

<div id="mocking">
  ## 모킹
</div>

이 크레이트는 CH 서버를 모킹하고 DDL, `SELECT`, `INSERT`, `WATCH` 쿼리를 테스트하기 위한 유틸리티를 제공합니다. 이 기능은 `test-util` 기능을 활성화하면 사용할 수 있습니다. **반드시** 개발 의존성으로만 사용하세요.

[예시](https://github.com/ClickHouse/clickhouse-rs/tree/main/examples/mock.rs)를 참조하세요.

<div id="troubleshooting">
  ## 문제 해결
</div>

<div id="cannot_read_all_data">
  ### CANNOT\_READ\_ALL\_DATA
</div>

`CANNOT_READ_ALL_DATA` 오류의 가장 일반적인 원인은 애플리케이션 측의 행 정의가 ClickHouse의 행 정의와 일치한다는 것입니다.

다음 테이블을 살펴보십시오:

```sql theme={null}
CREATE OR REPLACE TABLE event_log (id UInt32)
ENGINE = MergeTree
ORDER BY timestamp
```

그런 다음 애플리케이션 측에서 `EventLog`가 서로 다른 타입으로 정의된 경우(예:):

```rust theme={null}
#[derive(Debug, Serialize, Deserialize, Row)]
struct EventLog {
    id: String, // <- should be u32 instead!
}
```

데이터 삽입 시 다음 오류가 발생할 수 있습니다:

```response theme={null}
Error: BadResponse("Code: 33. DB::Exception: Cannot read all data. Bytes read: 5. Bytes expected: 23.: (at row 1)\n: While executing BinaryRowInputFormat. (CANNOT_READ_ALL_DATA)")
```

이 예시에서는 `EventLog` 구조체를 올바르게 정의하면 이 문제가 해결됩니다:

```rust theme={null}
#[derive(Debug, Serialize, Deserialize, Row)]
struct EventLog {
    id: u32
}
```

<div id="known-limitations">
  ## 알려진 제한 사항
</div>

* `Variant`, `Dynamic`, (new) `JSON` 데이터 타입은 아직 지원되지 않습니다.
* 서버 측 매개변수 바인딩은 아직 지원되지 않습니다. 관련 진행 상황은 [this issue](https://github.com/ClickHouse/clickhouse-rs/issues/142)에서 추적하고 있습니다.

<div id="contact-us">
  ## 문의하기
</div>

질문이 있거나 도움이 필요하시면 [Community Slack](https://clickhouse.com/slack) 또는 [GitHub 이슈](https://github.com/ClickHouse/clickhouse-rs/issues)를 통해 언제든지 문의하세요.