Skip to content

Database governance built for humans and agents — controlling changes and access across every major database.

fix(clickhouse): translate AggregateFunction decode errors (#20156)

Vincent Huang52f63a3a6f5d
diff --git a/backend/plugin/db/clickhouse/query.go b/backend/plugin/db/clickhouse/query.go
index d9e7d12b19..5ec38f1eb5 100644
--- a/backend/plugin/db/clickhouse/query.go
+++ b/backend/plugin/db/clickhouse/query.go
@@ -17,6 +17,7 @@ import (
"github.com/google/uuid"
"github.com/paulmach/orb"
"github.com/paulmach/orb/encoding/wkt"
+ "github.com/pkg/errors"
"github.com/shopspring/decimal"
"google.golang.org/protobuf/types/known/durationpb"
@@ -27,6 +28,8 @@ import (
"github.com/bytebase/bytebase/backend/plugin/parser/standard"
)
+const aggregateFunctionErrMarker = `unsupported column type "AggregateFunction(`
+
// QueryConn queries a SQL statement in a given connection.
func (*Driver) QueryConn(ctx context.Context, conn *sql.Conn, statement string, queryContext db.QueryContext) ([]*v1pb.QueryResult, error) {
singleSQLs, err := standard.SplitSQL(statement)
@@ -81,6 +84,7 @@ func (*Driver) QueryConn(ctx context.Context, conn *sql.Conn, statement string,
}()
stop := false
if err != nil {
+ err = translateAggregateFunctionError(err)
queryResult = &v1pb.QueryResult{
Error: err.Error(),
}
@@ -102,6 +106,20 @@ func getStatementWithResultLimit(statement string, limit int) string {
return fmt.Sprintf("WITH result AS (%s) SELECT * FROM result LIMIT %d;", util.TrimStatement(statement), limit)
}
+// translateAggregateFunctionError rewrites the clickhouse-go driver's opaque
+// "unsupported column type \"AggregateFunction(...)\"" error into actionable
+// guidance pointing the user at -Merge combinators or finalizeAggregation(),
+// since the driver cannot decode AggregateFunction intermediate state directly.
+func translateAggregateFunctionError(err error) error {
+ if err == nil || !strings.Contains(err.Error(), aggregateFunctionErrMarker) {
+ return err
+ }
+ return errors.Wrap(err,
+ "this query selects an AggregateFunction column, which stores aggregator intermediate state and cannot be decoded directly. "+
+ "Wrap each AggregateFunction column with its -Merge combinator under GROUP BY (for example, maxMerge(col)), or with "+
+ "finalizeAggregation(col) for per-row finalization")
+}
+
func makeValueByTypeName(typeName string, columnType *sql.ColumnType) any {
if strings.HasPrefix(typeName, "TUPLE") || strings.HasPrefix(typeName, "ARRAY") || strings.HasPrefix(typeName, "MAP") || strings.HasPrefix(typeName, "JSON") {
// For TUPLE, ARRAY, MAP, JSON type in ClickHouse, we pass any and the driver will do the rest.
diff --git a/backend/plugin/db/clickhouse/query_test.go b/backend/plugin/db/clickhouse/query_test.go
new file mode 100644
index 0000000000..12b1188d25
--- /dev/null
+++ b/backend/plugin/db/clickhouse/query_test.go
@@ -0,0 +1,37 @@
+package clickhouse
+
+import (
+ "errors"
+ "testing"
+
+ "github.com/stretchr/testify/require"
+)
+
+func TestTranslateAggregateFunctionError(t *testing.T) {
+ t.Run("nil", func(t *testing.T) {
+ require.NoError(t, translateAggregateFunctionError(nil))
+ })
+
+ t.Run("non aggregate function error", func(t *testing.T) {
+ err := errors.New("some other clickhouse error")
+ require.Same(t, err, translateAggregateFunctionError(err))
+ })
+
+ t.Run("simple aggregate function error is not rewritten", func(t *testing.T) {
+ // Defensive: SimpleAggregateFunction is supported by the driver, but if a
+ // future driver bug ever surfaces an "unsupported column type" error for
+ // it, our marker must not match (because SimpleAggregateFunction errors
+ // do not need the -Merge / finalizeAggregation guidance).
+ err := errors.New(`clickhouse: unsupported column type "SimpleAggregateFunction(sum, UInt64)"`)
+ require.Same(t, err, translateAggregateFunctionError(err))
+ })
+
+ t.Run("aggregate function error", func(t *testing.T) {
+ err := errors.New(`read data: failed to decode block from 127.0.0.1:9000 (conn_id=26, compression=none): clickhouse: unsupported column type "AggregateFunction(argMin, Decimal(20, 6), DateTime64(3, 'UTC'))"`)
+ got := translateAggregateFunctionError(err)
+ require.Error(t, got)
+ require.Contains(t, got.Error(), "cannot be decoded directly")
+ require.Contains(t, got.Error(), "finalizeAggregation(col)")
+ require.Contains(t, got.Error(), err.Error())
+ })
+}