[minor](doc) Add sql manual for stats #27176

apache · Nov 22, 2023 · 3966311 · 3966311
1 parent e06e976
commit 3966311
Show file tree

Hide file tree

Showing 8 changed files with 646 additions and 0 deletions.
diff --git a/...s/sql-manual/sql-reference/Data-Manipulation-Statements/Manipulation/ANALYZE.md b/...s/sql-manual/sql-reference/Data-Manipulation-Statements/Manipulation/ANALYZE.md
@@ -0,0 +1,66 @@
+---
+{
+ "title": "ANALYZE",
+ "language": "en"
+}
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+## ANALYZE
+
+### Name
+
+<version since="2.0"></version>
+
+ANALYZE
+
+### Description
+
+This statement is used to collect statistical information for various columns.
+
+```sql
+ANALYZE < TABLE | DATABASE table_name | db_name > 
+ [ (column_name [, ...]) ]
+ [ [ WITH SYNC ] [ WITH SAMPLE PERCENT | ROWS ] ];
+```
+
+- `table_name`: The specified target table. It can be in the format `db_name.table_name`.
+- `column_name`: The specified target column. It must be an existing column in `table_name`. You can specify multiple column names separated by commas.
+- `sync`: Collect statistics synchronously. Returns after collection. If not specified, it executes asynchronously and returns a JOB ID.
+- `sample percent | rows`: Collect statistics with sampling. You can specify a sampling percentage or a number of sampling rows.
+
+### Example
+
+Collect statistical data for a table with a 10% sampling rate:
+
+```sql
+ANALYZE TABLE lineitem WITH SAMPLE PERCENT 10;
+```
+
+Collect statistical data for a table with a sample of 100,000 rows:
+
+```sql
+ANALYZE TABLE lineitem WITH SAMPLE ROWS 100000;
+```
+
+### Keywords
+
+ANALYZE
diff --git a/docs/en/docs/sql-manual/sql-reference/Show-Statements/SHOW-ANALYZE.md b/docs/en/docs/sql-manual/sql-reference/Show-Statements/SHOW-ANALYZE.md
@@ -0,0 +1,109 @@
+---
+{
+ "title": "SHOW-ANALYZE",
+ "language": "en"
+}
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+## SHOW-ANALYZE
+
+### Name
+
+SHOW ANALYZE
+
+### Description
+
+Use `SHOW ANALYZE` to view information about statistics collection jobs.
+
+Syntax:
+
+```SQL
+SHOW [AUTO] ANALYZE < table_name | job_id >
+ [ WHERE [ STATE = [ "PENDING" | "RUNNING" | "FINISHED" | "FAILED" ] ] ];
+```
+
+- AUTO: Show historical information for automatic collection jobs only. Note that, by default, the status of only the last 20,000 completed automatic collection jobs is retained.
+- table_name: Table name, specify to view statistics job information for that table. It can be in the format `db_name.table_name`. When not specified, it returns information for all statistics jobs.
+- job_id: Job ID for statistics collection, obtained when executing `ANALYZE`. When not specified, this command returns information for all statistics jobs.
+
+Output:
+
+| Column Name | Description |
+| :--------------------- | :--------------- |
+| `job_id` | Job ID |
+| `catalog_name` | Catalog Name |
+| `db_name` | Database Name |
+| `tbl_name` | Table Name |
+| `col_name` | Column Name List |
+| `job_type` | Job Type |
+| `analysis_type` | Analysis Type |
+| `message` | Job Information |
+| `last_exec_time_in_ms` | Last Execution Time |
+| `state` | Job Status |
+| `schedule_type` | Scheduling Method |
+
+Here's an example:
+
+```sql
+mysql> show analyze 245073\G;
+*************************** 1. row ***************************
+ job_id: 245073
+ catalog_name: internal
+ db_name: default_cluster:tpch
+ tbl_name: lineitem
+ col_name: [l_returnflag,l_receiptdate,l_tax,l_shipmode,l_suppkey,l_shipdate,l_commitdate,l_partkey,l_orderkey,l_quantity,l_linestatus,l_comment,l_extendedprice,l_linenumber,l_discount,l_shipinstruct]
+ job_type: MANUAL
+ analysis_type: FUNDAMENTALS
+ message: 
+last_exec_time_in_ms: 2023-11-07 11:00:52
+ state: FINISHED
+ progress: 16 Finished | 0 Failed | 0 In Progress | 16 Total
+ schedule_type: ONCE
+```
+
+<br/>
+
+Each collection job can contain one or more tasks, with each task corresponding to the collection of a column. Users can use the following command to view the completion status of statistics collection for each column.
+
+Syntax:
+
+```sql
+SHOW ANALYZE TASK STATUS [job_id]
+```
+
+Here's an example:
+
+```
+mysql> show analyze task status 20038 ;
++---------+----------+---------+----------------------+----------+
+| task_id | col_name | message | last_exec_time_in_ms | state |
++---------+----------+---------+----------------------+----------+
+| 20039 | col4 | | 2023-06-01 17:22:15 | FINISHED |
+| 20040 | col2 | | 2023-06-01 17:22:15 | FINISHED |
+| 20041 | col3 | | 2023-06-01 17:22:15 | FINISHED |
+| 20042 | col1 | | 2023-06-01 17:22:15 | FINISHED |
++---------+----------+---------+----------------------+----------+
+```
+
+### Keywords
+
+SHOW, ANALYZE
diff --git a/docs/en/docs/sql-manual/sql-reference/Show-Statements/SHOW-COLUMN-STATS.md b/docs/en/docs/sql-manual/sql-reference/Show-Statements/SHOW-COLUMN-STATS.md
@@ -0,0 +1,71 @@
+---
+{
+ "title": "SHOW-COLUMN-STATS",
+ "language": "en"
+}
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+## SHOW-COLUMN-STATS
+
+### Name
+
+SHOW COLUMN STATS
+
+### Description
+
+Use `SHOW COLUMN STATS` to view various statistics data for columns.
+
+Syntax:
+
+```SQL
+SHOW COLUMN [cached] STATS table_name [ (column_name [, ...]) ];
+```
+
+Where:
+
+- cached: Show statistics information in the current FE memory cache.
+- table_name: The target table for collecting statistics. It can be in the format `db_name.table_name`.
+- column_name: Specifies the target column, which must be an existing column in `table_name`. You can specify multiple column names separated by commas.
+
+Here's an example:
+
+```sql
+mysql> show column stats lineitem(l_tax)\G;
+*************************** 1. row ***************************
+ column_name: l_tax
+ count: 6001215.0
+ ndv: 9.0
+ num_null: 0.0
+ data_size: 4.800972E7
+avg_size_byte: 8.0
+ min: 0.00
+ max: 0.08
+ method: FULL
+ type: FUNDAMENTALS
+ trigger: MANUAL
+ query_times: 0
+ updated_time: 2023-11-07 11:00:46
+```
+
+### Keywords
+
+SHOW, TABLE, STATS
diff --git a/docs/en/docs/sql-manual/sql-reference/Show-Statements/SHOW-TABLE-STATS.md b/docs/en/docs/sql-manual/sql-reference/Show-Statements/SHOW-TABLE-STATS.md
@@ -0,0 +1,74 @@
+---
+{
+ "title": "SHOW-TABLE-STATS",
+ "language": "en"
+}
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+## SHOW-TABLE-STATS
+
+### Name
+
+SHOW TABLE STATS
+
+### Description
+
+Use `SHOW TABLE STATS` to view an overview of statistics collection for a table.
+
+Syntax:
+
+```SQL
+SHOW TABLE STATS table_name;
+```
+
+Where:
+
+- table_name: The target table name. It can be in the format `db_name.table_name`.
+
+Output:
+
+| Column Name | Description |
+| :--------------------- | :--------------- |
+| `updated_rows` | Updated rows since the last ANALYZE |
+| `query_times` | Reserved column for recording the number of times the table was queried in future versions |
+| `row_count` | Number of rows (does not reflect the exact number of rows at the time of command execution) |
+| `updated_time` | Last update time |
+| `columns` | Columns for which statistics information has been collected |
+
+Here's an example:
+
+```sql
+mysql> show table stats lineitem \G;
+*************************** 1. row ***************************
+updated_rows: 0
+ query_times: 0
+ row_count: 6001215
+updated_time: 2023-11-07
+ columns: [l_returnflag, l_receiptdate, l_tax, l_shipmode, l_suppkey, l_shipdate, l_commitdate, l_partkey, l_orderkey, l_quantity, l_linestatus, l_comment, l_extendedprice, l_linenumber, l_discount, l_shipinstruct]
+ trigger: MANUAL
+```
+
+<br/>
+
+### Keywords
+
+SHOW, TABLE, STATS
diff --git a/...s/sql-manual/sql-reference/Data-Manipulation-Statements/Manipulation/ANALYZE.md b/...s/sql-manual/sql-reference/Data-Manipulation-Statements/Manipulation/ANALYZE.md
@@ -0,0 +1,66 @@
+---
+{
+ "title": "ANALYZE",
+ "language": "zh-CN"
+}
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+## ANALYZE
+
+### Name
+
+<version since="2.0"></version>
+
+ANALYZE
+
+### Description
+
+该语句用于收集各列的统计信息。
+
+```sql
+ANALYZE < TABLE | DATABASE table_name | db_name > 
+ [ (column_name [, ...]) ]
+ [ [ WITH SYNC ] [ WITH SAMPLE PERCENT | ROWS ] ];
+```
+
+- table_name: 指定的目标表。可以是  `db_name.table_name`  形式。
+- column_name: 指定的目标列。必须是  `table_name`  中存在的列，多个列名称用逗号分隔。
+- sync：同步收集统计信息。收集完后返回。若不指定则异步执行并返回JOB ID。
+- sample percent | rows：抽样收集统计信息。可以指定抽样比例或者抽样行数。
+
+### Example
+
+对一张表按照10%的比例采样收集统计数据：
+
+```sql
+ANALYZE TABLE lineitem WITH SAMPLE PERCENT 10;
+```
+
+对一张表按采样10万行收集统计数据
+
+```sql
+ANALYZE TABLE lineitem WITH SAMPLE ROWS 100000;
+```
+
+### Keywords
+
+ANALYZE