Project: ClickHouse (App Definition and Development / Database)
File: aggregatingmergetree.md

slug: /en/engines/table-engines/mergetree-family/aggregatingmergetree sidebar_position: 60 sidebar_label: AggregatingMergeTree The engine inherits from , altering the logic for data parts merging. ClickHouse replaces all rows with the same primary key (or more accurately, with the same ) with a single row (within a one data part) that stores a combination of states of aggregate functions. You can use `AggregatingMergeTree` tables for incremental data aggregation, including for aggregated materialized views. The engine processes all columns with the following types: It is appropriate to use `AggregatingMergeTree` if it reduces the number of rows by orders. ``` sql CREATE TABLE [IF NOT EXISTS] [db.]table_name [ON CLUSTER cluster] ( name1 [type1] [DEFAULT|MATERIALIZED|ALIAS expr1], name2 [type2] [DEFAULT|MATERIALIZED|ALIAS expr2], ... ) ENGINE = AggregatingMergeTree() [PARTITION BY expr] [ORDER BY expr] [SAMPLE BY expr] [TTL expr] [SETTINGS name=value, ...] ``` For a description of request parameters, see . Query clauses When creating an `AggregatingMergeTree` table the same are required, as when creating a `MergeTree` table. <details markdown="1"> <summary>Deprecated Method for Creating a Table</summary> :::note Do not use this method in new projects and, if possible, switch the old projects to the method described above. ::: ``` sql CREATE TABLE [IF NOT EXISTS] [db.]table_name [ON CLUSTER cluster] ( name1 [type1] [DEFAULT|MATERIALIZED|ALIAS expr1], name2 [type2] [DEFAULT|MATERIALIZED|ALIAS expr2], ... ) ENGINE [=] AggregatingMergeTree(date-column [, samplingexpression], (primary, key), indexgranularity) ``` All of the parameters have the same meaning as in `MergeTree`. </details> To insert data, use query with aggregate -State- functions. When selecting data from `AggregatingMergeTree` table, use `GROUP BY` clause and the same aggregate functions as when inserting data, but using `-Merge` suffix. In the results of `SELECT` query, the values of `AggregateFunction` type have implementation-specific binary representation for all of the ClickHouse output formats. If dump data into, for example, `TabSeparated` format with `SELECT` query then this dump can be loaded back using `INSERT`

The following examples assumes that you have a database named `test` so make sure you create that if it doesn't already exist: ```sql CREATE DATABASE test; ``` We will create the table `test.visits` that contain the raw data: ``` sql CREATE TABLE test.visits ( StartDate DateTime64 NOT NULL, CounterID UInt64, Sign Nullable(Int32), UserID Nullable(Int32) ) ENGINE = MergeTree ORDER BY (StartDate, CounterID); ``` Next, we need to create an `AggregatingMergeTree` table that will store `AggregationFunction`s that keep track of the total number of visits and the number of unique users. `AggregatingMergeTree` materialized view that watches the `test.visits` table, and use the `AggregateFunction` type: ``` sql CREATE TABLE test.agg_visits ( StartDate DateTime64 NOT NULL, CounterID UInt64, Visits AggregateFunction(sum, Nullable(Int32)), Users AggregateFunction(uniq, Nullable(Int32)) ) ENGINE = AggregatingMergeTree() ORDER BY (StartDate, CounterID); ``` And then let's create a materialized view that populates `test.agg_visits` from `test.visits` : ```sql CREATE MATERIALIZED VIEW test.visitsmv TO test.aggvisits AS SELECT StartDate, CounterID, sumState(Sign) AS Visits, uniqState(UserID) AS Users FROM test.visits GROUP BY StartDate, CounterID; ``` Inserting data into the `test.visits` table. ``` sql INSERT INTO test.visits (StartDate, CounterID, Sign, UserID) VALUES (1667446031000, 1, 3, 4), (1667446031000, 1, 6, 3); ``` The data is inserted in both `test.visits` and `test.agg_visits`. To get the aggregated data, we need to execute a query such as `SELECT ... GROUP BY ...` from the materialized view `test.mv_visits`: ```sql SELECT StartDate, sumMerge(Visits) AS Visits, uniqMerge(Users) AS Users FROM test.agg_visits GROUP BY StartDate ORDER BY StartDate; ``` ```text StartDateVisitsUsers 2022-11-03 03:27:11.000 9 2 ``` And how about if we add another couple of records to `test.visits`, but this time we'll use a different timestamp for one of the records: ```sql INSERT INTO test.visits (StartDate, CounterID, Sign, UserID) VALUES (1669446031000, 2, 5, 10), (1667446031000, 3, 7, 5); ``` If we then run the `SELECT` query again, we'll see the following output: ```text StartDateVisitsUsers 2022-11-03 03:27:11.000 16 3 2022-11-26 07:00:31.000 5 1 ``` Blog: