From 3521ec34d2a390af1f02f0a5f88b36fcd4d87961 Mon Sep 17 00:00:00 2001
From: Hongze Cheng <hzcheng@taosdata.com>
Date: Sun, 31 Oct 2021 13:17:19 +0800
Subject: [PATCH] add user manual of SMA

---
 .../Small_Materialized_Aggrates.md            | 43 +++++++++++++++++++
 1 file changed, 43 insertions(+)
 create mode 100644 docs/user_manual/Small_Materialized_Aggrates.md

diff --git a/docs/user_manual/Small_Materialized_Aggrates.md b/docs/user_manual/Small_Materialized_Aggrates.md
new file mode 100644
index 0000000000..59a5ed7b45
--- /dev/null
+++ b/docs/user_manual/Small_Materialized_Aggrates.md
@@ -0,0 +1,43 @@
+# Small Materialized Aggragates
+
+**SMA** (**S**mall **M**aterialized **A**ggrates) is used to speed up the query process on materialized data cube in TDengine. TDengine 3.0 gives more flexibility on the SMA configurations.
+
+There are two kinds of SMA in TDengine:
+1. Block-wise SMA
+2. Time-range-wise SMA
+
+<!-- 
+```plantuml
+    @startmindmap mind_map_test
+    * SMA
+    ** Block SMA
+    ** Time-Range SMA
+    @endmindmap
+``` 
+-->
+![SMA in TDengine 3.0](http://www.plantuml.com/plantuml/png/Km02X-AInAAItCoybDp40WKG7Gzan9Ua5fTmWUIr589z7I4iBGMddFpaR6I1aCpSLDsWnBpqLBYeGsfU2jGu0000)
+
+## Block-wise SMA
+Block-wise SMA is created by default when the data are committed. Since time-series data are saved as block data in files, a corresponding SMA is create when the data block is written. The default block-wise SMA includes:
+1. sum(*)
+2. max(*)
+3. min(*)
+
+By default, the system will create SMA for each column except those columns with type *binary* and *nchar*. However, users can change the behavior by the keyword **NOSMA** to disable the SMA for a certain column like below:
+```SQL
+# create a super table with the SMA on column b disabled
+create table st (ts timestamp, a int, b int NOSMA, c double) tags (tg1 binary(10), tg2 int);
+```
+
+## Time-range-wise SMA
+In addition to the default block-wise SMA, users can create their own SMAs ondemand. Below is an example to create a SMA.
+```SQL
+# create a SMA every 10 minutes with SMA of sum, max and min
+create sma_indx sma_5min on st (sum(*), max(*), min(*), twa(*)) interval(10m);
+```
+Users can also drop a time-range-wise SMA like below:
+```SQL
+# drop the sma index
+drop sma_index sma_5min on st;
+```
+**NOTE: Creating a SMA index is a heavy operation which may take a long time and block the write operation. So create the time-range-wise SMA when creating the table or when there are not too much data.**
\ No newline at end of file