reference/sql: add description about when partition pruning works (#2328)

Co-authored-by: yikeke <yikeke@pingcap.com>
Co-authored-by: Lilian Lee <lilin@pingcap.com>

Author: 3 people

reference/sql/partitioning.md

@@ -507,6 +507,108 @@ The optimizer can prune partitions through `WHERE` conditions in the following t
 * partition_column = constant
 * partition_column IN (constant1, constant2, ..., constantN)
 
+### Some cases for partition pruning to take effect
+
+1. Partition pruning uses the query conditions on the partitioned table, so if the query conditions can not be pushed down to the partitioned table according to the planner's optimization rules, partition pruning does not apply for this query.
+
+    For example:
+
+    {{< copyable "sql" >}}
+
+    ```sql
+    create table t1 (x int) partition by range (x) (
+            partition p0 values less than (5),
+            partition p1 values less than (10));
+    create table t2 (x int);
+    ```
+
+    {{< copyable "sql" >}}
+
+    ```sql
+    explain select * from t1 left join t2 on t1.x = t2.x where t2.x > 5;
+    ```
+
+    In this query, the left out join is converted to the inner join, and then `t1.x > 5` is derived from `t1.x = t2.x` and `t2.x > 5`, so it could be used in partition pruning and only the partition `p1` remains.
+
+    ```sql
+    explain select * from t1 left join t2 on t1.x = t2.x and t2.x > 5;
+    ```
+
+    In this query, `t2.x > 5` can not be pushed down to the `t1` partitioned table, so partition pruning would not take effect for this query.
+
+2. Since partition pruning is done during the plan optimizing phase, it does not apply for those cases that filter conditions are unknown until the execution phase.
+
+    For example:
+
+    {{< copyable "sql" >}}
+
+    ```sql
+    create table t1 (x int) partition by range (x) (
+            partition p0 values less than (5),
+            partition p1 values less than (10));
+    ```
+
+    {{< copyable "sql" >}}
+
+    ```sql
+    explain select * from t2 where x < (select * from t1 where t2.x < t1.x and t2.x < 2);
+    ```
+
+    This query reads a row from `t2` and uses the result for the subquery on `t1`. Theoretically, partition pruning could benefit from `t1.x > val` expression in the subquery, but it does not take effect there as that happens in the execution phase.
+
+3. As a result of a limitation from current implementation, if a query condition can not be pushed down to TiKV, it can not be used by the partition pruning.
+
+    Take the `fn(col)` expression as an example. If the TiKV coprocessor supports this `fn` function, `fn(col)` may be pushed down to the the leaf node (that is, partitioned table) according to the predicate push-down rule during the plan optimizing phase, and partition pruning can use it.
+
+    If the TiKV coprocessor does not support this `fn` function, `fn(col)` would not be pushed down to the leaf node. Instead, it becomes a `Selection` node above the leaf node. The current partition pruning implementation does not support this kind of plan tree.
+
+4. For hash partition, the only query supported by partition pruning is the equal condition.
+
+5. For range partition, for partition pruning to take effect, the partition expression must be in those forms: `col` or `fn(col)`, and the query condition must be one of `>`, `<`, `=`, `>=`, and `<=`. If the partition expression is in the form of `fn(col)`, the `fn` function must be monotonous.
+
+    If the `fn` function is monotonous, for any `x` and `y`, if `x > y`, then `fn(x) > fn(y)`. Then this `fn` function can be called strictly monotonous. For any `x` and `y`, if `x > y`, then `fn(x) >= fn(y)`. In this case, `fn` could also be called "monotonous". In theory, all monotonous functions are supported by partition pruning.
+
+    Currently, partition pruning in TiDB only support those monotonous functions:
+
+    ```
+    unix_timestamp
+    to_days
+    ```
+
+    For example, the partition expression is a simple column:
+
+    {{< copyable "sql" >}}
+
+    ```sql
+    create table t (id int) partition by range (id) (
+            partition p0 values less than (5),
+            partition p1 values less than (10));
+    select * from t where t > 6;
+    ```
+
+    Or the partition expression is in the form of `fn(col)` where `fn` is `to_days`:
+
+    {{< copyable "sql" >}}
+
+    ```sql
+    create table t (dt datetime) partition by range (to_days(id)) (
+            partition p0 values less than (to_days('2020-04-01')),
+            partition p1 values less than (to_days('2020-05-01')));
+    select * from t where t > '2020-04-18';
+    ```
+
+    An exception is `floor(unix_timestamp())` as the partition expression. TiDB does some optimization for that case by case, so it is supported by partition pruning.
+
+    {{< copyable "sql" >}}
+
+    ```sql
+    create table t (ts timestamp(3) not null default current_timestamp(3))
+    partition by range (floor(unix_timestamp(ts))) (
+            partition p0 values less than (unix_timestamp('2020-04-01 00:00:00')),
+            partition p1 values less than (unix_timestamp('2020-05-01 00:00:00')));
+    select * from t where t > '2020-04-18 02:00:42.123';
+    ```
+
 ## Partition selection
 
 `SELECT` statements support partition selection, which is implemented by using a `PARTITION` option.