From 58df1ced14ae72f043c7de04a281d110937bbba1 Mon Sep 17 00:00:00 2001 From: Charlotte Liu <37295236+CharLotteiu@users.noreply.github.com> Date: Mon, 1 Feb 2021 11:16:19 +0800 Subject: [PATCH 1/2] cherry pick #4722 to release-3.1 Signed-off-by: ti-srebot --- expression-syntax.md | 45 +++++ sql-statements/sql-statement-add-column.md | 36 ++++ sql-statements/sql-statement-add-index.md | 77 +++++++++ .../sql-statement-admin-cancel-ddl.md | 12 +- .../sql-statement-admin-check-table-index.md | 12 +- .../sql-statement-admin-checksum-table.md | 12 +- .../sql-statement-admin-show-ddl.md | 17 +- sql-statements/sql-statement-admin.md | 7 +- .../sql-statement-alter-database.md | 13 ++ sql-statements/sql-statement-alter-index.md | 154 ++++++++++++++++++ .../sql-statement-alter-instance.md | 13 ++ sql-statements/sql-statement-alter-table.md | 41 +++-- sql-statements/sql-statement-alter-user.md | 19 ++- sql-statements/sql-statement-analyze-table.md | 17 +- 14 files changed, 421 insertions(+), 54 deletions(-) create mode 100644 sql-statements/sql-statement-alter-index.md diff --git a/expression-syntax.md b/expression-syntax.md index 3c1650fb0f31a..fe1cdfb43a73e 100644 --- a/expression-syntax.md +++ b/expression-syntax.md @@ -6,6 +6,7 @@ aliases: ['/docs/v3.1/expression-syntax/','/docs/v3.1/reference/sql/language-str # Expression Syntax +<<<<<<< HEAD The following rules define the expression syntax in TiDB. You can find the definition in `parser/parser.y`. The syntax parsing in TiDB is based on Yacc. ``` @@ -65,4 +66,48 @@ PrimaryExpression: | '+' PrimaryExpression | "BINARY" PrimaryExpression | PrimaryExpression "COLLATE" StringName +======= +An expression is a combination of one or more values, operators, or functions. In TiDB, expressions are mainly used in various clauses of the `SELECT` statement, including Group by clause, Where clause, Having clause, Join condition and window function. In addition, some DDL statements also use expressions, such as the setting of the default values, columns, and partition rules when creating tables. + +The expressions can be divided into the following types: + +- Identifier. For reference, see [Schema object names](/schema-object-names.md). + +- Predicates, numeric values, strings, date expressions. The [Literal values](/literal-values.md) of these types are also expressions. + +- Function calls and window functions. For reference, see [Functions and operators overview](/functions-and-operators/functions-and-operators-overview.md) and [Window functions](/functions-and-operators/window-functions.md) + +- ParamMarker (`?`), system variables, user variables and CASE expressions. + +The following rules are the expression syntax, which is based on the [parser.y](https://github.com/pingcap/parser/blob/master/parser.y) rules of TiDB parser. For the navigable version of the following syntax diagram, refer to [TiDB SQL Syntax Diagram](https://pingcap.github.io/sqlgram/#Expression). + +```ebnf+diagram +Expression ::= + ( singleAtIdentifier assignmentEq | 'NOT' | Expression ( logOr | 'XOR' | logAnd ) ) Expression +| 'MATCH' '(' ColumnNameList ')' 'AGAINST' '(' BitExpr FulltextSearchModifierOpt ')' +| PredicateExpr ( IsOrNotOp 'NULL' | CompareOp ( ( singleAtIdentifier assignmentEq )? PredicateExpr | AnyOrAll SubSelect ) )* ( IsOrNotOp ( trueKwd | falseKwd | 'UNKNOWN' ) )? + +PredicateExpr ::= + BitExpr ( BetweenOrNotOp BitExpr 'AND' BitExpr )* ( InOrNotOp ( '(' ExpressionList ')' | SubSelect ) | LikeOrNotOp SimpleExpr LikeEscapeOpt | RegexpOrNotOp SimpleExpr )? + +BitExpr ::= + BitExpr ( ( '|' | '&' | '<<' | '>>' | '*' | '/' | '%' | 'DIV' | 'MOD' | '^' ) BitExpr | ( '+' | '-' ) ( BitExpr | "INTERVAL" Expression TimeUnit ) ) +| SimpleExpr + +SimpleExpr ::= + SimpleIdent ( ( '->' | '->>' ) stringLit )? +| FunctionCallKeyword +| FunctionCallNonKeyword +| FunctionCallGeneric +| SimpleExpr ( 'COLLATE' CollationName | pipes SimpleExpr ) +| WindowFuncCall +| Literal +| paramMarker +| Variable +| SumExpr +| ( '!' | '~' | '-' | '+' | 'NOT' | 'BINARY' ) SimpleExpr +| 'EXISTS'? SubSelect +| ( ( '(' ( ExpressionList ',' )? | 'ROW' '(' ExpressionList ',' ) Expression | builtinCast '(' Expression 'AS' CastType | ( 'DEFAULT' | 'VALUES' ) '(' SimpleIdent | 'CONVERT' '(' Expression ( ',' CastType | 'USING' CharsetName ) ) ')' +| 'CASE' ExpressionOpt WhenClause+ ElseOpt 'END' +>>>>>>> 4c603f53... sql-statements: use EBNF to render syntax diagrams for ADD, ALTER and ANALYZE statements (#4722) ``` diff --git a/sql-statements/sql-statement-add-column.md b/sql-statements/sql-statement-add-column.md index bbde0704ce3cf..39fe6c7fc6ef0 100644 --- a/sql-statements/sql-statement-add-column.md +++ b/sql-statements/sql-statement-add-column.md @@ -10,6 +10,7 @@ The `ALTER TABLE.. ADD COLUMN` statement adds a column to an existing table. Thi ## Synopsis +<<<<<<< HEAD **AlterTableStmt:** ![AlterTableStmt](/media/sqlgram/AlterTableStmt.png) @@ -29,6 +30,41 @@ The `ALTER TABLE.. ADD COLUMN` statement adds a column to an existing table. Thi **ColumnPosition:** ![ColumnPosition](/media/sqlgram/ColumnPosition.png) +======= +```ebnf+diagram +AlterTableStmt ::= + 'ALTER' IgnoreOptional 'TABLE' TableName ( AlterTableSpecListOpt AlterTablePartitionOpt | 'ANALYZE' 'PARTITION' PartitionNameList ( 'INDEX' IndexNameList )? AnalyzeOptionListOpt ) + +AlterTableSpec ::= + TableOptionList +| 'SET' 'TIFLASH' 'REPLICA' LengthNum LocationLabelList +| 'CONVERT' 'TO' CharsetKw ( CharsetName | 'DEFAULT' ) OptCollate +| 'ADD' ( ColumnKeywordOpt IfNotExists ( ColumnDef ColumnPosition | '(' TableElementList ')' ) | Constraint | 'PARTITION' IfNotExists NoWriteToBinLogAliasOpt ( PartitionDefinitionListOpt | 'PARTITIONS' NUM ) ) +| ( ( 'CHECK' | 'TRUNCATE' ) 'PARTITION' | ( 'OPTIMIZE' | 'REPAIR' | 'REBUILD' ) 'PARTITION' NoWriteToBinLogAliasOpt ) AllOrPartitionNameList +| 'COALESCE' 'PARTITION' NoWriteToBinLogAliasOpt NUM +| 'DROP' ( ColumnKeywordOpt IfExists ColumnName RestrictOrCascadeOpt | 'PRIMARY' 'KEY' | 'PARTITION' IfExists PartitionNameList | ( KeyOrIndex IfExists | 'CHECK' ) Identifier | 'FOREIGN' 'KEY' IfExists Symbol ) +| 'EXCHANGE' 'PARTITION' Identifier 'WITH' 'TABLE' TableName WithValidationOpt +| ( 'IMPORT' | 'DISCARD' ) ( 'PARTITION' AllOrPartitionNameList )? 'TABLESPACE' +| 'REORGANIZE' 'PARTITION' NoWriteToBinLogAliasOpt ReorganizePartitionRuleOpt +| 'ORDER' 'BY' AlterOrderItem ( ',' AlterOrderItem )* +| ( 'DISABLE' | 'ENABLE' ) 'KEYS' +| ( 'MODIFY' ColumnKeywordOpt IfExists | 'CHANGE' ColumnKeywordOpt IfExists ColumnName ) ColumnDef ColumnPosition +| 'ALTER' ( ColumnKeywordOpt ColumnName ( 'SET' 'DEFAULT' ( SignedLiteral | '(' Expression ')' ) | 'DROP' 'DEFAULT' ) | 'CHECK' Identifier EnforcedOrNot | 'INDEX' Identifier IndexInvisible ) +| 'RENAME' ( ( 'COLUMN' | KeyOrIndex ) Identifier 'TO' Identifier | ( 'TO' | '='? | 'AS' ) TableName ) +| LockClause +| AlgorithmClause +| 'FORCE' +| ( 'WITH' | 'WITHOUT' ) 'VALIDATION' +| 'SECONDARY_LOAD' +| 'SECONDARY_UNLOAD' + +ColumnDef ::= + ColumnName ( Type | 'SERIAL' ) ColumnOptionListOpt + +ColumnPosition ::= + ( 'FIRST' | 'AFTER' ColumnName )? +``` +>>>>>>> 4c603f53... sql-statements: use EBNF to render syntax diagrams for ADD, ALTER and ANALYZE statements (#4722) ## Examples diff --git a/sql-statements/sql-statement-add-index.md b/sql-statements/sql-statement-add-index.md index 0728abd6409b6..a541fec58d850 100644 --- a/sql-statements/sql-statement-add-index.md +++ b/sql-statements/sql-statement-add-index.md @@ -10,6 +10,7 @@ The `ALTER TABLE.. ADD INDEX` statement adds an index to an existing table. This ## Synopsis +<<<<<<< HEAD **AlterTableStmt:** ![AlterTableStmt](/media/sqlgram/AlterTableStmt.png) @@ -29,6 +30,82 @@ The `ALTER TABLE.. ADD INDEX` statement adds an index to an existing table. This **ColumnPosition:** ![ColumnPosition](/media/sqlgram/ColumnPosition.png) +======= +```ebnf+diagram +AlterTableStmt ::= + 'ALTER' IgnoreOptional 'TABLE' TableName ( AlterTableSpecListOpt AlterTablePartitionOpt | 'ANALYZE' 'PARTITION' PartitionNameList ( 'INDEX' IndexNameList )? AnalyzeOptionListOpt ) + +AlterTableSpec ::= + TableOptionList +| 'SET' 'TIFLASH' 'REPLICA' LengthNum LocationLabelList +| 'CONVERT' 'TO' CharsetKw ( CharsetName | 'DEFAULT' ) OptCollate +| 'ADD' ( ColumnKeywordOpt IfNotExists ( ColumnDef ColumnPosition | '(' TableElementList ')' ) | Constraint | 'PARTITION' IfNotExists NoWriteToBinLogAliasOpt ( PartitionDefinitionListOpt | 'PARTITIONS' NUM ) ) +| ( ( 'CHECK' | 'TRUNCATE' ) 'PARTITION' | ( 'OPTIMIZE' | 'REPAIR' | 'REBUILD' ) 'PARTITION' NoWriteToBinLogAliasOpt ) AllOrPartitionNameList +| 'COALESCE' 'PARTITION' NoWriteToBinLogAliasOpt NUM +| 'DROP' ( ColumnKeywordOpt IfExists ColumnName RestrictOrCascadeOpt | 'PRIMARY' 'KEY' | 'PARTITION' IfExists PartitionNameList | ( KeyOrIndex IfExists | 'CHECK' ) Identifier | 'FOREIGN' 'KEY' IfExists Symbol ) +| 'EXCHANGE' 'PARTITION' Identifier 'WITH' 'TABLE' TableName WithValidationOpt +| ( 'IMPORT' | 'DISCARD' ) ( 'PARTITION' AllOrPartitionNameList )? 'TABLESPACE' +| 'REORGANIZE' 'PARTITION' NoWriteToBinLogAliasOpt ReorganizePartitionRuleOpt +| 'ORDER' 'BY' AlterOrderItem ( ',' AlterOrderItem )* +| ( 'DISABLE' | 'ENABLE' ) 'KEYS' +| ( 'MODIFY' ColumnKeywordOpt IfExists | 'CHANGE' ColumnKeywordOpt IfExists ColumnName ) ColumnDef ColumnPosition +| 'ALTER' ( ColumnKeywordOpt ColumnName ( 'SET' 'DEFAULT' ( SignedLiteral | '(' Expression ')' ) | 'DROP' 'DEFAULT' ) | 'CHECK' Identifier EnforcedOrNot | 'INDEX' Identifier IndexInvisible ) +| 'RENAME' ( ( 'COLUMN' | KeyOrIndex ) Identifier 'TO' Identifier | ( 'TO' | '='? | 'AS' ) TableName ) +| LockClause +| AlgorithmClause +| 'FORCE' +| ( 'WITH' | 'WITHOUT' ) 'VALIDATION' +| 'SECONDARY_LOAD' +| 'SECONDARY_UNLOAD' + +Constraint ::= + ConstraintKeywordOpt ConstraintElem + +ConstraintKeywordOpt ::= + ( 'CONSTRAINT' Symbol? )? + +ConstraintElem ::= + ( ( 'PRIMARY' 'KEY' | KeyOrIndex IfNotExists | 'UNIQUE' KeyOrIndexOpt ) IndexNameAndTypeOpt | 'FULLTEXT' KeyOrIndexOpt IndexName ) '(' IndexPartSpecificationList ')' IndexOptionList +| 'FOREIGN' 'KEY' IfNotExists IndexName '(' IndexPartSpecificationList ')' ReferDef +| 'CHECK' '(' Expression ')' EnforcedOrNotOpt + +IndexNameAndTypeOpt ::= + IndexName ( 'USING' IndexTypeName )? +| Identifier 'TYPE' IndexTypeName + +IndexPartSpecificationList ::= + IndexPartSpecification ( ',' IndexPartSpecification )* + +IndexPartSpecification ::= + ( ColumnName OptFieldLen | '(' Expression ')' ) Order + +IndexOptionList ::= + IndexOption* + +IndexOption ::= + 'KEY_BLOCK_SIZE' '='? LengthNum +| IndexType +| 'WITH' 'PARSER' Identifier +| 'COMMENT' stringLit +| IndexInvisible + +KeyOrIndex ::= + 'KEY' +| 'INDEX' + +IndexKeyTypeOpt ::= + ( 'UNIQUE' | 'SPATIAL' | 'FULLTEXT' )? + +IndexInvisible ::= + 'VISIBLE' +| 'INVISIBLE' + +IndexTypeName ::= + 'BTREE' +| 'HASH' +| 'RTREE' +``` +>>>>>>> 4c603f53... sql-statements: use EBNF to render syntax diagrams for ADD, ALTER and ANALYZE statements (#4722) ## Examples diff --git a/sql-statements/sql-statement-admin-cancel-ddl.md b/sql-statements/sql-statement-admin-cancel-ddl.md index 2cdc472fe8c2c..ee7c9c421807a 100644 --- a/sql-statements/sql-statement-admin-cancel-ddl.md +++ b/sql-statements/sql-statement-admin-cancel-ddl.md @@ -10,13 +10,13 @@ The `ADMIN CANCEL DDL` statement allows you to cancel a running DDL job. The `jo ## Synopsis -**AdminStmt:** +```ebnf+diagram +AdminStmt ::= + 'ADMIN' ( 'SHOW' ( 'DDL' ( 'JOBS' Int64Num? WhereClauseOptional | 'JOB' 'QUERIES' NumList )? | TableName 'NEXT_ROW_ID' | 'SLOW' AdminShowSlow ) | 'CHECK' ( 'TABLE' TableNameList | 'INDEX' TableName Identifier ( HandleRange ( ',' HandleRange )* )? ) | 'RECOVER' 'INDEX' TableName Identifier | 'CLEANUP' ( 'INDEX' TableName Identifier | 'TABLE' 'LOCK' TableNameList ) | 'CHECKSUM' 'TABLE' TableNameList | 'CANCEL' 'DDL' 'JOBS' NumList | 'RELOAD' ( 'EXPR_PUSHDOWN_BLACKLIST' | 'OPT_RULE_BLACKLIST' | 'BINDINGS' ) | 'PLUGINS' ( 'ENABLE' | 'DISABLE' ) PluginNameList | 'REPAIR' 'TABLE' TableName CreateTableStmt | ( 'FLUSH' | 'CAPTURE' | 'EVOLVE' ) 'BINDINGS' ) -![AdminStmt](/media/sqlgram/AdminStmt.png) - -**NumList:** - -![NumList](/media/sqlgram/NumList.png) +NumList ::= + Int64Num ( ',' Int64Num )* +``` ## Examples diff --git a/sql-statements/sql-statement-admin-check-table-index.md b/sql-statements/sql-statement-admin-check-table-index.md index cd54905600b38..921ca1f739fc9 100644 --- a/sql-statements/sql-statement-admin-check-table-index.md +++ b/sql-statements/sql-statement-admin-check-table-index.md @@ -10,13 +10,13 @@ The `ADMIN CHECK [TABLE|INDEX]` statement checks for data consistency of tables ## Synopsis -**AdminStmt:** +```ebnf+diagram +AdminStmt ::= + 'ADMIN' ( 'SHOW' ( 'DDL' ( 'JOBS' Int64Num? WhereClauseOptional | 'JOB' 'QUERIES' NumList )? | TableName 'NEXT_ROW_ID' | 'SLOW' AdminShowSlow ) | 'CHECK' ( 'TABLE' TableNameList | 'INDEX' TableName Identifier ( HandleRange ( ',' HandleRange )* )? ) | 'RECOVER' 'INDEX' TableName Identifier | 'CLEANUP' ( 'INDEX' TableName Identifier | 'TABLE' 'LOCK' TableNameList ) | 'CHECKSUM' 'TABLE' TableNameList | 'CANCEL' 'DDL' 'JOBS' NumList | 'RELOAD' ( 'EXPR_PUSHDOWN_BLACKLIST' | 'OPT_RULE_BLACKLIST' | 'BINDINGS' ) | 'PLUGINS' ( 'ENABLE' | 'DISABLE' ) PluginNameList | 'REPAIR' 'TABLE' TableName CreateTableStmt | ( 'FLUSH' | 'CAPTURE' | 'EVOLVE' ) 'BINDINGS' ) -![AdminStmt](/media/sqlgram/AdminStmt.png) - -**TableNameList:** - -![TableNameList](/media/sqlgram/TableNameList.png) +TableNameList ::= + TableName ( ',' TableName )* +``` ## Examples diff --git a/sql-statements/sql-statement-admin-checksum-table.md b/sql-statements/sql-statement-admin-checksum-table.md index 3ecb7c6e19b13..80d1ff05028d9 100644 --- a/sql-statements/sql-statement-admin-checksum-table.md +++ b/sql-statements/sql-statement-admin-checksum-table.md @@ -10,13 +10,13 @@ The `ADMIN CHECKSUM TABLE` statement calculates a CRC64 checksum for the data an ## Synopsis -**AdminStmt:** +```ebnf+diagram +AdminStmt ::= + 'ADMIN' ( 'SHOW' ( 'DDL' ( 'JOBS' Int64Num? WhereClauseOptional | 'JOB' 'QUERIES' NumList )? | TableName 'NEXT_ROW_ID' | 'SLOW' AdminShowSlow ) | 'CHECK' ( 'TABLE' TableNameList | 'INDEX' TableName Identifier ( HandleRange ( ',' HandleRange )* )? ) | 'RECOVER' 'INDEX' TableName Identifier | 'CLEANUP' ( 'INDEX' TableName Identifier | 'TABLE' 'LOCK' TableNameList ) | 'CHECKSUM' 'TABLE' TableNameList | 'CANCEL' 'DDL' 'JOBS' NumList | 'RELOAD' ( 'EXPR_PUSHDOWN_BLACKLIST' | 'OPT_RULE_BLACKLIST' | 'BINDINGS' ) | 'PLUGINS' ( 'ENABLE' | 'DISABLE' ) PluginNameList | 'REPAIR' 'TABLE' TableName CreateTableStmt | ( 'FLUSH' | 'CAPTURE' | 'EVOLVE' ) 'BINDINGS' ) -![AdminStmt](/media/sqlgram/AdminStmt.png) - -**TableNameList:** - -![TableNameList](/media/sqlgram/TableNameList.png) +TableNameList ::= + TableName ( ',' TableName )* +``` ## Examples diff --git a/sql-statements/sql-statement-admin-show-ddl.md b/sql-statements/sql-statement-admin-show-ddl.md index 894c23e75c8c8..42c48b9522fc6 100644 --- a/sql-statements/sql-statement-admin-show-ddl.md +++ b/sql-statements/sql-statement-admin-show-ddl.md @@ -9,17 +9,16 @@ The `ADMIN SHOW DDL [JOBS|QUERIES]` statement shows information about running an ## Synopsis -**AdminStmt:** +```ebnf+diagram +AdminStmt ::= + 'ADMIN' ( 'SHOW' ( 'DDL' ( 'JOBS' Int64Num? WhereClauseOptional | 'JOB' 'QUERIES' NumList )? | TableName 'NEXT_ROW_ID' | 'SLOW' AdminShowSlow ) | 'CHECK' ( 'TABLE' TableNameList | 'INDEX' TableName Identifier ( HandleRange ( ',' HandleRange )* )? ) | 'RECOVER' 'INDEX' TableName Identifier | 'CLEANUP' ( 'INDEX' TableName Identifier | 'TABLE' 'LOCK' TableNameList ) | 'CHECKSUM' 'TABLE' TableNameList | 'CANCEL' 'DDL' 'JOBS' NumList | 'RELOAD' ( 'EXPR_PUSHDOWN_BLACKLIST' | 'OPT_RULE_BLACKLIST' | 'BINDINGS' ) | 'PLUGINS' ( 'ENABLE' | 'DISABLE' ) PluginNameList | 'REPAIR' 'TABLE' TableName CreateTableStmt | ( 'FLUSH' | 'CAPTURE' | 'EVOLVE' ) 'BINDINGS' ) -![AdminStmt](/media/sqlgram/AdminStmt.png) +NumList ::= + Int64Num ( ',' Int64Num )* -**NumList:** - -![NumList](/media/sqlgram/NumList.png) - -**WhereClauseOptional:** - -![WhereClauseOptional](/media/sqlgram/WhereClauseOptional.png) +WhereClauseOptional ::= + WhereClause? +``` ## Examples diff --git a/sql-statements/sql-statement-admin.md b/sql-statements/sql-statement-admin.md index 7e9e97e8f918c..faa3652d2bddf 100644 --- a/sql-statements/sql-statement-admin.md +++ b/sql-statements/sql-statement-admin.md @@ -62,9 +62,10 @@ If the consistency check is passed, an empty result is returned. Otherwise, an e ## Synopsis -**AdminStmt:** - -![AdminStmt](/media/sqlgram/AdminStmt.png) +```ebnf+diagram +AdminStmt ::= + 'ADMIN' ( 'SHOW' ( 'DDL' ( 'JOBS' Int64Num? WhereClauseOptional | 'JOB' 'QUERIES' NumList )? | TableName 'NEXT_ROW_ID' | 'SLOW' AdminShowSlow ) | 'CHECK' ( 'TABLE' TableNameList | 'INDEX' TableName Identifier ( HandleRange ( ',' HandleRange )* )? ) | 'RECOVER' 'INDEX' TableName Identifier | 'CLEANUP' ( 'INDEX' TableName Identifier | 'TABLE' 'LOCK' TableNameList ) | 'CHECKSUM' 'TABLE' TableNameList | 'CANCEL' 'DDL' 'JOBS' NumList | 'RELOAD' ( 'EXPR_PUSHDOWN_BLACKLIST' | 'OPT_RULE_BLACKLIST' | 'BINDINGS' ) | 'PLUGINS' ( 'ENABLE' | 'DISABLE' ) PluginNameList | 'REPAIR' 'TABLE' TableName CreateTableStmt | ( 'FLUSH' | 'CAPTURE' | 'EVOLVE' ) 'BINDINGS' ) +``` ## Examples diff --git a/sql-statements/sql-statement-alter-database.md b/sql-statements/sql-statement-alter-database.md index e0c87c56624cb..0cad23e1f0b76 100644 --- a/sql-statements/sql-statement-alter-database.md +++ b/sql-statements/sql-statement-alter-database.md @@ -8,6 +8,19 @@ aliases: ['/docs/v3.1/sql-statements/sql-statement-alter-database/','/docs/v3.1/ `ALTER DATABASE` is used to specify or modify the default character set and collation of the current database. `ALTER SCHEMA` has the same effect as `ALTER DATABASE`. +<<<<<<< HEAD +======= +## Synopsis + +```ebnf+diagram +AlterDatabaseStmt ::= + 'ALTER' 'DATABASE' DBName? DatabaseOptionList + +DatabaseOption ::= + DefaultKwdOpt ( CharsetKw '='? CharsetName | 'COLLATE' '='? CollationName | 'ENCRYPTION' '='? EncryptionOpt ) +``` + +>>>>>>> 4c603f53... sql-statements: use EBNF to render syntax diagrams for ADD, ALTER and ANALYZE statements (#4722) ## Examples ```sql diff --git a/sql-statements/sql-statement-alter-index.md b/sql-statements/sql-statement-alter-index.md new file mode 100644 index 0000000000000..bff21e3ff4fca --- /dev/null +++ b/sql-statements/sql-statement-alter-index.md @@ -0,0 +1,154 @@ +--- +title: ALTER INDEX +summary: An overview of the usage of ALTER INDEX for the TiDB database. +aliases: ['/docs/dev/sql-statements/sql-statement-alter-index/'] +--- + +# ALTER INDEX + +The `ALTER INDEX` statement is used to modify the visibility of the index to `Visible` or `Invisible`. Invisible indexes are maintained by DML statements, but will not be used by the query optimizer. This is useful in scenarios where you want to double-check before removing an index permanently. + +## Synopsis + +```ebnf+diagram +AlterTableStmt ::= + 'ALTER' IgnoreOptional 'TABLE' TableName ( AlterTableSpecListOpt AlterTablePartitionOpt | 'ANALYZE' 'PARTITION' PartitionNameList ( 'INDEX' IndexNameList )? AnalyzeOptionListOpt ) + +AlterTableSpec ::= + TableOptionList +| 'SET' 'TIFLASH' 'REPLICA' LengthNum LocationLabelList +| 'CONVERT' 'TO' CharsetKw ( CharsetName | 'DEFAULT' ) OptCollate +| 'ADD' ( ColumnKeywordOpt IfNotExists ( ColumnDef ColumnPosition | '(' TableElementList ')' ) | Constraint | 'PARTITION' IfNotExists NoWriteToBinLogAliasOpt ( PartitionDefinitionListOpt | 'PARTITIONS' NUM ) ) +| ( ( 'CHECK' | 'TRUNCATE' ) 'PARTITION' | ( 'OPTIMIZE' | 'REPAIR' | 'REBUILD' ) 'PARTITION' NoWriteToBinLogAliasOpt ) AllOrPartitionNameList +| 'COALESCE' 'PARTITION' NoWriteToBinLogAliasOpt NUM +| 'DROP' ( ColumnKeywordOpt IfExists ColumnName RestrictOrCascadeOpt | 'PRIMARY' 'KEY' | 'PARTITION' IfExists PartitionNameList | ( KeyOrIndex IfExists | 'CHECK' ) Identifier | 'FOREIGN' 'KEY' IfExists Symbol ) +| 'EXCHANGE' 'PARTITION' Identifier 'WITH' 'TABLE' TableName WithValidationOpt +| ( 'IMPORT' | 'DISCARD' ) ( 'PARTITION' AllOrPartitionNameList )? 'TABLESPACE' +| 'REORGANIZE' 'PARTITION' NoWriteToBinLogAliasOpt ReorganizePartitionRuleOpt +| 'ORDER' 'BY' AlterOrderItem ( ',' AlterOrderItem )* +| ( 'DISABLE' | 'ENABLE' ) 'KEYS' +| ( 'MODIFY' ColumnKeywordOpt IfExists | 'CHANGE' ColumnKeywordOpt IfExists ColumnName ) ColumnDef ColumnPosition +| 'ALTER' ( ColumnKeywordOpt ColumnName ( 'SET' 'DEFAULT' ( SignedLiteral | '(' Expression ')' ) | 'DROP' 'DEFAULT' ) | 'CHECK' Identifier EnforcedOrNot | 'INDEX' Identifier IndexInvisible ) +| 'RENAME' ( ( 'COLUMN' | KeyOrIndex ) Identifier 'TO' Identifier | ( 'TO' | '='? | 'AS' ) TableName ) +| LockClause +| AlgorithmClause +| 'FORCE' +| ( 'WITH' | 'WITHOUT' ) 'VALIDATION' +| 'SECONDARY_LOAD' +| 'SECONDARY_UNLOAD' + +IndexInvisible ::= + 'VISIBLE' +| 'INVISIBLE' +``` + +## Examples + +You can modify the visibility of an index using the `ALTER TABLE ... ALTER INDEX ...` statement. + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t1 (c1 INT, UNIQUE(c1)); +ALTER TABLE t1 ALTER INDEX c1 INVISIBLE; +``` + +```sql +Query OK, 0 rows affected (0.02 sec) +``` + +{{< copyable "sql" >}} + +```sql +SHOW CREATE TABLE t1; +``` + +```sql ++-------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Table | Create Table + | ++-------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| t1 | CREATE TABLE `t1` ( + `c1` int(11) DEFAULT NULL, + UNIQUE KEY `c1` (`c1`) /*!80000 INVISIBLE */ +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin | ++-------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +1 row in set (0.00 sec) +``` + +The optimizer cannot use the **invisible index** of `c1`. + +{{< copyable "sql" >}} + +```sql +EXPLAIN SELECT c1 FROM t1 ORDER BY c1; +``` + +```sql ++-------------------------+----------+-----------+---------------+--------------------------------+ +| id | estRows | task | access object | operator info | ++-------------------------+----------+-----------+---------------+--------------------------------+ +| Sort_4 | 10000.00 | root | | test.t1.c1:asc | +| └─TableReader_8 | 10000.00 | root | | data:TableFullScan_7 | +| └─TableFullScan_7 | 10000.00 | cop[tikv] | table:t1 | keep order:false, stats:pseudo | ++-------------------------+----------+-----------+---------------+--------------------------------+ +3 rows in set (0.00 sec) +``` + +By comparison, `c2` is a **visible index** and can be used by the optimizer. + +{{< copyable "sql" >}} + +```sql +EXPLAIN SELECT c2 FROM t1 ORDER BY c2; +``` + +```sql ++------------------------+----------+-----------+------------------------+-------------------------------+ +| id | estRows | task | access object | operator info | ++------------------------+----------+-----------+------------------------+-------------------------------+ +| IndexReader_13 | 10000.00 | root | | index:IndexFullScan_12 | +| └─IndexFullScan_12 | 10000.00 | cop[tikv] | table:t1, index:c2(c2) | keep order:true, stats:pseudo | ++------------------------+----------+-----------+------------------------+-------------------------------+ +2 rows in set (0.00 sec) +``` + +Even if you use the `USE INDEX` SQL hint to forcibly use indexes, the optimizer still cannot use invisible indexes; otherwise, an error is returned. + +{{< copyable "sql" >}} + +```sql +SELECT * FROM t1 USE INDEX(c1); +``` + +```sql +ERROR 1176 (42000): Key 'c1' doesn't exist in table 't1' +``` + +> **Note:** +> +> "Invisible" here means invisible only to the optimizer. You can still modify or delete invisible indexes. + +{{< copyable "sql" >}} + +```sql +ALTER TABLE t1 DROP INDEX c1; +``` + +```sql +Query OK, 0 rows affected (0.02 sec) +``` + +## MySQL compatibility + +* Invisible indexes in TiDB are modeled on the equivalent feature from MySQL 8.0. +* Similiar to MySQL, TiDB does not permit `PRIMARY KEY` indexes to be made invisible. +* MySQL provides an optimizer switch `use_invisible_indexes=on` to make all invisible indexes _visible_ again. This functionality is not available in TiDB. + +## See also + +* [CREATE TABLE](/sql-statements/sql-statement-create-table.md) +* [CREATE INDEX](/sql-statements/sql-statement-create-index.md) +* [ADD INDEX](/sql-statements/sql-statement-add-index.md) +* [DROP INDEX](/sql-statements/sql-statement-drop-index.md) +* [RENAME INDEX](/sql-statements/sql-statement-rename-index.md) diff --git a/sql-statements/sql-statement-alter-instance.md b/sql-statements/sql-statement-alter-instance.md index 99ba8a5701353..4b9a207b3f791 100644 --- a/sql-statements/sql-statement-alter-instance.md +++ b/sql-statements/sql-statement-alter-instance.md @@ -18,8 +18,21 @@ When an error occurs during reloading, by default, this error message is returne ## Syntax diagram +<<<<<<< HEAD ![AlterInstanceStmt](/media/sqlgram/AlterInstanceStmt.png) +======= +**AlterInstanceStmt:** + +```ebnf+diagram +AlterInstanceStmt ::= + 'ALTER' 'INSTANCE' InstanceOption + +InstanceOption ::= + 'RELOAD' 'TLS' ('NO' 'ROLLBACK' 'ON' 'ERROR')? +``` + +>>>>>>> 4c603f53... sql-statements: use EBNF to render syntax diagrams for ADD, ALTER and ANALYZE statements (#4722) ## Example {{< copyable "sql" >}} diff --git a/sql-statements/sql-statement-alter-table.md b/sql-statements/sql-statement-alter-table.md index 9b6bd61e60c69..1d1d6b63a105a 100644 --- a/sql-statements/sql-statement-alter-table.md +++ b/sql-statements/sql-statement-alter-table.md @@ -13,17 +13,36 @@ This statement modifies an existing table to conform to a new table structure. T ## Synopsis -**AlterTableStmt:** - -![AlterTableStmt](/media/sqlgram/AlterTableStmt.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) - -**AlterTableSpec:** - -![AlterTableSpec](/media/sqlgram/AlterTableSpec.png) +```ebnf+diagram +AlterTableStmt ::= + 'ALTER' IgnoreOptional 'TABLE' TableName ( AlterTableSpecListOpt AlterTablePartitionOpt | 'ANALYZE' 'PARTITION' PartitionNameList ( 'INDEX' IndexNameList )? AnalyzeOptionListOpt ) + +TableName ::= + Identifier ('.' Identifier)? + +AlterTableSpec ::= + TableOptionList +| 'SET' 'TIFLASH' 'REPLICA' LengthNum LocationLabelList +| 'CONVERT' 'TO' CharsetKw ( CharsetName | 'DEFAULT' ) OptCollate +| 'ADD' ( ColumnKeywordOpt IfNotExists ( ColumnDef ColumnPosition | '(' TableElementList ')' ) | Constraint | 'PARTITION' IfNotExists NoWriteToBinLogAliasOpt ( PartitionDefinitionListOpt | 'PARTITIONS' NUM ) ) +| ( ( 'CHECK' | 'TRUNCATE' ) 'PARTITION' | ( 'OPTIMIZE' | 'REPAIR' | 'REBUILD' ) 'PARTITION' NoWriteToBinLogAliasOpt ) AllOrPartitionNameList +| 'COALESCE' 'PARTITION' NoWriteToBinLogAliasOpt NUM +| 'DROP' ( ColumnKeywordOpt IfExists ColumnName RestrictOrCascadeOpt | 'PRIMARY' 'KEY' | 'PARTITION' IfExists PartitionNameList | ( KeyOrIndex IfExists | 'CHECK' ) Identifier | 'FOREIGN' 'KEY' IfExists Symbol ) +| 'EXCHANGE' 'PARTITION' Identifier 'WITH' 'TABLE' TableName WithValidationOpt +| ( 'IMPORT' | 'DISCARD' ) ( 'PARTITION' AllOrPartitionNameList )? 'TABLESPACE' +| 'REORGANIZE' 'PARTITION' NoWriteToBinLogAliasOpt ReorganizePartitionRuleOpt +| 'ORDER' 'BY' AlterOrderItem ( ',' AlterOrderItem )* +| ( 'DISABLE' | 'ENABLE' ) 'KEYS' +| ( 'MODIFY' ColumnKeywordOpt IfExists | 'CHANGE' ColumnKeywordOpt IfExists ColumnName ) ColumnDef ColumnPosition +| 'ALTER' ( ColumnKeywordOpt ColumnName ( 'SET' 'DEFAULT' ( SignedLiteral | '(' Expression ')' ) | 'DROP' 'DEFAULT' ) | 'CHECK' Identifier EnforcedOrNot | 'INDEX' Identifier IndexInvisible ) +| 'RENAME' ( ( 'COLUMN' | KeyOrIndex ) Identifier 'TO' Identifier | ( 'TO' | '='? | 'AS' ) TableName ) +| LockClause +| AlgorithmClause +| 'FORCE' +| ( 'WITH' | 'WITHOUT' ) 'VALIDATION' +| 'SECONDARY_LOAD' +| 'SECONDARY_UNLOAD' +``` ## Examples diff --git a/sql-statements/sql-statement-alter-user.md b/sql-statements/sql-statement-alter-user.md index e5422184b2850..f5b4062711f8e 100644 --- a/sql-statements/sql-statement-alter-user.md +++ b/sql-statements/sql-statement-alter-user.md @@ -10,17 +10,28 @@ This statement changes an existing user inside the TiDB privilege system. In the ## Synopsis -**AlterUserStmt:** +```ebnf+diagram +AlterUserStmt ::= + 'ALTER' 'USER' IfExists (UserSpecList RequireClauseOpt ConnectionOptions PasswordOrLockOptions | 'USER' '(' ')' 'IDENTIFIED' 'BY' AuthString) -![AlterUserStmt](/media/sqlgram/AlterUserStmt.png) +UserSpecList ::= + UserSpec ( ',' UserSpec )* -**UserSpecList:** +UserSpec ::= + Username AuthOption -![UserSpecList](/media/sqlgram/UserSpecList.png) +Username ::= + StringName ('@' StringName | singleAtIdentifier)? | 'CURRENT_USER' OptionalBraces +<<<<<<< HEAD **UserSpec:** ![UserSpec](/media/sqlgram/UserSpec.png) +======= +AuthOption ::= + ( 'IDENTIFIED' ( 'BY' ( AuthString | 'PASSWORD' HashString ) | 'WITH' StringName ( 'BY' AuthString | 'AS' HashString )? ) )? +``` +>>>>>>> 4c603f53... sql-statements: use EBNF to render syntax diagrams for ADD, ALTER and ANALYZE statements (#4722) ## Examples diff --git a/sql-statements/sql-statement-analyze-table.md b/sql-statements/sql-statement-analyze-table.md index 034cd842f9da4..23cb079b52b4f 100644 --- a/sql-statements/sql-statement-analyze-table.md +++ b/sql-statements/sql-statement-analyze-table.md @@ -12,17 +12,16 @@ TiDB will also automatically update its statistics over time as it discovers tha ## Synopsis -**AnalyzeTableStmt:** +```ebnf+diagram +AnalyzeTableStmt ::= + 'ANALYZE' ( 'TABLE' ( TableNameList | TableName ( 'INDEX' IndexNameList | 'PARTITION' PartitionNameList ( 'INDEX' IndexNameList )? ) ) | 'INCREMENTAL' 'TABLE' TableName ( 'PARTITION' PartitionNameList )? 'INDEX' IndexNameList ) AnalyzeOptionListOpt -![AnalyzeTableStmt](/media/sqlgram/AnalyzeTableStmt.png) +TableNameList ::= + TableName (',' TableName)* -**TableNameList:** - -![TableNameList](/media/sqlgram/TableNameList.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) +TableName ::= + Identifier ( '.' Identifier )? +``` ## Examples From c5c35c5b0ad7125f975fc4f1eb790a0a2b3b26e4 Mon Sep 17 00:00:00 2001 From: Charlotte Liu <37295236+CharLotteiu@users.noreply.github.com> Date: Mon, 1 Feb 2021 12:05:41 +0800 Subject: [PATCH 2/2] resolve conflicts --- expression-syntax.md | 45 ----- sql-statements/sql-statement-add-column.md | 25 +-- sql-statements/sql-statement-add-index.md | 72 +------- .../sql-statement-alter-database.md | 13 -- sql-statements/sql-statement-alter-index.md | 154 ------------------ .../sql-statement-alter-instance.md | 8 - sql-statements/sql-statement-alter-user.md | 12 -- 7 files changed, 9 insertions(+), 320 deletions(-) delete mode 100644 sql-statements/sql-statement-alter-index.md diff --git a/expression-syntax.md b/expression-syntax.md index fe1cdfb43a73e..3c1650fb0f31a 100644 --- a/expression-syntax.md +++ b/expression-syntax.md @@ -6,7 +6,6 @@ aliases: ['/docs/v3.1/expression-syntax/','/docs/v3.1/reference/sql/language-str # Expression Syntax -<<<<<<< HEAD The following rules define the expression syntax in TiDB. You can find the definition in `parser/parser.y`. The syntax parsing in TiDB is based on Yacc. ``` @@ -66,48 +65,4 @@ PrimaryExpression: | '+' PrimaryExpression | "BINARY" PrimaryExpression | PrimaryExpression "COLLATE" StringName -======= -An expression is a combination of one or more values, operators, or functions. In TiDB, expressions are mainly used in various clauses of the `SELECT` statement, including Group by clause, Where clause, Having clause, Join condition and window function. In addition, some DDL statements also use expressions, such as the setting of the default values, columns, and partition rules when creating tables. - -The expressions can be divided into the following types: - -- Identifier. For reference, see [Schema object names](/schema-object-names.md). - -- Predicates, numeric values, strings, date expressions. The [Literal values](/literal-values.md) of these types are also expressions. - -- Function calls and window functions. For reference, see [Functions and operators overview](/functions-and-operators/functions-and-operators-overview.md) and [Window functions](/functions-and-operators/window-functions.md) - -- ParamMarker (`?`), system variables, user variables and CASE expressions. - -The following rules are the expression syntax, which is based on the [parser.y](https://github.com/pingcap/parser/blob/master/parser.y) rules of TiDB parser. For the navigable version of the following syntax diagram, refer to [TiDB SQL Syntax Diagram](https://pingcap.github.io/sqlgram/#Expression). - -```ebnf+diagram -Expression ::= - ( singleAtIdentifier assignmentEq | 'NOT' | Expression ( logOr | 'XOR' | logAnd ) ) Expression -| 'MATCH' '(' ColumnNameList ')' 'AGAINST' '(' BitExpr FulltextSearchModifierOpt ')' -| PredicateExpr ( IsOrNotOp 'NULL' | CompareOp ( ( singleAtIdentifier assignmentEq )? PredicateExpr | AnyOrAll SubSelect ) )* ( IsOrNotOp ( trueKwd | falseKwd | 'UNKNOWN' ) )? - -PredicateExpr ::= - BitExpr ( BetweenOrNotOp BitExpr 'AND' BitExpr )* ( InOrNotOp ( '(' ExpressionList ')' | SubSelect ) | LikeOrNotOp SimpleExpr LikeEscapeOpt | RegexpOrNotOp SimpleExpr )? - -BitExpr ::= - BitExpr ( ( '|' | '&' | '<<' | '>>' | '*' | '/' | '%' | 'DIV' | 'MOD' | '^' ) BitExpr | ( '+' | '-' ) ( BitExpr | "INTERVAL" Expression TimeUnit ) ) -| SimpleExpr - -SimpleExpr ::= - SimpleIdent ( ( '->' | '->>' ) stringLit )? -| FunctionCallKeyword -| FunctionCallNonKeyword -| FunctionCallGeneric -| SimpleExpr ( 'COLLATE' CollationName | pipes SimpleExpr ) -| WindowFuncCall -| Literal -| paramMarker -| Variable -| SumExpr -| ( '!' | '~' | '-' | '+' | 'NOT' | 'BINARY' ) SimpleExpr -| 'EXISTS'? SubSelect -| ( ( '(' ( ExpressionList ',' )? | 'ROW' '(' ExpressionList ',' ) Expression | builtinCast '(' Expression 'AS' CastType | ( 'DEFAULT' | 'VALUES' ) '(' SimpleIdent | 'CONVERT' '(' Expression ( ',' CastType | 'USING' CharsetName ) ) ')' -| 'CASE' ExpressionOpt WhenClause+ ElseOpt 'END' ->>>>>>> 4c603f53... sql-statements: use EBNF to render syntax diagrams for ADD, ALTER and ANALYZE statements (#4722) ``` diff --git a/sql-statements/sql-statement-add-column.md b/sql-statements/sql-statement-add-column.md index 39fe6c7fc6ef0..f3f8e04d09788 100644 --- a/sql-statements/sql-statement-add-column.md +++ b/sql-statements/sql-statement-add-column.md @@ -10,27 +10,6 @@ The `ALTER TABLE.. ADD COLUMN` statement adds a column to an existing table. Thi ## Synopsis -<<<<<<< HEAD -**AlterTableStmt:** - -![AlterTableStmt](/media/sqlgram/AlterTableStmt.png) - -**AlterTableSpec:** - -![AlterTableSpec](/media/sqlgram/AlterTableSpec.png) - -**ColumnKeywordOpt:** - -![ColumnKeywordOpt](/media/sqlgram/ColumnKeywordOpt.png) - -**ColumnDef:** - -![ColumnDef](/media/sqlgram/ColumnDef.png) - -**ColumnPosition:** - -![ColumnPosition](/media/sqlgram/ColumnPosition.png) -======= ```ebnf+diagram AlterTableStmt ::= 'ALTER' IgnoreOptional 'TABLE' TableName ( AlterTableSpecListOpt AlterTablePartitionOpt | 'ANALYZE' 'PARTITION' PartitionNameList ( 'INDEX' IndexNameList )? AnalyzeOptionListOpt ) @@ -58,13 +37,15 @@ AlterTableSpec ::= | 'SECONDARY_LOAD' | 'SECONDARY_UNLOAD' +ColumnKeywordOpt ::= + 'COLUMN'? + ColumnDef ::= ColumnName ( Type | 'SERIAL' ) ColumnOptionListOpt ColumnPosition ::= ( 'FIRST' | 'AFTER' ColumnName )? ``` ->>>>>>> 4c603f53... sql-statements: use EBNF to render syntax diagrams for ADD, ALTER and ANALYZE statements (#4722) ## Examples diff --git a/sql-statements/sql-statement-add-index.md b/sql-statements/sql-statement-add-index.md index a541fec58d850..f24b8e7771404 100644 --- a/sql-statements/sql-statement-add-index.md +++ b/sql-statements/sql-statement-add-index.md @@ -10,27 +10,6 @@ The `ALTER TABLE.. ADD INDEX` statement adds an index to an existing table. This ## Synopsis -<<<<<<< HEAD -**AlterTableStmt:** - -![AlterTableStmt](/media/sqlgram/AlterTableStmt.png) - -**AlterTableSpec:** - -![AlterTableSpec](/media/sqlgram/AlterTableSpec.png) - -**ColumnKeywordOpt:** - -![ColumnKeywordOpt](/media/sqlgram/ColumnKeywordOpt.png) - -**ColumnDef:** - -![ColumnDef](/media/sqlgram/ColumnDef.png) - -**ColumnPosition:** - -![ColumnPosition](/media/sqlgram/ColumnPosition.png) -======= ```ebnf+diagram AlterTableStmt ::= 'ALTER' IgnoreOptional 'TABLE' TableName ( AlterTableSpecListOpt AlterTablePartitionOpt | 'ANALYZE' 'PARTITION' PartitionNameList ( 'INDEX' IndexNameList )? AnalyzeOptionListOpt ) @@ -58,54 +37,15 @@ AlterTableSpec ::= | 'SECONDARY_LOAD' | 'SECONDARY_UNLOAD' -Constraint ::= - ConstraintKeywordOpt ConstraintElem - -ConstraintKeywordOpt ::= - ( 'CONSTRAINT' Symbol? )? - -ConstraintElem ::= - ( ( 'PRIMARY' 'KEY' | KeyOrIndex IfNotExists | 'UNIQUE' KeyOrIndexOpt ) IndexNameAndTypeOpt | 'FULLTEXT' KeyOrIndexOpt IndexName ) '(' IndexPartSpecificationList ')' IndexOptionList -| 'FOREIGN' 'KEY' IfNotExists IndexName '(' IndexPartSpecificationList ')' ReferDef -| 'CHECK' '(' Expression ')' EnforcedOrNotOpt - -IndexNameAndTypeOpt ::= - IndexName ( 'USING' IndexTypeName )? -| Identifier 'TYPE' IndexTypeName - -IndexPartSpecificationList ::= - IndexPartSpecification ( ',' IndexPartSpecification )* - -IndexPartSpecification ::= - ( ColumnName OptFieldLen | '(' Expression ')' ) Order - -IndexOptionList ::= - IndexOption* - -IndexOption ::= - 'KEY_BLOCK_SIZE' '='? LengthNum -| IndexType -| 'WITH' 'PARSER' Identifier -| 'COMMENT' stringLit -| IndexInvisible - -KeyOrIndex ::= - 'KEY' -| 'INDEX' - -IndexKeyTypeOpt ::= - ( 'UNIQUE' | 'SPATIAL' | 'FULLTEXT' )? +ColumnKeywordOpt ::= + 'COLUMN'? -IndexInvisible ::= - 'VISIBLE' -| 'INVISIBLE' +ColumnDef ::= + ColumnName ( Type | 'SERIAL' ) ColumnOptionListOpt -IndexTypeName ::= - 'BTREE' -| 'HASH' -| 'RTREE' +ColumnPosition ::= + ( 'FIRST' | 'AFTER' ColumnName )? ``` ->>>>>>> 4c603f53... sql-statements: use EBNF to render syntax diagrams for ADD, ALTER and ANALYZE statements (#4722) ## Examples diff --git a/sql-statements/sql-statement-alter-database.md b/sql-statements/sql-statement-alter-database.md index 0cad23e1f0b76..e0c87c56624cb 100644 --- a/sql-statements/sql-statement-alter-database.md +++ b/sql-statements/sql-statement-alter-database.md @@ -8,19 +8,6 @@ aliases: ['/docs/v3.1/sql-statements/sql-statement-alter-database/','/docs/v3.1/ `ALTER DATABASE` is used to specify or modify the default character set and collation of the current database. `ALTER SCHEMA` has the same effect as `ALTER DATABASE`. -<<<<<<< HEAD -======= -## Synopsis - -```ebnf+diagram -AlterDatabaseStmt ::= - 'ALTER' 'DATABASE' DBName? DatabaseOptionList - -DatabaseOption ::= - DefaultKwdOpt ( CharsetKw '='? CharsetName | 'COLLATE' '='? CollationName | 'ENCRYPTION' '='? EncryptionOpt ) -``` - ->>>>>>> 4c603f53... sql-statements: use EBNF to render syntax diagrams for ADD, ALTER and ANALYZE statements (#4722) ## Examples ```sql diff --git a/sql-statements/sql-statement-alter-index.md b/sql-statements/sql-statement-alter-index.md deleted file mode 100644 index bff21e3ff4fca..0000000000000 --- a/sql-statements/sql-statement-alter-index.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -title: ALTER INDEX -summary: An overview of the usage of ALTER INDEX for the TiDB database. -aliases: ['/docs/dev/sql-statements/sql-statement-alter-index/'] ---- - -# ALTER INDEX - -The `ALTER INDEX` statement is used to modify the visibility of the index to `Visible` or `Invisible`. Invisible indexes are maintained by DML statements, but will not be used by the query optimizer. This is useful in scenarios where you want to double-check before removing an index permanently. - -## Synopsis - -```ebnf+diagram -AlterTableStmt ::= - 'ALTER' IgnoreOptional 'TABLE' TableName ( AlterTableSpecListOpt AlterTablePartitionOpt | 'ANALYZE' 'PARTITION' PartitionNameList ( 'INDEX' IndexNameList )? AnalyzeOptionListOpt ) - -AlterTableSpec ::= - TableOptionList -| 'SET' 'TIFLASH' 'REPLICA' LengthNum LocationLabelList -| 'CONVERT' 'TO' CharsetKw ( CharsetName | 'DEFAULT' ) OptCollate -| 'ADD' ( ColumnKeywordOpt IfNotExists ( ColumnDef ColumnPosition | '(' TableElementList ')' ) | Constraint | 'PARTITION' IfNotExists NoWriteToBinLogAliasOpt ( PartitionDefinitionListOpt | 'PARTITIONS' NUM ) ) -| ( ( 'CHECK' | 'TRUNCATE' ) 'PARTITION' | ( 'OPTIMIZE' | 'REPAIR' | 'REBUILD' ) 'PARTITION' NoWriteToBinLogAliasOpt ) AllOrPartitionNameList -| 'COALESCE' 'PARTITION' NoWriteToBinLogAliasOpt NUM -| 'DROP' ( ColumnKeywordOpt IfExists ColumnName RestrictOrCascadeOpt | 'PRIMARY' 'KEY' | 'PARTITION' IfExists PartitionNameList | ( KeyOrIndex IfExists | 'CHECK' ) Identifier | 'FOREIGN' 'KEY' IfExists Symbol ) -| 'EXCHANGE' 'PARTITION' Identifier 'WITH' 'TABLE' TableName WithValidationOpt -| ( 'IMPORT' | 'DISCARD' ) ( 'PARTITION' AllOrPartitionNameList )? 'TABLESPACE' -| 'REORGANIZE' 'PARTITION' NoWriteToBinLogAliasOpt ReorganizePartitionRuleOpt -| 'ORDER' 'BY' AlterOrderItem ( ',' AlterOrderItem )* -| ( 'DISABLE' | 'ENABLE' ) 'KEYS' -| ( 'MODIFY' ColumnKeywordOpt IfExists | 'CHANGE' ColumnKeywordOpt IfExists ColumnName ) ColumnDef ColumnPosition -| 'ALTER' ( ColumnKeywordOpt ColumnName ( 'SET' 'DEFAULT' ( SignedLiteral | '(' Expression ')' ) | 'DROP' 'DEFAULT' ) | 'CHECK' Identifier EnforcedOrNot | 'INDEX' Identifier IndexInvisible ) -| 'RENAME' ( ( 'COLUMN' | KeyOrIndex ) Identifier 'TO' Identifier | ( 'TO' | '='? | 'AS' ) TableName ) -| LockClause -| AlgorithmClause -| 'FORCE' -| ( 'WITH' | 'WITHOUT' ) 'VALIDATION' -| 'SECONDARY_LOAD' -| 'SECONDARY_UNLOAD' - -IndexInvisible ::= - 'VISIBLE' -| 'INVISIBLE' -``` - -## Examples - -You can modify the visibility of an index using the `ALTER TABLE ... ALTER INDEX ...` statement. - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (c1 INT, UNIQUE(c1)); -ALTER TABLE t1 ALTER INDEX c1 INVISIBLE; -``` - -```sql -Query OK, 0 rows affected (0.02 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW CREATE TABLE t1; -``` - -```sql -+-------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Table | Create Table - | -+-------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| t1 | CREATE TABLE `t1` ( - `c1` int(11) DEFAULT NULL, - UNIQUE KEY `c1` (`c1`) /*!80000 INVISIBLE */ -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin | -+-------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -1 row in set (0.00 sec) -``` - -The optimizer cannot use the **invisible index** of `c1`. - -{{< copyable "sql" >}} - -```sql -EXPLAIN SELECT c1 FROM t1 ORDER BY c1; -``` - -```sql -+-------------------------+----------+-----------+---------------+--------------------------------+ -| id | estRows | task | access object | operator info | -+-------------------------+----------+-----------+---------------+--------------------------------+ -| Sort_4 | 10000.00 | root | | test.t1.c1:asc | -| └─TableReader_8 | 10000.00 | root | | data:TableFullScan_7 | -| └─TableFullScan_7 | 10000.00 | cop[tikv] | table:t1 | keep order:false, stats:pseudo | -+-------------------------+----------+-----------+---------------+--------------------------------+ -3 rows in set (0.00 sec) -``` - -By comparison, `c2` is a **visible index** and can be used by the optimizer. - -{{< copyable "sql" >}} - -```sql -EXPLAIN SELECT c2 FROM t1 ORDER BY c2; -``` - -```sql -+------------------------+----------+-----------+------------------------+-------------------------------+ -| id | estRows | task | access object | operator info | -+------------------------+----------+-----------+------------------------+-------------------------------+ -| IndexReader_13 | 10000.00 | root | | index:IndexFullScan_12 | -| └─IndexFullScan_12 | 10000.00 | cop[tikv] | table:t1, index:c2(c2) | keep order:true, stats:pseudo | -+------------------------+----------+-----------+------------------------+-------------------------------+ -2 rows in set (0.00 sec) -``` - -Even if you use the `USE INDEX` SQL hint to forcibly use indexes, the optimizer still cannot use invisible indexes; otherwise, an error is returned. - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1 USE INDEX(c1); -``` - -```sql -ERROR 1176 (42000): Key 'c1' doesn't exist in table 't1' -``` - -> **Note:** -> -> "Invisible" here means invisible only to the optimizer. You can still modify or delete invisible indexes. - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 DROP INDEX c1; -``` - -```sql -Query OK, 0 rows affected (0.02 sec) -``` - -## MySQL compatibility - -* Invisible indexes in TiDB are modeled on the equivalent feature from MySQL 8.0. -* Similiar to MySQL, TiDB does not permit `PRIMARY KEY` indexes to be made invisible. -* MySQL provides an optimizer switch `use_invisible_indexes=on` to make all invisible indexes _visible_ again. This functionality is not available in TiDB. - -## See also - -* [CREATE TABLE](/sql-statements/sql-statement-create-table.md) -* [CREATE INDEX](/sql-statements/sql-statement-create-index.md) -* [ADD INDEX](/sql-statements/sql-statement-add-index.md) -* [DROP INDEX](/sql-statements/sql-statement-drop-index.md) -* [RENAME INDEX](/sql-statements/sql-statement-rename-index.md) diff --git a/sql-statements/sql-statement-alter-instance.md b/sql-statements/sql-statement-alter-instance.md index 4b9a207b3f791..57e221b9cdede 100644 --- a/sql-statements/sql-statement-alter-instance.md +++ b/sql-statements/sql-statement-alter-instance.md @@ -18,21 +18,13 @@ When an error occurs during reloading, by default, this error message is returne ## Syntax diagram -<<<<<<< HEAD -![AlterInstanceStmt](/media/sqlgram/AlterInstanceStmt.png) - -======= **AlterInstanceStmt:** ```ebnf+diagram AlterInstanceStmt ::= 'ALTER' 'INSTANCE' InstanceOption - -InstanceOption ::= - 'RELOAD' 'TLS' ('NO' 'ROLLBACK' 'ON' 'ERROR')? ``` ->>>>>>> 4c603f53... sql-statements: use EBNF to render syntax diagrams for ADD, ALTER and ANALYZE statements (#4722) ## Example {{< copyable "sql" >}} diff --git a/sql-statements/sql-statement-alter-user.md b/sql-statements/sql-statement-alter-user.md index f5b4062711f8e..0ac8a78aaf12a 100644 --- a/sql-statements/sql-statement-alter-user.md +++ b/sql-statements/sql-statement-alter-user.md @@ -19,19 +19,7 @@ UserSpecList ::= UserSpec ::= Username AuthOption - -Username ::= - StringName ('@' StringName | singleAtIdentifier)? | 'CURRENT_USER' OptionalBraces - -<<<<<<< HEAD -**UserSpec:** - -![UserSpec](/media/sqlgram/UserSpec.png) -======= -AuthOption ::= - ( 'IDENTIFIED' ( 'BY' ( AuthString | 'PASSWORD' HashString ) | 'WITH' StringName ( 'BY' AuthString | 'AS' HashString )? ) )? ``` ->>>>>>> 4c603f53... sql-statements: use EBNF to render syntax diagrams for ADD, ALTER and ANALYZE statements (#4722) ## Examples