Klickhouse

https://docs.rs/klickhouse/0.15.3/klickhouse/
Admin
Klickhouse is a pure Rust SDK for working with Clickhouse with the native protocol in async...
Tokens:35,067
Snippets:339
Trust Score:9.1
Update:1 month ago
Show doc for...
Tokens:
Raw
### FromIterator Implementation Examples

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/type.Result.html

Examples showing how FromIterator collects Results, stopping at the first Err encountered.

```rust
let v = vec![1, 2];
let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32|
    x.checked_add(1).ok_or("Overflow!")
).collect();
assert_eq!(res, Ok(vec![2, 3]));
```

```rust
let v = vec![1, 2, 0];
let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32|
    x.checked_sub(1).ok_or("Underflow!")
).collect();
assert_eq!(res, Err("Underflow!"));
```

```rust
let v = vec![3, 2, 1, 10];
let mut shared = 0;
let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32| {
    shared += x;
    x.checked_sub(2).ok_or("Underflow!")
}).collect();
assert_eq!(res, Err("Underflow!"));
assert_eq!(shared, 6);
```

--------------------------------

### Run Integration Tests

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/index.html

Commands to start a Clickhouse Docker container and execute integration tests using cargo nextest.

```bash
$ docker run  --rm --name clickhouse -p 19000:9000 --ulimit nofile=262144:262144 clickhouse
$ export KLICKHOUSE_TEST_ADDR=127.0.0.1:19000
$ # export KLICKHOUSE_TEST_USER=default
$ # export KLICKHOUSE_TEST_PASSWORD=default
$ # export KLICKHOUSE_TEST_DATABASE=default
$ cargo nextest run
```

--------------------------------

### IntoIterator Implementation Example

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/type.Result.html

Demonstrates converting a Result into an iterator that yields the contained value if Ok.

```rust
let x: Result<u32, &str> = Ok(5);
let v: Vec<u32> = x.into_iter().collect();
assert_eq!(v, [5]);

let x: Result<u32, &str> = Err("nothing!");
```

--------------------------------

### Get Octets

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.Ipv6.html

Returns the sixteen bytes of the IPv6 address.

```rust
use std::net::Ipv6Addr;

assert_eq!(Ipv6Addr::new(0xff00, 0, 0, 0, 0, 0, 0, 0).octets(),
           [0xff, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]);
```

--------------------------------

### Collect Result into Vector

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/type.Result.html

Example of collecting an iterator into a vector.

```rust
let v: Vec<u32> = x.into_iter().collect();
assert_eq!(v, []);
```

--------------------------------

### Unwrap Unchecked Examples

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/type.Result.html

Demonstrates the use of unwrap_unchecked to retrieve values without safety checks. Note that calling this on an Err variant is undefined behavior.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(unsafe { x.unwrap_unchecked() }, 2);
```

```rust
let x: Result<u32, &str> = Err("emergency failure");
unsafe { x.unwrap_unchecked() }; // Undefined behavior!
```

--------------------------------

### Get UUID Version

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.Uuid.html

Returns the version of the UUID as an Option. Returns None if the version is not recognized.

```rust
let my_uuid = Uuid::parse_str("02f09a3f-1624-3b1d-8409-44eff7708208")?;

assert_eq!(Some(Version::Md5), my_uuid.get_version());
```

--------------------------------

### entry

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.IndexMap.html

Get the given key’s corresponding entry in the map for insertion and/or in-place manipulation.

```APIDOC
## pub fn entry(&mut self, key: K) -> Entry<'_, K, V>

### Description
Get the given key’s corresponding entry in the map for insertion and/or in-place manipulation.

### Parameters
- **key** (K) - The key to retrieve the entry for.
```

--------------------------------

### Get Address Octets

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.Ipv4.html

Retrieve the four eight-bit integers representing the IPv4 address.

```rust
use std::net::Ipv4Addr;

let addr = Ipv4Addr::new(127, 0, 0, 1);
assert_eq!(addr.octets(), [127, 0, 0, 1]);
```

--------------------------------

### Get Address Octets as Slice

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.Ipv4.html

Retrieve the address octets as a slice. Requires the nightly-only ip_as_octets feature.

```rust
#![feature(ip_as_octets)]

use std::net::Ipv4Addr;

let addr = Ipv4Addr::new(127, 0, 0, 1);
assert_eq!(addr.as_octets(), &[127, 0, 0, 1]);
```

--------------------------------

### Get UUID Version Number

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.Uuid.html

Returns the version number as a usize, serving as a future-proof alternative to get_version.

```rust
let my_uuid = Uuid::parse_str("02f09a3f-1624-3b1d-8409-44eff7708208")?;

assert_eq!(3, my_uuid.get_version_num());
```

--------------------------------

### Unwrap Err Unchecked Examples

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/type.Result.html

Demonstrates the use of unwrap_err_unchecked to retrieve error values without safety checks. Note that calling this on an Ok variant is undefined behavior.

```rust
let x: Result<u32, &str> = Ok(2);
unsafe { x.unwrap_err_unchecked() }; // Undefined behavior!
```

```rust
let x: Result<u32, &str> = Err("emergency failure");
assert_eq!(unsafe { x.unwrap_err_unchecked() }, "emergency failure");
```

--------------------------------

### Create UUID from little-endian bytes

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.Uuid.html

Creates a UUID using bytes in little-endian order, compatible with Microsoft's mixed-endian GUID format.

```rust
let bytes = [
    0xa1, 0xa2, 0xa3, 0xa4,
    0xb1, 0xb2,
    0xc1, 0xc2,
    0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8,
];

let uuid = Uuid::from_bytes_le(bytes);

assert_eq!(
    "a4a3a2a1-b2b1-c2c1-d1d2-d3d4d5d6d7d8",
    uuid.hyphenated().to_string(),
);
```

--------------------------------

### ConnectionManager::with_prequel

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.ConnectionManager.html

Configures the ConnectionManager with a prequel string.

```APIDOC
## pub fn with_prequel(self, prequel: impl Into<String>) -> Self

### Description
Sets a prequel string for the connection manager and returns the modified instance.

### Parameters
- **prequel** (impl Into<String>) - Required - The prequel string to be used.
```

--------------------------------

### ClickhouseLock::new

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.ClickhouseLock.html

Initializes a new instance of the ClickhouseLock.

```APIDOC
## pub fn new(client: Client, name: impl AsRef<str>) -> Self

### Description
Initializes a new lock instance with the provided client and lock name.

### Parameters
- **client** (Client) - The Clickhouse client instance.
- **name** (impl AsRef<str>) - The identifier for the lock.
```

--------------------------------

### Get signum of bf16

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.bf16.html

Returns the sign of the number as 1.0, -1.0, or NaN.

```rust

let f = bf16::from_f32(3.5_f32);

assert_eq!(f.signum(), bf16::from_f32(1.0));
assert_eq!(bf16::NEG_INFINITY.signum(), bf16::from_f32(-1.0));

assert!(bf16::NAN.signum().is_nan());
```

--------------------------------

### Get UUID as 128-bit Integer

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.Uuid.html

Packs the bytes of the UUID directly into a u128 value.

```rust
let uuid = Uuid::parse_str("a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8")?;

assert_eq!(
    uuid.as_u128(),
    0xa1a2a3a4b1b2c1c2d1d2d3d4d5d6d7d8,
);
```

--------------------------------

### ConnectionManager::new

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.ConnectionManager.html

Creates a new instance of ConnectionManager.

```APIDOC
## pub async fn new<A: ToSocketAddrs>(destination: A, options: ClientOptions) -> Result<Self>

### Description
Creates a new ConnectionManager instance that connects to the specified destination with the provided client options.

### Parameters
- **destination** (A: ToSocketAddrs) - Required - The address to connect to.
- **options** (ClientOptions) - Required - Configuration options for the client.
```

--------------------------------

### Define ClientOptions struct

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.ClientOptions.html

The structure definition for configuring a Clickhouse connection.

```rust
pub struct ClientOptions {
    pub username: String,
    pub password: String,
    pub default_database: String,
    pub tcp_nodelay: bool,
}
```

--------------------------------

### QueryBuilder::new

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.QueryBuilder.html

Creates a new instance of QueryBuilder with the provided query string.

```APIDOC
## pub fn new(query: &'a str) -> Self

### Description
Initializes a new QueryBuilder instance with the specified query string.

### Parameters
- **query** (&'a str) - Required - The SQL query string to be built.
```

--------------------------------

### RowIndex Trait Definition

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/trait.RowIndex.html

The core trait definition requiring the implementation of the get method.

```rust
pub trait RowIndex {
    // Required method
    fn get<'a, I: IntoIterator<Item = &'a str>>(
        &self,
        columns: I,
    ) -> Option<usize>;
}
```

--------------------------------

### Serialize bf16 as string with Serde

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.bf16.html

Uses the serialize_as_string adapter within a Serde serialize_with attribute to output bf16 as a string.

```rust
use serde::{Serialize, Deserialize};
use half::bf16;

#[derive(Serialize, Deserialize)]
struct MyStruct {
    #[serde(serialize_with = "bf16::serialize_as_string")]
    value: bf16 // Will be serialized as a string instead of u16
}
```

--------------------------------

### serialize_as_string

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.bf16.html

Alternate serialize adapter for serializing bf16 as a string.

```APIDOC
## pub fn serialize_as_string<S>(&self, serializer: S) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>

### Description
An alternate serialize implementation that serializes the `bf16` value as a string. Designed for use with `serde`'s `serialize_with` attribute.
```

--------------------------------

### QueryBuilder::args

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.QueryBuilder.html

Adds multiple arguments to the query.

```APIDOC
## pub fn args<A: ToSql>(self, args: impl IntoIterator<Item = A>) -> Self

### Description
Appends a collection of arguments to the query builder.

### Parameters
- **args** (impl IntoIterator<Item = A>) - Required - An iterator of items that implement ToSql.
```

--------------------------------

### Get UUID Fields

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.Uuid.html

Returns the four field values of the UUID, which can be used to reconstruct the original UUID.

```rust
let uuid = Uuid::nil();

assert_eq!(uuid.as_fields(), (0, 0, 0, &[0u8; 8]));

let uuid = Uuid::parse_str("a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8")?;

assert_eq!(
    uuid.as_fields(),
    (
        0xa1a2a3a4,
        0xb1b2,
        0xc1c2,
        &[0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8],
    )
);
```

--------------------------------

### serialize_as_f32

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.bf16.html

Alternate serialize adapter for serializing bf16 as an f32 value.

```APIDOC
## pub fn serialize_as_f32<S>(&self, serializer: S) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>

### Description
An alternate serialize implementation that serializes the `bf16` value as an `f32` instead of the default `u16` newtype. Designed for use with `serde`'s `serialize_with` attribute.
```

--------------------------------

### Create IndexMap from Array

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.IndexMap.html

Demonstrates initializing an IndexMap from an array of tuples using the From trait.

```rust
use indexmap::IndexMap;

let map1 = IndexMap::from([(1, 2), (3, 4)]);
let map2: IndexMap<_, _> = [(1, 2), (3, 4)].into();
assert_eq!(map1, map2);
```

--------------------------------

### Get UUID Variant

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.Uuid.html

Reads the variant byte of the UUID structure without validating the entire structure.

```rust
let my_uuid = Uuid::parse_str("02f09a3f-1624-3b1d-8409-44eff7708208")?;

assert_eq!(Variant::RFC4122, my_uuid.get_variant());
```

--------------------------------

### is_documentation

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.Ipv6.html

Checks if the IPv6 address is reserved for documentation.

```APIDOC
## pub fn is_documentation(&self) -> bool

### Description
Returns true if this is an address reserved for documentation (2001:db8::/32 and 3fff::/20), as defined by IETF RFC 3849 and IETF RFC 9637.
```

--------------------------------

### Get disjoint mutable indices

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.IndexMap.html

Retrieves multiple mutable references to values by their indices, ensuring all indices are unique.

```rust
let mut map = indexmap::IndexMap::from([(1, 'a'), (3, 'b'), (2, 'c')]);
assert_eq!(map.get_disjoint_indices_mut([2, 0]), Ok([(&2, &mut 'c'), (&1, &mut 'a')]));
```

--------------------------------

### Serialize bf16 as f32 with Serde

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.bf16.html

Uses the serialize_as_f32 adapter within a Serde serialize_with attribute to output bf16 as an f32.

```rust
use serde::{Serialize, Deserialize};
use half::bf16;

#[derive(Serialize, Deserialize)]
struct MyStruct {
    #[serde(serialize_with = "bf16::serialize_as_f32")]
    value: bf16 // Will be serialized as f32 instead of u16
}
```

--------------------------------

### Mutable Indexing with IndexMap

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.IndexMap.html

Demonstrates how to access and modify values in an IndexMap using mutable indexing. Note that index syntax cannot be used to insert new values and will panic if the index is out of bounds.

```rust
use indexmap::IndexMap;

let mut map = IndexMap::new();
for word in "Lorem ipsum dolor sit amet".split_whitespace() {
    map.insert(word.to_lowercase(), word.to_string());
}
let lorem = &mut map[0];
assert_eq!(lorem, "Lorem");
lorem.retain(char::is_lowercase);
assert_eq!(map["lorem"], "orem");
```

```rust
use indexmap::IndexMap;

let mut map = IndexMap::new();
map.insert("foo", 1);
map[10] = 1; // panics!
```

--------------------------------

### Get UUID Fields in Little-Endian

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.Uuid.html

Returns the four field values of the UUID with integer fields converted to little-endian order.

```rust
use uuid::Uuid;

let uuid = Uuid::parse_str("a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8")?;

assert_eq!(
    uuid.to_fields_le(),
    (
        0xa4a3a2a1,
        0xb2b1,
        0xc2c1,
        &[0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8],
    )
);
```

--------------------------------

### Format UUID using adapter methods

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.Uuid.html

Uses adapter methods to specify alternative formatting for a UUID.

```rust
let my_uuid = Uuid::parse_str("a1a2a3a4b1b2c1c2d1d2d3d4d5d6d7d8")?;

assert_eq!(
    "urn:uuid:a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8",
    my_uuid.urn().to_string(),
);
```

--------------------------------

### Client::connect

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.Client.html

Connects to a specific socket address over plaintext TCP for Clickhouse.

```APIDOC
## pub async fn connect<A: ToSocketAddrs>(destination: A, options: ClientOptions) -> Result<Self>

### Description
Connects to a specific socket address over plaintext TCP for Clickhouse.

### Parameters
- **destination** (A: ToSocketAddrs) - Required - The socket address to connect to.
- **options** (ClientOptions) - Required - Configuration options for the client.
```

--------------------------------

### Convert UUID to little-endian bytes

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.Uuid.html

Returns the UUID bytes in little-endian order, compatible with Microsoft's mixed endian GUID format.

```rust
use uuid::Uuid;

let uuid = Uuid::parse_str("a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8")?;

assert_eq!(
    uuid.to_bytes_le(),
    ([
        0xa4, 0xa3, 0xa2, 0xa1, 0xb2, 0xb1, 0xc2, 0xc1, 0xd1, 0xd2,
        0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8
    ])
);
```

--------------------------------

### Insert before index in IndexMap

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.IndexMap.html

Demonstrates inserting or moving keys before a specific index, where existing keys are updated and moved accordingly.

```rust
use indexmap::IndexMap;
let mut map: IndexMap<char, ()> = ('a'..='z').map(|c| (c, ())).collect();

// The new key '*' goes exactly at the given index.
assert_eq!(map.get_index_of(&'*'), None);
assert_eq!(map.insert_before(10, '*', ()), (10, None));
assert_eq!(map.get_index_of(&'*'), Some(10));

// Moving the key 'a' up will shift others down, so this moves *before* 10 to index 9.
assert_eq!(map.insert_before(10, 'a', ()), (9, Some(())));
assert_eq!(map.get_index_of(&'a'), Some(9));
assert_eq!(map.get_index_of(&'*'), Some(10));

// Moving the key 'z' down will shift others up, so this moves to exactly 10.
assert_eq!(map.insert_before(10, 'z', ()), (10, Some(())));
assert_eq!(map.get_index_of(&'z'), Some(10));
assert_eq!(map.get_index_of(&'*'), Some(11));

// Moving or inserting before the endpoint is also valid.
assert_eq!(map.len(), 27);
assert_eq!(map.insert_before(map.len(), '*', ()), (26, Some(())));
assert_eq!(map.get_index_of(&'*'), Some(26));
assert_eq!(map.insert_before(map.len(), '+', ()), (27, None));
assert_eq!(map.get_index_of(&'+'), Some(27));
assert_eq!(map.len(), 28);
```

--------------------------------

### Access IndexMap Values

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.IndexMap.html

Shows how to access values using the indexing operator and notes that missing keys will cause a panic.

```rust
use indexmap::IndexMap;

let mut map = IndexMap::new();
for word in "Lorem ipsum dolor sit amet".split_whitespace() {
    map.insert(word.to_lowercase(), word.to_uppercase());
}
assert_eq!(map["lorem"], "LOREM");
assert_eq!(map["ipsum"], "IPSUM");
```

```rust
use indexmap::IndexMap;

let mut map = IndexMap::new();
map.insert("foo", 1);
println!("{:?}", map["bar"]); // panics!
```

--------------------------------

### Get UUID as Little-Endian 128-bit Integer

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.Uuid.html

Returns the UUID as a 128-bit integer with bytes reversed. Note that this differs from to_fields_le as it reverses the entire UUID.

```rust
let uuid = Uuid::parse_str("a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8")?;

assert_eq!(
    uuid.to_u128_le(),
    0xd8d7d6d5d4d3d2d1c2c1b2b1a4a3a2a1,
);
```

--------------------------------

### Floating Point Conversion Methods

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.bf16.html

Methods for converting bf16 to f32 or f64 types.

```APIDOC
## Floating Point Conversion Methods

- `to_f32(self) -> f32`: Converts a `bf16` value into an `f32` value.
- `to_f32_const(self) -> f32`: Const-compatible version of `to_f32`.
- `to_f64(self) -> f64`: Converts a `bf16` value into an `f64` value.
- `to_f64_const(self) -> f64`: Const-compatible version of `to_f64`.
```

--------------------------------

### Verify default hyphenated formatting

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.Uuid.html

Demonstrates that the default Display implementation for a UUID uses the hyphenated format.

```rust
let my_uuid = Uuid::parse_str("a1a2a3a4b1b2c1c2d1d2d3d4d5d6d7d8")?;

assert_eq!(
    "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8",
    my_uuid.to_string(),
);
```

--------------------------------

### pub fn expect(self, msg: &str) -> T

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/type.Result.html

Returns the contained Ok value, or panics with the provided message if the result is Err.

```APIDOC
## pub fn expect(self, msg: &str) -> T

### Description
Returns the contained `Ok` value, consuming the `self` value. Panics if the value is an `Err`, with a panic message including the passed message, and the content of the `Err`.
```

--------------------------------

### Client::query

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.Client.html

Runs a query against Clickhouse, returning a stream of deserialized rows.

```APIDOC
## pub async fn query<T: Row, I: TryInto<ParsedQuery, Error = KlickhouseError>>(&self, query: I) -> Result<impl Stream<Item = Result<T>> + use<T, I>>

### Description
Runs a query against Clickhouse, returning a stream of deserialized rows. Note that no rows are returned until Clickhouse sends a full block.

### Parameters
- **query** (I: TryInto<ParsedQuery>) - Required - The query to execute.
```

--------------------------------

### Provide a default value with unwrap_or

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/type.Result.html

Returns the contained Ok value or a provided default. Arguments are eagerly evaluated.

```rust
let default = 2;
let x: Result<u32, &str> = Ok(9);
assert_eq!(x.unwrap_or(default), 9);

let x: Result<u32, &str> = Err("error");
assert_eq!(x.unwrap_or(default), default);
```

--------------------------------

### Client::execute

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.Client.html

Executes a query and discards all returned blocks.

```APIDOC
## pub async fn execute(&self, query: impl TryInto<ParsedQuery, Error = KlickhouseError>) -> Result<()>

### Description
Executes a query and discards all returned blocks. It waits until the first block returns from the server to check for errors.

### Parameters
- **query** (impl TryInto<ParsedQuery>) - Required - The query to execute.
```

--------------------------------

### Unwrap Result or Default

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/type.Result.html

Returns the Ok value or the default value for the type if the result is Err.

```rust
let good_year_from_input = "1909";
let bad_year_from_input = "190blarg";
let good_year = good_year_from_input.parse().unwrap_or_default();
let bad_year = bad_year_from_input.parse().unwrap_or_default();

assert_eq!(1909, good_year);
assert_eq!(0, bad_year);
```

--------------------------------

### Check for Unspecified Address

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.Ipv6.html

Verify if an address is the unspecified '::' address.

```rust
use std::net::Ipv6Addr;

assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff).is_unspecified(), false);
assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 0).is_unspecified(), true);
```

--------------------------------

### Check if an IPv6 address is reserved for benchmarking

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.Ipv6.html

Checks if the address is within the range reserved for benchmarking. Requires the nightly-only experimental `ip` feature.

```rust
#![feature(ip)]

use std::net::Ipv6Addr;

assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc613, 0x0).is_benchmarking(), false);
assert_eq!(Ipv6Addr::new(0x2001, 0x2, 0, 0, 0, 0, 0, 0).is_benchmarking(), true);
```

--------------------------------

### Client struct definition

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.Client.html

The internal structure of the Client handle.

```rust
pub struct Client { /* private fields */ }
```

--------------------------------

### Count character frequency with IndexMap

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.IndexMap.html

Demonstrates using IndexMap to track character occurrences in a string while maintaining insertion order.

```rust
use indexmap::IndexMap;

// count the frequency of each letter in a sentence.
let mut letters = IndexMap::new();
for ch in "a short treatise on fungi".chars() {
    *letters.entry(ch).or_insert(0) += 1;
}

assert_eq!(letters[&'s'], 2);
assert_eq!(letters[&'t'], 3);
assert_eq!(letters[&'u'], 1);
assert_eq!(letters.get(&'y'), None);
```

--------------------------------

### try_from_utc

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.DynDateTime64.html

Creates a new DynDateTime64 instance from a UTC DateTime with a specified precision.

```APIDOC
## pub fn try_from_utc(other: DateTime<Utc>, precision: usize) -> Result<Self, TryFromIntError>

### Description
Creates a new DynDateTime64 instance from a UTC DateTime with a specified precision.

### Parameters
- **other** (DateTime<Utc>) - The UTC date-time value.
- **precision** (usize) - The precision for the DateTime64 type.

### Returns
- **Result<Self, TryFromIntError>** - Returns the new DynDateTime64 instance or a conversion error.
```

--------------------------------

### fn from_sql

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/trait.FromSql.html

Converts a raw Clickhouse SQL value into the implementing type.

```APIDOC
## fn from_sql(type_: &Type, value: Value) -> Result<Self>

### Description
Converts a raw Clickhouse SQL value into the implementing type. This method is required for any type that needs to be deserialized from a Clickhouse query result.

### Parameters
- **type_** (&Type) - The Clickhouse type definition associated with the value.
- **value** (Value) - The raw value retrieved from the database.

### Returns
- **Result<Self>** - Returns the converted type on success, or an error if the conversion fails.
```

--------------------------------

### Check if Link-Local

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.Ipv4.html

Verify if the address is in the 169.254.0.0/16 link-local range.

```rust
use std::net::Ipv4Addr;

assert_eq!(Ipv4Addr::new(169, 254, 0, 0).is_link_local(), true);
assert_eq!(Ipv4Addr::new(169, 254, 10, 65).is_link_local(), true);
assert_eq!(Ipv4Addr::new(16, 89, 10, 65).is_link_local(), false);
```

--------------------------------

### Into Ok

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/type.Result.html

Extracts the Ok value from a Result that is guaranteed to be Ok, without panicking.

```rust
fn only_good_news() -> Result<String, !> {
    Ok("this is fine".into())
}

let s: String = only_good_news().into_ok();
println!("{s}");
```

--------------------------------

### QueryBuilder::arg

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.QueryBuilder.html

Adds a single argument to the query.

```APIDOC
## pub fn arg(self, arg: impl ToSql) -> Self

### Description
Appends a single argument to the query builder, which must implement the ToSql trait.

### Parameters
- **arg** (impl ToSql) - Required - The argument to bind to the query.
```

--------------------------------

### pub fn default_bf16_value() -> Value

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/fn.default_bf16_value.html

Creates and returns a default BFloat16 value.

```APIDOC
## pub fn default_bf16_value() -> Value

### Description
Creates a default BFloat16 value.

### Signature
`pub fn default_bf16_value() -> Value`

### Returns
- **Value** - The default BFloat16 value.
```

--------------------------------

### Check for Documentation Address

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.Ipv4.html

Determines if an IPv4 address falls within ranges reserved for documentation purposes.

```rust
use std::net::Ipv4Addr;

assert_eq!(Ipv4Addr::new(192, 0, 2, 255).is_documentation(), true);
assert_eq!(Ipv4Addr::new(198, 51, 100, 65).is_documentation(), true);
assert_eq!(Ipv4Addr::new(203, 0, 113, 6).is_documentation(), true);
assert_eq!(Ipv4Addr::new(193, 34, 17, 19).is_documentation(), false);
```

--------------------------------

### try_from_tz

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.DynDateTime64.html

Creates a new DynDateTime64 instance from a timezone-aware DateTime with a specified precision.

```APIDOC
## pub fn try_from_tz(other: DateTime<Tz>, precision: usize) -> Result<Self, TryFromIntError>

### Description
Creates a new DynDateTime64 instance from a timezone-aware DateTime with a specified precision.

### Parameters
- **other** (DateTime<Tz>) - The timezone-aware date-time value.
- **precision** (usize) - The precision for the DateTime64 type.

### Returns
- **Result<Self, TryFromIntError>** - Returns the new DynDateTime64 instance or a conversion error.
```

--------------------------------

### BlockRowIter Definition

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/block/struct.BlockRowIter.html

The structure definition for BlockRowIter.

```rust
pub struct BlockRowIter<'a> { /* private fields */ }
```

--------------------------------

### Accessing VERSION_MAJOR

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/constant.VERSION_MAJOR.html

Represents the major version of Clickhouse.

```rust
pub const VERSION_MAJOR: u64 = 22;
```

--------------------------------

### Check if Unspecified

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.Ipv4.html

Verify if the address is the special 0.0.0.0 unspecified address.

```rust
use std::net::Ipv4Addr;

assert_eq!(Ipv4Addr::new(0, 0, 0, 0).is_unspecified(), true);
assert_eq!(Ipv4Addr::new(45, 22, 13, 197).is_unspecified(), false);
```

--------------------------------

### is_benchmarking

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.Ipv6.html

Checks if the IPv6 address is reserved for benchmarking.

```APIDOC
## pub fn is_benchmarking(&self) -> bool

### Description
Returns true if this is an address reserved for benchmarking (2001:2::/48), as defined in IETF RFC 5180.
```

--------------------------------

### Check if an IPv6 address is reserved for documentation

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.Ipv6.html

Checks if the address is within the ranges reserved for documentation by RFC 3849 and RFC 9637. Requires the nightly-only experimental `ip` feature.

```rust
#![feature(ip)]

use std::net::Ipv6Addr;

assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff).is_documentation(), false);
assert_eq!(Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 0).is_documentation(), true);
assert_eq!(Ipv6Addr::new(0x3fff, 0, 0, 0, 0, 0, 0, 0).is_documentation(), true);
```

--------------------------------

### Shift insert into IndexMap

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.IndexMap.html

Demonstrates inserting or moving keys to a specific index, noting that existing entries cannot be moved to the map length index.

```rust
use indexmap::IndexMap;
let mut map: IndexMap<char, ()> = ('a'..='z').map(|c| (c, ())).collect();

// The new key '*' goes exactly at the given index.
assert_eq!(map.get_index_of(&'*'), None);
assert_eq!(map.shift_insert(10, '*', ()), None);
assert_eq!(map.get_index_of(&'*'), Some(10));

// Moving the key 'a' up to 10 will shift others down, including the '*' that was at 10.
assert_eq!(map.shift_insert(10, 'a', ()), Some(()));
assert_eq!(map.get_index_of(&'a'), Some(10));
assert_eq!(map.get_index_of(&'*'), Some(9));

// Moving the key 'z' down to 9 will shift others up, including the '*' that was at 9.
assert_eq!(map.shift_insert(9, 'z', ()), Some(()));
assert_eq!(map.get_index_of(&'z'), Some(9));
assert_eq!(map.get_index_of(&'*'), Some(10));

// Existing keys can move to len-1 at most, but new keys can insert at the endpoint.
assert_eq!(map.len(), 27);
assert_eq!(map.shift_insert(map.len() - 1, '*', ()), Some(()));
assert_eq!(map.get_index_of(&'*'), Some(26));
assert_eq!(map.shift_insert(map.len(), '+', ()), None);
assert_eq!(map.get_index_of(&'+'), Some(27));
assert_eq!(map.len(), 28);
```

```rust
use indexmap::IndexMap;
let mut map: IndexMap<char, ()> = ('a'..='z').map(|c| (c, ())).collect();
```

--------------------------------

### Expect Result Value

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/type.Result.html

Returns the Ok value or panics with a provided message.

```rust
let x: Result<u32, &str> = Err("emergency failure");
x.expect("Testing expect"); // panics with `Testing expect: emergency failure`
```

```rust
let path = std::env::var("IMPORTANT_PATH")
    .expect("env variable `IMPORTANT_PATH` should be set by `wrapper_script.sh`");
```

--------------------------------

### pub fn as_deref_mut(&mut self) -> Result<&mut <T as Deref>::Target, &mut E>

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/type.Result.html

Converts from Result<T, E> to Result<&mut <T as DerefMut>::Target, &mut E> by coercing the Ok variant via DerefMut.

```APIDOC
## pub fn as_deref_mut(&mut self) -> Result<&mut <T as Deref>::Target, &mut E>

### Description
Converts from `Result<T, E>` (or `&mut Result<T, E>`) to `Result<&mut <T as DerefMut>::Target, &mut E>`. Coerces the `Ok` variant of the original `Result` via `DerefMut` and returns the new `Result`.
```

--------------------------------

### ConnectionManager Definition

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.ConnectionManager.html

The primary structure definition for managing database connections.

```rust
pub struct ConnectionManager { /* private fields */ }
```

--------------------------------

### Perform total comparison with bf16::total_cmp

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.bf16.html

Demonstrates sorting a vector of bf16 values using the total_cmp method, which adheres to the IEEE 754 totalOrder predicate.

```rust
let mut v: Vec<bf16> = vec![];
v.push(bf16::ONE);
v.push(bf16::INFINITY);
v.push(bf16::NEG_INFINITY);
v.push(bf16::NAN);
v.push(bf16::MAX_SUBNORMAL);
v.push(-bf16::MAX_SUBNORMAL);
v.push(bf16::ZERO);
v.push(bf16::NEG_ZERO);
v.push(bf16::NEG_ONE);
v.push(bf16::MIN_POSITIVE);

v.sort_by(|a, b| a.total_cmp(&b));

assert!(v
    .into_iter()
    .zip(
        [
            bf16::NEG_INFINITY,
            bf16::NEG_ONE,
            -bf16::MAX_SUBNORMAL,
            bf16::NEG_ZERO,
            bf16::ZERO,
            bf16::MAX_SUBNORMAL,
            bf16::MIN_POSITIVE,
            bf16::ONE,
            bf16::INFINITY,
            bf16::NAN
        ]
        .iter()
    )
    .all(|(a, b)| a.to_bits() == b.to_bits()));
```

--------------------------------

### Check for Loopback Address

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.Ipv6.html

Verify if an address is the loopback '::1' address.

```rust
use std::net::Ipv6Addr;

assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff).is_loopback(), false);
assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 0x1).is_loopback(), true);
```

--------------------------------

### from_f64_const

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.bf16.html

Constructs a bf16 value from a 64-bit floating point value. This is a lossy operation that is const-compatible.

```APIDOC
## pub const fn from_f64_const(value: f64) -> bf16

### Description
Constructs a `bf16` value from a 64-bit floating point value. This function is identical to `from_f64` except it never uses hardware intrinsics, which allows it to be `const`.
```

--------------------------------

### Client::insert_native

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.Client.html

Sends a query string with streaming associated data (i.e. insert) over native protocol.

```APIDOC
## pub async fn insert_native<T: Row + Send + Sync + 'static>(&self, query: impl TryInto<ParsedQuery, Error = KlickhouseError>, blocks: impl Stream<Item = Vec<T>> + Send + Sync + Unpin + 'static) -> Result<()>

### Description
Sends a query string with streaming associated data (i.e. insert) over native protocol. Once all outgoing blocks are written, response blocks from Clickhouse are read and discarded.

### Parameters
- **query** (impl TryInto<ParsedQuery>) - Required - The insert query.
- **blocks** (impl Stream<Item = Vec<T>>) - Required - The stream of data blocks to insert.
```

--------------------------------

### Function signature for split_query_statements

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/query_parser/fn.split_query_statements.html

The function signature for splitting semicolon-delimited queries.

```rust
pub fn split_query_statements(query: &str) -> Vec<String>
```

--------------------------------

### Byte Conversion Methods

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.bf16.html

Methods for converting bf16 to and from byte arrays in various endianness formats.

```APIDOC
## Byte Conversion Methods

- `to_le_bytes(self) -> [u8; 2]`: Returns the memory representation as a byte array in little-endian byte order.
- `to_be_bytes(self) -> [u8; 2]`: Returns the memory representation as a byte array in big-endian byte order.
- `to_ne_bytes(self) -> [u8; 2]`: Returns the memory representation as a byte array in native byte order.
- `from_le_bytes(bytes: [u8; 2]) -> bf16`: Creates a floating point value from its representation as a byte array in little endian.
- `from_be_bytes(bytes: [u8; 2]) -> bf16`: Creates a floating point value from its representation as a byte array in big endian.
- `from_ne_bytes(bytes: [u8; 2]) -> bf16`: Creates a floating point value from its representation as a byte array in native endian.
```

--------------------------------

### Try parse UUID from string

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.Uuid.html

Parses a UUID from a string. This is the preferred method over parse_str.

```rust
let uuid = Uuid::try_parse("550e8400-e29b-41d4-a716-446655440000")?;

assert_eq!(Some(Version::Random), uuid.get_version());
assert_eq!(Variant::RFC4122, uuid.get_variant());
```

--------------------------------

### Define Ipv6 Struct

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.Ipv6.html

The basic definition of the Ipv6 wrapper struct.

```rust
pub struct Ipv6(pub Ipv6Addr);
```

--------------------------------

### Convert to IPv4

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.Ipv6.html

Converts compatible or mapped IPv6 addresses to IPv4. Note that this includes the loopback address.

```rust
use std::net::{Ipv4Addr, Ipv6Addr};

assert_eq!(Ipv6Addr::new(0xff00, 0, 0, 0, 0, 0, 0, 0).to_ipv4(), None);
assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff).to_ipv4(),
           Some(Ipv4Addr::new(192, 10, 2, 255)));
assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1).to_ipv4(),
           Some(Ipv4Addr::new(0, 0, 0, 1)));
```

--------------------------------

### ToSql::to_sql

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/trait.ToSql.html

Converts a value into a raw Clickhouse SQL value.

```APIDOC
## fn to_sql(self, type_hint: Option<&Type>) -> Result<Value>

### Description
Converts the implementing type into a raw Clickhouse SQL `Value`. This method is used to prepare data for insertion or querying in Clickhouse.

### Parameters
- **self** - The instance of the type to convert.
- **type_hint** (Option<&Type>) - Optional hint regarding the expected Clickhouse type.

### Returns
- **Result<Value>** - A result containing the converted Clickhouse `Value` or an error if the conversion fails.
```

--------------------------------

### Create a Max UUID

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.Uuid.html

Constructs a UUID with all 128 bits set to one.

```rust
let uuid = Uuid::max();

assert_eq!(
    "ffffffff-ffff-ffff-ffff-ffffffffffff",
    uuid.hyphenated().to_string(),
);
```

--------------------------------

### Check Benchmarking Address Space

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.Ipv4.html

Checks if an address falls within the 198.18.0.0/15 range reserved for network benchmarking.

```rust
#![feature(ip)]
use std::net::Ipv4Addr;

assert_eq!(Ipv4Addr::new(198, 17, 255, 255).is_benchmarking(), false);
assert_eq!(Ipv4Addr::new(198, 18, 0, 0).is_benchmarking(), true);
assert_eq!(Ipv4Addr::new(198, 19, 255, 255).is_benchmarking(), true);
assert_eq!(Ipv4Addr::new(198, 20, 0, 0).is_benchmarking(), false);
```

--------------------------------

### is_benchmarking

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.Ipv4.html

Checks if the IPv4 address is reserved for network device benchmarking.

```APIDOC
## pub fn is_benchmarking(&self) -> bool

### Description
Returns true if this address is part of the 198.18.0.0/15 range, which is reserved for network devices benchmarking. This is a nightly-only experimental API.

### Returns
- **bool** - True if the address is in the benchmarking range.
```

--------------------------------

### Insert at index in IndexMap

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.IndexMap.html

Demonstrates an invalid index usage for shifting an existing key.

```rust
// This is an invalid index for moving an existing key!
map.shift_insert(map.len(), 'a', ());
```

--------------------------------

### Accessing VERSION_MINOR constant

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/constant.VERSION_MINOR.html

Defines the minor version of the Clickhouse integration as a 64-bit unsigned integer.

```rust
pub const VERSION_MINOR: u64 = 9;
```

--------------------------------

### Check if Loopback

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.Ipv4.html

Verify if the address belongs to the 127.0.0.0/8 loopback range.

```rust
use std::net::Ipv4Addr;

assert_eq!(Ipv4Addr::new(127, 0, 0, 1).is_loopback(), true);
assert_eq!(Ipv4Addr::new(45, 22, 13, 197).is_loopback(), false);
```

--------------------------------

### Create a Nil UUID

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.Uuid.html

Constructs a UUID with all 128 bits set to zero.

```rust
let uuid = Uuid::nil();

assert_eq!(
    "00000000-0000-0000-0000-000000000000",
    uuid.hyphenated().to_string(),
);
```

--------------------------------

### Create UUID reference from byte reference

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.Uuid.html

Creates a reference to a UUID from a reference to 16 bytes.

```rust
let bytes = [
    0xa1, 0xa2, 0xa3, 0xa4,
    0xb1, 0xb2,
    0xc1, 0xc2,
    0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8,
];

let uuid = Uuid::from_bytes_ref(&bytes);

assert_eq!(
    uuid.hyphenated().to_string(),
    "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8"
);

assert!(std::ptr::eq(
    uuid as *const Uuid as *const u8,
    &bytes as *const [u8; 16] as *const u8,
));
```

--------------------------------

### Floating Point Property Checks

Source: https://docs.rs/klickhouse/0.15.3/klickhouse/struct.bf16.html

Methods to check the state of a bf16 value.

```APIDOC
## Floating Point Property Checks

- `is_nan(self) -> bool`: Returns `true` if this value is NaN.
- `is_infinite(self) -> bool`: Returns `true` if this value is ±∞.
- `is_finite(self) -> bool`: Returns `true` if this number is neither infinite nor NaN.
```
Tokens:
Raw