Support for struct field mapping to columns with dot (.) notation in ClickHouse Go client

[senabd]

The Go ClickHouse client’s AppendStruct currently does not support mapping Go struct fields to ClickHouse columns that contain dot (.) characters in their names, such as:

CREATE TABLE example_table (
  SystemID String,
  `Nested.FieldName` Array(String),
  `Nested.Temperature` Array(Nullable(Float64))
)

When attempting to map these columns using Go struct tags:

type ExampleStruct struct {
  SystemID string
  NestedFieldName []string   `json:"nestedFieldName" ch:"Nested.FieldName"`
  NestedTemp      []*float64 `json:"nestedTemp" ch:"Nested.Temperature"`
}

And inserting data like:

ctx := context.Background()
batch, err := conn.PrepareBatch(ctx, "INSERT INTO example_table")

data := ExampleStruct{
  SystemID: "abc123",
  NestedFieldName: []string{"sensorA", "sensorB"},
  NestedTemp: []*float64{floatPtr(22.5), floatPtr(23.1)},
}

if err := batch.AppendStruct(data); err != nil {
    log.Fatalf("append failed: %v", err)
}

if err := batch.Send(); err != nil {
    log.Fatalf("send failed: %v", err)
}

Calling AppendStruct results in an error such as:

clickhouse [AppendStruct]: missing destination name "Nested.FieldName" in *package.ExampleStruct

Why is this needed?

This limitation makes it difficult to work with flattened Avro or Parquet schemas that use dot notation to represent nested structures—especially when column names are fixed and cannot be changed due to schema compatibility, ingestion contracts, or external dependencies.

Proposed solution

Enable the Go client’s AppendStruct method to:

• Recognize struct tags like ch:"Nested.FieldName" and match them with column names containing dot notation.
• Alternatively, allow a custom tag (e.g., clickhouse:"") to explicitly map Go fields to arbitrary column names including those with dots.

Workarounds attempted

• Renaming columns in ClickHouse is not an option due to external schema constraints.
• Attempting to use embedded structs or JSON tags had no effect.
• Manual column mapping is possible but defeats the purpose of AppendStruct.

Environment

• Go ClickHouse client version: v2.37.2 (latest as of writing)
• ClickHouse server version: 24.3.2.23
• Using PrepareBatch + AppendStruct pattern

Additional context

Support for this feature would help teams working with structured data (e.g., Avro, Protobuf, etc.) seamlessly ingest telemetry or event-based data into ClickHouse without restructuring their pipelines or schemas.