ClickHouse · nihalzp · Jun 11, 2026 · Feb 12, 2026 · Mar 12, 2026 · Mar 19, 2026
diff --git a/docs/en/engines/table-engines/mergetree-family/aggregatingmergetree.md b/docs/en/engines/table-engines/mergetree-family/aggregatingmergetree.md
@@ -187,6 +187,46 @@ Each source row produces one row in the materialized view, and the actual aggreg
 `AggregatingMergeTree` merges parts. This is only true if `optimize_on_insert = 0`.
 :::
 
+## Tuple element aggregation {#tuple-element-aggregation}
+
+When the `allow_tuple_element_aggregation` setting is enabled, `Tuple` columns are recursively flattened so that each leaf element participates in aggregation independently. This means that `AggregateFunction` or `SimpleAggregateFunction` sub-columns inside a `Tuple` are aggregated according to their respective functions, just as if they were top-level columns.
+
+Sub-columns that belong to a `Tuple` in the sorting key are excluded from aggregation. Non-aggregate sub-columns are treated as ordinary columns (their first value is kept).
+
+:::note
+This setting is immutable and must be specified at table creation time.
+:::
+
+```sql
+CREATE TABLE agg_tuples
+(
+    key UInt32,
+    metrics Tuple(
+        total_visits SimpleAggregateFunction(sum, UInt64),
+        unique_users SimpleAggregateFunction(max, UInt64)
+    )
+) ENGINE = AggregatingMergeTree()
+ORDER BY key
+SETTINGS allow_tuple_element_aggregation = 1;
+
+INSERT INTO agg_tuples VALUES (1, (100, 5));
+INSERT INTO agg_tuples VALUES (1, (200, 8));
+INSERT INTO agg_tuples VALUES (2, (50, 3));
+
+OPTIMIZE TABLE agg_tuples FINAL;
+
+SELECT key, metrics.total_visits, metrics.unique_users FROM agg_tuples ORDER BY key;
+```
+
+```text
+┌─key─┬─metrics.total_visits─┬─metrics.unique_users─┐
+│   1 │                  300 │                    8 │
+│   2 │                   50 │                    3 │
+└─────┴──────────────────────┴──────────────────────┘
+```
+
+`total_visits` is aggregated with `sum` (100 + 200 = 300), while `unique_users` is aggregated with `max` (max(5, 8) = 8).
+
 ## Related content {#related-content}
 
 - Blog: [Using Aggregate Combinators in ClickHouse](https://clickhouse.com/blog/aggregate-functions-combinators-in-clickhouse-for-arrays-maps-and-states)
diff --git a/docs/en/engines/table-engines/mergetree-family/coalescingmergetree.md b/docs/en/engines/table-engines/mergetree-family/coalescingmergetree.md
@@ -133,3 +133,43 @@ SELECT key, last_value(value_int), last_value(value_string), last_value(value_da
 ```
 
 :::
+
+## Tuple element aggregation {#tuple-element-aggregation}
+
+When the `allow_tuple_element_aggregation` setting is enabled, `Tuple` columns are recursively flattened so that each leaf element participates in coalescing independently. This allows you to store multiple fields in a single `Tuple` column and have them coalesced element-wise during merges — each `Nullable` sub-column retains the latest non-NULL value independently.
+
+The same rules apply to the flattened sub-columns as to regular columns:
+
+- Sub-columns that belong to a `Tuple` in the sorting key or partition key are excluded from coalescing.
+- If `columns` is specified, only sub-columns of the listed `Tuple` columns are coalesced.
+
+:::note
+This setting is immutable and must be specified at table creation time.
+:::
+
+```sql
+CREATE TABLE coalescing_tuples
+(
+    key UInt64,
+    data Tuple(
+        value_a Nullable(UInt64),
+        value_b Nullable(String),
+        nested Tuple(
+            value_c Nullable(UInt64)
+        )
+    )
+) ENGINE = CoalescingMergeTree()
+ORDER BY key
+SETTINGS allow_tuple_element_aggregation = 1;
+
+INSERT INTO coalescing_tuples VALUES (1, (100, NULL, (NULL)));
+INSERT INTO coalescing_tuples VALUES (1, (NULL, 'hello', (42)));
+
+SELECT key, data.value_a, data.value_b, data.nested.value_c FROM coalescing_tuples FINAL;
+```
+
+```text
+┌─key─┬─data.value_a─┬─data.value_b─┬─data.nested.value_c─┐
+│   1 │          100 │ hello        │                  42 │
+└─────┴──────────────┴──────────────┴─────────────────────┘
+```
diff --git a/docs/en/engines/table-engines/mergetree-family/summingmergetree.md b/docs/en/engines/table-engines/mergetree-family/summingmergetree.md
@@ -189,6 +189,50 @@ When requesting data, use the [sumMap(key, value)](../../../sql-reference/aggreg
 
 For nested data structure, you do not need to specify its columns in the tuple of columns for summation.
 
+### Tuple element aggregation {#tuple-element-aggregation}
+
+When the `allow_tuple_element_aggregation` setting is enabled, `Tuple` columns are recursively flattened so that each leaf element participates in summation independently. This allows you to store multiple metrics in a single `Tuple` column and have them summed element-wise during merges.
+
+The same rules apply to the flattened sub-columns as to regular columns:
+
+- Only numeric sub-columns are summed.
+- Sub-columns that belong to a `Tuple` in the sorting key or partition key are excluded from summation.
+- If `columns` is specified, only sub-columns of the listed `Tuple` columns are summed.
+- If all numeric sub-columns of a row are zero after summation, the row is deleted.
+
+:::note
+This setting is immutable and must be specified at table creation time.
+:::
+
+```sql
+CREATE TABLE summing_tuples
+(
+    key UInt32,
+    metrics Tuple(
+        impressions UInt64,
+        clicks UInt64,
+        nested Tuple(
+            conversions UInt64
+        )
+    )
+) ENGINE = SummingMergeTree()
+ORDER BY key
+SETTINGS allow_tuple_element_aggregation = 1;
+
+INSERT INTO summing_tuples VALUES (1, (100, 10, (1)));
+INSERT INTO summing_tuples VALUES (1, (200, 20, (3)));
+
+OPTIMIZE TABLE summing_tuples FINAL;
+
+SELECT key, metrics.impressions, metrics.clicks, metrics.nested.conversions FROM summing_tuples;
+```
+
+```text
+┌─key─┬─metrics.impressions─┬─metrics.clicks─┬─metrics.nested.conversions─┐
+│   1 │                 300 │             30 │                          4 │
+└─────┴─────────────────────┴────────────────┴────────────────────────────┘
+```
+
 ## Related content {#related-content}
 
 - Blog: [Using Aggregate Combinators in ClickHouse](https://clickhouse.com/blog/aggregate-functions-combinators-in-clickhouse-for-arrays-maps-and-states)
diff --git a/src/Columns/ColumnAggregateFunction.h b/src/Columns/ColumnAggregateFunction.h
@@ -141,7 +141,9 @@ class ColumnAggregateFunction final : public COWHelper<IColumnHelper<ColumnAggre
 
     bool isDefaultAt(size_t) const override
     {
-        throw Exception(ErrorCodes::NOT_IMPLEMENTED, "Method isDefaultAt is not supported for ColumnAggregateFunction");
+        /// Aggregate function states have no meaningful default representation, so they are never considered default.
+        /// This is consistent with getNumberOfDefaultRows returning 0.
+        return false;
     }
 
     std::string_view getDataAt(size_t n) const override;

diff --git a/src/Core/SettingsChangesHistory.cpp b/src/Core/SettingsChangesHistory.cpp
@@ -1233,6 +1233,7 @@ const VersionToSettingsChangesMap & getMergeTreeSettingsChangesHistory()
     {
         addSettingsChanges(merge_tree_settings_changes_history, "26.6",
         {
+            {"allow_tuple_element_aggregation", false, false, "New setting"},
             {"shared_merge_tree_try_fetch_part_in_memory_data_from_replicas_on_startup", false, false, "New setting which allows SMT download parts data from replicas instead of S3 on startup"},
         });
         addSettingsChanges(merge_tree_settings_changes_history, "26.5",

diff --git a/src/DataTypes/NestedUtils.cpp b/src/DataTypes/NestedUtils.cpp
@@ -30,6 +30,7 @@ namespace DB
 namespace ErrorCodes
 {
     extern const int ILLEGAL_COLUMN;
+    extern const int LOGICAL_ERROR;
     extern const int SIZES_OF_ARRAYS_DONT_MATCH;
     extern const int BAD_ARGUMENTS;
 }
@@ -278,6 +279,183 @@ Block flattenNested(const Block & block)
     return flattenImpl(block, false);
 }
 
+const DataTypeTuple * tryGetFlattenableTuple(const DataTypePtr & type)
+{
+    const auto * tuple_type = typeid_cast<const DataTypeTuple *>(type.get());
+    if (tuple_type && !tuple_type->getElements().empty() && !type->hasCustomName())
+        return tuple_type;
+    return nullptr;
+}
+
+/// Recursively flattens one (column, type) into its leaf columns, calling
+/// `emit_leaf(column, type, name, ancestors)` once per leaf. A leaf is anything
+/// `tryGetFlattenableTuple` does not expand (a non-tuple, or an empty/custom-named tuple);
+/// flattenable tuples are descended into. `name` is the leaf's full dotted path; `ancestors`
+/// are the tuple paths it descends from (the root column plus every intermediate tuple node).
+///
+/// Example — a column `t` of type `Tuple(a UInt64, inner Tuple(c UInt64, d UInt64))`, called with
+/// name_prefix = "t", emits three leaves:
+///   emit_leaf(col, UInt64, "t.a",       ["t"])
+///   emit_leaf(col, UInt64, "t.inner.c", ["t", "t.inner"])
+///   emit_leaf(col, UInt64, "t.inner.d", ["t", "t.inner"])
+///
+/// Names and ancestors are built from real element boundaries, so an element whose own name
+/// contains a dot (e.g. `p.x` in tuple `t`) is not a problem and gives the single leaf `t.p.x`
+/// with the sole ancestor `t`, never the unrelated path `t.p`.
+template <typename LeafCallback>
+static void flattenTupleRecursiveImpl(
+    const ColumnPtr & column,
+    const DataTypePtr & data_type,
+    LeafCallback && emit_leaf,
+    const String & name_prefix,
+    const Strings & ancestors)
+{
+    const auto * tuple_type = tryGetFlattenableTuple(data_type);
+    if (!tuple_type)
+    {
+        emit_leaf(column, data_type, name_prefix, ancestors);
+        return;
+    }
+
+    /// If the column is ColumnConst, expand it to a full column first,
+    /// so that all leaf columns are always non-const after flattening.
+    ColumnPtr materialized_column = column->convertToFullColumnIfConst();
+    const auto * column_tuple = assert_cast<const ColumnTuple *>(materialized_column.get());
+
+    const DataTypes & element_types = tuple_type->getElements();
+    const Strings & element_names = tuple_type->getElementNames();
+    const auto & sub_columns = column_tuple->getColumns();
+
+    /// `name_prefix` is empty only on the column-only flattening path (flattenTupleColumnsRecursive),
+    /// where leaf names and ancestors are unused, so skip building them there.
+    const bool build_metadata = !name_prefix.empty();
+
+    Strings element_ancestors = ancestors;
+    if (build_metadata)
+        element_ancestors.push_back(name_prefix);
+
+    for (size_t i = 0; i < element_types.size(); ++i)
+    {
+        String element_name = build_metadata ? concatenateName(name_prefix, element_names[i]) : String{};
+        flattenTupleRecursiveImpl(sub_columns[i], element_types[i], emit_leaf, element_name, element_ancestors);
+    }
+}
+
+Block flattenTupleRecursive(const Block & block, std::vector<Strings> * flattened_ancestors)
+{
+    Block result;
+    if (flattened_ancestors)
+        flattened_ancestors->clear();
+    for (const auto & elem : block)
+    {
+        flattenTupleRecursiveImpl(
+            elem.column, elem.type,
+            [&](const ColumnPtr & col, const DataTypePtr & type, const String & name, const Strings & ancestors)
+            {
+                result.insert(ColumnWithTypeAndName(col, type, name));
+                if (flattened_ancestors)
+                    flattened_ancestors->push_back(ancestors);
+            },
+            elem.name, {});
+    }
+    return result;
+}
+
+void flattenTupleLeafNames(const String & name, const DataTypePtr & type, Names & out)
+{
+    /// Mirrors the name generation of `flattenTupleRecursiveImpl`: descend only into flattenable
+    /// tuples, joining each element name onto the prefix, and emit non-tuple types as leaves.
+    const auto * tuple_type = tryGetFlattenableTuple(type);
+    if (!tuple_type)
+    {
+        out.push_back(name);
+        return;
+    }
+
+    const DataTypes & element_types = tuple_type->getElements();
+    const Strings & element_names = tuple_type->getElementNames();
+    for (size_t i = 0; i < element_types.size(); ++i)
+        flattenTupleLeafNames(concatenateName(name, element_names[i]), element_types[i], out);
+}
+
+/// Flatten tuple columns: input a vector of columns, return a new vector with all tuples expanded
+/// All tuples are flattened recursively
+Columns flattenTupleColumnsRecursive(const Block & header, const Columns & columns)
+{
+    if (header.columns() != columns.size())
+    {
+        throw Exception(
+            ErrorCodes::LOGICAL_ERROR,
+            "Header columns count ({}) does not match columns count ({}) in flattenTupleColumns",
+            header.columns(),
+            columns.size());
+    }
+
+    Columns result;
+    result.reserve(columns.size()); /// Lower bound: every column flattens to at least one leaf.
+
+    for (size_t i = 0; i < columns.size(); ++i)
+    {
+        const auto & header_col = header.getByPosition(i);
+        flattenTupleRecursiveImpl(
+            columns[i], header_col.type,
+            [&result](const ColumnPtr & col, const DataTypePtr &, const String &, const Strings &)
+            {
+                result.push_back(col);
+            },
+            {}, {});
+    }
+
+    return result;
+}
+
+static ColumnPtr reconstructTupleColumnImpl(const DataTypePtr & data_type, const Columns & flattened_columns, size_t & flattened_idx)
+{
+    if (const auto * tuple_type = tryGetFlattenableTuple(data_type))
+    {
+        const auto & element_types = tuple_type->getElements();
+        Columns tuple_columns;
+        tuple_columns.reserve(element_types.size());
+
+        for (const auto & element_type : element_types)
+            tuple_columns.push_back(reconstructTupleColumnImpl(element_type, flattened_columns, flattened_idx));
+
+        return ColumnTuple::create(tuple_columns);
+    }
+
+    /// For non-tuple types, take as-is from flattened columns
+    if (flattened_idx >= flattened_columns.size())
+    {
+        throw Exception(ErrorCodes::LOGICAL_ERROR, "flattened_idx out of range in reconstructTupleColumns");
+    }
+    return flattened_columns[flattened_idx++];
+}
+
+/// Reconstruct tuple columns: input header and flattened columns, return a new vector with tuples reconstructed
+Columns reconstructTupleColumnsRecursive(const Block & header, const Columns & flattened_columns)
+{
+    Columns result;
+    result.reserve(header.columns());
+    size_t flattened_idx = 0;
+
+    for (size_t i = 0; i < header.columns(); ++i)
+    {
+        const auto & header_col = header.getByPosition(i);
+        result.push_back(reconstructTupleColumnImpl(header_col.type, flattened_columns, flattened_idx));
+    }
+
+    if (flattened_idx != flattened_columns.size())
+    {
+        throw Exception(
+            ErrorCodes::LOGICAL_ERROR,
+            "reconstructTupleColumnsRecursive: consumed {} flattened columns, but total flattened columns count is {}",
+            flattened_idx,
+            flattened_columns.size());
+    }
+
+    return result;
+}
+
 namespace
 {