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

# Native client packets

> Native protocol client

| value | name              | description            |
| ----- | ----------------- | ---------------------- |
| 0     | [Hello](#hello)   | Client handshake start |
| 1     | [Query](#query)   | Query request          |
| 2     | [Data](#data)     | Block with data        |
| 3     | [Cancel](#cancel) | Cancel query           |
| 4     | [Ping](#ping)     | Ping request           |
| 5     | TableStatus       | Table status request   |

The `Data` can be compressed.

<h2 id="hello">
  Hello
</h2>

For example, we're `Go Client` v1.10 that supports `54451` protocol version and
want to connect to `default` database with `default` user and `secret` password.

| field             | type    | value         | description                |
| ----------------- | ------- | ------------- | -------------------------- |
| client\_name      | String  | `"Go Client"` | Client implementation name |
| version\_major    | UVarInt | `1`           | Client major version       |
| version\_minor    | UVarInt | `10`          | Client minor version       |
| protocol\_version | UVarInt | `54451`       | TCP Protocol version       |
| database          | String  | `"default"`   | Database name              |
| username          | String  | `"default"`   | Username                   |
| password          | String  | `"secret"`    | Password                   |

<h3 id="protocol-version">
  Protocol version
</h3>

Protocol version is TCP protocol version of client.

Usually it is equal to the latest compatible server revision, but
shouldn't be confused with it.

<h3 id="defaults">
  Defaults
</h3>

All values should be **explicitly set**, there are no defaults on server side.
On client side, use `"default"` database, `"default"` username and `""` (blank string)
password as defaults.

<h2 id="query">
  Query
</h2>

| field           | type                       | value      | description               |
| --------------- | -------------------------- | ---------- | ------------------------- |
| query\_id       | String                     | `1ff-a123` | Query ID, can be UUIDv4   |
| client\_info    | [ClientInfo](#client-info) | See type   | Data about client         |
| settings        | [Settings](#settings)      | See type   | List of settings          |
| secret          | String                     | `secret`   | Inter-server secret       |
| [stage](#stage) | UVarInt                    | `2`        | Execute until query stage |
| compression     | UVarInt                    | `0`        | Disabled=0, enabled=1     |
| body            | String                     | `SELECT 1` | Query text                |

<h3 id="client-info">
  Client info
</h3>

| field              | type            | description                    |
| ------------------ | --------------- | ------------------------------ |
| query\_kind        | byte            | None=0, Initial=1, Secondary=2 |
| initial\_user      | String          | Initial user                   |
| initial\_query\_id | String          | Initial query id               |
| initial\_address   | String          | Initial address                |
| initial\_time      | Int64           | Initial time                   |
| interface          | byte            | TCP=1, HTTP=2                  |
| os\_user           | String          | OS User                        |
| client\_hostname   | String          | Client Hostname                |
| client\_name       | String          | Client Name                    |
| version\_major     | UVarInt         | Client major version           |
| version\_minor     | UVarInt         | Client minor version           |
| protocol\_version  | UVarInt         | Client protocol version        |
| quota\_key         | String          | Quota key                      |
| distributed\_depth | UVarInt         | Distributed depth              |
| version\_patch     | UVarInt         | Client patch version           |
| otel               | Bool            | Trace fields are present       |
| trace\_id          | FixedString(16) | Trace ID                       |
| span\_id           | FixedString(8)  | Span ID                        |
| trace\_state       | String          | Tracing state                  |
| trace\_flags       | Byte            | Tracing flags                  |

<h3 id="settings">
  Settings
</h3>

| field     | type   | value             | description           |
| --------- | ------ | ----------------- | --------------------- |
| key       | String | `send_logs_level` | Key of setting        |
| value     | String | `trace`           | Value of setting      |
| important | Bool   | `true`            | Can be ignored or not |

Encoded as list, blank key and value denotes end of list.

<h3 id="stage">
  Stage
</h3>

| value | name               | description                                 |
| ----- | ------------------ | ------------------------------------------- |
| 0     | FetchColumns       | Only fetch column types                     |
| 1     | WithMergeableState | Until mergeable state                       |
| 2     | Complete           | Until full completeness (should be default) |

<h2 id="data">
  Data
</h2>

| field   | type                  | description        |
| ------- | --------------------- | ------------------ |
| info    | BlockInfo             | Encoded block info |
| columns | UVarInt               | Columns count      |
| rows    | UVarInt               | Rows count         |
| columns | [\[\]Column](#column) | Columns with data  |

<h3 id="column">
  Column
</h3>

| field | type   | value           | description |
| ----- | ------ | --------------- | ----------- |
| name  | String | `foo`           | Column name |
| type  | String | `DateTime64(9)` | Column type |
| data  | bytes  | \~              | Column data |

<h2 id="cancel">
  Cancel
</h2>

No packet body. Server should cancel query.

<h2 id="ping">
  Ping
</h2>

No packet body. Server should [respond with pong](/resources/develop-contribute/native-protocol/server#pong).