Skip to content

Commit e8d2ffc

Browse files
authored
Update values.md: more clear
1 parent 83c43ae commit e8d2ffc

File tree

1 file changed

+25
-41
lines changed
  • docs/en/sql-reference/10-sql-commands/20-query-syntax

1 file changed

+25
-41
lines changed

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

Lines changed: 25 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -5,24 +5,28 @@ import FunctionDescription from '@site/src/components/FunctionDescription';
55

66
<FunctionDescription description="Introduced or updated: v1.2.65"/>
77

8-
The VALUES clause is used to define a set of rows explicitly for use in queries. It allows you to provide a list of values that can be used as a temporary table in your SQL statements.
8+
The VALUES clause creates an inline table by explicitly defining rows of data. This temporary table can be used directly or within other SQL statements.
99

1010
## Syntax
1111

1212
```sql
13-
VALUES (value_1_1, value_1_2, ...), (value_2_1, value_2_2, ...), ...
13+
SELECT ...
14+
FROM ( VALUES ( <expr> [ , <expr> [ , ... ] ] ) [ , ( ... ) ] ) [ [ AS ] <table_alias> [ ( <column_alias> [, ... ] ) ] ]
15+
[ ... ]
1416
```
15-
- The VALUES clause is followed by sets of values enclosed in parentheses.
16-
- Each set of values represents a row to be inserted into the temporary table.
17-
- Within each set of values, the individual values are comma-separated and correspond to the columns of the temporary table.
18-
- Databend automatically assigns default column names like *col0*, *col1*, *col2*, and so on when you insert multiple rows without specifying column names.
17+
18+
**Key Points:**
19+
- The VALUES clause must be enclosed in parentheses when used in a FROM clause: `FROM (VALUES ...)`
20+
- Each parenthesized group of expressions represents one row
21+
- Column names are automatically assigned as **col0**, **col1**, etc. (zero-based indexing)
22+
- You can provide custom column names using table aliases
1923

2024
## Examples
2125

22-
These examples demonstrate using the VALUES clause to show city data in various formats: directly, or ordered by population:
26+
### Basic Usage
2327

2428
```sql
25-
-- Directly return data
29+
-- Direct usage with automatic column names (col0, col1)
2630
VALUES ('Toronto', 2731571), ('Vancouver', 631486), ('Montreal', 1704694);
2731

2832
col0 |col1 |
@@ -31,7 +35,7 @@ Toronto |2731571|
3135
Vancouver| 631486|
3236
Montreal |1704694|
3337

34-
-- Order data
38+
-- With ORDER BY
3539
VALUES ('Toronto', 2731571), ('Vancouver', 631486), ('Montreal', 1704694) ORDER BY col1;
3640

3741
col0 |col1 |
@@ -41,56 +45,36 @@ Montreal |1704694|
4145
Toronto |2731571|
4246
```
4347

44-
These examples demonstrate how the VALUES clause can be used in a SELECT statement:
48+
### In SELECT Statements
4549

4650
```sql
47-
-- Select a single column
48-
SELECT col1
51+
-- Select specific column - note the parentheses around VALUES
52+
SELECT col1
4953
FROM (VALUES ('Toronto', 2731571), ('Vancouver', 631486), ('Montreal', 1704694));
5054

51-
col1 |
52-
-------+
53-
2731571|
54-
631486|
55-
1704694|
56-
57-
-- Select columns with aliases
55+
-- Custom column names - VALUES must be enclosed in parentheses
5856
SELECT * FROM (
59-
VALUES ('Toronto', 2731571),
60-
('Vancouver', 631486),
57+
VALUES ('Toronto', 2731571),
58+
('Vancouver', 631486),
6159
('Montreal', 1704694)
6260
) AS CityPopulation(City, Population);
6361

64-
city |population|
65-
---------+----------+
66-
Toronto | 2731571|
67-
Vancouver| 631486|
68-
Montreal | 1704694|
69-
70-
-- Select columns with aliases and sorting
62+
-- With column aliases and sorting
7163
SELECT col0 AS City, col1 AS Population
7264
FROM (VALUES ('Toronto', 2731571), ('Vancouver', 631486), ('Montreal', 1704694))
7365
ORDER BY col1 DESC
7466
LIMIT 1;
75-
76-
city |population|
77-
-------+----------+
78-
Toronto| 2731571|
7967
```
8068

81-
This example demonstrates how to use the VALUES clause to create a temporary table within a Common Table Expression (CTE):
69+
### With Common Table Expressions (CTE)
8270

8371
```sql
8472
WITH citypopulation(city, population) AS (
8573
VALUES ('Toronto', 2731571),
8674
('Vancouver', 631486),
8775
('Montreal', 1704694)
8876
)
89-
SELECT citypopulation.city, citypopulation.population FROM citypopulation;
90-
91-
city |population|
92-
---------+----------+
93-
Toronto | 2731571|
94-
Vancouver| 631486|
95-
Montreal | 1704694|
96-
```
77+
SELECT city, population FROM citypopulation;
78+
```
79+
80+
> **Important**: When using VALUES in a FROM clause or CTE, it must be enclosed in parentheses: `FROM (VALUES ...)` or `AS (VALUES ...)`. This is required syntax.

0 commit comments

Comments
 (0)