Skip to content

Commit 5556200

Browse files
BohuTANGBohuTANG
authored
fix: restore WITH clause documentation and improve SQL reference pages (#2730)
* fix: restore WITH clause documentation and improve SQL reference pages - Restored lost WITH clause documentation with syntax, examples, and usage notes - Improved SQL reference index pages with clean 2-column table format - Fixed MDX compilation error by escaping angle brackets in operators - Organized content into logical categories for better navigation * fix: add .md extension to administration command links
1 parent 4135f9f commit 5556200

File tree

7 files changed

+289
-84
lines changed

7 files changed

+289
-84
lines changed

‎docs/en/sql-reference/10-sql-commands/00-ddl/index.md‎

Lines changed: 56 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -4,50 +4,59 @@ title: DDL (Data Definition Language) Commands
44

55
These topics provide reference information for the DDL (Data Definition Language) commands in Databend.
66

7-
## Database and Table Management
8-
9-
- [Database](00-database/index.md)
10-
- [Table](01-table/index.md)
11-
- [View](05-view/index.md)
12-
- [Dictionary](17-dictionary/index.md)
13-
14-
## Database Performance and Indexing
15-
16-
- [Cluster Key](06-clusterkey/index.md)
17-
- [Aggregating Index](07-aggregating-index/index.md)
18-
- [Inverted Index](07-inverted-index/index.md)
19-
- [Ngram Index](07-ngram-index/index.md)
20-
- [Virtual Column](07-virtual-column/index.md)
21-
22-
## User, Role, and Security Management
23-
24-
- [User](02-user/index.md)
25-
- [Network Policy](12-network-policy/index.md)
26-
- [Mask Policy](12-mask-policy/index.md)
27-
- [Password Policy](12-password-policy/index.md)
28-
29-
## Data Staging and Processing
30-
31-
- [Stage](03-stage/index.md)
32-
- [Stream](04-stream/index.md)
33-
- [Sequence](04-sequence/index.md)
34-
- [Task](04-task/index.md)
35-
- [Connection](13-connection/index.md)
36-
- [File Format](13-file-format/index.md)
37-
38-
## Transaction and Variable Management
39-
40-
- [Transaction](14-transaction/index.md)
41-
- [Variable](15-variable/index.md)
42-
43-
## Function and External Integration
44-
45-
- [UDF (User Defined Function)](10-udf/index.md)
46-
- [External Function](11-external-function/index.md)
47-
- [Procedure](18-procedure/index.md)
48-
- [Notification](16-notification/index.md)
49-
50-
## Compute Resource Management
51-
52-
- [Warehouse](19-warehouse/index.md)
53-
- [Workload Group](20-workload-group/index.md)
7+
## Database & Table Management
8+
9+
| Component | Description |
10+
|-----------|-------------|
11+
| **[Database](00-database/index.md)** | Create, alter, and drop databases |
12+
| **[Table](01-table/index.md)** | Create, alter, and manage tables |
13+
| **[View](05-view/index.md)** | Create and manage virtual tables based on queries |
14+
| **[Dictionary](17-dictionary/index.md)** | Create key-value lookup tables for data enrichment |
15+
16+
## Performance & Indexing
17+
18+
| Component | Description |
19+
|-----------|-------------|
20+
| **[Cluster Key](06-clusterkey/index.md)** | Define data clustering for query optimization |
21+
| **[Aggregating Index](07-aggregating-index/index.md)** | Pre-compute aggregations for faster queries |
22+
| **[Inverted Index](07-inverted-index/index.md)** | Full-text search index for text columns |
23+
| **[Ngram Index](07-ngram-index/index.md)** | Substring search index for LIKE patterns |
24+
| **[Virtual Column](07-virtual-column/index.md)** | Extract and index JSON fields as virtual columns |
25+
26+
## Security & Access Control
27+
28+
| Component | Description |
29+
|-----------|-------------|
30+
| **[User](02-user/index.md)** | Create and manage database users |
31+
| **[Network Policy](12-network-policy/index.md)** | Control network access to databases |
32+
| **[Mask Policy](12-mask-policy/index.md)** | Apply data masking for sensitive information |
33+
| **[Password Policy](12-password-policy/index.md)** | Enforce password requirements and rotation |
34+
35+
## Data Integration & Processing
36+
37+
| Component | Description |
38+
|-----------|-------------|
39+
| **[Stage](03-stage/index.md)** | Define storage locations for data loading |
40+
| **[Stream](04-stream/index.md)** | Capture and process data changes |
41+
| **[Task](04-task/index.md)** | Schedule and automate SQL operations |
42+
| **[Sequence](04-sequence/index.md)** | Generate unique sequential numbers |
43+
| **[Connection](13-connection/index.md)** | Configure external data source connections |
44+
| **[File Format](13-file-format/index.md)** | Define formats for data import/export |
45+
46+
## Functions & Procedures
47+
48+
| Component | Description |
49+
|-----------|-------------|
50+
| **[UDF](10-udf/index.md)** | Create custom functions in Python or JavaScript |
51+
| **[External Function](11-external-function/index.md)** | Integrate external APIs as SQL functions |
52+
| **[Procedure](18-procedure/index.md)** | Create stored procedures for complex logic |
53+
| **[Notification](16-notification/index.md)** | Set up event notifications and webhooks |
54+
55+
## Resource Management
56+
57+
| Component | Description |
58+
|-----------|-------------|
59+
| **[Warehouse](19-warehouse/index.md)** | Manage compute resources for query execution |
60+
| **[Workload Group](20-workload-group/index.md)** | Control resource allocation and priorities |
61+
| **[Transaction](14-transaction/index.md)** | Manage database transactions |
62+
| **[Variable](15-variable/index.md)** | Set and use session/global variables |

‎docs/en/sql-reference/10-sql-commands/10-dml/index.md‎

Lines changed: 17 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,23 @@
11
---
22
title: DML (Data Manipulation Language) Commands
33
---
4-
import IndexOverviewList from '@site/src/components/IndexOverviewList';
54

65
This page provides reference information for the DML (Data Manipulation Language) commands in Databend.
76

8-
<IndexOverviewList />
7+
## Data Modification
8+
9+
| Command | Description |
10+
|---------|-------------|
11+
| **[INSERT](dml-insert)** | Add new rows to a table |
12+
| **[INSERT MULTI](dml-insert-multi)** | Insert data into multiple tables in one statement |
13+
| **[UPDATE](dml-update)** | Modify existing rows in a table |
14+
| **[DELETE](dml-delete-from)** | Remove rows from a table |
15+
| **[REPLACE](dml-replace)** | Insert new rows or update existing ones |
16+
| **[MERGE](dml-merge)** | Perform upsert operations based on conditions |
17+
18+
## Data Loading & Export
19+
20+
| Command | Description |
21+
|---------|-------------|
22+
| **[COPY INTO Table](dml-copy-into-table)** | Load data from files into tables |
23+
| **[COPY INTO Location](dml-copy-into-location)** | Export table data to files |

‎docs/en/sql-reference/10-sql-commands/20-query-syntax/index.md‎

Lines changed: 54 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,59 @@
11
---
22
title: Query Syntax
33
---
4-
import IndexOverviewList from '@site/src/components/IndexOverviewList';
54

6-
This page provides reference information for the query syntax in Databend.
5+
This page provides reference information for the query syntax in Databend. Each component can be used individually or combined to build powerful queries.
76

8-
<IndexOverviewList />
7+
## Core Query Components
8+
9+
| Component | Description |
10+
|-----------|-------------|
11+
| **[SELECT](query-select)** | Retrieve data from tables - the foundation of all queries |
12+
| **[FROM / JOIN](query-join)** | Specify data sources and combine multiple tables |
13+
| **[WHERE](query-select#where-clause)** | Filter rows based on conditions |
14+
| **[GROUP BY](query-group-by)** | Group rows and perform aggregations (SUM, COUNT, AVG, etc.) |
15+
| **[HAVING](query-group-by#having-clause)** | Filter grouped results |
16+
| **[ORDER BY](query-select#order-by-clause)** | Sort query results |
17+
| **[LIMIT / TOP](top)** | Restrict the number of rows returned |
18+
19+
## Advanced Features
20+
21+
| Component | Description |
22+
|-----------|-------------|
23+
| **[WITH (CTE)](with-clause)** | Define reusable query blocks for complex logic |
24+
| **[PIVOT](query-pivot)** | Convert rows to columns (wide format) |
25+
| **[UNPIVOT](query-unpivot)** | Convert columns to rows (long format) |
26+
| **[QUALIFY](qualify)** | Filter rows after window function calculations |
27+
| **[VALUES](values)** | Create inline temporary data sets |
28+
29+
## Time Travel & Streaming
30+
31+
| Component | Description |
32+
|-----------|-------------|
33+
| **[AT](query-at)** | Query data at a specific point in time |
34+
| **[CHANGES](changes)** | Track insertions, updates, and deletions |
35+
| **[WITH CONSUME](with-consume)** | Process streaming data with offset management |
36+
| **[WITH STREAM HINTS](with-stream-hints)** | Optimize stream processing behavior |
37+
38+
## Query Execution
39+
40+
| Component | Description |
41+
|-----------|-------------|
42+
| **[Settings](settings)** | Configure query optimization and execution parameters |
43+
44+
## Query Structure
45+
46+
A typical Databend query follows this structure:
47+
48+
```sql
49+
[WITH cte_expressions]
50+
SELECT [TOP n] columns
51+
FROM table
52+
[JOIN other_tables]
53+
[WHERE conditions]
54+
[GROUP BY columns]
55+
[HAVING group_conditions]
56+
[QUALIFY window_conditions]
57+
[ORDER BY columns]
58+
[LIMIT n]
59+
```

‎docs/en/sql-reference/10-sql-commands/20-query-syntax/with-clause.md‎

Lines changed: 100 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,103 @@
22
title: WITH Clause
33
---
44

5-
Databend uses the WITH clause for common table expressions (CTEs).
5+
The WITH clause is an optional clause that precedes the body of the SELECT statement, and defines one or more CTEs (common table expressions) that can be referenced later in the statement.
6+
7+
8+
## Syntax
9+
10+
### Basic CTE
11+
12+
```sql
13+
[ WITH
14+
cte_name1 [ ( cte_column_list ) ] AS ( SELECT ... )
15+
[ , cte_name2 [ ( cte_column_list ) ] AS ( SELECT ... ) ]
16+
[ , cte_nameN [ ( cte_column_list ) ] AS ( SELECT ... ) ]
17+
]
18+
SELECT ...
19+
```
20+
21+
### Recursive CTE
22+
23+
```sql
24+
[ WITH [ RECURSIVE ]
25+
cte_name1 ( cte_column_list ) AS ( anchorClause UNION ALL recursiveClause )
26+
[ , cte_name2 ( cte_column_list ) AS ( anchorClause UNION ALL recursiveClause ) ]
27+
[ , cte_nameN ( cte_column_list ) AS ( anchorClause UNION ALL recursiveClause ) ]
28+
]
29+
SELECT ...
30+
```
31+
32+
Where:
33+
- `anchorClause`: `SELECT anchor_column_list FROM ...`
34+
- `recursiveClause`: `SELECT recursive_column_list FROM ... [ JOIN ... ]`
35+
36+
## Parameters
37+
38+
| Parameter | Description |
39+
|-----------|-------------|
40+
| `cte_name` | The CTE name must follow standard identifier rules |
41+
| `cte_column_list` | The names of the columns in the CTE |
42+
| `anchor_column_list` | The columns used in the anchor clause for the recursive CTE |
43+
| `recursive_column_list` | The columns used in the recursive clause for the recursive CTE |
44+
45+
## Examples
46+
47+
### Basic CTE
48+
49+
```sql
50+
WITH high_value_customers AS (
51+
SELECT customer_id, customer_name, total_spent
52+
FROM customers
53+
WHERE total_spent > 10000
54+
)
55+
SELECT c.customer_name, o.order_date, o.order_amount
56+
FROM high_value_customers c
57+
JOIN orders o ON c.customer_id = o.customer_id
58+
ORDER BY o.order_date DESC;
59+
```
60+
61+
### Multiple CTEs
62+
63+
```sql
64+
WITH
65+
regional_sales AS (
66+
SELECT region, SUM(sales_amount) as total_sales
67+
FROM sales_data
68+
GROUP BY region
69+
),
70+
top_regions AS (
71+
SELECT region, total_sales
72+
FROM regional_sales
73+
WHERE total_sales > 1000000
74+
)
75+
SELECT r.region, r.total_sales
76+
FROM top_regions r
77+
ORDER BY r.total_sales DESC;
78+
```
79+
80+
### Recursive CTE
81+
82+
```sql
83+
WITH RECURSIVE countdown AS (
84+
-- Anchor clause: starting point
85+
SELECT 10 as num
86+
87+
UNION ALL
88+
89+
-- Recursive clause: repeat until condition
90+
SELECT num - 1
91+
FROM countdown
92+
WHERE num > 1 -- Stop condition
93+
)
94+
SELECT num FROM countdown
95+
ORDER BY num DESC;
96+
```
97+
98+
## Usage Notes
99+
100+
- CTEs are temporary named result sets that exist only for the duration of the query
101+
- CTE names must be unique within the same WITH clause
102+
- A CTE can reference previously defined CTEs in the same WITH clause
103+
- Recursive CTEs require both an anchor clause and a recursive clause connected by UNION ALL
104+
- The RECURSIVE keyword is required when using recursive CTEs

‎docs/en/sql-reference/10-sql-commands/30-query-operators/index.md‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,16 @@
11
---
22
title: Query Operators
33
---
4-
import IndexOverviewList from '@site/src/components/IndexOverviewList';
54

65
This page provides reference information for the query operators in Databend.
76

8-
<IndexOverviewList />
7+
## Operator Types
8+
9+
| Operator Type | Description |
10+
|--------------|-------------|
11+
| **[Arithmetic](arithmetic)** | Mathematical operations (+, -, *, /, %, DIV) |
12+
| **[Comparison](comparison)** | Value comparisons (=, !=, &lt;, &gt;, &lt;=, &gt;=, BETWEEN, IN) |
13+
| **[Logical](logical)** | Boolean logic (AND, OR, NOT, XOR) |
14+
| **[JSON](json)** | JSON data operations (::, -&gt;, -&gt;&gt;, @&gt;, &lt;@) |
15+
| **[Set](set)** | Combine query results (UNION, INTERSECT, EXCEPT) |
16+
| **[Subquery](subquery)** | Nested queries (EXISTS, IN, ANY, ALL, SOME) |

‎docs/en/sql-reference/10-sql-commands/50-administration-cmds/index.md‎

Lines changed: 40 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,46 @@
11
---
22
title: Administration Commands
33
---
4-
import IndexOverviewList from '@site/src/components/IndexOverviewList';
54

65
This page provides reference information for the system administration commands in Databend.
76

8-
<IndexOverviewList />
7+
## System Monitoring
8+
9+
| Command | Description |
10+
|---------|-------------|
11+
| **[SHOW PROCESSLIST](07-show-processlist.md)** | Display active queries and connections |
12+
| **[SHOW METRICS](08-show-metrics.md)** | View system performance metrics |
13+
| **[KILL](01-kill.md)** | Terminate running queries or connections |
14+
| **[RUST BACKTRACE](rust-backtrace.md)** | Debug Rust stack traces |
15+
16+
## Configuration Management
17+
18+
| Command | Description |
19+
|---------|-------------|
20+
| **[SET](02-set-global.md)** | Set global configuration parameters |
21+
| **[UNSET](02-unset.md)** | Remove configuration settings |
22+
| **[SET VARIABLE](03-set-var.md)** | Manage user-defined variables |
23+
| **[SHOW SETTINGS](03-show-settings.md)** | Display current system settings |
24+
25+
## Function Management
26+
27+
| Command | Description |
28+
|---------|-------------|
29+
| **[SHOW FUNCTIONS](04-show-functions.md)** | List built-in functions |
30+
| **[SHOW USER FUNCTIONS](05-show-user-functions.md)** | List user-defined functions |
31+
| **[SHOW TABLE FUNCTIONS](06-show-table-functions.md)** | List table-valued functions |
32+
33+
## Storage Maintenance
34+
35+
| Command | Description |
36+
|---------|-------------|
37+
| **[VACUUM TABLE](09-vacuum-table.md)** | Reclaim storage space from tables |
38+
| **[VACUUM DROP TABLE](09-vacuum-drop-table.md)** | Clean up dropped table data |
39+
| **[VACUUM TEMP FILES](09-vacuum-temp-files.md)** | Remove temporary files |
40+
| **[SHOW INDEXES](show-indexes.md)** | Display table indexes |
41+
42+
## Dynamic Execution
43+
44+
| Command | Description |
45+
|---------|-------------|
46+
| **[EXECUTE IMMEDIATE](execute-immediate.md)** | Execute dynamically constructed SQL statements |

0 commit comments

Comments
 (0)