> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-parallel-read-in-order-multi-part.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ClickHouse 中用于存储聚合函数中间状态的 AggregateFunction 数据类型文档

# AggregateFunction 类型

## 说明

ClickHouse 中所有[聚合函数](/zh/reference/functions/aggregate-functions/index)都有一个特定于实现的中间状态，该状态可以序列化为
`AggregateFunction` 数据类型并存储在表中。这通常通过
[materialized view](/zh/reference/statements/create/view)
来实现。

通常有两个聚合函数[组合器](/zh/reference/functions/aggregate-functions/combinators)
会与 `AggregateFunction` 类型配合使用：

* [`-State`](/zh/reference/functions/aggregate-functions/combinators#-state) 聚合函数组合器：将其追加到聚合
  函数名后，会生成 `AggregateFunction` 中间状态。
* [`-Merge`](/zh/reference/functions/aggregate-functions/combinators#-merge) 聚合
  函数组合器：用于从中间状态中得到聚合的最终结果。

## 语法

```sql theme={null}
AggregateFunction(aggregate_function_name, types_of_arguments...)
```

**参数**

* `aggregate_function_name` - 聚合函数的名称。如果该函数
  是参数化函数，则还应指定其参数。
* `types_of_arguments` - 聚合函数各参数的类型。

例如：

```sql theme={null}
CREATE TABLE t
(
    column1 AggregateFunction(uniq, UInt64),
    column2 AggregateFunction(anyIf, String, UInt8),
    column3 AggregateFunction(quantiles(0.5, 0.9), UInt64)
) ENGINE = ...
```

## 使用方法

### 数据插入

要将数据插入包含 `AggregateFunction` 类型列的表中，可以
使用带聚合函数和
[`-State`](/zh/reference/functions/aggregate-functions/combinators#-state) 聚合
函数组合器的 `INSERT SELECT`。

例如，要向类型为 `AggregateFunction(uniq, UInt64)` 和
`AggregateFunction(quantiles(0.5, 0.9), UInt64)` 的列插入数据，应使用以下
带组合器的聚合函数。

```sql theme={null}
uniqState(UserID)
quantilesState(0.5, 0.9)(SendTiming)
```

与函数 `uniq` 和 `quantiles` 相比，`uniqState` 和 `quantilesState`
(附加了 `-State` 组合器) 返回的是状态，而不是最终值。
换句话说，它们返回的是 `AggregateFunction` 类型的值。

在 `SELECT` 查询结果中，`AggregateFunction` 类型的值在所有 ClickHouse 输出
格式里都使用与具体实现相关的二进制表示。

有一个特殊的 Session 级别设置 `aggregate_function_input_format`，可用于根据输入值构建状态。
它支持以下格式：

* `state` - 序列化状态 (默认值) 。
  例如，如果你通过 `SELECT`
  查询将数据转储为 `TabSeparated` 格式，那么这个转储可以通过 `INSERT` 查询重新加载。
* `value` - 该格式要求提供聚合函数参数的单个值；如果有多个参数，则要求提供由这些参数组成的元组；该值会被聚合以形成状态。
* `array` - 该格式要求提供一个值的 Array，如上面的 `value` 选项所述；数组中的所有元素都会被聚合以形成该状态。

在 `value` 和 `array` 模式下，该列会按照这些值的类型 (`T`、`Tuple(T1, T2)` 或它们的 `Array`) 来读取，
并采用输入格式针对该类型所使用的表示方式。这一行为在所有输入格式中都相同，从 `CSV` 和 `JSONEachRow` 到 `RowBinary` 和 `Parquet`。

### 数据选择

从 `AggregatingMergeTree` 表中查询数据时，请使用 `GROUP BY` 子句，
并使用与插入数据时相同的聚合函数，但要加上
[`-Merge`](/zh/reference/functions/aggregate-functions/combinators#-merge) 组合器。

追加了 `-Merge` 组合器的聚合函数会接收一组
状态，将它们合并，并返回完整数据聚合的结果。

例如，以下两个查询会返回相同的结果：

```sql theme={null}
SELECT uniq(UserID) FROM table

SELECT uniqMerge(state) FROM (SELECT uniqState(UserID) AS state FROM table GROUP BY RegionID)
```

## 使用示例

请参阅 [AggregatingMergeTree](/zh/reference/engines/table-engines/mergetree-family/aggregatingmergetree) 引擎的说明。

## 相关内容

* 博客：[在 ClickHouse 中使用适用于数组、Map 和状态的聚合组合器](https://clickhouse.com/blog/aggregate-functions-combinators-in-clickhouse-for-arrays-maps-and-states)
* [MergeState](/zh/reference/functions/aggregate-functions/combinators#-mergestate)
  组合器。
* [State](/zh/reference/functions/aggregate-functions/combinators#-state) 组合器。