client-web-1.24.0

New features

• OpenTelemetry: richer, more actionable spans (requested by Langfuse, #948). (#950)
  • The X-ClickHouse-Summary header is now parsed on the Web client and attached to the operation spans (query / command / exec / insert), including the outer clickhouse.query span. Previously the Web client did not parse the summary header at all.
  • Every key present in the summary header is recorded as clickhouse.summary.<key> (the set is not hardcoded). This surfaces total_rows_to_read and memory_usage (peak query memory, in bytes; sent by newer servers), and picks up future server-side additions (e.g. real_time_microseconds) automatically.
  • db.response.returned_rows is now recorded for non-streaming result consumption too (json() on JSON / JSONObjectEachRow / the other single-document JSON formats), not just row-streaming paths.
  • Added a span_attributes field to the per-request query params (query / command / exec / insert / ping). Use it to enrich the operation span with application-level context — e.g. mirroring the tags you also send via the log_comment setting (route, tenant, surface, etc.). Caller-provided attributes never override the client's own db.* / server.* / clickhouse.* attributes.
  • Added a dangerously_log_query_text client option (default false). When enabled, the raw SQL statement is attached to spans as the OpenTelemetry db.query.text attribute. The query text may contain sensitive literals, which is why it is off by default; bound query_params values and credentials are never traced regardless of this setting.

Bug fixes

• Fixed Array(Date) / Array(Date32) query-parameter binding (and other temporal element types nested in arrays, tuples, and maps). A JS Date inside a container was serialized as a bare Unix timestamp (e.g. [1683244800]), which the server's Array(Date) element parser rejects (CANNOT_PARSE_INPUT_ASSERTION_FAILED). Container-nested Date values are now emitted as a quoted UTC date string (e.g. ['2023-05-05']), the one encoding every temporal element type accepts. Note: a Date used inside Array(DateTime) / Array(DateTime64) is now bound at day precision (the time-of-day is dropped), since date-only is the only form Array(Date) accepts; scalar Date / DateTime binding is unchanged. (#947)
• Export the QueryParamsWithFormat, ClickHouseSummary, WithClickHouseSummary, ResultJSONType, RowJSONType and PingParams types from @clickhouse/client-web. They are used in the signatures of the public API (query, ping, the result types), but could not be imported from the package root (#997). (#1024)