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

CalvinKirs · 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