add two HTAP documents

TOC.md

@@ -20,7 +20,9 @@
   + [Credits](/credits.md)
 + Quick Start
   + [Try Out TiDB](/quick-start-with-tidb.md)
+  + [Try Out HTAP](/quick-start-with-htap.md)
   + [Learn TiDB SQL](/basic-sql-operations.md)
+  + [Learn HTAP](/explore-htap.md)
   + [Import Example Database](/import-example-data.md)
 + Deploy
   + [Software and Hardware Requirements](/hardware-and-software-requirements.md)

_index.md

@@ -26,8 +26,10 @@ Designed for the cloud, TiDB provides flexible scalability, reliability and secu
 <NavColumn>
 <ColumnTitle>Quick Start</ColumnTitle>
 
-- [Quick Start Guide](/quick-start-with-tidb.md)
+- [Quick Start with TiDB](/quick-start-with-tidb.md)
+- [Quick Start with HTAP](/quick-start-with-htap.md)
 - [Explore SQL with TiDB](/basic-sql-operations.md)
+- [Explore HTAP](/explore-htap.md)
 
 </NavColumn>
 

explore-htap.md

@@ -0,0 +1,104 @@
+---
+title: Explore HTAP
+summary: Learn how to explore and use the features of TiDB HTAP.
+---
+
+# Explore HTAP
+
+This guide describes how to explore and use the features of TiDB Hybrid Transactional and Analytical Processing (HTAP).
+
+> **Note:**
+>
+> If you are new to TiDB HTAP and want to start using it quickly, see [Quick start with HTAP](/quick-start-with-htap.md).
+
+## Use cases
+
+TiDB HTAP can meet the needs that have increment massive data, reduce the risk cost of operation, and be used for on-premises big data technology stacks without difficulty, thereby presenting the value of data assets in real time.
+
+The following are the use cases of HTAP:
+
+- Hybrid load
+
+    When using TiDB for real-time Online Analytical Processing (OLAP) that is in hybrid load scenarios, you only need to provide an entry point. Then TiDB automatically selects different processing engines based on the specific business.
+
+- Real-time stream processing
+
+    When using TiDB in real-time stream processing scenarios, TiDB ensures that the continuously flowed data is queried in real time. At the same time, TiDB also can handle highly concurrent workloads and Business Intelligence (BI) queries.
+
+- Data center
+
+    When using TiDB as a data center, TiDB can meet specific business needs by seamlessly connecting the data for the application and the data warehouse.
+
+For more information about use cases of TiDB HTAP, see [blogs about HTAP on the PingCAP website](https://pingcap.com/blog-cn/#HTAP).
+
+## Architecture
+
+In TiDB, a row-based storage engine [TiKV](/tikv-overview.md) for Online Transactional Processing (OLTP) and a columnar storage engine [TiFlash](/tiflash/tiflash-overview.md) for Online Analytical Processing (OLAP) co-exist, replicate data automatically, and keep strong consistency. 
+
+For more information about the architecture, see [architecture of TiDB HTAP](/tiflash/tiflash-overview.md#architecture).
+
+## Prerequisites for environment
+
+Before exploring the features of TiDB HTAP, you need to configure TiDB and the corresponding storage engine according to the data volume. If the data volume is large (for example, 100 T), it is recommended to use TiFlash Massively Parallel Processing (MPP) as the primary solution and TiSpark as the supplementary solution.
+
+- TiFlash
+
+    - If you have deployed a TiDB cluster but not TiFlash nodes, add the TiFlash nodes in the on-premises TiDB cluster. For detailed information, see [Scale out a TiFlash cluster](/scale-tidb-using-tiup.md#scale-out-a-tiflash-cluster).
+    - If you have not deployed a TiDB cluster, see [Deploy a TiDB Cluster using TiUP](/production-deployment-using-tiup.md). At the same time, you also need to deploy the minimal cluster topology along with [TiFlash](/tiflash-deployment-topology.md).
+    - When deciding how to choose the number of TiFlash nodes, consider the following scenarios:
+
+        - If you mainly need OLTP that runs small-scale analytical processing, deploy one or several TiFlash nodes. They can dramatically increase the speed of analytic queries.
+        - If the OLTP throughput does not cause significant pressure to I/O usage rate of the TiFlash nodes, each TiFlash node uses more resources for computation, and thus the TiFlash cluster can have near-linear scalability. The number of TiFlash nodes should be tuned based on expected performance and response time.
+        - If the OLTP throughput is relatively high (for example, the rate of write throughput or update throughput is higher than 10 million lines/hours), the hot write regions and hot read regions can be formed. This is because the I/O usage in TiKV and TiFlash becomes the bottleneck due to limited write capacity of network and physical disk in this case.
+
+- TiSpark
+
+    - If your data needs to be analyzed with Spark, deploy TiSpark (Spark 3.x is not currently supported). For specific process, see [TiSpark User Guide](/tispark-overview.md).
+
+<!--    - Real-time stream processing
+  - If you want to build an efficient and easy-to-use real-time data warehouse with TiDB and Flink, you are welcome to participate in Apache Flink x TiDB meetups.-->
+
+## Prerequisites for data
+
+After TiFlash is deployed, data replication does not automatically begin. You need to manually specify the tables to be replicated to TiFlash.
+
+- If there is no data in the TiDB Cluster, migrate the data to TiDB first. For detailed information, see [data migration](/migration-overview.md).
+- If the TiDB cluster already has the replicated data from upstream, after TiFlash is deployed, data replication does not automatically begin. You need to manually specify the tables to be replicated to TiFlash. For detailed information, see [Use TiFlash](/tiflash/use-tiflash.md).
+
+## Data processing
+
+With TiDB, you can simply enter SQL statements for queries or write requirements. For the tables to be replicated to TiFlash, TiDB chooses the best execution freely by the front-end optimizer.
+
+> **Note:**
+> 
+> MPP mode of TiFlash is enabled by default. When an SQL statement is executed, TiDB automatically determines whether to run in MPP mode through the optimizer.
+>
+> - To disable MPP mode of TiFlash, set the value of [tidb_allow_mpp](/system-variables.md#tidb_allow_mpp-new-in-v50) system variable to `OFF`.
+> - To forcibly enable MPP mode of TiFlash for query execution, set the value of [tidb_allow_mpp](/system-variables.md#tidb_allow_mpp-new-in-v50) and [tidb_enforce_mpp](/system-variables.md#tidb_enforce_mpp-new-in-v51) to `ON`.
+> - To see whether to use MPP mode when TiDB execute queries, see [Explain Statements in the MPP Mode](/explain-mpp.md#explain-statements-in-the-mpp-mode). If the output of `EXPLAIN` statement includes `ExchangeSender` and `ExchangeReceiver` operator, MPP mode is activated.
+
+## Performance monitoring
+
+When using TiDB, you can monitor the running status and check TiDB performance by the following methods:
+
+- [TiDB Dashboard](/dashboard/dashboard-intro.md): you can see the overall running status of the TiDB cluster, analyse distribution and trends of read and write traffic, and learn the detailed execution information of slow queries.
+- [Monitoring system (Prometheus & Grafana)](/grafana-overview-dashboard.md): you can see the monitoring parameters of TiDB cluster-related componants including PD, TiDB, TiKV, TiFlash,TiCDC, and Node_exporter.
+
+To see the alert rules of TiDB cluster and TiFlash cluster, see [TiDB cluster alert rules](/alert-rules.md) and [TiFlash alert rules](/tiflash/tiflash-alert-rules.md).
+
+## Troubleshooting
+
+If you have issues while using TiDB, refer to the following documents:
+
+- [Analyze slow queries](/analyze-slow-queries.md)
+- [Identify expensive queries](/identify-expensive-queries.md)
+- [Troubleshoot hotspot issues](/troubleshoot-hot-spot-issues.md)
+- [TiDB cluster troubleshooting guide](/troubleshoot-tidb-cluster.md)
+- [Troubleshoot a TiFlash Cluster](/tiflash/troubleshoot-tiflash.md)
+
+You are also welcome to create [Github Issues](https://github.com/pingcap/tiflash/issues) or submit your questions on [AskTUG](https://asktug.com/).
+
+## What's next
+
+- To see TiFlash version, critical logs and system tables of TiFlash, see [Maintain a TiFlash cluster](/tiflash/maintain-tiflash.md).
+- To remove a specific TiFlash node, see [Scale out a TiFlash cluster](/scale-tidb-using-tiup.md#scale-out-a-tiflash-cluster).

quick-start-with-htap.md

@@ -0,0 +1,225 @@
+---
+title: Quick start with HTAP
+summary: Learn how to quickly get started with the TiDB HTAP.
+---
+
+# Quick Start Guide for TiDB HTAP
+
+This guide walks you through the quickest way to get started with TiDB's one-stop Hybrid Transactional and Analytical Processing (HTAP).
+
+> **Note:**
+>
+> The steps provided in this guide is ONLY for quick start in the test environment. For production environments, [explore HTAP](/explore-htap.md) is recommended. 
+
+## Basic concepts
+
+Before using TiDB HTAP, you need to have basic knowledge about [TiKV](/tikv-overview.md), a row-based storage engine for TiDB Online Transactional Processing (OLTP), and [TiFlash](/tiflash/tiflash-overview.md), a columnar storage engine for TiDB Online Analytical Processing (OLAP).
+
+- Storage engines of HTAP: The row-based storage engine and the columnar storage engine co-exist for HTAP. Both storage engines can replicate data automatically and keep strong consistency. The row-based storage engine optimizes OLTP performance, and the columnar storage engine optimizes OLAP performance.
+- Data consistency of HTAP: As a distributed and transactional key-value database, TiKV provides transactional APIs with ACID compliance. With the implementation of the [Raft onsensus algorithm](https://raft.github.io/raft.pdf), TiKV guarantees data consistency between multiple replicas and high availability. TiFlash replicates data from TiKV in real time, which ensures that data is strongly consistent between TiKV.
+- Data isolation of HTAP: TiKV and TiFlash can be deployed on different machines as needed to solve the problem of HTAP resource isolation.
+- MPP computing engine: [MPP](/tiflash/use-tiflash.md#control-whether-to-select-the-mpp-mode) is a distributed computing framework provided by the TiFlash engine since TiDB 5.0, which allows data exchange between nodes and provides high-performance, high-throughput SQL algorithms. If the MPP mode is enabled, the run time of the analytic queries can be significantly reduced.
+
+## Steps
+
+This document take a popular [TPC-H](http://www.tpc.org/tpch/) dataset as an example to guide you to experience the convenience and high performance of TiDB HTAP by trying to query.
+
+### Step 1: Prerequisites for deployment
+
+Before using TiDB HTAP, follow the steps in the [Quick Start Guide for the TiDB Database Platform](/quick-start-with-tidb.md) to deploy a local test environment.
+
+In [Quick Start Guide for the TiDB Database Platform](/quick-start-with-tidb.md):
+
+- You are recommended to run `tiup playground` to start a TiDB cluster of the latest version. When you run the following command, 1 TiDB instance, 1 TiKV instance, 1 PD instance, and 1 TiFlash instance are deloyed automatically:
+
+    {{< copyable "shell-regular" >}}
+
+    ```shell
+    tiup playground
+    ```
+
+- If you want to specify the TiDB version and the number of the instances of each component, run the command that specifies the number of the instances of TiFlash as following:
+
+    {{< copyable "shell-regular" >}}
+
+    ```shell
+    tiup playground v5.1.0 --db 2 --pd 3 --kv 3 --tiflash 1 --monitor
+    ```
+
+> **Note:**
+>
+> `tiup playground` command is ONLY for quick start, NOT for production.
+
+### Step 2: Prerequisites for data
+
+By following these steps, you can create the [TPC-H](http://www.tpc.org/tpch/) dataset for using TiDB HTAP. If you are interested in TPC-H, see [General Implementation Guidelines](http://tpc.org/tpc_documents_current_versions/pdf/tpc-h_v3.0.0.pdf).
+
+> **Note:**
+>
+> If you want to use your existing data for analytic queries, you can [migrate your data to TiDB](/migration-overview.md). If you want to design and create your own data, you can create it by executing SQL statements or using related tools.
+
+1. Install the tool that creates data by running the following command:
+
+    {{< copyable "shell-regular" >}}
+
+    ```shell
+    tiup install bench
+    ```
+
+2. Create the data by by running the following command:
+
+    {{< copyable "shell-regular" >}}
+
+    ```shell
+    tiup bench tpch --sf=1 prepare
+    ```
+
+    If the output of this command shows `Finished`, it indicates that the data is created.
+
+3. Execute the following SQL statement to see the created data:
+
+    {{< copyable "sql" >}}
+
+    ```sql
+    SELECT 
+      CONCAT(table_schema,'.',table_name) AS 'Table Name', 
+      table_rows AS 'Number of Rows', 
+      FORMAT_BYTES(data_length) AS 'Data Size', 
+      FORMAT_BYTES(index_length) AS 'Index Size', 
+      FORMAT_BYTES(data_length+index_length) AS'Total' 
+    FROM 
+      information_schema.TABLES 
+    WHERE 
+      table_schema='test';
+    ```
+
+    As you can see from the output, eight tables are created in total, and the largest table has 6.5 million rows of data (the actual amount of the created data is in line with the value of the SQL query, because the data is randomly created by the tool).
+
+    ```sql
+    +---------------+----------------+-----------+------------+-----------+
+    |  Table Name   | Number of Rows | Data Size | Index Size |   Total   |
+    +---------------+----------------+-----------+------------+-----------+
+    | test.nation   |             25 | 2.44 KiB  | 0 bytes    | 2.44 KiB  |
+    | test.region   |              5 | 416 bytes | 0 bytes    | 416 bytes |
+    | test.part     |         200000 | 25.07 MiB | 0 bytes    | 25.07 MiB |
+    | test.supplier |          10000 | 1.45 MiB  | 0 bytes    | 1.45 MiB  |
+    | test.partsupp |         800000 | 120.17 MiB| 12.21 MiB  | 132.38 MiB|
+    | test.customer |         150000 | 24.77 MiB | 0 bytes    | 24.77 MiB |
+    | test.orders   |        1527648 | 174.40 MiB| 0 bytes    | 174.40 MiB|
+    | test.lineitem |        6491711 | 849.07 MiB| 99.06 MiB  | 948.13 MiB|
+    +---------------+----------------+-----------+------------+-----------+
+    8 rows in set (0.06 sec)
+     ```
+
+    This is a database of a commercial ordering system. In which, the `test.nation` table indicates the information about countries, the `test.region` table indicates the information about regions, the `test.part` table indicates the information about parts, the `test.supplier` table indicates the information about suppliers, the `test.partsupp` table indicates the information about parts from suppliers, the `test.customer` table indicates the information about customers, the `test.customer` table indicates the information about orders, and the `test.lineitem` table indicates the information about online items.
+
+### Step 3: Query with the row-based storage engine
+
+You can see the performance of TiDB when using only the row-based storage engine (for most databases) by executing the following SQL statements:
+
+{{< copyable "sql" >}}
+
+```sql
+SELECT
+    l_orderkey,
+    SUM(
+        l_extendedprice * (1 - l_discount)
+    ) AS revenue,
+    o_orderdate,
+    o_shippriority
+FROM
+    customer,
+    orders,
+    lineitem
+WHERE
+    c_mktsegment = 'BUILDING'
+AND c_custkey = o_custkey
+AND l_orderkey = o_orderkey
+AND o_orderdate < DATE '1996-01-01'
+AND l_shipdate > DATE '1996-02-01'
+GROUP BY
+    l_orderkey,
+    o_orderdate,
+    o_shippriority
+ORDER BY
+    revenue DESC,
+    o_orderdate
+limit 10;
+```
+
+This is a shipping priority query that gives priority and potential revenue to the highest-revenue order that has not been shipped by a specified date. The potential income is defined as the sum of `l_extendedprice * (1-l_discount)`. The orders are listed in descending order of revenue. In this example, this query lists the unshipped orders with potential query revenue in the top 10.
+
+### Step 4: Replication with the columnar storage engine
+
+After TiFlash is deployed, data replication does not automatically begin. You need to send a DDL statement to TiDB through a MySQL client to create a TiFlash replica for a specific table:
+
+{{< copyable "sql" >}}
+
+```sql
+ALTER TABLE test.customer SET TIFLASH REPLICA 1;
+ALTER TABLE test.orders SET TIFLASH REPLICA 1;
+ALTER TABLE test.lineitem SET TIFLASH REPLICA 1;
+```
+
+You can check the status of the TiFlash replicas of a specific table using the following statement:
+
+{{< copyable "sql" >}}
+
+```sql
+SELECT * FROM information_schema.tiflash_replica WHERE TABLE_SCHEMA = 'test' and TABLE_NAME = 'customer';
+SELECT * FROM information_schema.tiflash_replica WHERE TABLE_SCHEMA = 'test' and TABLE_NAME = 'orders';
+SELECT * FROM information_schema.tiflash_replica WHERE TABLE_SCHEMA = 'test' and TABLE_NAME = 'lineitem';
+```
+
+In the result of above statement:
+
+- `AVAILABLE` indicates whether the TiFlash replicas of this table is available or not. `1` means available and `0` means unavailable. Once the replicas become available, this status does not change. If you use DDL statements to modify the number of replicas, the replication status will be recalculated.
+- `PROGRESS` means the progress of the replication. The value is between 0.0 and 1.0. 1 means at least one replica is replicated.
+
+### Step 5: analyze data faster using HTAP
+
+If you execute the SQL statements in [Step 3](#step-3-query-with-the-row-based-storage-engine), you can see the performance of TiDB HTAP.
+
+For tables with TiFlash replicas, the TiDB optimizer automatically determines whether to use TiFlash replicas based on the cost estimation. You can use the `desc` or `explain analyze` statement to check whether or not a TiFlash replica is selected. For example:
+
+{{< copyable "sql" >}}
+
+```sql
+explain analyze SELECT
+    l_orderkey,
+    SUM(
+        l_extendedprice * (1 - l_discount)
+    ) AS revenue,
+    o_orderdate,
+    o_shippriority
+FROM
+    customer,
+    orders,
+    lineitem
+WHERE
+    c_mktsegment = 'BUILDING'
+AND c_custkey = o_custkey
+AND l_orderkey = o_orderkey
+AND o_orderdate < DATE '1996-01-01'
+AND l_shipdate > DATE '1996-02-01'
+GROUP BY
+    l_orderkey,
+    o_orderdate,
+    o_shippriority
+ORDER BY
+    revenue DESC,
+    o_orderdate
+limit 10;
+```
+
+If the result of the `EXPLAIN` statement shows `ExchangeSender` and `ExchangeReceiver` operators, it indicates that the MPP mode has taken effect.
+
+In addition, you can specify that each part of the entire query is computed using only the TiFlash. For detailed inforamtion, see [Use TiDB to read TiFlash replicas](/tiflash/use-tiflash.md#use-tidb-to-read-tiflash-replicas).
+
+You can compare query results and query performance of these two methods.
+
+## What's next
+
+- [Architecture of TiDB HTAP](/tiflash/tiflash-overview.md#architecture)
+- [Explore HTAP](/explore-htap.md)
+- [Use TiFlash](/tiflash/use-tiflash.md#use-tiflash)