- Docs Home
- About TiDB Cloud
- Get Started
- Develop Applications
- Overview
- Quick Start
- Build a TiDB Developer Cluster
- CRUD SQL in TiDB
- Build a Simple CRUD App with TiDB
- Example Applications
- Connect to TiDB
- Design Database Schema
- Write Data
- Read Data
- Transaction
- Optimize
- Troubleshoot
- Reference
- Cloud Native Development Environment
- Manage Cluster
- Plan Your Cluster
- Create a TiDB Cluster
- Connect to Your TiDB Cluster
- Set Up VPC Peering Connections
- Use an HTAP Cluster with TiFlash
- Scale a TiDB Cluster
- Upgrade a TiDB Cluster
- Delete a TiDB Cluster
- Use TiDB Cloud API (Beta)
- Migrate Data
- Import Sample Data
- Migrate Data into TiDB
- Configure Amazon S3 Access and GCS Access
- Migrate from MySQL-Compatible Databases
- Migrate Incremental Data from MySQL-Compatible Databases
- Migrate from Amazon Aurora MySQL in Bulk
- Import or Migrate from Amazon S3 or GCS to TiDB Cloud
- Import CSV Files from Amazon S3 or GCS into TiDB Cloud
- Import Apache Parquet Files from Amazon S3 or GCS into TiDB Cloud
- Troubleshoot Access Denied Errors during Data Import from Amazon S3
- Export Data from TiDB
- Back Up and Restore
- Monitor and Alert
- Overview
- Built-in Monitoring
- Built-in Alerting
- Third-Party Monitoring Integrations
- Tune Performance
- Overview
- Analyze Performance
- SQL Tuning
- Overview
- Understanding the Query Execution Plan
- SQL Optimization Process
- Overview
- Logic Optimization
- Physical Optimization
- Prepare Execution Plan Cache
- Control Execution Plans
- TiKV Follower Read
- Coprocessor Cache
- Garbage Collection (GC)
- Tune TiFlash performance
- Manage User Access
- Billing
- Reference
- TiDB Cluster Architecture
- TiDB Cloud Cluster Limits and Quotas
- TiDB Limitations
- SQL
- Explore SQL with TiDB
- SQL Language Structure and Syntax
- SQL Statements
ADD COLUMN
ADD INDEX
ADMIN
ADMIN CANCEL DDL
ADMIN CHECKSUM TABLE
ADMIN CHECK [TABLE|INDEX]
ADMIN SHOW DDL [JOBS|QUERIES]
ALTER DATABASE
ALTER INDEX
ALTER TABLE
ALTER TABLE COMPACT
ALTER USER
ANALYZE TABLE
BATCH
BEGIN
CHANGE COLUMN
COMMIT
CHANGE DRAINER
CHANGE PUMP
CREATE [GLOBAL|SESSION] BINDING
CREATE DATABASE
CREATE INDEX
CREATE ROLE
CREATE SEQUENCE
CREATE TABLE LIKE
CREATE TABLE
CREATE USER
CREATE VIEW
DEALLOCATE
DELETE
DESC
DESCRIBE
DO
DROP [GLOBAL|SESSION] BINDING
DROP COLUMN
DROP DATABASE
DROP INDEX
DROP ROLE
DROP SEQUENCE
DROP STATS
DROP TABLE
DROP USER
DROP VIEW
EXECUTE
EXPLAIN ANALYZE
EXPLAIN
FLASHBACK TABLE
FLUSH PRIVILEGES
FLUSH STATUS
FLUSH TABLES
GRANT <privileges>
GRANT <role>
INSERT
KILL [TIDB]
MODIFY COLUMN
PREPARE
RECOVER TABLE
RENAME INDEX
RENAME TABLE
REPLACE
REVOKE <privileges>
REVOKE <role>
ROLLBACK
SELECT
SET DEFAULT ROLE
SET [NAMES|CHARACTER SET]
SET PASSWORD
SET ROLE
SET TRANSACTION
SET [GLOBAL|SESSION] <variable>
SHOW ANALYZE STATUS
SHOW [GLOBAL|SESSION] BINDINGS
SHOW BUILTINS
SHOW CHARACTER SET
SHOW COLLATION
SHOW [FULL] COLUMNS FROM
SHOW CREATE SEQUENCE
SHOW CREATE TABLE
SHOW CREATE USER
SHOW DATABASES
SHOW DRAINER STATUS
SHOW ENGINES
SHOW ERRORS
SHOW [FULL] FIELDS FROM
SHOW GRANTS
SHOW INDEX [FROM|IN]
SHOW INDEXES [FROM|IN]
SHOW KEYS [FROM|IN]
SHOW MASTER STATUS
SHOW PLUGINS
SHOW PRIVILEGES
SHOW [FULL] PROCESSSLIST
SHOW PROFILES
SHOW PUMP STATUS
SHOW SCHEMAS
SHOW STATS_HEALTHY
SHOW STATS_HISTOGRAMS
SHOW STATS_META
SHOW STATUS
SHOW TABLE NEXT_ROW_ID
SHOW TABLE REGIONS
SHOW TABLE STATUS
SHOW [FULL] TABLES
SHOW [GLOBAL|SESSION] VARIABLES
SHOW WARNINGS
SHUTDOWN
SPLIT REGION
START TRANSACTION
TABLE
TRACE
TRUNCATE
UPDATE
USE
WITH
- Data Types
- Functions and Operators
- Overview
- Type Conversion in Expression Evaluation
- Operators
- Control Flow Functions
- String Functions
- Numeric Functions and Operators
- Date and Time Functions
- Bit Functions and Operators
- Cast Functions and Operators
- Encryption and Compression Functions
- Locking Functions
- Information Functions
- JSON Functions
- Aggregate (GROUP BY) Functions
- Window Functions
- Miscellaneous Functions
- Precision Math
- Set Operations
- List of Expressions for Pushdown
- TiDB Specific Functions
- Clustered Indexes
- Constraints
- Generated Columns
- SQL Mode
- Table Attributes
- Transactions
- Views
- Partitioning
- Temporary Tables
- Cached Tables
- Character Set and Collation
- Read Historical Data
- System Tables
mysql
- INFORMATION_SCHEMA
- Overview
ANALYZE_STATUS
CLIENT_ERRORS_SUMMARY_BY_HOST
CLIENT_ERRORS_SUMMARY_BY_USER
CLIENT_ERRORS_SUMMARY_GLOBAL
CHARACTER_SETS
CLUSTER_INFO
COLLATIONS
COLLATION_CHARACTER_SET_APPLICABILITY
COLUMNS
DATA_LOCK_WAITS
DDL_JOBS
DEADLOCKS
ENGINES
KEY_COLUMN_USAGE
PARTITIONS
PROCESSLIST
REFERENTIAL_CONSTRAINTS
SCHEMATA
SEQUENCES
SESSION_VARIABLES
SLOW_QUERY
STATISTICS
TABLES
TABLE_CONSTRAINTS
TABLE_STORAGE_STATS
TIDB_HOT_REGIONS_HISTORY
TIDB_INDEXES
TIDB_SERVERS_INFO
TIDB_TRX
TIFLASH_REPLICA
TIKV_REGION_PEERS
TIKV_REGION_STATUS
TIKV_STORE_STATUS
USER_PRIVILEGES
VIEWS
- System Variables
- API Reference
- Storage Engines
- Dumpling
- Table Filter
- Troubleshoot Inconsistency Between Data and Indexes
- FAQs
- Release Notes
- Support
- Glossary
The Blocklist of Optimization Rules and Expression Pushdown
This document introduces how to use the blocklist of optimization rules and the blocklist of expression pushdown to control the behavior of TiDB.
The blocklist of optimization rules
The blocklist of optimization rules is one way to tune optimization rules, mainly used to manually disable some optimization rules.
Important optimization rules
Optimization Rule | Rule Name | Description |
---|---|---|
Column pruning | column_prune | One operator will prune the column if it is not needed by the upper executor. |
Decorrelate subquery | decorrelate | Tries to rewrite the correlated subquery to non-correlated join or aggregation. |
Aggregation elimination | aggregation_eliminate | Tries to remove unnecessary aggregation operators from the execution plan. |
Projection elimination | projection_eliminate | Removes unnecessary projection operators from the execution plan. |
Max/Min elimination | max_min_eliminate | Rewrites some max/min functions in aggregation to the order by + limit 1 form. |
Predicate pushdown | predicate_push_down | Tries to push predicates down to the operator that is closer to the data source. |
Outer join elimination | outer_join_eliminate | Tries to remove the unnecessary left join or right join from the execution plan. |
Partition pruning | partition_processor | Prunes partitions which are rejected by the predicates and rewrite partitioned table query to the UnionAll + Partition Datasource form. |
Aggregation pushdown | aggregation_push_down | Tries to push aggregations down to their children. |
TopN pushdown | topn_push_down | Tries to push the TopN operator to the place closer to the data source. |
Join reorder | join_reorder | Decides the order of multi-table joins. |
Disable optimization rules
You can use the blocklist of optimization rules to disable some of them if some rules lead to a sub-optimal execution plan for special queries.
Usage
All the following operations need the super privilege
privilege of the database. Each optimization rule has a name. For example, the name of column pruning is column_prune
. The names of all optimization rules can be found in the second column of the table Important Optimization Rules.
If you want to disable some rules, write its name to the
mysql.opt_rule_blacklist
table. For example:INSERT INTO mysql.opt_rule_blacklist VALUES("join_reorder"), ("topn_push_down");
Executing the following SQL statement can make the above operation take effect immediately. The effective range includes all old connections of the corresponding TiDB server:
admin reload opt_rule_blacklist;
Noteadmin reload opt_rule_blacklist
only takes effect on the TiDB server where the above statement has been run. If you want all TiDB servers of the cluster to take effect, run this command on each TiDB server.If you want to re-enable a rule, delete the corresponding data in the table, and then run the
admin reload
statement:DELETE FROM mysql.opt_rule_blacklist WHERE name IN ("join_reorder", "topn_push_down");
admin reload opt_rule_blacklist;
The blocklist of expression pushdown
The blocklist of expression pushdown is one way to tune the expression pushdown, mainly used to manually disable some expressions of some specific data types.
Expressions which are supported to be pushed down
Expression Classification | Concrete Operations |
---|---|
Logical operations | AND (&&), OR (||), NOT (!) |
Comparison functions and operators | <, <=, =, != (<> ), >, >=, <=> , IN() , IS NULL, LIKE, IS TRUE, IS FALSE, COALESCE() |
Numeric functions and operators | +, -, *, /, ABS() , CEIL() , CEILING() , FLOOR() |
Control flow functions | CASE , IF() , IFNULL() |
JSON functions | JSON_TYPE(json_val), JSON_EXTRACT(json_doc, path[, path] ...), JSON_UNQUOTE(json_val), JSON_OBJECT(key, val[, key, val] ...), JSON_ARRAY([val[, val] ...]), JSON_MERGE(json_doc, json_doc[, json_doc] ...), JSON_SET(json_doc, path, val[, path, val] ...), JSON_INSERT(json_doc, path, val[, path, val] ...), JSON_REPLACE(json_doc, path, val[, path, val] ...), JSON_REMOVE(json_doc, path[, path] ...) |
Date and time functions | DATE_FORMAT() |
Disable the pushdown of specific expressions
When you get wrong results due to the expression pushdown, you can use the blocklist to make a quick recovery for the application. More specifically, you can add some of the supported functions or operators to the mysql.expr_pushdown_blacklist
table to disable the pushdown of specific expressions.
The schema of mysql.expr_pushdown_blacklist
is shown as follows:
DESC mysql.expr_pushdown_blacklist;
+------------+--------------+------+------+-------------------+-------+
| Field | Type | Null | Key | Default | Extra |
+------------+--------------+------+------+-------------------+-------+
| name | char(100) | NO | | NULL | |
| store_type | char(100) | NO | | tikv,tiflash,tidb | |
| reason | varchar(200) | YES | | NULL | |
+------------+--------------+------+------+-------------------+-------+
3 rows in set (0.00 sec)
Here is the description of each field above:
name
: The name of the function that is disabled to be pushed down.store_type
: To specify the component that you want to prevent the function from being pushed down to for computing. Available components aretidb
,tikv
, andtiflash
. Thestore_type
is case-insensitive. If you need to specify multiple components, use a comma to separate each component.- When
store_type
istidb
, it indicates whether the function can be executed in other TiDB servers while the TiDB memory table is being read. - When
store_type
istikv
, it indicates whether the function can be executed in TiKV server's Coprocessor component. - When
store_type
istiflash
, it indicates whether the function can be executed in TiFlash Server's Coprocessor component.
- When
reason
: To record the reason why this function is added to the blocklist.
Usage
This section describes how to use the blocklist of expression pushdown.
Add to the blocklist
To add one or more expressions (functions or operators) to the blocklist, perform the following steps:
Insert the corresponding function name or operator name, and the set of components you want to disable the pushdown, to the
mysql.expr_pushdown_blacklist
table.Execute
admin reload expr_pushdown_blacklist
.
Remove from the blocklist
To remove one or more expressions from the blocklist, perform the following steps:
Delete the corresponding function name or operator name, and the set of components you want to disable the pushdown, from the
mysql.expr_pushdown_blacklist
table.Execute
admin reload expr_pushdown_blacklist
.
admin reload expr_pushdown_blacklist
only takes effect on the TiDB server where this statement is run. If you want all TiDB servers of the cluster to take effect, run this command on each TiDB server.
Expression blocklist usage example
In the following example, the <
and >
operators are added to the blocklist, and then the >
operator is removed from the blocklist.
To judge whether the blocklist takes effect, observe the results of EXPLAIN
(See TiDB Query Execution Plan Overview).
The predicates
a < 2
anda > 2
in theWHERE
clause of the following SQL statement can be pushed down to TiKV.EXPLAIN SELECT * FROM t WHERE a < 2 AND a > 2;
+-------------------------+----------+-----------+---------------+------------------------------------+ | id | estRows | task | access object | operator info | +-------------------------+----------+-----------+---------------+------------------------------------+ | TableReader_7 | 0.00 | root | | data:Selection_6 | | └─Selection_6 | 0.00 | cop[tikv] | | gt(ssb_1.t.a, 2), lt(ssb_1.t.a, 2) | | └─TableFullScan_5 | 10000.00 | cop[tikv] | table:t | keep order:false, stats:pseudo | +-------------------------+----------+-----------+---------------+------------------------------------+ 3 rows in set (0.00 sec)
Insert the expression to the
mysql.expr_pushdown_blacklist
table and executeadmin reload expr_pushdown_blacklist
.INSERT INTO mysql.expr_pushdown_blacklist VALUES('<','tikv',''), ('>','tikv','');
Query OK, 2 rows affected (0.01 sec) Records: 2 Duplicates: 0 Warnings: 0
admin reload expr_pushdown_blacklist;
Query OK, 0 rows affected (0.00 sec)
Observe the execution plan again and you will find that both the
<
and>
operators are not pushed down to TiKV Coprocessor.EXPLAIN SELECT * FROM t WHERE a < 2 and a > 2;
+-------------------------+----------+-----------+---------------+------------------------------------+ | id | estRows | task | access object | operator info | +-------------------------+----------+-----------+---------------+------------------------------------+ | Selection_7 | 10000.00 | root | | gt(ssb_1.t.a, 2), lt(ssb_1.t.a, 2) | | └─TableReader_6 | 10000.00 | root | | data:TableFullScan_5 | | └─TableFullScan_5 | 10000.00 | cop[tikv] | table:t | keep order:false, stats:pseudo | +-------------------------+----------+-----------+---------------+------------------------------------+ 3 rows in set (0.00 sec)
Remove one expression (here is
>
) from the blocklist and executeadmin reload expr_pushdown_blacklist
.DELETE FROM mysql.expr_pushdown_blacklist WHERE name = '>';
Query OK, 1 row affected (0.01 sec)
admin reload expr_pushdown_blacklist;
Query OK, 0 rows affected (0.00 sec)
Observe the execution plan again and you will find that
<
is not pushed down while>
is pushed down to TiKV Coprocessor.EXPLAIN SELECT * FROM t WHERE a < 2 AND a > 2;
+---------------------------+----------+-----------+---------------+--------------------------------+ | id | estRows | task | access object | operator info | +---------------------------+----------+-----------+---------------+--------------------------------+ | Selection_8 | 0.00 | root | | lt(ssb_1.t.a, 2) | | └─TableReader_7 | 0.00 | root | | data:Selection_6 | | └─Selection_6 | 0.00 | cop[tikv] | | gt(ssb_1.t.a, 2) | | └─TableFullScan_5 | 10000.00 | cop[tikv] | table:t | keep order:false, stats:pseudo | +---------------------------+----------+-----------+---------------+--------------------------------+ 4 rows in set (0.00 sec)