docs: add docs for kafka sink auto evolve option

docs/integrations/data-ingestion/kafka/kafka-clickhouse-connect-sink.md

@@ -122,6 +122,7 @@
 | `bufferCount` (since v1.3.6)                    | Number of records to buffer in memory before flushing to ClickHouse. `0` disables internal buffering. Buffering is not supported with `exactlyOnce=true`.                                                                       | `"0"`                                                    |
 | `bufferFlushTime` (since v1.3.6)                | Maximum time in milliseconds to buffer records before flush when `exactlyOnce=false`. `0` disables time-based flushing. Default value is `0`. Only required for time-base threshold. Only effective when `bufferCount > 0`.                                                                                           | `"0"`                                                    |
 | `reportInsertedOffsets` (since v1.3.6)          | Enables returning only successfully inserted offsets from `preCommit` (instead of `currentOffsets`) when `exactlyOnce=false`. This does not apply when `ignorePartitionsWhenBatching=true`, where `currentOffsets` are still returned. | `"false"`                                                |
+| `auto.evolve` (since v1.3.7)                    | Automatically add columns to the ClickHouse table when incoming records contain new fields not present in the table. See [Schema Evolution](#schema-evolution). | `"false"`                                                |
 
 ### Target tables {#target-tables}
 
@@ -327,6 +328,57 @@
 }
 ```
 
+### Schema Evolution {#schema-evolution}
+
+The connector supports automatic table schema evolution when `auto.evolve=true`. When incoming Kafka records contain fields not present in the destination ClickHouse table, the connector automatically issues `ALTER TABLE ... ADD COLUMN IF NOT EXISTS` statements to add the missing columns.
+
+This mirrors the [`auto.evolve` feature](https://docs.confluent.io/kafka-connectors/jdbc/current/sink-connector/sink_config_options.html#auto-evolution) in the Confluent JDBC Sink Connector.
+
+#### How it works {#how-schema-evolution-works}
+
+1. For each batch of records, the connector compares the record schema against the table's column list.
+2. If new fields are detected, it maps the Kafka Connect types to ClickHouse types and issues DDL.
+3. If multiple schema versions appear in a single batch, the batch is split at schema boundaries - each sub-batch is flushed and the table is evolved before continuing.
+
+#### Type mapping for new columns {#schema-evolution-type-mapping}
+
+When creating new columns, the connector maps Connect types to ClickHouse types as follows:
+
+| Kafka Connect Type | ClickHouse Type | Notes |
+|---|---|---|
+| `org.apache.kafka.connect.data.Decimal` | `Decimal(38, S)` | Scale from schema parameters |
+| `org.apache.kafka.connect.data.Date` | `Date32` | |
+| `org.apache.kafka.connect.data.Time` | `Int64` | |
+| `org.apache.kafka.connect.data.Timestamp` | `DateTime64(3)` | |
+| `INT8` .. `INT64` | `Int8` .. `Int64` | |
+| `FLOAT32` / `FLOAT64` | `Float32` / `Float64` | |
+| `BOOLEAN` | `Bool` | |
+| `STRING` / `BYTES` | `String` | |
+| `ARRAY` | `Array(<element_type>)` | Recursive |
+| `MAP` | `Map(<key_type>, <value_type>)` | Recursive |
+| `STRUCT` | Not supported | Throws an error |
+
+Optional (nullable) fields are wrapped in `Nullable(...)`, except for `ARRAY` and `MAP` types which [cannot be Nullable in ClickHouse](/sql-reference/data-types/nullable). Elements and values inside composite types can still be Nullable.
+
+#### Guards {#schema-evolution-guards}
+
+The connector rejects schema evolution in the following cases with a clear error message:
+
+- **Non-nullable field without a default value** - ClickHouse requires new columns to be either `Nullable` or have a `DEFAULT`.
+- **STRUCT fields** - Mapping Connect STRUCT to ClickHouse is non-trivial (could be Tuple, JSON, or Nested). Not supported for auto-evolution.
+- **Schemaless or string records** - No Connect schema is available to derive ClickHouse types. Evolution is skipped with a warning.
+
+#### Concurrent tasks {#schema-evolution-concurrent-tasks}
+
+Schema evolution is safe to use with multiple connector tasks. `ADD COLUMN IF NOT EXISTS` is idempotent - if two tasks race to add the same column, both succeed silently. DDL statements are executed with [`alter_sync=1`](/sql-reference/statements/alter#synchronicity-of-alter-queries) to wait for the local replica to apply the change. A retry loop on `DESCRIBE TABLE` (5 retries, 200ms backoff) handles propagation to other replicas.
+
+#### Limitations {#schema-evolution-limitations}
+
+- **Add-only** - Columns are only added, never removed or modified. This is the same behavior as the JDBC connector. Stale nullable columns accumulate harmlessly.
+- **Schema required** - Evolution only works with schema-based data (Avro, Protobuf, JSON Schema). Schemaless JSON and string records are not evolved.
+- **STRUCT not supported** - Individual STRUCT fields cannot be auto-evolved. The top-level value must be a STRUCT (i.e., a row), but nested STRUCT fields are rejected.
+- **Schema Registry recommended** - For best results, use a [Schema Registry](https://docs.confluent.io/platform/current/schema-registry/index.html) with BACKWARD or FULL compatibility mode. This ensures new fields are always optional (nullable), which is the safest mode for auto-evolution.
+
 ### Logging {#logging}
 
 Logging is automatically provided by Kafka Connect Platform.